diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 6f96ec33d..f2743b3d8 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
-    "version": "0.34.0"
+    "version": "0.35.0"
   },
   "plugins": [
     {
       "name": "headroom",
       "source": "./plugins/headroom-agent-hooks",
       "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
-      "version": "0.34.0",
+      "version": "0.35.0",
       "author": {
         "name": "Headroom Contributors",
         "url": "https://github.com/chopratejas/headroom"
diff --git a/.commitlintrc.json b/.commitlintrc.json
index d42e91489..4bc3e4519 100644
--- a/.commitlintrc.json
+++ b/.commitlintrc.json
@@ -1,7 +1,7 @@
 {
   "extends": ["@commitlint/config-conventional"],
   "rules": {
-    "body-max-line-length": [2, "always", 200],
+    "body-max-line-length": [0],
     "footer-leading-blank": [0],
     "subject-case": [0],
     "type-enum": [
@@ -12,6 +12,7 @@
         "chore",
         "ci",
         "docs",
+        "deps",
         "feat",
         "fix",
         "parity",
@@ -23,4 +24,4 @@
       ]
     ]
   }
-}
\ No newline at end of file
+}
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 2014d8dc8..3dd7ca601 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -40,6 +40,16 @@ Closes #
 - Observed result:
 - Not tested:
 
+## Runtime Rollout Safety
+
+- Rollout-managed feature(s):
+- Minimum rollout channel:
+- Stable/default behavior changed:
+- Kill switch / disable path:
+- Unsafe override required:
+- Qualification impact:
+- Rollback path:
+
 ## Review Readiness
 
 - [ ] I have performed a self-review
diff --git a/.github/act/pr-governance-valid.json b/.github/act/pr-governance-valid.json
index 8d1b07d16..a38b4b005 100644
--- a/.github/act/pr-governance-valid.json
+++ b/.github/act/pr-governance-valid.json
@@ -1,19 +1,13 @@
-{
-  "action": "ready_for_review",
-  "number": 42,
-  "pull_request": {
-    "number": 42,
-    "draft": false,
-    "title": "feat: add PR governance",
-    "body": "## Description\n\nAdd a required PR governance check and commit-msg enforcement.\n\nCloses #123\n\n## Type of Change\n\n- [x] New feature (non-breaking change that adds functionality)\n\n## Changes Made\n\n- Added workflow validation for PR template completeness.\n- Added a commit-msg hook that runs commitlint locally.\n\n## Testing\n\n- [x] Unit tests pass (`pytest`)\n- [x] Manual testing performed\n\n### Test Output\n\n```text\npytest scripts/tests/test_pr_governance.py -q\n```\n\n## Real Behavior Proof\n\n- Environment: Ubuntu runner, Python 3.12\n- Exact command / steps: Opened a PR with an incomplete template, then fixed the body.\n- Observed result: The governance check failed until the template and readiness boxes were complete.\n- Not tested: Repository-level automatic Copilot rulesets.\n\n## Review Readiness\n\n- [x] I have performed a self-review\n- [x] This PR is ready for human review\n",
-    "user": {
-      "login": "octocat"
-    },
-    "base": {
-      "sha": "dff6a199"
-    }
-  },
-  "repository": {
-    "full_name": "JerrettDavis/headroom"
-  }
-}
+{
+  "action": "ready_for_review",
+  "number": 42,
+  "pull_request": {
+    "number": 42,
+    "draft": false,
+    "title": "feat: add PR governance",
+    "body": "## Description\n\nAdd a required PR governance check and commit-msg enforcement.\n\n## Type of Change\n\n- [x] New feature (non-breaking change that adds functionality)\n\n## Changes Made\n\n- Added workflow validation for PR template completeness.\n\n## Testing\n\n- [x] Unit tests pass (`pytest`)\n\n### Test Output\n\n```text\npytest scripts/tests/test_pr_governance.py -q\n```\n\n## Real Behavior Proof\n\n- Environment: Ubuntu runner, Python 3.12\n- Exact command / steps: Opened a PR and ran governance.\n- Observed result: The check passed with complete facts.\n- Not tested: Repository settings.\n\n## Runtime Rollout Safety\n\n- Rollout-managed feature(s): None.\n- Minimum rollout channel: Stable.\n- Stable/default behavior changed: No.\n- Kill switch / disable path: Not applicable.\n- Unsafe override required: No.\n- Qualification impact: None.\n- Rollback path: Revert the workflow and script changes.\n\n## Review Readiness\n\n- [x] I have performed a self-review\n- [x] This PR is ready for human review\n",
+    "user": {"login": "octocat"},
+    "base": {"sha": "dff6a199"}
+  },
+  "repository": {"full_name": "JerrettDavis/headroom"}
+}
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index 6f96ec33d..f2743b3d8 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
-    "version": "0.34.0"
+    "version": "0.35.0"
   },
   "plugins": [
     {
       "name": "headroom",
       "source": "./plugins/headroom-agent-hooks",
       "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
-      "version": "0.34.0",
+      "version": "0.35.0",
       "author": {
         "name": "Headroom Contributors",
         "url": "https://github.com/chopratejas/headroom"
diff --git a/.github/pr-images/issue-2552-windows-fallback-verification.png b/.github/pr-images/issue-2552-windows-fallback-verification.png
new file mode 100644
index 000000000..91a1dc27e
Binary files /dev/null and b/.github/pr-images/issue-2552-windows-fallback-verification.png differ
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 49acfaf42..431860278 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -561,7 +561,7 @@ jobs:
       - name: Install test dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pytest
+          pip install pytest 'opentelemetry-api>=1.24.0'
       - name: Run native installer wrapper tests
         run: pytest tests/test_install/test_native_installers.py -q
 
@@ -579,7 +579,7 @@ jobs:
         run: |
           brew install bash
           python -m pip install --upgrade pip
-          python -m pip install --retries 10 --timeout 60 pytest
+          python -m pip install --retries 10 --timeout 60 pytest 'opentelemetry-api>=1.24.0'
       - name: Run native installer wrapper tests
         run: |
           BASH_PREFIX="$(brew --prefix bash)"
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index accab994a..a3d06f76c 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -204,10 +204,10 @@ jobs:
       - name: Upload digest marker
         uses: actions/upload-artifact@v7
         with:
-          # Variant + arch in the artifact name so the manifest job can
-          # download with `pattern: digests-<variant>-*` to gather all
-          # arches for one variant. `root` substitutes the empty-string
-          # variant since GHA artifact names can't end in a hyphen.
+          # Variant + arch uniquely identify the marker. The manifest job
+          # downloads both architecture artifacts by exact name; a glob such
+          # as `digests-code-*` would also match code-nonroot/code-slim.
+          # `root` substitutes the empty-string variant.
           name: digests-${{ matrix.variant.name || 'root' }}-${{ matrix.arch.name }}
           path: ${{ runner.temp }}/digests/*
           if-no-files-found: error
@@ -220,6 +220,7 @@ jobs:
   # tags, and that manifest is what users pull by `:tag`.
   docker-manifest:
     needs: docker-build
+    if: ${{ always() }}
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     strategy:
@@ -272,12 +273,17 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Download per-arch digests for this variant
+      - name: Download amd64 digest for this variant
         uses: actions/download-artifact@v8
         with:
-          pattern: digests-${{ matrix.variant.name || 'root' }}-*
+          name: digests-${{ matrix.variant.name || 'root' }}-amd64
+          path: ${{ runner.temp }}/digests
+
+      - name: Download arm64 digest for this variant
+        uses: actions/download-artifact@v8
+        with:
+          name: digests-${{ matrix.variant.name || 'root' }}-arm64
           path: ${{ runner.temp }}/digests
-          merge-multiple: true
 
       # Same tag rules as the pre-fan-out workflow — preserve every
       # tag flavor (semver, ref, sha-prefixed, version-suffixed,
@@ -313,6 +319,11 @@ jobs:
             echo "ERROR: no digests downloaded for variant '${{ matrix.variant.name || 'root' }}'" >&2
             exit 1
           fi
+          digest_count="$(find "${DIGEST_DIR}" -maxdepth 1 -type f | wc -l)"
+          if [ "${digest_count}" -ne 2 ]; then
+            echo "ERROR: expected both architecture digests for variant '${{ matrix.variant.name || 'root' }}', found ${digest_count}" >&2
+            exit 1
+          fi
           digest_refs=()
           for f in "${DIGEST_DIR}"/*; do
             digest="$(basename "$f")"
@@ -382,53 +393,13 @@ jobs:
             sleep "$sleep_for"
           done
 
-  promote-latest:
-    # Re-push the :latest tag pointing at the root variant *after* every
-    # variant manifest job has finished, so GHCR's package version
-    # listing (sorted by created_at) shows the root image with :latest
-    # at the top instead of whichever variant happened to finish last.
-    needs: docker-manifest
-    runs-on: ubuntu-24.04
-    timeout-minutes: 10
-    steps:
-      - name: Normalize image name
-        id: image-name
-        run: |
-          image_name="$(printf '%s' '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')"
-          printf 'image_name=%s\n' "$image_name" >> "$GITHUB_OUTPUT"
-
-      - name: Determine image version
-        id: version
-        env:
-          MANUAL_VERSION: ${{ inputs.version || github.event.inputs.version }}
-          RELEASE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          version="${MANUAL_VERSION#v}"
-          if [ -z "$version" ] && [ -n "$RELEASE_TAG" ]; then
-            version="${RELEASE_TAG#v}"
-          fi
-          printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v4
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Re-tag root image as :latest
-        if: steps.version.outputs.version != ''
+        if: steps.manifest.outputs.index_digest != '' && matrix.variant.name == '' && steps.version.outputs.version != ''
         env:
           IMAGE: ${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}
           VERSION: ${{ steps.version.outputs.version }}
         run: |
-          # Add a unique annotation so the resulting image index manifest gets
-          # a new digest, which makes GHCR record a fresh package version with
-          # current timestamp (otherwise the existing root manifest is reused
-          # and stays where it was in the version listing).
+          # Add a unique annotation so GHCR records a fresh root package version.
           promoted_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
           docker buildx imagetools create \
             --annotation "index:io.headroom.promoted-at=${promoted_at}" \
diff --git a/.github/workflows/opencode-plugin.yml b/.github/workflows/opencode-plugin.yml
index 4fd8103ab..4e81e6597 100644
--- a/.github/workflows/opencode-plugin.yml
+++ b/.github/workflows/opencode-plugin.yml
@@ -11,12 +11,14 @@ on:
     paths:
       - "plugins/opencode/**"
       - "headroom/providers/opencode/_dist/**"
+      - "headroom/providers/opencode/hook-shim/**"
       - ".github/workflows/opencode-plugin.yml"
   push:
     branches: [main]
     paths:
       - "plugins/opencode/**"
       - "headroom/providers/opencode/_dist/**"
+      - "headroom/providers/opencode/hook-shim/**"
       - ".github/workflows/opencode-plugin.yml"
 
 permissions:
@@ -51,3 +53,6 @@ jobs:
           cmp dist-standalone/entry.opencode.js \
             ../../headroom/providers/opencode/_dist/entry.opencode.js \
             || { echo "::error::headroom/providers/opencode/_dist/entry.opencode.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; }
+          cmp dist-standalone/hook-shim/handler.js \
+            ../../headroom/providers/opencode/hook-shim/handler.js \
+            || { echo "::error::headroom/providers/opencode/hook-shim/handler.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; }
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 81b90ebbc..1e3f19bf6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -12,6 +12,7 @@ env:
   NPM_REGISTRY_URL: https://registry.npmjs.org
   NPM_SDK_PACKAGE: headroom-ai
   NPM_OPENCLAW_PACKAGE: headroom-openclaw
+  NPM_OPENCODE_PACKAGE: headroom-opencode
 
   # GitHub Package Registry
   GITHUB_PACKAGES_REGISTRY_URL: https://npm.pkg.github.com
@@ -852,10 +853,30 @@ jobs:
           npm publish --access public
         continue-on-error: true
 
-      - name: npm publish notice
-        if: steps.npm-sdk-publish.outcome == 'failure' || steps.npm-openclaw-publish.outcome == 'failure'
+      - name: Publish ${{ env.NPM_OPENCODE_PACKAGE }} to npmjs.org
+        id: npm-opencode-publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          echo "::notice::One or more npm publishes failed. Set NPM_SKIP=true in repo Variables to skip both npm publishes if tokens are not configured."
+          version="${{ needs.detect-version.outputs.npm_version }}"
+          cd plugins/opencode
+          npm ci
+          npm run build
+          npm version "$version" --no-git-tag-version --allow-same-version
+          HEADROOM_NPM_VERSION="$version" node <<'EOF'
+          const fs = require("fs");
+          const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+          pkg.dependencies = pkg.dependencies || {};
+          pkg.dependencies["headroom-ai"] = `^${process.env.HEADROOM_NPM_VERSION}`;
+          fs.writeFileSync("package.json", `${JSON.stringify(pkg, null, 2)}\n`);
+          EOF
+          npm publish --access public
+        continue-on-error: true
+
+      - name: npm publish notice
+        if: steps.npm-sdk-publish.outcome == 'failure' || steps.npm-openclaw-publish.outcome == 'failure' || steps.npm-opencode-publish.outcome == 'failure'
+        run: |
+          echo "::notice::One or more npm publishes failed. Set NPM_SKIP=true in repo Variables to skip npm publishes if tokens are not configured."
 
   publish-github-packages:
     needs: [detect-version, build]
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 402975fd6..08ee4e215 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -27,7 +27,7 @@ repos:
         # unconditionally, so installing hooks is not required for enforcement.
         args: [--assume-in-merge]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.17
+    rev: v0.15.22
     hooks:
       - id: ruff
         args: [--fix]
diff --git a/.release-please-config.json b/.release-please-config.json
index dadabab91..3da8e177d 100644
--- a/.release-please-config.json
+++ b/.release-please-config.json
@@ -7,8 +7,8 @@
   "bump-patch-for-minor-pre-major": false,
   "draft": false,
   "prerelease": false,
-  "separate-pull-requests": false,
-  "pull-request-title-pattern": "chore: release ${version}",
+  "separate-pull-requests": true,
+  "pull-request-title-pattern": "chore: release${component} ${version}",
   "packages": {
     ".": {
       "package-name": "headroom-ai",
@@ -23,6 +23,11 @@
           "type": "json",
           "path": "plugins/openclaw/package.json",
           "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": "plugins/opencode/package.json",
+          "jsonpath": "$.version"
         }
       ]
     }
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 8878352c7..3a39fd8cf 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.34.0"
+  ".": "0.35.0"
 }
diff --git a/.releasemetadata b/.releasemetadata
index 25ef9aea4..017607cea 100644
--- a/.releasemetadata
+++ b/.releasemetadata
@@ -1,9 +1,10 @@
 {
-  "version": "0.34.0",
+  "version": "0.35.0",
   "packages": {
-    "pypi": "0.34.0",
-    "npm-sdk": "0.34.0",
-    "npm-openclaw": "0.34.0",
-    "agent-hooks-plugin": "0.34.0"
+    "pypi": "0.35.0",
+    "npm-sdk": "0.35.0",
+    "npm-openclaw": "0.35.0",
+    "npm-opencode": "0.35.0",
+    "agent-hooks-plugin": "0.35.0"
   }
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 807f16593..89fc5d9d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -284,6 +284,137 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **code:** fix two `CodeAwareCompressor` AST-reassembly bugs: an exported JS/TS function or class (`export function foo() {`) produced a duplicated `export export` keyword and invalid syntax, because line-based node slicing (used to preserve indentation) pulled in the preceding `export` sibling's text on top of the `export_statement` handler's own prefix reconstruction. Separately, in every supported language, a doc comment immediately above a top-level function, class, or type was detached from its declaration during extraction and re-emitted in a cluster at the end of the compressed output instead of staying attached to what it documents.
 - * **proxy:** Buffered upstream responses containing a `server_tool_use` (or any other unrecognized Anthropic content block) no longer turn a fully-generated response into an HTTP 502. `StreamingMixin._response_to_sse` raised `ValueError` on unknown block types after the entire upstream generation had already been buffered, so a slow-but-successful response failed and the client retried the whole multi-minute request. Unknown blocks are now emitted verbatim in `content_block_start` (following the existing redacted_thinking` pattern), so `server_tool_use`, `server_tool_result`, `mcp_tool_use`, and future block types round-trip ([#1806](https://github.com/headroomlabs-ai/headroom/issues/1806)).
 
+## [0.35.0](https://github.com/headroomlabs-ai/headroom/compare/v0.34.0...v0.35.0) (2026-08-12)
+
+
+### Features
+
+* **beacon:** allowlist the routing summary key ([#2818](https://github.com/headroomlabs-ai/headroom/issues/2818)) ([7940c05](https://github.com/headroomlabs-ai/headroom/commit/7940c05ebf4486c6b9d00984067ae33cedf4dddb))
+* **beacon:** hourly R2 compaction, per-strategy savings, and a stack that reports ([#2853](https://github.com/headroomlabs-ai/headroom/issues/2853)) ([e0870ef](https://github.com/headroomlabs-ai/headroom/commit/e0870ef931e5ea6cc6cb52551f5d80cd9e3dc715))
+* **cli,pricing:** add CLI extension seam and prompt-cache TTL pricing ([#2802](https://github.com/headroomlabs-ai/headroom/issues/2802)) ([6ec3e34](https://github.com/headroomlabs-ai/headroom/commit/6ec3e3478abf058fe1460f91342bcdadf54a1ba8))
+
+
+### Bug Fixes
+
+* **anthropic:** strip first-party tool search on custom upstreams ([#2539](https://github.com/headroomlabs-ai/headroom/issues/2539)) ([7f6950b](https://github.com/headroomlabs-ai/headroom/commit/7f6950be34e29304deae0fa5138b852491b092fe))
+* **backends/anyllm:** convert Anthropic tools and tool_choice to OpenAI shape ([0d6866b](https://github.com/headroomlabs-ai/headroom/commit/0d6866b91a3777475abd58cd8b63a10cd0621e7f))
+* **backends/anyllm:** stream tool_use blocks and map finish_reason on the streaming path ([e4904e2](https://github.com/headroomlabs-ai/headroom/commit/e4904e23a6ba6f5cff2488332946481172446922))
+* **backends/litellm:** None-guard core token counts in OpenAI usage block ([#2324](https://github.com/headroomlabs-ai/headroom/issues/2324)) ([12f9f58](https://github.com/headroomlabs-ai/headroom/commit/12f9f58cb3dcfc67af1238424d404d8dd9bad1dd))
+* **beacon:** report all-layers savings, not context-compression only ([#2796](https://github.com/headroomlabs-ai/headroom/issues/2796)) ([e9a24f3](https://github.com/headroomlabs-ai/headroom/commit/e9a24f3ec1ffd278b0b3ca547a90942c40c99ec8))
+* **beacon:** split session failures by status code ([#2815](https://github.com/headroomlabs-ai/headroom/issues/2815)) ([2954e37](https://github.com/headroomlabs-ai/headroom/commit/2954e37048f8dcffe16e1c37b8f71afb0094a0a2))
+* **cache:** bound compression cache bookkeeping ([0ae948c](https://github.com/headroomlabs-ai/headroom/commit/0ae948c1510735df39317bf0861f8a8750cdbf9d))
+* **cache:** enforce Anthropic's 1h-before-5m cache_control ordering before forwarding ([#2941](https://github.com/headroomlabs-ai/headroom/issues/2941)) ([3752458](https://github.com/headroomlabs-ai/headroom/commit/3752458022f736c779f7b5a6c2d6d2ef0bc89f72))
+* **cache:** mirror client cache_control positions instead of single-marker consolidation ([def3d76](https://github.com/headroomlabs-ai/headroom/commit/def3d76e5ab4665e609b51bfba54dd6d25116925))
+* **cache:** stabilize Anthropic block-growing lineages ([#2917](https://github.com/headroomlabs-ai/headroom/issues/2917)) ([1a04c95](https://github.com/headroomlabs-ai/headroom/commit/1a04c957f53ef25ab1209166f425a7876913c4d3))
+* **ccr:** avoid injecting tool on chat streaming ([d0c1f5b](https://github.com/headroomlabs-ai/headroom/commit/d0c1f5b8ad68c7a44ed3aaa0fe40e3a656950123))
+* **ccr:** preserve exact SQLite TTL boundary ([#2669](https://github.com/headroomlabs-ai/headroom/issues/2669)) ([d0a86d4](https://github.com/headroomlabs-ai/headroom/commit/d0a86d409fab377f9c642d1f3680b6ece7f97b8a))
+* **ccr:** report embedded hashes from compress endpoint ([#717](https://github.com/headroomlabs-ai/headroom/issues/717)) ([685ebe4](https://github.com/headroomlabs-ai/headroom/commit/685ebe457d727922ba4057515556a2d2aac0f616))
+* **ccr:** resolve &lt;&lt;ccr:...&gt;&gt; markers inline when no retrieve-tool path exists ([#2512](https://github.com/headroomlabs-ai/headroom/issues/2512)) ([ce8ce83](https://github.com/headroomlabs-ai/headroom/commit/ce8ce8313f8cebf060392a62f9adaab18c0df386))
+* **ccr:** tolerate null/malformed OpenAI data in response handling ([#2467](https://github.com/headroomlabs-ai/headroom/issues/2467)) ([e583e08](https://github.com/headroomlabs-ai/headroom/commit/e583e082d8dee942229ac6211c742f9c9448a905))
+* **ci:** publish latest from the root Docker manifest ([#2252](https://github.com/headroomlabs-ai/headroom/issues/2252)) ([5568d73](https://github.com/headroomlabs-ai/headroom/commit/5568d738afb5e080d8df56e64500026996cbf025))
+* **claude:** stop forcing tool search on Foundry ([#2477](https://github.com/headroomlabs-ai/headroom/issues/2477)) ([7981396](https://github.com/headroomlabs-ai/headroom/commit/798139608c0fb5118eb3a7a183b8b2abe92341f1))
+* **cli/update:** let install ownership win over bare /.dockerenv so venv installs self-update ([#2830](https://github.com/headroomlabs-ai/headroom/issues/2830)) ([7092b53](https://github.com/headroomlabs-ai/headroom/commit/7092b53c466bf5dbda8a1cda88403d1a4b16deb1))
+* **codex:** route alpha search through the Codex backend ([#2538](https://github.com/headroomlabs-ai/headroom/issues/2538)) ([a540eb2](https://github.com/headroomlabs-ai/headroom/commit/a540eb2c61b1a47e5ab8b07ea4a80fee780b6514))
+* **content-router:** protect custom-tag blocks before mixed-content section split ([d7bc1e2](https://github.com/headroomlabs-ai/headroom/commit/d7bc1e275f411788abffa2d007db14aa17fd31c5))
+* **deps:** bump h2 to 4.4.1 for CVE-2026-71554 ([#2839](https://github.com/headroomlabs-ai/headroom/issues/2839)) ([564e0a8](https://github.com/headroomlabs-ai/headroom/commit/564e0a8d0fe440dff21a6c405c88e05698b3059f))
+* **deps:** enforce audited transitive dependency floors ([#2791](https://github.com/headroomlabs-ai/headroom/issues/2791)) ([64e2039](https://github.com/headroomlabs-ai/headroom/commit/64e203931b9810e5a010f063d26d154419016f86))
+* **doctor:** flag `ollama launch claude` proxy bypass instead of misdirecting ([#2566](https://github.com/headroomlabs-ai/headroom/issues/2566)) ([7f24d69](https://github.com/headroomlabs-ai/headroom/commit/7f24d695eea00b9bb3265fbaa6629acf0c2ff181))
+* emit SSE ping before message_start on Bedrock streaming path (issue [#902](https://github.com/headroomlabs-ai/headroom/issues/902)) ([#1080](https://github.com/headroomlabs-ai/headroom/issues/1080)) ([4dab254](https://github.com/headroomlabs-ai/headroom/commit/4dab254d52914c39ffe13071848604e1771b1bd1))
+* **gemini:** resolve native CCR retrieval calls ([#2253](https://github.com/headroomlabs-ai/headroom/issues/2253)) ([2483f57](https://github.com/headroomlabs-ai/headroom/commit/2483f570025763cd9183a93749ea8cf38f1aeb85))
+* **health:** label kompress as degraded/optional when not yet loaded ([#2865](https://github.com/headroomlabs-ai/headroom/issues/2865)) ([8949371](https://github.com/headroomlabs-ai/headroom/commit/89493714d2cffdc1f81a8f417ea09891453d7009))
+* **image:** decouple routing types from trained_router so importing the compressor doesn't import torch ([#2513](https://github.com/headroomlabs-ai/headroom/issues/2513)) ([#2537](https://github.com/headroomlabs-ai/headroom/issues/2537)) ([d7cf981](https://github.com/headroomlabs-ai/headroom/commit/d7cf981093cf505192a3736dadd0254a120830a1))
+* **install/windows:** register persistent-task from S4U hidden XML ([#2453](https://github.com/headroomlabs-ai/headroom/issues/2453)) ([#2459](https://github.com/headroomlabs-ai/headroom/issues/2459)) ([1edaeb8](https://github.com/headroomlabs-ai/headroom/commit/1edaeb8b76f6b872a6c810d404c944caf1a594b2))
+* **install:** don't crash the PowerShell installer when $PROFILE is unset ([#2469](https://github.com/headroomlabs-ai/headroom/issues/2469)) ([fc5c4e2](https://github.com/headroomlabs-ai/headroom/commit/fc5c4e239ce32f2b90a6777772a01bdf49c66cb6))
+* **install:** trust Docker bridge for dashboard metadata ([e044139](https://github.com/headroomlabs-ai/headroom/commit/e044139001680fd5198147bf373df6f00db32cc7))
+* **install:** use --userns=keep-id under Podman so bind-mount writes don't fail ([#2846](https://github.com/headroomlabs-ai/headroom/issues/2846)) ([3488f8d](https://github.com/headroomlabs-ai/headroom/commit/3488f8d4b5fae4eab157e0c4031ccf712bcbcc0d))
+* **learn/gemini:** stop double-counting session tokens ([#2230](https://github.com/headroomlabs-ai/headroom/issues/2230)) ([29d8a5e](https://github.com/headroomlabs-ai/headroom/commit/29d8a5e563cf16dbd3a53a1571f4f352e61e1b33))
+* **learn/grok:** detect a Windows absolute project path ([#2283](https://github.com/headroomlabs-ai/headroom/issues/2283)) ([e240df2](https://github.com/headroomlabs-ai/headroom/commit/e240df2b698e601324b85956bd93cb304f6030ab))
+* **learn:** stop classifying a successful exit code 0 as an error ([#2289](https://github.com/headroomlabs-ai/headroom/issues/2289)) ([a24fe7d](https://github.com/headroomlabs-ai/headroom/commit/a24fe7dcbfe5ab30d0cef631c936e2245c12d123))
+* **litellm:** add async_post_call_success_hook to HeadroomCallback ([#1322](https://github.com/headroomlabs-ai/headroom/issues/1322)) ([3107994](https://github.com/headroomlabs-ai/headroom/commit/3107994aed5fd42e713d3c26f3f08121a62b980e))
+* **litellm:** don't forward a caller key the target cannot accept ([#2883](https://github.com/headroomlabs-ai/headroom/issues/2883)) ([2f2950a](https://github.com/headroomlabs-ai/headroom/commit/2f2950a626cebf851aac29255e7188fbb1639f5a))
+* **memory:** bound the TrafficLearner pending-pattern accumulator (memory leak) ([#2579](https://github.com/headroomlabs-ai/headroom/issues/2579)) ([1f5feff](https://github.com/headroomlabs-ai/headroom/commit/1f5fefffd3e82c73bddd928cfd53334031e807bc))
+* **memory:** close DirectMem0 resources ([6596182](https://github.com/headroomlabs-ai/headroom/commit/65961827cf5e90d7b4e7026feb89aac000a73ea3))
+* **memory:** close MCP backend on shutdown ([4bd8ecd](https://github.com/headroomlabs-ai/headroom/commit/4bd8ecd1e31475365801791d35630f66f7393553))
+* **memory:** don't crash inline memory extraction on a non-object &lt;memory&gt; block ([#2470](https://github.com/headroomlabs-ai/headroom/issues/2470)) ([e00c6ff](https://github.com/headroomlabs-ai/headroom/commit/e00c6ff81ce2003e04042b8f2d1bd6aa3c6e885c))
+* **memory:** keep vector metadata in sync ([#2295](https://github.com/headroomlabs-ai/headroom/issues/2295)) ([c471800](https://github.com/headroomlabs-ai/headroom/commit/c471800e8ee22986c308464b02a85da5575f34cc))
+* **memory:** make explicit-project and user store keys collision-resistant ([#2231](https://github.com/headroomlabs-ai/headroom/issues/2231)) ([f840d5f](https://github.com/headroomlabs-ai/headroom/commit/f840d5f2fe938432e542c3f71f2218eeecd06b05))
+* **memory:** skip &lt;system-reminder&gt; blocks when building the retrieval query ([#2195](https://github.com/headroomlabs-ai/headroom/issues/2195)) ([#2541](https://github.com/headroomlabs-ai/headroom/issues/2541)) ([4e5a67a](https://github.com/headroomlabs-ai/headroom/commit/4e5a67a342be4be659b62c7863a9e72422605788))
+* **memory:** sync FTS5 and vector indexes on CLI delete/edit/prune/purge ([fd4628d](https://github.com/headroomlabs-ai/headroom/commit/fd4628d82156c65d4fa22df9513315790a6cd2fb))
+* **oauth2:** make repository lint checks pass ([c85abf7](https://github.com/headroomlabs-ai/headroom/commit/c85abf7a87920012e01f0a677f6fbd98c4b08de0))
+* **observability:** aggregate tool savings in OTEL ([#2936](https://github.com/headroomlabs-ai/headroom/issues/2936)) ([941c25d](https://github.com/headroomlabs-ai/headroom/commit/941c25d31e6c6e0b436c307cbe212771ff76b45f))
+* **onnx:** stop ONNX thread pools from spinning idle cores ([#2495](https://github.com/headroomlabs-ai/headroom/issues/2495)) ([#2540](https://github.com/headroomlabs-ai/headroom/issues/2540)) ([5c561bd](https://github.com/headroomlabs-ai/headroom/commit/5c561bd913ea60fad2c3c53f4b65e679e7d248d0))
+* **openai:** skip Responses tool-search deferral for clients that cannot execute it ([#2696](https://github.com/headroomlabs-ai/headroom/issues/2696)) ([54ea28d](https://github.com/headroomlabs-ai/headroom/commit/54ea28d9839a0dcfa4dd0cf4210a4421f03beeff))
+* **opencode:** ship the transport hook-shim so wheel installs route Node child traffic ([702dbc5](https://github.com/headroomlabs-ai/headroom/commit/702dbc5902ff184a7c20178958a811beb9c78fa3))
+* **providers/anthropic:** don't crash token estimation on null tool_calls ([#2472](https://github.com/headroomlabs-ai/headroom/issues/2472)) ([08466f3](https://github.com/headroomlabs-ai/headroom/commit/08466f3cae4dbb2647dc6f249fe42c4e840600c5))
+* **providers/openai:** bound tiktoken vocab loads with the guarded loader ([#2554](https://github.com/headroomlabs-ai/headroom/issues/2554)) ([0805e8e](https://github.com/headroomlabs-ai/headroom/commit/0805e8e410543d75c7ddd3b83dde5eda3bc13144))
+* **proxy/anthropic:** inject headroom_retrieve whenever a CCR marker is present, not only for new markers ([#2848](https://github.com/headroomlabs-ai/headroom/issues/2848)) ([3808f60](https://github.com/headroomlabs-ai/headroom/commit/3808f60ca61e84faf3ea8f8e003a6e6c8e9af4da))
+* **proxy/anthropic:** None-guard usage token counts on the direct buffered path ([#2434](https://github.com/headroomlabs-ai/headroom/issues/2434)) ([2b5ee7c](https://github.com/headroomlabs-ai/headroom/commit/2b5ee7cde809ca37f6998d9679b1eb2133ab50ca))
+* **proxy/anthropic:** run tool-search history repair after turn hooks ([c6f9948](https://github.com/headroomlabs-ai/headroom/commit/c6f99482e1bea024db6014a70c8e6da419543957))
+* **proxy/batch:** don't crash an OpenAI batch on a valid-JSON non-object line ([#2316](https://github.com/headroomlabs-ai/headroom/issues/2316)) ([1f2c681](https://github.com/headroomlabs-ai/headroom/commit/1f2c681c0b48150a569277d3ebd5e95709dc7c39))
+* **proxy/bedrock:** report uncached input tokens from backend usage, not the live-zone count ([#2318](https://github.com/headroomlabs-ai/headroom/issues/2318)) ([c19e412](https://github.com/headroomlabs-ai/headroom/commit/c19e412b3356d80dece001887d4ff48b6fd5150b))
+* **proxy/gemini:** keep streaming-parity baseline so eligible_pct can't exceed 100 ([#2824](https://github.com/headroomlabs-ai/headroom/issues/2824)) ([b97c7c6](https://github.com/headroomlabs-ai/headroom/commit/b97c7c6e99eac84df49c7a7e5f21dedb298716fe))
+* **proxy/metrics:** cap client-supplied model label cardinality ([#2480](https://github.com/headroomlabs-ai/headroom/issues/2480)) ([e24a7e6](https://github.com/headroomlabs-ai/headroom/commit/e24a7e66b95fa908c4ea6fd079809ece7692e6b2))
+* **proxy/metrics:** escape label values in the Prometheus export ([#2463](https://github.com/headroomlabs-ai/headroom/issues/2463)) ([6a53861](https://github.com/headroomlabs-ai/headroom/commit/6a53861063c3839e698bbec7194517bdfd851c38))
+* **proxy/openai:** don't crash the Responses memory tool loops on null arguments ([#2273](https://github.com/headroomlabs-ai/headroom/issues/2273)) ([a30db2c](https://github.com/headroomlabs-ai/headroom/commit/a30db2cae49b4ef03ebbd404ec1fc6c4f5f2404d))
+* **proxy/openai:** feed Codex WS traffic into the traffic learner ([#2334](https://github.com/headroomlabs-ai/headroom/issues/2334)) ([f669149](https://github.com/headroomlabs-ai/headroom/commit/f6691497692869b7067438597421ff12aace6bf4))
+* **proxy/openai:** run response hooks on Responses, and bill their re-drives ([#2872](https://github.com/headroomlabs-ai/headroom/issues/2872)) ([675d13f](https://github.com/headroomlabs-ai/headroom/commit/675d13f08d42455c8fa17bda878c1a11b905cee4))
+* **proxy:** allow settings routes for trusted gateway/dashboard clients ([#2491](https://github.com/headroomlabs-ai/headroom/issues/2491)) ([a5b0a8f](https://github.com/headroomlabs-ai/headroom/commit/a5b0a8f4cc54d68afcf371a422b3a4a9635b7e7f))
+* **proxy:** cache litellm model resolution to stop repeated Provider List spam ([99f07e7](https://github.com/headroomlabs-ai/headroom/commit/99f07e7bbdded9dadc70e35ee6ab025279d1aa22))
+* **proxy:** cancel periodic TOIN task on shutdown ([739fdef](https://github.com/headroomlabs-ai/headroom/commit/739fdef423fa8cbc82537481c875d4570b0ecad4))
+* **proxy:** close the upstream stream when a streaming body is never consumed ([0951663](https://github.com/headroomlabs-ai/headroom/commit/09516635621caccf7e3db4f537eb49ea49b8a453))
+* **proxy:** compress cache-mode cold starts and tag prefix-mismatch passthrough ([#2365](https://github.com/headroomlabs-ai/headroom/issues/2365)) ([aaeba0a](https://github.com/headroomlabs-ai/headroom/commit/aaeba0a319f12b98cad3bfcf1cf991b694b946bf))
+* **proxy:** emit request log timestamps in UTC ([620028f](https://github.com/headroomlabs-ai/headroom/commit/620028fa18843622d3e454bd40fb91a93e607dbf))
+* **proxy:** enable tool search by default and repair poisoned transcripts ([#2807](https://github.com/headroomlabs-ai/headroom/issues/2807)) ([0237cbf](https://github.com/headroomlabs-ai/headroom/commit/0237cbffbbc456ad8a7398005602d76881862d99))
+* **proxy:** gate mid-turn message coalescing to Claude Code clients ([#1643](https://github.com/headroomlabs-ai/headroom/issues/1643)) ([a4bd2e6](https://github.com/headroomlabs-ai/headroom/commit/a4bd2e62a5bb73f15b3b12e979c69e2b555bee10))
+* **proxy:** give each Codex /v1/responses WS turn a unique request_id ([#2164](https://github.com/headroomlabs-ai/headroom/issues/2164)) ([d02df10](https://github.com/headroomlabs-ai/headroom/commit/d02df1075894b414d60626aca2bbcadd7a3577a0))
+* **proxy:** graceful shutdown and reliable Ctrl+C exit ([#621](https://github.com/headroomlabs-ai/headroom/issues/621)) ([17cdb18](https://github.com/headroomlabs-ai/headroom/commit/17cdb185bc79d8cfec104e781a7e555af3ef11e1))
+* **proxy:** guard telemetry and TOIN endpoints ([cde1513](https://github.com/headroomlabs-ai/headroom/commit/cde1513c91b6c6c240869bc5660f4b8966197bbc))
+* **proxy:** include tool_search_deferral savings in the savings ledger ([12149f7](https://github.com/headroomlabs-ai/headroom/commit/12149f74466c08b69be8d5fe751425be63c2fda4))
+* **proxy:** pass through cross-region prefixed Bedrock model IDs directly ([#2330](https://github.com/headroomlabs-ai/headroom/issues/2330)) ([64cb46e](https://github.com/headroomlabs-ai/headroom/commit/64cb46e24bf7b223ea71b14b6f5e86e78fa7ac45))
+* **proxy:** port session-sticky beta headers to the Rust proxy ([#2381](https://github.com/headroomlabs-ai/headroom/issues/2381)) ([f6398a6](https://github.com/headroomlabs-ai/headroom/commit/f6398a64768a095b722a5fb0b2445c7953dee1c6))
+* **proxy:** preserve merged session and quarantine contracts ([#2943](https://github.com/headroomlabs-ai/headroom/issues/2943)) ([039cd24](https://github.com/headroomlabs-ai/headroom/commit/039cd2431aaec7d59fefaf7e97aeda1fd7ab3afa))
+* **proxy:** preserve signed Anthropic thinking blocks on outbound re-serialize ([#2254](https://github.com/headroomlabs-ai/headroom/issues/2254)) ([dc163bc](https://github.com/headroomlabs-ai/headroom/commit/dc163bcd1cba4cd8898f23286eb1365fcf6e0356))
+* **proxy:** stop discarding compressed Codex WS later-frame payloads ([#2823](https://github.com/headroomlabs-ai/headroom/issues/2823)) ([4ec416d](https://github.com/headroomlabs-ai/headroom/commit/4ec416df8899036544e679f561f1cf921f3da0dd))
+* **proxy:** time-cap the compression timeout-debt quarantine ([#2360](https://github.com/headroomlabs-ai/headroom/issues/2360)) ([#2412](https://github.com/headroomlabs-ai/headroom/issues/2412)) ([c5a08d2](https://github.com/headroomlabs-ai/headroom/commit/c5a08d22e05a7dd2b929f3cca76ee3fb42f122db))
+* **proxy:** unwrap Hermes tool_call bridge in tool name map ([#2717](https://github.com/headroomlabs-ai/headroom/issues/2717)) ([a97b824](https://github.com/headroomlabs-ai/headroom/commit/a97b82413bdc86655c064417ed4628ff4d9d7c9d))
+* publish headroom-opencode in release workflow ([#2372](https://github.com/headroomlabs-ai/headroom/issues/2372)) ([7859154](https://github.com/headroomlabs-ai/headroom/commit/78591545ceb8303fdf9b93cd5ff02b626df97d2b))
+* **settings:** accept documented HEADROOM_* env names as settings keys ([#2833](https://github.com/headroomlabs-ai/headroom/issues/2833)) ([de9e052](https://github.com/headroomlabs-ai/headroom/commit/de9e0523dad47b700062464adecd60f82547f332))
+* **subscription:** dedup transcript usage by message id ([#2340](https://github.com/headroomlabs-ai/headroom/issues/2340) token inflation) ([#2408](https://github.com/headroomlabs-ai/headroom/issues/2408)) ([74275b7](https://github.com/headroomlabs-ai/headroom/commit/74275b7c3e2b39be5198f9efa35057a5e026e665))
+* **toin:** bound private query and pattern retention ([8cd1380](https://github.com/headroomlabs-ai/headroom/commit/8cd138039edbfc295080ec474325d527fb3aedf3))
+* **tokenizer:** coerce non-string tool_call fields before counting ([#2801](https://github.com/headroomlabs-ai/headroom/issues/2801)) ([b6f9877](https://github.com/headroomlabs-ai/headroom/commit/b6f9877c78b3fa3b1d705426bd27d74be77f4fa0))
+* **tokenizer:** price CJK in the Rust fixed-ratio estimator (Python parity) ([#2260](https://github.com/headroomlabs-ai/headroom/issues/2260)) ([6840153](https://github.com/headroomlabs-ai/headroom/commit/6840153473caa0d61e982215e16a8cf54b0b6cc7))
+* **transforms/adaptive-sizer:** honor max_k on small-input fast path ([#2319](https://github.com/headroomlabs-ai/headroom/issues/2319)) ([8a90523](https://github.com/headroomlabs-ai/headroom/commit/8a905232091d993fac9e19a59bc449f201d4cdf3))
+* **transforms/smart_crusher:** don't crash on a tool call with a null function ([#2232](https://github.com/headroomlabs-ai/headroom/issues/2232)) ([3bb02f8](https://github.com/headroomlabs-ai/headroom/commit/3bb02f8f75f12cf8258a5b1c2a7fbdc190f9d074))
+* Vertex model pricing shows $0.00 for versioned model names and vertex:anthropic provider ([#2517](https://github.com/headroomlabs-ai/headroom/issues/2517)) ([eb5b5e4](https://github.com/headroomlabs-ai/headroom/commit/eb5b5e41988f5c27d29ae8ae3e5fe74e56493b8c))
+* **wrap/claude:** keep --1m effective when an explicit --model is passed through ([c093bf1](https://github.com/headroomlabs-ai/headroom/commit/c093bf11eb5f356f71367ebb7b56ae3c2b434a12))
+* **wrap/opencode:** verify the opencode binary before mutating config ([ae38486](https://github.com/headroomlabs-ai/headroom/commit/ae384862a4950cec057103e9daf75e74107640df))
+* **wrap/serena:** install Serena from the serena-agent PyPI wheel, not the git source ([d7b25ae](https://github.com/headroomlabs-ai/headroom/commit/d7b25ae3bb3364cde4931509ecb65e32085e5b09))
+* **wrap:** honor Copilot OAuth wire-api override and model default ([#2387](https://github.com/headroomlabs-ai/headroom/issues/2387)) ([1db6d88](https://github.com/headroomlabs-ai/headroom/commit/1db6d88ab4ea25654b8277358902b7df700db6b4))
+* **wrap:** serialize shared proxy startup ([#2946](https://github.com/headroomlabs-ai/headroom/issues/2946)) ([e540d64](https://github.com/headroomlabs-ai/headroom/commit/e540d64febf27f2e7997d3a1a1d89478cc1ef658))
+* **wrap:** stop the launch cwd from shadowing the installed package in the proxy subprocess ([#2843](https://github.com/headroomlabs-ai/headroom/issues/2843)) ([c49be26](https://github.com/headroomlabs-ai/headroom/commit/c49be269a18446779cd8a048caaa7f0ba3a3b48b))
+
+
+### Performance Improvements
+
+* cut hot-path latency 27% (token-count memo, startup preloads, JSON scan memo) ([#2838](https://github.com/headroomlabs-ai/headroom/issues/2838)) ([53af90d](https://github.com/headroomlabs-ai/headroom/commit/53af90d68c723f644a5a41dd273a606117109866))
+* **proxy:** bound upstream calls and hot-path costs ([#2852](https://github.com/headroomlabs-ai/headroom/issues/2852)) ([f624d3a](https://github.com/headroomlabs-ai/headroom/commit/f624d3a00ac271db7947443ddeb0c8bc2e93d3eb))
+* **subscription:** skip transcripts older than the window in compute_window_tokens ([#2861](https://github.com/headroomlabs-ai/headroom/issues/2861)) ([91d6bf3](https://github.com/headroomlabs-ai/headroom/commit/91d6bf33cde777b541375fb182d4479fdd78f81b))
+
+
+### Dependencies
+
+* bump brace-expansion from 5.0.7 to 5.0.9 in /docs ([#2751](https://github.com/headroomlabs-ai/headroom/issues/2751)) ([56ee57b](https://github.com/headroomlabs-ai/headroom/commit/56ee57be98bf109f0a46de522724ef169a4bc51c))
+* bump bytesize from 1.3.3 to 2.4.2 ([#2286](https://github.com/headroomlabs-ai/headroom/issues/2286)) ([6448545](https://github.com/headroomlabs-ai/headroom/commit/6448545a7f5a1dee88bce6f0830bdbfd1c99c617))
+* bump hf-hub from 0.4.3 to 0.5.0 ([#2285](https://github.com/headroomlabs-ai/headroom/issues/2285)) ([4925bf6](https://github.com/headroomlabs-ai/headroom/commit/4925bf6a829735977bab5000b469c3edb19c75b1))
+* bump next from 16.2.10 to 16.3.0 in /docs ([#2750](https://github.com/headroomlabs-ai/headroom/issues/2750)) ([0fd0b99](https://github.com/headroomlabs-ai/headroom/commit/0fd0b996a4b58a166491b145f4d3885c21b27cc0))
+* bump postcss from 8.5.19 to 8.5.25 in /plugins/openclaw ([#2749](https://github.com/headroomlabs-ai/headroom/issues/2749)) ([cd60ee9](https://github.com/headroomlabs-ai/headroom/commit/cd60ee9ae886b32ba5da3203e35bb6b088031fd3))
+* bump postcss from 8.5.19 to 8.5.25 in /plugins/opencode ([#2748](https://github.com/headroomlabs-ai/headroom/issues/2748)) ([ff4e016](https://github.com/headroomlabs-ai/headroom/commit/ff4e0167bbccbd4ae51bf23ddec144e61c94cd68))
+* bump postcss from 8.5.19 to 8.5.25 in /sdk/typescript ([#2747](https://github.com/headroomlabs-ai/headroom/issues/2747)) ([267c2bd](https://github.com/headroomlabs-ai/headroom/commit/267c2bdcb56e132b2dd9c065dab3498dbf730ca3))
+* bump postcss from 8.5.19 to 8.5.26 in /docs ([#2881](https://github.com/headroomlabs-ai/headroom/issues/2881)) ([e6e5826](https://github.com/headroomlabs-ai/headroom/commit/e6e5826423a0a700a8c544ce2c8cbcdef694160e))
+* bump ruff from 0.15.17 to 0.15.22 in the pip-minor-patch group ([#2501](https://github.com/headroomlabs-ai/headroom/issues/2501)) ([ecf130d](https://github.com/headroomlabs-ai/headroom/commit/ecf130d3ac6fb864098cb93fafd2621ae3ac7e12))
+* bump rusqlite from 0.32.1 to 0.40.1 ([#2287](https://github.com/headroomlabs-ai/headroom/issues/2287)) ([522faa1](https://github.com/headroomlabs-ai/headroom/commit/522faa1a59aa94e4adfd4a4afe0202d1126e187d))
+* bump the cargo-minor-patch group across 1 directory with 22 updates ([#2916](https://github.com/headroomlabs-ai/headroom/issues/2916)) ([148d860](https://github.com/headroomlabs-ai/headroom/commit/148d8605e2087f3c8d6a3fa4b8d248ad2da5858f))
+
 ## [0.34.0](https://github.com/headroomlabs-ai/headroom/compare/v0.33.0...v0.34.0) (2026-08-05)
 
 
diff --git a/Cargo.lock b/Cargo.lock
index 5959d3596..2da32bedf 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -24,9 +24,9 @@ dependencies = [
 
 [[package]]
 name = "aho-corasick"
-version = "1.1.4"
+version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
 dependencies = [
  "memchr",
 ]
@@ -49,6 +49,15 @@ dependencies = [
  "equator",
 ]
 
+[[package]]
+name = "alloca"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5a7d05ea6aea7e9e64d25b9156ba2fee3fdd659e34e41063cd2fc7cd020d7f4"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "allocator-api2"
 version = "0.2.21"
@@ -122,9 +131,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.103"
+version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 
 [[package]]
 name = "arbitrary"
@@ -149,7 +158,7 @@ checksum = "0ae92a5119aa49cdbcf6b9f893fe4e1d98b04ccbf82ee0584ad948a44a734dea"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -185,13 +194,13 @@ dependencies = [
 
 [[package]]
 name = "async-trait"
-version = "0.1.89"
+version = "0.1.92"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -221,7 +230,7 @@ dependencies = [
  "num-traits",
  "pastey",
  "rayon",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "v_frame",
  "y4m",
 ]
@@ -251,9 +260,9 @@ dependencies = [
 
 [[package]]
 name = "aws-config"
-version = "1.9.0"
+version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47712fde1909402600ccfbb26e47d482d2e58bb9e9e603d9f17e67cc435a6319"
+checksum = "1b180a3c8b55960db3426d8964b8745e652466a1a49fe1a2eda828046d30b5e4"
 dependencies = [
  "aws-credential-types",
  "aws-runtime",
@@ -271,8 +280,8 @@ dependencies = [
  "bytes",
  "fastrand",
  "hex",
- "http 1.4.2",
- "sha1",
+ "http 1.5.0",
+ "sha1 0.10.6",
  "time",
  "tokio",
  "tracing",
@@ -316,9 +325,9 @@ dependencies = [
 
 [[package]]
 name = "aws-runtime"
-version = "1.8.1"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7816e98ee912159f45d307e5ee6bfea4a335a55aee15f7f3e32f81a6f3000f1d"
+checksum = "c9007227e10b5fed2f3e0a2beff489211e2b5604c400b7a9d5d81ca9d64c24bb"
 dependencies = [
  "aws-credential-types",
  "aws-sigv4",
@@ -331,7 +340,7 @@ dependencies = [
  "bytes",
  "bytes-utils",
  "fastrand",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "percent-encoding",
  "pin-project-lite",
@@ -341,9 +350,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-sso"
-version = "1.103.0"
+version = "1.105.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0469f435f645ad2162cfb463b15bde37115966ee3acf2d87fb4871ee309b8401"
+checksum = "6ffd0fbe7873cb548a7aa60f9573c268fff94155397fd4f14dc9f1ecaaab8516"
 dependencies = [
  "arc-swap",
  "aws-credential-types",
@@ -360,16 +369,16 @@ dependencies = [
  "bytes",
  "fastrand",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "regex-lite",
  "tracing",
 ]
 
 [[package]]
 name = "aws-sdk-ssooidc"
-version = "1.105.0"
+version = "1.107.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "085faefb253f770655e162b9304321e62a1e71adf7f019ee1f4454228a377b3a"
+checksum = "175763eb222a46377df7aa257a3bca980ab3e96703fefc8f4d0b8da6ad2e254c"
 dependencies = [
  "arc-swap",
  "aws-credential-types",
@@ -386,16 +395,16 @@ dependencies = [
  "bytes",
  "fastrand",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "regex-lite",
  "tracing",
 ]
 
 [[package]]
 name = "aws-sdk-sts"
-version = "1.108.0"
+version = "1.110.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c72b08911d8128dd360fe1b22a9fec0fa8b552dde8ec828dcf20ef5ec974e9f"
+checksum = "dd8b14781dfbff48984017d57167b6ea0b6471c6920ec52b44a2677c7feb3c13"
 dependencies = [
  "arc-swap",
  "aws-credential-types",
@@ -413,7 +422,7 @@ dependencies = [
  "aws-types",
  "fastrand",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "regex-lite",
  "tracing",
 ]
@@ -433,7 +442,7 @@ dependencies = [
  "hex",
  "hmac",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "percent-encoding",
  "sha2 0.11.0",
  "time",
@@ -463,7 +472,7 @@ dependencies = [
  "bytes-utils",
  "futures-core",
  "futures-util",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "http-body-util",
  "percent-encoding",
@@ -482,7 +491,7 @@ dependencies = [
  "aws-smithy-runtime-api",
  "aws-smithy-types",
  "h2",
- "http 1.4.2",
+ "http 1.5.0",
  "hyper",
  "hyper-rustls",
  "hyper-util",
@@ -518,19 +527,22 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-query"
-version = "0.61.1"
+version = "0.62.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd22a6ba36e3f113cb8d5b3d1fe0ed31c76ee608ef63322d753bb8d2c9479e77"
+checksum = "512346c7212ab7436df2d77a16d976a468ae44a418835511d2a69269810aaf62"
 dependencies = [
+ "aws-smithy-runtime-api",
+ "aws-smithy-schema",
  "aws-smithy-types",
+ "aws-smithy-xml",
  "urlencoding",
 ]
 
 [[package]]
 name = "aws-smithy-runtime"
-version = "1.12.0"
+version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bea94a9ff8464016338c851e24b472d7131c388c88898a502e781815b2ee6045"
+checksum = "07505b34e8f4b3591a4fa69e9792b52289b95488dbbc68c3c0075b7bedb245e1"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-http",
@@ -542,7 +554,7 @@ dependencies = [
  "bytes",
  "fastrand",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 0.4.6",
  "http-body 1.0.1",
  "http-body-util",
@@ -554,16 +566,16 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-runtime-api"
-version = "1.13.0"
+version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22ed1ebe6e0a95ea84570225f5a8208dec4b8f77e61a9b0d6f51773fcb4612f0"
+checksum = "3b98f2e1fd67ec06618f9c291e5e495a468e60519e44c9c1979cd0521f3affdb"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-runtime-api-macros",
  "aws-smithy-types",
  "bytes",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "pin-project-lite",
  "tokio",
  "tracing",
@@ -578,7 +590,7 @@ checksum = "221eaa237ddf1ca79b60d1372aad77e47f9c0ea5b3ce5099da8c61d027dc77b3"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -589,7 +601,7 @@ checksum = "7d56e0a4e53127a632224e43633b0fe045fa9e1e3cfc68b9830f1115e103f910"
 dependencies = [
  "aws-smithy-runtime-api",
  "aws-smithy-types",
- "http 1.4.2",
+ "http 1.5.0",
 ]
 
 [[package]]
@@ -602,7 +614,7 @@ dependencies = [
  "bytes",
  "bytes-utils",
  "http 0.2.12",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 0.4.6",
  "http-body 1.0.1",
  "http-body-util",
@@ -617,9 +629,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-xml"
-version = "0.61.1"
+version = "0.62.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea3f68eec3607f02acd24067969ce2abc6ba16aa7d5ce59ca450ed2fb5f78957"
+checksum = "ce84f71c72fee2cbbadde6e7d082f5fb466e3a84733855295fa7aafd1b31b7d8"
 dependencies = [
  "aws-smithy-runtime-api",
  "aws-smithy-schema",
@@ -629,9 +641,9 @@ dependencies = [
 
 [[package]]
 name = "aws-types"
-version = "1.4.0"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e957a6c6dbce82b7a91f44231c09273159703769f447cbe85e854dfe9cf67f86"
+checksum = "eec1cd5469f328c782dc3e33d4153cf118a54e33cbb3356d60d16f89883e1f94"
 dependencies = [
  "aws-credential-types",
  "aws-smithy-async",
@@ -654,7 +666,7 @@ dependencies = [
  "base64 0.22.1",
  "bytes",
  "futures-util",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "http-body-util",
  "hyper",
@@ -670,10 +682,10 @@ dependencies = [
  "serde_json",
  "serde_path_to_error",
  "serde_urlencoded",
- "sha1",
+ "sha1 0.10.6",
  "sync_wrapper",
  "tokio",
- "tokio-tungstenite",
+ "tokio-tungstenite 0.24.0",
  "tower",
  "tower-layer",
  "tower-service",
@@ -689,7 +701,7 @@ dependencies = [
  "async-trait",
  "bytes",
  "futures-util",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "http-body-util",
  "mime",
@@ -709,7 +721,7 @@ checksum = "57d123550fa8d071b7255cb0cc04dc302baa6c8c4a79f55701552684d8399bce"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -772,9 +784,9 @@ dependencies = [
 
 [[package]]
 name = "blake3"
-version = "1.8.5"
+version = "1.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0aa83c34e62843d924f905e0f5c866eb1dd6545fc4d719e803d9ba6030371fce"
+checksum = "76ae7bad254120e9e4c63bafc385310756f90c484eac0e36b8317cf09cb92a77"
 dependencies = [
  "arrayref",
  "arrayvec",
@@ -861,9 +873,9 @@ dependencies = [
 
 [[package]]
 name = "bytesize"
-version = "1.3.3"
+version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e93abca9e28e0a1b9877922aacb20576e05d4679ffa78c3d6dc22a26a216659"
+checksum = "7354288c522e7e980fafd2075d63d1285794c3a6a16cdd492f189ea406e5f18b"
 
 [[package]]
 name = "cast"
@@ -882,9 +894,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.2.67"
+version = "1.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
+checksum = "5d262e149917187838d5b42777c8253bcb64500067342904e7d429499a6f277e"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -904,6 +916,17 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
+[[package]]
+name = "chacha20"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
+]
+
 [[package]]
 name = "chrono"
 version = "0.4.45"
@@ -947,9 +970,9 @@ dependencies = [
 
 [[package]]
 name = "clap"
-version = "4.6.2"
+version = "4.6.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd059f9da4f5c36b3787f65d38ccaab1cc315f07b01f89abc8359ee6a8205011"
+checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -957,9 +980,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.6.2"
+version = "4.6.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
+checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
 dependencies = [
  "anstream",
  "anstyle",
@@ -969,14 +992,14 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.6.1"
+version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -1037,19 +1060,6 @@ dependencies = [
  "static_assertions",
 ]
 
-[[package]]
-name = "console"
-version = "0.15.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "054ccb5b10f9f2cbf51eb355ca1d05c2d279ce1804688d0db74b4733a5aeafd8"
-dependencies = [
- "encode_unicode",
- "libc",
- "once_cell",
- "unicode-width",
- "windows-sys 0.59.0",
-]
-
 [[package]]
 name = "console"
 version = "0.16.3"
@@ -1157,25 +1167,24 @@ dependencies = [
 
 [[package]]
 name = "criterion"
-version = "0.5.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
+checksum = "950046b2aa2492f9a536f5f4f9a3de7b9e2476e575e05bd6c333371add4d98f3"
 dependencies = [
+ "alloca",
  "anes",
  "cast",
  "ciborium",
  "clap",
  "criterion-plot",
- "is-terminal",
- "itertools 0.10.5",
+ "itertools 0.13.0",
  "num-traits",
- "once_cell",
  "oorandom",
+ "page_size",
  "plotters",
  "rayon",
  "regex",
  "serde",
- "serde_derive",
  "serde_json",
  "tinytemplate",
  "walkdir",
@@ -1183,12 +1192,12 @@ dependencies = [
 
 [[package]]
 name = "criterion-plot"
-version = "0.5.0"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
+checksum = "d8d80a2f4f5b554395e47b5d8305bc3d27813bacb73493eb1001e8f76dae29ea"
 dependencies = [
  "cast",
- "itertools 0.10.5",
+ "itertools 0.13.0",
 ]
 
 [[package]]
@@ -1271,7 +1280,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "strsim",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1282,7 +1291,7 @@ checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead"
 dependencies = [
  "darling_core",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1356,7 +1365,7 @@ dependencies = [
  "darling",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1366,7 +1375,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ab63b0e2bf4d5928aff72e83a7dace85d7bba5fe12dcc3c5a572d78caffd3f3c"
 dependencies = [
  "derive_builder_core",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1420,7 +1429,7 @@ checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1476,7 +1485,7 @@ checksum = "44f23cf4b44bfce11a86ace86f8a73ffdec849c9fd00a386a53d278bd9e81fb3"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1549,7 +1558,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f3c8600c9ec79b51d60c19911fe14eac04fe9c2895e87d2a3e80e2213d645a32"
 dependencies = [
  "anyhow",
- "hf-hub 0.5.0",
+ "hf-hub",
  "image",
  "ndarray",
  "ort",
@@ -1582,9 +1591,9 @@ dependencies = [
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.9"
+version = "0.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+checksum = "26b73573e6edcd2af0cdf47bd6cb58f0b3839491263c314eaad1ccf24430e1de"
 
 [[package]]
 name = "flate2"
@@ -1625,9 +1634,9 @@ checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
 
 [[package]]
 name = "futures"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d"
+checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218"
 dependencies = [
  "futures-channel",
  "futures-core",
@@ -1640,9 +1649,9 @@ dependencies = [
 
 [[package]]
 name = "futures-channel"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
 dependencies = [
  "futures-core",
  "futures-sink",
@@ -1650,15 +1659,15 @@ dependencies = [
 
 [[package]]
 name = "futures-core"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
 
 [[package]]
 name = "futures-executor"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
+checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
 dependencies = [
  "futures-core",
  "futures-task",
@@ -1667,38 +1676,38 @@ dependencies = [
 
 [[package]]
 name = "futures-io"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
 
 [[package]]
 name = "futures-macro"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
+checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "futures-sink"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
 
 [[package]]
 name = "futures-task"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
 
 [[package]]
 name = "futures-util"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
 dependencies = [
  "futures-channel",
  "futures-core",
@@ -1721,7 +1730,7 @@ dependencies = [
  "base64 0.22.1",
  "bytes",
  "chrono",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body-util",
  "hyper",
  "hyper-rustls",
@@ -1731,7 +1740,7 @@ dependencies = [
  "rustls-pki-types",
  "serde",
  "serde_json",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "tracing-futures",
@@ -1784,6 +1793,7 @@ dependencies = [
  "cfg-if",
  "libc",
  "r-efi 6.0.0",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -1807,7 +1817,7 @@ dependencies = [
  "fnv",
  "futures-core",
  "futures-sink",
- "http 1.4.2",
+ "http 1.5.0",
  "indexmap",
  "slab",
  "tokio",
@@ -1831,9 +1841,6 @@ name = "hashbrown"
 version = "0.14.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
-dependencies = [
- "ahash",
-]
 
 [[package]]
 name = "hashbrown"
@@ -1861,11 +1868,11 @@ dependencies = [
 
 [[package]]
 name = "hashlink"
-version = "0.9.1"
+version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"
+checksum = "32069d97bb81e38fa67eab65e3393bf804bb85969f2bc06bf13f64aef5aba248"
 dependencies = [
- "hashbrown 0.14.5",
+ "hashbrown 0.17.1",
 ]
 
 [[package]]
@@ -1879,8 +1886,8 @@ dependencies = [
  "dashmap",
  "fastembed",
  "flate2",
- "hf-hub 0.4.3",
- "http 1.4.2",
+ "hf-hub",
+ "http 1.5.0",
  "icu_segmenter",
  "magika",
  "md-5",
@@ -1894,7 +1901,7 @@ dependencies = [
  "serde_json",
  "sha2 0.10.9",
  "tempfile",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "tiktoken-rs",
  "tokenizers",
  "toml",
@@ -1920,7 +1927,7 @@ dependencies = [
  "headroom-core",
  "serde",
  "serde_json",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -1942,7 +1949,7 @@ dependencies = [
  "gcp_auth",
  "headroom-core",
  "headroom-simulators",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body-util",
  "humantime",
  "hyper",
@@ -1956,10 +1963,10 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2 0.10.9",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "tokio",
  "tokio-stream",
- "tokio-tungstenite",
+ "tokio-tungstenite 0.30.0",
  "tokio-util",
  "tower",
  "tower-http 0.7.0",
@@ -1989,12 +1996,12 @@ dependencies = [
  "bytes",
  "clap",
  "crc32fast",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body-util",
  "reqwest",
  "serde",
  "serde_json",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "tokio",
  "tower",
  "tracing",
@@ -2019,26 +2026,6 @@ version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
-[[package]]
-name = "hf-hub"
-version = "0.4.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "629d8f3bbeda9d148036d6b0de0a3ab947abd08ce90626327fc3547a49d59d97"
-dependencies = [
- "dirs",
- "http 1.4.2",
- "indicatif 0.17.11",
- "libc",
- "log",
- "rand 0.9.4",
- "reqwest",
- "serde",
- "serde_json",
- "thiserror 2.0.18",
- "ureq 2.12.1",
- "windows-sys 0.60.2",
-]
-
 [[package]]
 name = "hf-hub"
 version = "0.5.0"
@@ -2046,16 +2033,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "aef3982638978efa195ff11b305f51f1f22f4f0a6cabee7af79b383ebee6a213"
 dependencies = [
  "dirs",
- "http 1.4.2",
- "indicatif 0.18.4",
+ "http 1.5.0",
+ "indicatif",
  "libc",
  "log",
  "rand 0.9.4",
  "reqwest",
  "serde",
  "serde_json",
- "thiserror 2.0.18",
- "ureq 3.3.0",
+ "thiserror 2.0.20",
+ "ureq",
  "windows-sys 0.61.2",
 ]
 
@@ -2081,9 +2068,9 @@ dependencies = [
 
 [[package]]
 name = "http"
-version = "1.4.2"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
 dependencies = [
  "bytes",
  "itoa",
@@ -2107,7 +2094,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
 dependencies = [
  "bytes",
- "http 1.4.2",
+ "http 1.5.0",
 ]
 
 [[package]]
@@ -2118,7 +2105,7 @@ checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
 dependencies = [
  "bytes",
  "futures-core",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "pin-project-lite",
 ]
@@ -2152,16 +2139,16 @@ dependencies = [
 
 [[package]]
 name = "hyper"
-version = "1.10.1"
+version = "1.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498"
+checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
 dependencies = [
  "atomic-waker",
  "bytes",
  "futures-channel",
  "futures-core",
  "h2",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "httparse",
  "httpdate",
@@ -2178,7 +2165,7 @@ version = "0.27.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
 dependencies = [
- "http 1.4.2",
+ "http 1.5.0",
  "hyper",
  "hyper-util",
  "rustls",
@@ -2199,7 +2186,7 @@ dependencies = [
  "bytes",
  "futures-channel",
  "futures-util",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "hyper",
  "ipnet",
@@ -2441,26 +2428,13 @@ dependencies = [
  "hashbrown 0.17.1",
 ]
 
-[[package]]
-name = "indicatif"
-version = "0.17.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "183b3088984b400f4cfac3620d5e076c84da5364016b4f49473de574b2586235"
-dependencies = [
- "console 0.15.11",
- "number_prefix",
- "portable-atomic",
- "unicode-width",
- "web-time",
-]
-
 [[package]]
 name = "indicatif"
 version = "0.18.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "25470f23803092da7d239834776d653104d551bc4d7eacaf31e6837854b8e9eb"
 dependencies = [
- "console 0.16.3",
+ "console",
  "portable-atomic",
  "unicode-width",
  "unit-prefix",
@@ -2475,7 +2449,7 @@ checksum = "c34819042dc3d3971c46c2190835914dfbe0c3c13f61449b2997f4e9722dfa60"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2484,32 +2458,12 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
-[[package]]
-name = "is-terminal"
-version = "0.4.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
-dependencies = [
- "hermit-abi",
- "libc",
- "windows-sys 0.61.2",
-]
-
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
-[[package]]
-name = "itertools"
-version = "0.10.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
-dependencies = [
- "either",
-]
-
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -2610,9 +2564,9 @@ dependencies = [
 
 [[package]]
 name = "libsqlite3-sys"
-version = "0.30.1"
+version = "0.38.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149"
+checksum = "f1d20bef17f513b9b3004532233187769cd072d790971f4e4da0e346eb6401e8"
 dependencies = [
  "cc",
  "pkg-config",
@@ -2663,9 +2617,9 @@ dependencies = [
 
 [[package]]
 name = "lru"
-version = "0.18.1"
+version = "0.18.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b6180140927ee907000b0aa540091f6ea512ead4447c92b8fc35bc72788a5a6"
+checksum = "5d2f2f9b4ba7e6b24d95e7e899329d35be83bcded72c8540cdd5368932d1d90a"
 dependencies = [
  "hashbrown 0.17.1",
 ]
@@ -2807,7 +2761,7 @@ checksum = "e4db6d5580af57bf992f59068d4ea26fd518574ff48d7639b255a36f9de6e7e9"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2917,7 +2871,7 @@ checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2959,12 +2913,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "number_prefix"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "830b246a0e5f20af87141b25c173cd1b609bd7779a4617d6ec582abaf90870f3"
-
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -3042,6 +2990,16 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e"
 
+[[package]]
+name = "page_size"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d5b2194ed13191c1999ae0704b7839fb18384fa22e49b57eeaa97d79ce40da"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -3100,7 +3058,7 @@ checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -3228,7 +3186,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4488a4a36b9a4ba6b9334a32a39971f77c1436ec82c38707bce707699cc3bbcb"
 dependencies = [
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -3242,7 +3200,7 @@ dependencies = [
  "lazy_static",
  "memchr",
  "parking_lot",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3272,9 +3230,9 @@ checksum = "e0c5ccf5294c6ccd63a74f1565028353830a9c2f5eb0c682c355c471726a6e3f"
 
 [[package]]
 name = "pyo3"
-version = "0.29.0"
+version = "0.29.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd274650b21d4bfc26a0a47587962c1edb425f69287324355cd040c3ea66071c"
+checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
 dependencies = [
  "libc",
  "once_cell",
@@ -3286,18 +3244,18 @@ dependencies = [
 
 [[package]]
 name = "pyo3-build-config"
-version = "0.29.0"
+version = "0.29.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c5e2a7d2f0d013342f295c048ad19237add5154a55b1c5a254c0ec93d4109078"
+checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
 dependencies = [
  "target-lexicon",
 ]
 
 [[package]]
 name = "pyo3-ffi"
-version = "0.29.0"
+version = "0.29.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca85c467da1bbc8d866eea5deff9cf29ea5f7785054a17da36e65bda9c05845b"
+checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
 dependencies = [
  "libc",
  "pyo3-build-config",
@@ -3316,26 +3274,26 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros"
-version = "0.29.0"
+version = "0.29.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ac53762fd065daa3194dd09337a38bd793a188100fd1a9304c4ab312d901771"
+checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
 dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "pyo3-macros-backend"
-version = "0.29.0"
+version = "0.29.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ca3a1557399783172dc5bf39cfca835157732532cba56b71d2292161e53b362"
+checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -3373,7 +3331,7 @@ dependencies = [
  "rustc-hash 2.1.2",
  "rustls",
  "socket2",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "tokio",
  "tracing",
  "web-time",
@@ -3394,7 +3352,7 @@ dependencies = [
  "rustls",
  "rustls-pki-types",
  "slab",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "tinyvec",
  "tracing",
  "web-time",
@@ -3411,7 +3369,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.60.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -3456,6 +3414,17 @@ dependencies = [
  "rand_core 0.9.5",
 ]
 
+[[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 0.10.1",
+]
+
 [[package]]
 name = "rand_chacha"
 version = "0.3.1"
@@ -3494,6 +3463,12 @@ dependencies = [
  "getrandom 0.3.4",
 ]
 
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
 [[package]]
 name = "rand_xorshift"
 version = "0.4.0"
@@ -3533,7 +3508,7 @@ dependencies = [
  "rand 0.9.4",
  "rand_chacha 0.9.0",
  "simd_helpers",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "v_frame",
  "wasm-bindgen",
 ]
@@ -3623,7 +3598,7 @@ checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
 dependencies = [
  "getrandom 0.2.17",
  "libredox",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
 ]
 
 [[package]]
@@ -3672,7 +3647,7 @@ dependencies = [
  "futures-core",
  "futures-util",
  "h2",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "http-body-util",
  "hyper",
@@ -3724,10 +3699,20 @@ dependencies = [
 ]
 
 [[package]]
-name = "rusqlite"
-version = "0.32.1"
+name = "rsqlite-vfs"
+version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"
+checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c"
+dependencies = [
+ "hashbrown 0.16.1",
+ "thiserror 2.0.20",
+]
+
+[[package]]
+name = "rusqlite"
+version = "0.40.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23f2a97da3e3873c73cb2a2e71b35c40ff95e0b1eefa8d72d8499a6928c3b5b3"
 dependencies = [
  "bitflags",
  "fallible-iterator",
@@ -3735,6 +3720,7 @@ dependencies = [
  "hashlink",
  "libsqlite3-sys",
  "smallvec",
+ "sqlite-wasm-rs",
 ]
 
 [[package]]
@@ -3938,14 +3924,14 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.150"
+version = "1.0.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
 dependencies = [
  "indexmap",
  "itoa",
@@ -3998,6 +3984,17 @@ dependencies = [
  "digest 0.10.7",
 ]
 
+[[package]]
+name = "sha1"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "digest 0.11.3",
+]
+
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -4105,6 +4102,18 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "sqlite-wasm-rs"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75"
+dependencies = [
+ "cc",
+ "js-sys",
+ "rsqlite-vfs",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -4146,6 +4155,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
 [[package]]
 name = "sync_wrapper"
 version = "1.0.2"
@@ -4163,7 +4183,7 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -4196,11 +4216,11 @@ dependencies = [
 
 [[package]]
 name = "thiserror"
-version = "2.0.18"
+version = "2.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
 dependencies = [
- "thiserror-impl 2.0.18",
+ "thiserror-impl 2.0.20",
 ]
 
 [[package]]
@@ -4211,18 +4231,18 @@ checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "2.0.18"
+version = "2.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -4342,7 +4362,7 @@ dependencies = [
  "derive_builder",
  "esaxx-rs",
  "getrandom 0.3.4",
- "indicatif 0.18.4",
+ "indicatif",
  "itertools 0.14.0",
  "log",
  "macro_rules_attribute",
@@ -4357,7 +4377,7 @@ dependencies = [
  "serde",
  "serde_json",
  "spm_precompiled",
- "thiserror 2.0.18",
+ "thiserror 2.0.20",
  "unicode-normalization-alignments",
  "unicode-segmentation",
  "unicode_categories",
@@ -4365,9 +4385,9 @@ dependencies = [
 
 [[package]]
 name = "tokio"
-version = "1.52.3"
+version = "1.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
 dependencies = [
  "bytes",
  "libc",
@@ -4387,7 +4407,7 @@ checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -4402,9 +4422,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-stream"
-version = "0.1.18"
+version = "0.1.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32da49809aab5c3bc678af03902d4ccddea2a87d028d86392a4b1560c6906c70"
+checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b"
 dependencies = [
  "futures-core",
  "pin-project-lite",
@@ -4416,6 +4436,18 @@ name = "tokio-tungstenite"
 version = "0.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "edc5f74e248dc973e0dbb7b74c7e0d6fcc301c694ff50049504004ef4d0cdcd9"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite 0.24.0",
+]
+
+[[package]]
+name = "tokio-tungstenite"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17a073bfed563fa236697a068031408a93cd9522e08abf9933ead3e73411bd71"
 dependencies = [
  "futures-util",
  "log",
@@ -4423,28 +4455,29 @@ dependencies = [
  "rustls-pki-types",
  "tokio",
  "tokio-rustls",
- "tungstenite",
+ "tungstenite 0.30.0",
  "webpki-roots 0.26.11",
 ]
 
 [[package]]
 name = "tokio-util"
-version = "0.7.18"
+version = "0.7.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
 dependencies = [
  "bytes",
  "futures-core",
  "futures-sink",
+ "libc",
  "pin-project-lite",
  "tokio",
 ]
 
 [[package]]
 name = "toml"
-version = "1.1.3+spec-1.1.0"
+version = "1.1.4+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53c96ecdfa941c8fc4fcaed14f99ada8ebed502eef533015095a07e3301d4c3c"
+checksum = "3aace63f4bbcdfc2c965b059de67119c89c4017a70d633be6c104910f67056f5"
 dependencies = [
  "indexmap",
  "serde_core",
@@ -4466,9 +4499,9 @@ dependencies = [
 
 [[package]]
 name = "toml_parser"
-version = "1.1.2+spec-1.1.0"
+version = "1.1.3+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
+checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
 dependencies = [
  "winnow",
 ]
@@ -4504,7 +4537,7 @@ dependencies = [
  "bitflags",
  "bytes",
  "futures-util",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "pin-project-lite",
  "tower",
@@ -4521,7 +4554,7 @@ checksum = "b11f75e912b0c2be01b63d8cf8057b8c3f97cf34abb3d431a3a4c8675498e233"
 dependencies = [
  "bitflags",
  "bytes",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body 1.0.1",
  "percent-encoding",
  "pin-project-lite",
@@ -4564,7 +4597,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -4744,17 +4777,33 @@ dependencies = [
  "byteorder",
  "bytes",
  "data-encoding",
- "http 1.4.2",
+ "http 1.5.0",
  "httparse",
  "log",
  "rand 0.8.6",
- "rustls",
- "rustls-pki-types",
- "sha1",
+ "sha1 0.10.6",
  "thiserror 1.0.69",
  "utf-8",
 ]
 
+[[package]]
+name = "tungstenite"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e48ac77174b19c110a50ab2128b24215ac9cb40e0e12e093fb602d175c569d22"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http 1.5.0",
+ "httparse",
+ "log",
+ "rand 0.10.2",
+ "rustls",
+ "rustls-pki-types",
+ "sha1 0.11.0",
+ "thiserror 2.0.20",
+]
+
 [[package]]
 name = "typenum"
 version = "1.20.1"
@@ -4802,9 +4851,9 @@ checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e"
 
 [[package]]
 name = "unidiff"
-version = "0.4.0"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3ae26d2e6582eb32eff85cffebf74d20b6510e8b558bbac3a23b48965cf952f"
+checksum = "98f3525b540ac79ce6db6f518b91f224c0aac4bffee14da01ccdb2edf5e2be1d"
 dependencies = [
  "encoding_rs",
  "regex",
@@ -4822,25 +4871,6 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
 
-[[package]]
-name = "ureq"
-version = "2.12.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
-dependencies = [
- "base64 0.22.1",
- "flate2",
- "log",
- "once_cell",
- "rustls",
- "rustls-pki-types",
- "serde",
- "serde_json",
- "socks",
- "url",
- "webpki-roots 0.26.11",
-]
-
 [[package]]
 name = "ureq"
 version = "3.3.0"
@@ -4869,7 +4899,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e994ba84b0bd1b1b0cf92878b7ef898a5c1760108fe7b6010327e274917a808c"
 dependencies = [
  "base64 0.22.1",
- "http 1.4.2",
+ "http 1.5.0",
  "httparse",
  "log",
 ]
@@ -5047,7 +5077,7 @@ dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "wasm-bindgen-shared",
 ]
 
@@ -5169,7 +5199,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5180,7 +5210,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5213,25 +5243,7 @@ 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",
+ "windows-targets",
 ]
 
 [[package]]
@@ -5249,31 +5261,14 @@ 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",
- "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",
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
 ]
 
 [[package]]
@@ -5282,96 +5277,48 @@ 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.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.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.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.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.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.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 = "1.0.3"
@@ -5388,7 +5335,7 @@ dependencies = [
  "base64 0.22.1",
  "deadpool",
  "futures",
- "http 1.4.2",
+ "http 1.5.0",
  "http-body-util",
  "hyper",
  "hyper-util",
@@ -5444,7 +5391,7 @@ checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "synstructure",
 ]
 
@@ -5465,7 +5412,7 @@ checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5485,7 +5432,7 @@ checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "synstructure",
 ]
 
@@ -5527,7 +5474,7 @@ checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
diff --git a/Dockerfile b/Dockerfile
index 8a73b44dd..fc2c3d176 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -47,7 +47,10 @@ COPY Cargo.toml Cargo.lock rust-toolchain.toml ./
 COPY crates/ crates/
 COPY headroom/ headroom/
 
-ARG HEADROOM_EXTRAS=proxy,code
+# The standalone Dockerfile must support every backend advertised by
+# `headroom proxy --backend`, including Bedrock temporary/SSO credentials.
+# Those credentials require botocore (GH #1551), supplied by [bedrock].
+ARG HEADROOM_EXTRAS=proxy,code,bedrock
 RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
diff --git a/README.md b/README.md
index 39a5852a3..0b923e940 100644
--- a/README.md
+++ b/README.md
@@ -415,7 +415,7 @@ Everything in this repo stays open source (Apache 2.0). The managed offering is
 uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
 pip install "headroom-ai[all]"                    # Python, everything — includes the `headroom` CLI
 npm install headroom-ai                           # TypeScript SDK (library only — no `headroom` CLI)
-docker pull ghcr.io/chopratejas/headroom:latest
+docker pull ghcr.io/headroomlabs-ai/headroom:latest
 ```
 
 Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`, `[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain, not in `[all]`), `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`, `[pytorch-mps]` (Apple-GPU memory-embedder offload — set `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.10+**.
diff --git a/TESTING-copilot-subscription.md b/TESTING-copilot-subscription.md
index 69204ca24..2255ccb28 100644
--- a/TESTING-copilot-subscription.md
+++ b/TESTING-copilot-subscription.md
@@ -107,7 +107,7 @@ There is **no native Windows wheel yet**, so pick one:
 
 **A. Mechanism test (easiest — Docker Desktop or WSL2):**
 ```powershell
-$env:HEADROOM_DOCKER_IMAGE = "ghcr.io/chopratejas/headroom:<branch-tag>"   # ask the maintainer for the tag
+$env:HEADROOM_DOCKER_IMAGE = "ghcr.io/headroomlabs-ai/headroom:<branch-tag>"   # ask the maintainer for the tag
 # run the Docker-native installer (scripts/install.ps1), then:
 $env:GITHUB_COPILOT_TOKEN = "<your-token>"
 headroom wrap copilot --subscription -- --model gpt-4o -p "Reply with: HEADROOM_OK"
diff --git a/crates/headroom-core/Cargo.toml b/crates/headroom-core/Cargo.toml
index c47d2a88b..c1f0d5537 100644
--- a/crates/headroom-core/Cargo.toml
+++ b/crates/headroom-core/Cargo.toml
@@ -22,7 +22,7 @@ tokenizers = "0.22"
 # with `rustls` (no system OpenSSL dep — keeps the binary static-linkable for
 # AWS deploys). `from_pretrained` is called once at startup, so blocking is
 # fine; if a tokio caller needs it later we can wrap in `spawn_blocking`.
-hf-hub = { version = "0.4", default-features = false, features = ["ureq", "rustls-tls"] }
+hf-hub = { version = "0.5", default-features = false, features = ["ureq", "rustls-tls"] }
 # `md5` for the CCR cache_key. Python's compression_store hashes the original
 # diff with MD5 truncated to 24 hex chars; we must match byte-for-byte.
 md-5 = "0.10"
@@ -125,7 +125,7 @@ blake3 = "1"
 # image may lag behind. Sub-1 MB binary cost. WAL is enabled at
 # connection-open time (see `ccr/backends/sqlite.rs`); no extra feature
 # flags required.
-rusqlite = { version = "0.32", features = ["bundled"] }
+rusqlite = { version = "0.40", features = ["bundled"] }
 # `redis` for the optional multi-worker CCR backend. Cfg-gated behind
 # the `redis` feature so deploys that don't need it pay no compile
 # cost. Default features include the sync `Connection` API used in
@@ -196,7 +196,7 @@ redis = ["dep:redis"]
 
 [dev-dependencies]
 proptest = "1"
-criterion = { version = "0.5", features = ["html_reports"] }
+criterion = { version = "0.8", features = ["html_reports"] }
 tempfile = "3"
 
 [[bench]]
diff --git a/crates/headroom-core/src/lib.rs b/crates/headroom-core/src/lib.rs
index 8a907045a..a9417bd49 100644
--- a/crates/headroom-core/src/lib.rs
+++ b/crates/headroom-core/src/lib.rs
@@ -7,6 +7,7 @@ pub mod compression_policy;
 #[cfg(feature = "ml")]
 mod onnx_cpu;
 pub mod relevance;
+pub mod rollout;
 pub mod signals;
 pub mod tokenizer;
 pub mod transforms;
diff --git a/crates/headroom-core/src/rollout.rs b/crates/headroom-core/src/rollout.rs
new file mode 100644
index 000000000..fc9d4fb92
--- /dev/null
+++ b/crates/headroom-core/src/rollout.rs
@@ -0,0 +1,439 @@
+//! Deterministic runtime-rollout policy and provenance.
+//!
+//! Rollout channels control behavior in an already-built artifact. They do not
+//! select a package, release candidate, or distribution version. Composition
+//! roots resolve one immutable snapshot and inject its concrete decisions.
+
+use serde::Serialize;
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+use std::collections::BTreeSet;
+use std::str::FromStr;
+
+pub const ROLLOUT_SCHEMA_VERSION: u32 = 1;
+pub const ROLLOUT_POLICY_VERSION: &str = "1";
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RolloutChannel {
+    #[default]
+    Stable,
+    Beta,
+    Canary,
+    Dev,
+}
+
+impl RolloutChannel {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Stable => "stable",
+            Self::Beta => "beta",
+            Self::Canary => "canary",
+            Self::Dev => "dev",
+        }
+    }
+
+    pub fn allows(self, required: Self) -> bool {
+        self >= required
+    }
+}
+
+impl FromStr for RolloutChannel {
+    type Err = ();
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value.trim().to_ascii_lowercase().replace('-', "_").as_str() {
+            "" | "stable" | "prod" | "production" => Ok(Self::Stable),
+            "beta" | "preview" => Ok(Self::Beta),
+            "canary" | "nightly" => Ok(Self::Canary),
+            "dev" | "development" => Ok(Self::Dev),
+            _ => Err(()),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Feature {
+    NativeBedrock,
+    OpenAiResponsesStreaming,
+    CanaryProbe,
+}
+
+const ALL_FEATURES: [Feature; 3] = [
+    Feature::CanaryProbe,
+    Feature::NativeBedrock,
+    Feature::OpenAiResponsesStreaming,
+];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+pub struct FeatureSpec {
+    pub name: &'static str,
+    pub available_in: RolloutChannel,
+    pub default_enabled_in: Option<RolloutChannel>,
+}
+
+impl Feature {
+    pub fn spec(self) -> FeatureSpec {
+        match self {
+            Self::NativeBedrock => FeatureSpec {
+                name: "native_bedrock",
+                available_in: RolloutChannel::Stable,
+                default_enabled_in: Some(RolloutChannel::Stable),
+            },
+            Self::OpenAiResponsesStreaming => FeatureSpec {
+                name: "openai_responses_streaming",
+                available_in: RolloutChannel::Stable,
+                default_enabled_in: Some(RolloutChannel::Stable),
+            },
+            Self::CanaryProbe => FeatureSpec {
+                name: "canary_probe",
+                available_in: RolloutChannel::Canary,
+                default_enabled_in: None,
+            },
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FeatureDecisionReason {
+    Default,
+    Explicit,
+    LegacyAlias,
+    Disabled,
+    BlockedByChannel,
+    UnsafeOverride,
+    NotRequested,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct RolloutConfig {
+    pub channel: RolloutChannel,
+    pub requested: BTreeSet<String>,
+    pub disabled: BTreeSet<String>,
+    pub unsafe_allow_unstable: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct FeatureDecision {
+    pub name: &'static str,
+    pub available_in: RolloutChannel,
+    pub default_enabled_in: Option<RolloutChannel>,
+    pub requested: bool,
+    pub disabled: bool,
+    pub enabled: bool,
+    #[serde(rename = "decision")]
+    pub reason: FeatureDecisionReason,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RolloutSnapshot {
+    pub schema_version: u32,
+    pub policy_version: &'static str,
+    pub registry_digest: String,
+    pub config: RolloutConfig,
+    pub decisions: Vec<FeatureDecision>,
+}
+
+impl Default for RolloutSnapshot {
+    fn default() -> Self {
+        Self::from_parts("stable", "", "", false)
+    }
+}
+
+impl RolloutSnapshot {
+    pub fn from_parts(
+        channel: &str,
+        requested: &str,
+        disabled: &str,
+        unsafe_allow_unstable: bool,
+    ) -> Self {
+        Self::from_parts_with_explicit(channel, requested, disabled, unsafe_allow_unstable, &[])
+    }
+
+    pub fn from_parts_with_explicit(
+        channel: &str,
+        requested: &str,
+        disabled: &str,
+        unsafe_allow_unstable: bool,
+        explicit: &[Feature],
+    ) -> Self {
+        let parsed_channel = RolloutChannel::from_str(channel).unwrap_or_else(|_| {
+            tracing::warn!(channel, "unknown rollout channel; falling back to stable");
+            RolloutChannel::Stable
+        });
+        let valid_names: BTreeSet<_> = ALL_FEATURES
+            .iter()
+            .map(|feature| feature.spec().name.to_owned())
+            .collect();
+        let mut requested_names = validated_names(requested, "requested", &valid_names);
+        requested_names.extend(
+            explicit
+                .iter()
+                .map(|feature| feature.spec().name.to_owned()),
+        );
+        let disabled_names = validated_names(disabled, "disabled", &valid_names);
+        let config = RolloutConfig {
+            channel: parsed_channel,
+            requested: requested_names,
+            disabled: disabled_names,
+            unsafe_allow_unstable,
+        };
+        let decisions = ALL_FEATURES
+            .iter()
+            .map(|feature| resolve_feature(*feature, &config))
+            .collect();
+        Self {
+            schema_version: ROLLOUT_SCHEMA_VERSION,
+            policy_version: ROLLOUT_POLICY_VERSION,
+            registry_digest: registry_digest(),
+            config,
+            decisions,
+        }
+    }
+
+    pub fn decision(&self, feature: Feature) -> &FeatureDecision {
+        let name = feature.spec().name;
+        self.decisions
+            .iter()
+            .find(|decision| decision.name == name)
+            .expect("every registered feature has a decision")
+    }
+
+    pub fn is_enabled(&self, feature: Feature, _explicit: bool) -> bool {
+        self.decision(feature).enabled
+    }
+
+    pub fn enabled(&self) -> BTreeSet<String> {
+        self.decisions
+            .iter()
+            .filter(|decision| decision.enabled)
+            .map(|decision| decision.name.to_owned())
+            .collect()
+    }
+
+    pub fn qualification_eligible(&self) -> bool {
+        !self.config.unsafe_allow_unstable
+    }
+
+    fn canonical_value(&self) -> Value {
+        json!({
+            "schema_version": self.schema_version,
+            "policy_version": self.policy_version,
+            "channel": self.config.channel,
+            "unsafe_override": self.config.unsafe_allow_unstable,
+            "registry_digest": self.registry_digest,
+            "features": self.decisions,
+        })
+    }
+
+    pub fn snapshot_digest(&self) -> String {
+        digest_value(&self.canonical_value())
+    }
+
+    pub fn to_value(&self) -> Value {
+        let mut value = self.canonical_value();
+        let object = value
+            .as_object_mut()
+            .expect("rollout snapshot is an object");
+        object.insert("snapshot_digest".into(), json!(self.snapshot_digest()));
+        object.insert(
+            "qualification_eligible".into(),
+            json!(self.qualification_eligible()),
+        );
+        if !self.qualification_eligible() {
+            object.insert(
+                "qualification_ineligible_reason".into(),
+                json!("unsafe_rollout_override_active"),
+            );
+        }
+        value
+    }
+}
+
+fn resolve_feature(feature: Feature, config: &RolloutConfig) -> FeatureDecision {
+    let spec = feature.spec();
+    let requested = config.requested.contains(spec.name);
+    let disabled = config.disabled.contains(spec.name);
+    let normally_available = config.channel.allows(spec.available_in);
+    let (enabled, reason) = if disabled {
+        (false, FeatureDecisionReason::Disabled)
+    } else if requested && !normally_available && !config.unsafe_allow_unstable {
+        (false, FeatureDecisionReason::BlockedByChannel)
+    } else if requested && !normally_available {
+        (true, FeatureDecisionReason::UnsafeOverride)
+    } else if requested {
+        (true, FeatureDecisionReason::Explicit)
+    } else if spec
+        .default_enabled_in
+        .is_some_and(|minimum| config.channel.allows(minimum))
+    {
+        (true, FeatureDecisionReason::Default)
+    } else {
+        (false, FeatureDecisionReason::NotRequested)
+    };
+    FeatureDecision {
+        name: spec.name,
+        available_in: spec.available_in,
+        default_enabled_in: spec.default_enabled_in,
+        requested,
+        disabled,
+        enabled,
+        reason,
+    }
+}
+
+fn validated_names(raw: &str, source: &str, valid: &BTreeSet<String>) -> BTreeSet<String> {
+    let names: BTreeSet<_> = split_feature_names(raw).into_iter().collect();
+    for unknown in names.difference(valid) {
+        tracing::warn!(
+            feature = unknown,
+            source,
+            "unknown rollout feature; ignoring (fail-closed)"
+        );
+    }
+    names.intersection(valid).cloned().collect()
+}
+
+pub fn split_feature_names(raw: &str) -> Vec<String> {
+    raw.replace(';', ",")
+        .split(',')
+        .filter_map(|part| {
+            let normalized = normalize_feature_name(part);
+            (!normalized.is_empty()).then_some(normalized)
+        })
+        .collect()
+}
+
+pub fn normalize_feature_name(raw: impl AsRef<str>) -> String {
+    raw.as_ref().trim().to_ascii_lowercase().replace('-', "_")
+}
+
+pub fn registry_digest() -> String {
+    let registry: Vec<_> = ALL_FEATURES.iter().map(|feature| feature.spec()).collect();
+    digest_value(&serde_json::to_value(registry).expect("registry is serializable"))
+}
+
+pub fn feature_names() -> BTreeSet<&'static str> {
+    ALL_FEATURES
+        .iter()
+        .map(|feature| feature.spec().name)
+        .collect()
+}
+
+fn digest_value(value: &Value) -> String {
+    let canonical = serde_json::to_vec(value).expect("rollout provenance is serializable");
+    format!("sha256:{:x}", Sha256::digest(canonical))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Deserialize;
+
+    #[derive(Deserialize)]
+    struct PolicyVector {
+        channel: String,
+        requested: bool,
+        disabled: bool,
+        #[serde(rename = "unsafe")]
+        unsafe_override: bool,
+        enabled: bool,
+        decision: String,
+    }
+
+    #[test]
+    fn channel_order_matches_python_policy() {
+        assert!(RolloutChannel::Dev.allows(RolloutChannel::Canary));
+        assert!(RolloutChannel::Canary.allows(RolloutChannel::Beta));
+        assert!(!RolloutChannel::Stable.allows(RolloutChannel::Canary));
+    }
+
+    #[test]
+    fn stable_blocks_explicit_canary_feature_with_reason() {
+        let rollout = RolloutSnapshot::from_parts("stable", "canary_probe", "", false);
+        let decision = rollout.decision(Feature::CanaryProbe);
+        assert!(!decision.enabled);
+        assert_eq!(decision.reason, FeatureDecisionReason::BlockedByChannel);
+    }
+
+    #[test]
+    fn default_enabled_feature_has_default_reason() {
+        let rollout = RolloutSnapshot::default();
+        let decision = rollout.decision(Feature::NativeBedrock);
+        assert!(decision.enabled);
+        assert_eq!(decision.reason, FeatureDecisionReason::Default);
+    }
+
+    #[test]
+    fn unsafe_override_crosses_boundary_and_is_ineligible() {
+        let rollout = RolloutSnapshot::from_parts("stable", "canary_probe", "", true);
+        assert_eq!(
+            rollout.decision(Feature::CanaryProbe).reason,
+            FeatureDecisionReason::UnsafeOverride
+        );
+        assert!(!rollout.qualification_eligible());
+        assert_eq!(
+            rollout.to_value()["qualification_ineligible_reason"],
+            "unsafe_rollout_override_active"
+        );
+    }
+
+    #[test]
+    fn disable_beats_default_explicit_and_unsafe() {
+        for unsafe_override in [false, true] {
+            let rollout = RolloutSnapshot::from_parts(
+                "stable",
+                "native_bedrock",
+                "native-bedrock",
+                unsafe_override,
+            );
+            assert_eq!(
+                rollout.decision(Feature::NativeBedrock).reason,
+                FeatureDecisionReason::Disabled
+            );
+        }
+    }
+
+    #[test]
+    fn provenance_digests_are_deterministic_and_policy_sensitive() {
+        let first = RolloutSnapshot::from_parts("canary", "canary_probe", "", false);
+        let second = RolloutSnapshot::from_parts("canary", "canary_probe", "", false);
+        let changed = RolloutSnapshot::from_parts("stable", "canary_probe", "", false);
+        assert_eq!(first.registry_digest, second.registry_digest);
+        assert_eq!(first.snapshot_digest(), second.snapshot_digest());
+        assert_ne!(first.snapshot_digest(), changed.snapshot_digest());
+    }
+
+    #[test]
+    fn invalid_inputs_fail_closed() {
+        let rollout = RolloutSnapshot::from_parts("stabel", "unknown", "unknown", false);
+        assert_eq!(rollout.config.channel, RolloutChannel::Stable);
+        assert!(rollout.config.requested.is_empty());
+        assert!(rollout.config.disabled.is_empty());
+    }
+
+    #[test]
+    fn shared_python_rust_policy_vectors() {
+        let vectors: Vec<PolicyVector> = serde_json::from_str(include_str!(
+            "../../../tests/fixtures/rollout_policy_vectors.json"
+        ))
+        .unwrap();
+        for vector in vectors {
+            let requested = if vector.requested { "canary_probe" } else { "" };
+            let disabled = if vector.disabled { "canary_probe" } else { "" };
+            let rollout = RolloutSnapshot::from_parts(
+                &vector.channel,
+                requested,
+                disabled,
+                vector.unsafe_override,
+            );
+            let decision = rollout.decision(Feature::CanaryProbe);
+            assert_eq!(decision.enabled, vector.enabled);
+            assert_eq!(
+                serde_json::to_value(decision.reason).unwrap(),
+                vector.decision
+            );
+        }
+    }
+}
diff --git a/crates/headroom-core/src/tokenizer/estimator.rs b/crates/headroom-core/src/tokenizer/estimator.rs
index 5dde222d3..818077be0 100644
--- a/crates/headroom-core/src/tokenizer/estimator.rs
+++ b/crates/headroom-core/src/tokenizer/estimator.rs
@@ -1,12 +1,35 @@
 //! Character-density estimator. Used as a fallback for any tokenizer family
 //! we haven't wired in yet (Anthropic Claude, Google Gemini, Cohere, …).
 //!
-//! Mirrors `headroom.tokenizers.estimator.EstimatingTokenCounter`. The formula
-//! is `ceil(chars / chars_per_token)`. `chars` is *Unicode scalar count*, not
-//! byte length, to match Python's `len(text)` semantics on str.
+//! Mirrors `headroom.tokenizers.estimator.EstimatingTokenCounter`. Latin chars
+//! are priced at `chars_per_token`; dense scripts (CJK / Kana / Hangul / full-
+//! width) are priced separately at `CHARS_PER_TOKEN_CJK`, since they tokenize at
+//! ~1 token/char and the Latin ratio under-counts them 2-4x. `chars` is a
+//! *Unicode scalar count*, not byte length, to match Python's `len(text)`.
 
 use super::{Backend, Tokenizer};
 
+/// Chars-per-token for dense scripts. Byte-identical with Python
+/// `EstimatingTokenCounter.CHARS_PER_TOKEN_CJK`.
+const CHARS_PER_TOKEN_CJK: f64 = 1.5;
+
+/// True for a "dense-script" codepoint (CJK ideographs + punctuation, Kana,
+/// Hangul, CJK compatibility, half/full-width forms, CJK Ext-A/B). Ranges kept
+/// byte-identical with Python `EstimatingTokenCounter.CJK_PATTERN`.
+fn is_dense_script(c: char) -> bool {
+    matches!(
+        c as u32,
+        0x3000..=0x303F         // CJK symbols and punctuation
+            | 0x3040..=0x30FF   // Hiragana + Katakana
+            | 0x3400..=0x4DBF   // CJK Unified Ideographs Ext A
+            | 0x4E00..=0x9FFF   // CJK Unified Ideographs
+            | 0xAC00..=0xD7AF   // Hangul syllables
+            | 0xF900..=0xFAFF   // CJK compatibility ideographs
+            | 0xFF00..=0xFFEF   // Half/full-width forms
+            | 0x20000..=0x2A6DF // CJK Unified Ideographs Ext B
+    )
+}
+
 #[derive(Debug, Clone, Copy)]
 pub struct EstimatingCounter {
     chars_per_token: f64,
@@ -42,15 +65,15 @@ impl Tokenizer for EstimatingCounter {
         if text.is_empty() {
             return 0;
         }
-        // Match Python `EstimatingTokenCounter.count_text`:
-        //     max(1, int(len(text) / chars_per_token + 0.5))
-        // Python `int()` truncates toward zero; for non-negative inputs that's
-        // identical to `as usize` saturating-cast semantics in Rust >= 1.45.
-        // Adding 0.5 then truncating yields round-half-up. We previously used
-        // ceil, which over-counted in the middle of the range (e.g. "aaaaa"
-        // at 4.0 cpt returned 2 here vs 1 in Python).
-        let chars = text.chars().count() as f64;
-        let raw = (chars / self.chars_per_token + 0.5) as usize;
+        // Match Python `EstimatingTokenCounter.count_text` (fixed-ratio path):
+        //     cjk = count_dense_script(text); other = len(text) - cjk
+        //     max(1, int(other / chars_per_token + cjk / CHARS_PER_TOKEN_CJK + 0.5))
+        // Dense scripts tokenize at ~1 token/char, so the Latin `chars_per_token`
+        // under-counts them; price them separately. `int()` truncates toward
+        // zero (== `as usize` for non-negative); the `+ 0.5` gives round-half-up.
+        let cjk = text.chars().filter(|&c| is_dense_script(c)).count();
+        let other = (text.chars().count() - cjk) as f64;
+        let raw = (other / self.chars_per_token + cjk as f64 / CHARS_PER_TOKEN_CJK + 0.5) as usize;
         raw.max(1)
     }
 
@@ -104,6 +127,27 @@ mod tests {
         assert_eq!(est.count_text("🦀🦀🦀🦀"), 1);
     }
 
+    #[test]
+    fn dense_scripts_priced_at_cjk_ratio() {
+        let est = EstimatingCounter::default(); // 4.0 for Latin
+                                                // Pure CJK: cjk=3, other=0 -> 0/4 + 3/1.5 + 0.5 = 2.5 -> int -> 2
+        assert_eq!(est.count_text("数据库"), 2);
+        // 7 CJK -> 7/1.5 + 0.5 = 5.16 -> 5 (the old flat 7/4 -> 2 under-counted ~2.5x)
+        assert_eq!(est.count_text("数据库连接失败"), 5);
+        // Kana is dense: 3 hiragana -> 3/1.5 + 0.5 = 2.5 -> 2
+        assert_eq!(est.count_text("ひらが"), 2);
+        // Full-width Latin is dense (U+FF00-FFEF): ＡＰＩ -> 2, vs plain "API" -> 1
+        assert_eq!(est.count_text("ＡＰＩ"), 2);
+        assert_eq!(est.count_text("API"), 1);
+    }
+
+    #[test]
+    fn mixed_ascii_and_cjk_prices_each_separately() {
+        let est = EstimatingCounter::default();
+        // "api数据": other=3, cjk=2 -> 3/4 + 2/1.5 + 0.5 = 0.75+1.33+0.5 = 2.58 -> 2
+        assert_eq!(est.count_text("api数据"), 2);
+    }
+
     #[test]
     fn min_is_one_for_non_empty_input() {
         let est = EstimatingCounter::default();
diff --git a/crates/headroom-proxy/Cargo.toml b/crates/headroom-proxy/Cargo.toml
index 898645e9d..b1f5088f1 100644
--- a/crates/headroom-proxy/Cargo.toml
+++ b/crates/headroom-proxy/Cargo.toml
@@ -23,7 +23,7 @@ tower-http = { version = "0.7", features = ["trace", "request-id", "util"] }
 tracing = { workspace = true }
 tracing-subscriber = { version = "0.3", features = ["json", "env-filter", "fmt"] }
 reqwest = { version = "0.12", default-features = false, features = ["stream", "rustls-tls", "http2"] }
-tokio-tungstenite = { version = "0.24", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
+tokio-tungstenite = { version = "0.30", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
 clap = { workspace = true, features = ["derive", "env"] }
 serde = { workspace = true }
 serde_json = { workspace = true }
@@ -38,7 +38,7 @@ http-body-util = "0.1"
 hyper = "1"
 url = "2"
 humantime = "2"
-bytesize = "1"
+bytesize = "2"
 tokio-util = { version = "0.7" }
 headroom-core = { path = "../headroom-core" }
 # Phase D PR-D1: native Bedrock InvokeModel route. SigV4 + AWS
@@ -98,7 +98,7 @@ md-5 = "0.10"
 tower = { workspace = true, features = ["util"] }
 wiremock = "0.6"
 reqwest = { version = "0.12", default-features = false, features = ["stream", "rustls-tls", "http2", "json"] }
-tokio-tungstenite = { version = "0.24", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
+tokio-tungstenite = { version = "0.30", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
 futures-util = "0.3"
 tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal", "net", "io-util", "time", "test-util", "process"] }
 hyper = { version = "1", features = ["server", "http1", "http2"] }
diff --git a/crates/headroom-proxy/src/bedrock/invoke.rs b/crates/headroom-proxy/src/bedrock/invoke.rs
index 2571e8bcb..a30e0027a 100644
--- a/crates/headroom-proxy/src/bedrock/invoke.rs
+++ b/crates/headroom-proxy/src/bedrock/invoke.rs
@@ -615,6 +615,7 @@ mod tests {
             client: reqwest::Client::new(),
             bedrock_credentials: None,
             drift_state: crate::cache_stabilization::drift_detector::DriftState::new(8),
+            beta_sticky: crate::cache_stabilization::beta_sticky::BetaStickyState::new(8),
             vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
                 "test".to_string(),
             )),
@@ -649,6 +650,7 @@ mod tests {
             // unit test never observes drift, but `AppState` requires
             // the field to be populated.
             drift_state: crate::cache_stabilization::drift_detector::DriftState::new(8),
+            beta_sticky: crate::cache_stabilization::beta_sticky::BetaStickyState::new(8),
             // PR-D4: unit tests for the Bedrock URL builder don't
             // touch the Vertex route, but `AppState` is one struct
             // — supply a dummy token source so the test compiles.
@@ -684,6 +686,7 @@ mod tests {
             // PR-E6: see above — drift detector is unused by this
             // test; we just satisfy the struct shape.
             drift_state: crate::cache_stabilization::drift_detector::DriftState::new(8),
+            beta_sticky: crate::cache_stabilization::beta_sticky::BetaStickyState::new(8),
             // PR-D4: unit tests for the Bedrock URL builder don't
             // touch the Vertex route, but `AppState` is one struct
             // — supply a dummy token source so the test compiles.
diff --git a/crates/headroom-proxy/src/bedrock/invoke_streaming.rs b/crates/headroom-proxy/src/bedrock/invoke_streaming.rs
index ce66429f9..62501003c 100644
--- a/crates/headroom-proxy/src/bedrock/invoke_streaming.rs
+++ b/crates/headroom-proxy/src/bedrock/invoke_streaming.rs
@@ -1014,6 +1014,7 @@ mod tests {
             // PR-E6: drift detector is unused by this URL-builder
             // unit test; small capacity to satisfy the struct shape.
             drift_state: crate::cache_stabilization::drift_detector::DriftState::new(8),
+            beta_sticky: crate::cache_stabilization::beta_sticky::BetaStickyState::new(8),
             // PR-D4: unit tests for the Bedrock URL builder don't
             // touch the Vertex route, but `AppState` is one struct
             // — supply a dummy token source so the test compiles.
@@ -1056,6 +1057,7 @@ mod tests {
             client: reqwest::Client::new(),
             bedrock_credentials: None,
             drift_state: crate::cache_stabilization::drift_detector::DriftState::new(8),
+            beta_sticky: crate::cache_stabilization::beta_sticky::BetaStickyState::new(8),
             vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
                 "test".to_string(),
             )),
diff --git a/crates/headroom-proxy/src/cache_stabilization/beta_sticky.rs b/crates/headroom-proxy/src/cache_stabilization/beta_sticky.rs
new file mode 100644
index 000000000..a8db6a5bc
--- /dev/null
+++ b/crates/headroom-proxy/src/cache_stabilization/beta_sticky.rs
@@ -0,0 +1,620 @@
+//! Session-sticky provider beta headers — Rust port of the Python
+//! proxy's `SessionBetaTracker` (PR-A6, `headroom/proxy/helpers.py`).
+//!
+//! ## Why
+//!
+//! Provider beta headers (`anthropic-beta`, `openai-beta`) are part of
+//! the request bytes that determine the upstream prefix-cache key.
+//! Interactive clients (Claude Code, Codex CLI) MAY drop a beta token
+//! between turn N and turn N+1 of the same conversation; the cache hot
+//! zone is positional, so the next turn's prefix hashes differently and
+//! the prefix-cache read misses — the customer silently pays for a full
+//! prompt re-write. The Python proxy defeats this with a bounded LRU
+//! tracker that unions the client's tokens with every token previously
+//! seen for the same `(provider, session)` and forwards the union.
+//!
+//! The Rust proxy replaces the Python request path in Phase H, which
+//! deletes `SessionBetaTracker` with the rest of
+//! `headroom/proxy/helpers.py`. Without this port the protection —
+//! and its documented operator contract
+//! (`docs/content/docs/configuration.mdx`, "Session Beta Header
+//! Tracking") — would silently not survive the migration.
+//!
+//! ## Behaviour contract (parity with Python)
+//!
+//! - Union client tokens with previously-seen tokens for the session,
+//!   preserving first-seen order; case-insensitive dedup where the
+//!   first-seen casing wins.
+//! - Keyed by `(provider, session)` so the same session id against
+//!   Anthropic and OpenAI upstreams keeps independent token sets.
+//! - Bounded LRU (`BETA_TRACKER_CAPACITY` sessions): lookups touch
+//!   recency, overflow evicts the oldest session.
+//! - The tracker only ever records tokens the client itself sent.
+//!   Headroom-added tokens (e.g. memory-tool betas on the Python
+//!   path) are NOT recorded — the forwarded union is always a subset
+//!   of values this client already put on the wire, which is what
+//!   keeps the mechanism consistent with the subscription-stealth
+//!   invariant (REALIGNMENT invariant #10: "no beta drift").
+//!
+//! The operator opt-out lives at the call site: when
+//! `Config::beta_header_sticky` is `disabled` the proxy skips the
+//! tracker entirely and forwards the client header verbatim (the
+//! Python proxy's `HEADROOM_BETA_HEADER_STICKY=disabled` diagnostic
+//! mode). That gate is per REALIGNMENT build constraint #4 an explicit
+//! loud opt-in, not a silent fallback.
+//!
+//! Session identity comes from
+//! [`super::drift_detector::derive_session_key`] — the same
+//! conversation-aware key the drift detector uses (explicit
+//! `x-headroom-session-id` when the client declares it, otherwise
+//! credential/IP arms folded with a first-message conversation
+//! discriminator).
+//!
+//! ## Divergence from Python: per-conversation, not per-(model, system)
+//!
+//! The Python tracker keys on the store session id — explicit header,
+//! else a hash of `(model, leading system prompt)` — so all parallel
+//! conversations sharing a model + system prompt (a Claude Code
+//! session and every one of its subagents) share ONE token union and
+//! cross-inherit each other's tokens. This port keys on the drift
+//! detector's conversation-aware key instead, so each conversation
+//! keeps its own union; the integration test
+//! `separate_conversations_do_not_leak_tokens` pins that. Deliberate:
+//! the `(model, system)` bucket conflating parallel agentic
+//! conversations is the exact defect #2085 / #2193 / #2301 chased out
+//! of the other session-sticky subsystems. The cost is losing
+//! Python's accidental cross-conversation repair (conversation B
+//! turn 1 inheriting a token only conversation A ever sent); each
+//! conversation's stickiness now starts from its own first sighting,
+//! which is also the only variant that can't leak one tenant-visible
+//! experiment token into an unrelated conversation's request bytes.
+
+use std::collections::HashSet;
+use std::num::NonZeroUsize;
+use std::sync::{Arc, Mutex};
+
+use http::header::{HeaderMap, HeaderValue};
+use lru::LruCache;
+
+use super::drift_detector::session_key_log_prefix;
+
+/// Maximum number of `(provider, session)` entries tracked. Sessions
+/// are keyed per conversation (see module docs), so the working set is
+/// the number of concurrently active conversations — same sizing
+/// rationale as the drift detector's capacity. Eviction cost is
+/// re-learning a live session's dropped tokens from scratch (the next
+/// turn forwards the client value verbatim), not a lost request.
+pub const BETA_TRACKER_CAPACITY: usize = 1000;
+
+/// Upstream namespace for a tracked beta-token set. Mirrors the
+/// Python tracker's `provider` string key ("anthropic" / "openai").
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum BetaProvider {
+    /// `/v1/messages` — `anthropic-beta` header.
+    Anthropic,
+    /// `/v1/chat/completions` and `/v1/responses` — `openai-beta`
+    /// header. One namespace for both endpoints, matching the Python
+    /// proxy's single `provider="openai"` key.
+    OpenAi,
+}
+
+impl BetaProvider {
+    /// Stable lower-case label for log fields; matches the Python
+    /// tracker's provider strings.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            BetaProvider::Anthropic => "anthropic",
+            BetaProvider::OpenAi => "openai",
+        }
+    }
+
+    /// The request header this provider's beta tokens travel in.
+    pub fn header_name(self) -> &'static str {
+        match self {
+            BetaProvider::Anthropic => "anthropic-beta",
+            BetaProvider::OpenAi => "openai-beta",
+        }
+    }
+}
+
+/// Split a comma-separated beta-header value into trimmed, non-empty
+/// tokens. Port of the Python `split_beta_tokens` helper.
+pub fn split_beta_tokens(value: Option<&str>) -> Vec<String> {
+    value
+        .unwrap_or("")
+        .split(',')
+        .map(str::trim)
+        .filter(|t| !t.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+/// Per-session ordered token lists, keyed by `(provider, session)`.
+type SessionTokenCache = LruCache<(BetaProvider, String), Vec<String>>;
+
+/// Bounded LRU of beta tokens observed per `(provider, session)`.
+///
+/// Cloning shares the underlying map (`Arc`), mirroring
+/// [`super::drift_detector::DriftState`] so one instance lives in
+/// `AppState` and clones freely into every handler path.
+#[derive(Clone)]
+pub struct BetaStickyState {
+    sessions: Arc<Mutex<SessionTokenCache>>,
+}
+
+impl BetaStickyState {
+    /// Create a tracker bounded to `capacity` sessions.
+    ///
+    /// # Panics
+    ///
+    /// Panics when `capacity == 0`, mirroring `DriftState::new` (the
+    /// Python tracker raises `ValueError` on a non-positive bound).
+    pub fn new(capacity: usize) -> Self {
+        let cap = NonZeroUsize::new(capacity).expect("BetaStickyState capacity must be > 0");
+        Self {
+            sessions: Arc::new(Mutex::new(LruCache::new(cap))),
+        }
+    }
+
+    /// Union `client_value`'s tokens with the session's previously
+    /// seen tokens, update the session, and return the merged
+    /// comma-separated value (possibly empty). Port of the Python
+    /// `SessionBetaTracker.record_and_get_sticky_betas`.
+    ///
+    /// On a poisoned lock the tracker fails open: the client value is
+    /// returned verbatim (trimmed) and state is left untouched —
+    /// never drop or delay the request for a telemetry-adjacent
+    /// protection.
+    pub fn record_and_get_sticky_betas(
+        &self,
+        provider: BetaProvider,
+        session_key: &str,
+        client_value: Option<&str>,
+    ) -> String {
+        let client_tokens = split_beta_tokens(client_value);
+
+        let mut sessions = match self.sessions.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => {
+                tracing::warn!(
+                    event = "beta_sticky_lock_poisoned",
+                    provider = provider.as_str(),
+                    "beta tracker lock poisoned; forwarding client value verbatim"
+                );
+                drop(poisoned);
+                return client_tokens.join(",");
+            }
+        };
+
+        let key = (provider, session_key.to_string());
+        // `get_mut` touches LRU recency on hit, mirroring the Python
+        // tracker's move-to-end.
+        if let Some(merged) = sessions.get_mut(&key) {
+            // Dedup is case-insensitive with the first-seen casing
+            // winning. Header values reaching this point are visible
+            // ASCII (`HeaderValue::to_str` rejects anything else), so
+            // ASCII lowercasing matches Python's `str.lower()` over
+            // the reachable domain.
+            let mut seen: HashSet<String> = merged.iter().map(|t| t.to_ascii_lowercase()).collect();
+            for token in client_tokens {
+                if seen.insert(token.to_ascii_lowercase()) {
+                    merged.push(token);
+                }
+            }
+            return merged.join(",");
+        }
+
+        let mut merged: Vec<String> = Vec::with_capacity(client_tokens.len());
+        let mut seen: HashSet<String> = HashSet::with_capacity(client_tokens.len());
+        for token in client_tokens {
+            if seen.insert(token.to_ascii_lowercase()) {
+                merged.push(token);
+            }
+        }
+        let joined = merged.join(",");
+        // `put` on a fresh key evicts the oldest entry once the cache
+        // is at capacity — the Python tracker's bounded-LRU overflow
+        // pop. Sessions that never sent a beta token still occupy a
+        // slot (Python stores their empty list too); the cost is one
+        // LRU entry, the benefit is identical recency behaviour.
+        sessions.put(key, merged);
+        joined
+    }
+
+    /// Number of tracked sessions (test observability).
+    #[cfg(test)]
+    fn active_sessions(&self) -> usize {
+        self.sessions.lock().map(|c| c.len()).unwrap_or(0)
+    }
+}
+
+/// Count tokens in a raw header value without allocating a `Vec`
+/// (log-field helper; same tokenization as [`split_beta_tokens`]).
+fn count_beta_tokens(value: Option<&str>) -> usize {
+    value
+        .unwrap_or("")
+        .split(',')
+        .filter(|t| !t.trim().is_empty())
+        .count()
+}
+
+/// Record the client's beta header for this `(provider, session)` and
+/// rewrite the upstream-bound header to the session union when they
+/// differ. The full merge site: reads `provider.header_name()` from
+/// `outgoing_headers`, unions via the tracker, mutates the map in
+/// place. Mirrors the Python handler block (anthropic.py PR-A6):
+/// rewrite only when the union is non-empty and differs from the
+/// client value; an absent client header gains the union; a session
+/// with no tokens anywhere stays header-less.
+///
+/// Fail-open contract: a client value that isn't visible ASCII is
+/// forwarded verbatim and nothing is recorded (never rewrite what we
+/// can't faithfully parse); an unencodable union (unreachable — every
+/// token came from a parsed header value) logs and forwards verbatim.
+///
+/// Logging: counts only — beta tokens can carry experiment IDs the
+/// user hasn't opted to share with Headroom logs (Python
+/// `log_beta_header_merge` contract). Python logs every merge at
+/// info; here the no-op case drops to debug, matching the drift
+/// detector's silent-on-stable precedent, so an info-level
+/// `beta_header_merge` always marks an actual cache-affecting
+/// rewrite.
+pub fn apply_sticky_betas(
+    tracker: &BetaStickyState,
+    provider: BetaProvider,
+    session_key: &str,
+    outgoing_headers: &mut HeaderMap,
+    request_id: &str,
+) {
+    let header_name = provider.header_name();
+    // Join repeated field lines with "," per RFC 9110 §5.3 list
+    // semantics BEFORE recording, so a client sending two beta lines
+    // has both recorded and a later rewrite (which `insert`s a single
+    // line, dropping the others) can never shrink the upstream token
+    // set mid-conversation.
+    let mut parts: Vec<&str> = Vec::new();
+    for raw in outgoing_headers.get_all(header_name) {
+        match raw.to_str() {
+            Ok(s) => parts.push(s),
+            Err(_) => {
+                tracing::debug!(
+                    event = "beta_header_merge_skipped",
+                    request_id = %request_id,
+                    provider = provider.as_str(),
+                    reason = "non_ascii_header_value",
+                    "client beta header is not visible ASCII; forwarding verbatim"
+                );
+                return;
+            }
+        }
+    }
+    let client_value: Option<String> = if parts.is_empty() {
+        None
+    } else {
+        Some(parts.join(","))
+    };
+
+    let sticky =
+        tracker.record_and_get_sticky_betas(provider, session_key, client_value.as_deref());
+    let rewritten = !sticky.is_empty() && sticky != client_value.as_deref().unwrap_or("");
+    if rewritten {
+        match HeaderValue::from_str(&sticky) {
+            Ok(value) => {
+                outgoing_headers.insert(header_name, value);
+            }
+            Err(error) => {
+                tracing::warn!(
+                    event = "beta_header_merge_skipped",
+                    request_id = %request_id,
+                    provider = provider.as_str(),
+                    reason = "unencodable_union",
+                    error = %error,
+                    "sticky beta union not encodable as a header value"
+                );
+                return;
+            }
+        }
+    }
+
+    let client_betas = count_beta_tokens(client_value.as_deref());
+    let sticky_betas = count_beta_tokens(Some(&sticky));
+    if rewritten {
+        tracing::info!(
+            event = "beta_header_merge",
+            request_id = %request_id,
+            provider = provider.as_str(),
+            session_key_hash = %session_key_log_prefix(session_key),
+            client_betas,
+            sticky_betas,
+            "session-sticky beta merge rewrote the upstream header"
+        );
+    } else {
+        tracing::debug!(
+            event = "beta_header_merge",
+            request_id = %request_id,
+            provider = provider.as_str(),
+            session_key_hash = %session_key_log_prefix(session_key),
+            client_betas,
+            sticky_betas,
+            "session-sticky beta merge (no-op)"
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // -----------------------------------------------------------------
+    // split_beta_tokens — port of the Python tokenizer contract.
+    // -----------------------------------------------------------------
+
+    #[test]
+    fn split_none_and_empty_yield_no_tokens() {
+        assert!(split_beta_tokens(None).is_empty());
+        assert!(split_beta_tokens(Some("")).is_empty());
+        assert!(split_beta_tokens(Some("   ")).is_empty());
+        assert!(split_beta_tokens(Some(",, ,")).is_empty());
+    }
+
+    #[test]
+    fn split_trims_and_drops_empty_segments() {
+        assert_eq!(
+            split_beta_tokens(Some(" a , ,b,  c-1 ")),
+            vec!["a".to_string(), "b".to_string(), "c-1".to_string()]
+        );
+    }
+
+    // -----------------------------------------------------------------
+    // record_and_get_sticky_betas — tracker semantics ported from
+    // tests/test_anthropic_beta_session_sticky.py.
+    // -----------------------------------------------------------------
+
+    fn tracker() -> BetaStickyState {
+        BetaStickyState::new(BETA_TRACKER_CAPACITY)
+    }
+
+    #[test]
+    fn first_request_returns_client_tokens() {
+        let t = tracker();
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a,b"));
+        assert_eq!(got, "a,b");
+    }
+
+    #[test]
+    fn dropped_token_is_reinjected_on_next_turn() {
+        // The cache-killer this module exists for: turn N sends
+        // "a,b", turn N+1 drops "b" — the union must restore it.
+        let t = tracker();
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a,b"));
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a"));
+        assert_eq!(got, "a,b");
+    }
+
+    #[test]
+    fn union_preserves_first_seen_order() {
+        let t = tracker();
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("b,a"));
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a,c"));
+        assert_eq!(got, "b,a,c");
+    }
+
+    #[test]
+    fn dedup_is_case_insensitive_first_casing_wins() {
+        let t = tracker();
+        t.record_and_get_sticky_betas(
+            BetaProvider::Anthropic,
+            "s1",
+            Some("Context-Management-2025-06-27"),
+        );
+        let got = t.record_and_get_sticky_betas(
+            BetaProvider::Anthropic,
+            "s1",
+            Some("context-management-2025-06-27"),
+        );
+        assert_eq!(got, "Context-Management-2025-06-27");
+    }
+
+    #[test]
+    fn duplicate_client_tokens_are_deduped() {
+        let t = tracker();
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a,a,b,A"));
+        assert_eq!(got, "a,b");
+    }
+
+    #[test]
+    fn client_whitespace_is_trimmed_in_union() {
+        let t = tracker();
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some(" a , b "));
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("c "));
+        assert_eq!(got, "a,b,c");
+    }
+
+    #[test]
+    fn absent_client_value_returns_session_union() {
+        let t = tracker();
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a"));
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", None);
+        assert_eq!(got, "a");
+    }
+
+    #[test]
+    fn empty_session_and_client_yield_empty_string() {
+        let t = tracker();
+        assert_eq!(
+            t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", None),
+            ""
+        );
+    }
+
+    #[test]
+    fn providers_keep_independent_namespaces() {
+        // Same session id, different providers — token sets must not
+        // leak across (Python: the (provider, session_id) tuple key).
+        let t = tracker();
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("anth-only"));
+        let got = t.record_and_get_sticky_betas(BetaProvider::OpenAi, "s1", Some("oai-only"));
+        assert_eq!(got, "oai-only");
+    }
+
+    #[test]
+    fn sessions_keep_independent_token_sets() {
+        let t = tracker();
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a"));
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s2", Some("b"));
+        assert_eq!(got, "b");
+    }
+
+    #[test]
+    fn lru_evicts_oldest_session_at_capacity() {
+        let t = BetaStickyState::new(2);
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a"));
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s2", Some("b"));
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s3", Some("c"));
+        assert_eq!(t.active_sessions(), 2);
+        // s1 was evicted: its history is gone, so a bare re-request
+        // returns only the fresh client value.
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("z"));
+        assert_eq!(got, "z");
+    }
+
+    #[test]
+    fn lru_hit_touches_recency() {
+        let t = BetaStickyState::new(2);
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("a"));
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s2", Some("b"));
+        // Touch s1 so s2 becomes the eviction candidate.
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", None);
+        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s3", Some("c"));
+        // s1 survived the s3 insert…
+        assert_eq!(
+            t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", None),
+            "a"
+        );
+        // …and s2 did not.
+        assert_eq!(
+            t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s2", None),
+            ""
+        );
+    }
+
+    // -----------------------------------------------------------------
+    // apply_sticky_betas — header-map plumbing.
+    // -----------------------------------------------------------------
+
+    fn header_map(values: &[&str]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for v in values {
+            map.append("anthropic-beta", HeaderValue::from_str(v).unwrap());
+        }
+        map
+    }
+
+    fn beta_values(map: &HeaderMap) -> Vec<String> {
+        map.get_all("anthropic-beta")
+            .iter()
+            .map(|v| v.to_str().unwrap().to_string())
+            .collect()
+    }
+
+    #[test]
+    fn apply_rewrites_dropped_token_to_union() {
+        let t = tracker();
+        let mut turn1 = header_map(&["a,b"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut turn1, "req-1");
+        assert_eq!(beta_values(&turn1), vec!["a,b"]);
+
+        let mut turn2 = header_map(&["a"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut turn2, "req-2");
+        assert_eq!(beta_values(&turn2), vec!["a,b"]);
+    }
+
+    #[test]
+    fn apply_reinserts_union_when_header_fully_omitted() {
+        let t = tracker();
+        let mut turn1 = header_map(&["a,b"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut turn1, "req-1");
+
+        let mut turn2 = HeaderMap::new();
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut turn2, "req-2");
+        assert_eq!(beta_values(&turn2), vec!["a,b"]);
+    }
+
+    #[test]
+    fn apply_never_invents_a_header() {
+        let t = tracker();
+        let mut map = HeaderMap::new();
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut map, "req-1");
+        assert!(map.get("anthropic-beta").is_none());
+    }
+
+    #[test]
+    fn apply_noop_leaves_header_lines_untouched() {
+        let t = tracker();
+        let mut map = header_map(&["a,b"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut map, "req-1");
+        let mut again = header_map(&["a,b"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut again, "req-2");
+        assert_eq!(beta_values(&again), vec!["a,b"]);
+    }
+
+    #[test]
+    fn apply_records_all_repeated_header_lines() {
+        // RFC 9110 list semantics: two field lines are one list. The
+        // union must record BOTH lines, so a later rewrite (which
+        // collapses to a single line) can never shrink the upstream
+        // token set mid-conversation.
+        let t = tracker();
+        let mut turn1 = header_map(&["a,x", "b"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut turn1, "req-1");
+        // No rewrite on turn 1 (union == joined client list): both
+        // lines pass through untouched.
+        assert_eq!(beta_values(&turn1), vec!["a,x", "b"]);
+
+        // Turn 2 drops "x" from the first line: the rewrite must
+        // carry the full set from both turn-1 lines.
+        let mut turn2 = header_map(&["a", "b"]);
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut turn2, "req-2");
+        assert_eq!(beta_values(&turn2), vec!["a,x,b"]);
+    }
+
+    #[test]
+    fn apply_skips_non_ascii_value_and_records_nothing() {
+        let t = tracker();
+        let mut map = HeaderMap::new();
+        map.insert(
+            "anthropic-beta",
+            HeaderValue::from_bytes(&[0xfa, 0xfb]).unwrap(),
+        );
+        apply_sticky_betas(&t, BetaProvider::Anthropic, "s1", &mut map, "req-1");
+        // Wire bytes untouched…
+        assert_eq!(map.get("anthropic-beta").unwrap().as_bytes(), &[0xfa, 0xfb]);
+        // …and nothing recorded: the next ASCII turn sees only its
+        // own tokens.
+        let got = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some("y"));
+        assert_eq!(got, "y");
+    }
+
+    #[test]
+    fn concurrent_unions_lose_no_tokens() {
+        // Port of the Python thread-hammering test: concurrent turns
+        // on one session must never drop a recorded token.
+        let t = tracker();
+        std::thread::scope(|s| {
+            for i in 0..8 {
+                let t = t.clone();
+                s.spawn(move || {
+                    let token = format!("tok-{i}");
+                    for _ in 0..50 {
+                        t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", Some(&token));
+                    }
+                });
+            }
+        });
+        let merged = t.record_and_get_sticky_betas(BetaProvider::Anthropic, "s1", None);
+        let tokens: HashSet<&str> = merged.split(',').collect();
+        for i in 0..8 {
+            assert!(tokens.contains(format!("tok-{i}").as_str()));
+        }
+    }
+}
diff --git a/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs b/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs
index c288d3131..12ca1f709 100644
--- a/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs
+++ b/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs
@@ -399,8 +399,9 @@ pub fn observe_drift(state: &DriftState, session_key: &str, current: StructuralH
 
 /// 16-char hex prefix of SHA-256(session_key). Bounds the log line
 /// width and never reveals the raw key (which may be a bearer token
-/// or API key — see `derive_session_key`).
-fn session_key_log_prefix(session_key: &str) -> String {
+/// or API key — see `derive_session_key`). `pub(crate)` so the
+/// beta-sticky merge site logs the same session identity the same way.
+pub(crate) fn session_key_log_prefix(session_key: &str) -> String {
     let mut hasher = Sha256::new();
     hasher.update(session_key.as_bytes());
     let digest = hasher.finalize();
diff --git a/crates/headroom-proxy/src/cache_stabilization/mod.rs b/crates/headroom-proxy/src/cache_stabilization/mod.rs
index 815c3af21..b5f91a21b 100644
--- a/crates/headroom-proxy/src/cache_stabilization/mod.rs
+++ b/crates/headroom-proxy/src/cache_stabilization/mod.rs
@@ -12,9 +12,14 @@
 //! - **Normalize** request bytes to make cache hits deterministic
 //!   under PAYG mode ([`tool_def_normalize`], PR-E1 / PR-E2;
 //!   [`anthropic_cache_control`], PR-E3; [`openai_cache_key`], PR-E4).
-//!   These mutate bytes only when the auth-mode gate and per-policy
-//!   preconditions (e.g. no customer `cache_control` marker) all clear;
-//!   OAuth and Subscription always passthrough.
+//!   These mutate *body* bytes only when the auth-mode gate and
+//!   per-policy preconditions (e.g. no customer `cache_control`
+//!   marker) all clear; for body mutations, OAuth and Subscription
+//!   always passthrough.
+//! - **Re-echo** client-sent state ([`beta_sticky`]): mutate request
+//!   *headers* only, on every auth mode, and only ever with values
+//!   the same client already put on the wire — anti-drift repair of
+//!   the client's own signal, never injection of Headroom state.
 //!
 //! Currently shipped:
 //!
@@ -49,6 +54,16 @@
 //!   `(model, system, tools)` and inject it so the upstream pins
 //!   cache lookup to a tenant-stable identity. **Mutates the body**
 //!   (only on PAYG) — see its docs for the gating contract.
+//! - [`beta_sticky`] — parity port of the Python proxy's PR-A6
+//!   `SessionBetaTracker`: per-`(provider, session)` LRU that unions
+//!   `anthropic-beta` / `openai-beta` tokens across turns so a client
+//!   dropping a token mid-conversation doesn't rotate the upstream
+//!   prefix-cache key. **Mutates request headers, never the body**;
+//!   applies to all auth modes exactly like the Python path (the
+//!   union only ever contains tokens this client itself sent, so
+//!   subscription stealth — invariant #10 "no beta drift" — is
+//!   preserved by construction). Operator opt-out:
+//!   `--beta-header-sticky disabled`.
 //!
 //! Sibling PRs hang additional submodules off this `mod.rs`. Conflict
 //! resolution between parallel Phase E PRs is intentionally trivial:
@@ -56,6 +71,7 @@
 //! `mod.rs`'s `pub mod` list.
 
 pub mod anthropic_cache_control;
+pub mod beta_sticky;
 pub mod drift_detector;
 pub mod openai_cache_key;
 pub mod tool_def_normalize;
diff --git a/crates/headroom-proxy/src/config.rs b/crates/headroom-proxy/src/config.rs
index 8cc0ae593..181589754 100644
--- a/crates/headroom-proxy/src/config.rs
+++ b/crates/headroom-proxy/src/config.rs
@@ -1,6 +1,9 @@
 //! Configuration for the proxy: CLI flags + env vars.
 
 use clap::{Parser, ValueEnum};
+use headroom_core::rollout::{
+    feature_names, split_feature_names, Feature, RolloutChannel, RolloutSnapshot,
+};
 use std::net::SocketAddr;
 use std::time::Duration;
 use url::Url;
@@ -181,6 +184,48 @@ impl CompressionMode {
     }
 }
 
+/// Session-sticky provider beta headers (parity port of the Python
+/// proxy's `HEADROOM_BETA_HEADER_STICKY`; see
+/// `cache_stabilization::beta_sticky`).
+///
+/// When `enabled` (default), the proxy unions each request's
+/// `anthropic-beta` / `openai-beta` tokens with the tokens previously
+/// seen for the same conversation and forwards the union, so a client
+/// dropping a beta token mid-conversation doesn't rotate the upstream
+/// prefix-cache key.
+///
+/// When `disabled`, the client header is forwarded verbatim and no
+/// per-session token state is kept. Diagnostic operator opt-in — NOT
+/// a fallback per realignment build constraint #4.
+///
+/// Source priority: CLI flag → `HEADROOM_PROXY_BETA_HEADER_STICKY`
+/// env var → default (`enabled`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+#[clap(rename_all = "snake_case")]
+pub enum BetaHeaderSticky {
+    /// Union beta tokens per conversation and forward the union.
+    /// Default. Matches the Python proxy's default behaviour.
+    Enabled,
+    /// Forward the client's beta header verbatim; keep no state.
+    /// Diagnostic-only.
+    Disabled,
+}
+
+impl BetaHeaderSticky {
+    /// Stable snake_case name suitable for log fields.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            BetaHeaderSticky::Enabled => "enabled",
+            BetaHeaderSticky::Disabled => "disabled",
+        }
+    }
+
+    /// Convenience: is the sticky union switched on?
+    pub fn is_enabled(self) -> bool {
+        matches!(self, BetaHeaderSticky::Enabled)
+    }
+}
+
 #[derive(Debug, Clone, Parser)]
 #[command(
     name = "headroom-proxy",
@@ -188,6 +233,49 @@ impl CompressionMode {
     about = "Headroom transparent reverse proxy"
 )]
 pub struct CliArgs {
+    /// Runtime rollout channel that bounds which managed features may run.
+    ///
+    /// `stable` admits only features that have completed bake time. `beta` and
+    /// `canary` admit progressively newer features. `dev` is for local work.
+    /// Explicit feature requests still cannot cross this boundary unless the
+    /// unsafe override is set.
+    #[arg(
+        long = "rollout-channel",
+        env = "HEADROOM_ROLLOUT_CHANNEL",
+        default_value = "stable",
+        value_parser = parse_rollout_channel,
+    )]
+    pub rollout_channel: String,
+
+    /// Comma-separated rollout features to request explicitly.
+    #[arg(
+        long = "features",
+        env = "HEADROOM_FEATURES",
+        default_value = "",
+        value_parser = parse_rollout_features,
+    )]
+    pub features: String,
+
+    /// Comma-separated rollout features to force off. Disable wins over defaults
+    /// and explicit enable requests.
+    #[arg(
+        long = "disable-features",
+        env = "HEADROOM_DISABLE_FEATURES",
+        default_value = "",
+        value_parser = parse_rollout_features,
+    )]
+    pub disable_features: String,
+
+    /// Break-glass override that allows unstable features below their channel.
+    /// Intended only for emergency mitigation and should be visible in logs.
+    #[arg(
+        long = "unsafe-allow-unstable-features",
+        env = "HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES",
+        default_value_t = false,
+        action = clap::ArgAction::Set,
+    )]
+    pub unsafe_allow_unstable_features: bool,
+
     /// Address the proxy listens on (e.g. 0.0.0.0:8787).
     #[arg(long, env = "HEADROOM_PROXY_LISTEN", default_value = "0.0.0.0:8787")]
     pub listen: SocketAddr,
@@ -320,6 +408,28 @@ pub struct CliArgs {
     )]
     pub strip_internal_headers: StripInternalHeaders,
 
+    /// Session-sticky provider beta headers: union `anthropic-beta` /
+    /// `openai-beta` tokens per conversation so a client dropping a
+    /// token mid-conversation doesn't bust the upstream prefix cache.
+    /// Parity port of the Python proxy's `SessionBetaTracker` (PR-A6).
+    /// Default `enabled`; `disabled` is a diagnostic operator opt-in.
+    ///
+    /// Active only when the compression interceptor is on
+    /// (`--compression` / `HEADROOM_PROXY_COMPRESSION=1`): with the
+    /// interceptor off the proxy is a strict byte-pipe and never
+    /// mutates headers. Startup logs a warning when this is `enabled`
+    /// while `--compression` is off.
+    ///
+    /// Source priority: CLI flag → `HEADROOM_PROXY_BETA_HEADER_STICKY`
+    /// env var → default (`enabled`).
+    #[arg(
+        long = "beta-header-sticky",
+        env = "HEADROOM_PROXY_BETA_HEADER_STICKY",
+        value_enum,
+        default_value_t = BetaHeaderSticky::Enabled,
+    )]
+    pub beta_header_sticky: BetaHeaderSticky,
+
     /// Phase C PR-C4: enable the `/v1/responses` SSE streaming
     /// pipeline. When `true` (default), `Accept: text/event-stream`
     /// requests on `/v1/responses` flow through the byte-level SSE
@@ -475,6 +585,32 @@ fn parse_duration(s: &str) -> Result<Duration, String> {
     humantime::parse_duration(s).map_err(|e| format!("invalid duration `{s}`: {e}"))
 }
 
+fn parse_rollout_channel(value: &str) -> Result<String, String> {
+    value
+        .parse::<RolloutChannel>()
+        .map(|channel| channel.as_str().to_owned())
+        .map_err(|_| {
+            format!("unknown rollout channel `{value}` (valid: stable, beta, canary, dev)")
+        })
+}
+
+fn parse_rollout_features(value: &str) -> Result<String, String> {
+    let valid = feature_names();
+    let unknown: Vec<_> = split_feature_names(value)
+        .into_iter()
+        .filter(|name| !valid.contains(name.as_str()))
+        .collect();
+    if unknown.is_empty() {
+        Ok(value.to_owned())
+    } else {
+        Err(format!(
+            "unknown rollout feature(s): {}; valid: {}",
+            unknown.join(", "),
+            valid.into_iter().collect::<Vec<_>>().join(", ")
+        ))
+    }
+}
+
 fn parse_bytes(s: &str) -> Result<u64, String> {
     s.parse::<bytesize::ByteSize>()
         .map(|b| b.as_u64())
@@ -484,6 +620,8 @@ fn parse_bytes(s: &str) -> Result<u64, String> {
 /// Resolved configuration used by the running server.
 #[derive(Debug, Clone)]
 pub struct Config {
+    /// Runtime rollout state resolved from CLI/env.
+    pub rollout: RolloutSnapshot,
     pub listen: SocketAddr,
     pub upstream: Url,
     pub upstream_timeout: Duration,
@@ -517,6 +655,9 @@ pub struct Config {
     /// upstream-bound requests. PR-A5 default-on guard against
     /// fingerprinting / leakage of internal flags.
     pub strip_internal_headers: StripInternalHeaders,
+    /// Session-sticky provider beta headers (parity port of the
+    /// Python `SessionBetaTracker`, PR-A6). Default `enabled`.
+    pub beta_header_sticky: BetaHeaderSticky,
     /// PR-C4: enable the `/v1/responses` streaming pipeline (SSE
     /// state-machine + telemetry tee). Default `true`.
     pub enable_responses_streaming: bool,
@@ -555,6 +696,30 @@ pub struct Config {
 
 impl Config {
     pub fn from_cli(args: CliArgs) -> Self {
+        let mut explicit_features = Vec::new();
+        if args.enable_responses_streaming {
+            explicit_features.push(Feature::OpenAiResponsesStreaming);
+        }
+        if args.enable_bedrock_native {
+            explicit_features.push(Feature::NativeBedrock);
+        }
+        // Preserve the pre-rollout rollback controls as legacy disables. Both
+        // features are stable defaults in the registry, so merely omitting a
+        // false flag from `explicit_features` would turn it straight back on.
+        let mut disabled_features = split_feature_names(&args.disable_features);
+        if !args.enable_responses_streaming {
+            disabled_features.push(Feature::OpenAiResponsesStreaming.spec().name.to_owned());
+        }
+        if !args.enable_bedrock_native {
+            disabled_features.push(Feature::NativeBedrock.spec().name.to_owned());
+        }
+        let rollout = RolloutSnapshot::from_parts_with_explicit(
+            &args.rollout_channel,
+            &args.features,
+            &disabled_features.join(","),
+            args.unsafe_allow_unstable_features,
+            &explicit_features,
+        );
         let rewrite_host = if args.no_rewrite_host {
             false
         } else {
@@ -564,6 +729,7 @@ impl Config {
             .compression_max_body_bytes
             .unwrap_or(args.max_body_bytes);
         Self {
+            rollout: rollout.clone(),
             listen: args.listen,
             upstream: args.upstream,
             upstream_timeout: args.upstream_timeout,
@@ -578,9 +744,14 @@ impl Config {
             cache_control_auto_frozen: args.cache_control_auto_frozen,
             auth_mode_policy_enforcement: args.auth_mode_policy_enforcement,
             strip_internal_headers: args.strip_internal_headers,
-            enable_responses_streaming: args.enable_responses_streaming,
+            beta_header_sticky: args.beta_header_sticky,
+            enable_responses_streaming: rollout.is_enabled(
+                Feature::OpenAiResponsesStreaming,
+                args.enable_responses_streaming,
+            ),
             enable_conversations_passthrough: args.enable_conversations_passthrough,
-            enable_bedrock_native: args.enable_bedrock_native,
+            enable_bedrock_native: rollout
+                .is_enabled(Feature::NativeBedrock, args.enable_bedrock_native),
             bedrock_region: args.bedrock_region,
             bedrock_endpoint: args.bedrock_endpoint,
             aws_profile: args.aws_profile,
@@ -594,6 +765,7 @@ impl Config {
     /// production-default behaviour so existing tests stay unchanged.
     pub fn for_test(upstream: Url) -> Self {
         Self {
+            rollout: RolloutSnapshot::default(),
             listen: "127.0.0.1:0".parse().unwrap(),
             upstream,
             upstream_timeout: Duration::from_secs(60),
@@ -621,6 +793,9 @@ impl Config {
             // from upstream-bound requests. Tests opt out per-case via
             // `start_proxy_with`.
             strip_internal_headers: StripInternalHeaders::Enabled,
+            // Production default: sticky beta-header union per
+            // conversation (Python-parity). Tests opt out per-case.
+            beta_header_sticky: BetaHeaderSticky::Enabled,
             // PR-C4: streaming pipeline + conversations passthrough
             // both default-on so tests exercise the same paths
             // production traffic will hit.
@@ -644,3 +819,48 @@ impl Config {
         }
     }
 }
+
+#[cfg(test)]
+mod rollout_input_tests {
+    use super::*;
+
+    #[test]
+    fn explicit_rollout_inputs_are_strict_and_diagnosable() {
+        assert_eq!(parse_rollout_channel("CANARY").unwrap(), "canary");
+        assert!(parse_rollout_channel("stabel")
+            .unwrap_err()
+            .contains("unknown rollout channel"));
+        assert!(parse_rollout_features("native-bedrock").is_ok());
+        let error = parse_rollout_features("native_bedrok").unwrap_err();
+        assert!(error.contains("native_bedrok"));
+        assert!(error.contains("native_bedrock"));
+    }
+
+    #[test]
+    fn legacy_false_flags_remain_effective_rollout_disables() {
+        let args = CliArgs::try_parse_from([
+            "headroom-proxy",
+            "--upstream",
+            "http://127.0.0.1:9",
+            "--enable-responses-streaming",
+            "false",
+            "--enable-bedrock-native",
+            "false",
+        ])
+        .unwrap();
+
+        let config = Config::from_cli(args);
+
+        for feature in [Feature::OpenAiResponsesStreaming, Feature::NativeBedrock] {
+            let decision = config.rollout.decision(feature);
+            assert!(!decision.enabled);
+            assert!(decision.disabled);
+            assert_eq!(
+                decision.reason,
+                headroom_core::rollout::FeatureDecisionReason::Disabled
+            );
+        }
+        assert!(!config.enable_responses_streaming);
+        assert!(!config.enable_bedrock_native);
+    }
+}
diff --git a/crates/headroom-proxy/src/health.rs b/crates/headroom-proxy/src/health.rs
index 683b917a6..5cf17a7f2 100644
--- a/crates/headroom-proxy/src/health.rs
+++ b/crates/headroom-proxy/src/health.rs
@@ -13,6 +13,11 @@ pub async fn healthz() -> impl IntoResponse {
     Json(json!({ "ok": true, "service": "headroom-proxy" }))
 }
 
+/// Effective rollout state of this running Rust proxy process.
+pub async fn rollout_status(State(state): State<AppState>) -> Json<serde_json::Value> {
+    Json(state.config.rollout.to_value())
+}
+
 /// Upstream health: GETs upstream `/healthz`. Returns 200 when reachable +
 /// 2xx, 503 otherwise. The endpoint name is reserved by the proxy and is
 /// not forwarded; operators must not name a real upstream route this.
@@ -39,3 +44,18 @@ pub async fn healthz_upstream(State(state): State<AppState>) -> Response {
             .into_response(),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Config;
+
+    #[tokio::test]
+    async fn rollout_status_exposes_running_snapshot() {
+        let state = AppState::new(Config::for_test("http://127.0.0.1:9".parse().unwrap())).unwrap();
+        let expected = state.config.rollout.snapshot_digest();
+        let Json(payload) = rollout_status(State(state)).await;
+        assert_eq!(payload["snapshot_digest"], expected);
+        assert_eq!(payload["qualification_eligible"], true);
+    }
+}
diff --git a/crates/headroom-proxy/src/main.rs b/crates/headroom-proxy/src/main.rs
index 19e748522..f21d0117f 100644
--- a/crates/headroom-proxy/src/main.rs
+++ b/crates/headroom-proxy/src/main.rs
@@ -28,9 +28,32 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         max_body_bytes = config.max_body_bytes,
         rewrite_host = config.rewrite_host,
         graceful_shutdown_timeout_s = config.graceful_shutdown_timeout.as_secs(),
+        rollout_channel = config.rollout.config.channel.as_str(),
+        rollout_features_enabled = ?config.rollout.enabled(),
+        rollout_features_disabled = ?config.rollout.config.disabled,
+        unsafe_allow_unstable_features = config.rollout.config.unsafe_allow_unstable,
+        rollout_registry_digest = %config.rollout.registry_digest,
+        rollout_snapshot_digest = %config.rollout.snapshot_digest(),
+        qualification_eligible = config.rollout.qualification_eligible(),
         "headroom-proxy starting"
     );
 
+    // Session-sticky beta headers only run inside the compression
+    // interceptor: with `--compression` off the proxy is a strict
+    // byte-pipe and never mutates headers. Say so loudly at startup —
+    // an operator reading `beta_header_sticky=enabled` (the default)
+    // must not believe the protection is active when it isn't.
+    if config.beta_header_sticky.is_enabled() && !config.compression {
+        tracing::warn!(
+            event = "beta_header_sticky_inactive",
+            beta_header_sticky = config.beta_header_sticky.as_str(),
+            compression = config.compression,
+            "beta-header stickiness is enabled but the compression \
+             interceptor is off; enable --compression (or \
+             HEADROOM_PROXY_COMPRESSION=1) to activate it"
+        );
+    }
+
     let mut state = AppState::new(config.clone())?;
 
     // PR-D1: resolve AWS credentials at startup via the `aws-config`
diff --git a/crates/headroom-proxy/src/proxy.rs b/crates/headroom-proxy/src/proxy.rs
index 7f3d81cd3..1005fb03f 100644
--- a/crates/headroom-proxy/src/proxy.rs
+++ b/crates/headroom-proxy/src/proxy.rs
@@ -17,6 +17,7 @@ use futures_util::{StreamExt as _, TryStreamExt};
 use http_body_util::BodyExt;
 
 use crate::cache_stabilization;
+use crate::cache_stabilization::beta_sticky::BetaProvider;
 use crate::cache_stabilization::drift_detector::{
     compute_structural_hash, derive_session_key, observe_drift, ApiKind, DriftState,
 };
@@ -24,7 +25,7 @@ use crate::compression;
 use crate::config::Config;
 use crate::error::ProxyError;
 use crate::headers::{build_forward_request_headers, filter_response_headers};
-use crate::health::{healthz, healthz_upstream};
+use crate::health::{healthz, healthz_upstream, rollout_status};
 use crate::websocket::ws_handler;
 // Phase F PR-F1: imported as `classify_auth_mode` to make the call
 // site self-documenting. `AuthMode` is re-exported under the same
@@ -66,6 +67,13 @@ pub struct AppState {
     /// request body — so this can be cloned freely into every handler
     /// path that buffers the body.
     pub drift_state: DriftState,
+    /// Session-sticky beta-header tracker (parity port of the Python
+    /// `SessionBetaTracker`, PR-A6): per-`(provider, session)` LRU of
+    /// `anthropic-beta` / `openai-beta` tokens, unioned across turns
+    /// so a client dropping a token mid-conversation doesn't rotate
+    /// the upstream prefix-cache key. Shares the drift detector's
+    /// session identity (same `derive_session_key` output).
+    pub beta_sticky: cache_stabilization::beta_sticky::BetaStickyState,
     /// PR-D4: GCP ADC bearer-token source for Vertex routes. Default:
     /// [`crate::vertex::adc::GcpAdcTokenSource`] constructed lazily;
     /// the actual ADC chain is only resolved when the first Vertex
@@ -111,6 +119,9 @@ impl AppState {
             client,
             bedrock_credentials: None,
             drift_state: DriftState::new(DRIFT_DETECTOR_CAPACITY),
+            beta_sticky: cache_stabilization::beta_sticky::BetaStickyState::new(
+                cache_stabilization::beta_sticky::BETA_TRACKER_CAPACITY,
+            ),
             vertex_token_source,
         })
     }
@@ -146,6 +157,7 @@ pub fn build_app(state: AppState) -> Router {
     let mut router = Router::new()
         .route("/healthz", get(healthz))
         .route("/healthz/upstream", get(healthz_upstream))
+        .route("/rollout/status", get(rollout_status))
         // PR-D3: Prometheus scrape endpoint. Renders the global
         // registry in text format. The handler is stateless — no
         // `AppState` needed — and idempotent across concurrent
@@ -707,6 +719,41 @@ pub(crate) async fn forward_http(
                 let session_key = derive_session_key(headers, &client_addr, &parsed, kind);
                 let hash = compute_structural_hash(&parsed, kind);
                 observe_drift(&state.drift_state, &session_key, hash);
+
+                // Session-sticky provider beta headers — port of the
+                // Python PR-A6 `SessionBetaTracker`. Beta headers are
+                // part of the bytes that determine the upstream
+                // prefix-cache key; a client dropping a token between
+                // turns rotates the key and re-writes the whole
+                // prefix at the customer's cost. Forward the
+                // per-conversation union instead. See
+                // `cache_stabilization::beta_sticky` for the behavior
+                // contract, the auth-mode rationale (applies to every
+                // mode, like the Python handler), and the one
+                // documented divergence from Python (per-conversation
+                // keying). Reuses the drift detector's `session_key`
+                // so both cache-stability subsystems agree on
+                // conversation identity. Mutates upstream-bound
+                // HEADERS only; body bytes stay untouched (Phase-A
+                // cache-safety invariant).
+                if state.config.beta_header_sticky.is_enabled() {
+                    let provider = match endpoint {
+                        compression::CompressibleEndpoint::AnthropicMessages => {
+                            BetaProvider::Anthropic
+                        }
+                        compression::CompressibleEndpoint::OpenAiChatCompletions
+                        | compression::CompressibleEndpoint::OpenAiResponses => {
+                            BetaProvider::OpenAi
+                        }
+                    };
+                    cache_stabilization::beta_sticky::apply_sticky_betas(
+                        &state.beta_sticky,
+                        provider,
+                        &session_key,
+                        &mut outgoing_headers,
+                        &request_id,
+                    );
+                }
             }
         }
         let outcome = match endpoint {
diff --git a/crates/headroom-proxy/src/websocket.rs b/crates/headroom-proxy/src/websocket.rs
index c3a6358c6..509cd6bfd 100644
--- a/crates/headroom-proxy/src/websocket.rs
+++ b/crates/headroom-proxy/src/websocket.rs
@@ -218,10 +218,10 @@ async fn run_ws_pump(
 
 fn ax_to_tg(m: AxMsg) -> Option<TgMsg> {
     Some(match m {
-        AxMsg::Text(t) => TgMsg::Text(t.to_string()),
-        AxMsg::Binary(b) => TgMsg::Binary(b.to_vec()),
-        AxMsg::Ping(p) => TgMsg::Ping(p.to_vec()),
-        AxMsg::Pong(p) => TgMsg::Pong(p.to_vec()),
+        AxMsg::Text(t) => TgMsg::Text(t.to_string().into()),
+        AxMsg::Binary(b) => TgMsg::Binary(b.to_vec().into()),
+        AxMsg::Ping(p) => TgMsg::Ping(p.to_vec().into()),
+        AxMsg::Pong(p) => TgMsg::Pong(p.to_vec().into()),
         AxMsg::Close(Some(cf)) => TgMsg::Close(Some(TgCloseFrame {
             code: tokio_tungstenite::tungstenite::protocol::frame::coding::CloseCode::from(cf.code),
             reason: cf.reason.to_string().into(),
diff --git a/crates/headroom-proxy/tests/integration_beta_header_sticky.rs b/crates/headroom-proxy/tests/integration_beta_header_sticky.rs
new file mode 100644
index 000000000..d1712be96
--- /dev/null
+++ b/crates/headroom-proxy/tests/integration_beta_header_sticky.rs
@@ -0,0 +1,529 @@
+//! End-to-end coverage for session-sticky provider beta headers
+//! (`cache_stabilization::beta_sticky` — Rust port of the Python
+//! proxy's PR-A6 `SessionBetaTracker`).
+//!
+//! The scenario every test guards: a client (Claude Code, Codex CLI)
+//! sends `anthropic-beta: a,b` on turn 1 and drops `b` on turn 2 of
+//! the SAME conversation. Beta headers are part of the bytes that
+//! determine the upstream prefix-cache key, so the drop rotates the
+//! key and the provider re-writes the whole prefix at the customer's
+//! cost. The proxy must forward the per-conversation union instead.
+//!
+//! These tests boot a real Rust proxy in front of a wiremock upstream
+//! and assert on the headers/bytes the upstream actually receives:
+//!
+//! - dropped tokens are re-injected on later turns (Anthropic,
+//!   OpenAI Chat, OpenAI Responses — all three intercepted routes);
+//! - conversation identity works both via the explicit
+//!   `x-headroom-session-id` opt-in AND via the body-derived
+//!   conversation discriminator (no explicit header — the realistic
+//!   Claude Code shape);
+//! - the union NEVER invents tokens the client didn't send: no beta
+//!   header in → no beta header out, and separate conversations don't
+//!   leak tokens into each other;
+//! - `--beta-header-sticky disabled` forwards the client value
+//!   verbatim (diagnostic opt-out, Python
+//!   `HEADROOM_BETA_HEADER_STICKY=disabled` parity);
+//! - the body is forwarded byte-equal (SHA-256) while the header is
+//!   rewritten — the mechanism mutates request headers, never body
+//!   bytes (Phase-A cache-safety contract).
+
+mod common;
+
+use common::start_proxy_with;
+use serde_json::json;
+use sha2::{Digest, Sha256};
+use std::sync::{Arc, Mutex};
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+/// Everything the upstream saw for one request: selected header
+/// values (lower-case names) + raw body bytes.
+#[derive(Clone)]
+struct Seen {
+    beta: Option<String>,
+    session_id_header: Option<String>,
+    body: Vec<u8>,
+}
+
+type Captures = Arc<Mutex<Vec<Seen>>>;
+
+/// Mount a capture-everything mock for `route` on the upstream. The
+/// `beta_header` name is which provider beta header to record
+/// (`anthropic-beta` / `openai-beta`).
+async fn mount_capture(upstream: &MockServer, route: &str, beta_header: &'static str) -> Captures {
+    let captured: Captures = Arc::new(Mutex::new(Vec::new()));
+    let captured_clone = captured.clone();
+    Mock::given(method("POST"))
+        .and(path(route))
+        .respond_with(move |req: &wiremock::Request| {
+            let get = |name: &str| {
+                req.headers
+                    .get(name)
+                    .and_then(|v| v.to_str().ok())
+                    .map(|s| s.to_string())
+            };
+            captured_clone.lock().unwrap().push(Seen {
+                beta: get(beta_header),
+                session_id_header: get("x-headroom-session-id"),
+                body: req.body.clone(),
+            });
+            ResponseTemplate::new(200).set_body_string(r#"{"ok":true}"#)
+        })
+        .mount(upstream)
+        .await;
+    captured
+}
+
+fn anthropic_body(turns: &[(&str, &str)]) -> Vec<u8> {
+    let messages: Vec<serde_json::Value> = turns
+        .iter()
+        .map(|(role, content)| json!({"role": role, "content": content}))
+        .collect();
+    serde_json::to_vec(&json!({
+        "model": "claude-sonnet-4-5",
+        "max_tokens": 32,
+        "messages": messages,
+    }))
+    .unwrap()
+}
+
+fn openai_chat_body(turns: &[(&str, &str)]) -> Vec<u8> {
+    let messages: Vec<serde_json::Value> = turns
+        .iter()
+        .map(|(role, content)| json!({"role": role, "content": content}))
+        .collect();
+    serde_json::to_vec(&json!({
+        "model": "gpt-4o",
+        "messages": messages,
+    }))
+    .unwrap()
+}
+
+fn openai_responses_body(text: &str) -> Vec<u8> {
+    serde_json::to_vec(&json!({
+        "model": "gpt-4o",
+        "input": [{"role": "user", "content": text}],
+    }))
+    .unwrap()
+}
+
+async fn post(
+    client: &reqwest::Client,
+    url: String,
+    body: Vec<u8>,
+    headers: &[(&str, &str)],
+) -> reqwest::Response {
+    let mut req = client
+        .post(url)
+        .header("content-type", "application/json")
+        .body(body);
+    for (name, value) in headers {
+        req = req.header(*name, *value);
+    }
+    req.send().await.expect("proxy reachable")
+}
+
+#[tokio::test]
+async fn anthropic_dropped_beta_token_reinjected_with_explicit_session_header() {
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    // Turn 1: two beta tokens.
+    let resp = post(
+        &client,
+        url.clone(),
+        anthropic_body(&[("user", "hello")]),
+        &[
+            (
+                "anthropic-beta",
+                "context-management-2025-06-27,interleaved-thinking-2025-05-14",
+            ),
+            ("x-headroom-session-id", "conv-explicit-1"),
+        ],
+    )
+    .await;
+    assert_eq!(resp.status(), 200);
+
+    // Turn 2, same conversation: the client dropped the second token.
+    let resp = post(
+        &client,
+        url,
+        anthropic_body(&[("user", "hello"), ("assistant", "hi"), ("user", "next")]),
+        &[
+            ("anthropic-beta", "context-management-2025-06-27"),
+            ("x-headroom-session-id", "conv-explicit-1"),
+        ],
+    )
+    .await;
+    assert_eq!(resp.status(), 200);
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(
+        seen[0].beta.as_deref(),
+        Some("context-management-2025-06-27,interleaved-thinking-2025-05-14"),
+        "turn 1 forwards the client value unchanged"
+    );
+    assert_eq!(
+        seen[1].beta.as_deref(),
+        Some("context-management-2025-06-27,interleaved-thinking-2025-05-14"),
+        "turn 2 must re-inject the dropped token so the upstream \
+         prefix-cache key stays byte-stable"
+    );
+    // PR-A5 invariant intact: the internal session header never
+    // crosses the upstream boundary.
+    assert!(seen.iter().all(|s| s.session_id_header.is_none()));
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn anthropic_conversation_keyed_without_explicit_session_header() {
+    // The realistic Claude Code shape: no `x-headroom-session-id`;
+    // conversation identity comes from the credential arm + the
+    // first-message discriminator inside `derive_session_key`.
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    let auth = ("authorization", "Bearer oauth-workspace-token");
+    post(
+        &client,
+        url.clone(),
+        anthropic_body(&[("user", "conversation opener")]),
+        &[("anthropic-beta", "a,b"), auth],
+    )
+    .await;
+    // Same conversation (same opener, grown transcript), token "b"
+    // dropped.
+    post(
+        &client,
+        url,
+        anthropic_body(&[
+            ("user", "conversation opener"),
+            ("assistant", "reply"),
+            ("user", "follow-up"),
+        ]),
+        &[("anthropic-beta", "a"), auth],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(seen[1].beta.as_deref(), Some("a,b"));
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn openai_chat_dropped_beta_token_reinjected() {
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/chat/completions", "openai-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/chat/completions", proxy.url());
+
+    post(
+        &client,
+        url.clone(),
+        openai_chat_body(&[("user", "hello")]),
+        &[
+            ("openai-beta", "assistants=v2,realtime=v1"),
+            ("x-headroom-session-id", "conv-oai-1"),
+        ],
+    )
+    .await;
+    post(
+        &client,
+        url,
+        openai_chat_body(&[("user", "hello"), ("assistant", "hi"), ("user", "next")]),
+        &[
+            ("openai-beta", "assistants=v2"),
+            ("x-headroom-session-id", "conv-oai-1"),
+        ],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(seen[1].beta.as_deref(), Some("assistants=v2,realtime=v1"));
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn openai_responses_dropped_beta_token_reinjected() {
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/responses", "openai-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/responses", proxy.url());
+
+    post(
+        &client,
+        url.clone(),
+        openai_responses_body("hello"),
+        &[
+            ("openai-beta", "responses=v1,tools=v2"),
+            ("x-headroom-session-id", "conv-resp-1"),
+        ],
+    )
+    .await;
+    post(
+        &client,
+        url,
+        openai_responses_body("hello again"),
+        &[
+            ("openai-beta", "responses=v1"),
+            ("x-headroom-session-id", "conv-resp-1"),
+        ],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(seen[1].beta.as_deref(), Some("responses=v1,tools=v2"));
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn anthropic_fully_omitted_beta_header_regains_union() {
+    // The headline docs claim: "sends a token in turn N and omits it
+    // in turn N+1" — here the whole header disappears, not just one
+    // token, and the union must be re-added through real axum/reqwest
+    // plumbing.
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    post(
+        &client,
+        url.clone(),
+        anthropic_body(&[("user", "hello")]),
+        &[
+            ("anthropic-beta", "context-management-2025-06-27"),
+            ("x-headroom-session-id", "conv-omit-1"),
+        ],
+    )
+    .await;
+    // Turn 2: no anthropic-beta header at all.
+    post(
+        &client,
+        url,
+        anthropic_body(&[("user", "hello"), ("assistant", "hi"), ("user", "next")]),
+        &[("x-headroom-session-id", "conv-omit-1")],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(
+        seen[1].beta.as_deref(),
+        Some("context-management-2025-06-27"),
+        "a fully omitted beta header must be restored from session state"
+    );
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn disabled_flag_forwards_client_value_verbatim() {
+    use headroom_proxy::config::BetaHeaderSticky;
+
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+        c.beta_header_sticky = BetaHeaderSticky::Disabled;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    post(
+        &client,
+        url.clone(),
+        anthropic_body(&[("user", "hello")]),
+        &[
+            ("anthropic-beta", "a,b"),
+            ("x-headroom-session-id", "conv-d1"),
+        ],
+    )
+    .await;
+    post(
+        &client,
+        url,
+        anthropic_body(&[("user", "hello"), ("assistant", "hi"), ("user", "next")]),
+        &[
+            ("anthropic-beta", "a"),
+            ("x-headroom-session-id", "conv-d1"),
+        ],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(
+        seen[1].beta.as_deref(),
+        Some("a"),
+        "disabled mode must forward the dropped-token value verbatim \
+         and keep no session state"
+    );
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn no_client_beta_header_is_never_invented() {
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    for body in [
+        anthropic_body(&[("user", "hello")]),
+        anthropic_body(&[("user", "hello"), ("assistant", "hi"), ("user", "next")]),
+    ] {
+        post(
+            &client,
+            url.clone(),
+            body,
+            &[("x-headroom-session-id", "conv-n1")],
+        )
+        .await;
+    }
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert!(
+        seen.iter().all(|s| s.beta.is_none()),
+        "a session that never sent a beta header must never gain one"
+    );
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn separate_conversations_do_not_leak_tokens() {
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    post(
+        &client,
+        url.clone(),
+        anthropic_body(&[("user", "conversation A")]),
+        &[
+            ("anthropic-beta", "token-a"),
+            ("x-headroom-session-id", "conv-A"),
+        ],
+    )
+    .await;
+    post(
+        &client,
+        url,
+        anthropic_body(&[("user", "conversation B")]),
+        &[
+            ("anthropic-beta", "token-b"),
+            ("x-headroom-session-id", "conv-B"),
+        ],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    assert_eq!(seen[0].beta.as_deref(), Some("token-a"));
+    assert_eq!(
+        seen[1].beta.as_deref(),
+        Some("token-b"),
+        "conversation B must not inherit conversation A's tokens"
+    );
+
+    proxy.shutdown().await;
+}
+
+#[tokio::test]
+async fn body_bytes_stay_byte_equal_while_header_is_rewritten() {
+    // Cache-safety contract: the sticky union mutates request
+    // HEADERS only. The forwarded body must remain byte-identical
+    // (SHA-256) to what the client sent — same assertion idiom as the
+    // model-sanitizer integration tests.
+    let upstream = MockServer::start().await;
+    let captured = mount_capture(&upstream, "/v1/messages", "anthropic-beta").await;
+    let proxy = start_proxy_with(&upstream.uri(), |c| {
+        c.compression = true;
+    })
+    .await;
+    let client = reqwest::Client::new();
+    let url = format!("{}/v1/messages", proxy.url());
+
+    let turn1 = anthropic_body(&[("user", "hello")]);
+    let turn2 = anthropic_body(&[("user", "hello"), ("assistant", "hi"), ("user", "next")]);
+
+    post(
+        &client,
+        url.clone(),
+        turn1,
+        &[
+            ("anthropic-beta", "a,b"),
+            ("x-headroom-session-id", "conv-bb"),
+        ],
+    )
+    .await;
+    post(
+        &client,
+        url,
+        turn2.clone(),
+        &[
+            ("anthropic-beta", "a"),
+            ("x-headroom-session-id", "conv-bb"),
+        ],
+    )
+    .await;
+
+    let seen = captured.lock().unwrap().clone();
+    assert_eq!(seen.len(), 2);
+    // Header was rewritten to the union…
+    assert_eq!(seen[1].beta.as_deref(), Some("a,b"));
+    // …but the body bytes are untouched.
+    assert_eq!(
+        Sha256::digest(&seen[1].body),
+        Sha256::digest(&turn2),
+        "sticky beta union must never mutate body bytes"
+    );
+
+    proxy.shutdown().await;
+}
diff --git a/crates/headroom-proxy/tests/integration_ws.rs b/crates/headroom-proxy/tests/integration_ws.rs
index 7f9688d87..1c29aaf3a 100644
--- a/crates/headroom-proxy/tests/integration_ws.rs
+++ b/crates/headroom-proxy/tests/integration_ws.rs
@@ -53,7 +53,7 @@ async fn ws_text_and_binary_round_trip() {
 
     for i in 0..5 {
         let m = format!("hello-{i}");
-        ws.send(Message::Text(m.clone())).await.unwrap();
+        ws.send(Message::Text(m.clone().into())).await.unwrap();
         let echoed = ws.next().await.unwrap().unwrap();
         match echoed {
             Message::Text(t) => assert_eq!(t.as_str(), m),
@@ -62,7 +62,7 @@ async fn ws_text_and_binary_round_trip() {
     }
     for i in 0..5u8 {
         let m: Vec<u8> = (0..32u8).map(|b| b ^ i).collect();
-        ws.send(Message::Binary(m.clone())).await.unwrap();
+        ws.send(Message::Binary(m.clone().into())).await.unwrap();
         let echoed = ws.next().await.unwrap().unwrap();
         match echoed {
             Message::Binary(b) => assert_eq!(b.to_vec(), m),
diff --git a/dashboard-cache-ttl-main.png b/dashboard-cache-ttl-main.png
new file mode 100644
index 000000000..3433b1c56
Binary files /dev/null and b/dashboard-cache-ttl-main.png differ
diff --git a/deploy/beacon/package.json b/deploy/beacon/package.json
new file mode 100644
index 000000000..b1913f3bd
--- /dev/null
+++ b/deploy/beacon/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "headroom-beacon",
+  "private": true,
+  "type": "module"
+}
diff --git a/deploy/beacon/sample-event.json b/deploy/beacon/sample-event.json
index 6d5e13bd5..4bacb0ebc 100644
--- a/deploy/beacon/sample-event.json
+++ b/deploy/beacon/sample-event.json
@@ -284,6 +284,21 @@
                       "value": {
                         "intValue": "2"
                       }
+                    },
+                    {
+                      "key": "failure_statuses",
+                      "value": {
+                        "kvlistValue": {
+                          "values": [
+                            {
+                              "key": "529",
+                              "value": {
+                                "intValue": "2"
+                              }
+                            }
+                          ]
+                        }
+                      }
                     }
                   ]
                 }
diff --git a/deploy/beacon/test-rollup.mjs b/deploy/beacon/test-rollup.mjs
new file mode 100644
index 000000000..3878ee2d4
--- /dev/null
+++ b/deploy/beacon/test-rollup.mjs
@@ -0,0 +1,214 @@
+/**
+ * Self-check for scheduled()'s hourly compaction.  node test-rollup.mjs [dir]
+ *
+ * The one thing that must never drift: rollupHour() and the QUALIFY in
+ * headroom-beacon-stats/beacon.sh have to agree on which heartbeat wins. If
+ * they disagree the reports get quietly wrong rather than loudly broken, so
+ * this asserts the JS picks exactly the max-seq row per (install, session).
+ *
+ * Point it at a directory of real beacon objects to check against the corpus:
+ *   aws s3 sync s3://headroom-telemetry/sessions/dt=.../hh=.../ /tmp/hr/ ...
+ *   node test-rollup.mjs /tmp/hr
+ * With no argument it runs on a small fixture and needs no network.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import assert from 'node:assert/strict';
+import { oldestRawDay, rollupHour } from './worker.js';
+
+// R2 returns at most 1000 keys per list page, so on a real hour (~4,000
+// objects) the cursor loop in rollupHour is load-bearing. The stub paginates at
+// a deliberately tiny size so that loop is exercised by every case below: with
+// a single-page stub, a regression that dropped the cursor would still print
+// "ok" while silently rolling up only the first page of every hour.
+const PAGE = 3;
+
+/** The slice of the R2 binding rollupHour uses, backed by a plain object. */
+function stubBucket(files, { failKeys = new Set() } = {}) {
+  const written = {};
+  const reads = [];
+  return {
+    written,
+    reads,
+    list: async ({ prefix, cursor, delimiter }) => {
+      const keys = Object.keys(files)
+        .filter((k) => k.startsWith(prefix))
+        .sort();
+      if (delimiter) {
+        const seen = new Set();
+        for (const k of keys) {
+          const cut = k.indexOf(delimiter, prefix.length);
+          if (cut >= 0) seen.add(k.slice(0, cut + 1));
+        }
+        return { objects: [], delimitedPrefixes: [...seen], truncated: false };
+      }
+      const start = cursor ? keys.indexOf(cursor) : 0;
+      const page = keys.slice(start, start + PAGE);
+      const next = start + PAGE;
+      return {
+        objects: page.map((key) => ({ key })),
+        truncated: next < keys.length,
+        cursor: next < keys.length ? keys[next] : undefined,
+      };
+    },
+    get: async (key) => {
+      reads.push(key);
+      if (failKeys.has(key)) throw new Error(`simulated R2 failure: ${key}`);
+      if (!(key in files)) return null;
+      return { text: async () => files[key] };
+    },
+    put: async (key, body) => {
+      written[key] = body;
+    },
+  };
+}
+
+const beacon = (install, id, seq) =>
+  JSON.stringify({ resource: { 'headroom.install_id': install }, session: { id, seq } });
+
+const PART = 'dt=2026-08-06/hh=14';
+
+/** Run rollupHour against a stub bucket and decode whatever it wrote. */
+async function run(files, opts = {}) {
+  const CORPUS = stubBucket(files, opts);
+  const spend = { read: 0 };
+  let threw = null;
+  let out = null;
+  try {
+    out = await rollupHour({ CORPUS }, PART, spend);
+  } catch (err) {
+    threw = err;
+  }
+  const body = CORPUS.written[`rollup/${PART}/data.ndjson`];
+  return {
+    threw,
+    spend,
+    wrote: out ? out.wrote : 0,
+    empty: `rollup/${PART}/empty` in CORPUS.written,
+    keys: Object.keys(CORPUS.written),
+    rows: body ? body.split('\n').map((l) => JSON.parse(l)) : [],
+  };
+}
+
+// 1. Highest seq wins, out-of-order input, one row per (install, session).
+//    More objects than PAGE, so the list cursor loop runs.
+{
+  const files = {
+    [`sessions/${PART}/a.json`]: [beacon('i1', 's1', 3), beacon('i1', 's2', 1)].join('\n'),
+    [`sessions/${PART}/b.json`]: beacon('i1', 's1', 9),
+    [`sessions/${PART}/c.json`]: beacon('i1', 's1', 7),
+    // Same session id under a different install must not collapse together.
+    [`sessions/${PART}/d.json`]: beacon('i2', 's1', 2),
+    [`sessions/${PART}/e.json`]: beacon('i1', 's1', 5),
+  };
+  const { rows, spend, threw } = await run(files);
+  assert.equal(threw, null);
+  // 5 objects at PAGE=3 is two pages: proves the cursor loop, which is
+  // load-bearing at the real ~4,000 objects/hour.
+  assert.ok(Object.keys(files).length > PAGE, 'fixture must span pages');
+  assert.equal(spend.read, 5, 'reads every object across every page');
+  assert.equal(rows.length, 3, 'one row per (install, session)');
+  const seq = Object.fromEntries(
+    rows.map((r) => [`${r.resource['headroom.install_id']} ${r.session.id}`, r.session.seq])
+  );
+  assert.deepEqual(seq, { 'i1 s1': 9, 'i1 s2': 1, 'i2 s1': 2 });
+}
+
+// 2. An unparseable record loses only itself. Content this Worker wrote with
+//    JSON.stringify never becomes valid later, so blocking the hour on it would
+//    strand the hour rather than one record.
+{
+  const files = {
+    [`sessions/${PART}/a.json`]: '{ this is not json',
+    [`sessions/${PART}/b.json`]: `\n${beacon('i1', 's1', 4)}\n`,
+  };
+  const { rows, threw } = await run(files);
+  assert.equal(threw, null, 'corrupt content does not abandon the hour');
+  assert.deepEqual(rows.map((r) => r.session.seq), [4], 'survives a corrupt object');
+}
+
+// 3. A failed get is transient, so the hour must NOT be written — a rollup is
+//    built once and then trusted forever, so a short read would silently become
+//    the permanent record.
+{
+  const files = {
+    [`sessions/${PART}/a.json`]: beacon('i1', 's1', 1),
+    [`sessions/${PART}/b.json`]: beacon('i1', 's2', 1),
+  };
+  const { threw, keys } = await run(files, {
+    failKeys: new Set([`sessions/${PART}/b.json`]),
+  });
+  assert.ok(threw, 'a failed get throws so the hour is retried');
+  assert.deepEqual(keys, [], 'nothing written on a partial read');
+}
+
+// 4. Spend is reported even when the hour throws. Charging a flat guess instead
+//    lets a run that failed late overshoot the subrequest ceiling.
+{
+  const files = Object.fromEntries(
+    Array.from({ length: 7 }, (_, i) => [`sessions/${PART}/o${i}.json`, beacon('i1', `s${i}`, 1)])
+  );
+  const { threw, spend } = await run(files, {
+    failKeys: new Set([`sessions/${PART}/o6.json`]),
+  });
+  assert.ok(threw);
+  assert.equal(spend.read, 7, 'caller sees real spend, not a guess');
+}
+
+// 5. An empty hour writes a marker, not a zero-byte NDJSON. Without it the hour
+//    stays "missing" and is re-listed on every run forever.
+{
+  const { rows, empty, keys } = await run({});
+  assert.deepEqual(rows, []);
+  assert.ok(empty, 'empty hour leaves a marker');
+  assert.ok(
+    keys.every((k) => !k.endsWith('.ndjson')),
+    'no zero-byte ndjson for readers to special-case'
+  );
+}
+
+// 6. oldestRawDay floors the backfill. A fixed lookback window silently strands
+//    every hour older than it once analysis stopped reading sessions/.
+{
+  const CORPUS = stubBucket({
+    'sessions/dt=2026-08-03/hh=01/a.json': beacon('i1', 's1', 1),
+    'sessions/dt=2026-08-06/hh=14/b.json': beacon('i1', 's2', 1),
+    'sessions/dt=2026-08-07/hh=00/c.json': beacon('i1', 's3', 1),
+  });
+  assert.equal(await oldestRawDay({ CORPUS }), '2026-08-03');
+  assert.equal(await oldestRawDay({ CORPUS: stubBucket({}) }), null, 'empty bucket -> null');
+}
+
+// 7. Against real objects, if a directory was given: same answer as the QUALIFY
+//    in beacon.sh, which is `count(DISTINCT install||session)` rows, each
+//    carrying that pair's max seq.
+const dir = process.argv[2];
+if (dir) {
+  const files = {};
+  for (const f of readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+    files[`sessions/${PART}/${f}`] = readFileSync(`${dir}/${f}`, 'utf8');
+  }
+  const { rows, spend, threw } = await run(files);
+  assert.equal(threw, null);
+
+  const expected = new Map();
+  for (const text of Object.values(files)) {
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      const r = JSON.parse(line);
+      const k = `${r.resource?.['headroom.install_id']} ${r.session?.id}`;
+      expected.set(k, Math.max(expected.get(k) ?? -1, r.session?.seq ?? 0));
+    }
+  }
+  assert.equal(spend.read, Object.keys(files).length);
+  assert.equal(rows.length, expected.size, 'row count matches DISTINCT sessions');
+  for (const r of rows) {
+    const k = `${r.resource['headroom.install_id']} ${r.session.id}`;
+    assert.equal(r.session.seq, expected.get(k), `max seq for ${k}`);
+  }
+  console.log(
+    `real corpus: ${spend.read} objects -> ${rows.length} sessions in 1 object` +
+      ` (${Math.ceil(spend.read / PAGE)} list pages)`
+  );
+}
+
+console.log('ok');
diff --git a/deploy/beacon/worker.js b/deploy/beacon/worker.js
index d4e2d0ac2..7fea03001 100644
--- a/deploy/beacon/worker.js
+++ b/deploy/beacon/worker.js
@@ -28,9 +28,12 @@
  * deanonymise install_id, so it is never read.
  */
 
-// Mirrors the payload built by _Session.payload(). A key absent here is
-// dropped, not stored. Adding a metric means adding it here first — that
-// friction is the point.
+// Mostly mirrors the payload built by _Session.payload(); an extension may
+// also emit its own event carrying one of these top-level keys. A key absent
+// here is dropped, not stored. Adding a metric means adding it here first —
+// that friction is the point, and it is also the only privacy control that
+// works retroactively, so it must land BEFORE any client starts sending the
+// key or that traffic is silently discarded and unrecoverable.
 const ALLOWED_KEYS = [
   'schema_version',
   'session',
@@ -42,6 +45,14 @@ const ALLOWED_KEYS = [
   'providers',
   'models',
   'failures',
+  'failure_statuses',
+  // Model-routing summary. Emitted by a routing extension rather than by the
+  // proxy itself -- see proxy/route_advice.py for the decision seam. Same rule
+  // as everything above: counters and model ids, no free text. Allowlisted
+  // here so the corpus can answer what the proxy alone cannot -- a provider's
+  // real minimum cacheable prefix, how long a cache actually survives, and how
+  // far predicted cache hits are from the ones that happened.
+  'routing',
 ];
 
 // Resource attributes we keep. Same rule: allowlist, not denylist.
@@ -110,7 +121,184 @@ function extract(payload) {
   return records;
 }
 
+// ----------------------------------------------------------------- rollup --
+//
+// The corpus is one object per heartbeat, ~1KB each — 65k on 2026-08-06 and
+// climbing. DuckDB reads them correctly, but a full `pull` is ~100k HTTPS round
+// trips for 95MB: minutes of pure per-object latency, no real bytes or compute.
+// Listing the bucket alone took 88 seconds.
+//
+// This job collapses each COMPLETE hour into one object under rollup/, keeping
+// only the highest-seq heartbeat per (install, session). One measured hour
+// (dt=2026-08-06/hh=14): 3,938 objects and 3,938 rows in, 1 object and 1,061
+// rows out. Analysis reads rollup/**, never sessions/**. Raw is left exactly as
+// written, so any rollup can be rebuilt by deleting it.
+//
+// Hourly rather than daily because every R2 binding call is a subrequest: a day
+// is ~65k of them against a 10k-per-invocation ceiling, an hour is ~4k.
+
+const READ_BUDGET = 60000; // objects per run; see [limits] in wrangler.toml
+// A get costs ~45ms of round trip and almost no CPU, so this is what decides
+// whether a run finishes: at 20 an hour took ~3 minutes, against a 15-minute
+// wall clock for a cron invocation. Raise it if an hour ever stops fitting.
+const FANOUT = 100;        // concurrent R2 gets
+
+const partition = (d) =>
+  `dt=${d.toISOString().slice(0, 10)}/hh=${d.toISOString().slice(11, 13)}`;
+
+/**
+ * One hour of heartbeats -> one deduped NDJSON object.
+ *
+ * Returns `{ read, wrote }`. Spend is reported through the mutable `spend`
+ * accumulator so the caller still knows it even when this throws: the budget
+ * has to track real spend, and a flat guess lets a run that failed late
+ * overshoot the subrequest ceiling and get killed inside an hour that would
+ * otherwise have succeeded.
+ *
+ * Writes nothing unless the whole hour read cleanly. A rollup is built once and
+ * then treated as done forever, so a partial read would silently become the
+ * permanent record — better to write nothing and let the next run retry.
+ */
+export async function rollupHour(env, part, spend = { read: 0 }) {
+  const best = new Map();
+  let failed = 0;   // transient: retry the hour
+  let corrupt = 0;  // permanent: record and move on
+  let cursor;
+  do {
+    const page = await env.CORPUS.list({ prefix: `sessions/${part}/`, cursor });
+    for (let i = 0; i < page.objects.length; i += FANOUT) {
+      // allSettled, not all: one transient R2 error among the ~4,000 gets in a
+      // real hour would otherwise reject the batch and discard the whole hour.
+      const settled = await Promise.allSettled(
+        page.objects
+          .slice(i, i + FANOUT)
+          .map((o) => env.CORPUS.get(o.key).then((r) => (r ? r.text() : null)))
+      );
+      for (const outcome of settled) {
+        spend.read++;
+        // A miss counts as a failure too. The key came from a LIST, so the
+        // object existed; treating it as empty would quietly shrink the rollup.
+        if (outcome.status !== 'fulfilled' || outcome.value === null) {
+          failed++;
+          continue;
+        }
+        for (const line of outcome.value.split('\n')) {
+          if (!line) continue;
+          let rec;
+          try {
+            rec = JSON.parse(line);
+          } catch {
+            // Counted and logged, but NOT a reason to abandon the hour. A
+            // failed get is transient and worth retrying; content this Worker
+            // itself wrote with JSON.stringify does not become valid later, so
+            // blocking on it would strand the hour until its raw objects
+            // expire and then lose the whole hour instead of one record.
+            corrupt++;
+            continue;
+          }
+          // A session heartbeats every 5 minutes carrying CUMULATIVE totals, so
+          // the highest seq IS the whole session and every earlier row is a
+          // strict subset. Sessions straddle hours, so readers still dedupe
+          // across rollups on this same key — this only shrinks each hour.
+          const id = `${rec.resource?.['headroom.install_id']} ${rec.session?.id}`;
+          const prev = best.get(id);
+          if (!prev || (rec.session?.seq ?? 0) > (prev.session?.seq ?? 0)) {
+            best.set(id, rec);
+          }
+        }
+      }
+    }
+    cursor = page.truncated ? page.cursor : undefined;
+  } while (cursor);
+
+  if (failed) {
+    throw new Error(`${part}: ${failed} of ${spend.read} objects unreadable`);
+  }
+  if (corrupt) {
+    console.error(`rollup ${part}: skipped ${corrupt} unparseable record(s)`);
+  }
+
+  // A genuinely empty hour gets a marker rather than a zero-byte NDJSON that
+  // every reader would have to special-case. Without it the hour stays
+  // "missing" and is re-listed on every run for the life of the bucket.
+  if (best.size === 0) {
+    await env.CORPUS.put(`rollup/${part}/empty`, '');
+    return { read: spend.read, wrote: 0 };
+  }
+  await env.CORPUS.put(
+    `rollup/${part}/data.ndjson`,
+    [...best.values()].map((r) => JSON.stringify(r)).join('\n'),
+    { httpMetadata: { contentType: 'application/x-ndjson' } }
+  );
+  return { read: spend.read, wrote: best.size };
+}
+
+/** Oldest `dt=` day still under sessions/, or null. One delimited LIST. */
+export async function oldestRawDay(env) {
+  const page = await env.CORPUS.list({ prefix: 'sessions/', delimiter: '/' });
+  const days = (page.delimitedPrefixes || [])
+    .map((p) => p.slice('sessions/dt='.length).replace(/\/$/, ''))
+    .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d))
+    .sort();
+  return days.length ? days[0] : null;
+}
+
 export default {
+  /** Hourly cron. Builds every complete hour back to the oldest raw data. */
+  async scheduled(event, env) {
+    // Backfill reaches all the way to the oldest surviving raw day, NOT a fixed
+    // window. A fixed window silently strands everything older than it the
+    // moment analysis stopped reading sessions/ — the raw objects are still
+    // there, but nothing would ever compact them, so they vanish from every
+    // report. Bounding by real data instead means the floor rises only when a
+    // lifecycle rule actually expires the raw objects.
+    const oldest = await oldestRawDay(env);
+    if (!oldest) return;
+    const floorMs = Date.parse(`${oldest}T00:00:00Z`);
+    if (Number.isNaN(floorMs)) return;
+
+    // Only list from the floor forward. Rollups older than the oldest raw day
+    // can never be rebuilt, so enumerating them answers nothing — this is what
+    // keeps the listing bounded by retention rather than by total history.
+    const done = new Set();
+    let cursor;
+    do {
+      const page = await env.CORPUS.list({
+        prefix: 'rollup/',
+        startAfter: `rollup/dt=${oldest}`,
+        cursor,
+      });
+      for (const o of page.objects) {
+        // Tolerates both `<part>/data.ndjson` and the `<part>/empty` marker.
+        const rel = o.key.slice('rollup/'.length);
+        const cut = rel.lastIndexOf('/');
+        if (cut > 0) done.add(rel.slice(0, cut));
+      }
+      cursor = page.truncated ? page.cursor : undefined;
+    } while (cursor);
+
+    // Newest first, so a backlog drains from the present backwards and the
+    // freshest hour is never the one starved by the budget. Starts one hour
+    // back: the current hour is still being written to.
+    let budget = READ_BUDGET;
+    for (let t = event.scheduledTime - 3600_000; t >= floorMs && budget > 0; t -= 3600_000) {
+      const part = partition(new Date(t));
+      if (done.has(part)) continue;
+      // Shared with rollupHour so a throw still reports what it spent.
+      const spend = { read: 0 };
+      try {
+        await rollupHour(env, part, spend);
+      } catch (err) {
+        // Newest-first means an hour that always throws — one grown past the
+        // subrequest ceiling, say — would otherwise block every older hour
+        // behind it forever. Skip it and keep draining; it has no marker, so
+        // the next run retries it.
+        console.error(`rollup ${part} failed after ${spend.read} objects: ${err}`);
+      }
+      budget -= spend.read;
+    }
+  },
+
   async fetch(request, env, ctx) {
     if (request.method !== 'POST') {
       return new Response('beacon: POST OTLP logs to /v1/logs', { status: 405 });
@@ -134,14 +322,13 @@ export default {
     }
     if (records.length === 0) return new Response(null, { status: 204 });
 
-    const now = new Date();
-    const day = now.toISOString().slice(0, 10);
-    const hour = now.toISOString().slice(11, 13);
     // Hive-style partitioning so DuckDB can prune by date without a catalog.
-    // ponytail: one object per request. At beacon volume that is a few hundred
-    // thousand objects a month, which globs fine. Add a daily compaction job
-    // when the file count starts to slow queries, not before.
-    const key = `sessions/dt=${day}/hh=${hour}/${crypto.randomUUID()}.json`;
+    // Shares partition() with the rollup: the cron lists `sessions/<part>/`, so
+    // two independent spellings of this scheme would mean the writer and the
+    // compactor could drift apart and silently match zero objects.
+    // ponytail: one object per request. Compacted hourly into rollup/ by
+    // scheduled() above — analysis reads that, never this.
+    const key = `sessions/${partition(new Date())}/${crypto.randomUUID()}.json`;
     const ndjson = records.map((r) => JSON.stringify(r)).join('\n');
 
     // Respond immediately; durability work continues after the response.
diff --git a/deploy/beacon/wrangler.toml b/deploy/beacon/wrangler.toml
index 412b22045..826dba6bb 100644
--- a/deploy/beacon/wrangler.toml
+++ b/deploy/beacon/wrangler.toml
@@ -32,6 +32,24 @@ bucket_name = "headroom-telemetry"
 #   npx wrangler secret put METRICS_OTLP_AUTH
 # Absent = R2 only, which is the right place to start.
 
+# Hourly compaction of sessions/ into rollup/ — see scheduled() in worker.js.
+# At :05 so the hour being rolled up is definitely closed. A >=1h interval also
+# buys the 15-minute CPU limit instead of 30s, which the backfill run needs.
+[triggers]
+crons = ["5 * * * *"]
+
+# Every R2 binding call is a subrequest, and one hour is already ~4k objects.
+# The paid default of 10k would cap a run at two hours and stall the backfill
+# behind live traffic forever. This only raises a ceiling; a normal run spends
+# ~4k. READ_BUDGET in worker.js is what actually bounds the work.
+#
+# Workers Paid only — on the Free plan this key is rejected outright ("CPU
+# limits are not supported for the Free plan"), and the cron could not run
+# anyway: Free gives a scheduled handler 10ms of CPU, and parsing an hour of
+# heartbeats is tens of ms.
+[limits]
+subrequests = 100000
+
 [observability]
 enabled = true
 
diff --git a/docker-bake.hcl b/docker-bake.hcl
index 07397c965..f7ca8aacd 100644
--- a/docker-bake.hcl
+++ b/docker-bake.hcl
@@ -10,7 +10,7 @@ target "runtime-default" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime"
   args = {
-    HEADROOM_EXTRAS = "proxy"
+    HEADROOM_EXTRAS = "proxy,bedrock"
     RUNTIME_USER    = "nonroot"
   }
 }
@@ -19,7 +19,7 @@ target "runtime" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime"
   args = {
-    HEADROOM_EXTRAS = "proxy"
+    HEADROOM_EXTRAS = "proxy,bedrock"
     RUNTIME_USER    = "root"
   }
 }
@@ -28,7 +28,7 @@ target "runtime-nonroot" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime"
   args = {
-    HEADROOM_EXTRAS = "proxy"
+    HEADROOM_EXTRAS = "proxy,bedrock"
     RUNTIME_USER    = "nonroot"
   }
 }
@@ -37,7 +37,7 @@ target "runtime-code" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime"
   args = {
-    HEADROOM_EXTRAS = "proxy,code"
+    HEADROOM_EXTRAS = "proxy,code,bedrock"
     RUNTIME_USER    = "root"
   }
 }
@@ -46,7 +46,7 @@ target "runtime-code-nonroot" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime"
   args = {
-    HEADROOM_EXTRAS = "proxy,code"
+    HEADROOM_EXTRAS = "proxy,code,bedrock"
     RUNTIME_USER    = "nonroot"
   }
 }
@@ -55,7 +55,7 @@ target "runtime-slim" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime-slim"
   args = {
-    HEADROOM_EXTRAS = "proxy"
+    HEADROOM_EXTRAS = "proxy,bedrock"
     RUNTIME_USER    = "root"
   }
 }
@@ -64,7 +64,7 @@ target "runtime-slim-nonroot" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime-slim"
   args = {
-    HEADROOM_EXTRAS = "proxy"
+    HEADROOM_EXTRAS = "proxy,bedrock"
     RUNTIME_USER    = "nonroot"
   }
 }
@@ -73,7 +73,7 @@ target "runtime-code-slim" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime-slim"
   args = {
-    HEADROOM_EXTRAS = "proxy,code"
+    HEADROOM_EXTRAS = "proxy,code,bedrock"
     RUNTIME_USER    = "root"
   }
 }
@@ -82,7 +82,7 @@ target "runtime-code-slim-nonroot" {
   inherits = ["_common", "docker-metadata-action"]
   target   = "runtime-slim"
   args = {
-    HEADROOM_EXTRAS = "proxy,code"
+    HEADROOM_EXTRAS = "proxy,code,bedrock"
     RUNTIME_USER    = "nonroot"
   }
 }
diff --git a/docker-compose.yml b/docker-compose.yml
index 47b707b2d..204aecb81 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,7 +10,7 @@
 #   3. point your LLM client at http://localhost:8787  (proxy)
 #
 # Just want the proxy without the memory features? You can run the proxy image
-# on its own (`docker run -p 8787:8787 ghcr.io/chopratejas/headroom`); the two
+# on its own (`docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom`); the two
 # database services below are only required for the memory/relevance features.
 #
 # Ports exposed on the host:
diff --git a/docs/content/docs/architecture.mdx b/docs/content/docs/architecture.mdx
index 089cfca7c..d8f754372 100644
--- a/docs/content/docs/architecture.mdx
+++ b/docs/content/docs/architecture.mdx
@@ -47,7 +47,7 @@ In proxy mode the server is a FastAPI app with per-provider handlers (Anthropic,
 
 The proxy assembles a small, ordered pipeline. Every transform is independent, safe to skip, and **fails open** — on any error it returns the content unchanged and the request still goes through.
 
-1. **Tool-result interceptor** *(opt-in)* — light structural interceptors such as ast-grep Read outlining. Off unless you pass `--intercept-tool-results`.
+1. **Tool-result interceptor** *(canary opt-in)* — light structural interceptors such as ast-grep Read outlining. Requires `HEADROOM_ROLLOUT_CHANNEL=canary` plus `--intercept-tool-results`.
 2. **CacheAligner** *(off by default)* — a detector that reports dynamic-prefix drift (dates, UUIDs, session tokens). It **never mutates, moves, or rewrites** content. It is disabled by default and hard-disabled inside the proxy; it exists to surface prefix-stability metrics, not to change your messages.
 3. **ContentRouter** — the workhorse that does essentially all of the compression. See below.
 
diff --git a/docs/content/docs/ccr.mdx b/docs/content/docs/ccr.mdx
index 18c4ff2c4..4d668b07c 100644
--- a/docs/content/docs/ccr.mdx
+++ b/docs/content/docs/ccr.mdx
@@ -73,13 +73,15 @@ When the LLM calls `headroom_retrieve`:
 
 The client never sees CCR tool calls on the Anthropic and OpenAI proxy paths; Headroom resolves them transparently there.
 
-<Callout type="warning" title="Current Gemini limitation">
-  Native Gemini requests do not yet run the server-side CCR response handler, so
-  `headroom_retrieve` is not resolved transparently on that path today. Google's
-  OpenAI-compatible Gemini endpoint can also return
-  `finish_reason=MALFORMED_FUNCTION_CALL` on large function-response continuations
-  after CCR retrieval. If you need fully transparent CCR resolution today, use the
-  Anthropic or OpenAI proxy paths. See [issue #2041](https://github.com/headroomlabs-ai/headroom/issues/2041).
+<Callout type="warning" title="Gemini CCR boundary">
+  Buffered native Gemini requests resolve `headroom_retrieve` server-side and
+  return the model's final response. Streaming native Gemini requests keep the
+  existing forwarding behavior. When a response contains `headroom_retrieve`
+  alongside a client-owned function call, Headroom preserves both calls for the
+  client instead of resolving the mixed response. Google's OpenAI-compatible Gemini endpoint can
+  also return `finish_reason=MALFORMED_FUNCTION_CALL` on large function-response
+  continuations after CCR retrieval; that separate limitation remains tracked in
+  [issue #2041](https://github.com/headroomlabs-ai/headroom/issues/2041).
 </Callout>
 
 ## Phase 4: Context Tracker
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdx
index 40ee56530..c8a4fca82 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/configuration.mdx
@@ -5,6 +5,20 @@ description: All configuration options for the Headroom Python and TypeScript SD
 
 Headroom can be configured via the SDK constructor, proxy command line, environment variables, or per-request overrides.
 
+## Runtime Rollout Channels
+
+Headroom uses rollout channels to control which behaviors an already-installed
+artifact may expose. They do not select a package or released version.
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HEADROOM_ROLLOUT_CHANNEL` | `stable` | Selects `stable`, `beta`, `canary`, or `dev`. |
+| `HEADROOM_FEATURES` | unset | Comma-separated feature names to request explicitly. |
+| `HEADROOM_DISABLE_FEATURES` | unset | Comma-separated feature names to force off. Disable wins over every enable path. |
+| `HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES` | unset | Break-glass override for emergency mitigation only. |
+
+See [Runtime Rollouts](/docs/runtime-rollouts) for policy, provenance, and
+contributor rules.
 If Codex history disappeared after using an older wrapper, see [Recover Codex State](/docs/codex-recovery) before wrapping Codex again.
 
 ## SDK Modes (`default_mode` / `headroom_mode`)
@@ -294,6 +308,7 @@ headroom proxy --learn --min-evidence 3
 | `HEADROOM_REQUEST_TIMEOUT` | Request timeout in seconds | `300` |
 | `HEADROOM_BETA_HEADER_STICKY` | Controls per-session `anthropic-beta` / `OpenAI-Beta` re-echo. `enabled` (default): the proxy unions beta tokens across turns within a session — if the client sends a token in turn N and omits it in turn N+1, the proxy re-injects it to preserve prefix-cache stability. `disabled`: the client's value is forwarded verbatim with no accumulation. Any other value raises at request time. See [Session Beta Header Tracking](/docs/configuration#session-beta-header-tracking). | `enabled` |
 | `HEADROOM_BETA_TRACKER_MAX_SESSIONS` | LRU capacity of the in-memory session beta tracker. Once full, the oldest session entry is evicted. | `1000` |
+| `HEADROOM_PROXY_BETA_HEADER_STICKY` | Rust proxy: same per-conversation beta-token union as `HEADROOM_BETA_HEADER_STICKY`, applied to `anthropic-beta` / `openai-beta` on the intercepted `/v1/messages`, `/v1/chat/completions`, and `/v1/responses` routes. Requires the compression interceptor (`HEADROOM_PROXY_COMPRESSION=1`) — with it off the Rust proxy is a strict byte-pipe and this flag has no effect (startup warns). Unlike the Python tracker (keyed on model + system prompt), sessions are keyed per conversation, shared with the cache-drift detector — parallel conversations never inherit each other's tokens. `enabled` default; `disabled` forwards the client value verbatim and keeps no state. Tracker capacity is fixed at 1000 sessions. | `enabled` |
 | `HEADROOM_MODEL_ROUTER_ENABLED` | Enable cost-aware model routing. `1`/`true`/`yes`/`on`/`enabled` turns it on and requires `HEADROOM_MODEL_ROUTES`. See [Cost-aware model routing](/docs/configuration#cost-aware-model-routing). | `off` |
 | `HEADROOM_MODEL_ROUTES` | JSON array of ordered routing rules for cost-aware model routing (schema below). | -- |
 | `HEADROOM_THINKING_COMPACT` | Compact plain-text reasoning that models re-send every turn (Kimi/GLM/DeepSeek `reasoning_content` / inline `<think>`): Kompress it on warm turns, drop it on cold turns. No-op for Claude/Codex/OpenAI (encrypted reasoning). See [Cold-prefix hook](#cold-prefix-hook--reasoning-compaction). | `off` |
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 6a45b0b4c..d716df852 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -40,6 +40,7 @@
     "vscode-claude-code",
     "vscode-copilot",
     "opencode",
+    "opencode-deepseek",
     "grok-build",
     "mcp",
     "---Configuration---",
@@ -57,6 +58,7 @@
     "architecture",
     "ci-cd-flows",
     "releases",
+    "runtime-rollouts",
     "benchmarks",
     "limitations",
     "---Help---",
diff --git a/docs/content/docs/metrics.mdx b/docs/content/docs/metrics.mdx
index ea8c2577f..c07953d6a 100644
--- a/docs/content/docs/metrics.mdx
+++ b/docs/content/docs/metrics.mdx
@@ -113,7 +113,11 @@ HEADROOM_OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod
 | `HEADROOM_OTEL_SERVICE_NAME` | `headroom-proxy` | OTEL `service.name` |
 | `HEADROOM_OTEL_RESOURCE_ATTRIBUTES` | unset | Comma-separated resource attributes |
 
-Exported counters include `headroom.proxy.requests`, `headroom.proxy.tokens.input`, `headroom.proxy.tokens.output`, `headroom.proxy.tokens.saved`, and `headroom.proxy.cache.read_tokens` / `write_tokens`.
+Exported counters include `headroom.proxy.requests`, `headroom.proxy.tokens.input`, and
+`headroom.proxy.tokens.output`. `headroom.proxy.tokens.saved` is the all-layer total:
+message/compression savings plus tool-schema deferral savings. The component counter
+`headroom.proxy.tokens.tool_schema_saved` exposes the deferral portion separately;
+`headroom.compression.tokens.saved` remains the compression-pipeline component.
 
 Confirm the exporter is live with `curl -s http://localhost:8787/stats | jq .otel`.
 
diff --git a/docs/content/docs/opencode-deepseek.mdx b/docs/content/docs/opencode-deepseek.mdx
new file mode 100644
index 000000000..a9a3594af
--- /dev/null
+++ b/docs/content/docs/opencode-deepseek.mdx
@@ -0,0 +1,233 @@
+---
+title: OpenCode + DeepSeek
+description: Configure OpenCode to route DeepSeek traffic through the Headroom proxy for compression, output shaping, and savings visibility.
+---
+
+Save 20-60% on DeepSeek API costs with Headroom's context compression proxy.
+
+## How it works
+
+```
+OpenCode → Headroom Proxy (:8787) → DeepSeek API
+              ↑ compresses input
+              + shapes output
+```
+
+The proxy sits between OpenCode and DeepSeek. It compresses tool outputs, logs,
+and search results before they reach the model, then shapes responses to be
+concise. DeepSeek's API is OpenAI-compatible — one flag and you're running.
+
+---
+
+## 1. Install Headroom
+
+```bash
+pip install headroom-ai
+# or via uv:
+uv tool install headroom-ai
+```
+
+You get SmartCrusher (structural compression), the proxy, output shaping, and
+the MCP server — everything you need.
+
+---
+
+## 2. Get your DeepSeek API key
+
+Sign up at [platform.deepseek.com](https://platform.deepseek.com) and generate
+an API key.
+
+Store it somewhere safe:
+```bash
+export DEEPSEEK_API_KEY="sk-your-deepseek-key-here"
+```
+
+---
+
+## 3. Start the proxy
+
+```bash
+headroom proxy \
+  --port 8787 \
+  --openai-api-url https://api.deepseek.com/v1
+```
+
+The proxy auto-detects `api.deepseek.com` and labels itself "DeepSeek" on the
+dashboard. Verify it's running:
+
+```bash
+curl http://127.0.0.1:8787/health
+# → "status": "healthy"
+```
+
+To see which models the proxy exposes:
+```bash
+curl -s http://127.0.0.1:8787/v1/models \
+  -H "Authorization: Bearer sk-your-key" | jq '.data[].id'
+```
+
+### With output shaping (optional)
+
+Output shaping makes the model's responses shorter — fewer tokens, lower cost:
+
+```bash
+HEADROOM_ROLLOUT_CHANNEL=beta HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \
+headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1
+```
+
+Verbosity levels:
+
+| Level | Behavior |
+|---|---|
+| `1` | Skip preambles/postambles |
+| `2` | + Don't restate code/file content already in context (**recommended**) |
+| `3` | + Omit rationale unless asked |
+| `4` | Maximum — fragments, zero fluff |
+
+---
+
+## 4. Configure OpenCode
+
+**Note:** If you have an existing `~/.config/opencode/opencode.json` (for MCP
+servers, etc.), merge the provider section into that file. Having both `.json`
+and `.jsonc` in the same directory can cause conflicts.
+
+Edit `~/.config/opencode/opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "headroom/deepseek-v4-pro",
+  "provider": {
+    "headroom": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Headroom Proxy",
+      "options": {
+        "baseURL": "http://127.0.0.1:8787/v1",
+        "apiKey": "sk-your-deepseek-key"
+      },
+      "models": {
+        "deepseek-v4-pro": {
+          "name": "DeepSeek V4 Pro",
+          "limit": { "context": 1000000, "output": 384000 }
+        },
+        "deepseek-v4-flash": {
+          "name": "DeepSeek V4 Flash",
+          "limit": { "context": 1000000, "output": 384000 }
+        }
+      }
+    }
+  },
+  "mcp": {
+    "headroom": {
+      "type": "local",
+      "command": ["headroom", "mcp", "serve"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Important:** Only include model IDs that appear in the proxy's `/v1/models`
+response. OpenCode validates config models against the proxy's model list.
+The current DeepSeek model names are `deepseek-v4-pro` and `deepseek-v4-flash`.
+`deepseek-chat` and `deepseek-reasoner` are deprecated compatibility aliases.
+
+### Model comparison
+
+| Model | Input / Output (per 1M) | Context | Max Output |
+|---|---|---|---|
+| `deepseek-v4-pro` | $0.435 / $0.87 | 1M | 384K |
+| `deepseek-v4-flash` | $0.14 / $0.28 | 1M | 384K |
+
+Both models support **thinking mode** for step-by-step reasoning (see below).
+
+Switch models at any time with `/model` in OpenCode.
+
+---
+
+## 5. Start OpenCode
+
+```bash
+opencode
+```
+
+Run `/models` to confirm both DeepSeek models appear under "Headroom Proxy".
+Select one with `/model deepseek-v4-flash` or `/model deepseek-v4-pro`.
+
+---
+
+## 6. Check savings
+
+```bash
+curl http://127.0.0.1:8787/stats | python3 -m json.tool | grep -A5 compression
+```
+
+Or open the dashboard at [http://127.0.0.1:8787/dashboard](http://127.0.0.1:8787/dashboard).
+
+---
+
+## Thinking mode (reasoning)
+
+Both models support thinking mode natively, and DeepSeek enables it by default.
+This replaces the deprecated `deepseek-reasoner` (R1) model.
+See [DeepSeek's thinking mode docs](https://api-docs.deepseek.com/guides/thinking_mode)
+for details on switching between thinking and non-thinking modes.
+
+---
+
+## Common issues
+
+### "Authentication Fails" / Unauthorized
+
+The `apiKey` in OpenCode's config is missing or wrong. OpenCode must send the
+API key to the proxy, and the proxy forwards it to DeepSeek. Make sure
+`"apiKey": "sk-..."` is set under `options`.
+
+### Models don't appear under "Headroom Proxy"
+
+1. Verify the proxy is running: `curl http://127.0.0.1:8787/health`
+2. Check which models the proxy exposes: `curl -s http://127.0.0.1:8787/v1/models -H "Authorization: Bearer sk-your-key"`
+3. Make sure your config model IDs match **exactly** what the proxy returns
+4. Don't use both `opencode.json` and `opencode.jsonc` in the same config directory — use one file
+
+### Models appear but requests fail
+
+You ran `headroom wrap opencode`. That command replaces your config with Claude
+and GPT models. **Do not use `headroom wrap`.** Configure OpenCode manually as
+shown above, and launch OpenCode directly with `opencode`.
+
+### "headroom" command not found
+
+`uv tool install` puts binaries in `~/.local/bin/`. Add it to your PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Output shaping shows no savings
+
+Output savings are measured against a learned baseline (it compares "what the
+model actually emitted" vs "what it would have emitted unshaped"). After a few
+sessions, run:
+
+```bash
+headroom learn --verbosity --apply
+```
+
+This builds the baseline, and `/stats` will show output savings numbers. The
+shaper is active immediately — the numbers just need calibration.
+
+---
+
+## What's NOT in this guide
+
+- **Claude or GPT models** — this setup uses DeepSeek exclusively
+- **`headroom wrap`** — do not use it; it overrides the config
+- **Deprecated model names** — `deepseek-chat` and `deepseek-reasoner` are
+  compatibility aliases that will be deprecated on 2026-07-24; use
+  `deepseek-v4-pro` and `deepseek-v4-flash` instead
+- **Kompress (ML compression)** — requires extra dependencies; SmartCrusher
+  handles the majority of use cases
+- **Any code changes** — headroom ships full DeepSeek support natively
+  (model tables, pricing, tokenizers, domain detection)
diff --git a/docs/content/docs/pipeline-extensions.mdx b/docs/content/docs/pipeline-extensions.mdx
index c98455e59..a525404ee 100644
--- a/docs/content/docs/pipeline-extensions.mdx
+++ b/docs/content/docs/pipeline-extensions.mdx
@@ -77,3 +77,26 @@ curl http://localhost:8787/v1/chat/completions \
 ```
 
 Internal `x-headroom-*` headers (including this one) are stripped before the request is forwarded upstream by default — see `HEADROOM_STRIP_INTERNAL_HEADERS` in [Configuration](/docs/configuration).
+
+## Per-request model routing with `request.state.headroom_route`
+
+`x-headroom-base-url` is client-driven and points at one OpenAI-compatible base. When the choice of model belongs to an extension instead of the caller — a router that picks a cheaper model per turn, say — publish it on the request state and Headroom serves that one request from a backend that speaks the target provider:
+
+```python
+# middleware or an extension holding the request
+request.state.headroom_route = SimpleNamespace(
+    model="moonshot/kimi-k2",   # required
+    provider="moonshot",        # optional; inferred from the model id if absent
+    reason="cheaper at this prefix length",
+)
+```
+
+The contract, in `headroom/proxy/route_advice.py`:
+
+- **Absent means unchanged.** No advice — or advice that is malformed, names an unknown provider, or fails to build a backend — and the request takes exactly the path it took before. A routing preference can never take traffic down.
+- **Duck-typed**, so an extension does not import Headroom to publish one.
+- A **native** provider (`anthropic`) needs no backend switch — rewrite `body["model"]` yourself. A foreign one is translated by a `LiteLLMBackend` built for it, and Headroom writes the model id.
+- Backends are **built once per provider** and cached; a provider that fails to build is not retried per request.
+- Honored on `/v1/messages` and `/v1/chat/completions`, streaming and non-streaming alike. (Not the Responses API, which does not use the backend abstraction.)
+
+`routemegood` is the reference consumer of this seam: it decides, Headroom routes.
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx
index 0351e3181..35bb7a77f 100644
--- a/docs/content/docs/proxy.mdx
+++ b/docs/content/docs/proxy.mdx
@@ -68,7 +68,7 @@ Avoid setting process-wide variables such as `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_P
 |--------|---------|-------------|
 | `--mode token` | | Prioritize token compression; prior turns may be rewritten for maximum savings. |
 | `--mode cache` | default | Freeze prior turns to maximize provider prefix-cache hit rate. This is the effective default (see [Savings profiles](#savings-profiles)). |
-| `--intercept-tool-results` | `false` | Opt into tool-result interceptors such as ast-grep Read outlining. |
+| `--intercept-tool-results` | `false` | Opt into canary tool-result interceptors such as ast-grep Read outlining. Requires `HEADROOM_ROLLOUT_CHANNEL=canary` (or `dev`). |
 | `--no-read-lifecycle` | `false` | Disable stale/superseded Read-output compression. |
 | `--code-aware` / `--no-code-aware` | disabled | Enable or disable AST-based code compression. Requires `headroom-ai[code]`. |
 | `--code-graph` | `false` | Enable the proxy's live code-graph file watcher for the current project. |
@@ -249,7 +249,7 @@ Coding agents re-read the same files repeatedly; these control how stale reads a
 | Flag / env | Default | Effect |
 |---|---|---|
 | `--no-read-lifecycle` | lifecycle on | Stop replacing stale/superseded file reads with CCR markers. |
-| `--read-maturation` / `HEADROOM_READ_MATURATION` | `false` | *(Experimental)* Hold freshly-read files out of the prefix cache until the file quiesces. |
+| `--read-maturation` / `HEADROOM_READ_MATURATION` | `false` | *(Beta)* Hold freshly-read files out of the prefix cache until the file quiesces. Requires `HEADROOM_ROLLOUT_CHANNEL=beta` (or `dev`). |
 | `--read-maturation-quiesce-turns` | `5` | Turns of no change before a held read is admitted. |
 
 ### Reliability: timeouts, retries, limits
diff --git a/docs/content/docs/releases.mdx b/docs/content/docs/releases.mdx
index bf58bbffc..c876f4080 100644
--- a/docs/content/docs/releases.mdx
+++ b/docs/content/docs/releases.mdx
@@ -16,10 +16,11 @@ For the end-to-end visual flow, see [CI/CD Flow Diagrams](/docs/ci-cd-flows).
 | Package | Type | Registry | Environment Variable |
 |---------|------|----------|----------------------|
 | `headroom-ai` | Python | PyPI | `PYPI_PACKAGE` |
-| `headroom-ai` | TypeScript SDK | npmjs.org | `NPM_SDK_PACKAGE` |
-| `headroom-openclaw` | TypeScript plugin | npmjs.org | `NPM_OPENCLAW_PACKAGE` |
-| `@{owner}/headroom-ai` | TypeScript SDK | GitHub Package Registry | — |
-| `@{owner}/headroom-openclaw` | TypeScript plugin | GitHub Package Registry | — |
+| `headroom-ai` | TypeScript SDK | npmjs.org | `NPM_SDK_PACKAGE` |
+| `headroom-openclaw` | TypeScript plugin | npmjs.org | `NPM_OPENCLAW_PACKAGE` |
+| `headroom-opencode` | TypeScript plugin | npmjs.org | `NPM_OPENCODE_PACKAGE` |
+| `@{owner}/headroom-ai` | TypeScript SDK | GitHub Package Registry | — |
+| `@{owner}/headroom-openclaw` | TypeScript plugin | GitHub Package Registry | — |
 | `headroom-ai-{version}.tar.gz` / `headroom_ai-{version}-py3-none-any.whl` | Python package distributions | GitHub Release (`{owner}/headroom`) | — |
 | `headroom-ai-{version}.tgz` / `headroom-openclaw-{version}.tgz` | Node release assets | GitHub Release (`{owner}/headroom`) | — |
 | `ghcr.io/{owner}/headroom` | Docker image | GitHub Container Registry | — |
@@ -41,6 +42,7 @@ Release Please calculates the release version from conventional commits and the
 - `pyproject.toml` - `[project].version`
 - `headroom/_version.py` - `__version__`, synced at build time
 - `plugins/openclaw/package.json` - `version`, synced at build time
+- `plugins/opencode/package.json` - `version`, synced at build time
 - `sdk/typescript/package.json` - `version`, synced at build time
 
 `release.yml` does not commit back to the repo. Version synchronization happens inside the release build workspace.
@@ -98,9 +100,10 @@ Installs the built wheels into representative customer environments and imports
 Downloads the Python dist artifact and publishes to PyPI via `pypa/gh-action-pypi-publish@release/v1` (trusted publisher).
 
 ### publish-npm
-Publishes both TypeScript packages to npmjs.org:
-- `sdk/typescript/` as `headroom-ai`
-- `plugins/openclaw/` as `headroom-openclaw`
+Publishes all npm packages to npmjs.org:
+- `sdk/typescript/` as `headroom-ai`
+- `plugins/openclaw/` as `headroom-openclaw`
+- `plugins/opencode/` as `headroom-opencode`
 
 ### publish-github-packages
 Publishes both Node packages to GitHub Package Registry (`npm.pkg.github.com`) using the current repository owner as the npm scope:
@@ -124,10 +127,11 @@ All package names, registry URLs, and environment names are defined as top-level
 env:
   PYPI_PACKAGE: headroom-ai
   PYPI_ENVIRONMENT: pypi
-  NPM_REGISTRY_URL: https://registry.npmjs.org
-  NPM_SDK_PACKAGE: headroom-ai
-  NPM_OPENCLAW_PACKAGE: headroom-openclaw
-  GITHUB_PACKAGES_REGISTRY_URL: https://npm.pkg.github.com
+  NPM_REGISTRY_URL: https://registry.npmjs.org
+  NPM_SDK_PACKAGE: headroom-ai
+  NPM_OPENCLAW_PACKAGE: headroom-openclaw
+  NPM_OPENCODE_PACKAGE: headroom-opencode
+  GITHUB_PACKAGES_REGISTRY_URL: https://npm.pkg.github.com
 ```
 
 To rename a package, update the corresponding constant — all references throughout the workflow update automatically.
diff --git a/docs/content/docs/runtime-rollouts.mdx b/docs/content/docs/runtime-rollouts.mdx
new file mode 100644
index 000000000..8dead2da9
--- /dev/null
+++ b/docs/content/docs/runtime-rollouts.mdx
@@ -0,0 +1,174 @@
+---
+title: Runtime Rollouts
+description: Deterministic runtime feature control for installed Headroom artifacts.
+---
+
+Runtime rollout answers one question: **which behaviors may this already-built
+Headroom artifact expose in this process?** It is separate from the source and
+distribution lifecycle, which decides which commit/artifact is qualified,
+released, packaged, and published.
+
+```bash
+HEADROOM_ROLLOUT_CHANNEL=canary headroom proxy
+```
+
+This runs the installed artifact with canary-eligible runtime features available
+according to that artifact's rollout policy. It does **not** install, select, or
+run a canary release/version of Headroom.
+
+## Channels and feature policy
+
+Channels are ordered `stable < beta < canary < dev`.
+
+| Channel | Purpose |
+|---------|---------|
+| `stable` | Default; behavior eligible for normal production use. |
+| `beta` | Opt-in behavior backed by automated and limited production evidence. |
+| `canary` | Early dogfood behavior still gathering evidence. |
+| `dev` | Local development and maintainer experiments. |
+
+Availability and default enablement are separate registry fields. A feature can
+be available in `canary` but remain off until explicitly requested; another can
+be available and default-enabled in `stable`.
+
+Request a named feature:
+
+```bash
+HEADROOM_ROLLOUT_CHANNEL=canary \
+HEADROOM_FEATURES=tool_result_interceptors \
+headroom proxy --intercept-tool-results
+```
+
+Force it off with the kill switch:
+
+```bash
+HEADROOM_DISABLE_FEATURES=tool_result_interceptors headroom proxy
+```
+
+## Resolution and precedence
+
+CLI arguments, environment variables, and typed configuration are resolved once
+at configuration construction. The immutable snapshot is injected into the
+proxy and transform pipelines; changing the process environment afterward does
+not alter a running proxy.
+
+The existing loopback-only `/admin/runtime-env` endpoint is one narrow
+exception: hot-reloading the legacy `HEADROOM_OUTPUT_SHAPER` alias replaces the
+proxy's immutable snapshot with a newly resolved snapshot. Channel bounds and
+`HEADROOM_DISABLE_FEATURES` still win, and `/stats.rollout` changes with the
+effective running decision. Because these overrides are process-local, the
+endpoint rejects updates when the built-in server uses multiple workers; restart
+the proxy with the desired environment instead. Ambient environment mutation
+remains ignored.
+
+Precedence is deterministic:
+
+| Condition | Result |
+|-----------|--------|
+| Explicit disable | Off, even if defaulted, requested, aliased, or unsafe override is active. |
+| Requested below its availability channel, unsafe override active | On with `unsafe_override`. |
+| Requested below its availability channel | Off with `blocked_by_channel`. |
+| Explicit request in an allowed channel | On with `explicit`. |
+| Enabled legacy alias in an allowed channel | On with `legacy_alias`. |
+| Default-enabled in the active channel | On with `default`. |
+| Otherwise | Off with `not_requested`. |
+
+Legacy feature-specific variables are narrow compatibility aliases only. They
+obey channel bounds and explicit disable precedence.
+
+## Unsafe override and invalid input
+
+`HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES=1` is a break-glass mechanism. It can
+cross a channel boundary for a requested feature, but cannot beat an explicit
+disable. The runtime remains usable for debugging and emergency reproduction,
+while its snapshot reports:
+
+```json
+{
+  "unsafe_override": true,
+  "qualification_eligible": false,
+  "qualification_ineligible_reason": "unsafe_rollout_override_active"
+}
+```
+
+The Python resolver logs a warning and falls back to `stable` for an unknown
+channel; unknown feature names are warned and ignored (fail-closed). Explicit
+Python diagnostics (`headroom rollout status`) and the Rust front proxy's typed
+CLI/environment parser reject unknown channels/features and list valid values
+before startup.
+
+## Machine-readable status and provenance
+
+Inspect a supplied configuration without starting the proxy:
+
+```bash
+headroom rollout status --json
+```
+
+Inspect the actual running process through the supported black-box endpoint:
+
+```bash
+curl http://127.0.0.1:8787/stats
+```
+
+The Python proxy publishes the object at `/stats.rollout`. The Rust front proxy,
+when deployed, publishes its own effective snapshot at `/rollout/status`; this
+keeps each process's distinct feature registry and decisions independently
+observable.
+
+The `/stats.rollout` object and CLI output contain no secrets. They include:
+
+```json
+{
+  "schema_version": 1,
+  "policy_version": "1",
+  "channel": "stable",
+  "unsafe_override": false,
+  "registry_digest": "sha256:...",
+  "snapshot_digest": "sha256:...",
+  "qualification_eligible": true,
+  "features": [
+    {
+      "name": "tool_result_interceptors",
+      "available_in": "canary",
+      "default_enabled_in": null,
+      "requested": false,
+      "disabled": false,
+      "enabled": false,
+      "decision": "not_requested"
+    }
+  ]
+}
+```
+
+`schema_version` versions the external JSON contract. `policy_version` versions
+the rollout rules. `registry_digest` is SHA-256 over canonical, ordered feature
+definitions. `snapshot_digest` identifies the complete effective runtime state.
+Equivalent policies/configurations produce equal digests; material policy or
+decision changes do not.
+
+These identities deliberately remain separate from source SHA, artifact SHA-256,
+runtime payload SHA-256, and future qualification-policy identities. An external
+benchmark can compare `/stats.rollout.registry_digest` and `snapshot_digest`
+between A1 passthrough and B Headroom arms without importing Headroom internals.
+A mismatch makes the future experiment invalid; benchmark logic itself is out of
+scope for runtime rollout.
+
+## Evidence-backed graduation and rollback
+
+Features progress from canary through beta toward stable only with linked
+deterministic, integration, and benchmark evidence. **Bake time is evidence, not
+qualification by itself.** Stable eligibility is followed by release
+qualification before behavior becomes a stable default.
+
+Every rollout-managed behavior must have a fast disable path. Operational
+rollback uses `HEADROOM_DISABLE_FEATURES`; source rollback reverts the defining
+change. The unsafe override is for diagnostics, not promotion or passing release
+evidence.
+
+Contributors should add named registry entries and tests for default behavior,
+explicit request, channel blocking, disable precedence, unsafe behavior,
+decision reasons, and provenance rather than reading rollout variables inside
+implementation components. Python and Rust registries contain features relevant
+to their own runtimes, but share channel ordering, precedence, decision reasons,
+fail-closed invalid-input semantics, and deterministic identity semantics.
diff --git a/docs/context-mode-integration-analysis.md b/docs/context-mode-integration-analysis.md
new file mode 100644
index 000000000..fc21c7bf1
--- /dev/null
+++ b/docs/context-mode-integration-analysis.md
@@ -0,0 +1,378 @@
+# context-mode → Headroom: enterprise plugin & variant analysis
+
+Analysis date: 2026-07-29. Sources: `/Users/tcms/demo/context-mode` @ v1.0.169, `/Users/tcms/demo/headroom` @ main.
+
+---
+
+## 1. Bottom line
+
+context-mode and Headroom attack the same cost problem at **two different layers**, and they do not
+overlap where it matters:
+
+| | context-mode | Headroom |
+|---|---|---|
+| Interception point | agent **tool-call boundary** (host hooks + MCP) | model **API boundary** (proxy / SDK / MCP) |
+| Position relative to context | **pre-context** — data never enters | **in-context** — data already entered, gets squeezed |
+| Mechanism | admission control: block, redirect, sandbox, externalize | compression: crush, cache, retrieve |
+| Touches the wire request | never | always |
+| Loss | lossless (full content in FTS5, queryable) | lossy squeeze + hash rehydrate |
+
+Headroom's own realignment doc identifies its correct compression target as the **live zone**:
+"latest user message content + latest `tool_result` + latest `function_call_output` + latest
+`local_shell_call_output`" (`REALIGNMENT/00-overview.md`, Phase B).
+
+**That is precisely the payload context-mode intercepts one layer earlier.** Headroom Phase B is
+building a Rust engine to compress the latest tool result *after* it hits the wire. context-mode
+stops that tool result from being produced at all. These are complements, not competitors — and the
+upstream position is strictly cheaper: nothing to compress, nothing to cache-invalidate, no
+token-validation fallback needed.
+
+Three strategic unlocks, in order of value:
+
+1. **Cache safety.** Headroom's #1 identified bug class is prompt-cache busting from request
+   mutation (5 top-tier cache-killer bugs, `REALIGNMENT/00-overview.md`). context-mode has
+   *structurally zero* cache-bust risk because it never touches the request body.
+2. **Subscription safety.** The realignment flags "fingerprint-class subscription-revocation
+   risks" from `X-Headroom-*` header leakage, `anthropic-beta` mutation and re-serialization on
+   OAuth/subscription CLIs. A hook-layer product carries none of this — it is invisible to the
+   upstream. This is a *deployable-where-the-proxy-can't-go* capability.
+3. **Proxy-free deployment.** Headroom's value today requires being in the API path
+   (`127.0.0.1:8787`). Verified live this session: with the proxy down, `headroom_stats` returns all
+   zeros and `headroom_compress` no-ops. Enterprises that cannot reroute model traffic (TLS trust,
+   egress policy, subscription auth) currently get nothing. context-mode's hook+MCP model needs no
+   interposition.
+
+Zero references to context-mode exist in the Headroom tree today — clean slate.
+
+---
+
+## 2. context-mode: portable IP inventory
+
+41,617 lines of TypeScript, 11 MCP tools, 18 host adapters, npm-distributed
+(`context-mode@1.0.169`, 8 runtime deps, esbuild-bundled).
+
+Ranked by *how hard it would be for Headroom to rebuild*:
+
+### Tier 1 — genuinely hard, no Headroom equivalent
+
+**1. Cross-host hook adapter layer** — `src/adapters/**` (~10K LOC), `src/adapters/types.ts`,
+`src/adapters/detect.ts` (737 lines), `configs/` (18 hosts).
+Normalizes three incompatible paradigms — `json-stdio` (Claude Code, Gemini/Qwen, Copilot, Codex,
+Kimi, Cursor, Kiro, Antigravity), `ts-plugin` (OpenCode, KiloCode, OpenClaw), `mcp-only` (Zed, Pi,
+OMP) — behind one contract: normalized `PreToolUse` / `PostToolUse` / `PreCompact` /
+`SessionStart` events, a `PlatformCapabilities` matrix, and a 5-way decision
+(`allow | deny | modify | context | ask`). Per-host install, config-format, and self-heal machinery
+included (`hooks/heal-partial-install.mjs`, `scripts/plugin-cache-integrity.mjs`).
+*Why hard to rebuild:* the value is entirely in the accumulated per-host quirks. There is no spec to
+implement against.
+
+**2. Tool-boundary policy engine** — `src/security.ts` (889 lines).
+A real policy decision point, not a regex list: glob→regex compilation, chained-command splitting
+(`&&`/`;`/`|` with escape awareness), subshell extraction, deny/ask pattern ingestion from host
+settings files, project-boundary containment (`evaluateProjectContainment` — Issue #852: an approved
+`ctx_execute_file` cannot escape the repo via a path the user couldn't see), and a
+**shell-escape scanner** (`SHELL_ESCAPE_PATTERNS`, `extractShellCommands`) that detects
+`execSync`/`subprocess`/etc. embedded inside sandboxed *non-shell* code and re-evaluates the escaped
+command against policy.
+*Why hard to rebuild:* this is the sandbox-escape prevention layer. Getting it wrong is a CVE.
+
+**3. Multi-language sandbox executor** — `src/executor.ts` (785), `src/runPool.ts`,
+`src/exit-classify.ts`, `src/truncate.ts`.
+12 languages, stdout-only egress, timeouts, background detach, output caps, exit classification.
+Enforces the "Think in Code" contract: the agent programs the analysis, only the answer enters
+context.
+
+**4. Lossless externalization store** — `src/store.ts` (2,071 lines).
+Dual SQLite FTS5 index — a tokenized `chunks` table *plus* a `chunks_trigram` table for
+substring/identifier search where BM25 tokenization fails on code — with a `vocabulary` table and
+schema migration path. Auto-externalizes any output >100 KB into FTS5 and returns a pointer.
+Nothing is discarded; the model queries on demand.
+
+### Tier 2 — valuable, but partially duplicated in Headroom
+
+**5. Counterfactual savings accounting** — `src/session/analytics.ts` (3,085 lines),
+`src/session/project-attribution.ts`, `src/session/db.ts` (1,726).
+`ContextSavings`, `ThinkInCodeComparison`, `RealBytesStats`, `MultiAdapterLifetimeStats`,
+`enumerateAdapterDirs()`. Measures *what would have entered context but didn't* — a different and
+harder quantity than Headroom's `savings_ledger.py`, which records actual compression deltas.
+Session event ledger + `tool_calls` + resume + per-project attribution.
+
+**6. Multi-vendor pricing catalog** — `src/session/pricing.ts` + `model-prices.json`.
+61 curated models × 4 rate buckets (input / output / cache-read / cache-write), refreshed from
+litellm, unknown model → `null` rather than a silently wrong Claude rate.
+**Overlaps `headroom/pricing/*` heavily. Do not port.**
+
+### Tier 3 — do not port
+
+Compression heuristics, memory/graph/relevance, telemetry transport, dashboard, install UX,
+update-check. Headroom has all of these, more mature, and Phase B/H is actively consolidating them.
+
+---
+
+## 3. Headroom's actual extension seams
+
+Verified entry-point groups (all `importlib.metadata`-discovered, all opt-in):
+
+| Seam | Group | Contract | Source |
+|---|---|---|---|
+| Proxy extension | `headroom.proxy_extension` | `install(app: FastAPI, config: ProxyConfig) -> None` | `headroom/proxy/extensions.py:52` |
+| Pipeline extension | `headroom.pipeline_extension` | `on_pipeline_event(PipelineEvent) -> PipelineEvent \| None` over 11 stages | `headroom/pipeline.py:13,68` |
+| Learn plugin | `headroom.learn_plugin` | — | `headroom/learn/registry.py:44` |
+| Memory text store | `headroom.memory_text` | — | `headroom/memory/config.py:41`, `factory.py:57` |
+| Memory vector store | `headroom.memory_vector` | — | `headroom/memory/config.py:34` |
+| Memory store | `headroom.memory_store` | — | `headroom/memory/config.py:25` |
+| CCR backend | `headroom.ccr_backend` | — | `headroom/cache/compression_store.py:981` |
+| Compression hooks | (subclass, not entry point) | `pre_compress` / `compute_biases` / `post_compress` | `headroom/hooks.py:1-31` |
+
+Two things worth noting:
+
+- `headroom/proxy/extensions.py:32` states an explicit **stability contract**: changing
+  `install(app, config)` or the group name requires a deprecation cycle. This is a supported public
+  seam, not an accident.
+- `headroom/hooks.py:16` says outright: *"Headroom SaaS implements position-aware compression and
+  cross-turn deduplication via these hooks."* The open-core split is already designed in.
+
+**The exemplar to copy:** `plugins/headroom-oauth2/` — own `pyproject.toml`, own `LICENSE`, own
+`SPEC.md`, registers on `headroom.proxy_extension`, dormant until `--proxy-extension oauth2`,
+all config via env, "zero core changes." That is the enterprise plugin template.
+
+**The precedent to copy:** `headroom/lean_ctx/installer.py` and `headroom/rtk/installer.py` —
+Headroom already ships thin installers that adopt sibling products. `plugins/headroom-agent-hooks`
+already installs startup hooks into Claude Code and Copilot CLI. The socket exists.
+
+**The gap:** Headroom has *no tool-boundary interception anywhere*. It sees `tool_use`/`tool_result`
+only as message content after the fact (`headroom/parser.py`, `headroom/tokenizers/*`). Its
+`PipelineStage` enum has no tool-result stage. Everything context-mode does is upstream of
+Headroom's earliest hook.
+
+---
+
+## 4. Proposed plugins & variants
+
+Ranked by value ÷ effort.
+
+### P1 — `headroom-recall`: FTS5+trigram lossless store as `headroom.memory_text`
+
+**What:** port `src/store.ts` behind the existing `headroom.memory_text` seam.
+
+**Why this first:** it is the smallest diff onto an *already-existing* contract, and it fixes a real
+product limitation. Today `headroom_retrieve(hash)` requires you to *know the hash* — the tool
+description literally says "hash comes from compression markers like `[N items compressed... hash=abc123]`".
+With an FTS5-backed store you get `retrieve-by-query`: "what did that build log say about OOM"
+instead of "paste hash abc123". The trigram index matters specifically because BM25 tokenization
+loses identifiers and stack frames.
+
+Composes rather than replaces: `compress` → return squeezed text + hash → store the *original* in
+FTS5 → rehydrate by hash **or** by query. Also a natural `headroom.ccr_backend` implementation —
+the realignment wants "CCR hardens: persistent backend" (Phase B), and this is one.
+
+**Enterprise variant:** shared team store, retention/TTL policy, per-project scoping (context-mode
+already has `project-attribution.ts`), audit of every retrieval.
+
+**Effort:** medium. Reimplement in Python/Rust against Headroom's memory interface, or ship the
+node store as a sidecar. Do not port the MCP tool surface — only the store.
+
+### P2 — `headroom-admission`: tool-boundary admission control across 18 hosts
+
+**What:** context-mode's adapter + hook layer, distributed the way `plugins/openclaw` and
+`plugins/opencode` already are (TS package under `plugins/`), reporting savings into Headroom's
+`savings_ledger.py` JSONL and emitting Headroom pipeline events.
+
+**Why:** this is the strategic piece. It gives Headroom:
+- a **pre-wire** enforcement point, upstream of Phase B's live-zone engine, with no cache-bust and
+  no token-validation fallback required;
+- coverage of **18 agent hosts** — the realignment's Phase G wants to "extend wrap CLIs (cline,
+  continue, goose, openhands)"; this is that work already done, and then some;
+- a deployment mode that works under **subscription auth**, where the proxy is a revocation risk.
+
+**Enterprise value — this is the DLP story Headroom cannot currently tell.** A `curl` inside a Bash
+tool call never touches the proxy, so Headroom is blind to it. context-mode blocks
+`curl`/`wget`/`WebFetch`/inline `fetch()`/`requests.get` at the tool boundary and forces network
+egress through `ctx_fetch_and_index`. That converts a token-savings feature into an
+**egress-control** feature — a different budget line and a different buyer.
+
+**Effort:** high, but it's mostly packaging + a reporting bridge, not a rewrite. Keep it TypeScript;
+Phase H retires Python *proxy* code but explicitly preserves "CLI wrappers, RTK installer" — the
+installer layer is the surviving Python, and it can shell out.
+
+### P3 — `headroom-policy` (Enterprise, license-gated): the PDP
+
+**What:** `src/security.ts` as a policy decision point, plus centrally-managed org rulesets.
+
+Two attach points: the hook layer from P2 (tool-level `allow/deny/ask`), and
+`headroom.pipeline_extension` at `PRE_SEND` (prompt-level policy). Feeds `headroom/audit/`.
+
+**Enterprise features that only make sense paid:** central policy service, org-wide allow/deny
+rulesets, project-boundary containment enforcement, shell-escape detection inside sandboxed code,
+tamper-evident audit trail, per-team reporting. Gate it with the ELv2 license key (see §6).
+
+**Effort:** medium. The engine exists and is tested (`tests/security/`, `src/security.ts` 889 lines);
+the work is the control plane.
+
+### P4 — `headroom-sandbox`: Think-in-Code execution
+
+**What:** `executor.ts` exposed as a Headroom MCP tool (`headroom_execute`), 12 languages,
+stdout-only.
+
+**Why:** this is the mechanism behind context-mode's largest measured savings —
+`ctx_execute_file` returns 98% savings across 315 KB of real fixtures (`BENCHMARK.md` Part 1),
+versus 82% for index+search (Part 2). Programming the analysis beats compressing the output.
+
+Must ship *with* P3: the shell-escape scanner is what stops the sandbox being an escape hatch.
+
+**Effort:** medium-high. Runtime isolation is the hard part; `headroom` already has a `sandbox` extra
+in `pyproject.toml` to build on.
+
+### P5 — `headroom-attribution`: counterfactual savings + per-project cost
+
+**What:** port the *methodology* from `session/analytics.ts` — `RealBytesStats`,
+`ThinkInCodeComparison`, `enumerateAdapterDirs`, `project-attribution.ts` — into Headroom's
+`savings_ledger` / `reporting` / `dashboard`.
+
+**Why:** Headroom measures compression deltas (what it squeezed). context-mode measures the
+counterfactual (what never entered). Enterprise buyers want the second number, sliced by team and
+repo. Do **not** port `pricing.ts` — `headroom/pricing/*` already does this with litellm resolution.
+
+**Merge, don't port.** `headroom/audit/reads.py` is already a counterfactual measurement tool over
+the same Claude Code transcript corpus (see §8). It has the better mechanism taxonomy — identical
+repeat, subset containment, write-readback, stale, line-number scaffolding, context residency,
+cache-death windows. `analytics.ts` has the multi-host coverage and per-project attribution it
+lacks. Combine the two rather than adding a third implementation.
+
+**Effort:** low-medium, mostly a metrics-definition merge.
+
+### Variants (packaging, not code)
+
+- **Headroom No-Proxy Edition** — P1+P2 only, zero API interposition. Sells to buyers who cannot
+  reroute model traffic and to every subscription-auth user. Removes the single biggest deployment
+  blocker Headroom has.
+- **Headroom Admission Control (Enterprise)** — P2+P3+P4 with a central policy plane and fleet
+  enrollment across 18 hosts. Positioned as AI-agent DLP/governance, not token savings.
+- **Headroom Fleet** — P5 + `enumerateAdapterDirs` for org-wide rollout state and cost reporting.
+
+---
+
+## 5. Evidence base
+
+context-mode's `BENCHMARK.md`: 21 scenarios, 376 KB raw → 16.5 KB context, **96% overall**, all
+fixtures captured from real tool invocations (Context7, Playwright, `gh`, vitest, tsc, nginx logs,
+`git log`, analytics CSV) rather than synthetic. Honest about its weak cases — 13% on a 0.4 KB
+Playwright network dump, and Part 2 openly explains why index+search only reaches 50-93% (it returns
+exact code blocks rather than summaries, by design).
+
+Test suite: 125 tests across executor/store/MCP-integration/ecosystem, plus 45 test dirs in `tests/`
+covering adapters, security, session, hooks, analytics.
+
+That's a defensible enough evidence base to reuse in Headroom's own materials, and the fixture corpus
+itself is reusable for Headroom's `benchmarks/`.
+
+---
+
+## 6. Blockers — resolve these before writing code
+
+**1. License incompatibility (hard blocker).**
+context-mode is **Elastic License 2.0**, "Copyright 2026 Mert Koseoglu". Headroom is
+**Apache-2.0**, "Copyright 2025 Headroom Contributors".
+
+- ELv2 code **cannot** be merged into the Apache-2.0 core. Not a technicality — it would relicense
+  Headroom's core.
+- ELv2 forbids providing the software "to third parties as a hosted or managed service." That
+  directly constrains `headroom-managed/`.
+- Different copyright holders means this needs an **IP arrangement between entities**, not an
+  engineering decision.
+
+The good news: Headroom's plugin architecture is exactly the boundary that makes this tractable.
+A separate package with its own `pyproject.toml` and its own `LICENSE`, registered on an entry
+point — the `plugins/headroom-oauth2/` shape — can carry ELv2 while core stays Apache-2.0. ELv2 is
+also the *right* license for a license-key-gated enterprise tier; it explicitly contemplates one.
+
+Recommendation: any context-mode-derived code ships as separately-licensed plugin packages under
+`plugins/`, never vendored into `headroom/`. Get the IP arrangement in writing first.
+
+**2. Realignment collision.**
+Phases A–I are ~40 PRs / 8–13 weeks and include deleting ~25K LOC. Do not open a new integration
+front mid-Phase-B. P1 (`headroom.memory_text` / `ccr_backend`) is the exception — it *serves* Phase
+B's "CCR hardens: persistent backend" goal rather than competing with it.
+
+**3. Phase H direction.**
+Python proxy code is being retired. Write nothing new in `headroom/proxy/`. Target the surviving
+layers: installers, memory writers, CLI wrappers, and Rust.
+
+---
+
+## 7. Sequencing
+
+| Order | Item | Gate |
+|---|---|---|
+| 0 | IP/licensing arrangement | before any code |
+| 1 | P1 `headroom-recall` — FTS5 store on `memory_text`/`ccr_backend` | lands inside Phase B, serves it |
+| 2 | P2 `headroom-admission` — 18-host hook layer under `plugins/` | after Phase A stabilizes |
+| 3 | Variant: **No-Proxy Edition** = P1+P2 | as soon as P2 works on 3+ hosts |
+| 4 | P3 `headroom-policy` (Enterprise, ELv2, key-gated) | after P2 |
+| 5 | P4 `headroom-sandbox` | with P3, never before |
+| 6 | P5 `headroom-attribution` | opportunistic |
+
+---
+
+## 8. Follow-up verification
+
+All four items flagged as open in the first pass are now resolved.
+
+**`headroom-managed/` is the SaaS arm, and it is unlicensed.**
+`headroom-managed/pyproject.toml`: `name = "headroom-managed"`, `description = "Headroom SaaS
+Platform - Managed context window optimization"`, `version = 0.1.0`. It has `app/auth.py`,
+`app/middleware/`, `app/routes/`, `app/services/`, `app/models.py`, alembic migrations, and a
+`pilot/`. There is **no `license` field and no LICENSE file** — i.e. proprietary by default.
+
+This *sharpens* the §6 blocker rather than easing it. ELv2 forbids providing the software "to third
+parties as a hosted or managed service." The product whose name is literally *Managed* is the one
+place context-mode-derived code cannot go without an explicit commercial grant from the copyright
+holder. Plan the plugin boundary so that `headroom-managed` consumes only Apache-2.0 core
+interfaces, never ELv2 implementations.
+
+**`headroom/audit/reads.py` does not overlap P3 — and it independently validates the whole thesis.**
+It is a *measurement* tool, not an audit trail: it streams Claude Code `*.jsonl` transcripts to size
+"the addressable bytes for each Read compression mechanism... so defaults are set from traffic, not
+theory." No policy, no tamper-evidence. P3's audit trail remains a gap.
+
+Two lines in its docstring are the most useful corroboration in either repo:
+
+- *"context residency — how many assistant turns each Read stays in context (the multiplier on its
+  prefix-cache read cost; **the case for compress-before-cache-entry**)"* — Headroom is already
+  arguing, from its own traffic, for moving earlier in the pipeline. context-mode is the terminus of
+  that argument: compress before **context** entry, not merely before cache entry.
+- *"identical repeat — a dedup mechanism for this was prototyped and removed: it measured 0.1% of
+  Read bytes on real traffic."* — Headroom has already empirically established that
+  message-history-level dedup is worthless. The addressable bytes are at the tool boundary, not in
+  history. That is the same conclusion the realignment reached from the cache side, arrived at
+  independently from the traffic side.
+
+It *does* overlap **P5** — `audit/reads.py` and context-mode's `session/analytics.ts` are two
+independent implementations of counterfactual measurement over the same transcript corpus. Merge
+them rather than porting; `audit/reads.py` has the better mechanism taxonomy, `analytics.ts` has
+multi-host coverage and per-project attribution.
+
+**No plugin-authoring docs exist.** `docs/` is a Next.js site (`app/`, `content/`, `components/`);
+`wiki/` has nothing on extension authoring (only `macos-deployment.md` matched). `plugins/headroom-oauth2/SPEC.md`
+remains the de-facto authoring reference — which means whichever plugin lands first sets the house
+style. Worth writing the authoring doc as part of P1.
+
+**Headroom publishes no benchmark results.** `benchmarks/` is 29 runner scripts with no committed
+results artifacts, so no like-for-like number exists to compare against context-mode's 96%. The
+comparison has to be run. The harness is there and is unusually strong on exactly the axis that
+matters: `prefix_cache_benchmark.py`, `cache_bust_trace_report.py`, `cache_validation_bundle.py`,
+`synthetic_token_cache_bust_report.py`, `proxy_mode_benchmark.py`, `agent_cost_benchmark.py`,
+`real_world_agent_benchmark.py`. Use it to *prove* the §1 cache-safety claim empirically rather than
+asserting it — a measured "zero cache-bust events" result is the strongest possible artifact for the
+No-Proxy Edition.
+
+**Bonus finding — the platform axes are orthogonal.**
+`docs/platform-feature-matrix.json` (schema v1, updated 2026-07-06) tracks coverage across
+`["linux", "macos", "windows"]` — Headroom's platform axis is **operating system**. context-mode's
+platform axis is **agent host** (18 of them). Headroom tracks no host-coverage matrix at all. P2
+therefore fills a dimension that does not currently exist in Headroom's own feature accounting,
+which also means it needs a second matrix rather than new rows in this one.
+
+*Process note:* six subagents were dispatched across this analysis and all six stalled at the
+600-second watchdog; one reported "Bash is temporarily unavailable" before dying, so the failures
+were tool-layer, not analytical. Every finding in this document was verified directly.
diff --git a/docs/observability.md b/docs/observability.md
index b6de50dc6..b43f5a970 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -245,6 +245,21 @@ Every label vocabulary is bounded by code, not customer input:
   `"other"` and a `tracing::warn!` is emitted so wire-format drift
   surfaces loudly in logs.
 - `status`: 5-variant enum.
+- `tool` (Python-side `wrap_rtk_invocations_total`): bounded by the
+  set of tools the wrap CLI rewrites, captured by
+  `headroom.cli.wrap_rtk_metrics`.
+- `model` (Python-side `requests_by_model` /
+  `_cache_requests_by_model`): unlike the Rust path above, the Python
+  proxy reads `model` from the request body, so it is client-supplied.
+  It is bounded at record time by `MAX_DISTINCT_MODELS`
+  (`headroom.telemetry.context`): once the cap is reached, further
+  distinct models bucket into the `"other"` sentinel and a one-time
+  warning is logged, mirroring the `tier` discipline above. The
+  in-memory dicts and the exported `headroom_requests_by_model` series
+  can never exceed the cap plus `"other"`.
+
+Every label vocabulary listed above is bounded by code, so no
+client-supplied value can drive label cardinality unbounded.
 
 There is no code path where a malicious client can drive label
 cardinality unbounded.
diff --git a/docs/package-lock.json b/docs/package-lock.json
index 152001ff3..55bff9b41 100644
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@@ -35,7 +35,7 @@
 				"@types/react-dom": "^19.2.3",
 				"ai": "^6.0.149",
 				"openai": "^6.47.0",
-				"postcss": "^8.5.19",
+				"postcss": "^8.5.26",
 				"tailwindcss": "^4.2.2",
 				"typescript": "^5.9.3"
 			}
@@ -5629,9 +5629,9 @@
 			"license": "MIT"
 		},
 		"node_modules/nanoid": {
-			"version": "3.3.15",
-			"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.15.tgz",
-			"integrity": "sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==",
+			"version": "3.3.18",
+			"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+			"integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
 			"funding": [
 				{
 					"type": "github",
@@ -5816,9 +5816,9 @@
 			}
 		},
 		"node_modules/postcss": {
-			"version": "8.5.19",
-			"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.19.tgz",
-			"integrity": "sha512-Mz8SaolMd8nB+G13WkORcxQKHZ/NE4xXevtkJHVuG+guo9/wYKlIMTKAqGdEmYOXR2ijPjTYNHssizdaVSUNdQ==",
+			"version": "8.5.26",
+			"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
+			"integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
 			"funding": [
 				{
 					"type": "opencollective",
@@ -5835,7 +5835,7 @@
 			],
 			"license": "MIT",
 			"dependencies": {
-				"nanoid": "^3.3.12",
+				"nanoid": "^3.3.17",
 				"picocolors": "^1.1.1",
 				"source-map-js": "^1.2.1"
 			},
diff --git a/docs/package.json b/docs/package.json
index 6a2171274..21abffaf3 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -36,7 +36,7 @@
 		"@types/react-dom": "^19.2.3",
 		"ai": "^6.0.149",
 		"openai": "^6.47.0",
-		"postcss": "^8.5.19",
+		"postcss": "^8.5.26",
 		"tailwindcss": "^4.2.2",
 		"typescript": "^5.9.3"
 	},
diff --git a/e2e/wrap/run.py b/e2e/wrap/run.py
index 0120adc00..c28a8b1a9 100644
--- a/e2e/wrap/run.py
+++ b/e2e/wrap/run.py
@@ -790,6 +790,11 @@ def verify_vscode_wrap(base_env: dict[str, str], project_dir: Path) -> None:
             f'"http://127.0.0.1:{port}{project_prefix}"' in configured,
             "VS Code wrap should configure the project-scoped proxy URL",
         )
+        assert_true(
+            f'"github.copilot.advanced.debug.overrideCapiUrl": '
+            f'"http://127.0.0.1:{port}{project_prefix}"' in configured,
+            "VS Code wrap should route Copilot Chat generation through Headroom",
+        )
         assert_true(
             '"github.copilot.advanced.debug.overrideAuthType": "token"' in configured,
             "VS Code wrap should configure token auth",
@@ -849,8 +854,8 @@ def verify_vscode_claude_wrap(base_env: dict[str, str], project_dir: Path) -> No
             "VS Code Claude wrap should configure the project-scoped Anthropic URL",
         )
         assert_true(
-            configured["env"]["ENABLE_TOOL_SEARCH"] == "true",
-            "VS Code Claude wrap should retain Claude Code tool deferral",
+            configured["env"]["ENABLE_TOOL_SEARCH"] == "false",
+            "VS Code Claude wrap should disable tool deferral for webview compatibility",
         )
         assert_true(configured["env"]["KEEP"] == "yes", "Existing Claude env must remain")
         assert_true(str(settings_path) in output, "Wrap output should identify Claude settings")
diff --git a/headroom/_ort.py b/headroom/_ort.py
index 4a77d847a..8f10cd7bd 100644
--- a/headroom/_ort.py
+++ b/headroom/_ort.py
@@ -40,15 +40,40 @@ import importlib.util
 import logging
 import os
 import sys
+from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
 _ENV_VAR = "ORT_DYLIB_PATH"
+_MIN_RUST_ORT_API_VERSION = (1, 24)
 
 # Tri-state module cache: unset sentinel / resolved path / None (no pin).
 _UNSET = object()
 _pinned: object = _UNSET
+_pinned_from_override = False
+
+
+def _installed_ort_version() -> tuple[int, int] | None:
+    """Return the installed ONNX Runtime major/minor without importing it."""
+    try:
+        raw = version("onnxruntime")
+        return tuple(int(part) for part in raw.split(".")[:2])  # type: ignore[return-value]
+    except (PackageNotFoundError, ValueError):
+        return None
+
+
+def rust_ort_runtime_compatible() -> bool:
+    """Whether native Rust detection can safely initialize ORT C API 24.
+
+    A caller-supplied ``ORT_DYLIB_PATH`` remains an explicit override: its
+    library may be newer than the separately installed Python package. The
+    auto-pinned package library, however, must advertise at least 1.24.
+    """
+    if _pinned_from_override:
+        return True
+    installed = _installed_ort_version()
+    return installed is not None and installed >= _MIN_RUST_ORT_API_VERSION
 
 
 def ensure_ort_dylib_pinned() -> str | None:
@@ -84,12 +109,24 @@ def _resolve_ort_native_library(capi_dir: Path) -> Path | None:
 
 
 def _resolve_and_pin() -> str | None:
+    global _pinned_from_override
     try:
         existing = os.environ.get(_ENV_VAR)
         if existing:
+            _pinned_from_override = True
             logger.debug("%s already set; respecting user override: %s", _ENV_VAR, existing)
             return existing
 
+        installed = _installed_ort_version()
+        if installed is not None and installed < _MIN_RUST_ORT_API_VERSION:
+            logger.warning(
+                "onnxruntime %d.%d exposes an older C API than Rust detection "
+                "requires (1.24+); leaving %s unset and using Python detection",
+                *installed,
+                _ENV_VAR,
+            )
+            return None
+
         spec = importlib.util.find_spec("onnxruntime")
         if spec is None or not spec.origin:
             logger.debug(
diff --git a/headroom/backends/anyllm.py b/headroom/backends/anyllm.py
index 468d20450..c1e02b35f 100644
--- a/headroom/backends/anyllm.py
+++ b/headroom/backends/anyllm.py
@@ -25,6 +25,44 @@ except ImportError:
     AnyLLM = None  # type: ignore
 
 
+def _convert_anthropic_tool(tool: dict[str, Any]) -> dict[str, Any]:
+    """Convert an Anthropic tool definition to the OpenAI function shape.
+
+    any-llm speaks OpenAI, so an Anthropic ``{name, description, input_schema}``
+    tool must become ``{type: function, function: {name, description,
+    parameters}}`` before it is forwarded, or the provider ignores/rejects the
+    tools array and the model never calls a tool. Mirrors the LiteLLM backend's
+    converter so both OpenAI-compatible backends send the same shape.
+    """
+    func: dict[str, Any] = {"name": tool.get("name", "")}
+    if "description" in tool:
+        func["description"] = tool["description"]
+    if "input_schema" in tool:
+        func["parameters"] = tool["input_schema"]
+    return {"type": "function", "function": func}
+
+
+def _convert_tool_choice(choice: Any) -> Any:
+    """Convert an Anthropic ``tool_choice`` to the OpenAI shape (mirrors LiteLLM).
+
+    Anthropic: ``{"type": "auto"}``, ``{"type": "any"}``, ``{"type": "tool",
+    "name": ...}``. OpenAI: ``"auto"``, ``"required"``, ``{"type": "function",
+    "function": {"name": ...}}``. Passing the raw Anthropic dict through makes
+    the provider reject or ignore it.
+    """
+    if isinstance(choice, str):
+        return choice
+    if isinstance(choice, dict):
+        choice_type = choice.get("type", "auto")
+        if choice_type == "auto":
+            return "auto"
+        if choice_type == "any":
+            return "required"
+        if choice_type == "tool":
+            return {"type": "function", "function": {"name": choice.get("name", "")}}
+    return "auto"
+
+
 class AnyLLMBackend(Backend):
     """Backend using any-llm for multi-provider support."""
 
@@ -251,9 +289,9 @@ class AnyLLMBackend(Backend):
             if "stop_sequences" in body:
                 kwargs["stop"] = body["stop_sequences"]
             if "tools" in body:
-                kwargs["tools"] = body["tools"]
+                kwargs["tools"] = [_convert_anthropic_tool(t) for t in body["tools"]]
             if "tool_choice" in body:
-                kwargs["tool_choice"] = body["tool_choice"]
+                kwargs["tool_choice"] = _convert_tool_choice(body["tool_choice"])
 
             logger.debug(f"any-llm request: provider={self.provider}, model={original_model}")
 
@@ -301,9 +339,9 @@ class AnyLLMBackend(Backend):
             if "stop_sequences" in body:
                 kwargs["stop"] = body["stop_sequences"]
             if "tools" in body:
-                kwargs["tools"] = body["tools"]
+                kwargs["tools"] = [_convert_anthropic_tool(t) for t in body["tools"]]
             if "tool_choice" in body:
-                kwargs["tool_choice"] = body["tool_choice"]
+                kwargs["tool_choice"] = _convert_tool_choice(body["tool_choice"])
 
             msg_id = f"msg_{uuid.uuid4().hex[:24]}"
 
@@ -324,42 +362,131 @@ class AnyLLMBackend(Backend):
                 },
             )
 
-            yield StreamEvent(
-                event_type="content_block_start",
-                data={
-                    "type": "content_block_start",
-                    "index": 0,
-                    "content_block": {"type": "text", "text": ""},
-                },
-            )
-
             stream_response = await self.llm.acompletion(**kwargs)
             output_tokens = 0
+            # Stream text immediately in a single text block, but BUFFER tool
+            # calls and emit them as complete blocks at the end. OpenAI streams
+            # parallel tool calls interleaved by index (index 0 and 1 introduced
+            # together, then a fragment for 0, then for 1), while Anthropic
+            # requires each content block to be fully emitted — start, deltas,
+            # stop — before the next opens. Reassembling per index and flushing
+            # complete blocks keeps every delta inside its own block's start/stop
+            # for any interleaving. (The previous version pre-opened one text
+            # block and dropped tool calls entirely; a naive open-on-new-index
+            # instead mis-sequenced parallel calls, emitting a fragment for an
+            # already-stopped block.)
+            current_block_index = -1
+            text_block_open = False
+            # provider tool index -> {"id", "name", "arguments"}, first-seen order
+            tool_calls: dict[int, dict[str, Any]] = {}
+            tool_order: list[int] = []
+            stop_reason = "end_turn"
 
             async for chunk in cast(AsyncIterator[Any], stream_response):
-                if hasattr(chunk, "choices") and chunk.choices:
-                    delta = chunk.choices[0].delta
-                    if hasattr(delta, "content") and delta.content:
+                if not (hasattr(chunk, "choices") and chunk.choices):
+                    continue
+                choice = chunk.choices[0]
+                delta = choice.delta
+
+                # Map OpenAI finish_reason to the Anthropic stop_reason so a tool
+                # call or a length truncation is not reported as end_turn.
+                finish_reason = getattr(choice, "finish_reason", None)
+                if finish_reason == "tool_calls":
+                    stop_reason = "tool_use"
+                elif finish_reason == "length":
+                    stop_reason = "max_tokens"
+                elif finish_reason == "stop":
+                    stop_reason = "end_turn"
+
+                if getattr(delta, "tool_calls", None):
+                    for tc in delta.tool_calls:
+                        idx = tc.index if getattr(tc, "index", None) is not None else 0
+                        buf = tool_calls.get(idx)
+                        if buf is None:
+                            buf = {"id": None, "name": "", "arguments": ""}
+                            tool_calls[idx] = buf
+                            tool_order.append(idx)
+                        if getattr(tc, "id", None):
+                            buf["id"] = tc.id
+                        func = getattr(tc, "function", None)
+                        if func is not None:
+                            if getattr(func, "name", None):
+                                buf["name"] = func.name
+                            if getattr(func, "arguments", None):
+                                buf["arguments"] += func.arguments
+
+                elif getattr(delta, "content", None):
+                    if not text_block_open:
+                        current_block_index += 1
+                        text_block_open = True
                         yield StreamEvent(
-                            event_type="content_block_delta",
+                            event_type="content_block_start",
                             data={
-                                "type": "content_block_delta",
-                                "index": 0,
-                                "delta": {"type": "text_delta", "text": delta.content},
+                                "type": "content_block_start",
+                                "index": current_block_index,
+                                "content_block": {"type": "text", "text": ""},
                             },
                         )
-                        output_tokens += 1
+                    yield StreamEvent(
+                        event_type="content_block_delta",
+                        data={
+                            "type": "content_block_delta",
+                            "index": current_block_index,
+                            "delta": {"type": "text_delta", "text": delta.content},
+                        },
+                    )
+                    output_tokens += 1
 
-            yield StreamEvent(
-                event_type="content_block_stop",
-                data={"type": "content_block_stop", "index": 0},
-            )
+            # Close the text block before any tool blocks (Anthropic orders
+            # content blocks sequentially, text then tool_use).
+            if text_block_open:
+                yield StreamEvent(
+                    event_type="content_block_stop",
+                    data={"type": "content_block_stop", "index": current_block_index},
+                )
+
+            # Flush each buffered tool call as a complete, self-contained block:
+            # start, one input_json_delta with the reassembled arguments, stop.
+            for idx in tool_order:
+                buf = tool_calls[idx]
+                current_block_index += 1
+                tool_id = buf["id"] or f"toolu_{uuid.uuid4().hex[:24]}"
+                yield StreamEvent(
+                    event_type="content_block_start",
+                    data={
+                        "type": "content_block_start",
+                        "index": current_block_index,
+                        "content_block": {
+                            "type": "tool_use",
+                            "id": tool_id,
+                            "name": buf["name"],
+                            "input": {},
+                        },
+                    },
+                )
+                if buf["arguments"]:
+                    yield StreamEvent(
+                        event_type="content_block_delta",
+                        data={
+                            "type": "content_block_delta",
+                            "index": current_block_index,
+                            "delta": {
+                                "type": "input_json_delta",
+                                "partial_json": buf["arguments"],
+                            },
+                        },
+                    )
+                    output_tokens += 1
+                yield StreamEvent(
+                    event_type="content_block_stop",
+                    data={"type": "content_block_stop", "index": current_block_index},
+                )
 
             yield StreamEvent(
                 event_type="message_delta",
                 data={
                     "type": "message_delta",
-                    "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+                    "delta": {"stop_reason": stop_reason, "stop_sequence": None},
                     "usage": {"output_tokens": output_tokens},
                 },
             )
diff --git a/headroom/backends/litellm.py b/headroom/backends/litellm.py
index 8430789ce..0297474d4 100644
--- a/headroom/backends/litellm.py
+++ b/headroom/backends/litellm.py
@@ -413,6 +413,81 @@ PROVIDER_REGISTRY: dict[str, ProviderConfig] = {
 }
 
 
+# How long an upstream call may go silent before we give up on it.
+#
+# WHY THIS EXISTS. There was no timeout here at all, so a request the upstream
+# never answered blocked its caller forever. Observed 2026-08-07 under load:
+# four agent workers sat on ESTABLISHED connections for 36+ minutes while this
+# proxy answered /readyz in 0.11s. No error, no retry, no log line -- the
+# client just stops. That is the worst shape a failure can take, because it is
+# indistinguishable from slow work and no supervisor can tell the difference.
+#
+# A float, not an httpx.Timeout, on purpose: litellm expands a float into all
+# four httpx phases, so for a STREAMING call this becomes the maximum gap
+# BETWEEN CHUNKS rather than a cap on total generation time. A long answer
+# streaming steadily is never cut off; a stalled one dies. That is the
+# semantic we want, and it falls out of the simpler type.
+#
+# 600s is deliberately generous -- long enough that no healthy call is at
+# risk, short enough that a hang surfaces within a coffee break instead of
+# never.
+UPSTREAM_TIMEOUT_ENV = "HEADROOM_UPSTREAM_TIMEOUT"
+DEFAULT_UPSTREAM_TIMEOUT = 600.0
+
+
+def _upstream_timeout() -> float:
+    """Seconds. Never raises; a junk env value must not disable the timeout."""
+    import os
+
+    try:
+        v = float(os.getenv(UPSTREAM_TIMEOUT_ENV, DEFAULT_UPSTREAM_TIMEOUT))
+    except (TypeError, ValueError):
+        return DEFAULT_UPSTREAM_TIMEOUT
+    # 0 or negative would mean "no timeout" to httpx, which is the bug.
+    return v if v > 0 else DEFAULT_UPSTREAM_TIMEOUT
+
+
+# Providers that cannot possibly accept an Anthropic `sk-ant-` credential.
+#
+# Explicit, rather than the inverse "anything not Anthropic": an unrecognised
+# provider is usually a compatible or self-hosted gateway, and guessing wrong
+# there drops a key that WAS working. Bedrock/Vertex are absent because the
+# dispatch sites already skip them entirely (env-based auth).
+#
+# ponytail: a hand-kept tuple; grow it as targets are confirmed. A registry
+# lookup would be the upgrade if this ever outgrows a handful of entries.
+_REJECTS_ANTHROPIC_KEY = ("openai", "azure", "gemini")
+
+
+def _caller_key_travels_to(model: str, key: str) -> bool:
+    """Can this inbound credential authenticate the provider we are about to call?
+
+    The caller authenticates to the PROXY. A routing extension may then rewrite
+    the model across families mid-request (claude-opus-5 -> gpt-5-mini), and the
+    caller's key does not travel with that rewrite: we forward `sk-ant-...` to
+    OpenAI and earn a guaranteed 401, which reads downstream as "the cheap model
+    failed the task" rather than as the routing bug it is.
+
+    Only an unambiguous mismatch is refused. `sk-ant-` is Anthropic's documented
+    vendor-specific prefix, so it cannot authenticate one of the providers above.
+    Every other credential -- a plain Bearer token, an OpenAI-style `sk-` that a
+    dozen vendors also mint, anything aimed at a compatible or custom gateway --
+    is unclassifiable from the string alone and keeps the pass-through.
+
+    Returning False drops the api_key kwarg, so litellm falls back to the target
+    provider's own env credential: the only key that can work.
+    """
+    if not key.startswith("sk-ant-"):
+        return True
+    try:
+        from litellm import get_llm_provider
+
+        provider = (get_llm_provider(model)[1] or "").lower()
+    except Exception:  # noqa: BLE001 - unclassifiable model, keep pass-through
+        return True
+    return provider not in _REJECTS_ANTHROPIC_KEY
+
+
 def get_provider_config(provider: str) -> ProviderConfig:
     """Get provider config, with fallback for unknown providers."""
     if provider in PROVIDER_REGISTRY:
@@ -622,6 +697,21 @@ class LiteLLMBackend(Backend):
             if anthropic_model.startswith("arn:aws:"):
                 return f"bedrock/converse/{anthropic_model}"
 
+            # Cross-region prefixed IDs are already fully qualified system-defined
+            # profile IDs — pass through directly.  Normalizing and re-looking them
+            # up in the discovery map can route the request to a wrong or
+            # unauthorized profile (e.g. an APPLICATION profile in the same account
+            # that also wraps the same foundation model). This applies whether the
+            # prefix arrives bare ("us.anthropic...") or already LiteLLM-qualified
+            # ("bedrock/us.anthropic...").
+            _CROSS_REGION_PREFIXES = ("au.", "us.", "eu.", "apac.", "global.")
+            if anthropic_model.startswith(_CROSS_REGION_PREFIXES):
+                return f"bedrock/{anthropic_model}"
+            if anthropic_model.startswith("bedrock/") and anthropic_model[
+                len("bedrock/") :
+            ].startswith(_CROSS_REGION_PREFIXES):
+                return anthropic_model
+
             normalized = _normalize_bedrock_profile_id(anthropic_model)
             if normalized and normalized in self._model_map:
                 return self._model_map[normalized]
@@ -917,14 +1007,21 @@ class LiteLLMBackend(Backend):
             _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker")
             if self.provider not in _env_auth_providers:
                 auth_header = headers.get("authorization", headers.get("Authorization", ""))
-                if auth_header.startswith("Bearer "):
-                    kwargs["api_key"] = auth_header[7:]
-                elif headers.get("x-api-key"):
-                    kwargs["api_key"] = headers["x-api-key"]
+                _caller_key = (
+                    auth_header[7:]
+                    if auth_header.startswith("Bearer ")
+                    else headers.get("x-api-key", "")
+                )
+                # Only forward it if it can actually authenticate the TARGET.
+                if _caller_key and _caller_key_travels_to(litellm_model, _caller_key):
+                    kwargs["api_key"] = _caller_key
 
             logger.debug(f"LiteLLM request: model={litellm_model}")
 
             # Make the call
+            # Bounded, always: an upstream that never answers must not
+            # block the caller forever. setdefault so an explicit value wins.
+            kwargs.setdefault("timeout", _upstream_timeout())
             response = await acompletion(**kwargs)
 
             # Convert to Anthropic format
@@ -1022,10 +1119,14 @@ class LiteLLMBackend(Backend):
             _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker")
             if self.provider not in _env_auth_providers:
                 auth_header = headers.get("authorization", headers.get("Authorization", ""))
-                if auth_header.startswith("Bearer "):
-                    kwargs["api_key"] = auth_header[7:]
-                elif headers.get("x-api-key"):
-                    kwargs["api_key"] = headers["x-api-key"]
+                _caller_key = (
+                    auth_header[7:]
+                    if auth_header.startswith("Bearer ")
+                    else headers.get("x-api-key", "")
+                )
+                # Only forward it if it can actually authenticate the TARGET.
+                if _caller_key and _caller_key_travels_to(litellm_model, _caller_key):
+                    kwargs["api_key"] = _caller_key
 
             msg_id = f"msg_{uuid.uuid4().hex[:24]}"
 
@@ -1055,6 +1156,9 @@ class LiteLLMBackend(Backend):
             kwargs["stream_options"] = {"include_usage": True}
 
             # Stream content — blocks emitted dynamically based on response
+            # Bounded, always: an upstream that never answers must not
+            # block the caller forever. setdefault so an explicit value wins.
+            kwargs.setdefault("timeout", _upstream_timeout())
             response = await acompletion(**kwargs)
             output_tokens = 0
             current_block_index = -1
@@ -1275,14 +1379,21 @@ class LiteLLMBackend(Backend):
             _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker")
             if self.provider not in _env_auth_providers:
                 auth_header = headers.get("authorization", headers.get("Authorization", ""))
-                if auth_header.startswith("Bearer "):
-                    kwargs["api_key"] = auth_header[7:]
-                elif headers.get("x-api-key"):
-                    kwargs["api_key"] = headers["x-api-key"]
+                _caller_key = (
+                    auth_header[7:]
+                    if auth_header.startswith("Bearer ")
+                    else headers.get("x-api-key", "")
+                )
+                # Only forward it if it can actually authenticate the TARGET.
+                if _caller_key and _caller_key_travels_to(litellm_model, _caller_key):
+                    kwargs["api_key"] = _caller_key
 
             logger.debug(f"LiteLLM OpenAI request: model={litellm_model}")
 
             # Make the call
+            # Bounded, always: an upstream that never answers must not
+            # block the caller forever. setdefault so an explicit value wins.
+            kwargs.setdefault("timeout", _upstream_timeout())
             response = await acompletion(**kwargs)
 
             # Build the usage block. LiteLLM normalizes prompt-cache stats from
@@ -1293,10 +1404,16 @@ class LiteLLMBackend(Backend):
             # cache_creation_tokens for the OpenAI nested dialect. Surface both
             # so PrefixCacheTracker.update_from_response on the backend-routed
             # path observes a stable shape instead of branching on key presence.
+            # None-guard the core counts (same defensive style as the cache
+            # fields just below). A provider can leave any of these None on the
+            # Usage object; emitting None here flows into the OpenAI-shape body,
+            # and the backend-routed OpenAI handler reads them straight into
+            # arithmetic and RequestOutcome (output_tokens=..., and
+            # max(0, prompt_tokens - ...)), which raises TypeError on None.
             usage_block: dict[str, Any] = {
-                "prompt_tokens": response.usage.prompt_tokens,
-                "completion_tokens": response.usage.completion_tokens,
-                "total_tokens": response.usage.total_tokens,
+                "prompt_tokens": int(getattr(response.usage, "prompt_tokens", 0) or 0),
+                "completion_tokens": int(getattr(response.usage, "completion_tokens", 0) or 0),
+                "total_tokens": int(getattr(response.usage, "total_tokens", 0) or 0),
             }
 
             # Defensive getattr: LiteLLM only attaches these top-level attrs
@@ -1447,11 +1564,18 @@ class LiteLLMBackend(Backend):
             _env_auth_providers = ("bedrock", "vertex_ai", "vertex_ai_beta", "sagemaker")
             if self.provider not in _env_auth_providers:
                 auth_header = headers.get("authorization", headers.get("Authorization", ""))
-                if auth_header.startswith("Bearer "):
-                    kwargs["api_key"] = auth_header[7:]
-                elif headers.get("x-api-key"):
-                    kwargs["api_key"] = headers["x-api-key"]
+                _caller_key = (
+                    auth_header[7:]
+                    if auth_header.startswith("Bearer ")
+                    else headers.get("x-api-key", "")
+                )
+                # Only forward it if it can actually authenticate the TARGET.
+                if _caller_key and _caller_key_travels_to(litellm_model, _caller_key):
+                    kwargs["api_key"] = _caller_key
 
+            # Bounded, always: an upstream that never answers must not
+            # block the caller forever. setdefault so an explicit value wins.
+            kwargs.setdefault("timeout", _upstream_timeout())
             response = await acompletion(**kwargs)
 
             async for chunk in response:
diff --git a/headroom/binaries.py b/headroom/binaries.py
index 3ce4cebbf..229bd817e 100644
--- a/headroom/binaries.py
+++ b/headroom/binaries.py
@@ -29,6 +29,7 @@ import subprocess
 import sys
 import tarfile
 import tempfile
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -245,12 +246,24 @@ def _download(url: str, dest: Path, *, progress: bool = True) -> None:
         raise OSError(f"binary cache directory is not writable: {dest.parent}")
     final_url = _mirror_url(url)
     req = urllib.request.Request(final_url, headers={"User-Agent": "headroom-binaries/1"})
-    try:
-        with urllib.request.urlopen(req, timeout=60) as resp:  # noqa: S310 (https)
-            total = int(resp.headers.get("Content-Length") or 0)
-            _stream_to(resp, dest, total, label=dest.name, show_progress=progress)
-    except urllib.error.URLError as e:
-        raise BinaryFetchError(f"failed to download {final_url}: {e}") from e
+    attempts = 3
+    for attempt in range(1, attempts + 1):
+        try:
+            with urllib.request.urlopen(req, timeout=60) as resp:  # noqa: S310 (https)
+                total = int(resp.headers.get("Content-Length") or 0)
+                _stream_to(resp, dest, total, label=dest.name, show_progress=progress)
+            return
+        except urllib.error.URLError as e:
+            dest.unlink(missing_ok=True)
+            if attempt == attempts:
+                raise BinaryFetchError(
+                    f"failed to download {final_url} after {attempts} attempts: {e}"
+                ) from e
+            # GitHub release assets occasionally return a transient 5xx or
+            # reset while redirecting to the object store. A short bounded
+            # retry keeps proxy startup reliable without hiding persistent
+            # credential, mirror, or connectivity failures.
+            time.sleep(0.25 * attempt)
 
 
 def _stream_to(src: Any, dest: Path, total: int, *, label: str, show_progress: bool) -> None:
diff --git a/headroom/cache/compression_cache.py b/headroom/cache/compression_cache.py
index 71beb4091..00abf07b0 100644
--- a/headroom/cache/compression_cache.py
+++ b/headroom/cache/compression_cache.py
@@ -135,8 +135,10 @@ class CompressionCache:
         # `compute_frozen_count` (bounded above by the `min` clamp at
         # `proxy/handlers/anthropic.py`) and `update_from_result`'s
         # "unchanged content" tracking.
-        self._stable_hashes: set[str] = set()
-        self._first_seen: dict[str, float] = {}
+        # Ordered mappings preserve set/dict-style membership while allowing
+        # deterministic oldest-first eviction.
+        self._stable_hashes: OrderedDict[str, None] = OrderedDict()
+        self._first_seen: OrderedDict[str, float] = OrderedDict()
         self._hits: int = 0
         self._misses: int = 0
         self._total_tokens_saved: int = 0
@@ -172,6 +174,34 @@ class CompressionCache:
                 _, evicted = self._cache.popitem(last=False)
                 self._total_tokens_saved -= evicted.tokens_saved
 
+    def _mark_stable_locked(self, content_hash: str) -> None:
+        """Record a stable hash while bounding retained bookkeeping."""
+        self._stable_hashes[content_hash] = None
+        self._stable_hashes.move_to_end(content_hash)
+
+        while len(self._stable_hashes) > self.max_entries:
+            self._stable_hashes.popitem(last=False)
+
+    def _record_first_seen_locked(self, content_hash: str, seen_at: float) -> None:
+        """Record a first-seen timestamp while bounding retained bookkeeping."""
+        self._first_seen[content_hash] = seen_at
+        self._first_seen.move_to_end(content_hash)
+
+        while len(self._first_seen) > self.max_entries:
+            self._first_seen.popitem(last=False)
+
+    def _prune_expired_first_seen_locked(
+        self,
+        now: float,
+        ttl_seconds: float,
+    ) -> None:
+        """Remove first-seen entries whose cache timing window has expired."""
+        while self._first_seen:
+            _, oldest_seen_at = next(iter(self._first_seen.items()))
+            if now - oldest_seen_at < ttl_seconds:
+                break
+            self._first_seen.popitem(last=False)
+
     def mark_stable(self, content_hash: str) -> None:
         """Mark a content hash as stable (unchanged, not compressed).
 
@@ -180,7 +210,7 @@ class CompressionCache:
         even though no compressed version exists in the cache.
         """
         with self._lock:
-            self._stable_hashes.add(content_hash)
+            self._mark_stable_locked(content_hash)
 
     def mark_stable_from_messages(self, messages: list[dict], up_to: int) -> None:
         """Mark all tool_result hashes in messages[:up_to] as stable."""
@@ -189,7 +219,7 @@ class CompressionCache:
                 if _is_tool_result_message(msg):
                     content = _extract_tool_result_content(msg)
                     if content is not None:
-                        self._stable_hashes.add(self.content_hash(content))
+                        self._mark_stable_locked(self.content_hash(content))
 
     def should_defer_compression(
         self,
@@ -216,13 +246,18 @@ class CompressionCache:
         """
         with self._lock:
             now = time.time()
+            self._prune_expired_first_seen_locked(now, ttl_seconds)
+
             first_seen = self._first_seen.get(content_hash)
             if first_seen is None:
-                self._first_seen[content_hash] = now
+                self._record_first_seen_locked(content_hash, now)
                 return False  # First time — compress now (no cache entry to preserve)
+
             age = now - first_seen
             if age >= ttl_seconds - batch_window:
+                self._record_first_seen_locked(content_hash, now)
                 return False  # Near TTL boundary — compress now (batch window)
+
             return True  # Seen recently within TTL — defer to preserve cache
 
     def get_stats(self) -> dict:
@@ -335,7 +370,7 @@ class CompressionCache:
                     continue
                 if orig_content == comp_content:
                     # Content unchanged — mark as stable for frozen count walk
-                    self._stable_hashes.add(self.content_hash(orig_content))
+                    self._mark_stable_locked(self.content_hash(orig_content))
                     continue
                 h = self.content_hash(orig_content)
                 tokens_saved = len(orig_content) // 4 - len(comp_content) // 4
diff --git a/headroom/cache/compression_store.py b/headroom/cache/compression_store.py
index 72e6ca34f..bbda697cd 100644
--- a/headroom/cache/compression_store.py
+++ b/headroom/cache/compression_store.py
@@ -52,6 +52,10 @@ DEFAULT_CCR_TTL_SECONDS = 1800  # session-scale; override via HEADROOM_CCR_TTL_S
 CCR_TTL_SECONDS_ENV = "HEADROOM_CCR_TTL_SECONDS"
 
 _RETRIEVAL_LOG_PREVIEW_CHARS = 4096
+# Previews carry verbatim tool-result content (post-redaction), which makes
+# proxy.log too sensitive for users to share in bug reports. Set to
+# 0/false/no/off to log byte counts only.
+PAYLOAD_PREVIEW_ENV = "HEADROOM_LOG_PAYLOAD_PREVIEW"
 _SECRET_KEY_VALUE_RE = re.compile(
     r"(?i)\b([A-Z0-9_-]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|AUTH)[A-Z0-9_-]*)"
     r"(\s*[:=]\s*)([\"']?)([^\"'\s,}]+)"
@@ -108,7 +112,21 @@ def _redact_retrieval_log_payload(payload: str) -> str:
     return _API_KEY_VALUE_RE.sub("sk-[REDACTED]", redacted)
 
 
+def _payload_preview_enabled() -> bool:
+    raw = os.environ.get(PAYLOAD_PREVIEW_ENV)
+    if raw is None:
+        return True
+    return raw.strip().lower() not in ("0", "false", "no", "off")
+
+
 def _payload_for_retrieval_log(payload: str) -> dict[str, Any]:
+    if not _payload_preview_enabled():
+        return {
+            "payload_chars": len(payload),
+            "payload_preview_chars": 0,
+            "payload_truncated": len(payload) > 0,
+            "payload_preview": "",
+        }
     redacted = _redact_retrieval_log_payload(payload)
     preview = redacted[:_RETRIEVAL_LOG_PREVIEW_CHARS]
     truncated = len(redacted) > len(preview)
diff --git a/headroom/cache/prefix_tracker.py b/headroom/cache/prefix_tracker.py
index d54950191..8157e9e9a 100644
--- a/headroom/cache/prefix_tracker.py
+++ b/headroom/cache/prefix_tracker.py
@@ -21,6 +21,7 @@ import hashlib
 import itertools
 import json
 import logging
+import os
 import time
 from collections import OrderedDict
 from dataclasses import dataclass
@@ -229,6 +230,184 @@ def _canonicalize_for_prefix_compare(obj: Any) -> Any:
     return obj
 
 
+# Canonical relationships between consecutive histories.  These constants are
+# strings (rather than an Enum) so they remain cheap to log on the request hot
+# path and easy to assert in tests.
+RELATION_EXACT = "exact"
+RELATION_MESSAGE_APPEND = "message_append"
+RELATION_BLOCK_APPEND = "block_append"
+RELATION_BLOCK_REWRITE_TAIL = "block_rewrite_tail"
+RELATION_DIVERGED = "diverged"
+
+
+@dataclass(frozen=True)
+class HistoryRelation:
+    """How a current message history relates to one recorded last turn.
+
+    ``block_append`` and ``block_rewrite_tail`` are deliberately distinct:
+    Anthropic should keep the breakpoint on the newest block for a pure append,
+    but anchor it to ``stable_prefix_blocks - 1`` when the previous tail was
+    rewritten and therefore can never match a prior cache write (#2671).
+    """
+
+    kind: str
+    message_index: int | None = None
+    stable_prefix_blocks: int = 0
+    stable_suffix_blocks: int = 0
+    previous_block_count: int = 0
+    current_block_count: int = 0
+
+
+# A rewritten-tail match is intentionally conservative.  The production shape
+# behind #2671 has a hundred-plus-block stable prefix and a fixed two-block
+# suffix.  Requiring both avoids merging sibling sub-calls which merely share a
+# short injected preamble or a single generic reminder at the end.
+_MIN_REWRITE_PREFIX_BLOCKS = 8
+_MIN_REWRITE_SUFFIX_BLOCKS = 2
+
+
+def _message_fields_outside_content(message: dict[str, Any]) -> dict[str, Any]:
+    """Return message identity fields, excluding the block list itself."""
+    return {key: value for key, value in message.items() if key != "content"}
+
+
+def _stable_leading_block_run(current: list[Any], previous: list[Any]) -> int:
+    """Number of canonical-equal blocks at the start of both lists."""
+    limit = min(len(current), len(previous))
+    run = 0
+    while run < limit and current[run] == previous[run]:
+        run += 1
+    return run
+
+
+def _stable_trailing_block_run(current: list[Any], previous: list[Any], *, leading_run: int) -> int:
+    """Non-overlapping canonical-equal suffix length."""
+    limit = min(len(current), len(previous)) - leading_run
+    run = 0
+    while run < limit and current[-(run + 1)] == previous[-(run + 1)]:
+        run += 1
+    return run
+
+
+def _classify_history_canonical(
+    current_messages: list[Any], previous_messages: list[Any]
+) -> HistoryRelation:
+    """Classify two already-canonical, structurally snapshotted histories."""
+    if not previous_messages or len(current_messages) < len(previous_messages):
+        return HistoryRelation(RELATION_DIVERGED)
+
+    changed: HistoryRelation | None = None
+    for index, previous_message in enumerate(previous_messages):
+        current_message = current_messages[index]
+        if current_message == previous_message:
+            continue
+        if changed is not None:
+            return HistoryRelation(RELATION_DIVERGED)
+        if not isinstance(previous_message, dict) or not isinstance(current_message, dict):
+            return HistoryRelation(RELATION_DIVERGED)
+        if _message_fields_outside_content(previous_message) != _message_fields_outside_content(
+            current_message
+        ):
+            return HistoryRelation(RELATION_DIVERGED)
+
+        previous_blocks = previous_message.get("content")
+        current_blocks = current_message.get("content")
+        if not isinstance(previous_blocks, list) or not isinstance(current_blocks, list):
+            return HistoryRelation(RELATION_DIVERGED)
+
+        previous_count = len(previous_blocks)
+        current_count = len(current_blocks)
+        leading = _stable_leading_block_run(current_blocks, previous_blocks)
+
+        # Pure block append.  The previous write remains intact and Anthropic's
+        # lookback can find it, so the breakpoint must advance to the newest
+        # block and cover the newly appended tail.
+        if current_count > previous_count and leading == previous_count:
+            changed = HistoryRelation(
+                RELATION_BLOCK_APPEND,
+                message_index=index,
+                stable_prefix_blocks=leading,
+                previous_block_count=previous_count,
+                current_block_count=current_count,
+            )
+            continue
+
+        # Rewritten-tail growth.  This is narrower than a fuzzy prefix match:
+        # message count may not change, content may not shrink, most of the old
+        # prefix must survive, and a substantial fixed suffix must identify the
+        # sub-call.  Crucially ``leading < previous_count`` proves this is NOT a
+        # pure append (the bug in the original #2702 discriminator).
+        trailing = _stable_trailing_block_run(current_blocks, previous_blocks, leading_run=leading)
+        if (
+            len(current_messages) == len(previous_messages)
+            and current_count >= previous_count
+            and _MIN_REWRITE_PREFIX_BLOCKS <= leading < previous_count
+            and leading * 2 >= previous_count
+            and leading * 2 >= current_count
+            and trailing >= _MIN_REWRITE_SUFFIX_BLOCKS
+        ):
+            changed = HistoryRelation(
+                RELATION_BLOCK_REWRITE_TAIL,
+                message_index=index,
+                stable_prefix_blocks=leading,
+                stable_suffix_blocks=trailing,
+                previous_block_count=previous_count,
+                current_block_count=current_count,
+            )
+            continue
+
+        return HistoryRelation(RELATION_DIVERGED)
+
+    if changed is not None:
+        return changed
+    return HistoryRelation(
+        RELATION_EXACT
+        if len(current_messages) == len(previous_messages)
+        else RELATION_MESSAGE_APPEND
+    )
+
+
+def classify_history_relation(
+    current_messages: list[dict[str, Any]],
+    previous_messages: list[dict[str, Any]],
+) -> HistoryRelation:
+    """Return the canonical cross-turn relationship for two raw histories.
+
+    The canonical projection may drop a whole directive-only message.  Refuse
+    classification when that would shift raw message indices: block replay
+    always slices the raw lists and must never consume a canonical index as a
+    raw one.
+    """
+    if not current_messages or not previous_messages:
+        return HistoryRelation(RELATION_DIVERGED)
+    current = _lineage_snapshot(_canonicalize_for_prefix_compare(current_messages))
+    previous = _lineage_snapshot(_canonicalize_for_prefix_compare(previous_messages))
+    prefix_len = len(previous_messages)
+    if len(previous) != prefix_len:
+        return HistoryRelation(RELATION_DIVERGED)
+    if len(_canonicalize_for_prefix_compare(current_messages[:prefix_len])) != prefix_len:
+        return HistoryRelation(RELATION_DIVERGED)
+    return _classify_history_canonical(current, previous)
+
+
+def segment_fingerprint(value: Any) -> str:
+    """Stable hash for non-message provider cache-key segments.
+
+    Cache-control placement and transport annotations are deliberately ignored;
+    semantic tool/model/thinking changes remain visible.  The hash is affinity
+    metadata only and is never used to reconstruct or forward request content.
+    """
+    canonical = _lineage_snapshot(_canonicalize_for_prefix_compare(value))
+    encoded = json.dumps(
+        canonical,
+        sort_keys=True,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        default=str,
+    )
+    return hashlib.sha256(encoded.encode()).hexdigest()[:24]
+
+
 def extract_cache_stable_delta(
     current_messages: list[dict[str, Any]],
     previous_original_messages: list[dict[str, Any]] | None,
@@ -251,13 +430,13 @@ def extract_cache_stable_delta(
     """
     if not previous_original_messages or previous_forwarded_messages is None:
         return None
+    relation = classify_history_relation(current_messages, previous_original_messages)
+    if relation.kind not in (RELATION_EXACT, RELATION_MESSAGE_APPEND):
+        # A same-message block append needs a block-level splice in
+        # ``overlay_cached_prefix``; slicing only whole messages would silently
+        # discard its new blocks.  Rewritten tails are not append-only deltas.
+        return None
     prefix_len = len(previous_original_messages)
-    if len(current_messages) < prefix_len:
-        return None
-    if _canonicalize_for_prefix_compare(
-        current_messages[:prefix_len]
-    ) != _canonicalize_for_prefix_compare(previous_original_messages):
-        return None
     return (
         copy.deepcopy(previous_forwarded_messages),
         copy.deepcopy(current_messages[prefix_len:]),
@@ -281,12 +460,12 @@ def overlay_cached_prefix(
     the corresponding leading messages so the forwarded prefix stays byte-for-byte
     what the provider hashed for its cache key.
 
-    Safe only when this turn append-only-extends the previous turn (the standard
-    growing-conversation shape): the previous ORIGINAL messages must be an exact
-    prefix of the current ORIGINAL messages, and there is exactly one forwarded
-    message per original. Otherwise the previous forwarded bytes may not
-    correspond to the same positions, so we return ``optimized_messages``
-    unchanged (accept a possible bust rather than forward wrong content).
+    Safe only when this turn extends the previous turn in a proven positional
+    shape: either whole-message append or pure block append inside one message.
+    There must be exactly one previous forwarded message per original. Otherwise
+    the previous bytes may not correspond to the same positions, so we return
+    ``optimized_messages`` unchanged (accept a possible bust rather than forward
+    wrong content).
 
     This makes freezing byte-identical in BOTH proxy modes, so the only remaining
     difference between them is how large a mutable (still-compressible) tail each
@@ -311,6 +490,55 @@ def overlay_cached_prefix(
             n,
         )
         return optimized_messages
+
+    relation = classify_history_relation(current_original_messages, prev_orig)
+    if relation.kind == RELATION_BLOCK_APPEND and relation.message_index is not None:
+        message_index = relation.message_index
+        if message_index < len(optimized_messages):
+            previous_message = prev_fwd[message_index]
+            previous_original_message = prev_orig[message_index]
+            current_message = optimized_messages[message_index]
+            previous_content = (
+                previous_message.get("content") if isinstance(previous_message, dict) else None
+            )
+            previous_original_content = (
+                previous_original_message.get("content")
+                if isinstance(previous_original_message, dict)
+                else None
+            )
+            current_content = (
+                current_message.get("content") if isinstance(current_message, dict) else None
+            )
+            split = (
+                len(previous_original_content)
+                if isinstance(previous_original_content, list)
+                else -1
+            )
+            if (
+                isinstance(previous_content, list)
+                and isinstance(previous_original_content, list)
+                and isinstance(current_content, list)
+                and len(previous_content) == split
+                and len(current_content) >= split
+                and _canonicalize_for_prefix_compare(current_content[:split])
+                == _canonicalize_for_prefix_compare(previous_original_content)
+            ):
+                merged = copy.deepcopy(previous_message)
+                merged["content"] = copy.deepcopy(previous_content) + copy.deepcopy(
+                    current_content[split:]
+                )
+                logger.debug(
+                    "overlay: replayed %d forwarded blocks and appended %d new blocks "
+                    "inside message %d",
+                    split,
+                    len(current_content) - split,
+                    message_index,
+                )
+                return (
+                    list(prev_fwd[:message_index])
+                    + [merged]
+                    + list(optimized_messages[message_index + 1 :])
+                )
     # Append-only guard on CONTENT ONLY, message-by-message. Replay the
     # previously-forwarded (cached, compressed) bytes for the longest LEADING
     # run of messages that is byte-for-byte (content-canonical) identical to
@@ -359,8 +587,77 @@ def overlay_cached_prefix(
     return list(prev_fwd[:k]) + list(optimized_messages[k:])
 
 
+_STABLE_BOUNDARY_ENV = "HEADROOM_STABLE_BOUNDARY_BREAKPOINT"
+_MIN_BLOCKS_FOR_RELOCATION = 20
+
+
+def _stable_boundary_enabled() -> bool:
+    return os.environ.get(_STABLE_BOUNDARY_ENV, "").strip().lower() not in (
+        "0",
+        "false",
+        "no",
+        "off",
+    )
+
+
+def _breakpoint_index(
+    content: list[Any],
+    message: dict[str, Any],
+    message_index: int,
+    previous_forwarded_messages: list[dict[str, Any]] | None,
+) -> int:
+    """Choose newest for appends, stable-prefix end for rewritten tails."""
+    newest = len(content) - 1
+    if (
+        not previous_forwarded_messages
+        or not _stable_boundary_enabled()
+        or len(content) < _MIN_BLOCKS_FOR_RELOCATION
+        or message_index >= len(previous_forwarded_messages)
+    ):
+        return newest
+    previous = previous_forwarded_messages[message_index]
+    if not isinstance(previous, dict):
+        return newest
+    relation = classify_history_relation([message], [previous])
+    if relation.kind != RELATION_BLOCK_REWRITE_TAIL:
+        return newest
+    logger.debug(
+        "cache breakpoint anchored to stable run %d/%d blocks in message %d "
+        "(previous=%d, stable_suffix=%d)",
+        relation.stable_prefix_blocks,
+        relation.current_block_count,
+        message_index,
+        relation.previous_block_count,
+        relation.stable_suffix_blocks,
+    )
+    return relation.stable_prefix_blocks - 1
+
+
+def _client_marker_positions(
+    client_messages: list[dict[str, Any]],
+) -> list[tuple[int, int, dict[str, Any]]]:
+    """(message index, block index, marker) for every CLIENT cache_control.
+
+    Block-level, not one-per-message: clients mark multiple blocks within a
+    single long message (Claude Code does this on 1-2-message requests with a
+    large first message), and the ~20-block lookback applies within a message
+    just as it does across messages. Only block-style content carries markers.
+    """
+    positions: list[tuple[int, int, dict[str, Any]]] = []
+    for i, msg in enumerate(client_messages):
+        content = msg.get("content") if isinstance(msg, dict) else None
+        if not isinstance(content, list):
+            continue
+        for bi, b in enumerate(content):
+            if isinstance(b, dict) and isinstance(b.get("cache_control"), dict):
+                positions.append((i, bi, b["cache_control"]))
+    return positions
+
+
 def normalize_message_cache_control(
     messages: list[dict[str, Any]],
+    previous_forwarded_messages: list[dict[str, Any]] | None = None,
+    client_messages: list[dict[str, Any]] | None = None,
 ) -> list[dict[str, Any]]:
     """Own message-level cache_control placement so breakpoints stay bounded.
 
@@ -370,22 +667,35 @@ def normalize_message_cache_control(
     hard-errors at **>4 cache_control blocks total** (system + tools + messages),
     so on a long conversation the accumulation eventually 400s.
 
-    Fix: strip EVERY message-level cache_control and re-place a **single**
-    ephemeral breakpoint on the last block of the last block-style message. One
-    breakpoint caches the whole message prefix up to it, and — because the
-    provider's cache key is message CONTENT, not marker presence (moving the
-    breakpoint forward is the documented client pattern and it hits) — stripping
-    and re-placing markers never busts. system/tools breakpoints live outside
-    ``messages`` and are left untouched (they still count toward the 4 limit, so
-    holding messages to one breakpoint leaves room for them).
+    Fix: strip EVERY message-level cache_control, then re-place markers at the
+    positions the CLIENT's current request marks (``client_messages``). The
+    client's positions are load-bearing, not redundant: Anthropic resolves each
+    breakpoint by walking back **at most ~20 content blocks** for a prior cache
+    entry, and agentic clients (Claude Code) keep a marker on the previous
+    turn's newest message precisely so the new turn's write can chain to the
+    old entry. Collapsing to a single newest-block marker breaks that chain
+    whenever one turn adds >20 blocks (typical for tool-heavy turns): the
+    lookback misses, the entire message history silently re-bills as cache
+    creation, and a marker anchored short of the final block leaves the tail
+    billing as fully uncached input. Mirroring the client's positions bounds
+    accumulation identically (the client manages its own 4-marker budget) while
+    preserving its read/write chaining.
 
-    Headroom owns WHERE the breakpoint goes; the client still owns WHAT it says:
-    the re-placed marker reuses the newest client marker verbatim, so an explicit
-    ``ttl`` (e.g. ``"1h"``) survives consolidation instead of silently
-    downgrading to the 5-minute default (#2375).
+    The provider's cache key is message CONTENT, not marker presence (moving
+    the breakpoint forward is the documented client pattern and it hits), so
+    stripping replay leftovers and re-placing markers never busts. system/tools
+    breakpoints live outside ``messages`` and are left untouched.
 
-    Only block-style (list) content can carry cache_control; string content is
-    left as-is. Returns the input unchanged when there is nothing to normalize.
+    Headroom owns WHICH BLOCK carries each marker; the client owns the message
+    positions and the marker values, so an explicit ``ttl`` (e.g. ``"1h"``)
+    survives per position instead of silently downgrading (#2375). The newest
+    position uses stable-run anchoring for proven rewritten tails; earlier
+    positions go on their message's last block.
+
+    Without ``client_messages`` (or when the transformed list no longer aligns
+    with it), falls back to the legacy single-marker consolidation. Only
+    block-style (list) content can carry cache_control; string content is left
+    as-is. Returns the input unchanged when there is nothing to normalize.
     """
     changed = False
     out: list[dict[str, Any]] = []
@@ -412,13 +722,75 @@ def normalize_message_cache_control(
                 last_block_idx = i
         else:
             out.append(msg)
-    # Re-place exactly one breakpoint on the last block-style message.
+
+    def _place(
+        target_idx: int,
+        marker: dict[str, Any],
+        *,
+        anchor: bool,
+        block_idx: int | None = None,
+    ) -> bool:
+        msg = out[target_idx]
+        content = msg.get("content")
+        if not isinstance(content, list) or not content:
+            return False
+        content = list(content)
+        if block_idx is not None and 0 <= block_idx < len(content):
+            # Transforms can shift block indices (e.g. a dropped thinking
+            # block); a slightly-off placement still lands on a stable block
+            # in the same message, which is harmless — markers are not part
+            # of the provider's cache key.
+            breakpoint_index = block_idx
+        elif anchor:
+            breakpoint_index = _breakpoint_index(
+                content, msg, target_idx, previous_forwarded_messages
+            )
+        else:
+            breakpoint_index = len(content) - 1
+        # Anthropic content blocks are dictionaries, but callers can still
+        # supply mixed list content. Fall back to the newest block rather than
+        # attempting ``**`` on a scalar stable-boundary element, and skip the
+        # message entirely when even that is not a dict.
+        if not isinstance(content[breakpoint_index], dict):
+            breakpoint_index = len(content) - 1
+        if not isinstance(content[breakpoint_index], dict):
+            return False
+        content[breakpoint_index] = {**content[breakpoint_index], "cache_control": dict(marker)}
+        out[target_idx] = {**msg, "content": content}
+        return True
+
+    # Preferred: mirror the client's marker positions 1:1, block-level. The
+    # transform pipeline preserves message count, so index alignment is the
+    # invariant; fall back to legacy consolidation if it ever does not hold,
+    # or when the client marked nothing (legacy still places one so the
+    # prefix caches). The newest client marker keeps stable-run anchoring
+    # when the client placed it on its message's final block (intent: "cache
+    # through the end"); an explicit mid-message marker is honored verbatim.
+    if client_messages is not None and len(client_messages) == len(messages):
+        positions = _client_marker_positions(client_messages)
+        if positions:
+            placed_any = False
+            newest_mi, newest_bi, _ = positions[-1]
+            newest_client_content = client_messages[newest_mi].get("content")
+            newest_on_final_block = (
+                isinstance(newest_client_content, list)
+                and newest_bi == len(newest_client_content) - 1
+            )
+            for mi, bi, marker in positions:
+                is_newest = (mi, bi) == (newest_mi, newest_bi)
+                if is_newest and newest_on_final_block:
+                    placed = _place(mi, marker, anchor=True)
+                else:
+                    placed = _place(mi, marker, anchor=False, block_idx=bi)
+                placed_any = placed or placed_any
+            if placed_any or changed:
+                return out
+            return messages
+
+    # Legacy: re-place exactly one breakpoint on the last block-style message.
     if last_block_idx >= 0:
-        msg = out[last_block_idx]
-        content = list(msg["content"])
         marker = dict(last_marker) if last_marker else {"type": "ephemeral"}
-        content[-1] = {**content[-1], "cache_control": marker}
-        out[last_block_idx] = {**msg, "content": content}
+        _place(last_block_idx, marker, anchor=True)
         changed = True
     return out if changed else messages
 
@@ -829,6 +1201,10 @@ class SessionTrackerStore:
         # value, so a synthetic key can never collide with a client-supplied
         # x-headroom-session-id.
         self._lineages: dict[str, OrderedDict[str, list[Any]]] = {}
+        # Exact non-message cache-key affinity per tracker.  Anthropic renders
+        # tools before system/messages, so two sub-calls with identical history
+        # but different tool profiles must never share frozen-prefix state.
+        self._lineage_affinities: dict[str, str | None] = {}
         self._lineage_counter = itertools.count(1)
 
     def get_or_create(self, session_id: str, provider: str) -> PrefixCacheTracker:
@@ -854,6 +1230,7 @@ class SessionTrackerStore:
         session_id: str,
         provider: str,
         messages: list[dict[str, Any]] | None = None,
+        cache_affinity: str | None = None,
     ) -> PrefixCacheTracker:
         """Resolve the tracker for THIS conversation within a session id (#2085).
 
@@ -866,10 +1243,11 @@ class SessionTrackerStore:
 
         Lineage resolution keys trackers by conversation content instead:
         reuse the tracker whose previous request messages are a prefix of the
-        incoming history (client histories are append-only, so a
-        conversation's next request always extends its previous one); start a
-        fresh lineage when the history diverges or was rewritten (client-side
-        compaction — the provider cache line is gone then anyway).
+        incoming history. It also recognizes a conservative block-level shape
+        where a large leading run and two-block identity suffix survive while
+        the middle tail is regenerated; all other rewrites start a fresh
+        lineage. This keeps #2671's stable cache boundary attached without
+        merging unrelated parallel sub-calls.
         Byte-identical histories (templated fan-outs before they diverge)
         intentionally share a tracker: their provider cache line is identical
         too, so sharing is harmless.
@@ -888,6 +1266,9 @@ class SessionTrackerStore:
                 compares like against like across turns. ``None``/empty
                 (legacy callers, stub stores in tests) falls back to plain
                 :meth:`get_or_create`.
+            cache_affinity: Stable fingerprint of the provider's non-message
+                cache-key segments (model/tools/tool choice/thinking). Lineages
+                with different affinity never share a tracker.
 
         Returns:
             The ``PrefixCacheTracker`` for this conversation's lineage.
@@ -918,14 +1299,48 @@ class SessionTrackerStore:
 
         family = self._lineages.setdefault(session_id, OrderedDict())
 
-        # Longest recorded chain that prefixes the incoming history wins.
+        # Strict whole-message continuations win first, then pure block appends.
+        # Rewritten-tail matches are deliberately last and require a unique best
+        # structural score; ambiguity starts a fresh lineage instead of making
+        # sibling sub-calls ping-pong one tracker.
+        by_length = sorted(family.items(), key=lambda item: len(item[1]), reverse=True)
         best_key: str | None = None
-        best_len = -1
-        for key, chain in family.items():
-            if len(chain) > len(snap) or len(chain) <= best_len:
-                continue
-            if snap[: len(chain)] == chain:
-                best_key, best_len = key, len(chain)
+        for accepted in (
+            (RELATION_EXACT, RELATION_MESSAGE_APPEND),
+            (RELATION_BLOCK_APPEND,),
+        ):
+            for key, chain in by_length:
+                if self._lineage_affinities.get(key) != cache_affinity:
+                    continue
+                relation = _classify_history_canonical(snap, chain)
+                if relation.kind in accepted:
+                    best_key = key
+                    break
+            if best_key is not None:
+                break
+
+        if best_key is None:
+            rewrite_candidates: list[tuple[tuple[int, int, int], str]] = []
+            for key, chain in by_length:
+                if self._lineage_affinities.get(key) != cache_affinity:
+                    continue
+                relation = _classify_history_canonical(snap, chain)
+                if relation.kind == RELATION_BLOCK_REWRITE_TAIL:
+                    rewrite_candidates.append(
+                        (
+                            (
+                                relation.stable_prefix_blocks,
+                                relation.stable_suffix_blocks,
+                                relation.previous_block_count,
+                            ),
+                            key,
+                        )
+                    )
+            rewrite_candidates.sort(reverse=True)
+            if rewrite_candidates and (
+                len(rewrite_candidates) == 1 or rewrite_candidates[0][0] != rewrite_candidates[1][0]
+            ):
+                best_key = rewrite_candidates[0][1]
 
         if best_key is None:
             cap = self._default_config.max_lineages_per_session
@@ -963,6 +1378,7 @@ class SessionTrackerStore:
         # the family before the stamp below.
         tracker = self.get_or_create(best_key, provider)
         family[best_key] = snap
+        self._lineage_affinities[best_key] = cache_affinity
         return tracker
 
     def compute_session_id(
@@ -1031,6 +1447,7 @@ class SessionTrackerStore:
                 family = self._lineages[base]
                 for key in [k for k in family if k not in self._trackers]:
                     del family[key]
+                    self._lineage_affinities.pop(key, None)
                 if not family:
                     del self._lineages[base]
             logger.debug("SessionTrackerStore: cleaned up %d expired sessions", len(expired))
diff --git a/headroom/ccr/marker_resolution.py b/headroom/ccr/marker_resolution.py
new file mode 100644
index 000000000..aef4a108f
--- /dev/null
+++ b/headroom/ccr/marker_resolution.py
@@ -0,0 +1,83 @@
+"""Inline resolution of ``<<ccr:...>>`` markers on the response path.
+
+Normal CCR resolution relies on the ``headroom_retrieve`` tool: a marker is
+redeemed when the model calls the tool back. That path assumes there's a
+subsequent turn in which the model *can* call it. Callers that never see an
+injected tool at all — e.g. Headroom running as a LiteLLM guardrail/proxy hop
+with no tool-call turn in between (#2509) — have no way to redeem a marker,
+so it leaks through as raw text.
+
+This module provides an explicit, opt-in fallback (``--ccr-inline-resolve``):
+scan the outgoing response for markers and substitute the original content
+directly, instead of leaving the marker for the model to redeem later.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from ..cache.compression_store import (
+    CompressionStore,
+    format_retrieval_miss_detail,
+    get_compression_store,
+)
+
+logger = logging.getLogger(__name__)
+
+# Matches the opaque-blob marker form `<<ccr:HASH,KIND,SIZE>>` (and the
+# row-offload form `<<ccr:HASH N_rows_offloaded>>`) emitted by SmartCrusher.
+# HASH is 12-24 hex chars; see headroom/ccr/tool_injection.py for the same
+# constant used on the injection side.
+_MARKER_RE = re.compile(r"<<ccr:([a-f0-9]{12,24})[^>]*>>")
+
+
+def resolve_markers_in_text(text: str, *, store: CompressionStore | None = None) -> str:
+    """Replace every ``<<ccr:HASH,...>>`` marker in ``text`` with its original content.
+
+    A miss (expired/evicted/unknown hash) can't be reported back to the
+    model on this path — there's no tool-call round-trip — so the marker is
+    left in place with the miss reason appended rather than raising.
+    """
+    if "<<ccr:" not in text:
+        return text
+
+    resolved_store = store or get_compression_store()
+
+    def _replace(match: re.Match[str]) -> str:
+        hash_key = match.group(1)
+        entry = resolved_store.retrieve(hash_key)
+        if entry is not None:
+            original = entry.original_content
+            return original if isinstance(original, str) else json.dumps(original)
+
+        get_status = getattr(resolved_store, "get_entry_status", None)
+        status = get_status(hash_key, clean_expired=True) if callable(get_status) else None
+        detail = format_retrieval_miss_detail(status) if status else "entry not found"
+        logger.warning(f"CCR inline-resolve: marker {hash_key} unresolvable ({detail})")
+        return f"{match.group(0)} [unresolved: {detail}]"
+
+    return _MARKER_RE.sub(_replace, text)
+
+
+def resolve_markers_in_response(response: Any, *, store: CompressionStore | None = None) -> Any:
+    """Recursively resolve ``<<ccr:...>>`` markers in every string field of a payload.
+
+    Walks the full response structure rather than picking out
+    provider-specific fields (``content`` blocks, ``message.content``,
+    Responses-API ``output`` items, ...) so it stays correct regardless of
+    where a marker ends up, and doesn't need per-provider maintenance.
+    """
+    resolved_store = store or get_compression_store()
+    if isinstance(response, str):
+        return resolve_markers_in_text(response, store=resolved_store)
+    if isinstance(response, list):
+        return [resolve_markers_in_response(item, store=resolved_store) for item in response]
+    if isinstance(response, dict):
+        return {
+            key: resolve_markers_in_response(value, store=resolved_store)
+            for key, value in response.items()
+        }
+    return response
diff --git a/headroom/ccr/response_handler.py b/headroom/ccr/response_handler.py
index ff93aa981..7cdea7a49 100644
--- a/headroom/ccr/response_handler.py
+++ b/headroom/ccr/response_handler.py
@@ -58,6 +58,7 @@ class CCRToolResult:
     content: str
     success: bool
     items_retrieved: int = 0
+    tool_name: str | None = None
 
 
 @dataclass
@@ -211,6 +212,7 @@ class CCRResponseHandler:
                     tool_call_id=ccr_call.tool_call_id,
                     content=content,
                     success=False,
+                    tool_name=ccr_call.tool_name,
                 )
 
             # Retrieval is by hash: always return the full original content.
@@ -229,6 +231,7 @@ class CCRResponseHandler:
                     content=content,
                     success=True,
                     items_retrieved=entry.original_item_count,
+                    tool_name=ccr_call.tool_name,
                 )
 
             miss_status = (
@@ -249,6 +252,7 @@ class CCRResponseHandler:
                 tool_call_id=ccr_call.tool_call_id,
                 content=content,
                 success=False,
+                tool_name=ccr_call.tool_name,
             )
 
         except Exception as e:
@@ -264,6 +268,7 @@ class CCRResponseHandler:
                 tool_call_id=ccr_call.tool_call_id,
                 content=content,
                 success=False,
+                tool_name=ccr_call.tool_name,
             )
 
     def _create_tool_result_message(
@@ -337,14 +342,13 @@ class CCRResponseHandler:
                     response_data = json.loads(result.content)
                 except json.JSONDecodeError:
                     response_data = {"content": result.content}
-                parts.append(
-                    {
-                        "functionResponse": {
-                            "name": result.tool_call_id,  # tool_call_id contains the function name for Google
-                            "response": response_data,
-                        }
-                    }
-                )
+                function_response = {
+                    "name": result.tool_name or result.tool_call_id,
+                    "response": response_data,
+                }
+                if result.tool_name and result.tool_call_id != result.tool_name:
+                    function_response["id"] = result.tool_call_id
+                parts.append({"functionResponse": function_response})
             return {
                 "role": "user",
                 "parts": parts,
@@ -399,7 +403,16 @@ class CCRResponseHandler:
             # echoed back verbatim as `input[]` items — not a single
             # role/content dict like chat completions. Sentinel key mirrors
             # `_openai_tool_results`; handle_response() extends on it.
-            return {"_openai_responses_output_items": response.get("output", [])}
+            # `.get("output", [])` only falls back when the key is absent, so a
+            # present-but-null `output` would return None and make the
+            # `current_messages.extend(...)` in handle_response raise TypeError;
+            # coerce to a list like the choices branch above.
+            output_items = response.get("output")
+            return {
+                "_openai_responses_output_items": output_items
+                if isinstance(output_items, list)
+                else []
+            }
         elif provider == "google":
             # Google/Gemini format: role is "model", content is in candidates[0].content.parts
             candidates = response.get("candidates", [])
@@ -901,8 +914,17 @@ class StreamingCCRHandler:
             if "content" in delta and delta["content"]:
                 message["content"] = (message.get("content") or "") + delta["content"]
 
-            if "tool_calls" in delta:
-                for tc_delta in delta["tool_calls"]:
+            # Guard the value, not just the key: some OpenAI-compatible
+            # providers include ``"tool_calls": null`` (and ``"function": null``)
+            # in a delta rather than omitting the key, which would make the
+            # iteration below raise ``TypeError: 'NoneType' object is not
+            # iterable`` and abort the whole reconstruction. Mirrors the
+            # ``and delta["content"]`` value-guard above.
+            tool_calls = delta.get("tool_calls")
+            if isinstance(tool_calls, list):
+                for tc_delta in tool_calls:
+                    if not isinstance(tc_delta, dict):
+                        continue
                     idx = tc_delta.get("index", 0)
                     if idx not in tool_calls_map:
                         tool_calls_map[idx] = {
@@ -914,8 +936,8 @@ class StreamingCCRHandler:
                     tc = tool_calls_map[idx]
                     if "id" in tc_delta:
                         tc["id"] = tc_delta["id"]
-                    if "function" in tc_delta:
-                        fn = tc_delta["function"]
+                    fn = tc_delta.get("function")
+                    if isinstance(fn, dict):
                         if "name" in fn:
                             tc["function"]["name"] = fn["name"]
                         if "arguments" in fn:
diff --git a/headroom/ccr/tool_calls.py b/headroom/ccr/tool_calls.py
index 46e5feacb..44d75ff34 100644
--- a/headroom/ccr/tool_calls.py
+++ b/headroom/ccr/tool_calls.py
@@ -14,6 +14,7 @@ class CCRToolCall:
 
     tool_call_id: str
     hash_key: str
+    tool_name: str | None = None
 
 
 def extract_tool_calls(response: dict[str, Any], provider: str) -> list[dict[str, Any]]:
@@ -88,6 +89,8 @@ def tool_call_id_for_provider(tool_call: dict[str, Any], provider: str) -> str:
     if provider == "google":
         function_call = tool_call.get("functionCall", {})
         if isinstance(function_call, dict):
+            if function_call.get("id"):
+                return str(function_call["id"])
             name = function_call.get("name", CCR_TOOL_NAME)
             return str(name)
         return CCR_TOOL_NAME
@@ -111,11 +114,14 @@ def parse_ccr_tool_calls(
             other_calls.append(tool_call)
             continue
 
+        tool_name = None
+        tool_call_id = tool_call_id_for_provider(tool_call, provider)
+        if provider == "google":
+            function_call = tool_call.get("functionCall", {})
+            if isinstance(function_call, dict) and function_call.get("id"):
+                tool_name = str(function_call.get("name", CCR_TOOL_NAME))
         ccr_calls.append(
-            CCRToolCall(
-                tool_call_id=tool_call_id_for_provider(tool_call, provider),
-                hash_key=hash_key,
-            )
+            CCRToolCall(tool_call_id=tool_call_id, hash_key=hash_key, tool_name=tool_name)
         )
 
     return ccr_calls, other_calls
diff --git a/headroom/ccr/tool_injection.py b/headroom/ccr/tool_injection.py
index 20337285d..86f6cac3f 100644
--- a/headroom/ccr/tool_injection.py
+++ b/headroom/ccr/tool_injection.py
@@ -16,12 +16,24 @@ from __future__ import annotations
 import json
 import re
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 # Tool name constant - used for matching tool calls
 CCR_TOOL_NAME = "headroom_retrieve"
 
 
+@runtime_checkable
+class _HashOwnershipStore(Protocol):
+    """Structural type for verify_ownership()'s store dependency.
+
+    Only needs the existence check — matches CompressionStore.exists()
+    without coupling this module to the concrete cache implementation
+    (or requiring test doubles to subclass it).
+    """
+
+    def exists(self, hash_key: str, clean_expired: bool = False) -> bool: ...
+
+
 def create_ccr_tool_definition(
     provider: str = "anthropic",
 ) -> dict[str, Any]:
@@ -170,6 +182,11 @@ class CCRToolInjector:
     inject_tool: bool = True
     inject_system_instructions: bool = True
     retrieval_endpoint: str = "/v1/retrieve"
+    # Store used to verify a scanned marker's hash is actually ours before
+    # advertising it (issue #2836). None resolves lazily to
+    # get_compression_store() — request-scoped store if one is set, else the
+    # global singleton — matching how every other CCR call site resolves it.
+    compression_store: _HashOwnershipStore | None = None
 
     # Detected compression markers
     _detected_hashes: list[str] = field(default_factory=list)
@@ -281,7 +298,16 @@ class CCRToolInjector:
         return self._detected_hashes
 
     def _scan_text(self, text: str) -> None:
-        """Scan text for compression markers from any compressor."""
+        """Scan text for compression markers from any compressor.
+
+        Shape-only: this matches the bracket format any compressor (or,
+        as it turns out, any *other* context tool) can produce. Callers
+        that need to know the hash is actually ours — i.e. before
+        advertising it to the model via the retrieve tool — must call
+        :meth:`verify_ownership` afterward. Kept separate so this method
+        stays a pure, store-independent text scan (that's what the
+        existing marker-format test suite exercises).
+        """
         for pattern in self._marker_patterns:
             matches = pattern.findall(text)
             for match in matches:
@@ -293,6 +319,59 @@ class CCRToolInjector:
                 if hash_key and hash_key not in self._detected_hashes:
                     self._detected_hashes.append(hash_key)
 
+    def verify_ownership(self, store: _HashOwnershipStore | None = None) -> list[str]:
+        """Drop any detected hash the compression store doesn't recognize.
+
+        The bracket-marker shape (``[... hash=...]``) is not unique to
+        Headroom — other context tools emit visually identical markers.
+        Matching shape alone (what :meth:`scan_for_markers` does) adopts
+        their hashes too: ``has_compressed_content`` goes true and the
+        retrieve tool + "Available hashes" instruction get injected for a
+        hash this proxy never stored. The model then calls
+        ``headroom_retrieve``, gets a guaranteed miss, and re-does the work
+        it already had (issue #2836).
+
+        Call this after :meth:`scan_for_markers` and before checking
+        ``has_compressed_content`` / injecting the tool. Uses the same
+        ``store.exists()`` check the retrieve endpoint itself performs, so
+        a hash that survives this filter is provably redeemable right now
+        (or, if it expires between this check and the model's next call,
+        fails the same way a genuinely-ours stale hash already would —
+        this only removes hashes that were never ours to begin with).
+
+        Args:
+            store: Compression store to verify against. Defaults to
+                ``get_compression_store()`` (request-scoped if set, else
+                the global singleton) — the same resolution every other
+                CCR call site uses.
+
+        Returns:
+            The filtered ``detected_hashes`` list (also updates
+            ``self.detected_hashes`` in place).
+        """
+        if not self._detected_hashes:
+            return self._detected_hashes
+        if store is None:
+            store = self.compression_store
+        if store is None:
+            from headroom.cache.compression_store import get_compression_store
+
+            store = get_compression_store()
+
+        def _safe_exists(hash_key: str) -> bool:
+            try:
+                return store.exists(hash_key)
+            except Exception:
+                # A store lookup failure must not make CCR verification
+                # blow up the request; treat as "not ours" (drop the
+                # marker) — the safe direction, since a dropped real
+                # marker just means the model can't use the retrieve tool
+                # for it this turn, the same failure mode as CCR being off.
+                return False
+
+        self._detected_hashes = [h for h in self._detected_hashes if _safe_exists(h)]
+        return self._detected_hashes
+
     def inject_tool_definition(
         self,
         tools: list[dict[str, Any]] | None,
@@ -437,6 +516,10 @@ class CCRToolInjector:
             tool_was_injected is False if tool was already present (e.g., from MCP).
         """
         self.scan_for_markers(messages)
+        # Shape-only scanning also matches markers from other context tools;
+        # drop hashes this proxy never actually stored before they can
+        # drive tool injection (issue #2836).
+        self.verify_ownership()
 
         if not (self.has_compressed_content or session_has_done_ccr):
             return messages, tools, False
diff --git a/headroom/cli/__init__.py b/headroom/cli/__init__.py
index 529a20d65..5901456a0 100644
--- a/headroom/cli/__init__.py
+++ b/headroom/cli/__init__.py
@@ -25,6 +25,7 @@ from . import (  # noqa: F401
     perf,
     proxy,
     recover,
+    rollout,
     tools,
     update,
     wrap,
diff --git a/headroom/cli/doctor.py b/headroom/cli/doctor.py
index f1f06b380..a45a0cbf1 100644
--- a/headroom/cli/doctor.py
+++ b/headroom/cli/doctor.py
@@ -30,6 +30,8 @@ from headroom.paths import savings_path
 from headroom.providers.claude import (
     REMOTE_CONTROL_BASE_URL_ENV,
     REMOTE_CONTROL_SIBLING_GATE_NOTE,
+    claude_auth_conflict_message,
+    claude_auth_conflict_sources,
     detect_claude_code_version,
     is_custom_anthropic_base_url,
     remote_control_applies_to_auth,
@@ -48,6 +50,13 @@ SKIP = "skip"
 _LOOPBACK_URL_RE = re.compile(r"https?://(?:127\.0\.0\.1|localhost):(\d+)")
 _CODEX_BASE_URL_RE = re.compile(r'base_url\s*=\s*"https?://(?:127\.0\.0\.1|localhost):(\d+)')
 
+# Ollama's fixed default port. `ollama launch claude` writes
+# ``ANTHROPIC_BASE_URL=http://127.0.0.1:11434`` into the launched Claude Code
+# child, which outranks the persistent-install env block and silently bypasses
+# the Headroom proxy (issue #2199). Recognized so the routing diagnostic names
+# the collision instead of telling the user to re-probe port 11434.
+_OLLAMA_DEFAULT_PORT = 11434
+
 
 @dataclass
 class CheckResult:
@@ -182,6 +191,39 @@ def check_claude_routing(settings_path: Path, port: int) -> CheckResult:
     return _classify_routing_url(name, base_url, port, source=str(settings_path))
 
 
+def check_claude_auth_conflict(
+    settings_path: Path,
+    project_settings_path: Path,
+    project_local_settings_path: Path,
+    environ: Mapping[str, str],
+) -> CheckResult | None:
+    """Report contradictory effective Claude credentials without their values."""
+
+    def settings_env(path: Path) -> dict[str, object]:
+        if not path.exists():
+            return {}
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        env = payload.get("env") if isinstance(payload, dict) else None
+        return dict(env) if isinstance(env, dict) else {}
+
+    conflict = claude_auth_conflict_sources(
+        (str(settings_path), settings_env(settings_path)),
+        (str(project_settings_path), settings_env(project_settings_path)),
+        (str(project_local_settings_path), settings_env(project_local_settings_path)),
+        ("shell environment", environ),
+    )
+    if conflict is None:
+        return None
+    return CheckResult(
+        name="claude auth",
+        status=FAIL,
+        summary=claude_auth_conflict_message(conflict),
+    )
+
+
 def check_claude_remote_control_gate(
     settings_path: Path,
     environ: Mapping[str, str],
@@ -344,6 +386,22 @@ def _classify_routing_url(name: str, url: str, port: int, *, source: str) -> Che
         )
     found_port = int(match.group(1))
     if found_port != port:
+        if found_port == _OLLAMA_DEFAULT_PORT:
+            # Not a mis-probed Headroom port — this is Ollama's endpoint, so
+            # `headroom doctor --port 11434` would only chase a red herring.
+            return CheckResult(
+                name=name,
+                status=WARN,
+                summary=(
+                    f"points at Ollama ({url}), not the Headroom proxy ({source}) — "
+                    "`ollama launch claude` bypasses the persistent Headroom route"
+                ),
+                hint=(
+                    "both claim ANTHROPIC_BASE_URL; run Ollama-backed sessions "
+                    "through Headroom by chaining the proxy at its Ollama upstream "
+                    "(see issue #2199)"
+                ),
+            )
         return CheckResult(
             name=name,
             status=WARN,
@@ -544,16 +602,26 @@ def doctor(port: int, emit_json: bool) -> None:
     stats = probe_json(f"{base_url}/stats", timeout=5.0) if livez else None
     installed = get_version()
 
+    project_claude_settings = Path.cwd() / ".claude" / "settings.json"
+    project_local_claude_settings = Path.cwd() / ".claude" / "settings.local.json"
     checks = [
         check_proxy_liveness(livez, base_url),
         check_version_drift(livez, installed),
         check_claude_routing(claude_settings_path(), port),
-        check_wrap_marker_staleness(Path.cwd() / ".claude" / "settings.local.json"),
+        check_wrap_marker_staleness(project_local_claude_settings),
         check_codex_routing(codex_config_path(), port),
         check_shell_env(os.environ, port),
         check_savings(stats, savings_path()),
         check_budget(stats),
     ]
+    auth_conflict_check = check_claude_auth_conflict(
+        claude_settings_path(),
+        project_claude_settings,
+        project_local_claude_settings,
+        os.environ,
+    )
+    if auth_conflict_check is not None:
+        checks.append(auth_conflict_check)
     # Lazy resolver: `claude --version` is a Node CLI subprocess (seconds of
     # cold start, 10s worst-case timeout) — only pay for it when the RC gate
     # is actually plausible (custom base URL + subscription auth).
diff --git a/headroom/cli/init.py b/headroom/cli/init.py
index 8a153ee22..2b6f4bf4c 100644
--- a/headroom/cli/init.py
+++ b/headroom/cli/init.py
@@ -41,6 +41,7 @@ from headroom.install.runtime import (
 from headroom.install.state import ManifestError, load_manifest, save_manifest
 from headroom.install.supervisors import start_supervisor
 from headroom.providers.claude import TOOL_SEARCH_DEFAULT, TOOL_SEARCH_ENV
+from headroom.providers.claude.runtime import TOOL_SEARCH_FOUNDRY_DEFAULT
 from headroom.providers.codex.install import codex_uses_chatgpt_auth
 from headroom.providers.codex.threads import retag_to_headroom
 
@@ -181,7 +182,12 @@ def _ensure_claude_hooks(path: Path, profile: str, port: int) -> None:
     # all into its context window — overflowing it (breaks sub-agent spawns,
     # forces constant compaction). Keep deferral on; respect a user-set value.
     # Shares the TOOL_SEARCH_* constants with `wrap` and `install`.
-    env_map.setdefault(TOOL_SEARCH_ENV, TOOL_SEARCH_DEFAULT)
+    tool_search_default = (
+        TOOL_SEARCH_FOUNDRY_DEFAULT
+        if os.environ.get("CLAUDE_CODE_USE_FOUNDRY")
+        else TOOL_SEARCH_DEFAULT
+    )
+    env_map.setdefault(TOOL_SEARCH_ENV, tool_search_default)
     payload["env"] = env_map
 
     hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}
diff --git a/headroom/cli/install.py b/headroom/cli/install.py
index bf6b79991..50e897ad4 100644
--- a/headroom/cli/install.py
+++ b/headroom/cli/install.py
@@ -11,6 +11,7 @@ from copy import deepcopy
 from dataclasses import dataclass
 
 import click
+from click.core import ParameterSource
 
 from headroom._subprocess import run
 from headroom.install.health import probe_json, probe_ready
@@ -36,6 +37,7 @@ from headroom.install.runtime import (
 from headroom.install.state import (
     ManifestError,
     delete_manifest,
+    list_manifests,
     load_manifest,
     save_manifest,
 )
@@ -65,14 +67,82 @@ def install() -> None:
     """Install and manage persistent Headroom deployments."""
 
 
+def _profile_selection_was_explicit() -> bool:
+    """True when the current command received an explicit ``--profile``.
+
+    An explicit selection must be honored verbatim or rejected, never redirected
+    to ``HEADROOM_DEPLOYMENT_PROFILE`` or a lone installed deployment: silently
+    operating ``stop``/``restart``/``remove`` on a different profile than the one
+    the user typed is dangerous. Only a defaulted (omitted) ``--profile`` is
+    eligible for the recovery fallback. Outside a Click command context (direct
+    calls / unit tests) there is no explicit selection to protect.
+    """
+    ctx = click.get_current_context(silent=True)
+    if ctx is None:
+        return False
+    return bool(ctx.get_parameter_source("profile") == ParameterSource.COMMANDLINE)
+
+
+def _missing_profile_error(
+    name: str,
+    installed: list[DeploymentManifest],
+    *,
+    source: str | None = None,
+) -> click.ClickException:
+    if installed:
+        names = ", ".join(sorted(m.profile for m in installed))
+        hint = f" Installed: {names}. Select one with --profile <name>."
+    else:
+        hint = " No deployments are installed; run `headroom init` or `headroom install apply`."
+    origin = f" (from {source})" if source else ""
+    return click.ClickException(f"No deployment profile named '{name}'{origin} is installed.{hint}")
+
+
 def _require_manifest(profile: str) -> DeploymentManifest:
     try:
         manifest = load_manifest(profile)
     except ManifestError as e:
         raise click.ClickException(str(e)) from None
-    if manifest is None:
-        raise click.ClickException(f"No deployment profile named '{profile}' is installed.")
-    return manifest
+    if manifest is not None:
+        return manifest
+
+    # The requested profile isn't installed. `headroom init` installs under a
+    # non-"default" profile name (e.g. init-user), while every lifecycle command
+    # defaults --profile to "default" -- so on an init'd machine the documented
+    # bare commands (`headroom install status`, etc.) would all dead-end (#2811).
+    installed = list_manifests()
+
+    # An EXPLICIT --profile is honored or rejected verbatim, never redirected: a
+    # typo must not silently act on the env/lone profile (#2832 review).
+    if _profile_selection_was_explicit():
+        raise _missing_profile_error(profile, installed)
+
+    # --profile was defaulted. A non-empty HEADROOM_DEPLOYMENT_PROFILE (which the
+    # runtime exports) is itself an explicit selection: honor it when installed,
+    # otherwise fail naming it. It must never fall through to the lone-manifest
+    # fallback and silently operate on a different deployment (#2832 review).
+    env_profile = os.environ.get("HEADROOM_DEPLOYMENT_PROFILE", "").strip()
+    if env_profile:
+        if env_profile != profile:
+            try:
+                resolved = load_manifest(env_profile)
+            except ManifestError:
+                resolved = None
+            if resolved is not None:
+                return resolved
+        raise _missing_profile_error(env_profile, installed, source="HEADROOM_DEPLOYMENT_PROFILE")
+
+    # Neither CLI nor environment named a profile. A single installed deployment
+    # is unambiguous, so use it; otherwise report what is available.
+    if len(installed) == 1:
+        return installed[0]
+    raise _missing_profile_error(profile, installed)
+
+
+def _is_windows() -> bool:
+    """Return whether this command is running on Windows."""
+
+    return sys.platform.startswith("win")
 
 
 def _start_deployment(manifest: DeploymentManifest, *, assume_start_lock: bool = False) -> None:
@@ -495,7 +565,8 @@ def _echo_installed(manifest: DeploymentManifest, *, prefix: str = "Installed pe
     is_flag=True,
     help=(
         "Opt in to tool_result interceptors (ast-grep Read outliner, etc.) in the "
-        "persistent runtime. Off by default while this feature ships."
+        "persistent runtime. This also selects the required canary rollout channel "
+        "unless --env HEADROOM_ROLLOUT_CHANNEL=... is supplied."
     ),
 )
 @click.option(
@@ -593,6 +664,16 @@ def install_apply(
         bedrock_profile=bedrock_profile,
         extra_env=combined_env,
     )
+    if (
+        preset == InstallPreset.PERSISTENT_SERVICE.value
+        and manifest.preset == InstallPreset.PERSISTENT_TASK.value
+        and _is_windows()
+    ):
+        click.echo(
+            "Warning: persistent-service is not supported on Windows because the "
+            "Python runner cannot act as a Windows service. Falling back to "
+            "persistent-task with Task Scheduler."
+        )
 
     _apply_manifest(manifest)
     _echo_installed(manifest)
diff --git a/headroom/cli/learn.py b/headroom/cli/learn.py
index bcbf51466..b17a339ec 100644
--- a/headroom/cli/learn.py
+++ b/headroom/cli/learn.py
@@ -400,8 +400,9 @@ def _activate_output_shaper(port: int | None = None) -> tuple[str, int]:
     When a proxy is already running locally we hot-enable it via
     ``/admin/runtime-env`` (no restart, the same channel ``wrap`` uses), so
     ``--apply`` actually takes effect. Returns ``(status, port)`` where status is
-    ``"live"`` (enabled on a running proxy), ``"absent"`` (no reachable proxy),
-    or ``"error"``.
+    ``"live"`` (enabled on a running proxy), ``"blocked"`` (the proxy's
+    rollout channel rejected it), ``"absent"`` (no reachable proxy), or
+    ``"error"``.
     """
     import json as _json
     import os as _os
@@ -417,7 +418,22 @@ def _activate_output_shaper(port: int | None = None) -> tuple[str, int]:
     )
     try:
         with urllib.request.urlopen(request, timeout=2) as response:
-            response.read()
+            raw_response = response.read()
+        payload = _json.loads(raw_response) if raw_response else {}
+        rollout = payload.get("rollout") if isinstance(payload, dict) else None
+        if isinstance(rollout, dict):
+            decisions = rollout.get("features")
+            if isinstance(decisions, list):
+                output_shaper = next(
+                    (
+                        item
+                        for item in decisions
+                        if isinstance(item, dict) and item.get("name") == "proxy_output_shaper"
+                    ),
+                    None,
+                )
+                if isinstance(output_shaper, dict) and not output_shaper.get("enabled", False):
+                    return "blocked", resolved_port
         return "live", resolved_port
     except (urllib.error.URLError, OSError):
         # ConnectionRefused (no proxy) or 404 (proxy predates the endpoint).
@@ -555,8 +571,17 @@ def _run_verbosity(
                 f"level {best_profile.level} is live now (while HEADROOM_VERBOSITY_LEVEL is unset)."
             )
             click.echo(
-                "    To keep it on across restarts: export HEADROOM_OUTPUT_SHAPER=1 "
-                "before `headroom wrap ...` (wrap pushes it to the proxy)."
+                "    To keep it on across restarts: export HEADROOM_ROLLOUT_CHANNEL=beta "
+                "and HEADROOM_OUTPUT_SHAPER=1 before `headroom wrap ...`."
+            )
+        elif status == "blocked":
+            click.echo(
+                "\n  ⚠ Level written, but the running proxy's rollout channel blocks the "
+                "beta output shaper."
+            )
+            click.echo(
+                "    Restart it with HEADROOM_ROLLOUT_CHANNEL=beta and "
+                "HEADROOM_OUTPUT_SHAPER=1; the learned level will be used automatically."
             )
         else:
             click.echo(
@@ -564,9 +589,10 @@ def _run_verbosity(
                 "NOT shaping output yet."
             )
             click.echo(
-                "    Enable it: export HEADROOM_OUTPUT_SHAPER=1 then `headroom wrap ...` "
-                "(or start `headroom proxy` with it set). The learned level is then used "
-                "automatically while HEADROOM_VERBOSITY_LEVEL is unset."
+                "    Enable it: export HEADROOM_ROLLOUT_CHANNEL=beta and "
+                "HEADROOM_OUTPUT_SHAPER=1, then run `headroom wrap ...` (or restart "
+                "`headroom proxy`). The learned level is then used automatically while "
+                "HEADROOM_VERBOSITY_LEVEL is unset."
             )
     else:
         click.echo("\n  Dry run — use --apply to persist the level and baseline.")
diff --git a/headroom/cli/main.py b/headroom/cli/main.py
index 1b74e22df..74fdaad8a 100644
--- a/headroom/cli/main.py
+++ b/headroom/cli/main.py
@@ -76,6 +76,7 @@ def _register_commands() -> None:
         perf,  # noqa: F401
         proxy,  # noqa: F401
         recover,  # noqa: F401
+        rollout,  # noqa: F401
         savings,  # noqa: F401
         tools,  # noqa: F401
         update,  # noqa: F401
diff --git a/headroom/cli/memory.py b/headroom/cli/memory.py
index 51a1fd1f9..9a930233a 100644
--- a/headroom/cli/memory.py
+++ b/headroom/cli/memory.py
@@ -30,6 +30,8 @@ from ._utils.formatting import (
 from ._utils.parsers import parse_duration
 from .main import main
 
+_REINDEX_PAGE_SIZE = 1_000
+
 
 def _default_db_path() -> str:
     """Resolve the memory DB the proxy/install actually use.
@@ -66,6 +68,148 @@ def get_store(db_path: str) -> SQLiteMemoryStore:
     return SQLiteMemoryStore(db_path)
 
 
+def _sqlite_table_exists(conn: Any, table_name: str) -> bool:
+    """Return whether a SQLite table or virtual table has been initialized."""
+    row = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?",
+        (table_name,),
+    ).fetchone()
+    return row is not None
+
+
+def _remove_from_search_indexes(db_path: str, memory_ids: list[str]) -> bool:
+    """Remove specific memories from FTS5 and vector search indexes.
+
+    FTS5 cleanup uses a bare sqlite3 connection (FTS5 is built-in).
+    Vector cleanup requires sqlite-vec to load the vec0 virtual-table
+    module; when not installed a warning is printed.
+
+    Returns True when both indexes were fully synced, False when any part
+    of the sync failed.  Callers must treat False as a partial failure and
+    surface it — typically by exiting with a non-zero code so the primary
+    store mutation is not silently reported as fully successful.
+    """
+    if not memory_ids:
+        return True
+
+    import sqlite3
+
+    db = Path(db_path)
+    ok = True
+
+    # FTS5 table lives in the same memory.db file (built-in, no extension needed).
+    try:
+        with sqlite3.connect(str(db)) as conn:
+            if _sqlite_table_exists(conn, "memory_fts"):
+                for i in range(0, len(memory_ids), 500):
+                    chunk = memory_ids[i : i + 500]
+                    placeholders = ",".join("?" * len(chunk))
+                    conn.execute(
+                        f"DELETE FROM memory_fts WHERE memory_id IN ({placeholders})",
+                        chunk,
+                    )
+                conn.commit()
+    except Exception as exc:
+        print_warning(f"FTS5 index cleanup incomplete: {exc}")
+        ok = False
+
+    # Vector DB is a sibling file: memory.db -> memory_vectors.db.
+    # vec_embeddings is a vec0 virtual table — the sqlite-vec extension must be
+    # loaded on every connection before touching it.
+    vector_db = db.parent / f"{db.stem}_vectors.db"
+    if not vector_db.exists():
+        return ok
+
+    try:
+        with sqlite3.connect(str(vector_db)) as conn:
+            # A sibling database may exist before the optional vector index has
+            # ever been initialized. That is a valid no-op, not a sync failure.
+            if not _sqlite_table_exists(conn, "vec_metadata"):
+                return ok
+
+            try:
+                import sqlite_vec
+            except ImportError:
+                print_warning(
+                    "sqlite-vec is not installed; stale vector index entries may remain. "
+                    "Run 'headroom memory reindex' after installing sqlite-vec to repair."
+                )
+                return False
+
+            conn.enable_load_extension(True)
+            sqlite_vec.load(conn)
+            conn.enable_load_extension(False)
+            for i in range(0, len(memory_ids), 500):
+                chunk = memory_ids[i : i + 500]
+                placeholders = ",".join("?" * len(chunk))
+                rows = conn.execute(
+                    f"SELECT rowid FROM vec_metadata WHERE memory_id IN ({placeholders})",
+                    chunk,
+                ).fetchall()
+                rowids = [r[0] for r in rows]
+                if rowids:
+                    rph = ",".join("?" * len(rowids))
+                    conn.execute(f"DELETE FROM vec_embeddings WHERE rowid IN ({rph})", rowids)
+                    conn.execute(f"DELETE FROM vec_metadata WHERE rowid IN ({rph})", rowids)
+            conn.commit()
+    except Exception as exc:
+        print_warning(f"Vector index cleanup incomplete: {exc}")
+        ok = False
+
+    return ok
+
+
+def _clear_all_search_indexes(db_path: str) -> bool:
+    """Truncate both search indexes after a full purge.
+
+    Same extension-loading requirement as :func:`_remove_from_search_indexes`.
+    Returns True on full success, False on any partial failure.
+    """
+    import sqlite3
+
+    db = Path(db_path)
+    ok = True
+
+    try:
+        with sqlite3.connect(str(db)) as conn:
+            if _sqlite_table_exists(conn, "memory_fts"):
+                conn.execute("DELETE FROM memory_fts")
+                conn.commit()
+    except Exception as exc:
+        print_warning(f"FTS5 index cleanup incomplete: {exc}")
+        ok = False
+
+    vector_db = db.parent / f"{db.stem}_vectors.db"
+    if not vector_db.exists():
+        return ok
+
+    try:
+        with sqlite3.connect(str(vector_db)) as conn:
+            if not _sqlite_table_exists(conn, "vec_metadata"):
+                return ok
+
+            try:
+                import sqlite_vec
+            except ImportError:
+                print_warning(
+                    "sqlite-vec is not installed; stale vector index entries may remain. "
+                    "Run 'headroom memory reindex' after installing sqlite-vec to repair."
+                )
+                return False
+
+            conn.enable_load_extension(True)
+            sqlite_vec.load(conn)
+            conn.enable_load_extension(False)
+            conn.execute("DELETE FROM vec_embeddings")
+            conn.execute("DELETE FROM vec_metadata")
+            conn.commit()
+    except Exception as exc:
+        print_warning(f"Vector index cleanup incomplete: {exc}")
+        ok = False
+
+    return ok
+
+
 def _resolve_memory(store: SQLiteMemoryStore, memory_id: str) -> Memory:
     """Resolve an exact or unambiguous partial memory ID."""
     memory = asyncio.run(store.get(memory_id))
@@ -620,13 +764,37 @@ def edit_memory(
                 mem = matches[0]
 
         # Update fields
+        content_changed = content is not None and content != mem.content
         if content is not None:
             mem.content = content
         if importance is not None:
             mem.importance = importance
 
+        index_ok = True
+        if content_changed:
+            # Clear the stale embedding so the memory MCP server re-embeds on
+            # next startup. Also remove the old FTS5 and vector index entries
+            # now to avoid serving stale search results until then.
+            mem.embedding = None
+            index_ok = _remove_from_search_indexes(db_path, [mem.id])
+            # Re-index FTS5 immediately with new content (no embedder needed).
+            try:
+                from ..memory.adapters.fts5 import FTS5TextIndex
+
+                fts = FTS5TextIndex(db_path=db_path)
+                asyncio.run(fts.index_memory(mem))
+            except Exception as exc:
+                print_warning(f"FTS5 re-index incomplete: {exc}")
+                index_ok = False
+
         # Save
         asyncio.run(store.save(mem))
+        if not index_ok:
+            print_warning(
+                f"Updated memory {mem.id[:8]}, but search index sync incomplete. "
+                "Run 'headroom memory reindex' to repair."
+            )
+            sys.exit(1)
         print_success(f"Updated memory {mem.id[:8]}")
 
     except Exception as e:
@@ -775,7 +943,14 @@ def delete_memories(
 
         # Delete
         deleted = asyncio.run(store.delete_batch(resolved_ids))
-        print_success(f"Deleted {deleted} memory(ies).")
+        if _remove_from_search_indexes(db_path, resolved_ids):
+            print_success(f"Deleted {deleted} memory(ies).")
+        else:
+            print_warning(
+                f"Deleted {deleted} memory(ies) from store, but search index sync "
+                "incomplete. Run 'headroom memory reindex' to repair."
+            )
+            sys.exit(1)
 
     except click.Abort:
         click.echo("Aborted.")
@@ -897,7 +1072,14 @@ def prune_memories(
         # Delete
         ids_to_delete = [m.id for m in memories]
         deleted = asyncio.run(store.delete_batch(ids_to_delete))
-        print_success(f"Deleted {deleted} memory(ies).")
+        if _remove_from_search_indexes(db_path, ids_to_delete):
+            print_success(f"Deleted {deleted} memory(ies).")
+        else:
+            print_warning(
+                f"Deleted {deleted} memory(ies) from store, but search index sync "
+                "incomplete. Run 'headroom memory reindex' to repair."
+            )
+            sys.exit(1)
 
     except click.BadParameter as e:
         print_error(str(e))
@@ -952,7 +1134,14 @@ def purge_memories(ctx: click.Context, db_path: str, confirm_flag: bool) -> None
 
         # Purge
         deleted = asyncio.run(store.clear_all())
-        print_success(f"Purged {deleted} memory(ies).")
+        if _clear_all_search_indexes(db_path):
+            print_success(f"Purged {deleted} memory(ies).")
+        else:
+            print_warning(
+                f"Purged {deleted} memory(ies) from store, but search index sync "
+                "incomplete. Run 'headroom memory reindex' to repair."
+            )
+            sys.exit(1)
 
     except click.Abort:
         click.echo("Aborted.")
@@ -962,6 +1151,143 @@ def purge_memories(ctx: click.Context, db_path: str, confirm_flag: bool) -> None
         sys.exit(1)
 
 
+@memory.command("reindex")
+@db_path_option
+@click.pass_context
+def reindex_memories(ctx: click.Context, db_path: str) -> None:
+    """Rebuild FTS5 search index and remove orphaned vector entries.
+
+    Use this to repair an inconsistent index after a failed delete, prune,
+    or purge.  Run it after installing sqlite-vec to clean up any vector
+    entries that could not be removed earlier.
+
+    Vector embeddings are not regenerated by this command — they are rebuilt
+    automatically when the Headroom server next starts.
+
+    \b
+    Example:
+        headroom memory reindex
+    """
+    import sqlite3
+
+    store = get_store(db_path)
+
+    try:
+        # Page through the complete active store. A fixed cap is destructive:
+        # clearing FTS and rebuilding only the first N rows drops valid search
+        # coverage, while using the same truncated ID set for vector cleanup
+        # misclassifies later primary rows as orphans.
+        memories: list[Memory] = []
+        offset = 0
+        while True:
+            page = asyncio.run(
+                store.query(
+                    MemoryFilter(
+                        limit=_REINDEX_PAGE_SIZE,
+                        offset=offset,
+                        order_by="created_at",
+                        order_desc=False,
+                    )
+                )
+            )
+            if not page:
+                break
+            memories.extend(page)
+            offset += len(page)
+
+        db = Path(db_path)
+        ok = True
+
+        # --- FTS5: wipe and rebuild from primary store ---
+        from ..memory.adapters.fts5 import FTS5TextIndex
+
+        # Construction initializes an absent optional FTS table. Cleanup
+        # helpers, by contrast, intentionally treat an absent table as a no-op.
+        fts = FTS5TextIndex(db_path=db_path)
+        try:
+            with sqlite3.connect(str(db)) as conn:
+                conn.execute("DELETE FROM memory_fts")
+                conn.commit()
+        except Exception as exc:
+            print_error(f"Failed to clear FTS5 index: {exc}")
+            sys.exit(1)
+
+        fts_indexed = 0
+        for mem in memories:
+            try:
+                asyncio.run(fts.index_memory(mem))
+                fts_indexed += 1
+            except Exception as exc:
+                print_warning(f"FTS5: failed to index {mem.id[:8]}: {exc}")
+                ok = False
+
+        # --- Vector: remove orphaned entries (requires sqlite-vec) ---
+        vector_db = db.parent / f"{db.stem}_vectors.db"
+        vector_msg = ""
+        if vector_db.exists():
+            # Orphan detection is based on every primary row, including
+            # superseded memories that are intentionally omitted from FTS.
+            with store._get_conn() as conn:
+                primary_ids = {row[0] for row in conn.execute("SELECT id FROM memories")}
+            try:
+                with sqlite3.connect(str(vector_db)) as conn:
+                    if not _sqlite_table_exists(conn, "vec_metadata"):
+                        vector_msg = ", vector index not initialized"
+                    else:
+                        import sqlite_vec
+
+                        conn.enable_load_extension(True)
+                        sqlite_vec.load(conn)
+                        conn.enable_load_extension(False)
+                        rows = conn.execute("SELECT memory_id FROM vec_metadata").fetchall()
+                        orphan_ids = [r[0] for r in rows if r[0] not in primary_ids]
+                        if orphan_ids:
+                            for i in range(0, len(orphan_ids), 500):
+                                chunk = orphan_ids[i : i + 500]
+                                ph = ",".join("?" * len(chunk))
+                                vec_rows = conn.execute(
+                                    f"SELECT rowid FROM vec_metadata WHERE memory_id IN ({ph})",
+                                    chunk,
+                                ).fetchall()
+                                rowids = [r[0] for r in vec_rows]
+                                if rowids:
+                                    rph = ",".join("?" * len(rowids))
+                                    conn.execute(
+                                        f"DELETE FROM vec_embeddings WHERE rowid IN ({rph})",
+                                        rowids,
+                                    )
+                                    conn.execute(
+                                        f"DELETE FROM vec_metadata WHERE rowid IN ({rph})",
+                                        rowids,
+                                    )
+                            conn.commit()
+                        vector_msg = (
+                            f", removed {len(orphan_ids)} orphaned vector entry(ies)"
+                            if orphan_ids
+                            else ", vector index clean"
+                        )
+            except ImportError:
+                vector_msg = (
+                    " (vector index skipped: sqlite-vec not installed — "
+                    "install with: pip install sqlite-vec)"
+                )
+                ok = False
+            except Exception as exc:
+                vector_msg = f" (vector index cleanup failed: {exc})"
+                ok = False
+
+        msg = f"Re-indexed {fts_indexed}/{len(memories)} memories{vector_msg}."
+        if ok:
+            print_success(msg)
+        else:
+            print_warning(msg)
+            sys.exit(1)
+
+    except Exception as e:
+        print_error(f"Failed to reindex: {e}")
+        sys.exit(1)
+
+
 @memory.command("export")
 @db_path_option
 @click.option(
diff --git a/headroom/cli/output_savings.py b/headroom/cli/output_savings.py
index a341b2eea..c3598fc3b 100644
--- a/headroom/cli/output_savings.py
+++ b/headroom/cli/output_savings.py
@@ -28,7 +28,10 @@ def output_savings() -> None:
     if not path.exists():
         click.echo("No output-savings data yet.")
         click.echo("Run `headroom learn --verbosity --apply` to seed the baseline,")
-        click.echo("then enable the shaper (HEADROOM_OUTPUT_SHAPER=1) and send traffic.")
+        click.echo(
+            "then enable the beta shaper (HEADROOM_ROLLOUT_CHANNEL=beta "
+            "HEADROOM_OUTPUT_SHAPER=1) and send traffic."
+        )
         return
 
     ledger = SavingsLedger.load(path)
diff --git a/headroom/cli/perf.py b/headroom/cli/perf.py
index 5c512a073..f3bc65112 100644
--- a/headroom/cli/perf.py
+++ b/headroom/cli/perf.py
@@ -79,6 +79,8 @@ def perf(hours: float, raw: bool, output_format: str) -> None:
                 "tokens_before",
                 "tokens_after",
                 "tokens_saved",
+                "message_tokens_saved",
+                "tool_tokens_saved",
                 "savings_pct",
                 "list_price_per_mtok",
             ]
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 30292a4e1..73e2aee8a 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -4,6 +4,7 @@ import logging
 import os
 import sys
 import warnings
+from importlib import import_module
 from typing import Any, Literal, cast
 
 import click
@@ -18,6 +19,38 @@ from headroom.proxy.modes import PROXY_MODE_CACHE, normalize_proxy_mode
 
 from .main import main
 
+
+def ensure_proxy_dependencies() -> None:
+    """Verify optional proxy extras are installed before starting or wrapping."""
+    required_modules: list[str] = [
+        "fastapi",
+        "uvicorn",
+        "httpx",
+        "openai",
+        "mcp",
+        "magika",
+        "zstandard",
+        "websockets",
+        "onnxruntime",
+        "transformers",
+        "watchdog",
+    ]
+    if sys.implementation.name != "pypy":
+        required_modules.append("orjson")
+
+    try:
+        for module in required_modules:
+            import_module(module)
+    except ImportError as e:
+        click.secho(
+            "Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]",
+            fg="red",
+            err=True,
+        )
+        click.secho(f"Details: {e}", fg="red", err=True)
+        raise SystemExit(1) from None
+
+
 # ---------------------------------------------------------------------------
 # Startup log suppression.
 #
@@ -258,7 +291,7 @@ def dashboard(port: int, no_open: bool) -> None:
     is_flag=True,
     help=(
         "Opt in to tool_result interceptors (ast-grep Read outliner, etc.). "
-        "Off by default while this feature ships."
+        "Requires HEADROOM_ROLLOUT_CHANNEL=canary (or dev)."
     ),
 )
 @click.option("--no-optimize", is_flag=True, help="Disable optimization (passthrough mode)")
@@ -313,6 +346,19 @@ def dashboard(port: int, no_open: bool) -> None:
         "retrieval marker, so no MCP retrieve tool is needed. Env: HEADROOM_LOSSLESS=1."
     ),
 )
+@click.option(
+    "--ccr-inline-resolve",
+    is_flag=True,
+    envvar="HEADROOM_CCR_INLINE_RESOLVE",
+    help=(
+        "Resolve <<ccr:...>> markers inline on the response path instead of "
+        "relying on the model to call headroom_retrieve. For callers with no "
+        "tool-call round-trip to redeem a marker (e.g. Headroom running as a "
+        "LiteLLM guardrail/proxy hop, see issue #2509). Applies to non-streaming "
+        "responses only. Off by default. "
+        "Env: HEADROOM_CCR_INLINE_RESOLVE."
+    ),
+)
 @click.option(
     "--no-ccr-proactive-expansion",
     is_flag=True,
@@ -628,7 +674,8 @@ def dashboard(port: int, no_open: bool) -> None:
     help=(
         "EXPERIMENTAL: activity-based read maturation — hold fresh Reads "
         "out of the provider prefix cache and compress them once their "
-        "file quiesces (env: HEADROOM_READ_MATURATION=1)"
+        "file quiesces. Requires HEADROOM_ROLLOUT_CHANNEL=beta (or dev); "
+        "env: HEADROOM_READ_MATURATION=1."
     ),
 )
 @click.option(
@@ -934,6 +981,7 @@ def proxy(
     tpm: int | None,
     no_ccr: bool,
     lossless: bool,
+    ccr_inline_resolve: bool,
     no_ccr_proactive_expansion: bool,
     proxy_extension: tuple[str, ...],
     compressor: tuple[str, ...],
@@ -1017,23 +1065,16 @@ def proxy(
     Usage with OpenAI-compatible clients:
         OPENAI_BASE_URL=http://localhost:8787/v1 your-app
     """
+    ensure_proxy_dependencies()
+
     # Import here to avoid slow startup
-    try:
-        from headroom.proxy.server import (
-            ProxyConfig,
-            _parse_csv_tools,
-            _parse_exclude_tools,
-            _parse_tool_profiles,
-            run_server,
-        )
-    except ImportError as e:
-        click.secho(
-            "Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]",
-            fg="red",
-            err=True,
-        )
-        click.secho(f"Details: {e}", fg="red", err=True)
-        raise SystemExit(1) from None
+    from headroom.proxy.server import (
+        ProxyConfig,
+        _parse_csv_tools,
+        _parse_exclude_tools,
+        _parse_tool_profiles,
+        run_server,
+    )
 
     # Warn if --learn and --no-learn are both set (--no-learn wins, per docstring)
     if learn and no_learn:
@@ -1066,12 +1107,46 @@ def proxy(
             err=True,
         )
 
+    # Resolve rollout inputs once before constructing any rollout-managed
+    # behavior. The immutable snapshot is injected into ProxyConfig and is also
+    # what /stats later exposes.
+    from headroom.rollout import resolve_rollout
+
+    rollout_requests = []
+    if intercept_tool_results:
+        rollout_requests.append("tool_result_interceptors")
+    if read_maturation:
+        rollout_requests.append("read_maturation")
+    rollout_snapshot = resolve_rollout(os.environ, requested=rollout_requests)
+
+    if read_maturation and not rollout_snapshot.is_enabled("read_maturation"):
+        click.secho(
+            "error: --read-maturation is not available in the current rollout channel "
+            f"({rollout_snapshot.channel.value}). Set HEADROOM_ROLLOUT_CHANNEL=beta "
+            "(or dev), or use HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES=1 for an "
+            "emergency override.",
+            fg="red",
+            err=True,
+        )
+        sys.exit(1)
+
     # Opt-in: turn on tool_result interceptors (ast-grep Read outline, etc.).
     # Only fetch the bundled CLI tool binaries when the feature is enabled —
     # otherwise we'd pay a network round-trip and risk a readonly-FS failure
     # for capabilities the user hasn't asked for. The TransformPipeline reads
-    # this env var at construction time.
+    # the resolved snapshot says it is active.
     if intercept_tool_results:
+        if not rollout_snapshot.is_enabled("tool_result_interceptors"):
+            click.secho(
+                "error: --intercept-tool-results is not available in the current "
+                f"rollout channel ({rollout_snapshot.channel.value}). Set "
+                "HEADROOM_ROLLOUT_CHANNEL=canary to dogfood it, or use "
+                "HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES=1 for emergency override.",
+                fg="red",
+                err=True,
+            )
+            sys.exit(1)
+
         from headroom.binaries import ensure_tools
 
         resolved_tools = ensure_tools()
@@ -1089,7 +1164,6 @@ def proxy(
                 err=True,
             )
             sys.exit(1)
-        os.environ["HEADROOM_INTERCEPT_ENABLED"] = "1"
 
     try:
         resolved_anthropic_extra_headers = resolve_extra_headers(
@@ -1171,6 +1245,7 @@ def proxy(
     config = ProxyConfig(
         host=host,
         port=port,
+        rollout=rollout_snapshot,
         anthropic_api_url=provider_api_overrides.anthropic,
         anthropic_extra_headers=resolved_anthropic_extra_headers,
         openai_extra_headers=resolved_openai_extra_headers,
@@ -1206,6 +1281,7 @@ def proxy(
         # CCR fully on.
         ccr_inject_tool=not no_ccr,
         ccr_inject_marker=not no_ccr,
+        ccr_resolve_markers_inline=ccr_inline_resolve,
         lossless=lossless,
         ccr_proactive_expansion=not no_ccr_proactive_expansion,
         # Flatten repeat-flag tuple AND any comma-separated values inside it.
@@ -1276,7 +1352,7 @@ def proxy(
         # Read lifecycle: ON by default (use --no-read-lifecycle to disable)
         read_lifecycle=not no_read_lifecycle,
         # Read maturation (Mechanism B): experimental, OFF by default
-        read_maturation=read_maturation,
+        read_maturation=rollout_snapshot.is_enabled("read_maturation"),
         read_maturation_quiesce_turns=read_maturation_quiesce_turns,
         read_maturation_max_hold_turns=read_maturation_max_hold_turns,
         read_maturation_min_size_bytes=read_maturation_min_size_bytes,
diff --git a/headroom/cli/rollout.py b/headroom/cli/rollout.py
new file mode 100644
index 000000000..fce624174
--- /dev/null
+++ b/headroom/cli/rollout.py
@@ -0,0 +1,66 @@
+"""Runtime rollout diagnostics commands."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import click
+
+from headroom.rollout import RolloutConfigurationError, resolve_rollout
+
+from .main import main
+
+
+@main.group("rollout")
+def rollout_group() -> None:
+    """Inspect runtime feature-rollout policy (not package releases)."""
+
+
+@rollout_group.command("status")
+@click.option("--channel", envvar="HEADROOM_ROLLOUT_CHANNEL")
+@click.option("--features", envvar="HEADROOM_FEATURES")
+@click.option("--disable-features", envvar="HEADROOM_DISABLE_FEATURES")
+@click.option(
+    "--unsafe-allow-unstable-features",
+    is_flag=True,
+    envvar="HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES",
+)
+@click.option("--json", "json_output", is_flag=True, help="Emit the versioned JSON snapshot.")
+def rollout_status(
+    channel: str | None,
+    features: str | None,
+    disable_features: str | None,
+    unsafe_allow_unstable_features: bool,
+    json_output: bool,
+) -> None:
+    """Resolve and print the supplied runtime rollout configuration."""
+
+    env = dict(os.environ)
+    if channel is not None:
+        env["HEADROOM_ROLLOUT_CHANNEL"] = channel
+    if features is not None:
+        env["HEADROOM_FEATURES"] = features
+    if disable_features is not None:
+        env["HEADROOM_DISABLE_FEATURES"] = disable_features
+    if unsafe_allow_unstable_features:
+        env["HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES"] = "1"
+    try:
+        snapshot = resolve_rollout(env, strict=True)
+    except RolloutConfigurationError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    payload = snapshot.to_dict()
+    if json_output:
+        click.echo(json.dumps(payload, sort_keys=True, separators=(",", ":")))
+        return
+
+    click.echo(f"Rollout channel: {snapshot.channel.value}")
+    click.echo(f"Policy: {snapshot.policy_version} ({snapshot.registry_digest})")
+    click.echo(f"Snapshot: {snapshot.snapshot_digest}")
+    click.echo(f"Qualification eligible: {str(snapshot.qualification_eligible).lower()}")
+    for decision in snapshot.decisions:
+        click.echo(
+            f"  {decision.name}: enabled={str(decision.enabled).lower()} "
+            f"decision={decision.reason.value}"
+        )
diff --git a/headroom/cli/update.py b/headroom/cli/update.py
index 9b907f126..93796d246 100644
--- a/headroom/cli/update.py
+++ b/headroom/cli/update.py
@@ -328,13 +328,14 @@ def detect_install_method(extras: str | None = None) -> InstallMethod:
 
       1. git checkout            → refuse (`git pull`)
       2. editable install        → refuse (reinstall from source)
-      3. Docker                  → refuse (pull a new image)
+      3. explicit HEADROOM_IN_DOCKER → refuse (official image opt-out)
       4. pipx                    → `pipx upgrade`
       5. uv tool                 → `uv tool upgrade`
       6. venv / virtualenv / conda → `sys.executable -m pip install -U`
       7. user-site (`pip --user`)  → `sys.executable -m pip install -U --user`
-      8. externally-managed system Python (PEP 668) → refuse with guidance
-      9. writable global Python  → `sys.executable -m pip install -U` (last resort)
+      8. bare /.dockerenv (system interpreter) → refuse (pull a new image)
+      9. externally-managed system Python (PEP 668) → refuse with guidance
+     10. writable global Python  → `sys.executable -m pip install -U` (last resort)
     """
     if _is_source_checkout():
         return InstallMethod(
@@ -351,7 +352,13 @@ def detect_install_method(extras: str | None = None) -> InstallMethod:
                 "reinstall with `pip install -U --force-reinstall .`."
             ),
         )
-    if _in_docker():
+    # An EXPLICIT HEADROOM_IN_DOCKER (set by the official image) is a deliberate
+    # "pull a newer image" opt-out and wins up front, even over a venv. The bare
+    # /.dockerenv heuristic is handled far lower, after ownership detection, so a
+    # pip / pipx / uv install inside a devcontainer, Codespace, or docker dev
+    # image is not shadowed by the mere fact that the environment is a container
+    # (#2816).
+    if os.environ.get("HEADROOM_IN_DOCKER", "").strip():
         return InstallMethod(
             kind="docker",
             can_self_update=False,
@@ -404,6 +411,18 @@ def detect_install_method(extras: str | None = None) -> InstallMethod:
             argv=[sys.executable, "-m", "pip", "install", "-U", "--user", _spec(extras)],
         )
 
+    # Bare /.dockerenv with no venv / pipx / uv / user-site owner: the install
+    # belongs to the container's own interpreter, where "pull a newer image" is
+    # the only real route. An explicit HEADROOM_IN_DOCKER already returned above.
+    if _in_docker():
+        return InstallMethod(
+            kind="docker",
+            can_self_update=False,
+            guidance=(
+                "Running inside a container — pull a newer Headroom image instead of self-updating."
+            ),
+        )
+
     if _is_externally_managed():
         return InstallMethod(
             kind="system",
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index af22dc45c..09c6642bb 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -33,6 +33,8 @@ import sys
 import time
 import urllib.parse
 from collections.abc import Callable
+from contextlib import contextmanager
+from functools import wraps
 from pathlib import Path
 from typing import Any, cast
 
@@ -57,6 +59,7 @@ from headroom._version import normalize_release_version as _normalize_release_ve
 from headroom.agent_savings import (
     apply_agent_savings_env_defaults,
 )
+from headroom.cli.proxy import ensure_proxy_dependencies
 from headroom.copilot_auth import (
     _API_TOKEN_ENV_VARS,
     _API_TOKEN_EXPIRES_AT_ENV_VAR,
@@ -74,6 +77,8 @@ from headroom.providers.claude import (
     REMOTE_CONTROL_BASE_URL_ENV,
     TOOL_SEARCH_DEFAULT,
     TOOL_SEARCH_ENV,
+    claude_auth_conflict_message,
+    claude_auth_conflict_sources,
     claude_user_settings_path,
     configure_vscode_claude_settings,
     detect_claude_code_version,
@@ -87,6 +92,7 @@ from headroom.providers.claude import (
 from headroom.providers.claude import (
     proxy_base_url as _claude_proxy_base_url,
 )
+from headroom.providers.claude.runtime import TOOL_SEARCH_FOUNDRY_DEFAULT
 from headroom.providers.codex import build_launch_env as _build_codex_launch_env
 from headroom.providers.codex.install import codex_uses_chatgpt_auth
 from headroom.providers.codex.threads import retag_to_headroom, retag_to_native
@@ -256,6 +262,30 @@ def _read_settings_for_write(path: Path) -> dict[str, Any]:
     return cast("dict[str, Any]", payload)
 
 
+def _claude_settings_env(path: Path) -> dict[str, object]:
+    """Read a Claude settings env block for preflight validation."""
+    env = _read_settings_for_write(path).get("env")
+    return dict(env) if isinstance(env, dict) else {}
+
+
+def _raise_on_claude_auth_conflict(
+    *,
+    user_settings_path: Path,
+    project_settings_path: Path,
+    project_local_settings_path: Path,
+    environ: dict[str, str],
+) -> None:
+    """Refuse an auth state Claude Code rejects before mutating wrap state."""
+    conflict = claude_auth_conflict_sources(
+        (str(user_settings_path), _claude_settings_env(user_settings_path)),
+        (str(project_settings_path), _claude_settings_env(project_settings_path)),
+        (str(project_local_settings_path), _claude_settings_env(project_local_settings_path)),
+        ("shell environment", environ),
+    )
+    if conflict is not None:
+        raise click.ClickException(claude_auth_conflict_message(conflict))
+
+
 def _append_text(path: Path, content: str) -> None:
     """Append to a text file as UTF-8 without translating line endings."""
     fsutil.append_text(path, content)
@@ -269,13 +299,14 @@ _WRAP_PROXY_TIMEOUT_ML_MODULES = ("torch", "sentence_transformers", "spacy")
 # Issue #746: Claude Code disables on-demand tool loading (deferral) when
 # ANTHROPIC_BASE_URL is a custom host and ENABLE_TOOL_SEARCH is unset, which
 # inflates the local context window by tens of K tokens. Setting the env var
-# when we launch Claude Code keeps deferral on. Default to "true" — defer the
-# MCP/system tools for maximum context savings, matching native first-party
-# behaviour (core built-ins like Read/Edit/Bash are never deferred by Claude
-# Code, so the agent loop is unaffected). The key/default are shared with
-# `init` and `install` via the Claude provider package to prevent drift.
+# when we launch Claude Code keeps deferral on. The generic default stays
+# "true" for non-Foundry sessions, while Foundry uses a dedicated compatibility
+# default of "false" because its upstream does not support the deferred-tool
+# shape. The key/defaults are shared with `init` and `install` via the Claude
+# provider package to prevent drift.
 _TOOL_SEARCH_ENV = TOOL_SEARCH_ENV
 _TOOL_SEARCH_DEFAULT = TOOL_SEARCH_DEFAULT
+_TOOL_SEARCH_FOUNDRY_DEFAULT = TOOL_SEARCH_FOUNDRY_DEFAULT
 _AGENT_SAVINGS_WRAP_AGENTS = {"claude", "codex", "cursor", "grok", "grok_build"}
 
 # 1M context window for `wrap claude` (#1158). Claude Code only sends the
@@ -303,6 +334,33 @@ def _resolve_1m_model(current: str | None) -> str:
     return base if base.endswith(_CONTEXT_1M_SUFFIX) else f"{base}{_CONTEXT_1M_SUFFIX}"
 
 
+def _apply_1m_to_claude_args(args: tuple[str, ...]) -> tuple[tuple[str, ...], str | None]:
+    """Add the ``[1m]`` suffix to an explicit ``--model`` in pass-through args.
+
+    Claude Code gives the ``--model`` CLI flag precedence over the
+    ``ANTHROPIC_MODEL`` env var, so when a user passes both ``--1m`` and
+    ``--model X`` the env-var suffix is silently shadowed and the session caps at
+    200k (#2915). Rewriting the flag's value the same way ``_resolve_1m_model``
+    rewrites the env var keeps ``--1m`` effective on the higher-precedence flag.
+
+    Handles ``--model VALUE`` and ``--model=VALUE`` (the first occurrence only, as
+    Claude Code honours the first). Idempotent via ``_resolve_1m_model``. Returns
+    ``(new_args, rewritten_value)``; ``rewritten_value`` is ``None`` when no
+    ``--model`` was present (the env-var path already covers that case).
+    """
+    out = list(args)
+    for i, arg in enumerate(out):
+        if arg == "--model" and i + 1 < len(out):
+            rewritten = _resolve_1m_model(out[i + 1])
+            out[i + 1] = rewritten
+            return tuple(out), rewritten
+        if arg.startswith("--model="):
+            rewritten = _resolve_1m_model(arg.split("=", 1)[1])
+            out[i] = f"--model={rewritten}"
+            return tuple(out), rewritten
+    return tuple(out), None
+
+
 def _normalize_tool_search_mode(value: str) -> str:
     """Validate an ``ENABLE_TOOL_SEARCH`` value and return it normalized.
 
@@ -331,7 +389,8 @@ def _configure_tool_search_env(env: dict[str, str], flag_value: str | None) -> s
     1. explicit ``--tool-search`` flag — wins (the user asked for it on the CLI),
     2. a pre-existing ``ENABLE_TOOL_SEARCH`` in the environment — respected and
        left untouched (the user's own Claude Code knob),
-    3. the built-in default (``true``).
+    3. the built-in mode-specific default (``true`` normally, ``false`` on
+       Foundry).
 
     Returns the value written, or ``None`` when an existing environment value
     was deliberately left in place.
@@ -346,8 +405,11 @@ def _configure_tool_search_env(env: dict[str, str], flag_value: str | None) -> s
     existing = env.get(_TOOL_SEARCH_ENV)
     if existing is not None and existing.strip():
         return None
-    env[_TOOL_SEARCH_ENV] = _TOOL_SEARCH_DEFAULT
-    return _TOOL_SEARCH_DEFAULT
+    default = (
+        _TOOL_SEARCH_FOUNDRY_DEFAULT if env.get("CLAUDE_CODE_USE_FOUNDRY") else _TOOL_SEARCH_DEFAULT
+    )
+    env[_TOOL_SEARCH_ENV] = default
+    return default
 
 
 # ENABLE_TOOL_SEARCH modes that turn deferral OFF. Everything else Claude Code
@@ -415,6 +477,8 @@ def _resolved_tool_search_mode(flag_value: str | None) -> str:
     existing = os.environ.get(_TOOL_SEARCH_ENV)
     if existing is not None:
         probe[_TOOL_SEARCH_ENV] = existing
+    if os.environ.get("CLAUDE_CODE_USE_FOUNDRY"):
+        probe["CLAUDE_CODE_USE_FOUNDRY"] = os.environ["CLAUDE_CODE_USE_FOUNDRY"]
     written = _configure_tool_search_env(probe, flag_value)
     return written if written is not None else probe.get(_TOOL_SEARCH_ENV, "")
 
@@ -629,6 +693,15 @@ def _start_proxy(
     proxy_env = os.environ.copy()
     _scrub_copilot_proxy_seed_env(proxy_env)
     proxy_env["PYTHONIOENCODING"] = "utf-8"
+    # `python -m headroom.cli` prepends the launch cwd to sys.path, so running
+    # `wrap` from a directory that contains a `headroom/` folder (most commonly a
+    # clone of this repo, whose package lives at <root>/headroom/) shadows the
+    # installed wheel with the raw source tree, which has no compiled
+    # `headroom._core`. The proxy then dies with "No module named 'headroom._core'"
+    # and wrap silently falls back to launching the client unwrapped (#2793).
+    # PYTHONSAFEPATH disables that cwd prepend (Python 3.11+; a harmless no-op on
+    # 3.10) so the subprocess always resolves the installed package.
+    proxy_env["PYTHONSAFEPATH"] = "1"
     # Vertex AI RST_STREAMs HTTP/2 connections (error_code:2). Force HTTP/1.1
     # when wrapping a Vertex-mode client so upstream requests succeed.
     if os.environ.get("CLAUDE_CODE_USE_VERTEX") or os.environ.get("ANTHROPIC_VERTEX_PROJECT_ID"):
@@ -750,7 +823,7 @@ _RETIRED_CONTEXT_TOOL_MESSAGE = (
     "rewrote shell commands through a third-party binary Headroom no longer "
     "manages. Drop --context-tool / --no-context-tool and unset "
     f"{_RETIRED_CONTEXT_TOOL_ENV}; `headroom wrap` uninstalls what they left "
-    "behind on first run."
+    "behind automatically."
 )
 
 
@@ -810,8 +883,10 @@ def _report_context_tool_purge() -> None:
     default: the Claude ``PreToolUse`` hook, the vendored binaries and the
     injected hint-file guidance are all durable on disk. Running this once per
     ``wrap`` / ``unwrap`` invocation is what actually makes the tools go away.
-    Silent when there is nothing to do, which is the steady state after the first
-    run, and never fatal — a cleanup failure must not block launching the tool.
+    Silent when there is nothing to do — the common case once the machine-global
+    half is stamped done, though the project- and config-directory-scoped half
+    still runs every launch — and never fatal: a cleanup failure must not block
+    launching the tool.
 
     Reports on **stderr**: some subcommands (``wrap/unwrap openclaw
     --prepare-only``) emit machine-readable JSON on stdout as their entire
@@ -1431,6 +1506,36 @@ def _write_claude_wrap_base_url(
     return previous
 
 
+def _write_claude_wrap_tool_search(value: str, *, settings_path: Path | None = None) -> str | None:
+    """Persist the resolved tool-search mode for daemon-spawned workers.
+
+    Claude Code workers read project settings afresh rather than inheriting
+    the parent process environment (#2492). Keep this separate from the proxy
+    URL crash marker: a stale tool-search mode cannot route traffic to a dead
+    process, and is restored transactionally when the wrap session exits.
+    """
+    path = settings_path or (Path.cwd() / ".claude" / "settings.local.json")
+    payload = _read_settings_for_write(path)
+    env_map = dict(payload.get("env") or {}) if isinstance(payload.get("env"), dict) else {}
+    previous = env_map.get(_TOOL_SEARCH_ENV)
+    env_map[_TOOL_SEARCH_ENV] = value
+    payload["env"] = env_map
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _write_text(path, json.dumps(payload, indent=2) + "\n")
+    return previous
+
+
+def _restore_claude_wrap_tool_search(
+    previous: str | None, *, settings_path: Path | None = None
+) -> None:
+    """Restore the project-local tool-search value written for this session."""
+    _restore_claude_wrap_base_url(
+        previous,
+        settings_path=settings_path,
+        _key_override=_TOOL_SEARCH_ENV,
+    )
+
+
 def _restore_claude_wrap_base_url(
     previous: str | None,
     *,
@@ -1671,6 +1776,18 @@ def _serena_project_skip_reason(root: Path) -> str | None:
     Serena's own ``~/.serena`` config directory. A linked git worktree (its
     top-level ``.git`` is a file, not a directory) is an ephemeral checkout that
     would pay for its own index at a path that soon disappears.
+
+    A project with no ``.serena/project.yml`` is skipped because the pre-index
+    cannot succeed there (#2938). ``serena project index`` auto-creates the file
+    when it is missing, and that auto-creation calls
+    ``ProjectConfig.autogenerate(interactive=True)``, which asks one ``[y/N]``
+    question per additionally-detected language server. The CLI has no
+    non-interactive switch; the only way to reach the silent branch is to pass
+    ``--ls/--language`` explicitly, which means Headroom guessing the project's
+    languages again — exactly the hand-maintained map removed below. Serena's
+    MCP server generates that file itself (non-interactively) on first start and
+    indexes lazily on demand, so the pre-index simply resumes from the next
+    wrap onwards.
     """
     try:
         resolved = root.resolve()
@@ -1681,46 +1798,144 @@ def _serena_project_skip_reason(root: Path) -> str | None:
         return "$HOME is not a project"
     if (resolved / ".git").is_file():
         return "linked git worktree"
+    if not (resolved / ".serena" / "project.yml").is_file():
+        return "no .serena/project.yml yet — Serena will create it and index on demand"
     return None
 
 
+#: Upper bound on the synchronous pre-index. The agent does not launch until
+#: this call returns, so the number is a stall budget, not just a safety net.
+_SERENA_INDEX_TIMEOUT = 300
+
+
+def _kill_serena_index_tree(proc: subprocess.Popen) -> None:
+    """Kill *proc* and everything it spawned (best-effort, never raises).
+
+    ``uvx`` is a launcher: it resolves the environment and then runs the real
+    ``serena`` executable as a grandchild. Killing only the direct child leaves
+    that grandchild alive and reparented to PID 1, so every timed-out pre-index
+    leaked one process that never exits (#2938 — the same failure mode as #615
+    and #880). The child is started in its own process group precisely so the
+    whole tree can be signalled here.
+    """
+    if sys.platform == "win32":
+        # Windows has no process groups to signal for an already-wedged child;
+        # ``taskkill /T`` walks the tree by parent PID instead. ``/F`` because a
+        # process blocked in a read will not act on a graceful close request.
+        try:
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True,
+                timeout=10,
+                check=False,
+            )
+        except Exception:
+            pass
+    else:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except Exception:
+            pass
+    # Backstop: if the tree kill above did not land, at least the direct child
+    # goes. Then reap so the parent does not leave a zombie behind, and close
+    # the capture pipes we opened so the wrap does not carry stray fds into the
+    # agent it is about to exec.
+    try:
+        proc.kill()
+    except Exception:
+        pass
+    try:
+        proc.wait(timeout=10)
+    except Exception:
+        pass
+    for stream in (proc.stdout, proc.stderr, proc.stdin):
+        try:
+            if stream is not None:
+                stream.close()
+        except Exception:
+            pass
+
+
 def _index_serena_project(*, verbose: bool = False) -> None:
     """Warm Serena's symbol cache for the current project (non-fatal).
 
-    Runs ``serena project index`` (the same ``uvx --from git+…`` launch used to
-    start the MCP server) in the project directory so the first symbol query is
-    not paying for a cold index. Timeout-guarded and best-effort: Serena also
-    indexes lazily on demand, so a failure or timeout here never blocks the
-    wrap.
+    Runs ``serena project index`` (the same ``uvx --from serena-agent`` launch
+    used to start the MCP server) in the project directory so the first symbol
+    query is not paying for a cold index. Serena also indexes lazily on demand,
+    so any failure here is survivable.
+
+    This runs on the launch path, synchronously: the agent starts only once it
+    returns, so the timeout below is time the user spends staring at nothing.
+    Two guards keep that bounded (#2938):
+
+    * ``stdin`` is ``DEVNULL``. Serena prompts when it has to auto-create
+      ``project.yml``, and because stdout is captured the question never
+      reaches the terminal — an inherited stdin turned that into a silent,
+      full-timeout hang. EOF makes it fail in about a second instead.
+      ``_serena_project_skip_reason`` already keeps us out of that state; this
+      is the belt-and-braces half, and it covers any future Serena prompt too.
+    * The child gets its own process group so ``_kill_serena_index_tree`` can
+      take out the ``uvx`` grandchild on timeout rather than orphaning it.
     """
     if shutil.which("uvx") is None:
         if verbose:
             click.echo("  Serena: uvx not found — skipping pre-index")
         return
+
+    popen_kwargs: dict[str, Any] = {
+        "stdout": subprocess.PIPE,
+        "stderr": subprocess.PIPE,
+        "stdin": subprocess.DEVNULL,
+        "text": True,
+        # ``subprocess.Popen`` directly, so the encoding defaults that
+        # ``headroom._subprocess.run`` applies have to be repeated here.
+        "encoding": "utf-8",
+        "errors": "replace",
+        "cwd": str(Path.cwd()),
+    }
+    if sys.platform == "win32":
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        popen_kwargs["start_new_session"] = True
+
     try:
-        result = run(
+        proc = subprocess.Popen(
             [
                 "uvx",
+                # PyPI (prebuilt wheels), not the git source that fails to build
+                # under proot-based filesystems (#2871).
                 "--from",
-                "git+https://github.com/oraios/serena",
+                "serena-agent",
                 "serena",
                 "project",
                 "index",
             ],
-            capture_output=True,
-            text=True,
-            timeout=300,
-            cwd=str(Path.cwd()),
+            **popen_kwargs,
         )
-        if result.returncode == 0:
-            click.echo("  Serena: project pre-indexed (symbol cache warmed)")
-        elif verbose:
-            click.echo(f"  Serena: pre-index failed ({(result.stderr or '')[:100]})")
-    except subprocess.TimeoutExpired:
-        click.echo("  Serena: pre-index timed out (will index on demand)")
     except Exception as e:
         if verbose:
             click.echo(f"  Serena: pre-index skipped ({e})")
+        return
+
+    # Announce the wait. Indexing a large repo legitimately takes minutes and
+    # the output is captured, so without this line the wrap looks hung.
+    click.echo("  Serena: pre-indexing project (first run can take a while)…")
+    try:
+        _stdout, stderr = proc.communicate(timeout=_SERENA_INDEX_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        _kill_serena_index_tree(proc)
+        click.echo("  Serena: pre-index timed out (will index on demand)")
+        return
+    except Exception as e:
+        _kill_serena_index_tree(proc)
+        if verbose:
+            click.echo(f"  Serena: pre-index skipped ({e})")
+        return
+
+    if proc.returncode == 0:
+        click.echo("  Serena: project pre-indexed (symbol cache warmed)")
+    elif verbose:
+        click.echo(f"  Serena: pre-index failed ({(stderr or '')[:100]})")
 
 
 def _setup_serena_mcp(
@@ -1787,7 +2002,9 @@ def _setup_serena_mcp(
 
     # Serena is the active engine here (we passed the detect/uvx guards): steer
     # the agent toward symbol-level tools, then warm the symbol cache. Both are
-    # best-effort and non-fatal — neither blocks the wrap.
+    # best-effort and non-fatal, but the pre-index is *synchronous* — the agent
+    # does not launch until it returns or hits ``_SERENA_INDEX_TIMEOUT``. See
+    # ``_index_serena_project`` for how that wait is kept bounded and visible.
     #
     # Headroom no longer writes ``.serena/project.yml`` language scoping. Serena
     # determines the project's languages itself during
@@ -3416,7 +3633,7 @@ def _push_runtime_env(port: int, no_proxy: bool) -> None:
     click.echo(f"  Synced output settings to proxy: {', '.join(sorted(payload))}")
 
 
-def _ensure_proxy(
+def _ensure_proxy_unlocked(
     port: int,
     no_proxy: bool,
     *,
@@ -3435,7 +3652,13 @@ def _ensure_proxy(
     copilot_refresh_oauth_token: str | None = None,
     copilot_api_token_expires_at: float | None = None,
 ) -> tuple[subprocess.Popen | None, int]:
-    """Start or verify proxy. Returns (process_handle, actual_port)."""
+    """Start or verify proxy. Returns (process_handle, actual_port).
+
+    The public ``_ensure_proxy`` wrapper serializes callers per port before
+    entering this function. Keeping the implementation separate makes the
+    lock boundary explicit and ensures every health/configuration check runs
+    under the same startup critical section.
+    """
     helpers = _live_wrap_module()
     copilot_subscription_seed_requested = (
         bool(copilot_api_token)
@@ -3802,6 +4025,81 @@ def _ensure_proxy(
         return None, port
 
 
+@contextmanager
+def _proxy_start_lock(port: int) -> Any:
+    """Serialize wrap proxy startup across processes sharing a port.
+
+    A proxy can spend tens of seconds loading optional ML components before it
+    binds its socket. Without this lock, two concurrent ``headroom wrap``
+    commands both see an unavailable health endpoint, choose the same port,
+    and race to spawn a listener. The lock is deliberately held through the
+    health/configuration checks and startup, then released once the proxy is
+    ready (or startup fails). Lock files are retained so an interrupted
+    process cannot create an inode-replacement race for another waiter.
+    """
+    from headroom import paths as _paths
+
+    lock_path = _paths.proxy_start_lock_path(port)
+    try:
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        lock_file = open(lock_path, "a+b")  # noqa: SIM115
+    except OSError:
+        # Locking is a race-prevention enhancement, not a reason to make wrap
+        # unusable when a read-only/custom workspace cannot hold state. The
+        # existing port bind remains the final safety check in that degraded
+        # environment.
+        yield
+        return
+    with lock_file:
+        if sys.platform == "win32":
+            import msvcrt
+
+            # msvcrt.locking operates on bytes from the current file position.
+            lock_file.seek(0)
+            if lock_file.read(1) == b"":
+                lock_file.seek(0)
+                lock_file.write(b"0")
+                lock_file.flush()
+            lock_file.seek(0)
+            # LK_LOCK has implementation-dependent retry limits. A proxy may
+            # legitimately take longer than that to load ML components, so
+            # use the non-blocking primitive in a loop instead.
+            while True:
+                try:
+                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError:
+                    time.sleep(0.05)
+            try:
+                yield
+            finally:
+                lock_file.seek(0)
+                msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+
+
+@wraps(_ensure_proxy_unlocked)
+def _ensure_proxy(
+    port: int,
+    no_proxy: bool,
+    **kwargs: Any,
+) -> tuple[subprocess.Popen | None, int]:
+    """Start or reuse a proxy without racing another wrap on the same port."""
+    if no_proxy:
+        return _ensure_proxy_unlocked(port, no_proxy, **kwargs)
+    with _proxy_start_lock(port):
+        # Re-checking is part of the lock boundary: a concurrent wrapper may
+        # have finished startup while this caller was waiting for the lock.
+        return _ensure_proxy_unlocked(port, no_proxy, **kwargs)
+
+
 def _client_marker_path(port: int) -> Path:
     """Path to this process's wrap-client marker for ``port``."""
     from headroom import paths as _paths
@@ -4463,6 +4761,8 @@ def claude(
 
     proxy_holder: list[subprocess.Popen | None] = [None]
     _saved_base_url: list[str | None] = [None]  # previous settings.json value for restore
+    _tool_search_not_written = object()
+    _saved_tool_search: list[object | str | None] = [_tool_search_not_written]
     _settings_foundry: list[bool] = [False]
     port_holder: list[int] = [port]
     _settings_vertex: list[bool] = [False]
@@ -4471,6 +4771,12 @@ def claude(
     # early proxy-start failure would make the finally raise UnboundLocalError,
     # masking the real error and skipping cleanup(). Mirrors the holders above.
     _wrap_settings_path = Path.cwd() / ".claude" / "settings.local.json"
+    _raise_on_claude_auth_conflict(
+        user_settings_path=claude_user_settings_path(),
+        project_settings_path=Path.cwd() / ".claude" / "settings.json",
+        project_local_settings_path=_wrap_settings_path,
+        environ=dict(os.environ),
+    )
     cleanup = _make_cleanup(proxy_holder, port_holder)
     signal.signal(signal.SIGINT, _ignore_child_sigint)
     signal.signal(signal.SIGTERM, cleanup)
@@ -4694,6 +5000,11 @@ def claude(
         # Issue #746: keep Claude Code's on-demand tool loading on through the
         # proxy so tool schemas are not eagerly materialized into local context.
         _tool_search_value = _configure_tool_search_env(env, tool_search)
+        _resolved_tool_search_value = env.get(_TOOL_SEARCH_ENV, "")
+        _saved_tool_search[0] = _write_claude_wrap_tool_search(
+            _resolved_tool_search_value,
+            settings_path=_wrap_settings_path,
+        )
         if _tool_search_value is not None:
             # Describe what the written value actually does: --tool-search
             # false/0/no/off turns deferral OFF, and the banner must say so
@@ -4717,10 +5028,18 @@ def claude(
         # force it via ANTHROPIC_MODEL on the launched process.
         if context_1m:
             env[_ANTHROPIC_MODEL_ENV] = _resolve_1m_model(env.get(_ANTHROPIC_MODEL_ENV))
-            click.echo(
-                f"  {_ANTHROPIC_MODEL_ENV}={env[_ANTHROPIC_MODEL_ENV]} "
-                "(1M context window; issue #1158)"
-            )
+            # An explicit pass-through --model outranks ANTHROPIC_MODEL in Claude
+            # Code, so add the suffix there too or the env var is silently
+            # shadowed and the window stays 200k (#2915). Report what will
+            # actually take effect rather than the shadowed env value.
+            claude_args, _model_flag_1m = _apply_1m_to_claude_args(claude_args)
+            if _model_flag_1m is not None:
+                click.echo(f"  --model {_model_flag_1m} (1M context window; issue #1158)")
+            else:
+                click.echo(
+                    f"  {_ANTHROPIC_MODEL_ENV}={env[_ANTHROPIC_MODEL_ENV]} "
+                    "(1M context window; issue #1158)"
+                )
 
         result = subprocess.run([claude_bin, *claude_args], env=env)
         raise SystemExit(result.returncode)
@@ -4731,6 +5050,11 @@ def claude(
         click.echo(f"  Error: {e}")
         raise SystemExit(1) from e
     finally:
+        if _saved_tool_search[0] is not _tool_search_not_written:
+            _restore_claude_wrap_tool_search(
+                cast(str | None, _saved_tool_search[0]),
+                settings_path=_wrap_settings_path,
+            )
         _restore_claude_wrap_base_url(
             _saved_base_url[0],
             foundry_mode=_settings_foundry[0],
@@ -5044,8 +5368,11 @@ def copilot(
                 "automatic model selection."
             )
 
+        env_wire_api = env.get("COPILOT_PROVIDER_WIRE_API")
         effective_wire_api = wire_api or (
-            _copilot_default_wire_api_for_model(selected_model) if subscription else "completions"
+            env_wire_api
+            if env_wire_api in {"completions", "responses"}
+            else _copilot_default_wire_api_for_model(selected_model)
         )
         env["COPILOT_PROVIDER_TYPE"] = "openai"
         # Per-project savings: the Copilot CLI cannot send custom headers, so
@@ -5184,8 +5511,8 @@ def vscode_copilot(
 ) -> None:
     """Run Headroom for GitHub Copilot inside Visual Studio Code.
 
-    Transparently overrides Copilot's proxy endpoint, preserving the model
-    selected in VS Code. It does not edit Codex settings.
+    Transparently overrides Copilot's proxy and CAPI endpoints, preserving the
+    model selected in VS Code. It does not edit Codex settings.
     """
     resolution = _require_copilot_subscription_resolution()
     target_settings = settings_file or vscode_settings_path()
@@ -5205,6 +5532,9 @@ def vscode_copilot(
         click.echo(
             f'  "github.copilot.advanced.debug.overrideProxyUrl": "{vscode_proxy_url(actual_port, _project_name_from_cwd())}",'
         )
+        click.echo(
+            f'  "github.copilot.advanced.debug.overrideCapiUrl": "{vscode_proxy_url(actual_port, _project_name_from_cwd())}",'
+        )
         click.echo('  "github.copilot.advanced.debug.overrideAuthType": "token"')
 
     _run_proxy_only_watcher(
@@ -5469,6 +5799,9 @@ def _run_codex_wrap(
     codex_args: tuple,
 ) -> None:
     """Execute the Codex wrap flow against the durable Codex home."""
+    if not no_proxy:
+        ensure_proxy_dependencies()
+
     if prepare_only:
         _prepare_codex_wrap_state(
             port=port,
@@ -6936,6 +7269,20 @@ def opencode(
             )
         subscription_resolution = _require_copilot_subscription_resolution()
 
+    # Verify the opencode binary exists BEFORE mutating any config. Otherwise a
+    # missing binary leaves headroom MCP/Serena/memory entries in the user's
+    # opencode config and an injected AGENTS.md, then errors with no cleanup --
+    # the config-before-verify anti-pattern (#1614). Siblings (claude, codex,
+    # goose, omp) already check first. `--prepare-only` intentionally writes
+    # config without launching, so it is exempt.
+    opencode_bin: str | None = None
+    if not prepare_only:
+        opencode_bin = shutil.which("opencode")
+        if not opencode_bin:
+            click.echo("Error: 'opencode' not found in PATH.")
+            click.echo("Install OpenCode: https://opencode.ai")
+            raise SystemExit(1)
+
     # Snapshot OpenCode config.json BEFORE any wrap-time mutation so
     # `headroom unwrap opencode` can restore the user's pre-wrap state.
     _opencode_config_file, _opencode_backup_file = opencode_config_paths()
@@ -6976,11 +7323,9 @@ def opencode(
         inject_opencode_provider_config(port)
         return
 
-    opencode_bin = shutil.which("opencode")
-    if not opencode_bin:
-        click.echo("Error: 'opencode' not found in PATH.")
-        click.echo("Install OpenCode: https://opencode.ai")
-        raise SystemExit(1)
+    # Past the prepare-only return the launch path always ran the binary check
+    # above, so opencode_bin is resolved.
+    assert opencode_bin is not None
 
     # Register our proxy client marker BEFORE _ensure_proxy so that another
     # wrapper's cleanup sees us as an active client and doesn't terminate a
diff --git a/headroom/config.py b/headroom/config.py
index 2bc9f4a8a..01f94182c 100644
--- a/headroom/config.py
+++ b/headroom/config.py
@@ -11,6 +11,7 @@ from enum import Enum
 from typing import Any, Literal
 
 from headroom.models.config import ML_MODEL_DEFAULTS
+from headroom.rollout import RolloutSnapshot, resolve_rollout
 
 
 class HeadroomMode(str, Enum):
@@ -672,9 +673,14 @@ class HeadroomConfig:
     content_router_enabled: InitVar[bool | None] = None
 
     # Tool-result interceptors (ast-grep Read outline, etc.). Opt-in for now.
-    # Env var HEADROOM_INTERCEPT_ENABLED=1 also enables (for CLI `--intercept-tool-results`).
+    # The legacy env alias and this typed request still obey the canary rollout gate.
     intercept_tool_results: bool = False
 
+    # Immutable runtime rollout state. ``None`` is resolved once here so every
+    # pipeline built from this config observes the same decisions even if the
+    # process environment later changes.
+    rollout: RolloutSnapshot | None = None
+
     # Debugging - opt-in diff artifact generation
     generate_diff_artifact: bool = False  # Enable to get detailed transform diffs
 
@@ -682,6 +688,11 @@ class HeadroomConfig:
     pipeline_extensions: list[Any] = field(default_factory=list)
     discover_pipeline_extensions: bool = True
 
+    def __post_init__(self, content_router_enabled: bool | None = None) -> None:
+        if self.rollout is None:
+            requested = ("tool_result_interceptors",) if self.intercept_tool_results else ()
+            self.rollout = resolve_rollout(requested=requested)
+
     def get_context_limit(self, model: str) -> int | None:
         """
         Get context limit for a model from user overrides.
diff --git a/headroom/context_tool_cleanup.py b/headroom/context_tool_cleanup.py
index d6860d6ff..6dbeb2f14 100644
--- a/headroom/context_tool_cleanup.py
+++ b/headroom/context_tool_cleanup.py
@@ -10,26 +10,87 @@ Deleting the code is not enough: everything above is *durable state on the
 user's disk*. Left alone, the Claude hooks keep rewriting every Bash command
 through binaries Headroom no longer manages, and the injected guidance keeps
 telling agents to use tools that may not resolve. So ``headroom wrap`` /
-``headroom unwrap`` call :func:`purge_context_tool_artifacts` once per run to
-remove what earlier versions installed.
+``headroom unwrap`` call :func:`purge_context_tool_artifacts` on every run to
+remove what earlier versions installed — machine-global artifacts (hooks,
+binaries, Claude Code's MCP registration) are removed once per workspace and
+then stamped done (see the stamp below), while project- and config-directory-
+scoped guidance (``CODEX_HOME`` / ``OPENCODE_HOME`` hint files, Continue's
+config) is inspected on every launch, since a later launch can sit in a
+different project or point at a different ``CODEX_HOME`` / ``OPENCODE_HOME``.
 
 Everything here is idempotent, best-effort and deliberately conservative:
 
 * only files Headroom installed (or caused a context tool to install) are
-  deleted;
+  deleted. An MCP entry's ``command`` or a hook script's body counts as
+  Headroom's only when it names a path inside :func:`paths.bin_dir`
+  (:func:`_references_managed_bin` — which is where the matching rules and
+  the reasons behind them live);
+* a hook entry is Headroom's when it names such a path directly, or — the
+  common case, since a hook command names a script rather than the binary —
+  when it names one of the ``~/.claude/hooks`` scripts already classified as
+  Headroom's, whose verdict it inherits
+  (:func:`_references_context_tool`, :func:`_names_a_managed_script`). A
+  Cursor ``hooks.json`` entry naming a script under ``~/.cursor`` cannot
+  inherit a verdict this way, since the map covers ``~/.claude/hooks`` only;
+  it is still caught when its ``command`` names the managed directory;
+* ``.rtk-hook.sha256`` is never read for its own provenance (it holds a hex
+  digest, not a path) and instead inherits ``rtk-rewrite.sh``'s
+  classification; a ``<name>.lean-ctx.bak`` backup inherits ``<name>``'s
+  (:func:`_classify_hook_scripts`);
+* a hook script that exists but cannot be read is classified unknown —
+  deleted by nothing, and named in the report so the user can remove it by
+  hand;
 * ``~/.local/bin/{rtk,lean-ctx}`` is unlinked only when it is a symlink into
   Headroom's own bin directory — a user's own build is never touched;
 * a JSON config that does not parse is reported and **skipped**, never
   overwritten (a hand-edited typo must not cost the user their settings);
 * the tools' own backups of *config* files (``~/.claude.json.lean-ctx.bak`` and
   friends) are left in place — they hold the user's real settings history. Only
-  backups of the hook scripts being deleted are cleaned up.
+  backups of the hook scripts proven to be Headroom's are cleaned up;
+* two cases cannot be decided at all, and are accepted as limits rather than
+  fixed:
+
+  * ``get_lean_ctx_path`` used to check ``PATH`` before Headroom's own bin
+    directory, so on a machine that already had ``lean-ctx`` on ``PATH``,
+    the tool that ran was the user's own, and the config it wrote looks
+    exactly like config the user wrote by hand. That leftover survives the
+    purge — it still points at a binary that exists, so nothing dangles;
+  * an rtk hook written *after* #1698 execs a bare ``rtk`` and never mentions
+    :func:`paths.bin_dir`, so it reads exactly like a hook a user wrote by
+    hand, and ``rtk-rewrite.sh``, its ``.rtk-hook.sha256`` and its
+    ``settings.json`` entry all survive while step 3 removes the managed
+    binary — leaving a hook that silently no-ops (#487, #1698). Earlier
+    hooks are decidable: Headroom patched the absolute managed path into
+    them (``_patch_rtk_hook_absolute_path``, removed by #1698), so the
+    window this misses is rtk setups run between #1698 and the tools'
+    removal in #2677;
+* the marker-fenced guidance block is the one step with no provenance check
+  to make — ``<!-- headroom:rtk-instructions -->`` is Headroom's own fence,
+  and no third party writes it.
+
+Removing the retired integration's machine-global footprint — hook
+registrations, hook scripts, PATH symlinks, managed binaries and Claude
+Code's own MCP registration — is a one-time migration: the first completed
+run of that half stamps ``.context-tools-purged`` beside the managed bin
+directory, and every later run skips that half outright. Without the stamp
+this would keep rewriting the same machine-wide files on every ``wrap``
+invocation forever, and a user who installs one of these tools *after* the
+migration would have Headroom auditing files at each launch for a leftover
+that cannot exist there.
+
+Project- and config-directory-scoped state is not covered by that stamp: a
+later invocation can sit in a different project, or point ``CODEX_HOME`` /
+``OPENCODE_HOME`` somewhere the stamped run never inspected, and whatever
+guidance an earlier Headroom left behind there is still worth removing — so
+those steps run on every invocation instead (:func:`_purge_invocation_scoped`).
 """
 
 from __future__ import annotations
 
 import json
 import os
+import posixpath
+import re
 from pathlib import Path
 from typing import Any
 
@@ -69,52 +130,138 @@ _HOOK_SCRIPTS = (
     "lean-ctx-redirect-native",
 )
 
+# rtk's integrity digest never names a path (see ``_classify_hook_scripts``)
+# and rtk-rewrite.sh is the script it authenticates.
+_RTK_DIGEST_NAME = ".rtk-hook.sha256"
+_RTK_SCRIPT_NAME = "rtk-rewrite.sh"
+
 # MCP server entries the tools registered, and the config files holding them.
 # lean-ctx registers itself as an MCP server during ``lean-ctx init``; rtk never
 # did, but it is matched too so a stale hand-added entry is cleaned up as well.
 _MCP_SERVER_NAMES = ("lean-ctx", "lean_ctx", "rtk")
 
+# Report-line prefixes meaning "this one is not settled" — a config that would
+# not parse, a script that would not read, a file that would not unlink. Such a
+# run leaves a leftover behind, so it must not be stamped as the completed
+# migration. Emitted by _purge_hook_config, _purge_mcp_entries,
+# _purge_fenced_block, _purge_continue_system_messages and _remove_files.
+_DEFERRED_PREFIXES = ("skipped ", "could not remove ")
+
 
 def purge_context_tool_artifacts() -> list[str]:
     """Remove every rtk / lean-ctx artifact an earlier Headroom version installed.
 
     Returns human-readable descriptions of what was removed — plus a line for
-    any config that had to be skipped because the user must fix it by hand. An
-    empty list means there was nothing to do, which is the steady state after
-    the first run.
+    any config that had to be skipped because the user must fix it by hand.
+    Machine-global cleanup (hooks, binaries, Claude Code's MCP registration)
+    runs once and is then skipped via the stamp below; project- and config-
+    directory-scoped cleanup (hint files, ``CODEX_HOME`` / ``OPENCODE_HOME``,
+    Continue's config) runs on every call, so a later call in a different
+    project or a repointed ``CODEX_HOME`` / ``OPENCODE_HOME`` can still report
+    something even after the global half is long since stamped done.
     """
+    marker = _purge_marker()
     home = Path.home()
     project = Path.cwd()
     report: list[str] = []
 
-    # 1. Hook registrations (Claude Code's settings.json, Cursor's hooks.json).
-    for config in (home / ".claude" / "settings.json", home / ".cursor" / "hooks.json"):
-        report += _purge_hook_config(config)
+    if not marker.exists():
+        # Classify every hook script's provenance once, up front: both step 1
+        # (is a settings.json entry pointing at *our* script?) and step 2 (is
+        # the script itself ours?) need the same answer, and each file is
+        # read once.
+        hooks_dir = home / ".claude" / "hooks"
+        hook_classification = _classify_hook_scripts(hooks_dir)
 
-    # 2. The generated hook scripts, their integrity digests and stale backups.
-    hooks_dir = home / ".claude" / "hooks"
-    report += _remove_files(
-        *(hooks_dir / name for name in _HOOK_SCRIPTS),
-        *(hooks_dir / f"{name}.lean-ctx.bak" for name in _HOOK_SCRIPTS),
-    )
+        # 1. Hook registrations (Claude Code's settings.json, Cursor's hooks.json).
+        for config in (home / ".claude" / "settings.json", home / ".cursor" / "hooks.json"):
+            report += _purge_hook_config(config, hooks_dir, hook_classification)
 
-    # 3. The PATH symlinks, then the managed binaries they pointed at.
-    for name in ("rtk", "lean-ctx"):
-        report += _remove_managed_path_link(home / ".local" / "bin" / name)
-    report += _remove_files(*(paths.bin_dir() / name for name in _BINARY_NAMES))
+        # 2. The generated hook scripts, their integrity digests and stale
+        # backups — only the ones proven to reference Headroom's managed bin
+        # directory.
+        managed_names = [name for name in _HOOK_SCRIPTS if hook_classification.get(name)]
+        report += _remove_files(
+            *(hooks_dir / name for name in managed_names),
+            *(hooks_dir / f"{name}.lean-ctx.bak" for name in managed_names),
+        )
+        for name in _HOOK_SCRIPTS:
+            if hook_classification.get(name, False) is not None:
+                continue
+            if name == _RTK_DIGEST_NAME:
+                report.append(
+                    f"skipped {hooks_dir / name} (inherits {_RTK_SCRIPT_NAME}'s unreadable verdict)"
+                    " — remove any stale hook script by hand"
+                )
+            else:
+                report.append(
+                    f"skipped {hooks_dir / name} (could not read to verify it was Headroom's)"
+                    " — remove any stale hook script by hand"
+                )
 
-    # 4. MCP server registrations (lean-ctx registers itself during init).
-    report += _purge_mcp_entries(home / ".claude.json", "mcpServers")
+        # 3. The PATH symlinks, then the managed binaries they pointed at.
+        for name in ("rtk", "lean-ctx"):
+            report += _remove_managed_path_link(home / ".local" / "bin" / name)
+        report += _remove_files(*(paths.bin_dir() / name for name in _BINARY_NAMES))
+
+        # 4. Claude Code's own MCP server registration (lean-ctx registers
+        # itself during init). OpenCode's is invocation-scoped — see below.
+        report += _purge_mcp_entries(home / ".claude.json", "mcpServers")
+
+        # Only a global half that settled everything is the completed
+        # migration. One that could not read a script or parse a config left
+        # a leftover behind, and the user needs both the reminder on the next
+        # launch and the cleanup once the permissions or the typo are fixed.
+        # A deferral in the invocation-scoped half below must not withhold
+        # this stamp — that half re-runs every time regardless, so nothing is
+        # lost by stamping the global half done now.
+        if not any(line.startswith(_DEFERRED_PREFIXES) for line in report):
+            try:
+                # Cleanup must not become the first mutation on a pristine
+                # machine. In particular, ``wrap <missing-tool>`` validates
+                # the binary after the wrap-group migration hook; creating
+                # ``~/.headroom`` merely to stamp an empty scan violates that
+                # command's no-side-effects-on-failure contract. Established
+                # Headroom installs already have the state directory and get
+                # the one-time fast path; clean machines cheaply rescan until
+                # some real Headroom state exists.
+                if marker.parent.is_dir():
+                    marker.touch()
+            except OSError:
+                pass  # Unwritable workspace: the purge simply runs again next time.
+
+    report += _purge_invocation_scoped(home, project)
+    return report
+
+
+def _purge_invocation_scoped(home: Path, project: Path) -> list[str]:
+    """Steps the one-time stamp must never withhold.
+
+    ``OPENCODE_HOME``'s config, the hint files in ``project`` /
+    ``CODEX_HOME`` / ``OPENCODE_HOME``, and Continue's config are all a
+    function of *this* invocation's cwd and environment, not of the machine —
+    a later run can sit in a different project or point ``CODEX_HOME`` /
+    ``OPENCODE_HOME`` somewhere the global-half stamp never inspected. Each
+    step is cheap and side-effect-free when nothing matches, so re-running
+    them on every invocation costs a handful of reads in the steady state.
+    """
+    report: list[str] = []
     report += _purge_mcp_entries(_opencode_home(home) / "opencode.json", "mcp")
-
-    # 5. Marker-fenced guidance in every hint file the wrap harnesses wrote to.
     for hint_file in _instruction_files(home, project):
         report += _purge_fenced_block(hint_file)
     report += _purge_continue_system_messages(project / ".continue" / "config.json")
-
     return report
 
 
+def _purge_marker() -> Path:
+    """Path of the "already migrated" stamp.
+
+    Derived from :func:`paths.bin_dir` rather than ``workspace_dir`` so it
+    cannot escape a temporary tree through ``HEADROOM_WORKSPACE_DIR``.
+    """
+    return paths.bin_dir().parent / ".context-tools-purged"
+
+
 def _instruction_files(home: Path, project: Path) -> list[Path]:
     """Hint files the wrap subcommands injected the context-tool block into.
 
@@ -151,15 +298,194 @@ def _opencode_home(home: Path) -> Path:
 # --- hook registrations -------------------------------------------------------
 
 
-def _references_context_tool(entry: Any) -> bool:
-    """Whether a hook entry's command is one a retired context tool registered."""
+# Characters that can never be part of a path: a match ending right before
+# one of these (or at end-of-string) sits at a real word boundary. Quotes,
+# `=`/`:` (`export PATH="<dir>:$PATH"`, `BIN=<dir>/x`), `;`/`,`/`|` (command
+# joiners) and `()` (subshells) all end a path the same way whitespace does.
+_PATH_BOUNDARY_CHARS = frozenset("\"'=:;,()|")
+
+# Splits a command into path-shaped tokens on whitespace plus the same
+# boundary punctuation above — used by _names_a_managed_script, which (unlike
+# _references_managed_bin's needle-anchored scan) tokenizes the whole command.
+_PATH_TOKEN_SPLIT = re.compile(r"[\s" + re.escape("".join(_PATH_BOUNDARY_CHARS)) + r"]+")
+
+
+def _norm_path_text(value: str) -> str:
+    """Case-fold ``value`` and give it one separator, so paths compare as text."""
+    return os.path.normcase(value).replace("\\", "/")
+
+
+def _references_managed_bin(text: str) -> bool:
+    """Whether ``text`` names a path inside Headroom's managed bin directory.
+
+    A hook command or script body is free text we don't control, so this
+    scans ``text`` for raw occurrences of the managed directory — the
+    unresolved and resolved bin directory, and its ``~``-relative form
+    (home-relative, since a script may reference it unexpanded) — matched
+    against the text as given and as ``expanduser``'d, case-folded, with both
+    path separators. Deliberately *not* tokenized on whitespace first: a
+    quoted or ``$HOME``-derived path can itself contain a space, and slicing
+    the text into words before searching would sever it.
+
+    A hit is only a real reference at a path boundary on *both* ends. The
+    character immediately before the match, if any, must be whitespace or a
+    :data:`_PATH_BOUNDARY_CHARS` character, or the match is just the tail of
+    some longer, unrelated path segment (e.g. ``/prefix<bin_dir>/lean-ctx``)
+    and is rejected. The match must then be immediately followed by
+    end-of-string or a :data:`_PATH_BOUNDARY_CHARS` character (an exact
+    reference, e.g. a bare ``PATH=<dir>`` export), or by ``/`` — in which
+    case the run of characters up to the next boundary is lexically
+    normalized (``.``/``..`` collapsed) and re-compared, so neither a sibling
+    directory like ``bin-backup``/``binfoo`` nor a ``bin/../evil`` traversal
+    can borrow the managed prefix.
+    # ponytail: boundary-aware substring scan, not a shell parse — upgrade to
+    # shlex if a command ever embeds a managed path it does not execute.
+    """
+    try:
+        bin_dir = paths.bin_dir()
+        resolved_bin_dir = bin_dir.resolve()
+    except OSError:
+        return False
+
+    needles = {_norm_path_text(str(bin_dir)), _norm_path_text(str(resolved_bin_dir))}
+    home = Path.home()
+    for base in (bin_dir, resolved_bin_dir):
+        try:
+            needles.add(_norm_path_text(f"~/{base.relative_to(home).as_posix()}"))
+        except ValueError:
+            pass
+
+    for haystack in (text, os.path.expanduser(text)):
+        normalized_haystack = _norm_path_text(haystack)
+        if any(_names_managed_dir(normalized_haystack, needle) for needle in needles):
+            return True
+    return False
+
+
+def _names_managed_dir(haystack: str, needle: str) -> bool:
+    """Whether a normalized ``haystack`` names ``needle`` at a path boundary
+    on both ends: the character right before the match, if any, must be
+    whitespace or a :data:`_PATH_BOUNDARY_CHARS` character too, or a
+    user-owned path that merely has the managed directory as a substring
+    (e.g. ``/prefix<bin_dir>/lean-ctx``) would be misread as naming it.
+    """
+    search_from = 0
+    while True:
+        index = haystack.find(needle, search_from)
+        if index < 0:
+            return False
+        end = index + len(needle)
+        search_from = index + 1  # keep scanning; occurrences may overlap
+        if index > 0 and not (
+            haystack[index - 1].isspace() or haystack[index - 1] in _PATH_BOUNDARY_CHARS
+        ):
+            continue
+        following = haystack[end : end + 1]
+        if not following or following.isspace() or following in _PATH_BOUNDARY_CHARS:
+            return True
+        if following != "/":
+            continue
+        tail_end = end
+        while tail_end < len(haystack) and not (
+            haystack[tail_end].isspace() or haystack[tail_end] in _PATH_BOUNDARY_CHARS
+        ):
+            tail_end += 1
+        candidate = posixpath.normpath(haystack[index:tail_end])
+        if candidate == needle or candidate.startswith(needle + "/"):
+            return True
+
+
+def _classify_hook_scripts(hooks_dir: Path) -> dict[str, bool | None]:
+    """Classify each existing ``_HOOK_SCRIPTS`` file by whether it is Headroom's.
+
+    ``True`` — the file exists and its body references the managed bin
+    directory. ``False`` — it exists and does not. ``None`` — it exists but
+    could not be read, so its provenance is unprovable. A basename with no
+    file on disk is simply absent from the map. Each file is read at most once.
+
+    ``.rtk-hook.sha256`` holds a hex digest that can never reference a path,
+    so it is never read; it inherits ``rtk-rewrite.sh``'s classification.
+    """
+    classification: dict[str, bool | None] = {}
+    for name in _HOOK_SCRIPTS:
+        if name == _RTK_DIGEST_NAME:
+            continue
+        path = hooks_dir / name
+        if not path.is_file():
+            continue
+        try:
+            body = fsutil.read_text(path)
+        except OSError:
+            classification[name] = None
+            continue
+        classification[name] = _references_managed_bin(body)
+
+    if (hooks_dir / _RTK_DIGEST_NAME).is_file():
+        classification[_RTK_DIGEST_NAME] = classification.get(_RTK_SCRIPT_NAME, False)
+
+    return classification
+
+
+def _references_context_tool(
+    entry: Any, hooks_dir: Path, hook_classification: dict[str, bool | None]
+) -> bool:
+    """Whether a hook entry is one a retired context tool registered.
+
+    A command-marker hit alone is not enough — a user could author a script
+    with a matching name. It must also either name the managed bin directory
+    directly, or name — as a path resolving to that exact file, not merely
+    sharing its basename, so a same-named script of the user's own in a
+    different directory is never caught — a hook script in ``hooks_dir`` the
+    classification map marks ``True`` (see :func:`_names_a_managed_script`).
+    """
     if not isinstance(entry, dict):
         return False
-    command = str(entry.get("command", "")).lower()
-    return any(marker in command for marker in _HOOK_COMMAND_MARKERS)
+    command = str(entry.get("command", ""))
+    if not any(marker in command.lower() for marker in _HOOK_COMMAND_MARKERS):
+        return False
+    if _references_managed_bin(command):
+        return True
+    return _names_a_managed_script(command, hooks_dir, hook_classification)
 
 
-def _prune_hooks(hooks: Any) -> tuple[Any, bool]:
+def _names_a_managed_script(
+    command: str, hooks_dir: Path, hook_classification: dict[str, bool | None]
+) -> bool:
+    """Whether ``command`` names, by absolute path, a hook script the map marks ``True``.
+
+    A real command is rarely the bare script path: ``bash <script>`` wraps
+    it, a shell often quotes it, and it may carry a redundant ``./`` segment.
+    ``command`` is split into path-shaped tokens on the same boundary
+    punctuation :data:`_PATH_BOUNDARY_CHARS` (and whitespace) mark as *not*
+    part of a path, each token is lexically normalized, and compared against
+    the script's absolute path only.
+
+    Deliberately not resolved against ``~``/:func:`Path.home` or against the
+    process's working directory: a *relative* hook command in
+    ``~/.claude/settings.json`` is resolved by the harness against the
+    project's cwd, not against home — this module never writes or inspects a
+    project-relative path, so treating one as if it named a home-relative
+    script would delete a project-local hook this purge has no business
+    touching. A relative token, and a ``$VAR``-style unexpanded reference
+    (e.g. ``$HOME/...``), are both simply not recognised — unprovable, so
+    kept, per the guard's own rule.
+    """
+    tokens = {
+        token
+        for haystack in (command, os.path.expanduser(command))
+        for token in _PATH_TOKEN_SPLIT.split(haystack)
+        if token
+    }
+    normalized_tokens = {posixpath.normpath(_norm_path_text(token)) for token in tokens}
+    return any(
+        verdict is True and _norm_path_text(str(hooks_dir / name)) in normalized_tokens
+        for name, verdict in hook_classification.items()
+    )
+
+
+def _prune_hooks(
+    hooks: Any, hooks_dir: Path, hook_classification: dict[str, bool | None]
+) -> tuple[Any, bool]:
     """Drop retired-tool entries from a ``hooks`` mapping; return ``(pruned, changed)``.
 
     Handles both shapes Headroom's installers produced: Claude Code nests
@@ -180,13 +506,17 @@ def _prune_hooks(hooks: Any) -> tuple[Any, bool]:
         retained: list[Any] = []
         for entry in entries:
             # Cursor shape: the command sits on the entry itself.
-            if _references_context_tool(entry):
+            if _references_context_tool(entry, hooks_dir, hook_classification):
                 changed = True
                 continue
             # Claude shape: a matcher entry holding a list of hooks.
             inner = entry.get("hooks") if isinstance(entry, dict) else None
             if isinstance(inner, list):
-                kept_inner = [item for item in inner if not _references_context_tool(item)]
+                kept_inner = [
+                    item
+                    for item in inner
+                    if not _references_context_tool(item, hooks_dir, hook_classification)
+                ]
                 if len(kept_inner) != len(inner):
                     changed = True
                     if not kept_inner:
@@ -206,7 +536,9 @@ def _prune_hooks(hooks: Any) -> tuple[Any, bool]:
     return pruned, changed
 
 
-def _purge_hook_config(path: Path) -> list[str]:
+def _purge_hook_config(
+    path: Path, hooks_dir: Path, hook_classification: dict[str, bool | None]
+) -> list[str]:
     """Remove retired-tool hook registrations from a JSON hook config."""
     if not path.is_file():
         return []
@@ -217,7 +549,7 @@ def _purge_hook_config(path: Path) -> list[str]:
     if not isinstance(payload, dict):
         return [f"skipped {path} (not a JSON object) — remove any stale hook by hand"]
 
-    hooks, changed = _prune_hooks(payload.get("hooks"))
+    hooks, changed = _prune_hooks(payload.get("hooks"), hooks_dir, hook_classification)
     if not changed:
         return []
     if hooks:
@@ -236,8 +568,10 @@ def _purge_mcp_entries(path: Path, container_key: str) -> list[str]:
 
     ``lean-ctx init`` registers lean-ctx as an MCP server in the harness's own
     config — Claude Code keeps them under ``mcpServers``, OpenCode under ``mcp``.
-    Only the exactly-named entries are removed; every other server, and every
-    unrelated top-level key, is preserved byte-for-byte.
+    A name match alone is not enough — a user can register their own server
+    under the same name — so an entry is removed only when its ``command``
+    also names Headroom's managed bin directory. Every other server, and
+    every unrelated top-level key, is preserved byte-for-byte.
     """
     if not path.is_file():
         return []
@@ -251,7 +585,13 @@ def _purge_mcp_entries(path: Path, container_key: str) -> list[str]:
     servers = payload.get(container_key)
     if not isinstance(servers, dict):
         return []
-    removed = [name for name in _MCP_SERVER_NAMES if name in servers]
+    removed = [
+        name
+        for name in _MCP_SERVER_NAMES
+        if isinstance(servers.get(name), dict)
+        and isinstance(servers[name].get("command"), str)
+        and _references_managed_bin(servers[name]["command"])
+    ]
     if not removed:
         return []
     for name in removed:
diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.html
index d957c730c..a62091a4f 100644
--- a/headroom/dashboard/templates/dashboard.html
+++ b/headroom/dashboard/templates/dashboard.html
@@ -264,26 +264,29 @@
                         <template x-if="!stats.tokens?.output_reduction?.available">
                             <div class="mt-1 text-xs text-gray-500 leading-relaxed">
                                 <span class="text-2xl font-light tabular-nums text-gray-600">—</span>
-                                <div class="mt-1">Enable the output shaper (HEADROOM_OUTPUT_SHAPER=1) and run
+                                <div class="mt-1">Enable the beta output shaper (HEADROOM_ROLLOUT_CHANNEL=beta HEADROOM_OUTPUT_SHAPER=1) and run
                                     <code class="text-gray-400">headroom learn --verbosity --apply</code> to start measuring.</div>
                             </div>
                         </template>
                     </div>
 
-                    <!-- Tool-schema deferral: a COMPONENT of the Tokens Saved headline above
-                         (stats.tokens.saved is all-layers), not a rival metric. Labelled as
-                         such so a tool-heavy session doesn't read as "0 saved + some other
-                         number". Only rendered when there's a saving to show. -->
-                    <template x-if="(stats.savings?.by_layer?.tool_search?.tokens || 0) > 0">
+                    <!-- Dynamic attribution for any named savings source. These
+                         rows explain the headline; they are not added to it. -->
+                    <template x-for="row in (stats.savings?.by_source || [])" :key="row.source + ':' + row.realized">
                         <div class="bg-surface rounded-lg p-4 border border-border">
-                            <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Tokens Saved · Tool Schemas</div>
-                            <div class="flex items-baseline gap-2">
-                                <span class="text-3xl font-light tabular-nums text-emerald-400" x-text="formatNumber(stats.savings?.by_layer?.tool_search?.tokens || 0)"></span>
+                            <div class="text-xs text-gray-500 uppercase tracking-wide mb-1"
+                                 x-text="'Savings · ' + row.source.replaceAll('_', ' ')"></div>
+                            <div class="flex items-baseline gap-2" x-show="(row.tokens || 0) > 0">
+                                <span class="text-3xl font-light tabular-nums text-emerald-400" x-text="formatNumber(row.tokens || 0)"></span>
                                 <span class="text-sm text-gray-400">tokens</span>
                             </div>
-                            <div class="mt-1 text-xs text-gray-600 leading-relaxed"
-                                 x-text="formatNumber(stats.savings?.by_layer?.tool_search?.requests || 0) + ' calls · tool schemas deferred (recent window)'">
+                            <div class="flex items-baseline gap-2" x-show="(row.usd || 0) !== 0">
+                                <span class="text-2xl font-light tabular-nums"
+                                      :class="row.usd >= 0 ? 'text-emerald-400' : 'text-red-400'"
+                                      x-text="(row.usd >= 0 ? '$' : '-$') + formatCurrency(Math.abs(row.usd || 0))"></span>
                             </div>
+                            <div class="mt-1 text-xs text-gray-600 leading-relaxed"
+                                 x-text="formatNumber(row.events || 0) + ' calls · ' + (row.realized ? 'realized' : 'projected')"></div>
                         </div>
                     </template>
                 </div>
@@ -941,6 +944,17 @@
                                                         </div>
                                                     </div>
                                                 </template>
+                                                <template x-if="(req.savings_breakdown || []).length > 0">
+                                                    <div class="mt-3">
+                                                        <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Savings Attribution</div>
+                                                        <div class="flex flex-wrap gap-1">
+                                                            <template x-for="item in req.savings_breakdown" :key="item.source + ':' + item.tokens + ':' + item.usd">
+                                                                <span class="px-2 py-0.5 bg-border rounded text-xs font-mono"
+                                                                      x-text="item.source + (item.tokens ? ' · ' + formatNumber(item.tokens) + ' tok' : '') + (item.usd ? ' · $' + formatCurrency(item.usd) : '') + (item.realized ? '' : ' · projected')"></span>
+                                                            </template>
+                                                        </div>
+                                                    </div>
+                                                </template>
                                                 <!-- Waste Signals for this request -->
                                                 <template x-if="req.waste_signals && Object.keys(req.waste_signals).length > 0">
                                                     <div class="mt-3">
@@ -1832,7 +1846,7 @@
                 savingsHistory: [],
                 expandedRows: {},
                 pollInterval: null,
-                statsPollMs: 15000,
+                statsPollMs: 5000,
                 viewPollMs: 30000,
                 feedPollMs: 5000,
                 viewRefreshers: {
@@ -2152,7 +2166,9 @@
 
                 truncateModel(model) {
                     if (!model) return '-';
-                    return model.replace(/^(anthropic\.|openai\.|bedrock\/)/, '')
+                    return model.replace(/^(bedrock\/)/, '')
+                               .replace(/^(au\.|us\.|eu\.|apac\.|global\.)/, '')
+                               .replace(/^(anthropic\.|openai\.)/, '')
                                .replace(/-\d{8}$/, '')
                                .substring(0, 20);
                 },
diff --git a/headroom/image/compressor.py b/headroom/image/compressor.py
index 5dc7baa97..448d52be4 100644
--- a/headroom/image/compressor.py
+++ b/headroom/image/compressor.py
@@ -31,7 +31,10 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from .trained_router import TrainedRouter
 
-from .trained_router import Technique
+# Import the enum from the dependency-free module so importing the compressor
+# does not eagerly import trained_router (and thus torch/transformers) — that
+# eager import crashed on Python 3.13+ (#2513).
+from .image_types import Technique
 
 logger = logging.getLogger(__name__)
 
diff --git a/headroom/image/image_types.py b/headroom/image/image_types.py
new file mode 100644
index 000000000..572fcf7f3
--- /dev/null
+++ b/headroom/image/image_types.py
@@ -0,0 +1,45 @@
+"""Lightweight image-routing types shared across the image stack.
+
+Kept dependency-free (pure enum + dataclasses, no torch / transformers / onnx)
+so importing the image compressor or the ONNX router does not eagerly import
+the heavy ML stack via ``trained_router``. On Python 3.13+ that eager import
+crashed with ``AttributeError: module 'torch' has no attribute 'compiler'``
+because ``transformers`` touched ``torch.compiler`` before torch finished
+initializing inside the proxy process (#2513).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Technique(Enum):
+    """Image optimization techniques."""
+
+    TRANSCODE = "transcode"  # Convert to text description (99% savings)
+    CROP = "crop"  # Extract relevant region (50-90% savings)
+    PRESERVE = "preserve"  # Keep full quality (0% savings)
+    FULL_LOW = "full_low"  # Full image, lower quality (87% savings)
+
+
+@dataclass
+class ImageSignals:
+    """Signals extracted from image analysis."""
+
+    has_text: float
+    is_document: float
+    is_complex: float
+    has_small_details: float
+
+
+@dataclass
+class RouteDecision:
+    """Result of routing decision."""
+
+    technique: Technique
+    confidence: float
+    reason: str
+    image_signals: ImageSignals | None = None
+    query_prediction: str | None = None
+    query_confidence: float | None = None
diff --git a/headroom/image/onnx_router.py b/headroom/image/onnx_router.py
index 64ceeefa6..509303bac 100644
--- a/headroom/image/onnx_router.py
+++ b/headroom/image/onnx_router.py
@@ -19,7 +19,7 @@ from typing import Any
 
 import numpy as np
 
-from headroom.image.trained_router import ImageSignals, RouteDecision, Technique
+from headroom.image.image_types import ImageSignals, RouteDecision, Technique
 from headroom.onnx_runtime import create_cpu_session_options, hf_hub_download_local_first
 
 logger = logging.getLogger(__name__)
diff --git a/headroom/image/trained_router.py b/headroom/image/trained_router.py
index b53c30d19..dfa16ef70 100644
--- a/headroom/image/trained_router.py
+++ b/headroom/image/trained_router.py
@@ -12,8 +12,6 @@ from __future__ import annotations
 
 import gc
 import io
-from dataclasses import dataclass
-from enum import Enum
 from pathlib import Path
 from typing import Any
 
@@ -28,6 +26,11 @@ except ImportError:
 
 from headroom.models.config import ML_MODEL_DEFAULTS
 
+# Re-exported from the dependency-free module so existing
+# ``from .trained_router import Technique`` imports keep working without this
+# module (which imports torch/transformers) being needed just for the types.
+from .image_types import ImageSignals, RouteDecision, Technique
+
 
 def _extract_tensor(output: torch.Tensor | BaseModelOutputWithPooling) -> torch.Tensor:
     """Extract tensor from model output.
@@ -55,37 +58,6 @@ def _extract_tensor(output: torch.Tensor | BaseModelOutputWithPooling) -> torch.
     return output
 
 
-class Technique(Enum):
-    """Image optimization techniques."""
-
-    TRANSCODE = "transcode"  # Convert to text description (99% savings)
-    CROP = "crop"  # Extract relevant region (50-90% savings)
-    PRESERVE = "preserve"  # Keep full quality (0% savings)
-    FULL_LOW = "full_low"  # Full image, lower quality (87% savings)
-
-
-@dataclass
-class ImageSignals:
-    """Signals extracted from image analysis."""
-
-    has_text: float
-    is_document: float
-    is_complex: float
-    has_small_details: float
-
-
-@dataclass
-class RouteDecision:
-    """Result of routing decision."""
-
-    technique: Technique
-    confidence: float
-    reason: str
-    image_signals: ImageSignals | None = None
-    query_prediction: str | None = None
-    query_confidence: float | None = None
-
-
 class TrainedRouter:
     """Router using trained MiniLM classifier + SigLIP image analysis.
 
diff --git a/headroom/install/planner.py b/headroom/install/planner.py
index 79c11ed31..290cff063 100644
--- a/headroom/install/planner.py
+++ b/headroom/install/planner.py
@@ -3,18 +3,21 @@
 from __future__ import annotations
 
 import shutil
+import sys
 from collections.abc import Iterable
 
 import click
 
 from headroom import paths as _paths
 from headroom.providers.install_registry import build_install_target_envs
+from headroom.rollout import RolloutChannel
 
 from .models import (
     ConfigScope,
     DeploymentManifest,
     InstallPreset,
     ProviderSelectionMode,
+    RuntimeKind,
     SupervisorKind,
     ToolTarget,
 )
@@ -140,9 +143,19 @@ def build_manifest(
 
     normalized_profile = validate_profile_name(profile)
 
-    if preset == InstallPreset.PERSISTENT_SERVICE.value:
+    # A Windows service must implement the Service Control Manager protocol.
+    # The Python runner is an ordinary console process, so registering it with
+    # ``sc.exe create`` always fails at start with SCM error 1053.  Task
+    # Scheduler can run the same runner safely and already provides startup
+    # plus periodic health recovery, so make it the effective preset on
+    # Windows instead of creating a service that can never start (#2552).
+    effective_preset = preset
+    if sys.platform.startswith("win") and preset == InstallPreset.PERSISTENT_SERVICE.value:
+        effective_preset = InstallPreset.PERSISTENT_TASK.value
+
+    if effective_preset == InstallPreset.PERSISTENT_SERVICE.value:
         supervisor_kind = SupervisorKind.SERVICE.value
-    elif preset == InstallPreset.PERSISTENT_TASK.value:
+    elif effective_preset == InstallPreset.PERSISTENT_TASK.value:
         supervisor_kind = SupervisorKind.TASK.value
     else:
         supervisor_kind = SupervisorKind.NONE.value
@@ -168,6 +181,26 @@ def build_manifest(
     # defaults above (e.g. a custom HEADROOM_WORKSPACE_DIR).
     if extra_env:
         base_env.update(extra_env)
+    if intercept_tool_results:
+        configured_channel = base_env.get("HEADROOM_ROLLOUT_CHANNEL")
+        if configured_channel is None:
+            # The flag is an explicit canary opt-in. Persist the matching
+            # channel so the generated service can actually start.
+            base_env["HEADROOM_ROLLOUT_CHANNEL"] = RolloutChannel.CANARY.value
+        else:
+            channel = RolloutChannel.parse(configured_channel)
+            unsafe = base_env.get("HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES", "").lower() in {
+                "1",
+                "true",
+                "yes",
+                "on",
+                "enabled",
+            }
+            if not channel.allows(RolloutChannel.CANARY) and not unsafe:
+                raise click.ClickException(
+                    "--intercept-tool-results requires HEADROOM_ROLLOUT_CHANNEL=canary "
+                    "(or dev), unless the unsafe rollout override is explicitly enabled"
+                )
 
     proxy_args = [
         "--host",
@@ -181,7 +214,19 @@ def build_manifest(
     ]
     proxy_args.append("--telemetry" if telemetry_enabled else "--no-telemetry")
     if memory_enabled:
-        proxy_args.extend(["--memory", "--memory-db-path", str(_paths.memory_db_path())])
+        proxy_args.append("--memory")
+        # `_paths.memory_db_path()` resolves against the HOST home. A container
+        # runtime cannot use it: the container's HOME is /tmp/headroom-home and
+        # the host's ~/.headroom is bind-mounted there, so a host path like
+        # /home/<user>/.headroom/memory.db does not exist inside the container,
+        # SQLite fails to open the DB, /readyz stays 503, and the deployment
+        # times out and rolls back (#2803). Omit the flag for a container runtime:
+        # the proxy then resolves the DB under its own cwd (.headroom/memory.db),
+        # which is the container's workdir and therefore the bind mount, landing
+        # in the same host file the explicit path intended. On the host (python)
+        # runtime the resolved host path is correct, so keep passing it.
+        if runtime_kind != RuntimeKind.DOCKER.value:
+            proxy_args.extend(["--memory-db-path", str(_paths.memory_db_path())])
     if anyllm_provider:
         proxy_args.extend(["--anyllm-provider", anyllm_provider])
     if region:
@@ -200,7 +245,7 @@ def build_manifest(
     container_name = f"headroom-{normalized_profile}"
     return DeploymentManifest(
         profile=normalized_profile,
-        preset=preset,
+        preset=effective_preset,
         runtime_kind=runtime_kind,
         supervisor_kind=supervisor_kind,
         scope=scope,
diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py
index 0736e0a33..5288cdc74 100644
--- a/headroom/install/runtime.py
+++ b/headroom/install/runtime.py
@@ -56,6 +56,32 @@ def _is_windows() -> bool:
     return sys.platform.startswith("win")
 
 
+def _container_runtime_is_podman() -> bool:
+    """Best-effort: is the ``docker`` command actually Podman?
+
+    Rootless Podman maps the host user to container UID 0, so the
+    ``--user <host-uid>:<host-gid>`` flag that is correct for Docker instead
+    selects a subordinate UID that owns none of the bind-mounted host
+    directories, and every write into ``~/.headroom`` fails (#2804). Detect the
+    common ``docker -> podman`` shim (e.g. NixOS
+    ``/run/current-system/sw/bin/docker -> podman``) by resolving the binary and
+    checking its real name. ``HEADROOM_CONTAINER_RUNTIME`` (``podman`` / ``docker``)
+    is an explicit override for setups the symlink heuristic cannot see, such as a
+    wrapper script. No subprocess is spawned.
+    """
+    override = os.environ.get("HEADROOM_CONTAINER_RUNTIME", "").strip().lower()
+    if override:
+        return override == "podman"
+    resolved = shutil.which("docker")
+    if not resolved:
+        return False
+    try:
+        real = os.path.realpath(resolved)
+    except OSError:
+        real = resolved
+    return "podman" in os.path.basename(real).lower()
+
+
 def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:
     return {
         "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,
@@ -136,10 +162,18 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
     if docker_gpus:
         command.extend(["--gpus", docker_gpus])
     if not _is_windows():
-        getuid = getattr(os, "getuid", None)
-        getgid = getattr(os, "getgid", None)
-        if callable(getuid) and callable(getgid):
-            command.extend(["--user", f"{getuid()}:{getgid()}"])
+        if _container_runtime_is_podman():
+            # Rootless Podman maps the host user to container UID 0, so --user
+            # would map to a subordinate UID that owns none of the bind mounts and
+            # every write into ~/.headroom fails (#2804). keep-id maps the host
+            # user to the same UID inside the container, keeping the mounts
+            # writable. Docker maps UIDs 1:1, so --user stays correct there.
+            command.append("--userns=keep-id")
+        else:
+            getuid = getattr(os, "getuid", None)
+            getgid = getattr(os, "getgid", None)
+            if callable(getuid) and callable(getgid):
+                command.extend(["--user", f"{getuid()}:{getgid()}"])
     runtime_env = {**manifest.base_env, **_deployment_env(manifest)}
     for name, value in runtime_env.items():
         command.extend(["--env", f"{name}={value}"])
diff --git a/headroom/install/supervisors.py b/headroom/install/supervisors.py
index 7d825fbe7..83f517576 100644
--- a/headroom/install/supervisors.py
+++ b/headroom/install/supervisors.py
@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
+import getpass
 import os
 import re
 import shlex
 import subprocess
 import sys
+import tempfile
 import time
+from datetime import datetime
 from pathlib import Path
+from xml.sax.saxutils import escape as _xml_escape
 
 import click
 
@@ -242,6 +246,97 @@ def _linux_task_spec(manifest: DeploymentManifest, ensure_script: Path) -> tuple
     return None, content
 
 
+def _windows_current_user() -> str:
+    """Best-effort ``DOMAIN\\USER`` for the S4U task principal."""
+
+    user = os.environ.get("USERNAME") or getpass.getuser()
+    domain = os.environ.get("USERDOMAIN")
+    return f"{domain}\\{user}" if domain else user
+
+
+def _windows_task_xml(command: str, *, trigger_xml: str, scope: str) -> str:
+    """Render Task Scheduler XML that runs ``command`` without a visible window.
+
+    User-scope tasks use an S4U principal ("run whether user is logged on or
+    not", no stored password) so each run happens in a non-interactive session
+    and never draws a console window (issue #2453). System-scope tasks keep the
+    LocalSystem service account, which already has no desktop.
+    """
+
+    if scope == "system":
+        principal = (
+            "    <UserId>S-1-5-18</UserId>\n"
+            "    <LogonType>ServiceAccount</LogonType>\n"
+            "    <RunLevel>HighestAvailable</RunLevel>"
+        )
+    else:
+        principal = (
+            f"    <UserId>{_xml_escape(_windows_current_user())}</UserId>\n"
+            "    <LogonType>S4U</LogonType>\n"
+            "    <RunLevel>LeastPrivilege</RunLevel>"
+        )
+    return (
+        '<?xml version="1.0" encoding="UTF-16"?>\n'
+        '<Task version="1.2" '
+        'xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">\n'
+        "  <Triggers>\n"
+        f"{trigger_xml}\n"
+        "  </Triggers>\n"
+        '  <Principals>\n    <Principal id="Author">\n'
+        f"{principal}\n"
+        "    </Principal>\n  </Principals>\n"
+        "  <Settings>\n"
+        "    <Hidden>true</Hidden>\n"
+        "    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>\n"
+        "    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>\n"
+        "    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>\n"
+        "    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>\n"
+        "    <StartWhenAvailable>true</StartWhenAvailable>\n"
+        "  </Settings>\n"
+        '  <Actions Context="Author">\n'
+        f"    <Exec>\n      <Command>{_xml_escape(command)}</Command>\n    </Exec>\n"
+        "  </Actions>\n"
+        "</Task>\n"
+    )
+
+
+def _windows_boot_trigger() -> str:
+    return "    <BootTrigger>\n      <Enabled>true</Enabled>\n    </BootTrigger>"
+
+
+def _windows_health_trigger() -> str:
+    start = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+    return (
+        "    <TimeTrigger>\n"
+        f"      <StartBoundary>{start}</StartBoundary>\n"
+        "      <Enabled>true</Enabled>\n"
+        "      <Repetition>\n"
+        "        <Interval>PT5M</Interval>\n"
+        "        <StopAtDurationEnd>false</StopAtDurationEnd>\n"
+        "      </Repetition>\n"
+        "    </TimeTrigger>"
+    )
+
+
+def _register_windows_task(name: str, xml: str) -> None:
+    """Register ``xml`` as scheduled task ``name`` via ``schtasks /XML``."""
+
+    # schtasks reads the XML from a file; UTF-16 matches the declared encoding.
+    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".xml", encoding="utf-16", delete=False)
+    try:
+        tmp.write(xml)
+        tmp.close()
+        subprocess.run(
+            ["schtasks", "/Create", "/TN", name, "/XML", tmp.name, "/F"],
+            check=True,
+        )
+    finally:
+        try:
+            os.unlink(tmp.name)
+        except OSError:
+            pass
+
+
 def install_supervisor(manifest: DeploymentManifest) -> list[ArtifactRecord]:
     """Install service/task artifacts for the deployment."""
 
@@ -345,35 +440,21 @@ def install_supervisor(manifest: DeploymentManifest) -> list[ArtifactRecord]:
         startup_name = f"{manifest.service_name}-startup"
         health_name = f"{manifest.service_name}-health"
         startup_cmd = str(windows_ensure_cmd_path(manifest.profile))
-        user_args = ["/RU", "SYSTEM"] if manifest.scope == "system" else []
-        start_schedule = [
-            "schtasks",
-            "/Create",
-            "/TN",
+        # Register from task XML (not schtasks flags) so the principal is S4U /
+        # hidden — flag-created tasks use an interactive token and flash a
+        # focus-stealing console on every run (issue #2453).
+        _register_windows_task(
             startup_name,
-            "/TR",
-            startup_cmd,
-            "/SC",
-            "ONSTART",
-            "/F",
-            *user_args,
-        ]
-        health_schedule = [
-            "schtasks",
-            "/Create",
-            "/TN",
+            _windows_task_xml(
+                startup_cmd, trigger_xml=_windows_boot_trigger(), scope=manifest.scope
+            ),
+        )
+        _register_windows_task(
             health_name,
-            "/TR",
-            startup_cmd,
-            "/SC",
-            "MINUTE",
-            "/MO",
-            "5",
-            "/F",
-            *user_args,
-        ]
-        subprocess.run(start_schedule, check=True)
-        subprocess.run(health_schedule, check=True)
+            _windows_task_xml(
+                startup_cmd, trigger_xml=_windows_health_trigger(), scope=manifest.scope
+            ),
+        )
         records.extend(
             [
                 ArtifactRecord(kind="windows-task", path=startup_name),
diff --git a/headroom/integrations/langchain/langgraph.py b/headroom/integrations/langchain/langgraph.py
index 2e6734795..83aad7560 100644
--- a/headroom/integrations/langchain/langgraph.py
+++ b/headroom/integrations/langchain/langgraph.py
@@ -49,6 +49,7 @@ except ImportError:
 
 from headroom.ccr.tool_injection import CCR_TOOL_NAME
 from headroom.config import is_tool_excluded
+from headroom.telemetry.session import BeaconCompressionObserver
 from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig
 
 logger = logging.getLogger(__name__)
@@ -136,7 +137,11 @@ class _CrusherSingleton:
                     config = SmartCrusherConfig(
                         min_tokens_to_crush=self._min_tokens,
                     )
-                    self._crusher = SmartCrusher(config=config)
+                    # observer: no proxy here, so nothing else reports these
+                    # compressions to the beacon. See BeaconCompressionObserver.
+                    self._crusher = SmartCrusher(
+                        config=config, observer=BeaconCompressionObserver()
+                    )
         return self._crusher
 
 
diff --git a/headroom/integrations/litellm_callback.py b/headroom/integrations/litellm_callback.py
index d5d54cacb..c88078069 100644
--- a/headroom/integrations/litellm_callback.py
+++ b/headroom/integrations/litellm_callback.py
@@ -94,6 +94,18 @@ class HeadroomCallback(_CustomLogger):
         """Whether cloud compression is enabled."""
         return self._api_key is not None
 
+    async def aclose(self) -> None:
+        """Close the shared cloud HTTP client, if it was initialized.
+
+        Applications using LiteLLM should await this method during their async
+        shutdown lifecycle. It is safe to call when cloud mode was not used or
+        after the client has already been closed.
+        """
+        client = self._client
+        self._client = None
+        if client is not None:
+            await client.aclose()
+
     async def async_pre_call_hook(
         self,
         user_api_key_dict: Any = None,
diff --git a/headroom/integrations/mcp/server.py b/headroom/integrations/mcp/server.py
index 23fdf3e8f..888ad6115 100644
--- a/headroom/integrations/mcp/server.py
+++ b/headroom/integrations/mcp/server.py
@@ -56,6 +56,7 @@ from typing import Any
 
 from headroom.config import HeadroomConfig, SmartCrusherConfig
 from headroom.providers.openai import OpenAIProvider
+from headroom.telemetry.session import BeaconCompressionObserver
 from headroom.transforms.smart_crusher import SmartCrusher
 
 
@@ -263,7 +264,18 @@ class HeadroomMCPCompressor:
             min_tokens_to_crush=profile.min_tokens_to_compress,
             max_items_after_crush=profile.max_items,
         )
-        crusher = SmartCrusher(config=smart_config, with_compaction=False)  # type: ignore[arg-type]
+        # observer: MCP runs outside the proxy, so PrometheusMetrics (the
+        # proxy's observer, which forwards to the beacon) never sees these
+        # compressions. Without one, an MCP install reports real tokens.saved
+        # with an empty compression.by_strategy.
+        crusher = SmartCrusher(
+            # headroom.config.SmartCrusherConfig vs the transform's own
+            # same-named dataclass; the ignore has to sit on the argument line
+            # because that is where mypy reports a multi-line call's arg-type.
+            config=smart_config,  # type: ignore[arg-type]
+            with_compaction=False,
+            observer=BeaconCompressionObserver(),
+        )
 
         # Build messages for SmartCrusher (it expects conversation format)
         messages = [
diff --git a/headroom/integrations/strands/hooks.py b/headroom/integrations/strands/hooks.py
index 275b6f64d..07ef31887 100644
--- a/headroom/integrations/strands/hooks.py
+++ b/headroom/integrations/strands/hooks.py
@@ -50,6 +50,7 @@ except ImportError:
 from headroom import HeadroomConfig
 from headroom.ccr.tool_injection import CCR_TOOL_NAME
 from headroom.config import is_tool_excluded
+from headroom.telemetry.session import BeaconCompressionObserver
 from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig
 
 logger = logging.getLogger(__name__)
@@ -173,7 +174,11 @@ class HeadroomHookProvider(HookProvider):  # type: ignore[misc]
                         crusher_config = SmartCrusherConfig(
                             min_tokens_to_crush=self.min_tokens_to_compress
                         )
-                    self._crusher = SmartCrusher(config=crusher_config)
+                    # observer: no proxy here, so nothing else reports these
+                    # compressions to the beacon. See BeaconCompressionObserver.
+                    self._crusher = SmartCrusher(
+                        config=crusher_config, observer=BeaconCompressionObserver()
+                    )
                     logger.debug(
                         "SmartCrusher initialized with min_tokens=%d", self.min_tokens_to_compress
                     )
diff --git a/headroom/learn/_shared.py b/headroom/learn/_shared.py
index cb3a926f6..ba6f9944e 100644
--- a/headroom/learn/_shared.py
+++ b/headroom/learn/_shared.py
@@ -85,6 +85,14 @@ def classify_error(content: str) -> ErrorCategory:
     return ErrorCategory.UNKNOWN
 
 
+# "exit code" only signals an error for a NONZERO code. Agent harnesses (Codex,
+# Grok, opencode, ...) append "exit code 0" to every SUCCESSFUL shell command,
+# so a bare "exit code" substring wrongly flagged those as errors and inflated
+# the learned failure rate. Match a nonzero code (case-insensitive, so
+# "Exit code: 1" counts too), never "exit code 0".
+_NONZERO_EXIT_RE = re.compile(r"exit code:?\s*(?!0\b)\d", re.IGNORECASE)
+
+
 def is_error_content(content: str) -> bool:
     """Heuristic: does this tool result look like an error?"""
     if not content or len(content) < 10:
@@ -105,10 +113,11 @@ def is_error_content(content: str) -> bool:
         "auto-denied",
         "Sibling tool call errored",
         "timed out",
-        "exit code",
         "FileNotFoundError",
     ]
-    return any(ind in snippet for ind in indicators)
+    if any(ind in snippet for ind in indicators):
+        return True
+    return bool(_NONZERO_EXIT_RE.search(snippet))
 
 
 # =============================================================================
diff --git a/headroom/learn/plugins/gemini.py b/headroom/learn/plugins/gemini.py
index 15e589a68..fd4722aa8 100644
--- a/headroom/learn/plugins/gemini.py
+++ b/headroom/learn/plugins/gemini.py
@@ -216,14 +216,15 @@ class GeminiPlugin(LearnPlugin, ConversationScanner):
 
             usage = msg.get("usageMetadata", msg.get("usage", {}))
             if isinstance(usage, dict):
+                # Gemini's promptTokenCount is the FULL input token count and
+                # cachedContentTokenCount is the cached SUBSET of it, so adding
+                # both double-counts the cached input. Likewise totalTokenCount
+                # == promptTokenCount + candidatesTokenCount, so
+                # (totalTokenCount - promptTokenCount) is just candidatesTokenCount
+                # again — adding it on top double-counts the output. Count the
+                # prompt as input and the candidates as output, once each.
                 total_input_tokens += usage.get("promptTokenCount", 0)
-                total_input_tokens += usage.get("cachedContentTokenCount", 0)
                 total_output_tokens += usage.get("candidatesTokenCount", 0)
-                total_output_tokens += (
-                    usage.get("totalTokenCount", 0) - usage.get("promptTokenCount", 0)
-                    if usage.get("totalTokenCount")
-                    else 0
-                )
 
             if not isinstance(parts, list):
                 continue
@@ -312,7 +313,16 @@ class GeminiPlugin(LearnPlugin, ConversationScanner):
         )
 
     def _detect_project_path(self, session_path: Path) -> Path | None:
-        """Try to detect the project path from a session file."""
+        """Try to detect the project path from a session file (JSON or JSONL)."""
+        # A `.jsonl` session is a stream of one JSON object per line, so
+        # `json.load` on the whole file raises JSONDecodeError on the second
+        # line and detection silently fell back to cwd — writing the learned
+        # insights to the wrong project and missing its GEMINI.md. Read JSONL
+        # line-by-line like the sibling `_scan_jsonl_session` (and the Claude
+        # plugin's `_project_path_from_session_cwd`) do.
+        if session_path.suffix == ".jsonl":
+            return self._detect_project_path_jsonl(session_path)
+
         try:
             with open(session_path, encoding="utf-8", errors="replace") as f:
                 data = json.load(f)
@@ -320,15 +330,39 @@ class GeminiPlugin(LearnPlugin, ConversationScanner):
             return None
 
         if isinstance(data, dict):
-            project_path = data.get("projectPath", data.get("project_path", ""))
-            if project_path and Path(project_path).exists():
-                return Path(project_path)
-            cwd = data.get("cwd", data.get("workingDirectory", ""))
-            if cwd and Path(cwd).exists():
-                return Path(cwd)
+            return self._project_path_from_entry(data)
 
         return None
 
+    def _detect_project_path_jsonl(self, session_path: Path) -> Path | None:
+        try:
+            with open(session_path, encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        entry = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if not isinstance(entry, dict):
+                        continue
+                    found = self._project_path_from_entry(entry)
+                    if found is not None:
+                        return found
+        except (OSError, UnicodeDecodeError):
+            return None
+        return None
+
+    @staticmethod
+    def _project_path_from_entry(entry: dict) -> Path | None:
+        project_path = entry.get("projectPath", entry.get("project_path", ""))
+        if project_path and Path(project_path).exists():
+            return Path(project_path)
+        cwd = entry.get("cwd", entry.get("workingDirectory", ""))
+        if cwd and Path(cwd).exists():
+            return Path(cwd)
+        return None
+
 
 # Module-level instance for auto-discovery by the plugin registry
 plugin = GeminiPlugin()
diff --git a/headroom/learn/plugins/grok.py b/headroom/learn/plugins/grok.py
index c274dcf29..898466126 100644
--- a/headroom/learn/plugins/grok.py
+++ b/headroom/learn/plugins/grok.py
@@ -58,7 +58,15 @@ class GrokPlugin(LearnPlugin, ConversationScanner):
                 continue
 
             decoded = unquote(workspace_dir.name)
-            project_path = Path(decoded) if decoded.startswith("/") else Path.cwd()
+            # The workspace dir name is a URL-encoded absolute cwd. Use
+            # Path.is_absolute() rather than a `startswith("/")` check so a
+            # Windows drive-letter path (e.g. `C:\Users\...`) is recognised as
+            # absolute instead of silently falling back to cwd (which would
+            # attribute the learnings to the wrong project and miss its
+            # GROK.md/AGENTS.md). Mirrors the Windows-aware path handling in
+            # memory/traffic_learner.py.
+            decoded_path = Path(decoded)
+            project_path = decoded_path if decoded_path.is_absolute() else Path.cwd()
             agents_md = project_path / "AGENTS.md"
             grok_md = project_path / "GROK.md"
 
diff --git a/headroom/mcp_registry/install.py b/headroom/mcp_registry/install.py
index d8a9f7f09..e550f6ded 100644
--- a/headroom/mcp_registry/install.py
+++ b/headroom/mcp_registry/install.py
@@ -59,8 +59,11 @@ def build_serena_spec(context: str) -> ServerSpec:
         name="serena",
         command="uvx",
         args=(
+            # The PyPI package (serena-agent) ships prebuilt wheels; the git
+            # source forced a from-source build that fails under proot-based
+            # filesystems where uv cannot hardlink into a build venv (#2871).
             "--from",
-            "git+https://github.com/oraios/serena",
+            "serena-agent",
             "serena",
             "start-mcp-server",
             "--project-from-cwd",
diff --git a/headroom/memory/adapters/hnsw.py b/headroom/memory/adapters/hnsw.py
index 9d7f54d47..5f474bd5c 100644
--- a/headroom/memory/adapters/hnsw.py
+++ b/headroom/memory/adapters/hnsw.py
@@ -22,7 +22,7 @@ from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
-from ..models import Memory, ScopeLevel
+from ..models import Memory, ScopeLevel, normalize_entity_refs
 from ..ports import VectorFilter, VectorSearchResult
 
 # hnswlib is optional - may not compile on all platforms
@@ -139,7 +139,9 @@ class IndexedMemoryMetadata:
             valid_until=(
                 datetime.fromisoformat(data["valid_until"]) if data.get("valid_until") else None
             ),
-            entity_refs=data.get("entity_refs", []),
+            # Normalized on load so rows written before #2947 was fixed heal
+            # themselves instead of crashing search.
+            entity_refs=normalize_entity_refs(data.get("entity_refs")),
             content=data["content"],
             created_at=datetime.fromisoformat(data["created_at"]),
             importance=data.get("importance", 0.5),
diff --git a/headroom/memory/adapters/sqlite.py b/headroom/memory/adapters/sqlite.py
index 3b779bd91..c5fcdf28c 100644
--- a/headroom/memory/adapters/sqlite.py
+++ b/headroom/memory/adapters/sqlite.py
@@ -16,7 +16,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from ..models import Memory, ScopeLevel
+from ..models import Memory, ScopeLevel, normalize_entity_refs
 from ..ports import MemoryFilter
 
 if TYPE_CHECKING:
@@ -227,7 +227,11 @@ class SQLiteMemoryStore:
             last_accessed=datetime.fromisoformat(row["last_accessed"])
             if row["last_accessed"]
             else None,
-            entity_refs=json.loads(row["entity_refs"]) if row["entity_refs"] else [],
+            # Normalized on load so rows written before #2947 was fixed heal
+            # themselves instead of crashing search.
+            entity_refs=normalize_entity_refs(
+                json.loads(row["entity_refs"]) if row["entity_refs"] else []
+            ),
             embedding=self._deserialize_embedding(row["embedding"]),
             metadata=json.loads(row["metadata"]) if row["metadata"] else {},
         )
diff --git a/headroom/memory/adapters/sqlite_vector.py b/headroom/memory/adapters/sqlite_vector.py
index e67310320..71cd96a83 100644
--- a/headroom/memory/adapters/sqlite_vector.py
+++ b/headroom/memory/adapters/sqlite_vector.py
@@ -29,7 +29,7 @@ from typing import TYPE_CHECKING, Any, cast
 
 import numpy as np
 
-from ..models import Memory, ScopeLevel
+from ..models import Memory, ScopeLevel, normalize_entity_refs
 from ..ports import VectorFilter, VectorSearchResult
 
 if TYPE_CHECKING:
@@ -135,7 +135,9 @@ class VectorMetadata:
             valid_until=(
                 datetime.fromisoformat(d["valid_until"]) if d.get("valid_until") else None
             ),
-            entity_refs=d.get("entity_refs", []),
+            # Normalized on load so rows written before #2947 was fixed heal
+            # themselves instead of crashing search.
+            entity_refs=normalize_entity_refs(d.get("entity_refs")),
             content=d["content"],
             created_at=datetime.fromisoformat(d["created_at"]),
             importance=d.get("importance", 0.5),
diff --git a/headroom/memory/backends/direct_mem0.py b/headroom/memory/backends/direct_mem0.py
index c086ef012..20c454620 100644
--- a/headroom/memory/backends/direct_mem0.py
+++ b/headroom/memory/backends/direct_mem0.py
@@ -49,6 +49,7 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
+import inspect
 import logging
 import uuid
 from dataclasses import dataclass, field
@@ -150,6 +151,7 @@ class DirectMem0Adapter:
         """
         self._config = config or Mem0Config()
         self._mem0_client: Any = None
+        self._openai_client: Any = None
         self._embedder: Any = None
         self._neo4j_graph: Any = None
         self._neo4j_driver: Any = None
@@ -159,6 +161,7 @@ class DirectMem0Adapter:
         # Background task tracking
         self._background_tasks: dict[str, asyncio.Task] = {}
         self._task_results: dict[str, dict[str, Any]] = {}
+        self._close_lock = asyncio.Lock()
 
     async def _ensure_initialized(self) -> None:
         """Ensure all clients are initialized."""
@@ -389,7 +392,10 @@ class DirectMem0Adapter:
 
         task = self._background_tasks[task_id]
         try:
-            await asyncio.wait_for(task, timeout=timeout)
+            # A timeout must not cancel a save that may be awaiting
+            # ``asyncio.to_thread``.  Cancelling the asyncio task does not stop
+            # the underlying worker, and would hide that worker from close().
+            await asyncio.wait_for(asyncio.shield(task), timeout=timeout)
             return self.get_task_status(task_id)
         except asyncio.TimeoutError:
             return {"status": "timeout", "task_id": task_id}
@@ -949,9 +955,71 @@ class DirectMem0Adapter:
         """Whether this backend supports vector search."""
         return True
 
-    async def close(self) -> None:
-        """Close connections and release resources."""
-        if self._neo4j_driver:
-            self._neo4j_driver.close()
-        self._mem0_client = None
-        self._initialized = False
+    async def close(self, timeout: float = 60.0) -> None:
+        """Drain background writes and close all initialized resources.
+
+        Args:
+            timeout: Maximum seconds to wait for background writes to finish.
+
+        Raises:
+            TimeoutError: If background writes have not quiesced within
+                ``timeout``.  Tasks remain tracked and resources remain open so
+                callers can retry after the writes finish.
+        """
+        # Concurrent shutdown callers must observe one lifecycle transition.
+        # In particular, a second caller must not detach resources while the
+        # first is still waiting for executor-backed writes to quiesce.
+        async with self._close_lock:
+            if self._background_tasks:
+                task_items = list(self._background_tasks.items())
+                tasks = [task for _, task in task_items]
+                _, pending = await asyncio.wait(tasks, timeout=timeout)
+
+                if pending:
+                    pending_ids = [task_id for task_id, task in task_items if task in pending]
+                    raise TimeoutError(
+                        "Timed out waiting for DirectMem0 background writes: "
+                        + ", ".join(pending_ids)
+                    )
+
+                for task_id, task in task_items:
+                    try:
+                        self._task_results[task_id] = {
+                            "status": "completed",
+                            "result": task.result(),
+                        }
+                    except Exception as e:
+                        self._task_results[task_id] = {
+                            "status": "failed",
+                            "error": str(e),
+                        }
+                self._background_tasks.clear()
+
+            resources = [
+                ("Mem0 client", self._mem0_client),
+                ("OpenAI client", self._openai_client),
+                ("Qdrant client", self._qdrant_client),
+                ("Neo4j driver", self._neo4j_driver),
+                ("embedder", self._embedder),
+                ("Neo4j graph", self._neo4j_graph),
+            ]
+            self._mem0_client = None
+            self._openai_client = None
+            self._qdrant_client = None
+            self._neo4j_driver = None
+            self._embedder = None
+            self._neo4j_graph = None
+            self._initialized = False
+
+            for name, resource in resources:
+                if resource is None:
+                    continue
+                close = getattr(resource, "close", None) or getattr(resource, "aclose", None)
+                if close is None:
+                    continue
+                try:
+                    result = close()
+                    if inspect.isawaitable(result):
+                        await result
+                except Exception as e:
+                    logger.warning("Failed to close %s: %s", name, e)
diff --git a/headroom/memory/backends/local.py b/headroom/memory/backends/local.py
index 6fafeb91b..7010bc920 100644
--- a/headroom/memory/backends/local.py
+++ b/headroom/memory/backends/local.py
@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from headroom.memory.adapters.graph_models import Entity, Relationship, Subgraph
-from headroom.memory.models import Memory
+from headroom.memory.models import Memory, normalize_entity_refs
 from headroom.memory.ports import MemorySearchResult
 from headroom.models.config import ML_MODEL_DEFAULTS
 
@@ -284,8 +284,15 @@ class LocalBackend:
         # Determine if using pre-extraction mode
         has_pre_extraction = bool(facts or extracted_entities or extracted_relationships)
 
-        # Merge entity names from both simple and typed formats
-        all_entity_names: list[str] = list(entities) if entities else []
+        # Merge entity names from both simple and typed formats.
+        #
+        # `entities` is typed list[str], but it is populated straight from
+        # LLM-supplied memory_save tool arguments, and callers do sometimes
+        # pass the typed {"entity": ..., "entity_type": ...} shape here (that
+        # is what extracted_entities is for). Normalizing keeps those dicts out
+        # of entity_refs, where they used to crash every later search that
+        # retrieved the row -- see issue #2947.
+        all_entity_names: list[str] = normalize_entity_refs(entities)
         entity_types: dict[str, str] = {}
 
         if extracted_entities:
@@ -448,13 +455,17 @@ class LocalBackend:
                 continue
 
             seen_memory_ids.add(vr.memory.id)
-            all_entity_refs.update(vr.memory.entity_refs)
+            # Defense in depth: the storage adapters normalize entity_refs on
+            # load, but a backend that hands us Memory objects some other way
+            # must not be able to abort the whole search with one bad row.
+            entity_refs = normalize_entity_refs(vr.memory.entity_refs)
+            all_entity_refs.update(entity_refs)
 
             results.append(
                 MemorySearchResult(
                     memory=vr.memory,
                     score=vr.similarity,
-                    related_entities=list(vr.memory.entity_refs),
+                    related_entities=entity_refs,
                     related_memories=[],
                 )
             )
@@ -503,15 +514,17 @@ class LocalBackend:
                         MemorySearchResult(
                             memory=memory,
                             score=0.5,  # Default score for graph-expanded results
-                            related_entities=list(memory.entity_refs),
+                            related_entities=normalize_entity_refs(memory.entity_refs),
                             related_memories=[],
                         )
                     )
                     seen_memory_ids.add(mem_id)
 
-        # Filter by specified entities if provided
+        # Filter by specified entities if provided. Like the save path, this
+        # argument arrives from LLM-supplied tool input, so it gets the same
+        # normalization rather than trusting its list[str] annotation.
         if entities:
-            entities_lower = {e.lower() for e in entities}
+            entities_lower = {e.lower() for e in normalize_entity_refs(entities)}
             results = [
                 r
                 for r in results
@@ -528,6 +541,12 @@ class LocalBackend:
         assert self._hierarchical_memory is not None
         return await self._hierarchical_memory.record_access(memory_ids)
 
+    async def refresh_memory_indexes(self, memory_id: str) -> Memory | None:
+        """Refresh vector metadata and cache state from the primary store."""
+        await self._ensure_initialized()
+        assert self._hierarchical_memory is not None
+        return await self._hierarchical_memory.refresh_memory_indexes(memory_id)
+
     async def update_memory(
         self,
         memory_id: str,
@@ -820,7 +839,7 @@ class LocalBackend:
             MemorySearchResult(
                 memory=tr.memory,
                 score=tr.score,
-                related_entities=list(tr.memory.entity_refs),
+                related_entities=normalize_entity_refs(tr.memory.entity_refs),
                 related_memories=[],
             )
             for tr in text_results
diff --git a/headroom/memory/core.py b/headroom/memory/core.py
index 0265b8e12..776d5152c 100644
--- a/headroom/memory/core.py
+++ b/headroom/memory/core.py
@@ -494,10 +494,14 @@ class HierarchicalMemory:
         # Save updates
         await self._store.save(memory)
 
-        # Update indexes
+        # Vector indexes also carry filterable metadata. Refresh them for
+        # metadata-only updates, not just when the embedding content changes.
+        vector_metadata_changed = any(
+            value is not None for value in (importance, entity_refs, metadata)
+        )
+        if (content_changed or vector_metadata_changed) and memory.embedding is not None:
+            await self._vector_index.index(memory)
         if content_changed:
-            if memory.embedding is not None:
-                await self._vector_index.index(memory)
             await self._index_for_text_search(memory)
 
         # Invalidate and re-cache
@@ -507,6 +511,21 @@ class HierarchicalMemory:
 
         return memory
 
+    async def refresh_memory_indexes(self, memory_id: str) -> Memory | None:
+        """Refresh secondary index metadata from the primary memory store."""
+        memory = await self._store.get(memory_id)
+        if memory is None:
+            return None
+
+        if memory.embedding is not None:
+            await self._vector_index.index(memory)
+
+        if self._cache is not None:
+            await self._cache.invalidate(memory_id)
+            await self._cache.put(memory)
+
+        return memory
+
     async def supersede(
         self,
         old_memory_id: str,
diff --git a/headroom/memory/inline_extractor.py b/headroom/memory/inline_extractor.py
index bcbf6aabf..f560ae3ed 100644
--- a/headroom/memory/inline_extractor.py
+++ b/headroom/memory/inline_extractor.py
@@ -126,9 +126,21 @@ def parse_response_with_memory(response_text: str) -> ParsedResponse:
         # Parse the JSON
         try:
             data = json.loads(memory_json)
-            memories = data.get("memories", [])
         except json.JSONDecodeError as e:
             logger.warning(f"Failed to parse memory JSON: {e}")
+        else:
+            # The model controls the block content. A valid-JSON non-object
+            # (e.g. a bare array) would make `.get` raise AttributeError, which
+            # the JSONDecodeError guard above does not catch; likewise a
+            # non-list `memories` would break downstream iteration.
+            if isinstance(data, dict):
+                extracted = data.get("memories", [])
+                if isinstance(extracted, list):
+                    memories = extracted
+                else:
+                    logger.warning("Memory JSON 'memories' field is not a list; ignoring")
+            else:
+                logger.warning("Memory JSON is not an object; ignoring")
 
     return ParsedResponse(
         content=content,
diff --git a/headroom/memory/mcp_server.py b/headroom/memory/mcp_server.py
index 2a42dc7ab..3720b3e4f 100644
--- a/headroom/memory/mcp_server.py
+++ b/headroom/memory/mcp_server.py
@@ -162,6 +162,7 @@ def create_memory_server(db_path: str, user_id: str = "default") -> Server:
     server = Server("headroom-memory")
     _backend: LocalBackend | None = None
     _init_task: asyncio.Task[LocalBackend] | None = None
+    _close_lock = asyncio.Lock()
 
     async def _init_backend() -> LocalBackend:
         """Initialize backend with ONNX embedder (fast, no PyTorch)."""
@@ -225,6 +226,26 @@ def create_memory_server(db_path: str, user_id: str = "default") -> Server:
                 _init_task = None
             raise
 
+    async def _close_backend() -> None:
+        """Cancel backend initialization and close any initialized backend."""
+        nonlocal _backend, _init_task
+        async with _close_lock:
+            init_task = _init_task
+            if init_task is not None:
+                if not init_task.done():
+                    init_task.cancel()
+                await asyncio.gather(init_task, return_exceptions=True)
+                if _init_task is init_task:
+                    _init_task = None
+
+            backend = _backend
+            _backend = None
+            if backend is not None:
+                try:
+                    await backend.close()
+                except Exception as cleanup_error:
+                    logger.warning("Memory MCP: failed backend cleanup: %s", cleanup_error)
+
     @server.list_tools()
     async def list_tools() -> list[Tool]:
         # Kick off background init on first list_tools (called at MCP handshake)
@@ -243,6 +264,7 @@ def create_memory_server(db_path: str, user_id: str = "default") -> Server:
 
         return [TextContent(type="text", text=f"Unknown tool: {name}")]
 
+    server._headroom_close = _close_backend  # type: ignore[attr-defined]
     return server
 
 
@@ -357,8 +379,13 @@ async def _handle_save(
 
 async def _run(db_path: str, user_id: str) -> None:
     server = create_memory_server(db_path, user_id)
-    async with stdio_server() as (read_stream, write_stream):
-        await server.run(read_stream, write_stream, server.create_initialization_options())
+    try:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(read_stream, write_stream, server.create_initialization_options())
+    finally:
+        close_backend = getattr(server, "_headroom_close", None)
+        if close_backend is not None:
+            await close_backend()
 
 
 def _memory_mcp_startup_context(
diff --git a/headroom/memory/models.py b/headroom/memory/models.py
index 6e1293c34..2ecdcabe4 100644
--- a/headroom/memory/models.py
+++ b/headroom/memory/models.py
@@ -14,6 +14,46 @@ except ImportError:
     np = None  # type: ignore[assignment]
 
 
+def normalize_entity_refs(values: Any) -> list[str]:
+    """Coerce a raw entity-reference list into the plain ``list[str]`` it claims to be.
+
+    ``entity_refs`` (and the ``entities`` argument that feeds it) is typed
+    ``list[str]``, but nothing enforced that at runtime, so callers have
+    persisted the typed ``{"entity": ..., "entity_type": ...}`` shape -- the
+    format ``extracted_entities`` expects -- into it by mistake. Those dicts
+    then break every consumer that treats a ref as a string: ``set().update()``
+    raises ``TypeError: unhashable type: 'dict'`` and ``ref.lower()`` raises
+    ``AttributeError``, which took down whole memory searches rather than the
+    one bad row (see issue #2947).
+
+    Dicts are unwrapped to their ``entity`` name so no information is lost;
+    anything with no recoverable name is dropped rather than stringified, since
+    a ref like ``"{'entity_type': 'project'}"`` would only pollute the graph.
+    Order is preserved and duplicate names are collapsed.
+    """
+    if not values:
+        return []
+
+    normalized: list[str] = []
+    seen: set[str] = set()
+
+    for value in values:
+        if isinstance(value, str):
+            name = value
+        elif isinstance(value, dict):
+            # The extracted_entities shape, mistakenly used as a plain name.
+            candidate = value.get("entity") or value.get("name")
+            name = candidate if isinstance(candidate, str) else ""
+        else:
+            name = ""
+
+        if name and name not in seen:
+            seen.add(name)
+            normalized.append(name)
+
+    return normalized
+
+
 class ScopeLevel(Enum):
     """Memory scope hierarchy levels."""
 
@@ -132,7 +172,9 @@ class Memory:
             last_accessed=datetime.fromisoformat(data["last_accessed"])
             if data.get("last_accessed")
             else None,
-            entity_refs=data.get("entity_refs", []),
+            # Normalized on load so rows written before #2947 was fixed heal
+            # themselves instead of crashing search.
+            entity_refs=normalize_entity_refs(data.get("entity_refs")),
             embedding=embedding,
             metadata=data.get("metadata", {}),
         )
diff --git a/headroom/memory/storage_router.py b/headroom/memory/storage_router.py
index 5337e32f7..45f980584 100644
--- a/headroom/memory/storage_router.py
+++ b/headroom/memory/storage_router.py
@@ -160,7 +160,15 @@ class ProjectResolver:
         if explicit:
             safe = self._sanitize_basename(explicit)
             if safe:
-                return safe, explicit
+                # Append a digest of the raw id like `_identity_from_cwd` does:
+                # `_sanitize_basename` maps every disallowed character to a dash
+                # and truncates to 64 chars, so distinct ids such as "acme/api"
+                # and "acme api" both collapse to "acme-api" and would otherwise
+                # share one project store (cross-project memory leak). The digest
+                # keeps distinct ids on distinct keys while the sanitized prefix
+                # stays human-readable on disk.
+                digest = hashlib.sha256(explicit.encode("utf-8")).hexdigest()[:16]
+                return f"{safe}-{digest}", explicit
 
         # Tier 2: client-provided explicit cwd (any client).
         explicit_cwd = self._first_nonempty_header(ctx.headers, "x-headroom-cwd")
@@ -294,12 +302,20 @@ class BackendRouter:
 
         if mode is MemoryStorageMode.USER:
             user_safe = ProjectResolver._sanitize_basename(ctx.base_user_id) or "default"
-            db_path = self._config.root_dir / "users" / user_safe / "memory.db"
+            # Append a digest of the raw user id for the same reason as the
+            # project keys above: `_sanitize_basename` collapses distinct ids
+            # ("alice/qa", "alice qa", "alice@qa") to the same "alice-qa", which
+            # in USER mode would pool two different users into one memory.db —
+            # a cross-user data-isolation leak, the one thing USER mode exists to
+            # prevent. The digest keeps distinct users on distinct stores.
+            digest = hashlib.sha256(ctx.base_user_id.encode("utf-8")).hexdigest()[:16]
+            user_key = f"{user_safe}-{digest}"
+            db_path = self._config.root_dir / "users" / user_key / "memory.db"
             return ResolvedScope(
                 mode=MemoryStorageMode.USER,
                 db_path=db_path,
                 display_name=ctx.base_user_id,
-                project_key=user_safe,
+                project_key=user_key,
             )
 
         # PROJECT mode.
diff --git a/headroom/memory/traffic_learner.py b/headroom/memory/traffic_learner.py
index bcecefef0..612af996c 100644
--- a/headroom/memory/traffic_learner.py
+++ b/headroom/memory/traffic_learner.py
@@ -26,6 +26,7 @@ import os
 import re
 import sqlite3
 import time
+from collections import OrderedDict
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
@@ -450,6 +451,7 @@ class TrafficLearner:
         max_history: int = 20,
         dedup_window: int = 100,
         min_evidence: int = 5,
+        max_pending_patterns: int = 2048,
     ) -> None:
         """Initialize the traffic learner.
 
@@ -468,12 +470,19 @@ class TrafficLearner:
         self.agent_type = agent_type
         self._max_history = max_history
         self._min_evidence = min_evidence
+        self._max_pending_patterns = max_pending_patterns
 
         # Recent tool call history for error→recovery matching
         self._tool_history: list[dict[str, Any]] = []
 
-        # Pattern accumulator: hash → (pattern, count)
-        self._pattern_counts: dict[str, tuple[ExtractedPattern, int]] = {}
+        # Pattern accumulator: hash → (pattern, count). LRU-ordered and capped:
+        # a pattern that is seen once but never reaches ``min_evidence`` would
+        # otherwise linger here forever, so this dict grew unbounded over a
+        # long-lived proxy's traffic (the sibling ``_saved_hashes`` is trimmed
+        # to ``dedup_window`` for the same reason; this one was missed). Evicting
+        # the least-recently-corroborated pending pattern is safe: if it recurs
+        # it simply restarts accumulation.
+        self._pattern_counts: OrderedDict[str, tuple[ExtractedPattern, int]] = OrderedDict()
 
         # Dedup: hashes of patterns already saved to DB
         self._saved_hashes: set[str] = set()
@@ -1250,7 +1259,13 @@ class TrafficLearner:
             existing, count = self._pattern_counts[h]
             count += 1
             self._pattern_counts[h] = (existing, count)
+            # Mark as most-recently-corroborated so it survives LRU eviction.
+            self._pattern_counts.move_to_end(h)
         else:
+            # Bound the pending accumulator so one-off patterns can't grow it
+            # without limit; drop the least-recently-corroborated pending entry.
+            if len(self._pattern_counts) >= self._max_pending_patterns:
+                self._pattern_counts.popitem(last=False)
             self._pattern_counts[h] = (pattern, 1)
             return  # First sighting — wait for more evidence
 
@@ -1374,10 +1389,10 @@ class TrafficLearner:
 
         now_iso = datetime.now(timezone.utc).isoformat()
 
-        def _bump() -> None:
+        def _bump() -> bool:
             conn = sqlite3.connect(str(db_path))
             try:
-                conn.execute(
+                cursor = conn.execute(
                     "UPDATE memories SET metadata = json_set("
                     "metadata, '$.evidence_count', "
                     "COALESCE(json_extract(metadata, '$.evidence_count'), 0) + 1, "
@@ -1386,13 +1401,26 @@ class TrafficLearner:
                     (now_iso, memory_id),
                 )
                 conn.commit()
+                return cursor.rowcount > 0
             finally:
                 conn.close()
 
         try:
-            await asyncio.to_thread(_bump)
+            updated = await asyncio.to_thread(_bump)
         except Exception as e:
             logger.debug("Traffic learner evidence bump failed for %s: %s", memory_id, e)
+            return
+
+        refresh = getattr(self._backend, "refresh_memory_indexes", None)
+        if updated and refresh is not None:
+            try:
+                await refresh(memory_id)
+            except Exception as e:
+                logger.debug(
+                    "Traffic learner evidence index refresh failed for %s: %s",
+                    memory_id,
+                    e,
+                )
 
     # =========================================================================
     # Convenience: Extract from Anthropic messages format
@@ -1448,6 +1476,11 @@ class TrafficLearner:
                         "input": tool_use.get("input", {}),
                         "output": str(result_content),
                         "is_error": block.get("is_error", False) or _is_error(str(result_content)),
+                        # Stable per-turn identity (the tool_use/tool_result id).
+                        # Lets a caller dedup a replayed transcript so the same
+                        # result is not counted as evidence twice — used by the
+                        # Codex WebSocket ingestion path.
+                        "call_id": tool_use_id,
                     }
                 )
 
diff --git a/headroom/observability/__init__.py b/headroom/observability/__init__.py
index 7c261ba7b..e6249ac9e 100644
--- a/headroom/observability/__init__.py
+++ b/headroom/observability/__init__.py
@@ -7,9 +7,11 @@ from .metrics import (
     get_otel_meter,
     get_otel_metrics,
     get_otel_metrics_status,
+    register_otel_metric_attribute_provider,
     reset_otel_metrics,
     set_otel_metrics,
     shutdown_otel_metrics,
+    unregister_otel_metric_attribute_provider,
 )
 from .tracing import (
     HeadroomTracer,
@@ -29,6 +31,7 @@ __all__ = [
     "get_otel_meter",
     "get_otel_metrics",
     "get_otel_metrics_status",
+    "register_otel_metric_attribute_provider",
     "HeadroomTracer",
     "LangfuseTracingConfig",
     "configure_langfuse_tracing",
@@ -40,4 +43,5 @@ __all__ = [
     "set_headroom_tracer",
     "shutdown_headroom_tracing",
     "shutdown_otel_metrics",
+    "unregister_otel_metric_attribute_provider",
 ]
diff --git a/headroom/observability/metrics.py b/headroom/observability/metrics.py
index a2c55ae7b..22d5da309 100644
--- a/headroom/observability/metrics.py
+++ b/headroom/observability/metrics.py
@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from threading import Lock
 from typing import Any, Literal
@@ -26,6 +27,67 @@ _global_metrics: HeadroomOtelMetrics | None = None
 _owned_meter_provider: Any | None = None
 _owned_metrics_config: OTelMetricsConfig | None = None
 
+MetricAttributeProvider = Callable[[], Mapping[str, Any]]
+_metric_attribute_providers: list[MetricAttributeProvider] = []
+_metric_attribute_providers_lock = Lock()
+_MAX_DYNAMIC_ATTRIBUTES = 16
+_MAX_DYNAMIC_ATTRIBUTE_LENGTH = 256
+
+
+def register_otel_metric_attribute_provider(
+    provider: MetricAttributeProvider,
+) -> MetricAttributeProvider:
+    """Add request-scoped attributes to every Headroom OTEL datapoint.
+
+    Extensions use this narrow seam for dimensions such as tenant, team, or
+    user identity without coupling the OSS metrics layer to an auth package.
+    Providers run in the request context and must return content-free scalar
+    labels. A failing provider is ignored so observability cannot break traffic.
+    """
+
+    with _metric_attribute_providers_lock:
+        if provider not in _metric_attribute_providers:
+            _metric_attribute_providers.append(provider)
+    return provider
+
+
+def unregister_otel_metric_attribute_provider(provider: MetricAttributeProvider) -> None:
+    """Remove a previously registered request-attribute provider."""
+
+    with _metric_attribute_providers_lock:
+        try:
+            _metric_attribute_providers.remove(provider)
+        except ValueError:
+            pass
+
+
+def _dynamic_metric_attributes() -> dict[str, Any]:
+    with _metric_attribute_providers_lock:
+        providers = tuple(_metric_attribute_providers)
+
+    resolved: dict[str, Any] = {}
+    for provider in providers:
+        try:
+            attributes = provider()
+        except Exception:
+            logger.debug("OTEL metric attribute provider failed", exc_info=True)
+            continue
+        if not isinstance(attributes, Mapping):
+            continue
+        for raw_key, raw_value in attributes.items():
+            if len(resolved) >= _MAX_DYNAMIC_ATTRIBUTES:
+                return resolved
+            key = str(raw_key).strip()
+            if not key or raw_value is None or raw_value == "":
+                continue
+            if not isinstance(raw_value, (str, bool, int, float)):
+                continue
+            value = raw_value
+            if isinstance(value, str):
+                value = value[:_MAX_DYNAMIC_ATTRIBUTE_LENGTH]
+            resolved[key[:_MAX_DYNAMIC_ATTRIBUTE_LENGTH]] = value
+    return resolved
+
 
 def _headroom_version() -> str:
     return get_version()
@@ -163,9 +225,31 @@ class HeadroomOtelMetrics:
             description="Output tokens returned by upstream providers.",
             unit="1",
         )
+        self._proxy_attempted_input_tokens = self._meter.create_counter(
+            "headroom.proxy.tokens.attempted_input",
+            description=("Input tokens Headroom attempted to optimize before compression."),
+            unit="1",
+        )
+        self._proxy_output_saved_tokens = self._meter.create_counter(
+            "headroom.proxy.tokens.output_saved",
+            description="Estimated output tokens avoided by Headroom optimization.",
+            unit="1",
+        )
+        self._proxy_savings_usd = self._meter.create_counter(
+            "headroom.proxy.savings.usd",
+            description=("Estimated savings in USD by distinct Headroom or provider-cache layer."),
+            unit="USD",
+        )
         self._proxy_saved_tokens = self._meter.create_counter(
             "headroom.proxy.tokens.saved",
-            description="Input tokens saved by Headroom compression.",
+            description=(
+                "Input tokens saved across Headroom compression and tool-schema deferral."
+            ),
+            unit="1",
+        )
+        self._proxy_tool_schema_saved_tokens = self._meter.create_counter(
+            "headroom.proxy.tokens.tool_schema_saved",
+            description="Input tokens saved by deferring tool schemas.",
             unit="1",
         )
         self._proxy_cache_read_tokens = self._meter.create_counter(
@@ -258,6 +342,21 @@ class HeadroomOtelMetrics:
             description="Waste tokens detected in compressed inputs.",
             unit="1",
         )
+        self._savings_attribution_events = self._meter.create_counter(
+            "headroom.savings.attribution.events",
+            description="Per-request savings attribution events.",
+            unit="1",
+        )
+        self._savings_attributed_tokens = self._meter.create_counter(
+            "headroom.savings.attributed.tokens",
+            description="Tokens attributed to a named savings source.",
+            unit="1",
+        )
+        self._savings_attributed_usd = self._meter.create_up_down_counter(
+            "headroom.savings.attributed.usd",
+            description="Attributed cost delta; negative values represent added cost.",
+            unit="USD",
+        )
 
         # Backing values updated by record_subscription_window()
         self._sub_5h_util_val: float = 0.0
@@ -330,7 +429,9 @@ class HeadroomOtelMetrics:
 
     @staticmethod
     def _attrs(**attrs: Any) -> dict[str, Any]:
-        filtered: dict[str, Any] = {}
+        # Dynamic request dimensions are deliberately lower precedence than
+        # canonical instrument dimensions (provider/model/source/etc.).
+        filtered = _dynamic_metric_attributes()
         for key, value in attrs.items():
             if value is None or value == "":
                 continue
@@ -346,6 +447,7 @@ class HeadroomOtelMetrics:
         output_tokens: int,
         tokens_saved: int,
         latency_ms: float,
+        tool_search_saved: int = 0,
         cached: bool = False,
         overhead_ms: float = 0.0,
         ttfb_ms: float = 0.0,
@@ -354,8 +456,21 @@ class HeadroomOtelMetrics:
         cache_write_5m_tokens: int = 0,
         cache_write_1h_tokens: int = 0,
         uncached_input_tokens: int = 0,
+        attempted_input_tokens: int = 0,
+        output_tokens_saved: int = 0,
+        savings_usd: Mapping[str, float] | None = None,
+        project: str | None = None,
+        client: str | None = None,
     ) -> None:
-        attrs = self._attrs(provider=provider, model=model, cached=cached)
+        attrs = self._attrs(
+            provider=provider,
+            model=model,
+            cached=cached,
+            **{
+                "headroom.project": project,
+                "headroom.client": client,
+            },
+        )
 
         self._proxy_requests.add(1, attrs)
         if cached:
@@ -363,7 +478,22 @@ class HeadroomOtelMetrics:
 
         self._proxy_input_tokens.add(max(input_tokens, 0), attrs)
         self._proxy_output_tokens.add(max(output_tokens, 0), attrs)
-        self._proxy_saved_tokens.add(max(tokens_saved, 0), attrs)
+        if attempted_input_tokens > 0:
+            self._proxy_attempted_input_tokens.add(attempted_input_tokens, attrs)
+        if output_tokens_saved > 0:
+            self._proxy_output_saved_tokens.add(output_tokens_saved, attrs)
+        for source, value in (savings_usd or {}).items():
+            amount = max(float(value or 0.0), 0.0)
+            if amount:
+                self._proxy_savings_usd.add(
+                    amount,
+                    {**attrs, "source": str(source)[:64], "estimated": True},
+                )
+        compression_saved = max(tokens_saved, 0)
+        tool_schema_saved = max(tool_search_saved, 0)
+        self._proxy_saved_tokens.add(compression_saved + tool_schema_saved, attrs)
+        if tool_schema_saved > 0:
+            self._proxy_tool_schema_saved_tokens.add(tool_schema_saved, attrs)
         self._proxy_latency.record(max(latency_ms, 0.0) / _MILLISECONDS_TO_SECONDS, attrs)
 
         if overhead_ms > 0:
@@ -390,6 +520,21 @@ class HeadroomOtelMetrics:
     def record_proxy_failed(self, *, provider: str | None = None, model: str | None = None) -> None:
         self._proxy_failed_requests.add(1, self._attrs(provider=provider, model=model))
 
+    def record_savings_attribution(self, items: list[dict[str, Any]]) -> None:
+        for item in items:
+            attrs = self._attrs(
+                source=str(item.get("source") or "other")[:64],
+                realized=bool(item.get("realized", True)),
+                estimated=bool(item.get("estimated", False)),
+            )
+            self._savings_attribution_events.add(1, attrs)
+            saved = max(0, int(item.get("tokens", 0) or 0))
+            if saved:
+                self._savings_attributed_tokens.add(saved, attrs)
+            cost = float(item.get("usd", 0.0) or 0.0)
+            if cost:
+                self._savings_attributed_usd.add(cost, attrs)
+
     def record_proxy_rate_limited(
         self,
         *,
diff --git a/headroom/onnx_runtime.py b/headroom/onnx_runtime.py
index aa3e7f7b2..8157c2202 100644
--- a/headroom/onnx_runtime.py
+++ b/headroom/onnx_runtime.py
@@ -13,6 +13,7 @@ logger = logging.getLogger(__name__)
 # Override for the CPU memory-arena default below: "1"/"true" forces the
 # arena ON, "0"/"false" forces it OFF, unset/"auto" uses the platform default.
 ONNX_CPU_ARENA_ENV = "HEADROOM_ONNX_CPU_ARENA"
+ONNX_ALLOW_SPINNING_ENV = "HEADROOM_ONNX_ALLOW_SPINNING"
 
 _TRUTHY = frozenset({"1", "true", "yes", "on"})
 _FALSY = frozenset({"0", "false", "no", "off"})
@@ -46,6 +47,22 @@ def cpu_arena_enabled() -> bool:
     return sys.platform == "win32"
 
 
+def onnx_thread_spinning_enabled() -> bool:
+    """Whether ONNX Runtime intra/inter-op thread pools may spin-wait when idle.
+
+    ORT's thread pools spin-wait on every core between inferences by default, so
+    a long-lived proxy that keeps compression/embedding models loaded pegs all
+    cores even while completely idle — the machine slows to a crawl after a
+    while (#2495). Default to blocking idle threads (spinning off). Set
+    ``HEADROOM_ONNX_ALLOW_SPINNING=1`` to restore ORT's spinning for peak
+    throughput on a dedicated/batch box.
+    """
+    override = _env_flag(ONNX_ALLOW_SPINNING_ENV)
+    if override is not None:
+        return override
+    return False
+
+
 # Pin model artifacts to immutable commit SHAs so a changed or compromised
 # upstream HuggingFace repo cannot be pulled silently (supply-chain integrity).
 # Repos not listed here fall back to the floating default ref. Set
@@ -159,6 +176,20 @@ def create_cpu_session_options(
     if inter_op_num_threads is not None:
         sess_options.inter_op_num_threads = inter_op_num_threads
 
+    if not onnx_thread_spinning_enabled():
+        # ORT's thread pools spin-wait on all cores between inferences by
+        # default, so idle-but-loaded models peg every core in a long-lived
+        # proxy (#2495). Make idle threads block instead. Best-effort: older ORT
+        # builds may not recognize a key.
+        for spin_key in (
+            "session.intra_op.allow_spinning",
+            "session.inter_op.allow_spinning",
+        ):
+            try:
+                sess_options.add_session_config_entry(spin_key, "0")
+            except Exception:
+                pass
+
     if not cpu_arena_enabled():
         if hasattr(sess_options, "enable_cpu_mem_arena"):
             sess_options.enable_cpu_mem_arena = False
diff --git a/headroom/paths.py b/headroom/paths.py
index 645d8b6fc..25e9e882a 100644
--- a/headroom/paths.py
+++ b/headroom/paths.py
@@ -342,6 +342,12 @@ def beacon_lock_path(port: int) -> Path:
     return workspace_dir() / f".beacon_lock_{int(port)}"
 
 
+def proxy_start_lock_path(port: int) -> Path:
+    """Return the per-port lock used to serialize wrap proxy startup."""
+
+    return workspace_dir() / f".proxy_start_{int(port)}.lock"
+
+
 # ---------------------------------------------------------------------------
 # Per-resource helpers -- config bucket
 # ---------------------------------------------------------------------------
@@ -432,6 +438,7 @@ __all__ = [
     "proxy_clients_dir",
     "deploy_root",
     "beacon_lock_path",
+    "proxy_start_lock_path",
     "models_config_path",
     "plugin_config_dir",
     "plugin_workspace_dir",
diff --git a/headroom/perf/analyzer.py b/headroom/perf/analyzer.py
index 4deec44ac..b296e59f6 100644
--- a/headroom/perf/analyzer.py
+++ b/headroom/perf/analyzer.py
@@ -134,6 +134,16 @@ def _parse_kv(kv_str: str) -> dict[str, str]:
     return result
 
 
+def _decode_perf_savings(value: str) -> list[dict[str, object]]:
+    # Local import keeps the analyzer usable against old logs/install layouts.
+    try:
+        from headroom.proxy.savings_attribution import decode
+
+        return decode(value)
+    except Exception:
+        return []
+
+
 @dataclass
 class PerfRecord:
     """A single parsed PERF log entry."""
@@ -156,6 +166,7 @@ class PerfRecord:
     tokens_out: int = 0
     ttfb_ms: float = 0.0
     stages: dict[str, float] = field(default_factory=dict)
+    savings_breakdown: list[dict[str, object]] = field(default_factory=list)
 
 
 @dataclass
@@ -353,6 +364,7 @@ def parse_log_files(last_n_hours: float = 168.0) -> PerfReport:
                                 tokens_after=int(kv.get("tok_after", 0)),
                                 tokens_saved=int(kv.get("tok_saved", 0)),
                                 tool_saved=int(kv.get("tool_saved", 0)),
+                                savings_breakdown=_decode_perf_savings(kv.get("savings", "none")),
                                 cache_read=int(kv.get("cache_read", 0)),
                                 cache_write=int(kv.get("cache_write", 0)),
                                 cache_hit_pct=int(kv.get("cache_hit_pct", 0)),
@@ -752,6 +764,7 @@ PERF_RECORD_FIELDS = [
     "tokens_out",
     "ttfb_ms",
     "stages",
+    "savings_breakdown",
 ]
 
 
@@ -1001,7 +1014,9 @@ def build_perf_summary(report: PerfReport) -> dict:
     for model, recs in sorted(by_model_groups.items()):
         m_before = sum(r.tokens_before for r in recs)
         m_after = sum(r.tokens_after for r in recs)
-        m_saved = sum(r.tokens_saved for r in recs)
+        m_message_saved = sum(r.tokens_saved for r in recs)
+        m_tool_saved = sum(r.tool_saved for r in recs)
+        m_saved = m_message_saved + m_tool_saved
         by_model.append(
             {
                 "model": model,
@@ -1009,7 +1024,9 @@ def build_perf_summary(report: PerfReport) -> dict:
                 "tokens_before": m_before,
                 "tokens_after": m_after,
                 "tokens_saved": m_saved,
-                "savings_pct": _pct(m_saved, m_before),
+                "message_tokens_saved": m_message_saved,
+                "tool_tokens_saved": m_tool_saved,
+                "savings_pct": _pct(m_saved, m_before + m_tool_saved),
                 "list_price_per_mtok": _get_list_price(model),
             }
         )
@@ -1033,6 +1050,37 @@ def build_perf_summary(report: PerfReport) -> dict:
             }
         )
 
+    by_source_groups: dict[tuple[str, bool], dict[str, int | float | str | bool]] = {}
+    for record in records:
+        for item in record.savings_breakdown:
+            source = str(item.get("source") or "other")
+            realized = bool(item.get("realized", True))
+            key = (source, realized)
+            row = by_source_groups.setdefault(
+                key,
+                {
+                    "source": source,
+                    "realized": realized,
+                    "events": 0,
+                    "tokens": 0,
+                    "usd": 0.0,
+                },
+            )
+            row["events"] = int(row["events"]) + 1
+            raw_tokens = item.get("tokens", 0)
+            raw_usd = item.get("usd", 0.0)
+            tokens = int(raw_tokens) if isinstance(raw_tokens, (str, int, float)) else 0
+            usd = float(raw_usd) if isinstance(raw_usd, (str, int, float)) else 0.0
+            row["tokens"] = int(row["tokens"]) + max(0, tokens)
+            row["usd"] = round(
+                float(row["usd"]) + usd,
+                12,
+            )
+    by_source = sorted(
+        by_source_groups.values(),
+        key=lambda row: (-int(row["tokens"]), str(row["source"])),
+    )
+
     return {
         "window_hours": report.requested_hours,
         "actual_window": {
@@ -1056,6 +1104,7 @@ def build_perf_summary(report: PerfReport) -> dict:
         "cache_hit_pct": cache_hit_pct,
         "by_model": by_model,
         "by_transform": by_transform,
+        "by_source": by_source,
         "overhead": build_overhead_summary(report),
         "throughput": calculate_throughput(report),
         "log_files_read": report.log_files_read,
diff --git a/headroom/pricing/litellm_model_resolution.py b/headroom/pricing/litellm_model_resolution.py
index c006f64d9..0a9242001 100644
--- a/headroom/pricing/litellm_model_resolution.py
+++ b/headroom/pricing/litellm_model_resolution.py
@@ -2,9 +2,15 @@
 
 from __future__ import annotations
 
+import re
 from collections.abc import Callable
 from dataclasses import dataclass
 
+# Vertex AI appends @YYYYMMDD version tags to model names at runtime
+# (e.g. "claude-haiku-4-5@20251001"). LiteLLM's database stores bare
+# names without version suffixes, so we strip the suffix before lookup.
+_VERTEX_VERSION_SUFFIX_RE = re.compile(r"@\d{8}$")
+
 
 @dataclass(frozen=True, slots=True)
 class LiteLLMModelPrefixRule:
@@ -55,16 +61,40 @@ PRICE_LOOKUP_PROVIDER_PREFIXES: tuple[str, ...] = (
 )
 
 
+def _strip_vertex_version_suffix(model: str) -> str:
+    """Strip Vertex @YYYYMMDD version suffix if present."""
+    return _VERTEX_VERSION_SUFFIX_RE.sub("", model)
+
+
 def resolution_candidates(model: str) -> tuple[str, ...]:
     """Return ordered LiteLLM keys to try for cost-per-token resolution."""
     candidates = [model]
-    candidates.extend(
-        candidate
-        for rule in MODEL_PREFIX_RULES
-        for candidate in (rule.candidate_for(model),)
-        if candidate is not None
-    )
-    alias = MODEL_ALIASES.get(model)
+
+    # If the model has a Vertex @YYYYMMDD version suffix, also try the bare
+    # name. Vertex appends these at runtime; LiteLLM stores bare names only.
+    bare = _strip_vertex_version_suffix(model)
+    is_vertex_versioned = bare != model
+    if is_vertex_versioned:
+        candidates.append(bare)
+
+    # Apply prefix rules to both the original and bare name so that e.g.
+    # "anthropic/claude-haiku-4-5" is tried after "claude-haiku-4-5".
+    for m in dict.fromkeys([model, bare]):
+        candidates.extend(
+            candidate
+            for rule in MODEL_PREFIX_RULES
+            for candidate in (rule.candidate_for(m),)
+            if candidate is not None
+        )
+
+    # Only add vertex_ai/ candidates for models with @YYYYMMDD suffix —
+    # these are known Vertex-routed models. Non-versioned models should not
+    # get vertex_ai/ candidates to avoid matching wrong pricing tier.
+    if is_vertex_versioned:
+        for m in dict.fromkeys([model, bare]):
+            candidates.append(f"vertex_ai/{m}")
+
+    alias = MODEL_ALIASES.get(model) or MODEL_ALIASES.get(bare)
     if alias:
         candidates.append(alias)
     return tuple(dict.fromkeys(candidates))
@@ -86,11 +116,27 @@ def unwrapped_model_forms(model: str) -> tuple[str, ...]:
 
 def pricing_lookup_candidates(model: str) -> tuple[str, ...]:
     """Return ordered LiteLLM model_cost keys to try for pricing lookup."""
+    bare = _strip_vertex_version_suffix(model)
+    is_vertex_versioned = bare != model
+
     candidates = [model]
-    candidates.extend(f"{prefix}{model}" for prefix in PRICE_LOOKUP_PROVIDER_PREFIXES)
+    if is_vertex_versioned:
+        candidates.append(bare)
+
+    # Try all provider prefixes for both the original and bare name.
+    for m in dict.fromkeys([model, bare]):
+        candidates.extend(f"{prefix}{m}" for prefix in PRICE_LOOKUP_PROVIDER_PREFIXES)
+
     # Unwrapped forms come after the prefixed ones so existing precedence is
     # unchanged for names that already resolved.
-    candidates.extend(unwrapped_model_forms(model))
+    for m in dict.fromkeys([model, bare]):
+        candidates.extend(unwrapped_model_forms(m))
+
+    # Only add vertex_ai/ candidates for models with @YYYYMMDD suffix.
+    if is_vertex_versioned:
+        for m in dict.fromkeys([model, bare]):
+            candidates.append(f"vertex_ai/{m}")
+
     candidates.extend(
         alias for candidate in tuple(candidates) if (alias := MODEL_ALIASES.get(candidate))
     )
diff --git a/headroom/providers/anthropic.py b/headroom/providers/anthropic.py
index 5cac19a06..b16251621 100644
--- a/headroom/providers/anthropic.py
+++ b/headroom/providers/anthropic.py
@@ -24,7 +24,11 @@ import warnings
 from typing import Any, cast
 
 from headroom import paths as _paths
-from headroom.tokenizers.base import coerce_countable_text, count_content_blocks
+from headroom.tokenizers.base import (
+    TokenCountCache,
+    coerce_countable_text,
+    count_content_blocks,
+)
 
 from .base import Provider, TokenCounter
 
@@ -309,6 +313,7 @@ class AnthropicTokenCounter(TokenCounter):
         self.model = model
         self._client = client
         self._encoding: Any = None
+        self._count_cache = TokenCountCache()
         self._use_api = client is not None
 
         if not self._use_api and warn and not _FALLBACK_WARNING_SHOWN:
@@ -351,6 +356,14 @@ class AnthropicTokenCounter(TokenCounter):
         if not text:
             return 0
 
+        cached = self._count_cache.get(text)
+        if cached is not None:
+            return cached
+        count = self._count_text_uncached(text)
+        self._count_cache.put(text, count)
+        return count
+
+    def _count_text_uncached(self, text: str) -> int:
         if self._encoding:
             # tiktoken with ~1.1x multiplier for Claude
             try:
@@ -407,13 +420,14 @@ class AnthropicTokenCounter(TokenCounter):
             # str(block) catch-all would produce.
             tokens += count_content_blocks(content, self.count_text)
 
-        # OpenAI format tool calls
-        if "tool_calls" in message:
-            for tool_call in message.get("tool_calls", []):
-                if isinstance(tool_call, dict):
-                    func = tool_call.get("function") or {}
-                    tokens += self.count_text(coerce_countable_text(func.get("name")))
-                    tokens += self.count_text(coerce_countable_text(func.get("arguments")))
+        # OpenAI format tool calls. Guard the value, not just the key: an
+        # OpenAI-format assistant message often carries `tool_calls: null` on a
+        # no-tool turn, and `for ... in None` would raise TypeError.
+        for tool_call in message.get("tool_calls") or []:
+            if isinstance(tool_call, dict):
+                func = tool_call.get("function") or {}
+                tokens += self.count_text(coerce_countable_text(func.get("name")))
+                tokens += self.count_text(coerce_countable_text(func.get("arguments")))
 
         return tokens
 
diff --git a/headroom/providers/claude/__init__.py b/headroom/providers/claude/__init__.py
index 9fad1fbfb..e44238ebc 100644
--- a/headroom/providers/claude/__init__.py
+++ b/headroom/providers/claude/__init__.py
@@ -1,6 +1,7 @@
 """Claude-specific provider helpers."""
 
 from .runtime import (
+    CLAUDE_AUTH_KEYS,
     DEFAULT_API_URL,
     REMOTE_CONTROL_BASE_URL_ENV,
     REMOTE_CONTROL_GATED_MIN_VERSION,
@@ -8,6 +9,8 @@ from .runtime import (
     REMOTE_CONTROL_SIBLING_GATE_NOTE,
     TOOL_SEARCH_DEFAULT,
     TOOL_SEARCH_ENV,
+    claude_auth_conflict_message,
+    claude_auth_conflict_sources,
     detect_claude_code_version,
     is_custom_anthropic_base_url,
     parse_claude_code_version,
@@ -25,6 +28,7 @@ from .vscode import (
 )
 
 __all__ = [
+    "CLAUDE_AUTH_KEYS",
     "claude_user_settings_path",
     "configure_vscode_claude_settings",
     "remove_vscode_claude_settings",
@@ -36,6 +40,8 @@ __all__ = [
     "REMOTE_CONTROL_SIBLING_GATE_NOTE",
     "TOOL_SEARCH_DEFAULT",
     "TOOL_SEARCH_ENV",
+    "claude_auth_conflict_message",
+    "claude_auth_conflict_sources",
     "detect_claude_code_version",
     "is_custom_anthropic_base_url",
     "parse_claude_code_version",
diff --git a/headroom/providers/claude/runtime.py b/headroom/providers/claude/runtime.py
index 023357d01..1c7643606 100644
--- a/headroom/providers/claude/runtime.py
+++ b/headroom/providers/claude/runtime.py
@@ -15,8 +15,10 @@ DEFAULT_API_URL = "https://api.anthropic.com"
 # single source of truth shared by `wrap`, `init`, and `install`.
 TOOL_SEARCH_ENV = "ENABLE_TOOL_SEARCH"
 TOOL_SEARCH_DEFAULT = "true"
+TOOL_SEARCH_FOUNDRY_DEFAULT = "false"
 REMOTE_CONTROL_BASE_URL_ENV = "ANTHROPIC_BASE_URL"
 REMOTE_CONTROL_FEATURE = "Remote Control"
+CLAUDE_AUTH_KEYS = ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN")
 
 # GH #1779: Claude Code v2.1.196 added a client-side eligibility check that
 # DISABLES first-party Remote Control (`/remote-control` / `/rc`, which mirrors a
@@ -185,6 +187,46 @@ def remote_control_applies_to_auth(environ: Mapping[str, object]) -> bool:
     )
 
 
+def claude_auth_conflict_sources(
+    *layers: tuple[str, Mapping[str, object]],
+) -> dict[str, str] | None:
+    """Return source labels when both mutually exclusive Claude auth keys are effective.
+
+    Layers are ordered from lowest to highest precedence. Empty values clear an
+    inherited value, matching environment overlay semantics. Credential values
+    are deliberately never returned so callers cannot leak them in diagnostics.
+    """
+    effective: dict[str, str] = {}
+    sources: dict[str, str] = {}
+    for source, values in layers:
+        for key in CLAUDE_AUTH_KEYS:
+            if key not in values:
+                continue
+            value = str(values.get(key) or "").strip()
+            if value:
+                effective[key] = value
+                sources[key] = source
+            else:
+                effective.pop(key, None)
+                sources.pop(key, None)
+    if all(key in effective for key in CLAUDE_AUTH_KEYS):
+        return {key: sources[key] for key in CLAUDE_AUTH_KEYS}
+    return None
+
+
+def claude_auth_conflict_message(sources: Mapping[str, str]) -> str:
+    """Format a value-free remediation for contradictory Claude credentials."""
+    api_source = sources.get("ANTHROPIC_API_KEY", "effective configuration")
+    token_source = sources.get("ANTHROPIC_AUTH_TOKEN", "effective configuration")
+    return (
+        "Claude Code has both ANTHROPIC_API_KEY "
+        f"({api_source}) and ANTHROPIC_AUTH_TOKEN ({token_source}) set. "
+        "Claude rejects this ambiguous auth state before Headroom can proxy a request. "
+        "Keep ANTHROPIC_API_KEY for API-key billing, or keep ANTHROPIC_AUTH_TOKEN "
+        "for token/gateway auth; remove the other key from the named source and retry."
+    )
+
+
 def parse_claude_code_version(text: str | None) -> tuple[int, int, int] | None:
     """Parse a ``MAJOR.MINOR.PATCH`` version out of ``claude --version`` output.
 
diff --git a/headroom/providers/claude/vscode.py b/headroom/providers/claude/vscode.py
index 8f7e62486..79f9f3889 100644
--- a/headroom/providers/claude/vscode.py
+++ b/headroom/providers/claude/vscode.py
@@ -89,7 +89,11 @@ def configure_vscode_claude_settings(path: Path, proxy_url: str) -> str:
     payload = _read_settings(path)
     env = _env_map(payload, path)
     state_path = _state_path(path)
-    managed = {_BASE_URL_KEY: proxy_url, _TOOL_SEARCH_KEY: "true"}
+    # Claude Code's VS Code webview cannot render the server_tool_use /
+    # tool_search_tool_result blocks emitted by deferred tool search (#2028).
+    # Keep it disabled for this surface; the standalone CLI retains its own
+    # configurable/default-on policy.
+    managed = {_BASE_URL_KEY: proxy_url, _TOOL_SEARCH_KEY: "false"}
 
     if state_path.exists():
         state = _read_object(state_path, label="Headroom state")
diff --git a/headroom/providers/copilot/vscode.py b/headroom/providers/copilot/vscode.py
index 2a0fbc85b..354a4efe5 100644
--- a/headroom/providers/copilot/vscode.py
+++ b/headroom/providers/copilot/vscode.py
@@ -17,6 +17,7 @@ from headroom.proxy.project_context import with_project_prefix
 _MARKER_START = "// --- Headroom Copilot proxy ---"
 _MARKER_END = "// --- end Headroom Copilot proxy ---"
 _PROXY_KEY = "github.copilot.advanced.debug.overrideProxyUrl"
+_CAPI_KEY = "github.copilot.advanced.debug.overrideCapiUrl"
 _AUTH_KEY = "github.copilot.advanced.debug.overrideAuthType"
 
 
@@ -118,6 +119,7 @@ def _managed_block(proxy_url: str, *, owns_preceding_comma: bool, line_sep: str)
     return (
         f"\t{marker}{line_sep}"
         f"\t{json.dumps(_PROXY_KEY)}: {json.dumps(proxy_url)},{line_sep}"
+        f"\t{json.dumps(_CAPI_KEY)}: {json.dumps(proxy_url)},{line_sep}"
         f'\t{json.dumps(_AUTH_KEY)}: "token"{line_sep}'
         f"\t{_MARKER_END}"
     )
@@ -161,7 +163,7 @@ def configure_vscode_proxy_settings(path: Path, proxy_url: str) -> str:
     if had_managed_block:
         remove_vscode_proxy_settings(path)
         raw = _read_settings(path)
-    elif _PROXY_KEY in raw or _AUTH_KEY in raw:
+    elif _PROXY_KEY in raw or _CAPI_KEY in raw or _AUTH_KEY in raw:
         raise click.ClickException(
             f"{path} already configures a Copilot endpoint override outside Headroom's "
             "managed block; refusing to replace it. Remove it or use --no-configure."
diff --git a/headroom/providers/openai.py b/headroom/providers/openai.py
index 5b41bc8e1..891b13559 100644
--- a/headroom/providers/openai.py
+++ b/headroom/providers/openai.py
@@ -32,12 +32,7 @@ _UNKNOWN_MODEL_WARNINGS: set[str] = set()
 # Models whose price came from the built-in table rather than LiteLLM.
 _PRICING_FALLBACK_WARNINGS: set[str] = set()
 
-try:
-    import tiktoken
-
-    TIKTOKEN_AVAILABLE = True
-except ImportError:
-    TIKTOKEN_AVAILABLE = False
+TIKTOKEN_AVAILABLE = importlib.util.find_spec("tiktoken") is not None
 
 LITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None
 
@@ -285,12 +280,21 @@ def _check_pricing_staleness() -> str | None:
 
 @lru_cache(maxsize=8)
 def _get_encoding(encoding_name: str) -> Any:
-    """Get tiktoken encoding, cached."""
+    """Get tiktoken encoding, cached.
+
+    Routes through the bounded loader so a stalled vocab download raises
+    :class:`~headroom.tokenizers.tiktoken_counter.TiktokenLoadError` after a
+    timeout instead of hanging the caller indefinitely — ``tiktoken`` fetches
+    vocabularies with no network timeout, and this runs on whatever thread
+    first counts tokens for a model, including proxy startup (GH #956).
+    """
     if not TIKTOKEN_AVAILABLE:
         raise RuntimeError(
             "tiktoken is required for OpenAI provider. Install with: pip install tiktoken"
         )
-    return tiktoken.get_encoding(encoding_name)
+    from ..tokenizers.tiktoken_counter import load_encoding
+
+    return load_encoding(encoding_name)
 
 
 def _lookup_encoding_name(model: str, custom_encodings: dict[str, str] | None = None) -> str | None:
@@ -343,6 +347,8 @@ class OpenAITokenCounter:
 
         Raises:
             RuntimeError: If tiktoken is not installed.
+            TiktokenLoadError: If the encoding's vocabulary can't be loaded
+                within the bounded timeout (e.g. stalled download).
         """
         self.model = model
         encoding_name = _get_encoding_name_for_model(model, custom_encodings)
@@ -507,7 +513,9 @@ class OpenAIProvider(Provider):
         the proxy pipeline resolves its tokenizer through this provider while
         handlers resolve through the tokenizer registry, the two disagree about
         the same request — savings become a difference of two rulers. Defer to
-        the registry so each model has exactly one tokenizer.
+        the registry so each model has exactly one tokenizer. For OpenAI models,
+        fall back to estimation when a vocabulary cannot load within the bounded
+        timeout; the cached fallback prevents subsequent requests from blocking.
         """
         if model not in self._token_counters:
             if _lookup_encoding_name(model, self._encodings) is None:
@@ -515,9 +523,19 @@ class OpenAIProvider(Provider):
 
                 self._token_counters[model] = cast(Any, get_tokenizer(model))
             else:
-                self._token_counters[model] = OpenAITokenCounter(
-                    model=model, custom_encodings=self._encodings
-                )
+                from ..tokenizers.tiktoken_counter import TiktokenLoadError
+
+                try:
+                    self._token_counters[model] = OpenAITokenCounter(
+                        model=model, custom_encodings=self._encodings
+                    )
+                except TiktokenLoadError as exc:
+                    logger.warning(
+                        "tiktoken unavailable for %s (%s); using estimation.", model, exc
+                    )
+                    from ..tokenizers.estimator import EstimatingTokenCounter
+
+                    self._token_counters[model] = EstimatingTokenCounter()
         return self._token_counters[model]
 
     def get_context_limit(self, model: str) -> int:
diff --git a/headroom/providers/openai_responses.py b/headroom/providers/openai_responses.py
index e09adc42d..2e10b030f 100644
--- a/headroom/providers/openai_responses.py
+++ b/headroom/providers/openai_responses.py
@@ -32,9 +32,19 @@ OPENAI_RESPONSES_ROOT_PATHS: tuple[str, ...] = (
     "/v1/codex/responses",
     "/backend-api/responses",
     "/backend-api/codex/responses",
+    # Copilot Chat derives this unprefixed path from overrideCapiUrl. Without an
+    # explicit root route it falls through to uncompressed generic passthrough.
+    "/responses",
 )
 
-OPENAI_RESPONSES_WEBSOCKET_PATHS: tuple[str, ...] = OPENAI_RESPONSES_ROOT_PATHS
+# The Codex websocket relay speaks a different protocol; do not register the
+# Copilot HTTP alias as a websocket route without separate wire validation.
+OPENAI_RESPONSES_WEBSOCKET_PATHS: tuple[str, ...] = (
+    "/v1/responses",
+    "/v1/codex/responses",
+    "/backend-api/responses",
+    "/backend-api/codex/responses",
+)
 
 OPENAI_RESPONSES_SUBPATH_ROUTES: tuple[OpenAIResponsesSubpathRoute, ...] = (
     OpenAIResponsesSubpathRoute("/v1/responses/{sub_path:path}", ("GET", "POST", "DELETE")),
diff --git a/headroom/providers/opencode/config.py b/headroom/providers/opencode/config.py
index 6c64544fe..08a6f5748 100644
--- a/headroom/providers/opencode/config.py
+++ b/headroom/providers/opencode/config.py
@@ -31,24 +31,18 @@ _MCP_BLOCK_RE = re.compile(
 )
 HEADROOM_OPENCODE_PLUGIN = "headroom-opencode"
 
-# Models exposed by the injected `headroom` provider. OpenCode only resolves
-# `headroom/<id>` for ids listed in the provider's `models` map, so an empty
-# map means every documented `headroom/*` model fails with "Model not found".
-# Keep in sync with DEFAULT_MODELS in plugins/opencode/src/provider.ts and the
-# table in plugins/opencode/README.md.
+# Models exposed by the injected `headroom` provider. This provider uses
+# ``@ai-sdk/openai-compatible`` and the proxy's ``/v1/chat/completions`` path,
+# which is routed to the configured OpenAI upstream. Do not advertise Claude
+# models here: OpenCode would send them through the OpenAI endpoint and report
+# an ``invalid_api_key`` error instead of reaching Anthropic. Claude models are
+# available through OpenCode's native ``anthropic`` provider, whose base URL is
+# also redirected to Headroom by ``build_opencode_config_content``.
+#
+# OpenCode only resolves ``headroom/<id>`` for ids listed in this map, so an
+# empty map means every documented ``headroom/*`` model fails with "Model not
+# found".
 HEADROOM_OPENCODE_MODELS: dict[str, Any] = {
-    "claude-sonnet-4-6": {
-        "name": "Claude Sonnet 4.6",
-        "limit": {"context": 200000, "output": 16384},
-    },
-    "claude-opus-4-6": {
-        "name": "Claude Opus 4.6",
-        "limit": {"context": 200000, "output": 16384},
-    },
-    "claude-haiku-4-5-20251001": {
-        "name": "Claude Haiku 4.5",
-        "limit": {"context": 200000, "output": 8192},
-    },
     "gpt-4o": {
         "name": "GPT-4o",
         "limit": {"context": 128000, "output": 16384},
diff --git a/headroom/providers/opencode/hook-shim/handler.js b/headroom/providers/opencode/hook-shim/handler.js
new file mode 100644
index 000000000..1dbfba992
--- /dev/null
+++ b/headroom/providers/opencode/hook-shim/handler.js
@@ -0,0 +1,390 @@
+// src/transport.ts
+import { createRequire, syncBuiltinESMExports } from "module";
+var nodeRequire = createRequire(import.meta.url);
+var http = nodeRequire("node:http");
+var https = nodeRequire("node:https");
+var http2 = nodeRequire("node:http2");
+var childProcess = nodeRequire("node:child_process");
+var fs = nodeRequire("node:fs");
+var BASE_URL_HEADER = "x-headroom-base-url";
+var ORIGINAL_PATH_HEADER = "x-headroom-original-path";
+var PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
+var STATE_KEY = /* @__PURE__ */ Symbol.for("headroom.opencode.transport");
+function getState() {
+  return globalThis[STATE_KEY];
+}
+function setState(state) {
+  globalThis[STATE_KEY] = state;
+}
+function shimImportSpecifier() {
+  const shim = new URL("../hook-shim/handler.js", import.meta.url);
+  return fs.existsSync(shim) ? shim.href : void 0;
+}
+function withNodeImportOption(existing, shim) {
+  const parts = existing?.trim() ? existing.trim().split(/\s+/) : [];
+  const alreadyPresent = parts.some((part, index) => {
+    return part === `--import=${shim}` || part === "--import" && parts[index + 1] === shim;
+  });
+  if (!alreadyPresent) {
+    parts.push(`--import=${shim}`);
+  }
+  return parts.join(" ");
+}
+function withShimEnv(env, proxyUrl2) {
+  const nextEnv = { ...env ?? process.env };
+  nextEnv[PROXY_ENV] = proxyUrl2;
+  const shim = shimImportSpecifier();
+  if (shim) {
+    nextEnv.NODE_OPTIONS = withNodeImportOption(nextEnv.NODE_OPTIONS, shim);
+  }
+  return nextEnv;
+}
+function installProcessEnv(proxyUrl2) {
+  process.env[PROXY_ENV] = proxyUrl2;
+  const shim = shimImportSpecifier();
+  if (shim) {
+    process.env.NODE_OPTIONS = withNodeImportOption(process.env.NODE_OPTIONS, shim);
+  }
+}
+function isOptions(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && !(value instanceof URL);
+}
+function injectOptionsEnv(args, optionIndex, proxyUrl2) {
+  const nextArgs = [...args];
+  const callback = typeof nextArgs.at(-1) === "function" ? nextArgs.pop() : void 0;
+  const existing = isOptions(nextArgs[optionIndex]) ? { ...nextArgs[optionIndex] } : {};
+  existing.env = withShimEnv(existing.env, proxyUrl2);
+  if (isOptions(nextArgs[optionIndex])) {
+    nextArgs[optionIndex] = existing;
+  } else {
+    nextArgs.splice(optionIndex, 0, existing);
+  }
+  if (callback) {
+    nextArgs.push(callback);
+  }
+  return nextArgs;
+}
+function wrapSpawn(originalSpawn) {
+  return function headroomSpawn(...args) {
+    const state = getState();
+    if (!state) {
+      return Reflect.apply(originalSpawn, this, args);
+    }
+    const optionIndex = Array.isArray(args[1]) ? 2 : 1;
+    return Reflect.apply(originalSpawn, this, injectOptionsEnv(args, optionIndex, state.proxyUrl));
+  };
+}
+function wrapExec(originalExec) {
+  return function headroomExec(...args) {
+    const state = getState();
+    if (!state) {
+      return Reflect.apply(originalExec, this, args);
+    }
+    return Reflect.apply(originalExec, this, injectOptionsEnv(args, 1, state.proxyUrl));
+  };
+}
+function wrapExecFile(originalExecFile) {
+  return function headroomExecFile(...args) {
+    const state = getState();
+    if (!state) {
+      return Reflect.apply(originalExecFile, this, args);
+    }
+    const optionIndex = Array.isArray(args[1]) ? 2 : 1;
+    return Reflect.apply(originalExecFile, this, injectOptionsEnv(args, optionIndex, state.proxyUrl));
+  };
+}
+function wrapFork(originalFork) {
+  return function headroomFork(...args) {
+    const state = getState();
+    if (!state) {
+      return Reflect.apply(originalFork, this, args);
+    }
+    const optionIndex = Array.isArray(args[1]) ? 2 : 1;
+    return Reflect.apply(originalFork, this, injectOptionsEnv(args, optionIndex, state.proxyUrl));
+  };
+}
+function normalizeProxyUrl(proxyUrl2) {
+  return new URL(proxyUrl2);
+}
+function isLoopback(hostname) {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+function shouldRoute(url, proxy) {
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return false;
+  }
+  if (isLoopback(url.hostname)) {
+    return false;
+  }
+  if (url.origin === proxy.origin) {
+    return false;
+  }
+  return true;
+}
+function routedUrl(upstream, proxy) {
+  return new URL(`${upstream.pathname}${upstream.search}`, proxy.origin);
+}
+function normalizedOpenAiProxyPath(pathname) {
+  if (pathname.endsWith("/chat/completions")) {
+    return "/v1/chat/completions";
+  }
+  if (pathname.endsWith("/responses")) {
+    return "/v1/responses";
+  }
+  return void 0;
+}
+function routedUrlForOpenCode(upstream, proxy) {
+  const normalizedPath = normalizedOpenAiProxyPath(upstream.pathname);
+  if (!normalizedPath) {
+    return {
+      url: routedUrl(upstream, proxy),
+      originalPath: void 0
+    };
+  }
+  return {
+    url: new URL(`${normalizedPath}${upstream.search}`, proxy.origin),
+    originalPath: upstream.pathname
+  };
+}
+function requestUrl(input) {
+  if (input instanceof Request) {
+    return new URL(input.url);
+  }
+  if (input instanceof URL) {
+    return input;
+  }
+  return new URL(String(input));
+}
+function mergeFetchHeaders(input, init, upstream, originalPath = void 0) {
+  const headers = new Headers(input instanceof Request ? input.headers : void 0);
+  if (init?.headers) {
+    new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+  }
+  if (upstream) {
+    headers.set(BASE_URL_HEADER, upstream.origin);
+    headers.delete("host");
+  }
+  if (originalPath) {
+    headers.set(ORIGINAL_PATH_HEADER, originalPath);
+  }
+  return headers;
+}
+function withRoutedFetchInput(input, init, proxy) {
+  const upstream = requestUrl(input);
+  if (!shouldRoute(upstream, proxy)) {
+    return [input, init];
+  }
+  const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
+  const nextInit = {
+    ...init,
+    headers: mergeFetchHeaders(input, init, upstream, originalPath)
+  };
+  if (input instanceof Request) {
+    return [new Request(nextUrl, input), nextInit];
+  }
+  return [nextUrl, nextInit];
+}
+function splitNodeArgs(args) {
+  const callback = typeof args.at(-1) === "function" ? args.at(-1) : void 0;
+  const withoutCallback = callback ? args.slice(0, -1) : args;
+  const [first, second] = withoutCallback;
+  const options = typeof second === "object" && second !== null ? { ...second } : {};
+  if (first instanceof URL) {
+    return { url: first, options, callback };
+  }
+  if (typeof first === "string") {
+    try {
+      return { url: new URL(first), options, callback };
+    } catch {
+      return { options, callback };
+    }
+  }
+  if (typeof first === "object" && first !== null) {
+    const requestOptions = { ...first, ...options };
+    return { url: urlFromRequestOptions(requestOptions), options: requestOptions, callback };
+  }
+  return { options, callback };
+}
+function urlFromRequestOptions(options) {
+  const protocol = String(options.protocol ?? "http:");
+  if (protocol !== "http:" && protocol !== "https:") {
+    return void 0;
+  }
+  const hostValue = options.hostname ?? options.host;
+  if (!hostValue) {
+    return void 0;
+  }
+  const hostname = String(hostValue).replace(/:\d+$/, "");
+  const port = options.port ? `:${String(options.port)}` : "";
+  const path = String(options.path ?? "/");
+  try {
+    return new URL(`${protocol}//${hostname}${port}${path}`);
+  } catch {
+    return void 0;
+  }
+}
+function headersForNodeRequest(options, upstream, originalPath) {
+  const headers = new Headers(options.headers);
+  headers.set(BASE_URL_HEADER, upstream.origin);
+  if (originalPath) {
+    headers.set(ORIGINAL_PATH_HEADER, originalPath);
+  }
+  headers.delete("host");
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
+function routedNodeOptions(parts, proxy) {
+  if (!parts.url || !shouldRoute(parts.url, proxy)) {
+    return void 0;
+  }
+  const { url: nextUrl, originalPath } = routedUrlForOpenCode(parts.url, proxy);
+  const {
+    agent: _agent,
+    auth: _auth,
+    createConnection: _createConnection,
+    defaultPort: _defaultPort,
+    family: _family,
+    headers: _headers,
+    host: _host,
+    hostname: _hostname,
+    href: _href,
+    lookup: _lookup,
+    path: _path,
+    pathname: _pathname,
+    port: _port,
+    protocol: _protocol,
+    search: _search,
+    servername: _servername,
+    setHost: _setHost,
+    ...rest
+  } = parts.options;
+  return {
+    ...rest,
+    protocol: nextUrl.protocol,
+    hostname: nextUrl.hostname,
+    port: nextUrl.port || void 0,
+    path: `${nextUrl.pathname}${nextUrl.search}`,
+    headers: headersForNodeRequest(parts.options, parts.url, originalPath)
+  };
+}
+function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest) {
+  return function headroomRequest(...args) {
+    const state = getState();
+    if (!state) {
+      return Reflect.apply(originalRequest, this, args);
+    }
+    const proxy = normalizeProxyUrl(state.proxyUrl);
+    const parts = splitNodeArgs(args);
+    const nextOptions = routedNodeOptions(parts, proxy);
+    if (!nextOptions) {
+      return Reflect.apply(originalRequest, this, args);
+    }
+    const targetRequest = proxy.protocol === "https:" ? originalHttpsRequest : originalHttpRequest;
+    const nextArgs = parts.callback ? [nextOptions, parts.callback] : [nextOptions];
+    return Reflect.apply(targetRequest, this, nextArgs);
+  };
+}
+function wrapGet(request) {
+  return function headroomGet(...args) {
+    const req = Reflect.apply(request, this, args);
+    req.end();
+    return req;
+  };
+}
+function wrapHttp2Connect(originalConnect) {
+  return function headroomHttp2Connect(authority, ...args) {
+    const state = getState();
+    if (state) {
+      const proxy = normalizeProxyUrl(state.proxyUrl);
+      const upstream = authority instanceof URL ? authority : new URL(String(authority));
+      if (shouldRoute(upstream, proxy)) {
+        throw new Error(
+          `Headroom OpenCode wrap blocked direct HTTP/2 connection to ${upstream.origin}. Use fetch, http, or https so traffic can be routed through Headroom.`
+        );
+      }
+    }
+    return Reflect.apply(originalConnect, this, [authority, ...args]);
+  };
+}
+function installHeadroomTransport(options) {
+  const existing = getState();
+  if (existing) {
+    existing.refs += 1;
+    existing.proxyUrl = options.proxyUrl;
+    existing.debug = Boolean(options.debug);
+    installProcessEnv(options.proxyUrl);
+    return () => uninstallHeadroomTransport();
+  }
+  const state = {
+    refs: 1,
+    proxyUrl: options.proxyUrl,
+    debug: Boolean(options.debug),
+    originalFetch: globalThis.fetch,
+    originalHttpRequest: http.request,
+    originalHttpGet: http.get,
+    originalHttpsRequest: https.request,
+    originalHttpsGet: https.get,
+    originalHttp2Connect: http2.connect,
+    originalChildSpawn: childProcess.spawn,
+    originalChildExec: childProcess.exec,
+    originalChildExecFile: childProcess.execFile,
+    originalChildFork: childProcess.fork
+  };
+  setState(state);
+  installProcessEnv(options.proxyUrl);
+  globalThis.fetch = async (...args) => {
+    const current = getState();
+    if (!current) {
+      return state.originalFetch(...args);
+    }
+    const proxy = normalizeProxyUrl(current.proxyUrl);
+    const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy);
+    return state.originalFetch(nextInput, nextInit);
+  };
+  http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest);
+  https.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpsRequest);
+  http.get = wrapGet(http.request);
+  https.get = wrapGet(https.request);
+  http2.connect = wrapHttp2Connect(state.originalHttp2Connect);
+  childProcess.spawn = wrapSpawn(state.originalChildSpawn);
+  childProcess.exec = wrapExec(state.originalChildExec);
+  childProcess.execFile = wrapExecFile(state.originalChildExecFile);
+  childProcess.fork = wrapFork(state.originalChildFork);
+  syncBuiltinESMExports();
+  return () => uninstallHeadroomTransport();
+}
+function uninstallHeadroomTransport() {
+  const state = getState();
+  if (!state) {
+    return;
+  }
+  state.refs -= 1;
+  if (state.refs > 0) {
+    return;
+  }
+  globalThis.fetch = state.originalFetch;
+  http.request = state.originalHttpRequest;
+  http.get = state.originalHttpGet;
+  https.request = state.originalHttpsRequest;
+  https.get = state.originalHttpsGet;
+  http2.connect = state.originalHttp2Connect;
+  childProcess.spawn = state.originalChildSpawn;
+  childProcess.exec = state.originalChildExec;
+  childProcess.execFile = state.originalChildExecFile;
+  childProcess.fork = state.originalChildFork;
+  syncBuiltinESMExports();
+  setState(void 0);
+}
+
+// src/hook-shim.ts
+var proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;
+if (!proxyUrl) {
+  throw new Error(
+    "Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL"
+  );
+}
+installHeadroomTransport({ proxyUrl });
diff --git a/headroom/providers/proxy_routes.py b/headroom/providers/proxy_routes.py
index b7c6c595b..e77838bb0 100644
--- a/headroom/providers/proxy_routes.py
+++ b/headroom/providers/proxy_routes.py
@@ -7,13 +7,17 @@ import logging
 from typing import Any
 
 from fastapi import FastAPI, Request, WebSocket
+from fastapi.responses import Response
 
 from headroom.providers.cloudcode import normalize_cloudcode_passthrough_path
+from headroom.providers.codex.endpoints import codex_backend_url
+from headroom.providers.codex.headers import drop_header
 from headroom.providers.codex.live import (
     CODEX_LIVE_ROUTE_PATHS,
     handle_codex_live_websocket,
 )
 from headroom.providers.codex.responses import handle_chatgpt_codex_responses_subpath
+from headroom.providers.codex.runtime import resolve_codex_routing
 from headroom.providers.model_metadata import (
     MODEL_METADATA_LIST_ENDPOINT,
     handle_model_metadata_endpoint,
@@ -67,6 +71,32 @@ from headroom.proxy.request_scope import normalize_request_path
 logger = logging.getLogger("headroom.proxy.routes")
 
 
+async def _handle_chatgpt_codex_alpha_search(request: Request, proxy: Any) -> Response | None:
+    upstream_headers = dict(request.headers.items())
+    drop_header(upstream_headers, "host")
+    drop_header(upstream_headers, "accept-encoding")
+    from headroom.proxy.helpers import _strip_internal_headers
+
+    decision = resolve_codex_routing(_strip_internal_headers(upstream_headers))
+    if not decision.is_chatgpt_auth:
+        return None
+
+    body = await request.body()
+    assert proxy.http_client is not None
+    resp = await proxy.http_client.request(
+        request.method,
+        codex_backend_url("/alpha/search", request.url.query),
+        headers=decision.headers,
+        content=body,
+        timeout=120.0,
+    )
+    return Response(
+        content=resp.content,
+        status_code=resp.status_code,
+        headers=dict(resp.headers),
+    )
+
+
 def _register_provider_passthrough_route(
     app: FastAPI,
     proxy: Any,
@@ -456,6 +486,16 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
             provider_name=provider_name,
         )
 
+    @app.post("/v1/alpha/search")
+    async def codex_alpha_search(request: Request):
+        chatgpt_response = await _handle_chatgpt_codex_alpha_search(request, proxy)
+        if chatgpt_response is not None:
+            return chatgpt_response
+        return await proxy.handle_passthrough(
+            request,
+            _select_passthrough_base_url(proxy, dict(request.headers)),
+        )
+
     _register_openai_image_routes(app, proxy)
 
     _register_codex_live_routes(app, proxy)
diff --git a/headroom/providers/route_specs.py b/headroom/providers/route_specs.py
index 2aaabc9a4..296269443 100644
--- a/headroom/providers/route_specs.py
+++ b/headroom/providers/route_specs.py
@@ -105,6 +105,9 @@ ANTHROPIC_BATCH_ROUTES: tuple[ProviderHandlerRoute, ...] = (
 
 OPENAI_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
     ProviderHandlerRoute("POST", "/v1/chat/completions", "handle_openai_chat"),
+    # Copilot Chat derives this unprefixed path from overrideCapiUrl. Route it
+    # through the real handler; the generic catch-all would bypass compression.
+    ProviderHandlerRoute("POST", "/chat/completions", "handle_openai_chat"),
 )
 
 
diff --git a/headroom/proxy/auth_mode.py b/headroom/proxy/auth_mode.py
index 2c7e97021..97a76259a 100644
--- a/headroom/proxy/auth_mode.py
+++ b/headroom/proxy/auth_mode.py
@@ -162,6 +162,28 @@ def should_stamp_codex_client(path: str, headers: Mapping[str, Any] | Any) -> bo
     return should_stamp_codex_client_signals(path, _auth_signals(headers))
 
 
+# Client harnesses that can consume Headroom's mid-turn message-coalescing
+# protocol: the 202 ``headroom_queued`` reply and the synthetic
+# ``headroom_pending_messages`` SSE event. This is a custom protocol only Claude
+# Code parses today; other harnesses would receive events they can't decode, so
+# a concurrent same-session request from them must stream normally instead of
+# being queued and replayed. Keeping the capability in one named place — rather
+# than scattering ``client == "claude-code"`` string checks across the request
+# handlers — makes it a single, documented decision to revisit as more clients
+# learn the protocol (#1608).
+_COALESCING_CAPABLE_CLIENTS = frozenset({"claude-code"})
+
+
+def supports_mid_turn_coalescing(client: str | None) -> bool:
+    """Whether ``client`` can consume the mid-turn coalescing protocol.
+
+    ``client`` is a value returned by :func:`classify_client`. See
+    :data:`_COALESCING_CAPABLE_CLIENTS` for why the set is currently limited to
+    Claude Code.
+    """
+    return client in _COALESCING_CAPABLE_CLIENTS
+
+
 __all__ = [
     "AuthMode",
     "CLIENT_UA_MAP",
@@ -170,4 +192,5 @@ __all__ = [
     "classify_auth_mode",
     "classify_client",
     "should_stamp_codex_client",
+    "supports_mid_turn_coalescing",
 ]
diff --git a/headroom/proxy/body_forwarding.py b/headroom/proxy/body_forwarding.py
index 2897d7d8f..4648fce6c 100644
--- a/headroom/proxy/body_forwarding.py
+++ b/headroom/proxy/body_forwarding.py
@@ -4,6 +4,7 @@ This module owns the small algebra used by Python proxy forwarders to decide
 which bytes leave Headroom:
 
 * unmutated body with original bytes -> byte-for-byte passthrough
+* signed thinking blocks with original bytes -> byte-for-byte passthrough
 * mutated body or missing original bytes -> canonical JSON bytes
 * explicit rollback mode -> legacy httpx-style JSON bytes
 """
@@ -31,6 +32,15 @@ class OutboundBody:
 
     content: bytes
     source: OutboundBodySource
+    #: True when byte-faithful passthrough won over a mutated body, so every
+    #: edit the handler made to ``body`` was discarded before the wire. Callers
+    #: that gated a downstream decision on their own mutation (for example
+    #: flipping ``stream`` to False to buffer a reply) MUST consult this — the
+    #: request upstream actually sees is the client's original one.
+    dropped_mutations: bool = False
+    #: The ``BodyMutationTracker`` reasons discarded alongside it, when the
+    #: caller supplied them. Empty when the caller passed no reason list.
+    dropped_mutation_reasons: tuple[str, ...] = ()
 
 
 def get_python_forwarder_mode() -> PythonForwarderMode:
@@ -50,6 +60,27 @@ def serialize_body_canonical(body: dict[str, Any]) -> bytes:
     return json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
 
 
+def has_signed_thinking_blocks(body: dict[str, Any]) -> bool:
+    """Return whether message history contains Anthropic signed thinking blocks."""
+    messages = body.get("messages")
+    if not isinstance(messages, list):
+        return False
+
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, dict) and block.get("type") in {
+                "thinking",
+                "redacted_thinking",
+            }:
+                return True
+    return False
+
+
 class BodyMutationTracker:
     """Records whether a request body was mutated and why."""
 
@@ -82,9 +113,24 @@ def select_outbound_body(
     original_body_bytes: bytes | None,
     body_mutated: bool,
     forwarder_mode: PythonForwarderMode | None = None,
+    mutation_reasons: list[str] | None = None,
 ) -> OutboundBody:
-    """Select the exact bytes to forward upstream."""
+    """Select the exact bytes to forward upstream.
+
+    ``mutation_reasons`` is optional and only used for reporting: when the
+    signed-thinking passthrough overrides a mutated body, the discarded reasons
+    are echoed back on the result so the call site can log what never made it
+    upstream instead of silently claiming the edit landed.
+    """
     mode = forwarder_mode if forwarder_mode is not None else get_python_forwarder_mode()
+    if original_body_bytes is not None and has_signed_thinking_blocks(body):
+        return OutboundBody(
+            content=original_body_bytes,
+            source="passthrough",
+            dropped_mutations=body_mutated,
+            dropped_mutation_reasons=tuple(mutation_reasons or ()) if body_mutated else (),
+        )
+
     if mode == "legacy_json_kwarg":
         content = json.dumps(body, separators=(", ", ": "), ensure_ascii=True).encode("utf-8")
         return OutboundBody(content=content, source="legacy")
@@ -100,12 +146,38 @@ def prepare_outbound_body_bytes(
     original_body_bytes: bytes | None,
     body_mutated: bool,
     forwarder_mode: PythonForwarderMode | None = None,
+    mutation_reasons: list[str] | None = None,
 ) -> tuple[bytes, OutboundBodySource]:
-    """Compatibility tuple wrapper around :func:`select_outbound_body`."""
+    """Compatibility tuple wrapper around :func:`select_outbound_body`.
+
+    Keeps the two-value shape its existing callers unpack. Call
+    :func:`select_outbound_body` directly when you need the dropped-mutation
+    reporting.
+    """
     outbound = select_outbound_body(
         body=body,
         original_body_bytes=original_body_bytes,
         body_mutated=body_mutated,
         forwarder_mode=forwarder_mode,
+        mutation_reasons=mutation_reasons,
     )
     return outbound.content, outbound.source
+
+
+def outbound_body_is_client_bytes(
+    *,
+    body: dict[str, Any],
+    original_body_bytes: bytes | None,
+) -> bool:
+    """Return whether the wire body will be the client's original bytes.
+
+    A handler that changes ``body`` to steer its own upstream call — the
+    ``stream`` flip that buys a buffered reply is the load-bearing case — has to
+    know that the signed-thinking passthrough will throw that change away and
+    send the client's bytes verbatim. Asking before acting is cheaper than
+    discovering it from a reply in the wrong wire format.
+
+    Mirrors the first branch of :func:`select_outbound_body`; the forwarder mode
+    is deliberately not consulted because that branch overrides it too.
+    """
+    return original_body_bytes is not None and has_signed_thinking_blocks(body)
diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.py
index 435c09fd4..b42ac18b0 100644
--- a/headroom/proxy/cost.py
+++ b/headroom/proxy/cost.py
@@ -213,7 +213,7 @@ def build_prefix_cache_stats(
                 # Match model to provider
                 _openai_prefixes = ("gpt", "o1", "o3", "o4")
                 is_match = (
-                    (provider == "anthropic" and "claude" in model_name)
+                    (provider in ("anthropic", "vertex:anthropic") and "claude" in model_name)
                     or (provider == "openai" and any(p in model_name for p in _openai_prefixes))
                     or (provider == "gemini" and "gemini" in model_name)
                     or (provider == "bedrock" and "claude" in model_name)
@@ -1057,6 +1057,39 @@ class CostTracker:
         except Exception:
             return None
 
+    def totals(self) -> tuple[int, float]:
+        """Return just ``(total_input_tokens, total_input_cost_usd)``.
+
+        The same two numbers ``stats()`` reports, computed without the rest of
+        it. ``stats()`` is called once per request by the metrics path, which
+        reads exactly these two fields and discards ``per_model``,
+        ``savings_usd``, ``cost_with_headroom_usd`` and — the expensive one —
+        ``budget_basis``, whose ``period_cost_breakdown()`` walks up to 31 days
+        of retained cost records. MEASURED 2.8ms at 20k records and 13.6ms at
+        100k, on the event loop and holding the metrics lock, so it degraded
+        with proxy uptime rather than with load.
+
+        This loop is over models, not records, so it is bounded by how many
+        models a deployment talks to.
+        """
+        total_input_tokens = 0
+        cost_with_headroom = 0.0
+        for model in self._tokens_saved_by_model:
+            sent = self._tokens_sent_by_model.get(model, 0)
+            cr = self._api_cache_read_by_model.get(model, 0)
+            cw = self._api_cache_write_by_model.get(model, 0)
+            uncached = self._api_uncached_by_model.get(model, 0)
+            total_input_tokens += sent
+
+            prices = self._get_cache_prices(model)
+            if prices:
+                cr_price, cw_price, uncached_price = prices
+                if cr + cw + uncached > 0:
+                    cost_with_headroom += cr * cr_price + cw * cw_price + uncached * uncached_price
+                else:
+                    cost_with_headroom += sent * uncached_price
+        return total_input_tokens, round(cost_with_headroom, 4)
+
     def stats(self) -> dict:
         """Get token statistics per model."""
         per_model = {}
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index eaf399937..79045fa84 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -25,13 +25,18 @@ import httpx
 
 from headroom.agent_savings import proxy_pipeline_kwargs
 from headroom.ccr.context_tracker import looks_like_claude_code_compact_summary
+from headroom.ccr.marker_resolution import resolve_markers_in_response
 from headroom.copilot_auth import build_copilot_upstream_url
 from headroom.pipeline import PipelineStage, summarize_routing_markers
-from headroom.proxy.auth_mode import classify_auth_mode, classify_client
+from headroom.proxy.auth_mode import (
+    classify_auth_mode,
+    classify_client,
+    supports_mid_turn_coalescing,
+)
 from headroom.proxy.compression_decision import CompressionDecision
 from headroom.proxy.forwarded_headers import resolve_client_ip
 from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_value
-from headroom.proxy.helpers import extract_tags
+from headroom.proxy.helpers import extract_tags, relocate_system_messages_to_top_level
 from headroom.proxy.image_isolation import run_image_compression_isolated
 from headroom.proxy.memory_decision import MemoryDecision
 from headroom.proxy.memory_query import MemoryQuery
@@ -41,6 +46,115 @@ from headroom.proxy.outcome import RequestOutcome
 logger = logging.getLogger("headroom.proxy")
 
 
+class _AnthropicTurnHookUsage:
+    """Usage from hook-triggered Anthropic calls the main response omits.
+
+    The handler accounts for the response ultimately returned to the client.
+    A turn hook may make additional, billed calls before selecting that final
+    response, so retain every response and settle by object identity. This is
+    the Anthropic counterpart of OpenAI's ``TurnHookUsage`` and includes the
+    provider's disjoint uncached/read/write input buckets.
+    """
+
+    __slots__ = (
+        "_seen",
+        "input_tokens",
+        "output_tokens",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "cache_write_5m_tokens",
+        "cache_write_1h_tokens",
+        "extra_calls",
+    )
+
+    def __init__(self) -> None:
+        self._seen: list[tuple[Any, int, int, int, int, int, int]] = []
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.cache_read_tokens = 0
+        self.cache_write_tokens = 0
+        self.cache_write_5m_tokens = 0
+        self.cache_write_1h_tokens = 0
+        self.extra_calls = 0
+
+    @staticmethod
+    def _int(value: Any) -> int:
+        try:
+            return max(0, int(value or 0))
+        except (TypeError, ValueError):
+            return 0
+
+    def record(self, payload: Any) -> None:
+        usage = payload.get("usage") if isinstance(payload, dict) else None
+        if not isinstance(usage, dict):
+            self._seen.append((payload, 0, 0, 0, 0, 0, 0))
+            return
+        cache_read = self._int(usage.get("cache_read_input_tokens"))
+        cache_write = self._int(usage.get("cache_creation_input_tokens"))
+        creation = usage.get("cache_creation")
+        cache_write_5m = (
+            self._int(creation.get("ephemeral_5m_input_tokens"))
+            if isinstance(creation, dict)
+            else 0
+        )
+        cache_write_1h = (
+            self._int(creation.get("ephemeral_1h_input_tokens"))
+            if isinstance(creation, dict)
+            else 0
+        )
+        self._seen.append(
+            (
+                payload,
+                _anthropic_provider_input_tokens(usage),
+                self._int(usage.get("output_tokens")),
+                cache_read,
+                cache_write,
+                cache_write_5m,
+                cache_write_1h,
+            )
+        )
+
+    def settle(self, final: Any) -> None:
+        self.input_tokens = self.output_tokens = 0
+        self.cache_read_tokens = self.cache_write_tokens = 0
+        self.cache_write_5m_tokens = self.cache_write_1h_tokens = 0
+        self.extra_calls = 0
+        dropped = False
+        for (
+            payload,
+            input_tokens,
+            output_tokens,
+            cache_read,
+            cache_write,
+            cache_write_5m,
+            cache_write_1h,
+        ) in self._seen:
+            if not dropped and payload is final:
+                dropped = True
+                continue
+            self.extra_calls += 1
+            self.input_tokens += input_tokens
+            self.output_tokens += output_tokens
+            self.cache_read_tokens += cache_read
+            self.cache_write_tokens += cache_write
+            self.cache_write_5m_tokens += cache_write_5m
+            self.cache_write_1h_tokens += cache_write_1h
+
+
+def _anthropic_provider_input_tokens(usage: Any) -> int:
+    """Provider-scaled prompt total across Anthropic's disjoint buckets."""
+    if not isinstance(usage, dict):
+        return 0
+    return sum(
+        _AnthropicTurnHookUsage._int(usage.get(key))
+        for key in (
+            "input_tokens",
+            "cache_read_input_tokens",
+            "cache_creation_input_tokens",
+        )
+    )
+
+
 def _strip_streaming_only_content_fields(messages: Any) -> None:
     """Remove streaming-only ``index`` keys from request content blocks, in place.
 
@@ -68,6 +182,20 @@ def _strip_index_from_content_blocks(content: Any) -> None:
             _strip_index_from_content_blocks(block.get("content"))
 
 
+def _looks_like_sse_response(response: httpx.Response) -> bool:
+    """Return whether an upstream reply is a Server-Sent Events stream.
+
+    Trusts the declared content-type first and falls back to sniffing the
+    leading bytes for an SSE field, because a gateway in front of Anthropic may
+    relay the stream under a vaguer type.
+    """
+    content_type = (response.headers.get("content-type") or "").lower()
+    if "text/event-stream" in content_type:
+        return True
+    head = response.content[:64].lstrip()
+    return head.startswith(b"event:") or head.startswith(b"data:")
+
+
 class AnthropicHandlerMixin:
     """Mixin providing Anthropic API handler methods for HeadroomProxy."""
 
@@ -194,9 +322,30 @@ class AnthropicHandlerMixin:
     def _sort_tools_deterministically(
         cls, tools: list[dict[str, Any]] | None
     ) -> list[dict[str, Any]] | None:
-        """Return tools in deterministic order to preserve prompt-cache stability."""
+        """Return tools in deterministic order to preserve prompt-cache stability.
+
+        Skipped entirely when any tool carries ``cache_control``. A breakpoint on
+        a tool means "cache everything up to and including this one", so
+        reordering the array changes which tools are inside that prefix -- and
+        with two markers of different TTLs it can put the 1h one behind the 5m
+        one, which Anthropic rejects outright (#2939). The Rust proxy already
+        refuses for the same reason (``any_tool_has_cache_control`` in
+        ``crates/headroom-proxy/src/compression/live_zone_anthropic.rs``); this
+        is the Python side of that guard.
+
+        Clients that mark no tools -- the common case, and the one the sort was
+        written for -- are unaffected, so this costs nobody a cache bust.
+        """
         if not tools:
             return tools
+        marked = sum(1 for t in tools if isinstance(t, dict) and t.get("cache_control"))
+        if marked:
+            logger.info(
+                "event=tool_sort_skipped reason=marker_present tool_count=%d marked=%d",
+                len(tools),
+                marked,
+            )
+            return tools
         return sorted(tools, key=cls._tool_sort_key)
 
     @classmethod
@@ -290,7 +439,16 @@ class AnthropicHandlerMixin:
             new_content: list[dict[str, Any]] = []
             appended = False
             for block in content:
-                if not appended and isinstance(block, dict) and block.get("type") == "text":
+                if (
+                    not appended
+                    and isinstance(block, dict)
+                    and block.get("type") == "text"
+                    # Never mutate a block carrying the client's cache
+                    # breakpoint: the client re-sends the original bytes
+                    # next turn, so any injection here busts the prefix
+                    # cache at this message from then on.
+                    and "cache_control" not in block
+                ):
                     existing = block.get("text", "")
                     new_content.append({**block, "text": existing + "\n\n" + context_text})
                     appended = True
@@ -736,6 +894,29 @@ class AnthropicHandlerMixin:
             if input_event.tools is not None:
                 body["tools"] = input_event.tools
 
+            # Snapshot the client's cache_control breakpoints before any
+            # transform runs; paired with the outbound count right before
+            # forwarding (event=cache_breakpoints) so a dropped or moved
+            # final breakpoint is self-diagnosing from proxy.log alone.
+            from headroom.proxy.helpers import (
+                CACHE_TTL_1H,
+                cache_control_ttl_lanes,
+                count_cache_breakpoints,
+            )
+
+            inbound_breakpoints = count_cache_breakpoints(
+                body.get("system"), messages, body.get("tools")
+            )
+            # Which TTL lane did the CLIENT ask for on THIS turn? Claude Code
+            # picks 5m or 1h per request (a `/btw` side question drops to 5m and
+            # omits the extended-cache-ttl beta header even mid-1h-session), so
+            # this cannot be inferred from the session or from config. The
+            # pre-forward guard needs it to tell a breakpoint the client asked
+            # for from one an earlier turn's replayed bytes dragged in (#2939).
+            client_uses_1h = CACHE_TTL_1H in cache_control_ttl_lanes(
+                body.get("system"), messages, body.get("tools")
+            )
+
             # Validate message array size
             if len(messages) > MAX_MESSAGE_ARRAY_LENGTH:
                 await _finalize_pre_upstream()
@@ -794,6 +975,9 @@ class AnthropicHandlerMixin:
             # body is undecipherable → 502.
             headers.pop("accept-encoding", None)
             tags = extract_tags(headers)
+            from headroom.proxy.savings_attribution import bind_scope
+
+            bind_scope(tags, request.scope)
             # Identify the harness (codex / claude-code / aider / etc.)
             # from User-Agent or X-Client. Surfaced via the funnel into
             # PERF logs and RequestLog.tags — see RequestOutcome.client.
@@ -996,6 +1180,11 @@ class AnthropicHandlerMixin:
                     response_headers = dict(cached.response_headers)
                     response_headers.pop("content-encoding", None)
                     response_headers.pop("content-length", None)
+                    # Drop the stored content-type too. Starlette lets an
+                    # explicit header win over ``media_type``, so keeping the
+                    # producing request's type would let a cache entry hand this
+                    # caller a wire format it never asked for (#2952).
+                    response_headers.pop("content-type", None)
 
                     # Unit 4: release the pre-upstream semaphore on cache
                     # hit — no upstream call will happen.
@@ -1091,6 +1280,25 @@ class AnthropicHandlerMixin:
             session_id = self.session_tracker_store.compute_session_id(
                 request, model, session_messages
             )
+            # Prefix trackers must follow the provider's cache key, not just
+            # message history.  Anthropic renders tools before system/messages;
+            # parallel sub-calls commonly share model+system+history while
+            # carrying different tool sets.  Sharing one tracker across those
+            # requests pins cache reads at the early tools segment (#2671).
+            from headroom.cache.prefix_tracker import segment_fingerprint
+
+            affinity_tools = self._tools_for_forwarding(
+                body.get("tools"), preserve_order=preserve_tool_order
+            )
+            cache_affinity = segment_fingerprint(
+                {
+                    "model": model,
+                    "tools": affinity_tools,
+                    "tool_choice": body.get("tool_choice"),
+                    "thinking": body.get("thinking"),
+                    "output_config": body.get("output_config"),
+                }
+            )
             # Resolve the tracker by conversation lineage within the session id
             # (#2085): one model + system prompt spans a Claude Code session and
             # all its parallel subagents, so concurrent conversations share this
@@ -1098,9 +1306,21 @@ class AnthropicHandlerMixin:
             # thrash the frozen-prefix state and the provider prompt cache is
             # re-written on nearly every call.
             prefix_tracker = self.session_tracker_store.resolve_tracker(
-                session_id, "anthropic", messages=session_messages
+                session_id,
+                "anthropic",
+                messages=session_messages,
+                cache_affinity=cache_affinity,
             )
+            # Snapshot lineage state once.  Reusing the same pair for delta
+            # extraction, byte-stable replay, and breakpoint placement keeps
+            # all three decisions tied to one previous request (and avoids
+            # repeatedly deep-copying a multi-megabyte agent transcript).
+            previous_original_messages = prefix_tracker.get_last_original_messages()
+            previous_forwarded_messages = prefix_tracker.get_last_forwarded_messages()
             frozen_message_count = prefix_tracker.get_frozen_message_count()
+            # Pre-strict-override tracker truth: >0 only when a provider cache
+            # prefix was actually confirmed (or restored) for this session.
+            tracker_frozen_count = frozen_message_count
             # Idle gap since the previous turn's response, snapshotted at fetch
             # (before get_or_create bumped the access clock). Forwarded to the
             # pipeline so the net-cost/TTL gate (HEADROOM_NET_COST_POLICY=1) can
@@ -1505,13 +1725,54 @@ class AnthropicHandlerMixin:
                         optimized_tokens = tokenizer.count_messages(optimized_messages)
                         transforms_applied = _cold_transforms
                     else:
-                        previous_original_messages = prefix_tracker.get_last_original_messages()
-                        previous_forwarded_messages = prefix_tracker.get_last_forwarded_messages()
-                        delta = self._extract_cache_stable_delta(
-                            original_client_messages,
-                            previous_original_messages,
-                            previous_forwarded_messages,
-                        )
+                        if not previous_original_messages and tracker_frozen_count == 0:
+                            # Session cold start: nothing has been forwarded for
+                            # this session yet and no frozen prefix survives from
+                            # a prior process (frozen_message_count > 0 means a
+                            # provider cache prefix may already exist upstream —
+                            # e.g. a resumed session restored from the CCR
+                            # compression cache — so it must stay passthrough),
+                            # hence there is no provider cache prefix to protect — run the same full-message
+                            # compression as non-cache modes (issue #2357: the
+                            # previous silent passthrough here meant cache mode
+                            # never compressed anything until a stable delta
+                            # appeared, which for resumed 100k-token transcripts
+                            # was never). The compressed output is recorded as
+                            # the forwarded messages below, and later turns
+                            # replay that prefix byte-identically via the
+                            # stable-delta path, so append-only cache safety is
+                            # preserved.
+                            delta = None
+                            async with stage_timer.measure("compression_first_stage"):
+                                result = await self._run_compression_in_executor(
+                                    lambda: self.anthropic_pipeline.apply(
+                                        messages=messages,
+                                        model=model,
+                                        model_limit=context_limit,
+                                        context=extract_user_query(messages),
+                                        frozen_message_count=frozen_message_count,
+                                        biases=biases,
+                                        request_id=request_id,
+                                        compression_policy=compression_policy,
+                                        **proxy_pipeline_kwargs(self.config),
+                                    ),
+                                    timeout=COMPRESSION_TIMEOUT_SECONDS,
+                                )
+
+                            if result.messages != messages:
+                                optimized_messages = result.messages
+                                transforms_applied = list(result.transforms_applied) + [
+                                    "cache_mode:cold_start_full"
+                                ]
+                                pipeline_timing = result.timing
+                                original_tokens = result.tokens_before
+                                optimized_tokens = result.tokens_after
+                        else:
+                            delta = self._extract_cache_stable_delta(
+                                original_client_messages,
+                                previous_original_messages,
+                                previous_forwarded_messages,
+                            )
                         if delta is not None:
                             stable_forwarded_prefix, delta_messages = delta
                             if delta_messages:
@@ -1579,11 +1840,26 @@ class AnthropicHandlerMixin:
                             else:
                                 optimized_messages = stable_forwarded_prefix
                                 optimized_tokens = tokenizer.count_messages(optimized_messages)
-                        else:
+                        elif previous_original_messages:
                             # Conservative rule for cache mode:
                             # only replay exact stable message-prefix extensions.
                             # In-message append rewriting is deferred until we can
                             # prove it is perfectly replayable across future turns.
+                            # Tag the passthrough so the dashboard can explain 0
+                            # savings instead of silently reporting "optimization
+                            # enabled" with Before == After (issue #2357).
+                            tags["passthrough_reason"] = "cache_mode_prefix_mismatch"
+                            logger.info(
+                                "[%s] Compression skipped: reason=cache_mode_prefix_mismatch",
+                                request_id,
+                            )
+                            optimized_messages = messages
+                            optimized_tokens = original_tokens
+                        elif tracker_frozen_count > 0:
+                            # Cold start with a frozen prefix restored from a
+                            # prior process: the provider cache may already hold
+                            # that prefix, so forward unmodified.
+                            tags["passthrough_reason"] = "cache_mode_frozen_cold_start"
                             optimized_messages = messages
                             optimized_tokens = original_tokens
 
@@ -1625,8 +1901,8 @@ class AnthropicHandlerMixin:
                 _ov = overlay_cached_prefix(
                     optimized_messages,
                     original_client_messages,
-                    prefix_tracker.get_last_original_messages(),
-                    prefix_tracker.get_last_forwarded_messages(),
+                    previous_original_messages,
+                    previous_forwarded_messages,
                 )
                 _overlay_replayed = _ov != optimized_messages
                 if _overlay_replayed:
@@ -1635,11 +1911,19 @@ class AnthropicHandlerMixin:
 
             # Own cache_control placement: the client moves the breakpoint each
             # turn and the overlay replays past markers, so they accumulate ~1/turn
-            # and Anthropic hard-errors at >4. Strip message-level markers and keep
-            # a single breakpoint on the last block (caches the whole prefix;
-            # content-keyed cache so re-placing never busts). Applied last so the
+            # and Anthropic hard-errors at >4. Strip message-level markers and
+            # re-place them at the CLIENT's current positions: Anthropic resolves
+            # each breakpoint with a ~20-content-block lookback, and the client's
+            # previous-message marker is the read anchor that lets a big turn's
+            # write chain to the prior entry. Collapsing to one newest-block
+            # marker breaks that chain on tool-heavy turns (silent full re-write)
+            # and can leave the tail billing uncached. Applied last so the
             # forwarded AND recorded (next_forwarded) messages stay bounded.
-            _norm = normalize_message_cache_control(optimized_messages)
+            _norm = normalize_message_cache_control(
+                optimized_messages,
+                previous_forwarded_messages,
+                client_messages=original_client_messages,
+            )
             if _norm is not optimized_messages:
                 optimized_messages = _norm
 
@@ -1853,6 +2137,10 @@ class AnthropicHandlerMixin:
                     inject_system_instructions=inject_system_instructions,
                 )
                 injector.scan_for_markers(optimized_messages)
+                # Shape-only scanning also matches markers from other context
+                # tools; drop hashes this proxy never actually stored before
+                # they can drive tool injection (issue #2836).
+                injector.verify_ownership()
                 if inject_system_instructions and injector.has_compressed_content:
                     optimized_messages = injector.inject_into_system_message(optimized_messages)
 
@@ -1875,25 +2163,33 @@ class AnthropicHandlerMixin:
                 if configured_inject_tool:
                     from headroom.proxy.helpers import (
                         apply_session_sticky_ccr_tool,
-                        has_new_ccr_markers,
+                        history_references_ccr_tool,
                     )
 
-                    # #1850: markers replayed from the previously-forwarded
-                    # prefix (overlay_cached_prefix) are historical; only
-                    # markers NEW this turn may drive a first-time injection,
-                    # else a replayed marker injects the tool into a session
-                    # that never actually compressed.
-                    has_new_compressed_content = has_new_ccr_markers(
-                        current_detected_hashes=injector.detected_hashes,
-                        previous_forwarded_messages=prefix_tracker.get_last_forwarded_messages(),
-                        provider="anthropic",
-                    )
+                    # Inject whenever the request carries ANY CCR marker, new or
+                    # replayed from the frozen prefix. #1850 narrowed the
+                    # first-time gate to markers created THIS turn to avoid
+                    # arming a session that never compressed, but a replayed
+                    # marker is exactly as unredeemable as a fresh one: the agent
+                    # redeems hashes it was handed turns ago (project instructions
+                    # can even tell it to), and if `headroom_retrieve` is absent
+                    # Anthropic rejects the whole request with 400 "Tool reference
+                    # 'headroom_retrieve' not found in available tools" (#2766). A
+                    # present marker means the session HAS compressed, so this
+                    # cannot start injecting into non-CCR conversations. It is also
+                    # the cache-stable choice: toggling the tool in and out of the
+                    # tools array between turns is what busts the tools cache
+                    # segment, whereas injecting consistently whenever markers
+                    # exist keeps it stable. The `SessionCcrTracker` is
+                    # per-process, so a proxy restart mid-conversation makes live
+                    # sessions look fresh again, which is what re-armed the 400.
                     tools, ccr_tool_injected = apply_session_sticky_ccr_tool(
                         provider="anthropic",
                         session_id=session_id,
                         request_id=request_id,
                         existing_tools=tools,
-                        has_compressed_content_this_turn=has_new_compressed_content,
+                        has_compressed_content_this_turn=injector.has_compressed_content,
+                        history_has_ccr_reference=history_references_ccr_tool(optimized_messages),
                     )
                     if ccr_tool_injected:
                         logger.debug(
@@ -2401,6 +2697,29 @@ class AnthropicHandlerMixin:
                 optimized_tokens = tokenizer.count_messages(body["messages"])
                 tokens_saved = max(0, original_tokens - optimized_tokens)
 
+            from headroom.proxy.helpers import (
+                anthropic_first_party_tool_search_supported,
+                strip_first_party_tool_search_tools_for_third_party_upstream,
+            )
+
+            _anthropic_target_base_url = upstream_base_url or self.ANTHROPIC_API_URL
+            _third_party_anthropic_upstream = provider_name == "anthropic" and (
+                not anthropic_first_party_tool_search_supported(_anthropic_target_base_url)
+            )
+            if _third_party_anthropic_upstream:
+                _tools_before_strip = body.get("tools")
+                _tools_after_strip = strip_first_party_tool_search_tools_for_third_party_upstream(
+                    _tools_before_strip,
+                    _anthropic_target_base_url,
+                )
+                if _tools_after_strip is not _tools_before_strip:
+                    body["tools"] = _tools_after_strip
+                    tools = _tools_after_strip
+                    tags["third_party_tool_search_stripped"] = max(
+                        0,
+                        len(_tools_before_strip) - len(_tools_after_strip),
+                    )
+
             # Server-side Tool Search (on by default; HEADROOM_TOOL_SEARCH=0 opts
             # out — the `coding` savings profile already seeded it on via
             # seed_proxy_env_defaults, so default-on here just makes the same
@@ -2416,12 +2735,13 @@ class AnthropicHandlerMixin:
             # bytes are excluded from context this turn); the response usage confirms it.
             #
             # FIRST-PARTY ANTHROPIC ONLY: the tool_search_tool_* type + defer_loading
-            # here use the first-party Claude API shape (GA, no beta header). Bedrock
-            # (``anthropic_backend``) and Vertex/gateway providers gate tool search
-            # differently, so scope the injection to provider "anthropic" over the
-            # direct API and leave those paths untouched.
+            # here use the first-party Claude API shape (GA, no beta header). Custom
+            # Anthropic-compatible gateways reject that shape, so third-party routes
+            # strip client-originated tool_search_tool_* entries above and skip
+            # Headroom's own injector here.
             if (
                 provider_name == "anthropic"
+                and anthropic_first_party_tool_search_supported(_anthropic_target_base_url)
                 and getattr(self, "anthropic_backend", None) is None
                 and os.environ.get("HEADROOM_TOOL_SEARCH", "1").strip().lower()
                 in ("1", "true", "yes", "on", "auto")
@@ -2444,40 +2764,14 @@ class AnthropicHandlerMixin:
                     tools = _ts_after
                     tags["tool_search_deferred_tools"] = len(_ts_deferred)
                     tags["tool_search_deferred_tokens"] = _ts_saved_tokens
+                    from headroom.proxy.savings_attribution import record_savings
+
+                    record_savings(tags, "tool_search", tokens=_ts_saved_tokens)
                     transforms_applied.append(
                         f"router:tool_search_deferral:{len(_ts_deferred)}tools:"
                         f"{_ts_saved_tokens}tok"
                     )
 
-            # Tool-search history repair (#2805). Once deferral is on, the client
-            # stores Anthropic's server_tool_use / tool_search_tool_result blocks in
-            # its transcript forever, and upstream validates every tool_reference in
-            # that history against THIS request's tools array. Claude Code replays
-            # the same transcript on side-requests carrying a different, smaller
-            # tools array (the prompt-type Stop hook evaluator, /compact), which the
-            # proxy cannot predict — so upstream 400s with "Tool reference 'X' not
-            # found in available tools". Drop the blocks such a request cannot
-            # support. Runs AFTER the injection above so the tool we just added
-            # counts as present: on the main loop nothing is stripped and the prefix
-            # is untouched. Unconditional (not gated on the flag) so transcripts
-            # poisoned before the flag was turned off still recover.
-            from headroom.proxy.helpers import strip_unsupported_tool_search_blocks
-
-            _ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks(
-                body.get("messages"), body.get("tools")
-            )
-            if _ts_stripped:
-                body["messages"] = _ts_repaired
-                optimized_messages = _ts_repaired
-                body_mutation_tracker.mark_mutated("tool_search_history_repair")
-                transforms_applied.append(f"router:tool_search_repair:{_ts_stripped}blocks")
-                logger.info(
-                    "[%s] Tool search: dropped %d unsupportable history block(s) "
-                    "(tools array cannot resolve their tool_reference entries)",
-                    request_id,
-                    _ts_stripped,
-                )
-
             # Turn hooks (opt-in extensions): a registered hook may inspect or
             # rewrite the outbound tools/messages before we send upstream — the
             # extensible counterpart to the built-in deferral above. A single
@@ -2489,6 +2783,7 @@ class AnthropicHandlerMixin:
             )
 
             _pre_hook_tokens: int | None = None
+            _req_ctx: TurnContext | None = None
             if registered_turn_hooks():
                 _req_ctx = TurnContext(
                     provider="anthropic",
@@ -2496,6 +2791,9 @@ class AnthropicHandlerMixin:
                     messages=optimized_messages,
                     tools=body.get("tools"),
                     config=self.config,
+                    tags=tags,
+                    count_messages=tokenizer.count_messages,
+                    count_tools=_count_tool_tokens,
                 )
                 # Snapshot BEFORE the hook (same tokenizer) so we can tell whether the
                 # hook itself folded — comparing against the pipeline's optimized_tokens
@@ -2506,7 +2804,7 @@ class AnthropicHandlerMixin:
                     _pre_hook_tokens = None
                 _th_tools_before = body.get("tools")
                 _th_tok_before = _count_tool_tokens(_th_tools_before) if _th_tools_before else 0
-                run_request_hooks(_req_ctx)
+                run_request_hooks(_req_ctx, stream_safe_only=bool(stream))
                 if _req_ctx.messages is not optimized_messages:
                     optimized_messages = _req_ctx.messages
                     body["messages"] = optimized_messages
@@ -2524,6 +2822,62 @@ class AnthropicHandlerMixin:
                         int(tags.get("turn_hook_tools_saved_tokens", 0) or 0) + _th_saved
                     )
 
+            # Tool-search history repair (#2805). Once deferral is on, the client
+            # stores Anthropic's server_tool_use / tool_search_tool_result blocks in
+            # its transcript forever, and upstream validates every tool_reference in
+            # that history against THIS request's tools array. Claude Code replays
+            # the same transcript on side-requests carrying a different, smaller
+            # tools array (the prompt-type Stop hook evaluator, /compact), which the
+            # proxy cannot predict — so upstream 400s with "Tool reference 'X' not
+            # found in available tools". Drop the blocks such a request cannot
+            # support. Unconditional (not gated on the flag) so transcripts poisoned
+            # before the flag was turned off still recover.
+            #
+            # ORDERING (#2888): this must be the LAST stage that can invalidate a
+            # tool_reference, so it runs after BOTH the deferral injection above (the
+            # tool we just added counts as present, so the main loop strips nothing
+            # and the prefix is untouched) AND the turn hooks (a hook may rewrite the
+            # tools array, and repairing before it validated against a stale view).
+            # Nothing past this point mutates `body["tools"]` on the outbound path.
+            from headroom.proxy.helpers import strip_unsupported_tool_search_blocks
+
+            _ts_repaired, _ts_stripped = strip_unsupported_tool_search_blocks(
+                body.get("messages"), body.get("tools")
+            )
+            if _ts_stripped:
+                body["messages"] = _ts_repaired
+                optimized_messages = _ts_repaired
+                body_mutation_tracker.mark_mutated("tool_search_history_repair")
+                transforms_applied.append(f"router:tool_search_repair:{_ts_stripped}blocks")
+                logger.info(
+                    "[%s] Tool search: dropped %d unsupportable history block(s) "
+                    "(tools array cannot resolve their tool_reference entries)",
+                    request_id,
+                    _ts_stripped,
+                )
+
+            # CCR retrieve history repair (#2814). Run beside the tool-search
+            # repair and after both normal CCR injection and turn hooks, so it
+            # validates against the final outbound tools array. A side-request
+            # that does not declare headroom_retrieve cannot retain historical
+            # tool_use/tool_result references that Anthropic would reject.
+            from headroom.proxy.helpers import strip_unsupported_ccr_retrieve_blocks
+
+            _ccr_repaired, _ccr_neutralized = strip_unsupported_ccr_retrieve_blocks(
+                body.get("messages"), body.get("tools")
+            )
+            if _ccr_neutralized:
+                body["messages"] = _ccr_repaired
+                optimized_messages = _ccr_repaired
+                body_mutation_tracker.mark_mutated("ccr_retrieve_history_repair")
+                transforms_applied.append(f"router:ccr_retrieve_repair:{_ccr_neutralized}blocks")
+                logger.info(
+                    "[%s] CCR: neutralized %d headroom_retrieve history block(s) "
+                    "(tools array does not declare the tool this turn)",
+                    request_id,
+                    _ccr_neutralized,
+                )
+
             # Consistency: report tok_before/tok_after with ONE tokenizer. The pipeline
             # and the handler use different token estimators, and cache-mode branches
             # can leave original_tokens (handler, line ~1049) and optimized_tokens
@@ -2534,8 +2888,14 @@ class AnthropicHandlerMixin:
             # turn-hook fold (optimized_messages is post-hook). Runs unconditionally.
             try:
                 _orig_snapshot = original_client_messages  # noqa: F821 (bound at request start)
-                original_tokens = tokenizer.count_messages(_orig_snapshot)
-                optimized_tokens = tokenizer.count_messages(optimized_messages)
+                # Off the event loop (#2810): both passes are CPU-bound real BPE
+                # since #2543, and running them inline stalled every other
+                # in-flight request on the same process (~1s on a 2.3 MB body).
+                # Same tokenizer instance, so the reported values are unchanged.
+                original_tokens = await asyncio.to_thread(tokenizer.count_messages, _orig_snapshot)
+                optimized_tokens = await asyncio.to_thread(
+                    tokenizer.count_messages, optimized_messages
+                )
                 # Fold the tool-schema/desc compaction delta into BOTH endpoints so
                 # tok_before - tok_after == tok_saved stays coherent in the PERF line
                 # (count_messages never sees tool bytes). Same shape as the OpenAI chat
@@ -2571,7 +2931,13 @@ class AnthropicHandlerMixin:
                     shape_request,
                 )
 
-                _shaper_settings = OutputShaperSettings.from_env()
+                _shaper_settings = OutputShaperSettings.from_env(
+                    enabled=(
+                        self.config.rollout.is_enabled("proxy_output_shaper")
+                        if getattr(self.config, "rollout", None) is not None
+                        else None
+                    )
+                )
                 if _shaper_settings.enabled:
                     # Conversation-stable holdout assignment: a whole
                     # conversation is treatment or control. This keeps the A/B
@@ -2617,6 +2983,28 @@ class AnthropicHandlerMixin:
                 (time.perf_counter() - pre_upstream_started_at) * 1000.0,
             )
 
+            # Anthropic wire-contract guard (issue #765). Any transform or
+            # pipeline extension above may have left a ``role="system"`` entry
+            # in ``messages`` (e.g. a harness system block relocated during
+            # compression). Anthropic rejects that with a 400 ("messages.0: use
+            # the top-level 'system' parameter ..."), so relocate it back to the
+            # top-level ``system`` parameter as the last step before forwarding.
+            relocated_messages, relocated_system, system_relocated = (
+                relocate_system_messages_to_top_level(body["messages"], body.get("system"))
+            )
+            if system_relocated:
+                body["messages"] = relocated_messages
+                if relocated_system is None:
+                    body.pop("system", None)
+                else:
+                    body["system"] = relocated_system
+                body_mutation_tracker.mark_mutated("system_role_relocated")
+                logger.warning(
+                    "[%s] Relocated role=system message(s) out of messages[] into the "
+                    "top-level system parameter (Anthropic wire-contract guard, issue #765)",
+                    request_id,
+                )
+
             # Byte-faithful forwarder support (PR-A3, fixes P0-2). At this
             # point body has been through every transform (image, compression,
             # memory, tool sort, pipeline extensions). If a transform reported
@@ -2629,7 +3017,11 @@ class AnthropicHandlerMixin:
                     parsed_original = json.loads(original_body_bytes)
                     if parsed_original != body:
                         body_mutation_tracker.mark_mutated("structural_diff_vs_original")
-                except (json.JSONDecodeError, ValueError):
+                # MemoryError is not a ValueError, so a re-parse spike on 1M-context
+                # bodies used to escape and abort an otherwise-fine request (#2768).
+                # This block is a safety net; marking mutated is already the safe
+                # outcome (it forces canonical re-serialization).
+                except (json.JSONDecodeError, ValueError, MemoryError, RecursionError):
                     body_mutation_tracker.mark_mutated("original_unparseable")
 
             if (
@@ -2644,7 +3036,17 @@ class AnthropicHandlerMixin:
                 headers["anthropic-beta"] = _client_beta_value
 
             # Forward request - use Bedrock backend if configured, otherwise direct API
-            if self.anthropic_backend is not None:
+            #
+            # An extension may have published a per-request routing decision on
+            # `request.state.headroom_route` (see proxy/route_advice.py). When
+            # it names a provider we do not already speak, serve this ONE
+            # request from a translating backend for it. Absent, unresolvable,
+            # or same-protocol -> `self.anthropic_backend`, i.e. exactly the
+            # behaviour this line had before.
+            from headroom.proxy.route_advice import resolver_for
+
+            request_backend = resolver_for(self).for_request(request, body=body)
+            if request_backend is not None:
                 # Route through Bedrock backend
                 try:
                     if stream:
@@ -2675,12 +3077,11 @@ class AnthropicHandlerMixin:
                             original_messages=original_client_messages,
                             prefix_tracker=prefix_tracker,
                             optimized_messages=optimized_messages,
+                            backend=request_backend,
                         )
                     else:
                         async with stage_timer.measure("upstream_connect"):
-                            backend_response = await self.anthropic_backend.send_message(
-                                body, headers
-                            )
+                            backend_response = await request_backend.send_message(body, headers)
                         self.pipeline_extensions.emit(
                             PipelineStage.POST_SEND,
                             operation="proxy.request",
@@ -2732,9 +3133,7 @@ class AnthropicHandlerMixin:
                         usage = backend_response.body.get("usage", {})
                         output_tokens = usage.get("output_tokens", 0)
 
-                        _backend_name = (
-                            self.anthropic_backend.name if self.anthropic_backend else "anthropic"
-                        )
+                        _backend_name = request_backend.name if request_backend else "anthropic"
                         # Eligible-only denominator for the active
                         # compression ratio: tokens in the live zone we
                         # actually attempted to compress. Frozen prefix
@@ -2756,9 +3155,28 @@ class AnthropicHandlerMixin:
                         cw_5m_tokens, cw_1h_tokens = self._extract_anthropic_cache_ttl_metrics(
                             usage
                         )
-                        uncached_input_tokens = max(
-                            0, attempted_input_tokens - cr_tokens - cw_tokens
-                        )
+                        # Prefer the backend's Anthropic-shaped ``input_tokens``,
+                        # which is already the uncached count (prompt tokens minus
+                        # cache read/creation; see ``_anthropic_usage_from_litellm``
+                        # / #1345), matching the direct-API path below. Re-deriving
+                        # it as ``attempted_input_tokens - cache`` is wrong whenever
+                        # the backend reports it: ``attempted_input_tokens`` is the
+                        # live-zone tokenizer count kept for the compression-ratio
+                        # denominator, not the full request size, so on any turn
+                        # whose cached prefix is larger than the new turn it
+                        # underflows and ``max(0, ...)`` clamps uncached to 0.
+                        #
+                        # Guard on the backend actually reporting it: a backend that
+                        # omits ``input_tokens`` (or sends null) must not silently
+                        # report uncached=0 — fall back to the live-zone derivation,
+                        # which is never worse than the previous behaviour.
+                        _reported_input_tokens = usage.get("input_tokens")
+                        if _reported_input_tokens is not None:
+                            uncached_input_tokens = int(_reported_input_tokens)
+                        else:
+                            uncached_input_tokens = max(
+                                0, attempted_input_tokens - cr_tokens - cw_tokens
+                            )
 
                         # Update prefix cache tracker for next turn. Mirrors the
                         # direct-Anthropic-API branch below (~line 3011) — without
@@ -2815,6 +3233,9 @@ class AnthropicHandlerMixin:
                                 output_tokens=output_tokens,
                                 tokens_saved=tokens_saved,
                                 attempted_input_tokens=attempted_input_tokens,
+                                provider_input_tokens=(
+                                    uncached_input_tokens + cr_tokens + cw_tokens
+                                ),
                                 cache_read_tokens=cr_tokens,
                                 cache_write_tokens=cw_tokens,
                                 cache_write_5m_tokens=cw_5m_tokens,
@@ -2875,13 +3296,37 @@ class AnthropicHandlerMixin:
                 ccr_response_handler_enabled = bool(
                     self.ccr_response_handler and getattr(ccr_handler_config, "enabled", True)
                 )
-                buffered_stream_ccr = bool(
+                # A body carrying signed thinking blocks leaves as the client's
+                # original bytes (see ``select_outbound_body``), which throws
+                # away every edit made here — including the ``stream`` flip
+                # below. Taking the buffered path anyway asks upstream for a
+                # stream:true reply and then tries to read it as buffered JSON:
+                # the parse fails, SSE resynthesis is skipped, and the client
+                # gets a 200 with no usable body (#2952). The retrieve tool is
+                # itself an injected (and equally discarded) mutation on these
+                # turns, so the plain streaming path is the coherent choice.
+                from headroom.proxy.body_forwarding import outbound_body_is_client_bytes
+
+                outbound_locked_to_client_bytes = outbound_body_is_client_bytes(
+                    body=body,
+                    original_body_bytes=original_body_bytes,
+                )
+                wants_buffered_stream_ccr = bool(
                     stream
                     and ccr_response_handler_enabled
                     and self._has_headroom_retrieve_tool(
                         tools if tools is not None else body.get("tools")
                     )
                 )
+                buffered_stream_ccr = (
+                    wants_buffered_stream_ccr and not outbound_locked_to_client_bytes
+                )
+                if wants_buffered_stream_ccr and outbound_locked_to_client_bytes:
+                    logger.info(
+                        f"[{request_id}] CCR: signed thinking blocks force byte-faithful "
+                        "passthrough, so a stream:false flip could not reach upstream; "
+                        "using the plain streaming path instead of buffered retrieval"
+                    )
                 if buffered_stream_ccr:
                     if body.get("stream") is not False:
                         body["stream"] = False
@@ -2894,6 +3339,46 @@ class AnthropicHandlerMixin:
                         "upstream request for server-side retrieval handling"
                     )
 
+                # Last stop before the wire. Every transform, the tool sort, the
+                # tool-search deferral, CCR injection and the pipeline
+                # extensions have run, so this is the only place that can see
+                # the cache_control markers Anthropic will actually evaluate --
+                # and the ordering rule spans tools/system/messages, which no
+                # single transform is in a position to check (#2939).
+                from headroom.proxy.helpers import (
+                    enforce_cache_control_ttl_order,
+                    log_cache_breakpoints,
+                )
+
+                (
+                    _ttl_system,
+                    _ttl_messages,
+                    _ttl_tools,
+                    _ttl_stats,
+                ) = enforce_cache_control_ttl_order(
+                    body.get("system"),
+                    body.get("messages"),
+                    body.get("tools"),
+                    client_uses_1h=client_uses_1h,
+                    request_id=request_id,
+                )
+                if _ttl_stats["violation"]:
+                    if body.get("system") is not None:
+                        body["system"] = _ttl_system
+                    body["messages"] = _ttl_messages
+                    if body.get("tools") is not None:
+                        body["tools"] = _ttl_tools
+                    tools = _ttl_tools
+                    body_mutation_tracker.mark_mutated("cache_control_ttl_order")
+
+                log_cache_breakpoints(
+                    request_id=request_id,
+                    inbound=inbound_breakpoints,
+                    outbound=count_cache_breakpoints(
+                        body.get("system"), body.get("messages"), body.get("tools")
+                    ),
+                )
+
                 if stream and not buffered_stream_ccr:
                     self.pipeline_extensions.emit(
                         PipelineStage.POST_SEND,
@@ -2911,11 +3396,18 @@ class AnthropicHandlerMixin:
                         body,
                         session_header=explicit_session_header,
                     )
-                    # Only opt-in (header-bearing) callers participate in
-                    # mid-turn steering; see StreamingMixin._should_queue_mid_turn
-                    # for why the coarse md5 fallback must not queue concurrent
-                    # independent streams (it wrongly 202s a streaming caller).
-                    if self._should_queue_mid_turn(session_key, explicit_session_header):
+                    # Coalesce mid-turn messages only for Claude Code, the sole
+                    # client that understands the 202 `headroom_queued` reply and
+                    # the `headroom_pending_messages` SSE event. Other harnesses
+                    # (e.g. OpenCode subagents sharing a body-derived session key)
+                    # would otherwise have their request swallowed and never
+                    # answered. (#1608) `_should_queue_mid_turn` further restricts
+                    # this to opt-in (header-bearing) callers with an active
+                    # stream, so the coarse md5 fallback can't 202 a streaming
+                    # caller.
+                    if supports_mid_turn_coalescing(
+                        classify_client(request.headers)
+                    ) and self._should_queue_mid_turn(session_key, explicit_session_header):
                         from fastapi.responses import JSONResponse
 
                         queued = self._queue_mid_turn_message(session_key, body)
@@ -3117,9 +3609,23 @@ class AnthropicHandlerMixin:
                         try:
                             resp_json = response.json()
                         except (json.JSONDecodeError, ValueError) as e:
-                            logger.debug(
-                                f"[{request_id}] Failed to parse response JSON for CCR handling: {e}"
-                            )
+                            # DEBUG is right for the buffered non-stream path, where
+                            # an unparseable body is just "no CCR handling". On the
+                            # buffered-stream path it means the reply came back in a
+                            # wire format we did not ask for, and every downstream
+                            # step (retrieval, SSE resynthesis, usage accounting)
+                            # silently no-ops — that has to be visible (#2952).
+                            if buffered_stream_ccr:
+                                logger.warning(
+                                    f"[{request_id}] CCR: buffered stream:false request got a "
+                                    f"non-JSON {response.status_code} reply "
+                                    f"(content-type={response.headers.get('content-type')!r}): {e}"
+                                )
+                            else:
+                                logger.debug(
+                                    f"[{request_id}] Failed to parse response JSON for CCR "
+                                    f"handling: {e}"
+                                )
 
                         # CCR Response Handling: Handle headroom_retrieve tool calls automatically
                         if (
@@ -3228,26 +3734,6 @@ class AnthropicHandlerMixin:
                                 )
                                 # Update response content with final response
                                 resp_json = final_resp_json
-                                # Turn hooks (opt-in extensions) may inspect the turn or
-                                # re-drive the model before we hand back the response.
-                                # Inert when no hook is registered.
-                                from headroom.proxy.turn_hooks import (
-                                    TurnContext,
-                                    run_response_hooks,
-                                )
-
-                                final_resp_json = await run_response_hooks(
-                                    TurnContext(
-                                        provider="anthropic",
-                                        model=str(model),
-                                        messages=optimized_messages,
-                                        tools=tools,
-                                        config=self.config,
-                                    ),
-                                    final_resp_json,
-                                    api_call_fn,
-                                )
-                                resp_json = final_resp_json
                                 # Remove encoding headers since content is now uncompressed JSON
                                 ccr_response_headers = {
                                     k: v
@@ -3361,6 +3847,47 @@ class AnthropicHandlerMixin:
                                 )
                                 # Continue with original response
 
+                        # Buffered response hooks run for every successful turn,
+                        # not only the CCR branch. Reuse the request context so
+                        # observers close the exact turn they opened and a
+                        # search/reload hook can consume its synthetic tool call.
+                        _hook_usage = _AnthropicTurnHookUsage()
+                        if _req_ctx is not None and resp_json and response.status_code == 200:
+                            from headroom.proxy.turn_hooks import run_response_hooks
+
+                            _hook_usage.record(resp_json)
+
+                            async def _turn_hook_call_model(
+                                hook_messages: list[dict[str, Any]],
+                            ) -> dict[str, Any]:
+                                continuation_body = {**body, "messages": hook_messages}
+                                continuation_response = await self._retry_request(
+                                    "POST",
+                                    url,
+                                    headers,
+                                    continuation_body,
+                                    timeout=self._anthropic_buffered_request_timeout(),
+                                )
+                                continuation_json = continuation_response.json()
+                                _hook_usage.record(continuation_json)
+                                return continuation_json
+
+                            hooked_json = await run_response_hooks(
+                                _req_ctx, resp_json, _turn_hook_call_model
+                            )
+                            _hook_usage.settle(hooked_json)
+                            if hooked_json is not resp_json:
+                                resp_json = hooked_json
+                                response = httpx.Response(
+                                    status_code=200,
+                                    content=json.dumps(resp_json).encode(),
+                                    headers={
+                                        key: value
+                                        for key, value in response.headers.items()
+                                        if key.lower() not in ("content-encoding", "content-length")
+                                    },
+                                )
+
                         total_latency = (time.time() - start_time) * 1000
 
                         # Parse response for output token count and cache metrics
@@ -3372,13 +3899,24 @@ class AnthropicHandlerMixin:
                         uncached_input_tokens = 0
                         if resp_json:
                             usage = resp_json.get("usage", {})
-                            output_tokens = usage.get("output_tokens", 0)
-                            cr_tokens = usage.get("cache_read_input_tokens", 0)
-                            cw_tokens = usage.get("cache_creation_input_tokens", 0)
+                            output_tokens = int(usage.get("output_tokens", 0) or 0)
+                            output_tokens += _hook_usage.output_tokens
+                            cr_tokens = int(usage.get("cache_read_input_tokens", 0) or 0)
+                            cr_tokens += _hook_usage.cache_read_tokens
+                            cw_tokens = int(usage.get("cache_creation_input_tokens", 0) or 0)
+                            cw_tokens += _hook_usage.cache_write_tokens
                             cw_5m_tokens, cw_1h_tokens = self._extract_anthropic_cache_ttl_metrics(
                                 usage
                             )
-                            uncached_input_tokens = usage.get("input_tokens", 0)
+                            cw_5m_tokens += _hook_usage.cache_write_5m_tokens
+                            cw_1h_tokens += _hook_usage.cache_write_1h_tokens
+                            uncached_input_tokens = int(usage.get("input_tokens", 0) or 0)
+                            uncached_input_tokens += max(
+                                0,
+                                _hook_usage.input_tokens
+                                - _hook_usage.cache_read_tokens
+                                - _hook_usage.cache_write_tokens,
+                            )
 
                         # Track cache bust: tokens that lost their cache discount due to compression.
                         # If we had X tokens cached last turn and only Y hit cache this turn,
@@ -3447,7 +3985,13 @@ class AnthropicHandlerMixin:
                         # Cache response under the SAME key it was looked up by:
                         # cache_lookup_messages is the raw pre-mutation snapshot, not
                         # the live (compressed/hooked) `messages` (#327).
-                        if self.cache and response.status_code == 200:
+                        # ``resp_json`` is None when the reply did not parse as
+                        # JSON — an SSE stream, most often. Caching those bytes
+                        # poisons the entry for every later caller that shares
+                        # the key: the cache key has no ``stream`` component, so
+                        # a buffered request would be answered with a stream it
+                        # cannot read (#2952).
+                        if self.cache and response.status_code == 200 and resp_json is not None:
                             await self.cache.set(
                                 cache_lookup_messages,
                                 model,
@@ -3504,6 +4048,9 @@ class AnthropicHandlerMixin:
                                 status_code=response.status_code,
                                 original_tokens=original_tokens,
                                 optimized_tokens=optimized_tokens,
+                                provider_input_tokens=(
+                                    uncached_input_tokens + cr_tokens + cw_tokens
+                                ),
                                 output_tokens=output_tokens,
                                 tokens_saved=tokens_saved,
                                 attempted_input_tokens=optimized_tokens + tokens_saved,
@@ -3559,6 +4106,26 @@ class AnthropicHandlerMixin:
                         if _compression_failed:
                             response_headers["x-headroom-compression-failed"] = "true"
 
+                        # Inline CCR marker resolution, non-streaming only.
+                        # Deliberately OUTSIDE the has_ccr_tool_calls gate
+                        # above: the callers this flag exists for (#2509,
+                        # Headroom behind a LiteLLM guardrail hop) never get
+                        # a headroom_retrieve tool-call turn, so gating on
+                        # one makes the flag a no-op for its own use case.
+                        # Runs before the security scan so the scanner sees
+                        # the resolved text, not the marker.
+                        if (
+                            getattr(self.config, "ccr_resolve_markers_inline", False)
+                            and resp_json
+                            and response.status_code == 200
+                        ):
+                            resp_json = resolve_markers_in_response(resp_json)
+                            response = httpx.Response(
+                                status_code=200,
+                                content=json.dumps(resp_json).encode(),
+                                headers=response_headers,
+                            )
+
                         # Enterprise Security: scan response + de-anonymize.
                         # Gate on a 200 upstream like the sibling CCR/cache/buffered
                         # blocks below: without this, a non-2xx upstream (rate limit
@@ -3590,6 +4157,63 @@ class AnthropicHandlerMixin:
                                     f"[{request_id}] Security response scan error: {sec_err}"
                                 )
 
+                        if (
+                            buffered_stream_ccr
+                            and response.status_code == 200
+                            and not resp_json
+                            and _looks_like_sse_response(response)
+                        ):
+                            # Upstream streamed instead of buffering, so there is
+                            # nothing to resynthesize — but the client asked for a
+                            # stream and this already is one. Relay it verbatim
+                            # rather than falling through to a plain Response the
+                            # _BufferedCCRResponse wrapper can only turn into a bare
+                            # error event (#2952).
+                            logger.warning(
+                                f"[{request_id}] CCR: relaying the upstream SSE reply verbatim; "
+                                "server-side retrieval was skipped for this turn"
+                            )
+                            relay_headers = {
+                                k: v
+                                for k, v in response_headers.items()
+                                if k.lower()
+                                not in (
+                                    "content-encoding",
+                                    "content-length",
+                                    "transfer-encoding",
+                                    "content-type",
+                                )
+                            }
+                            relayed_sse = response.content
+
+                            async def _upstream_sse_relay():
+                                yield relayed_sse
+
+                            return StreamingResponse(
+                                _upstream_sse_relay(),
+                                media_type="text/event-stream",
+                                headers=relay_headers,
+                            )
+
+                        if buffered_stream_ccr and response.status_code == 200 and not resp_json:
+                            logger.warning(
+                                f"[{request_id}] CCR: rejecting malformed buffered 200 reply "
+                                f"(content-type={response.headers.get('content-type')!r}, "
+                                f"body_bytes={len(response.content)})"
+                            )
+                            return Response(
+                                content=json.dumps(
+                                    {
+                                        "error": {
+                                            "type": "upstream_protocol_error",
+                                            "message": "Upstream returned an invalid buffered response.",
+                                        }
+                                    }
+                                ),
+                                status_code=502,
+                                media_type="application/json",
+                            )
+
                         if buffered_stream_ccr and response.status_code == 200 and resp_json:
                             sse_headers = {
                                 k: v
@@ -3688,122 +4312,50 @@ class AnthropicHandlerMixin:
 
                     class _BufferedCCRResponse(Response):
                         async def __call__(self, scope, receive, send):  # noqa: ANN001
-                            await asyncio.sleep(0)
-                            loop = asyncio.get_running_loop()
-                            keepalive_deadline = loop.time() + 1.0
-                            started = False
+                            # Send nothing until the buffered operation resolves.
+                            # The previous keepalive preamble committed
+                            # `200 text/event-stream` after 1s, i.e. before the
+                            # outcome was known: any upstream reply that then
+                            # failed to become SSE (non-200, unparseable body)
+                            # reached the client as a 200 whose body carried no
+                            # `message_start`, which Claude Code reports as "API
+                            # returned an empty or malformed response (HTTP 200) —
+                            # check for a proxy or gateway intercepting the
+                            # request". The real status was lost with it, so
+                            # client-side 429/5xx backoff never fired. Clients
+                            # budget minutes for a turn (Claude Code sends
+                            # `x-stainless-timeout: 600`), so waiting is free.
                             try:
-                                while True:
-                                    timeout = (
-                                        0.25
-                                        if started
-                                        else max(0.0, keepalive_deadline - loop.time())
-                                    )
-                                    done, _ = await asyncio.wait({operation}, timeout=timeout)
-                                    if done:
-                                        try:
-                                            result = operation.result()
-                                        except Exception as e:
-                                            await record_failed(provider=provider_name)
-                                            logger.error(
-                                                f"[{request_id}] Request failed: {type(e).__name__}: {e}"
-                                            )
-                                            if not started:
-                                                await send(
-                                                    {
-                                                        "type": "http.response.start",
-                                                        "status": 502,
-                                                        "headers": [
-                                                            (b"content-type", b"application/json")
-                                                        ],
-                                                    }
-                                                )
-                                                await send(
-                                                    {
-                                                        "type": "http.response.body",
-                                                        "body": json.dumps(
-                                                            {
-                                                                "type": "error",
-                                                                "error": {
-                                                                    "type": "api_error",
-                                                                    "message": "An error occurred while processing your request. Please try again.",
-                                                                },
-                                                            }
-                                                        ).encode(),
-                                                        "more_body": False,
-                                                    }
-                                                )
-                                                return
-                                            await send(
-                                                {
-                                                    "type": "http.response.body",
-                                                    "body": b'event: error\ndata: {"type":"error","error":{"type":"api_error","message":"An error occurred while processing the request."}}\n\n',
-                                                    "more_body": False,
-                                                }
-                                            )
-                                            return
-
-                                        if not started:
-                                            await result(scope, receive, send)
-                                            return
-
-                                        body_iterator = getattr(result, "body_iterator", None)
-                                        if body_iterator is not None:
-                                            async for chunk in body_iterator:
-                                                await send(
-                                                    {
-                                                        "type": "http.response.body",
-                                                        "body": chunk,
-                                                        "more_body": True,
-                                                    }
-                                                )
-                                            await send(
-                                                {
-                                                    "type": "http.response.body",
-                                                    "body": b"",
-                                                    "more_body": False,
-                                                }
-                                            )
-                                            return
-
-                                        await send(
+                                result = await operation
+                            except Exception as e:
+                                await record_failed(provider=provider_name)
+                                logger.error(
+                                    f"[{request_id}] Request failed: {type(e).__name__}: {e}"
+                                )
+                                await send(
+                                    {
+                                        "type": "http.response.start",
+                                        "status": 502,
+                                        "headers": [(b"content-type", b"application/json")],
+                                    }
+                                )
+                                await send(
+                                    {
+                                        "type": "http.response.body",
+                                        "body": json.dumps(
                                             {
-                                                "type": "http.response.body",
-                                                "body": b'event: error\ndata: {"type":"error","error":{"type":"api_error","message":"An error occurred while processing the request."}}\n\n',
-                                                "more_body": False,
+                                                "type": "error",
+                                                "error": {
+                                                    "type": "api_error",
+                                                    "message": "An error occurred while processing your request. Please try again.",
+                                                },
                                             }
-                                        )
-                                        return
-
-                                    if not started:
-                                        await send(
-                                            {
-                                                "type": "http.response.start",
-                                                "status": 200,
-                                                "headers": [
-                                                    (b"content-type", b"text/event-stream")
-                                                ],
-                                            }
-                                        )
-                                        started = True
-                                    await send(
-                                        {
-                                            "type": "http.response.body",
-                                            "body": b'event: ping\ndata: {"type":"ping"}\n\n',
-                                            "more_body": True,
-                                        }
-                                    )
-                            except asyncio.CancelledError:
-                                raise
-                            finally:
-                                if not operation.done():
-                                    operation.cancel()
-                                try:
-                                    await operation
-                                except asyncio.CancelledError:
-                                    pass
-                                except Exception:
-                                    pass
+                                        ).encode(),
+                                        "more_body": False,
+                                    }
+                                )
+                                return
+                            await result(scope, receive, send)
 
                     return _BufferedCCRResponse(media_type="text/event-stream")
                 return await _buffered_ccr_operation()
diff --git a/headroom/proxy/handlers/batch.py b/headroom/proxy/handlers/batch.py
index 3681294a4..91c23f640 100644
--- a/headroom/proxy/handlers/batch.py
+++ b/headroom/proxy/handlers/batch.py
@@ -1104,7 +1104,18 @@ class BatchHandlerMixin:
 
             try:
                 request_obj = json.loads(line)
+                # A JSONL line can be valid JSON that isn't a request object
+                # (e.g. a stray array, string, or null). `.get` on it would raise
+                # AttributeError, which the outer `except json.JSONDecodeError`
+                # below does not catch — crashing the whole batch. Pass such lines
+                # through unchanged, like the other non-compressible cases.
+                if not isinstance(request_obj, dict):
+                    compressed_lines.append(line)
+                    total_requests += 1
+                    continue
                 body = request_obj.get("body", {})
+                if not isinstance(body, dict):
+                    body = {}
                 messages = body.get("messages", [])
                 model = body.get("model", "gpt-4")
 
diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.py
index 199a79fd1..3311fe69c 100644
--- a/headroom/proxy/handlers/gemini.py
+++ b/headroom/proxy/handlers/gemini.py
@@ -36,6 +36,14 @@ def _usage_int(value: Any, default: int = 0) -> int:
     return int(value)
 
 
+class _GeminiContinuationError(Exception):
+    def __init__(self, status_code: int, content: bytes, headers: dict[str, str]) -> None:
+        super().__init__(f"Gemini continuation failed with HTTP {status_code}")
+        self.status_code = status_code
+        self.content = content
+        self.headers = headers
+
+
 class GeminiHandlerMixin:
     """Mixin providing Gemini API handler methods for HeadroomProxy."""
 
@@ -630,6 +638,68 @@ class GeminiHandlerMixin:
             except Exception as e:
                 logger.warning(f"[{request_id}] Memory injection failed (gemini): {e}")
 
+        query_params = dict(request.query_params)
+        is_streaming = query_params.get("alt") == "sse" or request.url.path.endswith(
+            ":streamGenerateContent"
+        )
+        native_tools = body.get("tools")
+        native_function_declarations = None
+
+        def rebuild_tools(function_declarations: list[dict]) -> list[dict]:
+            rebuilt_tools = []
+            replaced = False
+            declaration_tools = [
+                tool for tool in body.get("tools") or [] if "functionDeclarations" in tool
+            ]
+            later_names = {
+                declaration.get("name")
+                for tool in declaration_tools[1:]
+                for declaration in tool["functionDeclarations"]
+            }
+            first_declarations = [
+                declaration
+                for declaration in function_declarations
+                if declaration.get("name") not in later_names
+            ]
+            for tool in body.get("tools") or []:
+                if "functionDeclarations" in tool and not replaced:
+                    rebuilt_tools.append({**tool, "functionDeclarations": first_declarations})
+                    replaced = True
+                else:
+                    rebuilt_tools.append(tool)
+            if not replaced:
+                rebuilt_tools.append({"functionDeclarations": function_declarations})
+            return rebuilt_tools
+
+        ccr_inject_tool = getattr(self.config, "ccr_inject_tool", True)
+        ccr_inject_system_instructions = getattr(
+            self.config, "ccr_inject_system_instructions", False
+        )
+        if ccr_inject_tool and tokens_saved > 0 and not is_streaming:
+            from headroom.ccr import CCRToolInjector
+
+            seen_names = set()
+            native_function_declarations = []
+            for tool in native_tools or []:
+                for declaration in tool.get("functionDeclarations", []):
+                    name = declaration.get("name")
+                    if name not in seen_names:
+                        native_function_declarations.append(declaration)
+                        seen_names.add(name)
+            injector = CCRToolInjector(
+                provider="google",
+                inject_tool=True,
+                inject_system_instructions=ccr_inject_system_instructions,
+            )
+            optimized_messages, injected_funcs, was_injected = injector.process_request(
+                optimized_messages, native_function_declarations
+            )
+            if was_injected:
+                native_function_declarations = injected_funcs
+                body["tools"] = rebuild_tools(injected_funcs)
+            elif native_function_declarations is not None:
+                native_function_declarations = list(native_function_declarations)
+
         # Convert back to Gemini format if optimized
         if optimized_messages != messages:
             optimized_contents, optimized_system = self._messages_to_gemini_contents(
@@ -644,12 +714,6 @@ class GeminiHandlerMixin:
             elif "systemInstruction" in body:
                 del body["systemInstruction"]
 
-        # Check if streaming requested via query param
-        query_params = dict(request.query_params)
-        is_streaming = query_params.get("alt") == "sse" or request.url.path.endswith(
-            ":streamGenerateContent"
-        )
-
         # Build URL - model is extracted from path. Vertex publisher
         # routes use the request's full path under the Vertex base URL;
         # native Gemini uses the public Gemini API shape.
@@ -703,6 +767,8 @@ class GeminiHandlerMixin:
                 total_input_tokens = optimized_tokens  # fallback
                 output_tokens = 0
                 cache_read_tokens = 0
+                resp_json = None
+                response_content = response.content
                 try:
                     resp_json = response.json()
                     usage = resp_json.get("usageMetadata", {})
@@ -736,8 +802,97 @@ class GeminiHandlerMixin:
                         f"[{request_id}] Failed to extract cached tokens from Gemini response: {e}"
                     )
 
+                if (
+                    response.status_code == 200
+                    and isinstance(resp_json, dict)
+                    and self.ccr_response_handler
+                    and getattr(getattr(self.ccr_response_handler, "config", None), "enabled", True)
+                    and self.ccr_response_handler.has_ccr_tool_calls(resp_json, "google")
+                ):
+
+                    async def api_call_fn(
+                        native_contents: list[dict],
+                        function_declarations: list[dict] | None,
+                    ) -> dict[str, Any]:
+                        continuation_body = {**body, "contents": native_contents}
+                        if function_declarations is not None:
+                            continuation_body["tools"] = rebuild_tools(function_declarations)
+                        continuation_headers = {
+                            key: value
+                            for key, value in headers.items()
+                            if key.lower()
+                            not in ("accept-encoding", "content-encoding", "content-length")
+                        }
+                        continuation = await self._retry_request(
+                            "POST", url, continuation_headers, continuation_body
+                        )
+                        if continuation.status_code >= 400:
+                            return {
+                                "_headroom_continuation_error": {
+                                    "status_code": continuation.status_code,
+                                    "content": continuation.content,
+                                    "headers": dict(continuation.headers),
+                                }
+                            }
+                        try:
+                            return continuation.json()
+                        except (json.JSONDecodeError, ValueError, TypeError):
+                            return {
+                                "_headroom_continuation_error": {
+                                    "status_code": continuation.status_code,
+                                    "content": continuation.content,
+                                    "headers": dict(continuation.headers),
+                                }
+                            }
+
+                    final_resp_json = await self.ccr_response_handler.handle_response(
+                        resp_json,
+                        body.get("contents", []),
+                        native_function_declarations,
+                        api_call_fn,
+                        provider="google",
+                    )
+                    continuation_error = final_resp_json.get("_headroom_continuation_error")
+                    if isinstance(continuation_error, dict):
+                        raise _GeminiContinuationError(
+                            continuation_error["status_code"],
+                            continuation_error["content"],
+                            continuation_error["headers"],
+                        )
+                    from headroom.ccr.response_handler import RESIDUAL_CCR_ERROR
+
+                    if (
+                        self.ccr_response_handler.residual_ccr_status(final_resp_json, "google")
+                        == RESIDUAL_CCR_ERROR
+                    ):
+                        raise RuntimeError("Gemini CCR continuation left an unresolved retrieval")
+                    resp_json = final_resp_json
+                    response_content = json.dumps(resp_json).encode()
+                    usage = resp_json.get("usageMetadata", {})
+                    total_input_tokens = usage.get("promptTokenCount", total_input_tokens)
+                    output_tokens = usage.get("candidatesTokenCount", output_tokens)
+                    cache_read_tokens = usage.get("cachedContentTokenCount", cache_read_tokens)
+
                 uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)
 
+                # optimized_tokens carries Gemini's own promptTokenCount, which is
+                # on the provider's tokenizer scale (it feeds billing/dashboard),
+                # while original_tokens is a LOCAL estimator count. When Gemini
+                # counts the forwarded prompt higher than our estimator does,
+                # attempted_input_tokens (optimized + saved) exceeded the local
+                # original_tokens and shipped a structurally-impossible
+                # eligible_pct > 100 plus a phantom tokens_inflated. Lift the
+                # baseline onto the provider scale when a provider count is
+                # present, mirroring the streaming finalizer's tested handling in
+                # _finalize_stream_response so the two Gemini paths agree. Guarded
+                # on a present count so a null/absent promptTokenCount leaves the
+                # local baseline untouched.
+                effective_original_tokens = (
+                    max(original_tokens, total_input_tokens + tokens_saved)
+                    if total_input_tokens > 0
+                    else original_tokens
+                )
+
                 # Eligible-tracking is TODO for Gemini; pass the full
                 # pre-compression request size as the fallback denominator.
                 # This makes Gemini's contribution to the aggregate
@@ -757,7 +912,7 @@ class GeminiHandlerMixin:
                     provider=provider_name,
                     model=model,
                     status_code=response.status_code,
-                    original_tokens=original_tokens,
+                    original_tokens=effective_original_tokens,
                     optimized_tokens=total_input_tokens,
                     output_tokens=output_tokens,
                     tokens_saved=tokens_saved,
@@ -804,10 +959,16 @@ class GeminiHandlerMixin:
                     response_headers["x-headroom-compression-failed"] = "true"
 
                 return Response(
-                    content=response.content,
+                    content=response_content,
                     status_code=response.status_code,
                     headers=response_headers,
                 )
+        except _GeminiContinuationError as e:
+            await self.metrics.record_failed(provider=provider_name)
+            response_headers = dict(e.headers)
+            response_headers.pop("content-encoding", None)
+            response_headers.pop("content-length", None)
+            return Response(content=e.content, status_code=e.status_code, headers=response_headers)
         except Exception as e:
             await self.metrics.record_failed(provider=provider_name)
             logger.error(f"[{request_id}] Gemini request failed: {type(e).__name__}: {e}")
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index dd12a2290..c011b4984 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -12,6 +12,7 @@ import hashlib
 import json
 import logging
 import os
+import re
 import threading
 import time
 import uuid
@@ -44,6 +45,7 @@ if TYPE_CHECKING:
 import httpx
 
 from headroom.agent_savings import proxy_pipeline_kwargs
+from headroom.ccr.marker_resolution import resolve_markers_in_response
 from headroom.config import unwrap_tool_call_name
 from headroom.copilot_auth import (
     apply_copilot_api_auth,
@@ -94,6 +96,45 @@ _OPENAI_RESPONSES_UNIT_CACHE_INIT_LOCK = threading.RLock()
 _OPENAI_RESPONSES_UNIT_EXECUTOR_LOCK = threading.RLock()
 _OPENAI_RESPONSES_UNIT_EXECUTOR: ThreadPoolExecutor | None = None
 _CODEX_WS_COMPRESSION_TIMEOUT_SECONDS = 5.0
+_CCR_HASH_RE = re.compile(
+    r"(?:Retrieve (?:more|original): hash=|<<ccr:)([a-fA-F0-9]{12,24})(?=[^a-fA-F0-9]|$)"
+)
+_BARE_CCR_HASH_RE = re.compile(r"[a-fA-F0-9]{12,24}")
+
+
+def _response_ccr_hashes(messages: list[dict[str, Any]], markers: list[str]) -> list[str]:
+    """Return the distinct retrievable CCR hashes exposed by a response.
+
+    ``TransformResult.markers_inserted`` is not a hash-only collection: it can
+    also contain tool-digest and stable-prefix metadata. Extract only supported
+    CCR retrieval markers, then scan the rendered messages because row-drop and
+    recursive JSON paths can embed a marker without registering it separately.
+    """
+    hashes: list[str] = []
+    seen: set[str] = set()
+
+    def collect(value: Any, *, allow_bare_hash: bool = False) -> None:
+        if isinstance(value, str):
+            candidates = [value] if allow_bare_hash and _BARE_CCR_HASH_RE.fullmatch(value) else []
+            candidates.extend(match.group(1) for match in _CCR_HASH_RE.finditer(value))
+            for candidate in candidates:
+                normalized = candidate.lower()
+                if normalized not in seen:
+                    seen.add(normalized)
+                    hashes.append(normalized)
+            return
+        if isinstance(value, dict):
+            for child in value.values():
+                collect(child)
+            return
+        if isinstance(value, list):
+            for child in value:
+                collect(child)
+
+    for marker in markers:
+        collect(marker, allow_bare_hash=True)
+    collect(messages)
+    return hashes
 
 
 def _codex_ws_compression_timeout_seconds() -> float:
@@ -187,6 +228,101 @@ def _header_get(headers: dict[str, str], name: str) -> str | None:
     return None
 
 
+#: Usage field names per OpenAI surface. Same three quantities, two spellings.
+CHAT_USAGE_KEYS = {
+    "input_key": "prompt_tokens",
+    "output_key": "completion_tokens",
+    "details_key": "prompt_tokens_details",
+}
+RESPONSES_USAGE_KEYS = {
+    "input_key": "input_tokens",
+    "output_key": "output_tokens",
+    "details_key": "input_tokens_details",
+}
+
+
+class TurnHookUsage:
+    """Upstream calls a turn hook caused that nothing else will account for.
+
+    A hook that re-drives the model (``call_model``) makes real, billed requests.
+    The handler's usage block reads exactly ONE response — the original, or
+    whichever the hook returned in its place, because the handler swaps
+    ``response`` for it. Every other upstream call on that turn is spend no
+    surface records.
+
+    The protocol is therefore two-sided, and both halves are required:
+
+    * :meth:`record` every upstream response as it arrives, original included.
+    * :meth:`settle` with the response the usage block will read.
+
+    ``settle`` removes that one response's contribution, so what remains is
+    exactly the delta the handler must add. Recording only the re-drives and
+    adding them unconditionally — the first version of this — double-counted the
+    re-drive the handler had just promoted to ``response`` and dropped the
+    original entirely: one re-drive billed ``B + B`` instead of ``A + B``.
+
+    Matching is by object identity, because the handler hands back the very
+    object it recorded. A hook that synthesises a brand new response matches
+    nothing and nothing is subtracted, which over-counts rather than under —
+    the safe direction for a bill.
+    """
+
+    __slots__ = ("_seen", "input_tokens", "output_tokens", "cache_read_tokens", "extra_calls")
+
+    def __init__(self) -> None:
+        self._seen: list[tuple[int, Any, int, int, int]] = []
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.cache_read_tokens = 0
+        self.extra_calls = 0
+
+    def record(
+        self,
+        payload: Any,
+        *,
+        input_key: str,
+        output_key: str,
+        details_key: str,
+    ) -> None:
+        """Note one upstream response. Never raises: a hook must not be able to
+        500 a request by returning an odd shape."""
+        usage = payload.get("usage") if isinstance(payload, dict) else None
+
+        def _int(value: Any) -> int:
+            try:
+                return max(int(value), 0)
+            except (TypeError, ValueError):
+                return 0
+
+        if isinstance(usage, dict):
+            details = usage.get(details_key)
+            cached = _int(details.get("cached_tokens")) if isinstance(details, dict) else 0
+            entry = (
+                id(payload),
+                payload,
+                _int(usage.get(input_key)),
+                _int(usage.get(output_key)),
+                cached,
+            )
+        else:
+            entry = (id(payload), payload, 0, 0, 0)
+        self._seen.append(entry)
+
+    def settle(self, final: Any) -> None:
+        """Total everything except ``final``, which the usage block will read."""
+        self.input_tokens = self.output_tokens = self.cache_read_tokens = 0
+        self.extra_calls = 0
+        dropped = False
+        for _ident, payload, tin, tout, cached in self._seen:
+            if not dropped and payload is final:
+                dropped = True
+                continue
+            self.extra_calls += 1
+            self.input_tokens += tin
+            self.output_tokens += tout
+            self.cache_read_tokens += cached
+
+
 def _sanitize_forwarded_response_headers(
     headers: httpx.Headers | dict[str, str],
     *extra_names: str,
@@ -538,6 +674,7 @@ def _shape_openai_responses_payload(
     *,
     model: str,
     request_id: str,
+    output_shaper_enabled: bool | None = None,
 ) -> tuple[list[str], bool]:
     """Output shaping for a Responses payload (opt-in, HEADROOM_OUTPUT_SHAPER).
 
@@ -568,7 +705,7 @@ def _shape_openai_responses_payload(
             shape_responses_request,
         )
 
-        settings = OutputShaperSettings.from_env()
+        settings = OutputShaperSettings.from_env(enabled=output_shaper_enabled)
         if not settings.enabled:
             return [], False
 
@@ -626,36 +763,9 @@ def _compact_openai_responses_tools(
     return compact_tools(payload)
 
 
-def _responses_request_allows_memory_tool_continuation(payload: dict[str, Any]) -> bool:
-    """Return whether Responses memory tools may rely on stored continuations.
-
-    Headroom memory tools use ``previous_response_id`` continuations after a
-    tool call. Those continuations require the originating response to be
-    stored. When a client explicitly sends ``store=false``, preserve that
-    contract and skip the Responses memory-tool injection path instead of
-    mutating the request.
-    """
-
-    return payload.get("store") is not False
-
-
-def _ensure_responses_store_for_memory_tools(
-    payload: dict[str, Any],
-    *,
-    memory_tools_injected: bool,
-) -> bool:
-    """Return True when memory-tool injection requires and receives store=true."""
-
-    if memory_tools_injected and payload.get("store") is not True:
-        payload["store"] = True
-        return True
-    return False
-
-
 def _allow_responses_memory_tools(is_chatgpt_auth: bool) -> bool:
-    # ChatGPT Codex rejects Responses payloads unless store=false. The
-    # transparent memory-tool continuation flow needs stored responses, so keep
-    # it on the regular API path only.
+    # Preserve the ChatGPT Codex route's existing store policy and memory-tool
+    # exclusion while API Responses memory continuations stay stateless.
     return not is_chatgpt_auth
 
 
@@ -884,6 +994,18 @@ def _should_buffer_openai_responses_stream_ccr(
     )
 
 
+def _should_inject_openai_chat_ccr_tool(*, ccr_inject_tool: bool, stream: bool) -> bool:
+    """Return whether chat-completions can redeem an injected CCR tool.
+
+    The chat streaming path forwards SSE events immediately and deliberately
+    does not run the response continuation loop. Injecting ``headroom_retrieve``
+    there makes OpenAI-compatible clients attempt an unknown tool call. The
+    non-streaming path can intercept and resolve it; Responses streaming has a
+    separate buffered-CCR path and is unaffected by this predicate.
+    """
+    return bool(ccr_inject_tool and not stream)
+
+
 def _responses_input_to_items(input_data: Any) -> list[dict[str, Any]]:
     """Normalize a Responses ``input`` field into an item list for CCR continuation.
 
@@ -898,6 +1020,23 @@ def _responses_input_to_items(input_data: Any) -> list[dict[str, Any]]:
     return []
 
 
+def _responses_stateless_output_items(output_items: Any) -> list[dict[str, Any]]:
+    """Return response items that can be replayed without provider state."""
+    if not isinstance(output_items, list):
+        return []
+    return [
+        item
+        for item in output_items
+        if isinstance(item, dict)
+        and not (item.get("type") == "reasoning" and not item.get("encrypted_content"))
+    ]
+
+
+def _responses_stateless_input_items(input_data: Any) -> list[dict[str, Any]]:
+    """Normalize input and remove reasoning items without encrypted content."""
+    return _responses_stateless_output_items(_responses_input_to_items(input_data))
+
+
 def _dedup_responses_output_items(
     items: list[dict[str, Any]],
     output_types: frozenset[str],
@@ -1033,6 +1172,47 @@ def _openai_responses_to_sse(response: dict[str, Any]) -> list[bytes]:
     return events
 
 
+def _openai_responses_from_sse(sse_text: str) -> dict[str, Any] | None:
+    """Reassemble the final Responses API JSON body from an SSE stream.
+
+    Inverse of ``_openai_responses_to_sse``, for upstreams that answer a
+    ``stream: false`` request with a valid ``200 text/event-stream`` body
+    (#2613). The terminal ``response.completed`` event carries the complete
+    response object, so no delta accumulation is needed. Returns ``None``
+    when no terminal event is present — the caller forwards the raw body
+    unchanged in that case.
+    """
+    completed: dict[str, Any] | None = None
+    data_lines: list[str] = []
+
+    def _consume(lines: list[str]) -> None:
+        nonlocal completed
+        if not lines:
+            return
+        data_str = "\n".join(lines)
+        if data_str == "[DONE]":
+            return
+        try:
+            data = json.loads(data_str)
+        except json.JSONDecodeError:
+            return
+        if isinstance(data, dict) and data.get("type") == "response.completed":
+            response = data.get("response")
+            if isinstance(response, dict):
+                completed = response
+
+    for raw_line in sse_text.split("\n"):
+        line = raw_line.rstrip("\r")
+        if not line:
+            _consume(data_lines)
+            data_lines = []
+        elif line.startswith("data:"):
+            # Per the SSE spec, strip at most one leading space after the colon.
+            data_lines.append(line[5:].removeprefix(" "))
+    _consume(data_lines)
+    return completed
+
+
 def _output_shaping_holdout_fraction() -> float:
     from headroom.proxy import runtime_env
 
@@ -1048,6 +1228,7 @@ def _shape_openai_responses_for_output(
     input_tokens: int,
     model: str,
     conversation_key: str | None = None,
+    output_shaper_enabled: bool | None = None,
 ) -> Any:
     """Apply OpenAI Responses output shaping and attach holdout labels."""
     from headroom.proxy.output_savings import (
@@ -1064,7 +1245,7 @@ def _shape_openai_responses_for_output(
         shape_openai_responses_request,
     )
 
-    settings = OutputShaperSettings.from_env()
+    settings = OutputShaperSettings.from_env(enabled=output_shaper_enabled)
     result = ShapeResult()
     if not settings.enabled:
         return result
@@ -1131,6 +1312,7 @@ def _shape_openai_response_create_frame(
     *,
     input_tokens: int,
     conversation_key: str | None = None,
+    output_shaper_enabled: bool | None = None,
 ) -> tuple[str, bool, list[str], str | None]:
     try:
         parsed = json.loads(raw_msg)
@@ -1149,6 +1331,7 @@ def _shape_openai_response_create_frame(
         input_tokens=input_tokens,
         model=str(payload.get("model") or ""),
         conversation_key=conversation_key,
+        output_shaper_enabled=output_shaper_enabled,
     )
     labels = list(result.labels or [])
     if not result.changed:
@@ -1443,6 +1626,72 @@ class OpenAIHandlerMixin:
         except Exception as exc:
             logger.debug("[%s] Traffic learner (chat): %s", request_id, exc)
 
+    async def _observe_openai_ws_response_create(
+        self,
+        inner_payload: dict[str, Any],
+        *,
+        seen_call_ids: set[str],
+        baseline: bool,
+        request_id: str,
+    ) -> None:
+        """Feed one Codex WS ``response.create`` turn into the traffic learner.
+
+        A long-lived Codex WebSocket resends the full transcript on every
+        ``response.create`` (and replays it wholesale on reconnect/resume), so
+        the HTTP one-shot ingestion would count the same tool results as new
+        evidence over and over. This dedups per connection by tool-call id:
+
+        * ``baseline=True`` (the first frame) records the already-present
+          transcript as seen WITHOUT learning from it, so a reconnect that
+          replays old turns adds no spurious evidence.
+        * later frames learn only the tool results whose call id first appears
+          after the baseline, then mark them seen.
+
+        Preference extraction (:meth:`on_messages`) is skipped on the baseline
+        frame and runs on later frames, where it already looks only at the most
+        recent messages (the new turn).
+        """
+        traffic_learner = getattr(self, "traffic_learner", None)
+        if traffic_learner is None:
+            return
+        try:
+            memory_handler = getattr(self, "memory_handler", None)
+            if (
+                traffic_learner._backend is None
+                and memory_handler
+                and memory_handler.initialized
+                and memory_handler.backend
+            ):
+                traffic_learner.set_backend(memory_handler.backend)
+
+            learner_messages = _responses_input_to_learner_messages(
+                inner_payload.get("instructions"),
+                inner_payload.get("input", ""),
+            )
+            tool_results = traffic_learner.extract_tool_results_from_messages(learner_messages)
+            for tool_result in tool_results:
+                call_id = tool_result.get("call_id") or ""
+                # A result already seen on this connection (or baselined) is not
+                # re-learned. Results without an id fall back to learn-once-per
+                # -frame on non-baseline frames (still deduped by the learner's
+                # own pattern accumulation).
+                if call_id:
+                    if call_id in seen_call_ids:
+                        continue
+                    seen_call_ids.add(call_id)
+                if baseline:
+                    continue
+                await traffic_learner.on_tool_result(
+                    tool_name=tool_result["tool_name"],
+                    tool_input=tool_result["input"],
+                    tool_output=tool_result["output"],
+                    is_error=tool_result["is_error"],
+                )
+            if not baseline:
+                await traffic_learner.on_messages(learner_messages)
+        except Exception as exc:
+            logger.debug("[%s] Traffic learner (ws): %s", request_id, exc)
+
     @staticmethod
     def _headroom_bypass_enabled(headers: Any) -> bool:
         """Return True when inbound headers request full passthrough."""
@@ -2219,6 +2468,7 @@ class OpenAIHandlerMixin:
         request_id: str,
         timing: dict[str, float] | None = None,
         client: str | None = None,
+        savings_tags: dict[str, Any] | None = None,
     ) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int]:
         """Compress an OpenAI Responses payload through the shared router.
 
@@ -2365,6 +2615,23 @@ class OpenAIHandlerMixin:
             working["tools"] = _deferred_tools
             modified = True
             transforms.append("openai:responses:tool_search_deferral")
+            try:
+                from headroom.proxy.savings_attribution import record_savings
+
+                deferred = [
+                    tool
+                    for tool in _deferred_tools
+                    if isinstance(tool, dict) and tool.get("defer_loading")
+                ]
+                record_savings(
+                    savings_tags if savings_tags is not None else {},
+                    "tool_search",
+                    tokens=self.openai_provider.get_token_counter(model).count_text(
+                        _json_debug_dumps(deferred)
+                    ),
+                )
+            except Exception:
+                logger.debug("tool-search savings attribution skipped", exc_info=True)
 
         # Turn hooks (opt-in extensions): a registered hook may inspect or rewrite
         # the outbound tools before we send — the extensible counterpart to the
@@ -2403,8 +2670,31 @@ class OpenAIHandlerMixin:
                 messages=_msgs_before,
                 tools=working.get("tools"),
                 config=getattr(self, "config", None),
+                tags=savings_tags if savings_tags is not None else {},
+                count_messages=lambda value: self.openai_provider.get_token_counter(
+                    model
+                ).count_text(_json_debug_dumps(value)),
+                count_tools=lambda value: (
+                    self.openai_provider.get_token_counter(model).count_text(
+                        _json_debug_dumps(value)
+                    )
+                    if value
+                    else 0
+                ),
             )
-            run_request_hooks(_req_ctx)
+            # Streaming turns get fold-only hooks, same rule as the
+            # chat-completions path. A hook that defers work to `on_response`
+            # cannot run here: the response side is wired on the buffered branch
+            # only, so on a real stream the shrink would land with no reload and
+            # the model's injected tool call would be streamed straight to a
+            # client that has no such tool. `stream` is not a parameter of this
+            # method, but the payload it is compressing carries the flag.
+            #
+            # Read before CCR may force `stream:false` further down, so this is
+            # the client's request rather than the effective one — conservative
+            # in the safe direction: at worst a buffered-by-CCR turn misses a
+            # saving, never a stranded tool call.
+            run_request_hooks(_req_ctx, stream_safe_only=bool(payload.get("stream")))
             if _req_ctx.tools is not working.get("tools"):
                 working["tools"] = _req_ctx.tools
             # A hook may also fold the messages (replace or in-place). Write back a
@@ -2561,6 +2851,7 @@ class OpenAIHandlerMixin:
         request_id: str,
         timeout: float = COMPRESSION_TIMEOUT_SECONDS,
         client: str | None = None,
+        savings_tags: dict[str, Any] | None = None,
     ) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int, dict[str, float]]:
         timing: dict[str, float] = {}
 
@@ -2573,7 +2864,16 @@ class OpenAIHandlerMixin:
             # closure so the extra payload serialization stays off the event
             # loop.
             shape_labels, shape_mutated = _shape_openai_responses_payload(
-                payload, model=model, request_id=request_id
+                payload,
+                model=model,
+                request_id=request_id,
+                output_shaper_enabled=(
+                    getattr(getattr(self, "config", None), "rollout", None).is_enabled(
+                        "proxy_output_shaper"
+                    )
+                    if getattr(getattr(self, "config", None), "rollout", None) is not None
+                    else None
+                ),
             )
             compression_kwargs: dict[str, Any] = {
                 "model": model,
@@ -2581,6 +2881,8 @@ class OpenAIHandlerMixin:
                 "timing": timing,
                 "client": client,
             }
+            if savings_tags is not None:
+                compression_kwargs["savings_tags"] = savings_tags
             while True:
                 try:
                     result = self._compress_openai_responses_payload(
@@ -2592,7 +2894,7 @@ class OpenAIHandlerMixin:
                     unsupported_kwarg = next(
                         (
                             name
-                            for name in ("client", "timing")
+                            for name in ("savings_tags", "client", "timing")
                             if f"unexpected keyword argument '{name}'" in str(exc)
                             and name in compression_kwargs
                         ),
@@ -2796,6 +3098,9 @@ class OpenAIHandlerMixin:
         # if httpx lacks brotli support the response body is undecipherable → 502.
         headers.pop("accept-encoding", None)
         tags = extract_tags(headers)
+        from headroom.proxy.savings_attribution import bind_scope
+
+        bind_scope(tags, request.scope)
         client = classify_client(headers)
         # Surface the image-compression decision (computed earlier) into
         # tags now that the tags dict exists. Same observability pattern
@@ -3303,22 +3608,42 @@ class OpenAIHandlerMixin:
         # anchored on the previous turn's tool list never busts.
         tools = body.get("tools")
         _original_tools = tools  # Preserve for diagnostic / future retry
+        can_inject_ccr_tool = _should_inject_openai_chat_ccr_tool(
+            ccr_inject_tool=self.config.ccr_inject_tool,
+            stream=stream,
+        )
         if (
             self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions
         ) and not _bypass:
+            if self.config.ccr_inject_tool and stream:
+                logger.info(
+                    f"[{request_id}] CCR: skipping retrieval-tool injection for "
+                    "OpenAI chat streaming; this path cannot intercept tool calls"
+                )
             injector = CCRToolInjector(
                 provider="openai",
                 inject_tool=False,  # routed through sticky helper below
-                inject_system_instructions=self.config.ccr_inject_system_instructions,
+                inject_system_instructions=(
+                    self.config.ccr_inject_system_instructions and not stream
+                ),
             )
             injector.scan_for_markers(optimized_messages)
-            if self.config.ccr_inject_system_instructions and injector.has_compressed_content:
+            # Shape-only scanning also matches markers from other context
+            # tools; drop hashes this proxy never actually stored before
+            # they can drive tool injection (issue #2836).
+            injector.verify_ownership()
+            if (
+                self.config.ccr_inject_system_instructions
+                and not stream
+                and injector.has_compressed_content
+            ):
                 optimized_messages = injector.inject_into_system_message(optimized_messages)
 
-            if self.config.ccr_inject_tool:
+            if can_inject_ccr_tool:
                 from headroom.proxy.helpers import (
                     apply_session_sticky_ccr_tool,
                     has_new_ccr_markers,
+                    history_references_ccr_tool,
                 )
 
                 # #1850: markers replayed from overlay_cached_prefix are
@@ -3337,6 +3662,7 @@ class OpenAIHandlerMixin:
                     request_id=request_id,
                     existing_tools=tools,
                     has_compressed_content_this_turn=has_new_compressed_content,
+                    history_has_ccr_reference=history_references_ccr_tool(optimized_messages),
                 )
                 if ccr_tool_injected:
                     logger.debug(
@@ -3614,8 +3940,11 @@ class OpenAIHandlerMixin:
         # (result.tokens_before), which mismatches optimized_tokens (provider tokenizer)
         # and yields impossible tok_after>tok_before. Recount original from the
         # pre-compression snapshot so the message delta is on one scale.
-        original_tokens = tokenizer.count_messages(original_client_messages)
-        optimized_tokens = tokenizer.count_messages(body["messages"])
+        # Off the event loop (#2810): see the matching note in the Anthropic handler.
+        original_tokens = await asyncio.to_thread(
+            tokenizer.count_messages, original_client_messages
+        )
+        optimized_tokens = await asyncio.to_thread(tokenizer.count_messages, body["messages"])
         if tool_tokens_before_compaction > 0:
             try:
                 tool_tokens_after_compaction = tokenizer.count_text(_json_debug_dumps(tools))
@@ -3639,6 +3968,7 @@ class OpenAIHandlerMixin:
             run_request_hooks,
         )
 
+        _th_ctx: TurnContext | None = None
         if registered_turn_hooks():
             _th_tools_before = body.get("tools")
             _th_tok_before = (
@@ -3652,6 +3982,11 @@ class OpenAIHandlerMixin:
                 messages=body["messages"],
                 tools=_th_tools_before,
                 config=self.config,
+                tags=tags,
+                count_messages=tokenizer.count_messages,
+                count_tools=lambda value: (
+                    tokenizer.count_text(json.dumps(value, default=str)) if value else 0
+                ),
             )
             # Snapshot messages BEFORE the hook (same tokenizer) so we can tell whether
             # the hook itself folded — comparing against optimized_tokens instead
@@ -3702,8 +4037,15 @@ class OpenAIHandlerMixin:
         # translate it here — the proxy already owns the outbound body — and
         # those requests work unchanged. No-op when the caller already set
         # `max_completion_tokens`.
+        # Resolved without `body=` so nothing is rewritten yet -- we only need
+        # to know WHICH backend will serve this request, because a translating
+        # one owns the max_tokens spelling. Cached, so the dispatch-site call
+        # below is a dict lookup.
+        from headroom.proxy.route_advice import resolver_for
+
         _normalize_openai_max_tokens(
-            body, backend_owns_translation=self.anthropic_backend is not None
+            body,
+            backend_owns_translation=resolver_for(self).for_request(request) is not None,
         )
 
         # Output shaping (opt-in via HEADROOM_OUTPUT_SHAPER): verbosity steering
@@ -3729,7 +4071,13 @@ class OpenAIHandlerMixin:
                 shape_openai_chat_request,
             )
 
-            _shaper_settings = OutputShaperSettings.from_env()
+            _shaper_settings = OutputShaperSettings.from_env(
+                enabled=(
+                    self.config.rollout.is_enabled("proxy_output_shaper")
+                    if getattr(self.config, "rollout", None) is not None
+                    else None
+                )
+            )
             if _shaper_settings.enabled:
                 # Conversation-stable holdout: a whole conversation is treatment
                 # or control, which keeps the A/B comparison clean and the
@@ -3763,8 +4111,12 @@ class OpenAIHandlerMixin:
                             f"{_shape_result.labels}"
                         )
 
-        # Route through LiteLLM/any-llm backend if configured
-        if self.anthropic_backend is not None:
+        # Route through LiteLLM/any-llm backend if configured -- or through a
+        # per-request one an extension asked for (see proxy/route_advice.py).
+        # No advice resolves to `self.anthropic_backend`, so this is the same
+        # condition it has always been.
+        request_backend = resolver_for(self).for_request(request, body=body)
+        if request_backend is not None:
             try:
                 if stream:
                     self.pipeline_extensions.emit(
@@ -3794,12 +4146,11 @@ class OpenAIHandlerMixin:
                         waste_signals=waste_signals_dict,
                         prefix_tracker=openai_prefix_tracker,
                         optimized_messages=optimized_messages,
+                        backend=request_backend,
                     )
                 else:
                     # Non-streaming: use send_openai_message() → JSON
-                    backend_response = await self.anthropic_backend.send_openai_message(
-                        body, headers
-                    )
+                    backend_response = await request_backend.send_openai_message(body, headers)
                     self.pipeline_extensions.emit(
                         PipelineStage.POST_SEND,
                         operation="proxy.request",
@@ -3858,7 +4209,7 @@ class OpenAIHandlerMixin:
                     ):
                         logger.info(
                             f"[{request_id}] CCR: Detected retrieval tool call "
-                            f"on backend path, handling via {self.anthropic_backend.name}"
+                            f"on backend path, handling via {request_backend.name}"
                         )
 
                         # Continuation closure — delegates transport to
@@ -3885,13 +4236,13 @@ class OpenAIHandlerMixin:
                                 )
                             }
 
-                            assert self.anthropic_backend is not None
+                            assert request_backend is not None
                             logger.info(
                                 f"[{request_id}] CCR: Issuing continuation via "
-                                f"{self.anthropic_backend.name} backend "
+                                f"{request_backend.name} backend "
                                 f"({len(msgs)} messages)"
                             )
-                            cont_resp = await self.anthropic_backend.send_openai_message(
+                            cont_resp = await request_backend.send_openai_message(
                                 continuation_body, continuation_headers
                             )
                             return cont_resp.body
@@ -3907,6 +4258,14 @@ class OpenAIHandlerMixin:
                             # Turn hooks (opt-in extensions) may inspect the turn
                             # or re-drive the model before we hand back the
                             # response. Inert when no hook is registered.
+                            #
+                            # Known gap: unlike the two HTTP paths, a re-drive
+                            # here is NOT folded into this request's token
+                            # accounting — `api_call_fn` goes through the custom
+                            # backend, whose usage is recorded elsewhere. Wire a
+                            # TurnHookUsage through `send_openai_message` before
+                            # relying on cost numbers from a backend deployment
+                            # that runs re-driving hooks.
                             from headroom.proxy.turn_hooks import (
                                 TurnContext,
                                 run_response_hooks,
@@ -3940,6 +4299,19 @@ class OpenAIHandlerMixin:
                             # feedback_no_silent_fallbacks.md.
                             raise
 
+                    # Inline marker resolution runs OUTSIDE the tool-call
+                    # gate above: the callers this flag exists for (#2509,
+                    # Headroom as a LiteLLM guardrail hop) never emit a
+                    # headroom_retrieve tool call, so gating on one would
+                    # make the flag a no-op for exactly its use case.
+                    # Non-streaming responses only.
+                    if (
+                        getattr(self.config, "ccr_resolve_markers_inline", False)
+                        and backend_response.body
+                        and backend_response.status_code == 200
+                    ):
+                        backend_response.body = resolve_markers_in_response(backend_response.body)
+
                     # Extract usage from the FINAL backend body (after
                     # any CCR resolution) so the prefix tracker counts
                     # cache stats from the LAST upstream call.
@@ -4017,7 +4389,7 @@ class OpenAIHandlerMixin:
                     await self._record_request_outcome(
                         RequestOutcome(
                             request_id=request_id,
-                            provider=self.anthropic_backend.name,
+                            provider=request_backend.name,
                             model=model,
                             original_tokens=original_tokens,
                             # Local count, same tokenizer as original_tokens, so
@@ -4049,7 +4421,7 @@ class OpenAIHandlerMixin:
                     if tokens_saved > 0:
                         logger.info(
                             f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "
-                            f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name}"
+                            f"(saved {tokens_saved:,} tokens) via {request_backend.name}"
                         )
 
                     return JSONResponse(
@@ -4128,28 +4500,56 @@ class OpenAIHandlerMixin:
                     run_response_hooks,
                 )
 
+                # Tokens the hook's own re-drives cost. Stays at zero unless a
+                # hook actually calls the model again.
+                _hook_usage = TurnHookUsage()
+
                 if _registered_turn_hooks() and response.status_code == 200:
                     try:
                         _hook_resp_json = response.json()
                     except (ValueError, json.JSONDecodeError):
                         _hook_resp_json = None
                     if isinstance(_hook_resp_json, dict):
-                        _hook_ctx = _TurnContext(
+                        # The call we already made counts too. If the hook
+                        # replaces the response, this original is the one nobody
+                        # else will read.
+                        _hook_usage.record(_hook_resp_json, **CHAT_USAGE_KEYS)
+                        _hook_ctx = _th_ctx or _TurnContext(
                             provider="openai",
                             model=str(model),
                             messages=body["messages"],
                             tools=body.get("tools"),
                             config=self.config,
+                            tags=tags,
                         )
 
                         async def _hook_call_model(_msgs):
                             body["messages"] = _msgs
+                            if _hook_ctx.tools is not None:
+                                body["tools"] = _hook_ctx.tools
                             _r = await self._retry_request("POST", url, headers, body)
-                            return _r.json()
+                            _r_json = _r.json()
+                            _hook_usage.record(_r_json, **CHAT_USAGE_KEYS)
+                            return _r_json
 
-                        _hook_final = await run_response_hooks(
-                            _hook_ctx, _hook_resp_json, _hook_call_model
-                        )
+                        # Same restore as the Responses path: the re-drive rewrote
+                        # body so the next upstream call carried the hook's turn,
+                        # but everything below is accounting for the request the
+                        # client made, not the proxy's internal detour.
+                        _hook_body_messages = body.get("messages")
+                        _hook_body_tools = body.get("tools")
+                        try:
+                            _hook_final = await run_response_hooks(
+                                _hook_ctx, _hook_resp_json, _hook_call_model
+                            )
+                        finally:
+                            if _hook_body_messages is not None:
+                                body["messages"] = _hook_body_messages
+                            if _hook_body_tools is not None:
+                                body["tools"] = _hook_body_tools
+                        # Drop whichever response the usage block below reads;
+                        # what is left is the spend nothing else records.
+                        _hook_usage.settle(_hook_final)
                         if _hook_final is not _hook_resp_json:
                             response = httpx.Response(
                                 status_code=200,
@@ -4310,6 +4710,20 @@ class OpenAIHandlerMixin:
                         f"[{request_id}] Failed to extract cached tokens from OpenAI response: {e}"
                     )
 
+                # Add what the hook's re-drives cost — see the matching block on
+                # the Responses path. A tool-search reload is a whole extra model
+                # call; counting only the last one lets the feature hide its own
+                # overhead behind the saving it is claiming.
+                if _hook_usage.extra_calls:
+                    total_input_tokens += _hook_usage.input_tokens
+                    output_tokens += _hook_usage.output_tokens
+                    cache_read_tokens += _hook_usage.cache_read_tokens
+                    logger.debug(
+                        f"[{request_id}] turn hook: {_hook_usage.extra_calls} unaccounted call(s): "
+                        f"+{_hook_usage.input_tokens} in / "
+                        f"+{_hook_usage.output_tokens} out"
+                    )
+
                 # Update prefix cache tracker for next turn
                 cache_write_tokens = _infer_openai_cache_write_tokens(
                     total_input_tokens,
@@ -4483,6 +4897,22 @@ class OpenAIHandlerMixin:
                 if _compression_failed:
                     response_headers["x-headroom-compression-failed"] = "true"
 
+                # Inline marker resolution, non-streaming only. The direct
+                # path has no CCR tool-call handling at all, which is
+                # exactly the #2509 shape: markers would otherwise reach
+                # the client as raw text.
+                if (
+                    getattr(self.config, "ccr_resolve_markers_inline", False)
+                    and resp_json
+                    and response.status_code == 200
+                ):
+                    resolved_json = resolve_markers_in_response(resp_json)
+                    return Response(
+                        content=json.dumps(resolved_json).encode(),
+                        status_code=response.status_code,
+                        headers=response_headers,
+                    )
+
                 return Response(
                     content=response.content,
                     status_code=response.status_code,
@@ -4628,6 +5058,9 @@ class OpenAIHandlerMixin:
         # to decompress already-decoded JSON and reject it with HTTP 400 (#1542).
         headers.pop("content-encoding", None)
         tags = extract_tags(headers)
+        from headroom.proxy.savings_attribution import bind_scope
+
+        bind_scope(tags, request.scope)
         client = classify_client(headers)
 
         # Learn from the original client payload before memory context or
@@ -4902,10 +5335,7 @@ class OpenAIHandlerMixin:
                     else:
                         memory_tool_defs_responses.append(t)
 
-                if (
-                    responses_memory_tools_allowed
-                    and _responses_request_allows_memory_tool_continuation(body)
-                ):
+                if responses_memory_tools_allowed:
                     resp_tools = body.get("tools") or []
                     resp_tools, mem_tools_injected = _apply_sticky_mem_tools_resp(
                         provider="openai",
@@ -4917,23 +5347,16 @@ class OpenAIHandlerMixin:
                     )
                     if mem_tools_injected:
                         body["tools"] = resp_tools
+                        include = body.get("include")
+                        if isinstance(include, list):
+                            if "reasoning.encrypted_content" not in include:
+                                body["include"] = [*include, "reasoning.encrypted_content"]
+                        elif include is None:
+                            body["include"] = ["reasoning.encrypted_content"]
                         body_mutation_tracker.mark_mutated("responses_memory_tools")
                         logger.info(
                             f"[{request_id}] Memory: Injected memory tools (openai/responses)"
                         )
-                        if _ensure_responses_store_for_memory_tools(
-                            body,
-                            memory_tools_injected=True,
-                        ):
-                            body_mutation_tracker.mark_mutated("responses_memory_store")
-                            logger.info(
-                                f"[{request_id}] Memory: forced store=true for Responses memory tool continuation"
-                            )
-                elif self.memory_handler.config.inject_tools:
-                    logger.info(
-                        "[%s] Memory: skipped Responses memory tools because client set store=false",
-                        request_id,
-                    )
             except Exception as e:
                 logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")
         elif self.memory_handler and memory_user_id and _bypass:
@@ -4990,6 +5413,7 @@ class OpenAIHandlerMixin:
                     model=model,
                     request_id=request_id,
                     client=client,
+                    savings_tags=tags,
                 )
                 attempted_input_tokens = int(_attempted_tokens)
                 if _transforms:
@@ -5080,6 +5504,11 @@ class OpenAIHandlerMixin:
                     if _http_conversation_key
                     else None
                 ),
+                output_shaper_enabled=(
+                    self.config.rollout.is_enabled("proxy_output_shaper")
+                    if getattr(self.config, "rollout", None) is not None
+                    else None
+                ),
             )
             _append_unique_transforms(transforms_applied, _shape_result.labels)
             if _shape_result.changed:
@@ -5216,11 +5645,150 @@ class OpenAIHandlerMixin:
                         status_code=response.status_code,
                         metadata={"stream": stream, "auth_mode": auth_mode.value},
                     )
+                    # Turn hooks, response side. `_compress_openai_responses_payload`
+                    # already runs `run_request_hooks` for this surface, so without
+                    # this block a hook could shrink a Responses turn and then never
+                    # be asked to resolve what the model did about it — a deferral
+                    # with no reload, which strands the model's call at a client
+                    # that has no such tool. Mirrors the chat-completions wiring in
+                    # `handle_openai_chat`; buffered path only, for the same reason
+                    # CCR forces `stream:false` above: you cannot re-drive a turn
+                    # whose bytes are already flowing.
+                    from headroom.proxy.turn_hooks import (
+                        TurnContext as _RespTurnContext,
+                    )
+                    from headroom.proxy.turn_hooks import (
+                        registered_turn_hooks as _resp_registered_hooks,
+                    )
+                    from headroom.proxy.turn_hooks import (
+                        run_response_hooks as _run_resp_hooks,
+                    )
+
+                    # Tokens the hook's own re-drives cost. Stays at zero unless a
+                    # hook actually calls the model again.
+                    _resp_hook_usage = TurnHookUsage()
+
+                    if _resp_registered_hooks() and response.status_code == 200:
+                        try:
+                            _resp_hook_json = response.json()
+                        except (ValueError, json.JSONDecodeError):
+                            _resp_hook_json = None
+                        if isinstance(_resp_hook_json, dict):
+                            # The Responses API names the turn's items `input`;
+                            # fall back to `messages` so an OpenAI-compatible
+                            # upstream that accepts either still round-trips.
+                            _resp_hook_usage.record(_resp_hook_json, **RESPONSES_USAGE_KEYS)
+                            _resp_key = "input" if body.get("input") is not None else "messages"
+                            _resp_hook_ctx = _RespTurnContext(
+                                provider="openai",
+                                model=str(model),
+                                messages=body.get(_resp_key) or [],
+                                tools=body.get("tools"),
+                                config=self.config,
+                                tags=tags,
+                            )
+
+                            async def _resp_hook_call_model(
+                                _items: list[dict[str, Any]],
+                                _key: str = _resp_key,
+                            ) -> dict[str, Any]:
+                                # Re-drive with the hook's items. Tools may also
+                                # have grown (a reload makes resolved schemas
+                                # callable), so send those back too.
+                                body[_key] = _items
+                                if _resp_hook_ctx.tools is not None:
+                                    body["tools"] = _resp_hook_ctx.tools
+                                _rr = await self._retry_request(
+                                    "POST",
+                                    url,
+                                    headers,
+                                    body,
+                                    request_id=request_id,
+                                    forwarder_name="openai_responses_turn_hook",
+                                    path_for_log=url,
+                                )
+                                _rr_json = _rr.json()
+                                _resp_hook_usage.record(_rr_json, **RESPONSES_USAGE_KEYS)
+                                return _rr_json
+
+                            # A re-drive rewrites body[input]/body[tools] so the
+                            # next upstream call carries the hook's items. Put
+                            # the client's turn back afterwards: everything below
+                            # — CCR's `_responses_input_to_items(body["input"])`,
+                            # usage accounting, observability — is describing the
+                            # request the client actually made, not the proxy's
+                            # internal detour. Without this, a turn that both
+                            # reloaded a tool and hit CCR retrieval would hand
+                            # CCR the hook's synthetic items.
+                            _resp_body_input = body.get(_resp_key)
+                            _resp_body_tools = body.get("tools")
+                            try:
+                                _resp_hook_final = await _run_resp_hooks(
+                                    _resp_hook_ctx, _resp_hook_json, _resp_hook_call_model
+                                )
+                            finally:
+                                if _resp_body_input is not None:
+                                    body[_resp_key] = _resp_body_input
+                                if _resp_body_tools is not None:
+                                    body["tools"] = _resp_body_tools
+                            # Drop whichever response the usage block below reads.
+                            _resp_hook_usage.settle(_resp_hook_final)
+                            if _resp_hook_final is not _resp_hook_json:
+                                response = httpx.Response(
+                                    status_code=200,
+                                    headers={
+                                        k: v
+                                        for k, v in response.headers.items()
+                                        if k.lower() not in ("content-encoding", "content-length")
+                                    },
+                                    content=json.dumps(_resp_hook_final).encode(),
+                                )
+
                     total_latency = (time.time() - start_time) * 1000
 
+                    # Some OpenAI-compatible upstreams answer a ``stream: false``
+                    # request with a valid 200 SSE body carrying Responses API
+                    # events (#2613). Reassemble the terminal response JSON so
+                    # the buffered path keeps working — previously
+                    # ``response.json()`` raised JSONDecodeError past the
+                    # narrow usage-extraction catch below and the successful
+                    # upstream reply surfaced as a 502 proxy_error.
+                    upstream_content_type = response.headers.get("content-type", "")
+                    if (
+                        response.status_code == 200
+                        and "text/event-stream" in upstream_content_type.lower()
+                    ):
+                        completed_json = _openai_responses_from_sse(response.text)
+                        if completed_json is None:
+                            # No terminal event to adapt — forward the
+                            # successful upstream body unchanged rather than
+                            # fabricating a 502.
+                            return Response(
+                                content=response.content,
+                                status_code=response.status_code,
+                                headers=_sanitize_forwarded_response_headers(response.headers),
+                            )
+                        adapted_headers = {
+                            k: v
+                            for k, v in response.headers.items()
+                            if k.lower()
+                            not in (
+                                "content-type",
+                                "content-length",
+                                "content-encoding",
+                                "transfer-encoding",
+                            )
+                        }
+                        response = httpx.Response(
+                            status_code=response.status_code,
+                            content=json.dumps(completed_json).encode(),
+                            headers={**adapted_headers, "content-type": "application/json"},
+                        )
+
                     total_input_tokens = original_tokens  # fallback
                     output_tokens = 0
                     cache_read_tokens = 0
+                    resp_json = None
                     try:
                         resp_json = response.json()
                         usage = resp_json.get("usage", {})
@@ -5239,11 +5807,32 @@ class OpenAIHandlerMixin:
                         details = usage.get("input_tokens_details")
                         if isinstance(details, dict):
                             cache_read_tokens = _usage_int(details.get("cached_tokens"))
-                    except (KeyError, TypeError, AttributeError) as e:
+                    except (
+                        json.JSONDecodeError,
+                        ValueError,
+                        KeyError,
+                        TypeError,
+                        AttributeError,
+                    ) as e:
                         logger.debug(
                             f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}"
                         )
 
+                    # Add what the hook's re-drives cost. The usage read above
+                    # describes the last upstream call; a hook that re-drove the
+                    # model made earlier ones that were just as billed. Leaving
+                    # them out lets a token-saving feature hide its own overhead,
+                    # so cost and savings both read better than they are.
+                    if _resp_hook_usage.extra_calls:
+                        total_input_tokens += _resp_hook_usage.input_tokens
+                        output_tokens += _resp_hook_usage.output_tokens
+                        cache_read_tokens += _resp_hook_usage.cache_read_tokens
+                        logger.debug(
+                            f"[{request_id}] turn hook: {_resp_hook_usage.extra_calls} unaccounted call(s): "
+                            f"+{_resp_hook_usage.input_tokens} in / "
+                            f"+{_resp_hook_usage.output_tokens} out"
+                        )
+
                     # CCR Response Handling: intercept headroom_retrieve tool
                     # calls server-side so a Responses API function_call the
                     # downstream caller can't resolve (e.g. Strands, or a
@@ -5371,10 +5960,10 @@ class OpenAIHandlerMixin:
                             for fc in memory_fc_items:
                                 call_id = fc.get("call_id", fc.get("id", ""))
                                 name = fc.get("name", "")
-                                args_str = fc.get("arguments", "{}")
+                                args_str = fc.get("arguments") or "{}"
                                 try:
                                     args = json.loads(args_str)
-                                except json.JSONDecodeError:
+                                except (json.JSONDecodeError, TypeError):
                                     args = {}
 
                                 await self.memory_handler._ensure_initialized()
@@ -5394,17 +5983,17 @@ class OpenAIHandlerMixin:
                                 )
 
                             if tool_outputs:
-                                # Make continuation request with tool results
-                                response_id = resp_json.get("id")
+                                # Make a stateless continuation with the complete
+                                # item history instead of relying on retained state.
                                 continuation_body = {
-                                    "model": model,
-                                    "input": tool_outputs,
+                                    **body,
+                                    "input": [
+                                        *_responses_stateless_input_items(body.get("input")),
+                                        *_responses_stateless_output_items(output_items),
+                                        *tool_outputs,
+                                    ],
                                 }
-                                if response_id:
-                                    continuation_body["previous_response_id"] = response_id
-                                existing_tools = body.get("tools")
-                                if existing_tools:
-                                    continuation_body["tools"] = existing_tools
+                                continuation_body.pop("previous_response_id", None)
 
                                 cont_response = await self._retry_request(
                                     "POST", url, headers, continuation_body
@@ -5542,6 +6131,40 @@ class OpenAIHandlerMixin:
                             headers=sse_headers,
                         )
 
+                    if buffered_stream_ccr and response.status_code == 200 and not resp_json:
+                        logger.warning(
+                            f"[{request_id}] CCR: rejecting malformed buffered Responses 200 "
+                            f"reply (content-type={response.headers.get('content-type')!r}, "
+                            f"body_bytes={len(response.content)})"
+                        )
+                        return Response(
+                            content=json.dumps(
+                                {
+                                    "error": {
+                                        "type": "upstream_protocol_error",
+                                        "message": "Upstream returned an invalid buffered response.",
+                                    }
+                                }
+                            ),
+                            status_code=502,
+                            media_type="application/json",
+                        )
+
+                    # Inline marker resolution, non-streaming only. Runs
+                    # outside the has_ccr_tool_calls gate above on purpose:
+                    # the #2509 case has no retrieve tool call at all.
+                    if (
+                        getattr(self.config, "ccr_resolve_markers_inline", False)
+                        and resp_json
+                        and response.status_code == 200
+                    ):
+                        resolved_json = resolve_markers_in_response(resp_json)
+                        return Response(
+                            content=json.dumps(resolved_json).encode(),
+                            status_code=response.status_code,
+                            headers=response_headers,
+                        )
+
                     return Response(
                         content=response.content,
                         status_code=response.status_code,
@@ -5554,118 +6177,44 @@ class OpenAIHandlerMixin:
 
                 class _BufferedCCRResponse(Response):
                     async def __call__(self, scope, receive, send):  # noqa: ANN001
-                        await asyncio.sleep(0)
-                        loop = asyncio.get_running_loop()
-                        keepalive_deadline = loop.time() + 1.0
-                        started = False
+                        # Send nothing until the buffered operation resolves —
+                        # see the AnthropicHandler twin for the full rationale.
+                        # Committing `200 text/event-stream` on a keepalive timer,
+                        # before the outcome is known, turns every non-200 or
+                        # unparseable upstream reply into a 200 with no usable
+                        # body and discards the status the client needs to back
+                        # off on.
                         try:
-                            while True:
-                                timeout = (
-                                    0.25 if started else max(0.0, keepalive_deadline - loop.time())
-                                )
-                                done, _ = await asyncio.wait({operation}, timeout=timeout)
-                                if done:
-                                    try:
-                                        result = operation.result()
-                                    except Exception as e:
-                                        await record_failed(provider="openai")
-                                        logger.error(
-                                            f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}"
-                                        )
-                                        if not started:
-                                            await send(
-                                                {
-                                                    "type": "http.response.start",
-                                                    "status": 502,
-                                                    "headers": [
-                                                        (b"content-type", b"application/json")
-                                                    ],
-                                                }
-                                            )
-                                            await send(
-                                                {
-                                                    "type": "http.response.body",
-                                                    "body": json.dumps(
-                                                        {
-                                                            "error": {
-                                                                "message": "An error occurred while processing your request. Please try again.",
-                                                                "type": "server_error",
-                                                                "code": "proxy_error",
-                                                            }
-                                                        }
-                                                    ).encode(),
-                                                    "more_body": False,
-                                                }
-                                            )
-                                            return
-                                        await send(
-                                            {
-                                                "type": "http.response.body",
-                                                "body": b'event: error\ndata: {"type":"error","error":{"message":"An error occurred while processing the request."}}\n\n',
-                                                "more_body": False,
-                                            }
-                                        )
-                                        return
-
-                                    if not started:
-                                        await result(scope, receive, send)
-                                        return
-
-                                    body_iterator = getattr(result, "body_iterator", None)
-                                    if body_iterator is not None:
-                                        async for chunk in body_iterator:
-                                            await send(
-                                                {
-                                                    "type": "http.response.body",
-                                                    "body": chunk,
-                                                    "more_body": True,
-                                                }
-                                            )
-                                        await send(
-                                            {
-                                                "type": "http.response.body",
-                                                "body": b"",
-                                                "more_body": False,
-                                            }
-                                        )
-                                        return
-
-                                    await send(
+                            result = await operation
+                        except Exception as e:
+                            await record_failed(provider="openai")
+                            logger.error(
+                                f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}"
+                            )
+                            await send(
+                                {
+                                    "type": "http.response.start",
+                                    "status": 502,
+                                    "headers": [(b"content-type", b"application/json")],
+                                }
+                            )
+                            await send(
+                                {
+                                    "type": "http.response.body",
+                                    "body": json.dumps(
                                         {
-                                            "type": "http.response.body",
-                                            "body": b'event: error\ndata: {"type":"error","error":{"message":"An error occurred while processing the request."}}\n\n',
-                                            "more_body": False,
+                                            "error": {
+                                                "message": "An error occurred while processing your request. Please try again.",
+                                                "type": "server_error",
+                                                "code": "proxy_error",
+                                            }
                                         }
-                                    )
-                                    return
-
-                                if not started:
-                                    await send(
-                                        {
-                                            "type": "http.response.start",
-                                            "status": 200,
-                                            "headers": [(b"content-type", b"text/event-stream")],
-                                        }
-                                    )
-                                    started = True
-                                await send(
-                                    {
-                                        "type": "http.response.body",
-                                        "body": b'event: ping\ndata: {"type":"ping"}\n\n',
-                                        "more_body": True,
-                                    }
-                                )
-                        except asyncio.CancelledError:
-                            raise
-                        finally:
-                            if not operation.done():
-                                operation.cancel()
-                            try:
-                                await operation
-                            except asyncio.CancelledError:
-                                pass
-                            except Exception:
-                                pass
+                                    ).encode(),
+                                    "more_body": False,
+                                }
+                            )
+                            return
+                        await result(scope, receive, send)
 
                 return _BufferedCCRResponse(media_type="text/event-stream")
             return await _buffered_ccr_operation()
@@ -6210,6 +6759,8 @@ class OpenAIHandlerMixin:
                 return json.dumps(flattened, ensure_ascii=False)
 
             body: dict[str, Any] = {}
+            current_response_input: list[dict[str, Any]] = []
+            current_response_template: dict[str, Any] = {}
             tokens_saved = 0
             # Session-scoped accumulator for tokens we *attempted* to
             # compress (extracted units + schema). Drives the active-
@@ -6245,6 +6796,27 @@ class OpenAIHandlerMixin:
             ws_recorded_tokens_saved_total = 0
             ws_recorded_attempted_input_tokens_total = 0
             ws_response_create_frames = 1
+            # Per-connection traffic-learner dedup: tool-call ids already
+            # observed on this WS, so a replayed transcript (each turn resends
+            # the full history; reconnect replays it wholesale) is not counted
+            # as new evidence. Seeded from the first frame as a baseline.
+            ws_learner_seen_call_ids: set[str] = set()
+            # Baseline the first frame's transcript into the learner: record its
+            # tool-call ids as seen WITHOUT learning, so a reconnect that replays
+            # this history adds no spurious evidence. Later frames learn only the
+            # results appended after this point. `body` here is the original
+            # client frame (parsed before memory injection / compression).
+            if isinstance(body, dict) and body:
+                _ws_first_inner = (
+                    body["response"] if isinstance(body.get("response"), dict) else body
+                )
+                if isinstance(_ws_first_inner, dict):
+                    await self._observe_openai_ws_response_create(
+                        _ws_first_inner,
+                        seen_call_ids=ws_learner_seen_call_ids,
+                        baseline=True,
+                        request_id=request_id,
+                    )
             ws_client_frames_total = 1
             ws_upstream_frames_total = 0
             ws_cancel_frames = 0
@@ -6387,7 +6959,8 @@ class OpenAIHandlerMixin:
                 try:
                     # Unwrap response.create envelope to access the response body
                     ws_response_body = frame_body.get("response", frame_body)
-
+                    if not isinstance(ws_response_body, dict):
+                        return frame_raw
                     # Per-project memory routing (GH #462). For WS,
                     # ``ws_response_body`` carries ``instructions`` —
                     # that's the system-prompt-equivalent we feed to the
@@ -6533,6 +7106,15 @@ class OpenAIHandlerMixin:
                     )
                     if mem_injected:
                         ws_response_body["tools"] = ws_tools
+                        include = ws_response_body.get("include")
+                        if isinstance(include, list):
+                            if "reasoning.encrypted_content" not in include:
+                                ws_response_body["include"] = [
+                                    *include,
+                                    "reasoning.encrypted_content",
+                                ]
+                        elif include is None:
+                            ws_response_body["include"] = ["reasoning.encrypted_content"]
 
                         # Add memory instruction so the model uses
                         # memory tools as persistent cross-session knowledge.
@@ -6572,6 +7154,12 @@ class OpenAIHandlerMixin:
                 body.get("type") == "response.create" or ("type" not in body and "input" in body)
             ):
                 first_msg_raw = await _prepare_memory_frame(body, first_msg_raw)
+                first_response_body = body.get("response", body)
+                current_response_input = _responses_input_to_items(
+                    first_response_body.get("input")
+                    if isinstance(first_response_body, dict)
+                    else None
+                )
 
             # Hot-fix follow-up to PR #406 — inline Rust compression on the
             # WS first frame before forwarding upstream. PR #406 enabled
@@ -6812,6 +7400,11 @@ class OpenAIHandlerMixin:
                         self.openai_provider,
                     ),
                     conversation_key=f"ws:{session_id}",
+                    output_shaper_enabled=(
+                        self.config.rollout.is_enabled("proxy_output_shaper")
+                        if getattr(self.config, "rollout", None) is not None
+                        else None
+                    ),
                 )
                 _append_unique_transforms(transforms_applied, _shape_labels)
                 if _shape_modified:
@@ -6826,6 +7419,19 @@ class OpenAIHandlerMixin:
                     )
 
             first_msg_raw = _normalize_ws_response_create_for_upstream(first_msg_raw)
+            try:
+                final_first_body = json.loads(first_msg_raw)
+            except json.JSONDecodeError:
+                final_first_body = None
+            if isinstance(final_first_body, dict):
+                final_first_response = final_first_body.get("response", final_first_body)
+                if isinstance(final_first_response, dict):
+                    current_response_template = dict(final_first_response)
+                    current_response_template.pop("input", None)
+                    current_response_template.pop("previous_response_id", None)
+                    current_response_input = _responses_input_to_items(
+                        final_first_response.get("input")
+                    )
             _first_upstream_body: Any = None
             try:
                 _first_upstream_body = json.loads(first_msg_raw)
@@ -6918,6 +7524,15 @@ class OpenAIHandlerMixin:
                                 frame_type="response.create",
                             )
                             return raw_msg, False, "invalid_inner_payload"
+                        # Learn from this turn's newly appended tool results.
+                        # Dedup against the per-connection baseline so the
+                        # replayed transcript prefix is not re-counted.
+                        await self._observe_openai_ws_response_create(
+                            inner_payload,
+                            seen_call_ids=ws_learner_seen_call_ids,
+                            baseline=False,
+                            request_id=request_id,
+                        )
                         store_forced = _ensure_chatgpt_responses_store_false(
                             inner_payload,
                             is_chatgpt_auth=is_chatgpt_auth,
@@ -7076,6 +7691,11 @@ class OpenAIHandlerMixin:
                                 frame_type="response.create",
                                 model=str(inner_payload.get("model") or "unknown"),
                             )
+                            return (
+                                raw_after_store,
+                                store_forced,
+                                "chatgpt_store_false" if store_forced else "compression_exception",
+                            )
                         # Record transform labels even when the frame bytes are
                         # unchanged: control-arm output-shaper labels
                         # (output_shaper:control:*) must reach the outcome
@@ -7083,11 +7703,6 @@ class OpenAIHandlerMixin:
                         for t in frame_transforms:
                             if t not in transforms_applied:
                                 transforms_applied.append(t)
-                        return (
-                            raw_after_store,
-                            store_forced,
-                            "chatgpt_store_false" if store_forced else "compression_exception",
-                        )
                         if not modified:
                             reason = frame_reason or "no_compression"
                             _log_ws_passthrough(
@@ -7155,6 +7770,8 @@ class OpenAIHandlerMixin:
                         nonlocal ws_client_frames_total, ws_cancel_frames
                         nonlocal ws_frames_compressed
                         nonlocal ws_last_client_frame_type, ws_client_disconnect_seen
+                        nonlocal current_response_input
+                        nonlocal current_response_template
                         client_frame_index = 1
                         try:
                             while True:
@@ -7207,6 +7824,14 @@ class OpenAIHandlerMixin:
                                     and _inbound_frame_body.get("type") == "response.create"
                                 ):
                                     ws_response_create_frames += 1
+                                    inbound_response = _inbound_frame_body.get(
+                                        "response", _inbound_frame_body
+                                    )
+                                    current_response_input = _responses_input_to_items(
+                                        inbound_response.get("input")
+                                        if isinstance(inbound_response, dict)
+                                        else None
+                                    )
                                     msg = await _prepare_memory_frame(_inbound_frame_body, msg)
                                 (
                                     msg,
@@ -7229,6 +7854,11 @@ class OpenAIHandlerMixin:
                                             self.openai_provider,
                                         ),
                                         conversation_key=f"ws:{session_id}",
+                                        output_shaper_enabled=(
+                                            self.config.rollout.is_enabled("proxy_output_shaper")
+                                            if getattr(self.config, "rollout", None) is not None
+                                            else None
+                                        ),
                                     )
                                     _append_unique_transforms(
                                         transforms_applied,
@@ -7246,6 +7876,27 @@ class OpenAIHandlerMixin:
                                         )
 
                                 msg = _normalize_ws_response_create_for_upstream(msg)
+                                if ws_last_client_frame_type == "response.create":
+                                    try:
+                                        outbound_body = json.loads(msg)
+                                        outbound_body = (
+                                            outbound_body.get("response", outbound_body)
+                                            if isinstance(outbound_body, dict)
+                                            else {}
+                                        )
+                                        if isinstance(outbound_body, dict):
+                                            current_response_template = dict(outbound_body)
+                                            current_response_template.pop("input", None)
+                                            current_response_template.pop(
+                                                "previous_response_id", None
+                                            )
+                                        candidate_input = _responses_input_to_items(
+                                            outbound_body.get("input")
+                                        )
+                                        if candidate_input:
+                                            current_response_input = candidate_input
+                                    except (json.JSONDecodeError, AttributeError, TypeError):
+                                        current_response_input = []
                                 _outbound_frame_body: Any = None
                                 try:
                                     _outbound_frame_body = json.loads(msg)
@@ -7302,10 +7953,11 @@ class OpenAIHandlerMixin:
                         """Relay upstream→client with transparent memory tool handling.
 
                         Uses a buffer-then-decide approach:
-                        1. Buffer events until first output item arrives
-                        2. If first output is a memory tool → suppress entire response,
-                           execute tools silently, send continuation upstream
-                        3. If first output is non-memory → flush buffer, stream normally
+                        1. Buffer events until the first non-reasoning output item arrives
+                        2. If a memory tool arrives, suppress the response and execute it
+                           silently before sending a stateless continuation upstream
+                        3. Flush ordinary output as soon as the response is known not to
+                           begin with a reasoning-only prelude
                         4. Continuation response events are relayed to Codex seamlessly
 
                         This prevents orphaned response.created events from confusing Codex.
@@ -7330,25 +7982,22 @@ class OpenAIHandlerMixin:
                         nonlocal ws_recorded_overhead_ms_total, ws_recorded_ttfb_ms
                         nonlocal ws_upstream_frames_total, ws_last_upstream_frame_type
                         nonlocal ws_ttfb_ms
-
-                        memory_enabled = bool(
-                            self.memory_handler and memory_user_id and ws_memory_tools_allowed
-                        )
+                        nonlocal current_response_input
 
                         # Per-response state (reset after each response.completed)
                         event_buffer: list[str] = []
                         decided = False
                         suppress_response = False
                         pending_fcs: list[dict[str, Any]] = []
-                        resp_id: str | None = None
+                        response_output_items: list[dict[str, Any]] = []
 
                         def _reset() -> None:
-                            nonlocal decided, suppress_response, resp_id
+                            nonlocal decided, suppress_response
                             event_buffer.clear()
                             decided = False
                             suppress_response = False
                             pending_fcs.clear()
-                            resp_id = None
+                            response_output_items.clear()
 
                         response_started_ms: float | None = None
 
@@ -7430,7 +8079,11 @@ class OpenAIHandlerMixin:
                             # as HTTP turns.
                             await self._record_request_outcome(
                                 RequestOutcome(
-                                    request_id=request_id,
+                                    # Per-emission ids keep dashboard request-log keys unique.
+                                    request_id=await self._next_request_id(),
+                                    # PERF remains grouped under the stable WS
+                                    # session id even though feed rows are unique.
+                                    perf_request_id=request_id,
                                     provider="openai",
                                     model=model_for_metrics,
                                     original_tokens=max(0, input_delta) + max(0, saved_delta),
@@ -7572,6 +8225,11 @@ class OpenAIHandlerMixin:
                                     ws_cache_write_tokens_total += usage_cache_write_tokens
                                     ws_uncached_input_tokens_total += usage_uncached_tokens
 
+                                memory_enabled = bool(
+                                    self.memory_handler
+                                    and memory_user_id
+                                    and ws_memory_tools_allowed
+                                )
                                 if not memory_enabled:
                                     if event_type == "response.completed":
                                         response_completed_seen = True
@@ -7579,17 +8237,25 @@ class OpenAIHandlerMixin:
                                     await websocket.send_text(msg_str)
                                     continue
 
-                                # --- Phase 1: Buffer until first output item ---
-                                if not decided:
-                                    event_buffer.append(msg_str)
-
-                                    if event_type == "response.output_item.added":
-                                        item = event.get("item", {})
+                                if event_type == "response.output_item.done":
+                                    item = event.get("item", {})
+                                    if isinstance(item, dict):
+                                        response_output_items.append(item)
                                         if (
                                             item.get("type") == "function_call"
                                             and item.get("name") in MEMORY_TOOL_NAMES
                                         ):
-                                            # Memory tool first → suppress entire response
+                                            pending_fcs.append(item)
+
+                                if not decided:
+                                    event_buffer.append(msg_str)
+                                    if event_type == "response.output_item.added":
+                                        item = event.get("item", {})
+                                        if (
+                                            isinstance(item, dict)
+                                            and item.get("type") == "function_call"
+                                            and item.get("name") in MEMORY_TOOL_NAMES
+                                        ):
                                             suppress_response = True
                                             decided = True
                                             event_buffer.clear()
@@ -7597,106 +8263,108 @@ class OpenAIHandlerMixin:
                                                 f"[{request_id}] WS Memory: Detected "
                                                 f"{item.get('name')} — suppressing response"
                                             )
-                                        else:
-                                            # Non-memory first → flush buffer, pass through
+                                        elif not (
+                                            isinstance(item, dict)
+                                            and item.get("type") == "reasoning"
+                                        ):
                                             decided = True
                                             for buf in event_buffer:
                                                 await websocket.send_text(buf)
                                             event_buffer.clear()
-
+                                            continue
                                     elif event_type == "response.completed":
-                                        # No output items at all — flush
                                         decided = True
-                                for buf in event_buffer:
-                                    await websocket.send_text(buf)
-                                event_buffer.clear()
-                                await _record_ws_response_metrics()
-                                _reset()
-                                response_completed_seen = True
-
-                                continue
-
-                                # --- Phase 2a: Suppress mode (memory response) ---
-                                if suppress_response:
-                                    if event_type == "response.output_item.done":
-                                        item = event.get("item", {})
-                                        if (
-                                            item.get("type") == "function_call"
-                                            and item.get("name") in MEMORY_TOOL_NAMES
-                                        ):
-                                            pending_fcs.append(item)
-
-                                    elif event_type == "response.completed":
                                         response_completed_seen = True
                                         await _record_ws_response_metrics()
-                                        resp = event.get("response", {})
-                                        resp_id = resp.get("id")
-
-                                        if pending_fcs:
-                                            logger.info(
-                                                f"[{request_id}] WS Memory: Executing "
-                                                f"{len(pending_fcs)} tool(s) transparently"
-                                            )
-
-                                            # Execute memory tool calls
-                                            tool_outputs: list[dict[str, Any]] = []
-                                            for fc in pending_fcs:
-                                                call_id = fc.get("call_id", fc.get("id", ""))
-                                                fc_name = fc.get("name", "")
-                                                args_str = fc.get("arguments", "{}")
-                                                try:
-                                                    fc_args = json.loads(args_str)
-                                                except json.JSONDecodeError:
-                                                    fc_args = {}
-
-                                                await self.memory_handler._ensure_initialized()
-                                                if self.memory_handler._backend:
-                                                    result = await self.memory_handler._execute_memory_tool(
-                                                        fc_name,
-                                                        fc_args,
-                                                        memory_user_id,
-                                                        "openai",
-                                                    )
-                                                else:
-                                                    result = json.dumps(
-                                                        {"error": "backend not ready"}
-                                                    )
-
-                                                tool_outputs.append(
-                                                    {
-                                                        "type": "function_call_output",
-                                                        "call_id": call_id,
-                                                        "output": result,
-                                                    }
-                                                )
-                                                logger.info(
-                                                    f"[{request_id}] WS Memory: Executed "
-                                                    f"{fc_name} for user {memory_user_id}"
-                                                )
-
-                                            # Send continuation upstream
-                                            cont: dict[str, Any] = {
-                                                "type": "response.create",
-                                                "response": {"input": tool_outputs},
-                                            }
-                                            if resp_id:
-                                                cont["response"]["previous_response_id"] = resp_id
-                                            await upstream.send(
-                                                _normalize_ws_response_create_for_upstream(
-                                                    json.dumps(cont)
-                                                )
-                                            )
-                                            logger.info(
-                                                f"[{request_id}] WS Memory: Sent continuation "
-                                                f"with {len(tool_outputs)} result(s)"
-                                            )
-
+                                        for buf in event_buffer:
+                                            await websocket.send_text(buf)
+                                        _reset()
+                                        continue
+                                    if not decided:
+                                        continue
+
+                                if not suppress_response:
+                                    await websocket.send_text(msg_str)
+                                    if event_type == "response.completed":
+                                        response_completed_seen = True
+                                        await _record_ws_response_metrics()
                                         _reset()
-                                    # All events suppressed in this mode
                                     continue
 
-                                # --- Phase 2b: Pass-through mode ---
-                                await websocket.send_text(msg_str)
+                                if event_type != "response.completed":
+                                    continue
+
+                                response_completed_seen = True
+                                await _record_ws_response_metrics()
+
+                                logger.info(
+                                    f"[{request_id}] WS Memory: Executing "
+                                    f"{len(pending_fcs)} tool(s) transparently"
+                                )
+
+                                # Execute memory tool calls.
+                                tool_outputs: list[dict[str, Any]] = []
+                                for fc in pending_fcs:
+                                    call_id = fc.get("call_id", fc.get("id", ""))
+                                    fc_name = fc.get("name", "")
+                                    args_str = fc.get("arguments") or "{}"
+                                    try:
+                                        fc_args = json.loads(args_str)
+                                    except (json.JSONDecodeError, TypeError):
+                                        fc_args = {}
+
+                                    await self.memory_handler._ensure_initialized()
+                                    if self.memory_handler._backend:
+                                        result = await self.memory_handler._execute_memory_tool(
+                                            fc_name,
+                                            fc_args,
+                                            memory_user_id,
+                                            "openai",
+                                        )
+                                    else:
+                                        result = json.dumps({"error": "backend not ready"})
+
+                                    tool_outputs.append(
+                                        {
+                                            "type": "function_call_output",
+                                            "call_id": call_id,
+                                            "output": result,
+                                        }
+                                    )
+                                    logger.info(
+                                        f"[{request_id}] WS Memory: Executed "
+                                        f"{fc_name} for user {memory_user_id}"
+                                    )
+
+                                stateless_input = _responses_stateless_input_items(
+                                    current_response_input
+                                )
+                                stateless_output = _responses_stateless_output_items(
+                                    response_output_items
+                                )
+                                current_response_input = [
+                                    *stateless_input,
+                                    *stateless_output,
+                                    *tool_outputs,
+                                ]
+                                continuation_response = {
+                                    **current_response_template,
+                                    "input": current_response_input,
+                                }
+                                continuation_response.pop("previous_response_id", None)
+                                cont: dict[str, Any] = {
+                                    "type": "response.create",
+                                    "response": continuation_response,
+                                }
+                                continuation_raw = _strip_codex_lite_metadata(json.dumps(cont))
+                                await upstream.send(
+                                    _normalize_ws_response_create_for_upstream(continuation_raw)
+                                )
+                                logger.info(
+                                    f"[{request_id}] WS Memory: Sent continuation "
+                                    f"with {len(tool_outputs)} result(s)"
+                                )
+                                _reset()
 
                         except asyncio.CancelledError:
                             raise
@@ -8005,7 +8673,9 @@ class OpenAIHandlerMixin:
                     ws_messages_for_log.append({"role": "user", "content": ws_input_for_log})
                 await self._record_request_outcome(
                     RequestOutcome(
-                        request_id=request_id,
+                        # Per-emission ids keep dashboard request-log keys unique.
+                        request_id=await self._next_request_id(),
+                        perf_request_id=request_id,
                         provider="openai",
                         model=model_name,
                         original_tokens=residual_input_tokens + residual_tokens_saved,
@@ -8669,6 +9339,7 @@ class OpenAIHandlerMixin:
                 ),
                 timeout=COMPRESSION_TIMEOUT_SECONDS,
             )
+            ccr_hashes = _response_ccr_hashes(result.messages, result.markers_inserted)
 
             tokens_before = result.tokens_before
             tokens_after = result.tokens_after
@@ -8716,7 +9387,7 @@ class OpenAIHandlerMixin:
                     ),
                     "transforms_applied": result.transforms_applied,
                     "transforms_summary": result.transforms_summary,
-                    "ccr_hashes": result.markers_inserted,
+                    "ccr_hashes": ccr_hashes,
                 }
             )
         except TimeoutError:
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index fd232dc52..07d4f70be 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -12,7 +12,7 @@ import logging
 import time
 from typing import TYPE_CHECKING, Any
 
-from headroom.proxy.auth_mode import classify_client
+from headroom.proxy.auth_mode import classify_client, supports_mid_turn_coalescing
 from headroom.proxy.helpers import (
     RETRYABLE_OVERLOAD_STATUSES,
     jitter_delay_ms,
@@ -1033,7 +1033,6 @@ class StreamingMixin:
         4. Streams the final response to the client
         """
         session_key = session_key or self._get_session_key(body)
-        self._active_streams.add(session_key)
 
         # Guard everything up to the generator's own try/finally (which owns
         # cleanup once streaming starts): any exception here — including
@@ -1098,6 +1097,7 @@ class StreamingMixin:
     ) -> Response | StreamingResponse:
         """Actual streaming implementation, guarded by _stream_response's cleanup wrapper."""
         from fastapi.responses import Response, StreamingResponse
+        from starlette.background import BackgroundTask
 
         from headroom.proxy.helpers import MAX_SSE_BUFFER_SIZE
 
@@ -1105,6 +1105,15 @@ class StreamingMixin:
         # ...) from the *client's* User-Agent before copilot-auth
         # potentially rewrites headers for upstream.
         client = classify_client(headers)
+        # Mid-turn message coalescing (queueing a concurrent same-session
+        # request and later replaying it via a `headroom_pending_messages`
+        # SSE event) is a Claude Code-only protocol. Only register the stream
+        # as active for coalescing when the client can consume that protocol,
+        # so concurrent requests from other harnesses (e.g. OpenCode subagents
+        # that share a body-derived session key) are streamed normally instead
+        # of being swallowed. (#1608)
+        if supports_mid_turn_coalescing(client):
+            self._active_streams.add(session_key)
         headers = await apply_copilot_api_auth(headers, url=url)
         start_time = time.time()
 
@@ -1650,16 +1659,35 @@ class StreamingMixin:
                     client=client,
                     waste_signals=waste_signals,
                 )
-                if pending_messages:
+                if supports_mid_turn_coalescing(client) and pending_messages:
                     pending_event = json.dumps(
                         {"type": "headroom_pending_messages", "messages": pending_messages}
                     )
                     yield f"event: headroom_pending_messages\ndata: {pending_event}\n\n".encode()
 
+        async def _release_upstream_stream() -> None:
+            # Guarantee the upstream HTTP/2 stream is released even when the
+            # body generator above is never iterated — the client disconnected
+            # before Starlette started sending the response body (routine when a
+            # harness like Claude Code cancels or supersedes an in-flight turn),
+            # so ``generate()`` never entered its own ``aclosing`` and nothing
+            # else closes ``upstream_response``. Each such request otherwise
+            # leaks one open h2 stream; they accumulate on the pooled upstream
+            # connection until it reaches SETTINGS_MAX_CONCURRENT_STREAMS (100)
+            # and no new stream can open ("Max outbound streams is 100, 100
+            # open"), and the proxy goes unhealthy until restart (#2797).
+            # Starlette runs a response's ``background`` task after the body
+            # finishes *and* after an early client disconnect, so this fires in
+            # both cases. ``aclose()`` is idempotent, so on the normal path —
+            # where the generator already closed the stream — this is a no-op.
+            with contextlib.suppress(Exception):
+                await upstream_response.aclose()
+
         return StreamingResponse(
             generate(),
             media_type="text/event-stream",
             headers=forwarded_headers,
+            background=BackgroundTask(_release_upstream_stream),
         )
 
     async def _stream_response_bedrock(
@@ -1679,6 +1707,7 @@ class StreamingMixin:
         original_messages: list[dict] | None = None,
         prefix_tracker: Any | None = None,
         optimized_messages: list[dict] | None = None,
+        backend: Any | None = None,
     ) -> StreamingResponse:
         """Stream response from Bedrock backend with metrics tracking.
 
@@ -1697,6 +1726,11 @@ class StreamingMixin:
 
         from headroom.proxy.outcome import RequestOutcome
 
+        # ``backend`` lets the caller serve this one request from somewhere
+        # other than the configured backend (see proxy/route_advice.py). None
+        # means "the configured one", i.e. what this method always did.
+        backend = backend if backend is not None else self.anthropic_backend
+
         client = classify_client(headers)
 
         start_time = time.time()
@@ -1721,7 +1755,7 @@ class StreamingMixin:
 
         async def generate():
             try:
-                assert self.anthropic_backend is not None
+                assert backend is not None
 
                 # Emit a synthetic ping before the first message_start so that
                 # downstream clients (e.g. Claude Code) arm their mid-turn
@@ -1731,7 +1765,7 @@ class StreamingMixin:
                 # (issue #902).
                 yield b"event: ping\ndata: {}\n\n"
 
-                async for event in self.anthropic_backend.stream_message(body, headers):
+                async for event in backend.stream_message(body, headers):
                     # Record TTFB on first event
                     if stream_state["ttfb_ms"] is None:
                         stream_state["ttfb_ms"] = (time.time() - start_time) * 1000
@@ -1807,9 +1841,7 @@ class StreamingMixin:
 
             finally:
                 total_latency = (time.time() - start_time) * 1000
-                _backend_name = (
-                    self.anthropic_backend.name if self.anthropic_backend else "anthropic"
-                )
+                _backend_name = backend.name if backend else "anthropic"
 
                 # Update prefix cache tracker for the next turn — mirrors
                 # _finalize_stream_response (direct-API streaming path)
@@ -1908,6 +1940,7 @@ class StreamingMixin:
         waste_signals: dict[str, int] | None = None,
         prefix_tracker: Any | None = None,
         optimized_messages: list[dict] | None = None,
+        backend: Any | None = None,
     ) -> StreamingResponse:
         """Stream OpenAI chat completion response from backend.
 
@@ -1942,7 +1975,11 @@ class StreamingMixin:
         from headroom.proxy.handlers.openai import _infer_openai_cache_write_tokens
         from headroom.proxy.outcome import RequestOutcome
 
-        assert self.anthropic_backend is not None
+        # ``backend`` lets the caller serve this one request from somewhere
+        # other than the configured backend (see proxy/route_advice.py). None
+        # means "the configured one", i.e. what this method always did.
+        backend = backend if backend is not None else self.anthropic_backend
+        assert backend is not None
         client = classify_client(headers)
 
         async def generate():
@@ -1972,7 +2009,7 @@ class StreamingMixin:
                         stream_state[key] = usage[key]
 
             try:
-                async for sse_chunk in self.anthropic_backend.stream_openai_message(body, headers):
+                async for sse_chunk in backend.stream_openai_message(body, headers):
                     chunk_bytes = sse_chunk.encode() if isinstance(sse_chunk, str) else sse_chunk
                     stream_state["sse_buffer"].extend(chunk_bytes)
                     full_sse_bytes.extend(chunk_bytes)
@@ -2074,7 +2111,7 @@ class StreamingMixin:
                 # instead of collapsing the dashboard headline to 0%.
                 outcome = RequestOutcome.from_stream(
                     body=body,
-                    provider=self.anthropic_backend.name,
+                    provider=backend.name,
                     model=model,
                     request_id=request_id,
                     original_tokens=original_tokens,
@@ -2099,7 +2136,7 @@ class StreamingMixin:
                 if tokens_saved > 0:
                     logger.info(
                         f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "
-                        f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name} [stream]"
+                        f"(saved {tokens_saved:,} tokens) via {backend.name} [stream]"
                     )
 
         return StreamingResponse(
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index adcb846e9..d98b67be3 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -18,6 +18,7 @@ import re
 import threading
 import time
 from collections import OrderedDict
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, cast
@@ -326,12 +327,18 @@ def log_outbound_request(
     mutation_reasons: list[str],
     request_id: str | None,
     source: str,
+    dropped_mutation_reasons: tuple[str, ...] | list[str] | None = None,
 ) -> None:
     """Structured log line for every outbound forwarder call.
 
     Per realignment build constraints: every cache-affecting decision is
     logged. Never includes ``Authorization``/``x-api-key`` content or full
     body bytes.
+
+    ``dropped_mutation_reasons`` records edits that byte-faithful passthrough
+    discarded before the wire. That is a WARNING, not a detail: the line above
+    reports the transforms Headroom *decided* on, and without this the operator
+    reads savings and injections that the upstream never saw.
     """
     logger.info(
         "event=outbound_request forwarder=%s method=%s path=%s body_bytes=%d "
@@ -345,6 +352,405 @@ def log_outbound_request(
         source,
         request_id or "",
     )
+    if dropped_mutation_reasons:
+        logger.warning(
+            "event=outbound_body_mutations_dropped forwarder=%s source=%s "
+            "dropped_mutation_reasons=%s request_id=%s (signed thinking blocks force "
+            "byte-faithful passthrough, so these body edits did NOT reach upstream)",
+            forwarder,
+            source,
+            ",".join(dropped_mutation_reasons),
+            request_id or "",
+        )
+
+
+def count_cache_breakpoints(
+    system: Any,
+    messages: Any,
+    tools: Any,
+) -> dict[str, int]:
+    """Count client ``cache_control`` breakpoints per request section.
+
+    Besides raw counts, records how far from the END of the message list the
+    last marker sits (``last_marker_tail`` = messages after the last marked
+    one). A dropped or backward-moved final breakpoint — the signature of a
+    "large uncached tail next to a healthy cache read" billing regression —
+    shows up as ``last_marker_tail`` growing between inbound and outbound.
+    Nested markers inside ``tool_result`` list content are counted too, so a
+    transform that rewrites sub-blocks can't lose one invisibly.
+    """
+    system_count = 0
+    if isinstance(system, list):
+        system_count = sum(1 for b in system if isinstance(b, dict) and "cache_control" in b)
+
+    tools_count = 0
+    if isinstance(tools, list):
+        tools_count = sum(1 for t in tools if isinstance(t, dict) and "cache_control" in t)
+
+    message_count = 0
+    messages_total = 0
+    last_marker_index = -1
+    if isinstance(messages, list):
+        message_count = len(messages)
+        for i, msg in enumerate(messages):
+            if not isinstance(msg, dict):
+                continue
+            found = 1 if "cache_control" in msg else 0
+            content = msg.get("content")
+            if isinstance(content, list):
+                for block in content:
+                    if not isinstance(block, dict):
+                        continue
+                    if "cache_control" in block:
+                        found += 1
+                    inner = block.get("content")
+                    if isinstance(inner, list):
+                        found += sum(
+                            1 for sub in inner if isinstance(sub, dict) and "cache_control" in sub
+                        )
+            if found:
+                messages_total += found
+                last_marker_index = i
+
+    last_marker_tail = message_count - 1 - last_marker_index if last_marker_index >= 0 else -1
+    return {
+        "system": system_count,
+        "tools": tools_count,
+        "messages": messages_total,
+        "total": system_count + tools_count + messages_total,
+        "message_count": message_count,
+        "last_marker_tail": last_marker_tail,
+    }
+
+
+# --------------------------------------------------------------------------
+# cache_control TTL lanes (issues #2939, #2767).
+#
+# Anthropic reads cache breakpoints in ONE global walk -- `tools`, then
+# `system`, then `messages` -- and requires every ``ttl="1h"`` marker to appear
+# before every 5-minute one. A bare ``{"type": "ephemeral"}`` marker IS 5m. Get
+# it wrong and the whole turn dies with
+#
+#   messages.15.content.1.cache_control.ttl: a ttl='1h' cache_control block must
+#   not come after a ttl='5m' cache_control block.
+#
+# The rule is already modelled in ``crates/headroom-core/src/cache_control.rs``
+# (``TtlOrderingWalk``), but that walker is instantiated once per field list, so
+# it only sees violations *within* `tools`, `system` or `messages` -- never
+# across them -- and it only warns. The helpers below are the cross-section
+# Python counterpart, and they repair rather than warn, because by the time the
+# body reaches the forwarder any violation in it is one Headroom introduced.
+#
+# No Headroom code ever invents a ``ttl`` value: every marker we re-place is
+# copied from some client marker. So an outbound 1h marker on a request whose
+# client sent none can only have leaked in from an EARLIER turn (via
+# ``overlay_cached_prefix`` replaying the previous turn's forwarded bytes), and
+# the fix is to drop the leaked ttl rather than to spread it.
+# --------------------------------------------------------------------------
+
+CACHE_TTL_1H = "1h"
+CACHE_TTL_5M = "5m"
+#: Any other ``ttl`` value is a lane we don't model; markers carrying one are
+#: reported but never rewritten, so a future Anthropic TTL can't be mangled by
+#: guesswork here. Mirrors ``TtlOrderingWalk::observe`` in headroom-core.
+CACHE_TTL_OTHER = "other"
+
+_TTL_GUARD_ENV = "HEADROOM_CACHE_CONTROL_TTL_GUARD"
+
+
+def cache_control_ttl_lane(marker: Any) -> str:
+    """Return ``"1h"``, ``"5m"`` or ``"other"`` for one ``cache_control`` marker.
+
+    A marker with no ``ttl`` key is 5m -- that is Anthropic's default lane, and
+    treating it as "unknown" instead would make every ordinary Claude Code
+    request look like a violation.
+    """
+    if not isinstance(marker, dict):
+        return CACHE_TTL_OTHER
+    ttl = marker.get("ttl")
+    if ttl is None:
+        return CACHE_TTL_5M
+    ttl = str(ttl)
+    return ttl if ttl in (CACHE_TTL_1H, CACHE_TTL_5M) else CACHE_TTL_OTHER
+
+
+def _revisit_holder(
+    holder: Any,
+    section: str,
+    visit: Callable[[str, dict[str, Any]], dict[str, Any] | None],
+) -> tuple[Any, bool]:
+    """Offer ``holder``'s marker to ``visit``; return a copy only if replaced."""
+    if not isinstance(holder, dict):
+        return holder, False
+    marker = holder.get("cache_control")
+    if not isinstance(marker, dict):
+        return holder, False
+    replacement = visit(section, marker)
+    if replacement is None:
+        return holder, False
+    return {**holder, "cache_control": replacement}, True
+
+
+def walk_cache_control(
+    system: Any,
+    messages: Any,
+    tools: Any,
+    visit: Callable[[str, dict[str, Any]], dict[str, Any] | None],
+) -> tuple[Any, Any, Any, bool]:
+    """Visit every ``cache_control`` marker in Anthropic's evaluation order.
+
+    ``visit(section, marker)`` returns a replacement marker, or ``None`` to
+    leave it alone -- so the same traversal serves both a read-only survey and a
+    rewrite. Sections are rebuilt copy-on-write and the untouched originals are
+    returned by identity: the forwarded body shares structure with the prefix
+    tracker's snapshot of what we sent, so mutating a marker in place would
+    rewrite history the next turn compares against.
+
+    Traversal matches :func:`count_cache_breakpoints`, nested ``tool_result``
+    sub-blocks included, so the guard and the diagnostic can never disagree
+    about what counts as a breakpoint.
+    """
+    changed = False
+
+    new_tools = tools
+    if isinstance(tools, list):
+        rebuilt_tools: list[Any] = []
+        hit = False
+        for tool in tools:
+            out, did = _revisit_holder(tool, "tools", visit)
+            hit = hit or did
+            rebuilt_tools.append(out)
+        if hit:
+            new_tools = rebuilt_tools
+            changed = True
+
+    new_system = system
+    if isinstance(system, list):
+        rebuilt_system: list[Any] = []
+        hit = False
+        for block in system:
+            out, did = _revisit_holder(block, "system", visit)
+            hit = hit or did
+            rebuilt_system.append(out)
+        if hit:
+            new_system = rebuilt_system
+            changed = True
+
+    new_messages = messages
+    if isinstance(messages, list):
+        rebuilt_messages: list[Any] = []
+        any_message_hit = False
+        for msg in messages:
+            if not isinstance(msg, dict):
+                rebuilt_messages.append(msg)
+                continue
+            # Message-level markers are non-standard but Headroom's own
+            # diagnostics count them, so keep the two traversals in step.
+            new_msg, message_hit = _revisit_holder(msg, "messages", visit)
+            content = new_msg.get("content")
+            if isinstance(content, list):
+                rebuilt_blocks: list[Any] = []
+                block_hit = False
+                for block in content:
+                    new_block, did = _revisit_holder(block, "messages", visit)
+                    inner = new_block.get("content") if isinstance(new_block, dict) else None
+                    if isinstance(inner, list):
+                        rebuilt_inner: list[Any] = []
+                        inner_hit = False
+                        for sub in inner:
+                            new_sub, sub_did = _revisit_holder(sub, "messages", visit)
+                            inner_hit = inner_hit or sub_did
+                            rebuilt_inner.append(new_sub)
+                        if inner_hit:
+                            new_block = {**new_block, "content": rebuilt_inner}
+                            did = True
+                    block_hit = block_hit or did
+                    rebuilt_blocks.append(new_block)
+                if block_hit:
+                    new_msg = {**new_msg, "content": rebuilt_blocks}
+                    message_hit = True
+            any_message_hit = any_message_hit or message_hit
+            rebuilt_messages.append(new_msg)
+        if any_message_hit:
+            new_messages = rebuilt_messages
+            changed = True
+
+    return new_system, new_messages, new_tools, changed
+
+
+def cache_control_ttl_lanes(system: Any, messages: Any, tools: Any) -> set[str]:
+    """Return the distinct TTL lanes the request's markers ask for."""
+    lanes: set[str] = set()
+
+    def _survey(_section: str, marker: dict[str, Any]) -> None:
+        lanes.add(cache_control_ttl_lane(marker))
+        return None
+
+    walk_cache_control(system, messages, tools, _survey)
+    return lanes
+
+
+def enforce_cache_control_ttl_order(
+    system: Any,
+    messages: Any,
+    tools: Any,
+    *,
+    client_uses_1h: bool,
+    request_id: str = "",
+) -> tuple[Any, Any, Any, dict[str, Any]]:
+    """Make the outbound body satisfy Anthropic's cache_control TTL ordering.
+
+    Two repairs, in this order:
+
+    1. **Lane containment.** When the client's own request carried no 1h marker
+       anywhere (``client_uses_1h`` is False), strip ``ttl`` from every outbound
+       1h marker. Headroom never authors a ttl, so such a marker is a previous
+       turn's value replayed into this one -- and a client that did not ask for
+       the 1h lane has not sent the ``extended-cache-ttl`` beta header either,
+       so promoting the rest of the request to match it is not an option. This
+       is the ``/btw`` case in #2939: Claude Code forks a side question into the
+       5m lane, and the replayed prefix drags a 1h marker in behind the fork's
+       own 5m ``tools``/``system`` breakpoints.
+    2. **Ordering.** Any 5m marker still sitting before the last 1h marker is
+       promoted to 1h. Here the client *is* in the 1h lane, so the beta header
+       is present and the promotion is safe. This covers the mirror-image bug
+       where a transform downgrades an early breakpoint -- e.g.
+       ``inject_tool_search_deferral`` losing a 1h marker off a deferred tool
+       (#2767) -- leaving the client's later 1h message breakpoints illegal.
+
+    Demoting the later 1h instead would also make the request legal, but it
+    throws away 1h caching the client asked and paid for, which is the exact
+    regression #2375 / #2382 / #2651 were filed to stop.
+
+    Returns ``(system, messages, tools, stats)``. When nothing needed repairing
+    the three sections are the objects that were passed in.
+    """
+    stats: dict[str, Any] = {
+        "violation": False,
+        "demoted": 0,
+        "promoted": 0,
+        "first_short_section": "",
+        "first_long_section": "",
+    }
+    if os.environ.get(_TTL_GUARD_ENV, "1").strip().lower() in ("0", "false", "no", "off"):
+        return system, messages, tools, stats
+
+    if not client_uses_1h:
+
+        def _contain(section: str, marker: dict[str, Any]) -> dict[str, Any] | None:
+            if cache_control_ttl_lane(marker) != CACHE_TTL_1H:
+                return None
+            stats["demoted"] += 1
+            if not stats["first_long_section"]:
+                stats["first_long_section"] = section
+            return {k: v for k, v in marker.items() if k != "ttl"}
+
+        system, messages, tools, contained = walk_cache_control(system, messages, tools, _contain)
+        if contained:
+            stats["violation"] = True
+            logger.warning(
+                "event=cache_control_ttl_order request_id=%s repair=lane_containment "
+                "demoted=%d leaked_from_section=%s; the client sent no 1h marker, so a "
+                "replayed 1h breakpoint would have been rejected upstream",
+                request_id,
+                stats["demoted"],
+                stats["first_long_section"],
+            )
+        return system, messages, tools, stats
+
+    # Ordering pass. Survey first so we know how far the violation reaches, then
+    # rewrite only the markers ahead of the last 1h one.
+    lanes: list[tuple[int, str, str]] = []
+    index = 0
+
+    def _survey(section: str, marker: dict[str, Any]) -> None:
+        nonlocal index
+        lanes.append((index, section, cache_control_ttl_lane(marker)))
+        index += 1
+        return None
+
+    walk_cache_control(system, messages, tools, _survey)
+
+    last_long = max((i for i, _s, lane in lanes if lane == CACHE_TTL_1H), default=-1)
+    offenders = [
+        (i, section) for i, section, lane in lanes if lane == CACHE_TTL_5M and i < last_long
+    ]
+    if not offenders:
+        return system, messages, tools, stats
+
+    stats["violation"] = True
+    stats["first_short_section"] = offenders[0][1]
+    stats["first_long_section"] = next(s for i, s, lane in lanes if lane == CACHE_TTL_1H)
+    offending_indices = {i for i, _section in offenders}
+    cursor = 0
+
+    def _promote(_section: str, marker: dict[str, Any]) -> dict[str, Any] | None:
+        nonlocal cursor
+        position = cursor
+        cursor += 1
+        if position not in offending_indices:
+            return None
+        stats["promoted"] += 1
+        return {**marker, "ttl": CACHE_TTL_1H}
+
+    system, messages, tools, _ = walk_cache_control(system, messages, tools, _promote)
+    logger.warning(
+        "event=cache_control_ttl_order request_id=%s repair=promote_to_1h promoted=%d "
+        "first_short_section=%s first_long_section=%s; a 5m breakpoint preceded a 1h one, "
+        "which Anthropic rejects outright",
+        request_id,
+        stats["promoted"],
+        stats["first_short_section"],
+        stats["first_long_section"],
+    )
+    return system, messages, tools, stats
+
+
+def log_cache_breakpoints(
+    *,
+    request_id: str | None,
+    inbound: dict[str, int],
+    outbound: dict[str, int],
+) -> None:
+    """One structured line per request: client breakpoints in vs forwarded out.
+
+    Per realignment build constraints: every cache-affecting decision is
+    logged. Escalates to WARNING when the forwarded request has fewer
+    breakpoints than the client sent, or the last marker moved further from
+    the end of the message list — either one silently un-caches the tail.
+    """
+    dropped = outbound["total"] < inbound["total"]
+    tail_grew = (
+        inbound["last_marker_tail"] >= 0
+        and outbound["last_marker_tail"] != inbound["last_marker_tail"]
+        and (
+            outbound["last_marker_tail"] < 0
+            or outbound["last_marker_tail"] > inbound["last_marker_tail"]
+        )
+    )
+    log = logger.warning if (dropped or tail_grew) else logger.info
+    log(
+        "event=cache_breakpoints request_id=%s "
+        "in_total=%d out_total=%d in_system=%d out_system=%d "
+        "in_tools=%d out_tools=%d in_messages=%d out_messages=%d "
+        "in_msg_count=%d out_msg_count=%d in_last_tail=%d out_last_tail=%d "
+        "dropped=%s tail_grew=%s",
+        request_id or "",
+        inbound["total"],
+        outbound["total"],
+        inbound["system"],
+        outbound["system"],
+        inbound["tools"],
+        outbound["tools"],
+        inbound["messages"],
+        outbound["messages"],
+        inbound["message_count"],
+        outbound["message_count"],
+        inbound["last_marker_tail"],
+        outbound["last_marker_tail"],
+        "true" if dropped else "false",
+        "true" if tail_grew else "false",
+    )
 
 
 def log_memory_injection(
@@ -437,6 +843,82 @@ def append_text_to_latest_user_chat_message(
     return messages, 0
 
 
+# Anthropic wire contract: the system prompt lives in the top-level ``system``
+# parameter; a ``role="system"`` entry inside ``messages`` is rejected with a
+# 400 ("messages.0: use the top-level 'system' parameter ..."). ``role`` /
+# ``content`` / ``type`` are bare wire keys used throughout this module; only
+# the load-bearing values are named here.
+_ROLE_SYSTEM = "system"
+_TEXT_BLOCK_TYPE = "text"
+
+
+def _system_message_to_blocks(message: dict[str, Any]) -> list[Any]:
+    """Convert a ``role="system"`` message into Anthropic system content blocks."""
+    content = message.get("content")
+    if isinstance(content, str):
+        return [{"type": _TEXT_BLOCK_TYPE, "text": content}] if content else []
+    if isinstance(content, list):
+        blocks: list[Any] = []
+        for block in content:
+            if isinstance(block, dict):
+                blocks.append(block)
+            elif isinstance(block, str) and block:
+                blocks.append({"type": _TEXT_BLOCK_TYPE, "text": block})
+        return blocks
+    return []
+
+
+def relocate_system_messages_to_top_level(
+    messages: list[dict[str, Any]],
+    system: Any,
+) -> tuple[list[dict[str, Any]], Any, bool]:
+    """Move any ``role="system"`` entries out of ``messages`` into ``system``.
+
+    Anthropic's Messages API rejects a ``system`` role inside ``messages`` with
+    HTTP 400 ("messages.0: use the top-level 'system' parameter for the initial
+    system prompt"). Internal transforms / pipeline extensions can leave a stray
+    system message in the list (e.g. a relocated harness system block during
+    compression). This is the Anthropic forwarder's last line of defense: it
+    guarantees the forwarded body never violates the wire contract, regardless
+    of which transform introduced the entry.
+
+    The relocated content is appended after any existing top-level ``system``
+    so wire order (system prompt, then conversation) is preserved and no content
+    is dropped.
+
+    Returns ``(clean_messages, new_system, changed)``. When no system-role
+    message is present the inputs pass through unchanged (``changed=False``) so
+    the common path is untouched.
+    """
+    system_indices = {
+        i for i, m in enumerate(messages) if isinstance(m, dict) and m.get("role") == _ROLE_SYSTEM
+    }
+    if not system_indices:
+        return messages, system, False
+
+    relocated_blocks: list[Any] = []
+    for i in sorted(system_indices):
+        relocated_blocks.extend(_system_message_to_blocks(messages[i]))
+
+    clean_messages = [m for i, m in enumerate(messages) if i not in system_indices]
+
+    if not relocated_blocks:
+        # System message(s) carried no content — drop the empty entries only.
+        return clean_messages, system, True
+
+    if system is None or system == "" or system == []:
+        new_system: Any = relocated_blocks
+    elif isinstance(system, str):
+        new_system = [{"type": _TEXT_BLOCK_TYPE, "text": system}, *relocated_blocks]
+    elif isinstance(system, list):
+        new_system = [*system, *relocated_blocks]
+    else:
+        # Unexpected shape — wrap rather than drop (safety-first: never lose content).
+        new_system = [system, *relocated_blocks]
+
+    return clean_messages, new_system, True
+
+
 def append_text_to_latest_user_input_item(
     body_input: list[dict[str, Any]],
     context_text: str,
@@ -1712,6 +2194,43 @@ def has_new_ccr_markers(
     )
 
 
+def history_references_ccr_tool(messages: Any) -> bool:
+    """True when the request history already contains a ``headroom_retrieve`` call.
+
+    Anthropic emits it as an assistant ``tool_use`` content block; OpenAI as an
+    assistant ``tool_calls[].function.name``. When such a reference is present in
+    history but the tool is not re-declared in ``tools``, the provider rejects
+    the whole request (``400 Tool reference 'headroom_retrieve' not found``,
+    #2440). Used to force sticky re-injection on the sessionless path.
+    """
+    from headroom.ccr.tool_injection import CCR_TOOL_NAME
+
+    if not isinstance(messages, list):
+        return False
+    for msg in messages:
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if isinstance(content, list):
+            for block in content:
+                if (
+                    isinstance(block, dict)
+                    and block.get("type") == "tool_use"
+                    and block.get("name") == CCR_TOOL_NAME
+                ):
+                    return True
+        tool_calls = msg.get("tool_calls")
+        if isinstance(tool_calls, list):
+            for tc in tool_calls:
+                if not isinstance(tc, dict):
+                    continue
+                fn = tc.get("function")
+                name = fn.get("name") if isinstance(fn, dict) else tc.get("name")
+                if name == CCR_TOOL_NAME:
+                    return True
+    return False
+
+
 def apply_session_sticky_ccr_tool(
     *,
     provider: Literal["anthropic", "openai", "google"],
@@ -1719,6 +2238,7 @@ def apply_session_sticky_ccr_tool(
     request_id: str | None,
     existing_tools: list[dict[str, Any]] | None,
     has_compressed_content_this_turn: bool,
+    history_has_ccr_reference: bool = False,
 ) -> tuple[list[dict[str, Any]], bool]:
     """Apply sticky-on CCR retrieval-tool injection per :class:`SessionCcrTracker`.
 
@@ -1767,9 +2287,14 @@ def apply_session_sticky_ccr_tool(
         )
         return tools_out, False
 
-    # No session_id (e.g. WS path): per-turn decision drives directly.
+    # No session_id (e.g. WS path): the per-turn flag drives the decision, but
+    # a headroom_retrieve tool_use already sitting in history must ALSO force
+    # re-injection. Without a session the tracker can't remember a prior turn's
+    # CCR, so a later turn with no fresh compression would drop the tool
+    # definition and the provider rejects the request because history still
+    # references it (#2440).
     if not session_id:
-        if not has_compressed_content_this_turn:
+        if not (has_compressed_content_this_turn or history_has_ccr_reference):
             log_tool_injection_decision(
                 provider=provider,
                 session_id=None,
@@ -1783,7 +2308,9 @@ def apply_session_sticky_ccr_tool(
         log_tool_injection_decision(
             provider=provider,
             session_id=None,
-            decision="inject_first_time",
+            decision="inject_first_time"
+            if has_compressed_content_this_turn
+            else "inject_history_reference",
             tool_definition_bytes_count=len(replay.canonical_bytes),
             request_id=request_id,
         )
@@ -2284,6 +2811,31 @@ _TOOL_SEARCH_DEFAULT_NAME = "tool_search_tool_regex"
 _TOOL_SEARCH_MIN_TOOLS = 12
 
 
+def anthropic_first_party_tool_search_supported(api_base_url: str | None) -> bool:
+    """Return whether Anthropic server-side tool search is valid for this upstream."""
+    from headroom.providers.claude.runtime import is_custom_anthropic_base_url
+
+    return not is_custom_anthropic_base_url(api_base_url)
+
+
+def strip_first_party_tool_search_tools_for_third_party_upstream(
+    tools: Any,
+    api_base_url: str | None,
+) -> Any:
+    """Remove first-party Anthropic tool-search tools when forwarding to a custom upstream."""
+    if not isinstance(tools, list) or anthropic_first_party_tool_search_supported(api_base_url):
+        return tools
+    filtered = [
+        tool
+        for tool in tools
+        if not (
+            isinstance(tool, dict)
+            and str(tool.get("type", "")).startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX)
+        )
+    ]
+    return filtered if len(filtered) != len(tools) else tools
+
+
 def inject_tool_search_deferral(
     tools: Any,
     *,
@@ -2306,8 +2858,9 @@ def inject_tool_search_deferral(
     if not isinstance(tools, list) or len(tools) < _TOOL_SEARCH_MIN_TOOLS:
         return tools
     for tool in tools:
-        if isinstance(tool, dict) and str(tool.get("type", "")).startswith(
-            _TOOL_SEARCH_TOOL_TYPE_PREFIX
+        if isinstance(tool, dict) and (
+            str(tool.get("type", "")).startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX)
+            or str(tool.get("name") or "").lower().startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX)
         ):
             return tools  # client already uses tool search — leave it alone
 
@@ -2422,7 +2975,19 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any
         return messages, 0
 
     tool_list = tools if isinstance(tools, list) else []
-    available = {str(t["name"]) for t in tool_list if isinstance(t, dict) and t.get("name")}
+    # Typed search tools (type starts with "tool_search_tool_") are the search
+    # mechanism itself — they are never the target of a tool_reference lookup.
+    # Excluding them from `available` ensures that a stale history entry that
+    # references "tool_search_tool_regex" (from a turn where inject deferred a
+    # typeless client tool with that name) is correctly dropped rather than
+    # falsely kept because the injected typed search tool shares the same name.
+    available = {
+        str(t["name"])
+        for t in tool_list
+        if isinstance(t, dict)
+        and t.get("name")
+        and not str(t.get("type") or "").startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX)
+    }
     has_search_tool = any(
         isinstance(t, dict) and str(t.get("type", "")).startswith(_TOOL_SEARCH_TOOL_TYPE_PREFIX)
         for t in tool_list
@@ -2475,6 +3040,126 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any
     return (out, removed) if changed else (messages, 0)
 
 
+def _ccr_result_as_text(block: dict[str, Any]) -> str:
+    """Flatten a ``tool_result`` block's content to plain text, preserving what
+    the model already saw. Falls back to a short placeholder when there is no
+    textual content to keep."""
+    content = block.get("content")
+    if isinstance(content, str) and content.strip():
+        return content
+    if isinstance(content, list):
+        parts = [
+            b.get("text", "")
+            for b in content
+            if isinstance(b, dict) and b.get("type") == "text" and b.get("text")
+        ]
+        joined = "\n".join(part for part in parts if part)
+        if joined.strip():
+            return joined
+    return "[headroom_retrieve result omitted]"
+
+
+def strip_unsupported_ccr_retrieve_blocks(messages: Any, tools: Any) -> tuple[Any, int]:
+    """Neutralize ``headroom_retrieve`` history references the outbound ``tools``
+    array cannot support.
+
+    Claude Code replays one transcript across requests that carry different
+    ``tools`` arrays, and Anthropic validates every history ``tool_use`` against
+    the array of the request at hand. A passthrough side-request (the prompt-type
+    Stop hook evaluator, ``/compact``) that the proxy forwards without declaring
+    ``headroom_retrieve`` then 400s on a historical ``tool_use`` that names it --
+    the CCR sibling of the tool-search history repair (#2814 / #2807). This is
+    belt-and-braces with the injection-side fixes: they keep the tool available
+    where it belongs; this makes the 400 structurally impossible where it cannot.
+
+    When the request does NOT declare ``headroom_retrieve``, replace each
+    ``headroom_retrieve`` ``tool_use`` block and its paired ``tool_result`` with a
+    text block, so no dangling reference survives. Neutralize rather than drop:
+    CCR's ``tool_use`` (an assistant turn) and its ``tool_result`` (the next user
+    turn) live in DIFFERENT messages, so removing a message could leave two
+    same-role messages adjacent and break Anthropic's user/assistant alternation.
+    Replacing blocks in place keeps every message and role intact, and preserves
+    the retrieved text the model already saw.
+
+    Returns ``(messages, blocks_neutralized)``, and the ORIGINAL ``messages``
+    object when nothing changed -- callers rely on identity to skip the write-back.
+    """
+    from headroom.ccr.tool_injection import CCR_TOOL_NAME
+
+    if not isinstance(messages, list):
+        return messages, 0
+
+    tool_list = tools if isinstance(tools, list) else []
+    available = {str(t["name"]) for t in tool_list if isinstance(t, dict) and t.get("name")}
+    # The tool is declared this turn (e.g. the main loop, or sticky re-injection),
+    # so its history references resolve. Nothing to repair.
+    if CCR_TOOL_NAME in available:
+        return messages, 0
+
+    # First pass: collect the ids of headroom_retrieve tool_use blocks so their
+    # paired tool_result blocks (in a later user turn) can be matched.
+    retrieve_ids: set[str] = set()
+    for message in messages:
+        content = message.get("content") if isinstance(message, dict) else None
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if (
+                isinstance(block, dict)
+                and block.get("type") == "tool_use"
+                and block.get("name") == CCR_TOOL_NAME
+            ):
+                use_id = block.get("id")
+                if use_id:
+                    retrieve_ids.add(str(use_id))
+
+    if not retrieve_ids:
+        return messages, 0
+
+    out: list[Any] = []
+    neutralized = 0
+    changed = False
+    for message in messages:
+        content = message.get("content") if isinstance(message, dict) else None
+        if not isinstance(content, list):
+            out.append(message)
+            continue
+
+        new_content: list[Any] = []
+        touched = False
+        for block in content:
+            if isinstance(block, dict):
+                if block.get("type") == "tool_use" and block.get("name") == CCR_TOOL_NAME:
+                    new_content.append(
+                        {
+                            "type": "text",
+                            "text": "[headroom_retrieve call omitted: tool not available this turn]",
+                        }
+                    )
+                    neutralized += 1
+                    touched = True
+                    continue
+                if (
+                    block.get("type") == "tool_result"
+                    and str(block.get("tool_use_id", "")) in retrieve_ids
+                ):
+                    new_content.append({"type": "text", "text": _ccr_result_as_text(block)})
+                    neutralized += 1
+                    touched = True
+                    continue
+            new_content.append(block)
+
+        if touched:
+            changed = True
+            repaired = dict(message)
+            repaired["content"] = new_content
+            out.append(repaired)
+        else:
+            out.append(message)
+
+    return (out, neutralized) if changed else (messages, 0)
+
+
 # ---------------------------------------------------------------------------
 # Server-side Tool Search injection — OpenAI Responses API (gpt-5.4+).
 #
@@ -2485,7 +3170,11 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any
 # (only name+description remain) until the model searches for one — while every
 # tool stays callable and the prompt cache is preserved. Same win as Anthropic
 # (~15-25k tool-schema tokens -> ~200) for clients that ship a big tool surface
-# and never opt into tool search themselves (opencode, plain API clients).
+# and never opt into tool search themselves (plain API clients).
+#
+# Two harnesses are excluded. Codex drops deferred-call namespaces during its
+# round trip, while GH #2660 reports OpenCode rejecting the injected
+# `tool_search` tool as unavailable. Their tools therefore stay resident.
 #
 # Differences from the Anthropic path that require a separate function:
 #   * Responses function tools carry ``type: "function"`` (Anthropic real tools
@@ -2500,7 +3189,7 @@ def strip_unsupported_tool_search_blocks(messages: Any, tools: Any) -> tuple[Any
 _OPENAI_TOOL_SEARCH_TYPE = "tool_search"
 _OPENAI_TOOL_SEARCH_MIN_TOOLS = 12
 _OPENAI_TOOL_SEARCH_RESIDENT_NAMES = frozenset({"terminal"})
-_OPENAI_TOOL_SEARCH_UNSUPPORTED_CLIENTS = frozenset({"codex"})
+_OPENAI_TOOL_SEARCH_UNSUPPORTED_CLIENTS = frozenset({"codex", "opencode"})
 # gpt-5.4 is the first model with Responses tool_search (OpenAI docs). Version-
 # gated by default; overridable per deployment via a regex in
 # HEADROOM_OPENAI_TOOL_SEARCH_MODELS (matched against the model name) so new
@@ -2548,8 +3237,9 @@ def inject_tool_search_deferral_openai(
     deferred + a ``{"type": "tool_search"}`` tool injected, or the original list
     unchanged when injection doesn't apply.
 
-    No-op for Codex, whose round-trip structs drop deferred-call namespaces. Also
-    no-op when: the model doesn't support tool search (gpt-5.4+ only), ``tools``
+    No-op for Codex and OpenCode, whose harnesses cannot safely execute the
+    injected search tool. Also no-op when: the model doesn't support tool search
+    (gpt-5.4+ only), ``tools``
     is not a list, there are fewer than ``_OPENAI_TOOL_SEARCH_MIN_TOOLS``, a
     tool_search tool is already present (client already defers), or nothing would
     be deferred. Core coding tools and hosted/typed tools (web_search,
diff --git a/headroom/proxy/memory_query_policy.py b/headroom/proxy/memory_query_policy.py
index 8d765e247..1480a5f15 100644
--- a/headroom/proxy/memory_query_policy.py
+++ b/headroom/proxy/memory_query_policy.py
@@ -63,11 +63,18 @@ def extract_memory_query_sources(
                     # Anthropic user turns carry the actual prompt as text blocks
                     # ({"type":"text","text":...}), not a plain string. Capture it
                     # so the memory retrieval query keys on the user's question and
-                    # not just any tool_result blocks in the same turn.
+                    # not just any tool_result blocks in the same turn. Skip Claude
+                    # Code's <system-reminder> harness blocks: they are appended to
+                    # the same turn and, concatenated into the embedding input,
+                    # dilute the user's question below the similarity floor so
+                    # nothing is retrieved (#2195). Filtering them keeps the query
+                    # on the substantive question.
                     user_text = "\n".join(
-                        b.get("text", "")
+                        text
                         for b in content
                         if isinstance(b, dict) and b.get("type") == "text"
+                        for text in (str(b.get("text", "")).strip(),)
+                        if text and not text.startswith("<system-reminder")
                     ).strip()
                     if user_text:
                         latest_user = user_text
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index 069867e2b..92c6ef366 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -14,6 +14,7 @@ from typing import Any, Literal
 from headroom.memory import qdrant_env
 from headroom.providers.registry import ProviderApiOverrides
 from headroom.proxy.model_router import ModelRouterConfig
+from headroom.rollout import RolloutSnapshot, resolve_rollout
 
 logger = logging.getLogger(__name__)
 
@@ -65,10 +66,14 @@ class RequestLog:
     total_latency_ms: float | None
 
     # Metadata
-    tags: dict[str, str]
+    tags: dict[str, Any]
     cache_hit: bool
     transforms_applied: list[str]
 
+    # Per-request attribution. Headline totals remain authoritative, so these
+    # explanatory rows are never added a second time.
+    savings_breakdown: list[dict[str, Any]] = field(default_factory=list)
+
     # Provider-side cache economics (Anthropic prompt caching, #2438).
     # ``cache_hit`` alone is ambiguous: a call billed cache-*creation* (write)
     # cannot be told apart from a real cache-*read* hit. These raw deltas —
@@ -133,6 +138,8 @@ class ProxyConfig:
     # Server
     host: str = "127.0.0.1"
     port: int = 8787
+    # Resolved at this configuration boundary and then injected unchanged.
+    rollout: RolloutSnapshot | None = None
     anthropic_api_url: str | None = None  # Custom Anthropic API URL override
     openai_api_url: str | None = None  # Custom OpenAI API URL override
     # Display label for the OpenAI-compatible upstream (dashboard/stats only).
@@ -186,6 +193,13 @@ class ProxyConfig:
     # markers can be toggled from the CLI (--no-ccr, which also drops the retrieve
     # tool). Threaded into the router in server.py; default preserves current behavior.
     ccr_inject_marker: bool = True
+    # Explicit opt-in fallback for callers with no path to redeem a marker via
+    # the headroom_retrieve tool (e.g. a LiteLLM guardrail/proxy hop with no
+    # tool-call turn — issue #2509). Off by default: guessing "this caller
+    # can't use tools" is fragile, so operators must opt in with
+    # --ccr-inline-resolve / HEADROOM_CCR_INLINE_RESOLVE. Applies to
+    # non-streaming responses only; buffered-CCR streaming is untouched.
+    ccr_resolve_markers_inline: bool = False
 
     # CCR Response Handling
     ccr_handle_responses: bool = True
@@ -486,7 +500,22 @@ class ProxyConfig:
     # ``HeadroomProxy._run_compression_in_executor``.
     compression_max_workers: int | None = None
 
+    # Number of built-in uvicorn worker processes sharing this listen socket.
+    # Kept at the end to avoid shifting existing positional constructor fields.
+    # Process-local runtime hot reload is unsafe above one worker because only
+    # the worker receiving the admin request would observe the update.
+    worker_processes: int = 1
+
     def __post_init__(self, smart_routing: bool | None = None) -> None:
+        if self.rollout is None:
+            self.rollout = resolve_rollout()
+        # ``read_maturation`` remains a concrete, already-resolved runtime
+        # setting for programmatic/config-file callers.  The CLI composition
+        # root derives it from this same snapshot before constructing the
+        # config; rewriting it here would resolve policy a second time and
+        # break explicit non-CLI configuration.
+        if self.worker_processes < 1:
+            raise ValueError("worker_processes must be >= 1")
         if self.retry_enabled and self.retry_max_attempts < 1:
             raise ValueError("retry_max_attempts must be >= 1 when retry_enabled=True")
         # A 0 (or negative) requests-per-minute limit divides by zero in the
diff --git a/headroom/proxy/outcome.py b/headroom/proxy/outcome.py
index e0b304d4c..f98c88753 100644
--- a/headroom/proxy/outcome.py
+++ b/headroom/proxy/outcome.py
@@ -27,7 +27,7 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any
 
 from headroom.proxy.tool_schema_savings_policy import (
@@ -87,6 +87,12 @@ class RequestOutcome:
     output_tokens: int
     tokens_saved: int
     attempted_input_tokens: int
+    # Optional correlation id for the human-readable PERF line. Most requests
+    # use ``request_id`` for both storage identity and log correlation. A
+    # long-lived WebSocket session is different: each emitted feed row needs a
+    # unique request id, while operators still need every line from the socket
+    # under one greppable session prefix.
+    perf_request_id: str | None = None
     # Optional so the 18 existing emit sites need no change: a handler that has
     # no provider count (or whose optimized_tokens is already provider-scaled)
     # leaves it 0 and billing falls back to optimized_tokens, exactly as before.
@@ -164,7 +170,7 @@ class RequestOutcome:
     # (``original_messages``); otherwise ``request_messages`` carries the sent
     # body for backward compatibility and this stays ``None``.
     compressed_messages: list[dict[str, Any]] | None = None
-    tags: dict[str, str] = field(default_factory=dict)
+    tags: dict[str, Any] = field(default_factory=dict)
     client: str | None = None
     project: str | None = None
 
@@ -393,6 +399,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
     from headroom.proxy.cost import _summarize_transforms
     from headroom.proxy.models import RequestLog
     from headroom.proxy.project_context import get_current_project
+    from headroom.proxy.savings_attribution import encode, from_tags, public_tags
     from headroom.telemetry.session import record_outcome
 
     # GitHub Copilot: requests routed to the Copilot API travel on the OpenAI or
@@ -458,6 +465,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
     # tags and never move tok_before/after; aggregate them into Metrics so the
     # session summary / cost summary / all-layers total can surface the layer.
     tool_search_saved = tool_schema_saved_from_tags(outcome.tags or {})
+    savings_breakdown = from_tags(outcome.tags)
 
     # Billed input volume. Prefer the provider's own count where it reported one
     # — that is what the invoice charges for, and it is the number cache math is
@@ -493,6 +501,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
         client=outcome.client,
         tool_search_saved=tool_search_saved,
         local_input_tokens=outcome.optimized_tokens,
+        savings_attribution=savings_breakdown,
     )
 
     # 2. Cost tracker (optional).
@@ -518,7 +527,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
     #    dict is not mutated (frozen dataclass + defensive copy).
     request_logger = getattr(handler, "logger", None)
     if request_logger is not None:
-        log_tags = dict(outcome.tags)
+        log_tags = public_tags(outcome.tags)
         if outcome.client:
             log_tags["client"] = outcome.client
         if project:
@@ -526,7 +535,10 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
         request_logger.log(
             RequestLog(
                 request_id=outcome.request_id,
-                timestamp=datetime.now().isoformat(),
+                # Request logs are consumed by browsers in arbitrary time zones.
+                # Include the UTC offset so relative-age calculations represent
+                # the same instant regardless of where the proxy runs.
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 provider=outcome.provider,
                 model=outcome.model,
                 input_tokens_original=outcome.original_tokens,
@@ -542,6 +554,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
                 cache_write_tokens=outcome.cache_write_tokens,
                 uncached_input_tokens=outcome.uncached_input_tokens,
                 transforms_applied=list(outcome.transforms_applied),
+                savings_breakdown=savings_breakdown,
                 waste_signals=outcome.waste_signals,
                 request_messages=outcome.request_messages,
                 compressed_messages=outcome.compressed_messages,
@@ -561,8 +574,9 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
     # compaction is already inside tok_saved and must not be added twice.
     tool_saved = tool_schema_saved_from_tags(outcome.tags or {})
     total_saved = headline_tokens_saved(outcome.tokens_saved, outcome.tags or {})
+    encoded_savings = encode(savings_breakdown)
     logger.info(
-        f"[{outcome.request_id}] PERF "
+        f"[{outcome.perf_request_id or outcome.request_id}] PERF "
         f"model={outcome.model} msgs={outcome.num_messages} "
         f"tok_before={outcome.original_tokens} tok_after={outcome.optimized_tokens} "
         f"tok_saved={outcome.tokens_saved} "
@@ -575,6 +589,7 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
         f"total_ms={outcome.total_latency_ms:.0f} "
         f"tok_out={outcome.output_tokens} "
         f"ttfb_ms={outcome.ttfb_ms:.0f} "
+        f"savings={encoded_savings} "
         f"transforms={_summarize_transforms(list(outcome.transforms_applied))}"
         f"{client_part}"
     )
diff --git a/headroom/proxy/output_shaper.py b/headroom/proxy/output_shaper.py
index daa84f256..7dd9663ba 100644
--- a/headroom/proxy/output_shaper.py
+++ b/headroom/proxy/output_shaper.py
@@ -97,11 +97,7 @@ _replace_or_append_steering_block = replace_or_append_steering_block
 
 @dataclass(frozen=True)
 class OutputShaperSettings:
-    """Runtime settings, resolved once per request from the environment.
-
-    Env-driven (like HEADROOM_INTERCEPT_ENABLED) so the proxy picks it up
-    without config plumbing through the server. Off by default.
-    """
+    """Output-shaping settings with rollout enablement injected by the proxy."""
 
     enabled: bool = False
     verbosity_level: int = 2
@@ -109,12 +105,19 @@ class OutputShaperSettings:
     mechanical_effort: str = "low"
 
     @classmethod
-    def from_env(cls) -> OutputShaperSettings:
-        enabled = runtime_env.getenv("HEADROOM_OUTPUT_SHAPER", "").lower() in (
-            "1",
-            "true",
-            "yes",
-        )
+    def from_env(cls, *, enabled: bool | None = None) -> OutputShaperSettings:
+        """Resolve tuning; running proxies always inject the resolved gate.
+
+        ``None`` preserves the helper's direct-call compatibility for SDK/tests,
+        but proxy request paths never use it and therefore never re-resolve the
+        rollout alias.
+        """
+        if enabled is None:
+            enabled = runtime_env.getenv("HEADROOM_OUTPUT_SHAPER", "").lower() in (
+                "1",
+                "true",
+                "yes",
+            )
         try:
             level = int(runtime_env.getenv("HEADROOM_VERBOSITY_LEVEL", "2"))
         except ValueError:
diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py
index 4f691b79b..3586c7a7b 100644
--- a/headroom/proxy/prometheus_metrics.py
+++ b/headroom/proxy/prometheus_metrics.py
@@ -14,7 +14,7 @@ import logging
 import threading
 from collections import defaultdict
 from datetime import datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from headroom.observability import HeadroomOtelMetrics
@@ -22,12 +22,23 @@ if TYPE_CHECKING:
 
 from headroom import savings_ledger
 from headroom.observability import get_otel_metrics
-from headroom.proxy.savings_tracker import SavingsTracker
+from headroom.proxy.savings_tracker import SavingsTracker, estimate_request_savings_usd
 
 logger = logging.getLogger("headroom.proxy")
 
+# Sentinel label value that models past MAX_DISTINCT_MODELS collapse into, so
+# client-supplied model cardinality stays bounded (see record_request).
+_OTHER_MODEL = "other"
+
 
 def _escape_label_value(value: str) -> str:
+    # The /metrics body is emitted whole with .encode("utf-8") (server.py). A
+    # client-supplied value can be a valid str that is not UTF-8-encodable — a
+    # lone surrogate decoded from a JSON model id — which raises in the response
+    # encoder and 500s every scrape, not just its own line. Drop un-encodable
+    # code points before escaping so one malformed request can't down the
+    # endpoint. Byte-identical for encodable values, including non-ASCII.
+    value = value.encode("utf-8", "replace").decode("utf-8")
     return value.replace("\\", "\\\\").replace("\n", "\\n").replace('"', '\\"')
 
 
@@ -82,6 +93,9 @@ class PrometheusMetrics:
         self.requests_total = 0
         self.requests_by_provider: dict[str, int] = defaultdict(int)
         self.requests_by_model: dict[str, int] = defaultdict(int)
+        # Set once when requests_by_model first reaches MAX_DISTINCT_MODELS, so the
+        # cardinality-cap warning fires exactly once instead of per request.
+        self._model_cardinality_warned = False
         # Populated via X-Headroom-Stack header (TS SDK adapters, etc.)
         self.requests_by_stack: dict[str, int] = defaultdict(int)
         self.requests_cached = 0
@@ -128,6 +142,8 @@ class PrometheusMetrics:
         # they saved so per-extension contribution is observable via /stats,
         # mirroring the per-strategy compression breakdown above.
         self.extension_savings: dict[str, int] = defaultdict(int)
+        # Named savings attribution; realized and projected rows stay separate.
+        self.savings_by_source: dict[str, dict[str, str | int | float | bool]] = {}
 
         # Fail-open compression failures, keyed by reason ("timeout",
         # "error"). The proxy fails open on any optimization error so the
@@ -315,6 +331,7 @@ class PrometheusMetrics:
             self.requests_total = 0
             self.requests_by_provider.clear()
             self.requests_by_model.clear()
+            self._model_cardinality_warned = False
             self.requests_by_stack.clear()
             self.requests_cached = 0
             self.requests_rate_limited = 0
@@ -335,6 +352,7 @@ class PrometheusMetrics:
             self.compressions_by_strategy.clear()
             self.tokens_saved_by_strategy.clear()
             self.extension_savings.clear()
+            self.savings_by_source.clear()
             with self._obs_counter_lock:
                 self.compression_failed_by_reason.clear()
                 self.kompress_size_gate_by_outcome.clear()
@@ -417,14 +435,14 @@ class PrometheusMetrics:
             return total_input_tokens, total_input_cost_usd
 
         try:
-            cost_stats = self.cost_tracker.stats()
+            # totals() rather than stats(): identical numbers, without the
+            # 31-day cost-record walk that stats()["budget_basis"] performs and
+            # this caller throws away. See CostTracker.totals.
+            tracked_input_tokens, tracked_input_cost_usd = self.cost_tracker.totals()
         except Exception:
             logger.debug("Failed to read cost tracker totals for savings history", exc_info=True)
             return total_input_tokens, total_input_cost_usd
 
-        tracked_input_tokens = cost_stats.get("total_input_tokens")
-        tracked_input_cost_usd = cost_stats.get("total_input_cost_usd")
-
         if tracked_input_tokens is not None:
             try:
                 total_input_tokens = self._savings_tracker_input_tokens_offset + max(
@@ -467,6 +485,14 @@ class PrometheusMetrics:
         self.requests_by_stack[slug] += 1
         self.savings_tracker.record_lifetime_stack(slug)
 
+        # Same fan-out as record_compression. This header is the only signal
+        # that names the harness when an agent is pointed at a persistent proxy
+        # rather than launched by `headroom wrap`, and the beacon cannot import
+        # headroom.proxy to read requests_by_stack itself.
+        from headroom.telemetry.session import record_stack as _beacon_stack
+
+        _beacon_stack(slug)
+
     def record_compression(
         self,
         strategy: str,
@@ -497,6 +523,22 @@ class PrometheusMetrics:
         if saved > 0:
             self.tokens_saved_by_strategy[strategy] += saved
 
+        # Fan out to the beacon. This object is the configured
+        # CompressionObserver for the proxy's pipelines, so it is where those
+        # events already arrive with both token counts — a second observer here
+        # would mean a second measurement pass for numbers in hand. (The paths
+        # that have no observer at all pass telemetry's
+        # BeaconCompressionObserver directly instead.)
+        #
+        # The beacon is ON by default, so this does not short-circuit in
+        # practice and must stay off the aggregator's lock: it stages into a
+        # dedicated mutex that the request path never takes, which is what
+        # keeps this method's "synchronous + lock-free" contract honest with
+        # respect to everything else in the process.
+        from headroom.telemetry.session import record_compression as _beacon_compression
+
+        _beacon_compression(strategy, original_tokens, compressed_tokens)
+
     def record_extension_savings(self, key: str, saved: int) -> None:
         """Accumulate tokens saved by a proxy extension, keyed by ``key``.
 
@@ -691,6 +733,7 @@ class PrometheusMetrics:
         client: str | None = None,
         tool_search_saved: int = 0,
         local_input_tokens: int | None = None,
+        savings_attribution: list[dict[str, Any]] | None = None,
     ):
         """Record metrics for a request.
 
@@ -700,6 +743,10 @@ class PrometheusMetrics:
         reduction/yield/ledger math never straddles two rulers. Defaults to
         ``input_tokens`` when omitted, preserving pre-split behaviour.
         """
+        # Local import mirrors record_stack: defers to call-time (the telemetry
+        # package is fully loaded by then), avoiding an import cycle at module load.
+        from headroom.telemetry.context import MAX_DISTINCT_MODELS
+
         ledger_input_tokens = input_tokens if local_input_tokens is None else local_input_tokens
         # Post-guard invariant (all providers): Headroom never forwards a request
         # larger than the original — handlers revert any inflation before sending
@@ -714,10 +761,35 @@ class PrometheusMetrics:
                 model,
             )
             tokens_saved = 0
+        savings_usd = estimate_request_savings_usd(
+            model,
+            compression_tokens_saved=tokens_saved,
+            tool_schema_tokens_saved=tool_search_saved,
+            output_tokens_saved=output_tokens_saved,
+            cache_read_tokens=cache_read_tokens,
+        )
         async with self._lock:
             self.requests_total += 1
             self.requests_by_provider[provider] += 1
-            self.requests_by_model[model] += 1
+            # Cap client-supplied model cardinality. `model` is client-controlled
+            # (body.get("model") in the openai/gemini/bedrock handlers), so an
+            # arbitrary-model client would otherwise grow requests_by_model and the
+            # exported series without bound. Bucket over-cap models into "other"
+            # (the sentinel docs/observability.md documents for `tier`), mirroring
+            # the requests_by_stack cap. Membership test, never a defaultdict index:
+            # indexing would materialize the key and defeat the cap.
+            if model in self.requests_by_model or len(self.requests_by_model) < MAX_DISTINCT_MODELS:
+                bounded_model = model
+            else:
+                bounded_model = _OTHER_MODEL
+                if not self._model_cardinality_warned:
+                    self._model_cardinality_warned = True
+                    logger.warning(
+                        "metrics.record: model cardinality cap (%d) reached; "
+                        'bucketing further models into "other"',
+                        MAX_DISTINCT_MODELS,
+                    )
+            self.requests_by_model[bounded_model] += 1
 
             if cached:
                 self.requests_cached += 1
@@ -726,6 +798,26 @@ class PrometheusMetrics:
             self.tokens_output_total += output_tokens
             self.tokens_saved_total += tokens_saved
             self.tool_search_saved_total += max(0, int(tool_search_saved))
+            for item in savings_attribution or ():
+                source = str(item.get("source") or "other")[:64]
+                realized = bool(item.get("realized", True))
+                key = f"{source}:{int(realized)}"
+                row = self.savings_by_source.setdefault(
+                    key,
+                    {
+                        "source": source,
+                        "realized": realized,
+                        "events": 0,
+                        "tokens": 0,
+                        "usd": 0.0,
+                    },
+                )
+                row["events"] = int(row["events"]) + 1
+                row["tokens"] = int(row["tokens"]) + max(0, int(item.get("tokens", 0) or 0))
+                row["usd"] = round(
+                    float(row["usd"]) + float(item.get("usd", 0.0) or 0.0),
+                    12,
+                )
             # See the attribute definition for why this is the right
             # denominator for the active-compression ratio.
             self.attempted_input_tokens_total += max(0, int(attempted_input_tokens))
@@ -749,8 +841,13 @@ class PrometheusMetrics:
                 # is always a cold start (100% write, 0% read) — not a bust.
                 # Only flag as bust when a previously-warm model suddenly has
                 # high write ratio, indicating prefix invalidation.
-                model_req_num = self._cache_requests_by_model[model]
-                self._cache_requests_by_model[model] += 1
+                # bounded_model can be "other" once the cardinality cap trips, which
+                # mixes distinct models in this bust heuristic. That is acceptable:
+                # it only happens past MAX_DISTINCT_MODELS distinct models on cached
+                # anthropic traffic, the worst case is a mis-attributed bust stat,
+                # and it keeps _cache_requests_by_model bounded.
+                model_req_num = self._cache_requests_by_model[bounded_model]
+                self._cache_requests_by_model[bounded_model] += 1
                 if provider == "anthropic" and model_req_num > 0:
                     total_cached = cache_read_tokens + cache_write_tokens
                     if total_cached > 0 and cache_write_tokens > total_cached * 0.5:
@@ -825,6 +922,7 @@ class PrometheusMetrics:
                 total_input_tokens=total_input_tokens,
                 total_input_cost_usd=total_input_cost_usd,
                 output_tokens_saved=output_tokens_saved,
+                estimated_savings_usd=savings_usd,
             )
 
         # Also append to the durable, multi-process savings ledger so
@@ -845,14 +943,23 @@ class PrometheusMetrics:
         # would hold the lock for the whole write instead of just the syscall.
         # ponytail: default thread pool, not a dedicated executor -- give it one
         # if a profile ever shows writers parked on flock saturating the pool.
-        if tokens_saved > 0 and not self._stateless:
+        # tool_search_deferral saves tool-SCHEMA tokens that never move the
+        # message-level tok_before/after, so a tool-heavy turn can have
+        # tokens_saved=0 while genuinely deferring thousands of tokens. Fold that
+        # component into the ledger delta the same way the PERF headline and
+        # perf/analyzer do (`headline_before = before + tool_saved`); otherwise
+        # `headroom savings` understates real compression 7-10x on tool-search
+        # sessions and drops deferral-only turns from the ledger entirely (#2795).
+        deferral_saved = max(0, int(tool_search_saved))
+        ledger_saved = tokens_saved + deferral_saved
+        if ledger_saved > 0 and not self._stateless:
             # `input_tokens` here is the optimized (post-compression) count
             # that was actually forwarded — see emit_request_outcome, which
             # passes `input_tokens=outcome.optimized_tokens`. The ledger's
             # `before` is the pre-compression original and `after` is what we
             # forwarded, and `headroom savings` derives the reduction percent
             # as saved / before. Passing the forwarded count as `before`
-            # understated the original by `tokens_saved`, inflating that
+            # understated the original by `ledger_saved`, inflating that
             # percentage (e.g. a real 40% reduction was reported as ~67%).
             # Reconstruct the original as forwarded + saved.
             await asyncio.to_thread(
@@ -863,19 +970,21 @@ class PrometheusMetrics:
                 # `tokens_saved` yields a mixed-ruler before/after (local 10->6
                 # with the provider reporting 8 would record 12->8). Use the
                 # caller's local count when supplied.
-                tokens_before=ledger_input_tokens + tokens_saved,
+                tokens_before=ledger_input_tokens + ledger_saved,
                 tokens_after=ledger_input_tokens,
                 model=model,
                 client=client or "proxy",
                 source="proxy",
             )
 
-        self._get_otel_metrics().record_proxy_request(
+        otel_metrics = self._get_otel_metrics()
+        otel_metrics.record_proxy_request(
             provider=provider,
             model=model,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             tokens_saved=tokens_saved,
+            tool_search_saved=tool_search_saved,
             latency_ms=latency_ms,
             cached=cached,
             overhead_ms=overhead_ms,
@@ -885,7 +994,15 @@ class PrometheusMetrics:
             cache_write_5m_tokens=cache_write_5m_tokens,
             cache_write_1h_tokens=cache_write_1h_tokens,
             uncached_input_tokens=uncached_input_tokens,
+            attempted_input_tokens=attempted_input_tokens,
+            output_tokens_saved=output_tokens_saved,
+            savings_usd=savings_usd,
+            project=project,
+            client=client,
         )
+        record_attribution = getattr(otel_metrics, "record_savings_attribution", None)
+        if record_attribution is not None and savings_attribution:
+            record_attribution(savings_attribution)
 
     async def record_stage_timings(
         self,
@@ -1081,6 +1198,47 @@ class PrometheusMetrics:
                 help_text="Tokens saved by optimization",
                 value=self.tokens_saved_total,
             )
+            if self.savings_by_source:
+                lines.extend(
+                    [
+                        "# HELP headroom_savings_attribution_events_total Per-request savings attribution events",
+                        "# TYPE headroom_savings_attribution_events_total counter",
+                    ]
+                )
+                for row in self.savings_by_source.values():
+                    labels = _format_labels(
+                        {"source": str(row["source"]), "realized": str(row["realized"]).lower()}
+                    )
+                    lines.append(
+                        f"headroom_savings_attribution_events_total{labels} {row['events']}"
+                    )
+                lines.extend(
+                    [
+                        "",
+                        "# HELP headroom_savings_attributed_tokens_total Tokens attributed to a savings source",
+                        "# TYPE headroom_savings_attributed_tokens_total counter",
+                    ]
+                )
+                for row in self.savings_by_source.values():
+                    labels = _format_labels(
+                        {"source": str(row["source"]), "realized": str(row["realized"]).lower()}
+                    )
+                    lines.append(
+                        f"headroom_savings_attributed_tokens_total{labels} {row['tokens']}"
+                    )
+                lines.extend(
+                    [
+                        "",
+                        "# HELP headroom_savings_attributed_usd_total Cost savings attributed to a source; may be negative",
+                        "# TYPE headroom_savings_attributed_usd_total gauge",
+                    ]
+                )
+                for row in self.savings_by_source.values():
+                    labels = _format_labels(
+                        {"source": str(row["source"]), "realized": str(row["realized"]).lower()}
+                    )
+                    lines.append(f"headroom_savings_attributed_usd_total{labels} {row['usd']}")
+                lines.append("")
             _append_metric(
                 lines,
                 name="headroom_persistent_savings_requests_total",
@@ -1234,10 +1392,11 @@ class PrometheusMetrics:
                     ]
                 )
                 for _provider, _reasons in self.cache_miss_attribution_by_provider.items():
+                    _safe_provider = _escape_label_value(str(_provider))
                     for _reason, _count in _reasons.items():
                         lines.append(
-                            f'headroom_cache_miss_attribution_total{{provider="{_provider}",'
-                            f'reason="{_reason}"}} {_count}'
+                            f'headroom_cache_miss_attribution_total{{provider="{_safe_provider}",'
+                            f'reason="{_escape_label_value(str(_reason))}"}} {_count}'
                         )
                 lines.append("")
 
@@ -1294,7 +1453,9 @@ class PrometheusMetrics:
                 ]
             )
             for provider, count in self.requests_by_provider.items():
-                lines.append(f'headroom_requests_by_provider{{provider="{provider}"}} {count}')
+                lines.append(
+                    f'headroom_requests_by_provider{{provider="{_escape_label_value(str(provider))}"}} {count}'
+                )
             lines.append("")
 
             lines.extend(
@@ -1304,7 +1465,9 @@ class PrometheusMetrics:
                 ]
             )
             for model, count in self.requests_by_model.items():
-                lines.append(f'headroom_requests_by_model{{model="{model}"}} {count}')
+                lines.append(
+                    f'headroom_requests_by_model{{model="{_escape_label_value(str(model))}"}} {count}'
+                )
             lines.append("")
 
             if self.transform_timing_sum:
@@ -1439,13 +1602,20 @@ class PrometheusMetrics:
                 lines.append("")
 
             if self.cache_by_provider:
+                # The exposition format wants each family's samples grouped, so the
+                # blocks below re-walk this dict once per family. Escape the provider
+                # keys once here instead of at all eleven emission sites.
+                cache_by_provider = {
+                    _escape_label_value(str(name)): stats
+                    for name, stats in self.cache_by_provider.items()
+                }
                 lines.extend(
                     [
                         "# HELP headroom_cache_read_tokens_total Provider cache read tokens",
                         "# TYPE headroom_cache_read_tokens_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_cache_read_tokens_total{{provider="{provider}"}} {stats["cache_read_tokens"]}'
                     )
@@ -1456,7 +1626,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_cache_write_tokens_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_cache_write_tokens_total{{provider="{provider}"}} {stats["cache_write_tokens"]}'
                     )
@@ -1467,7 +1637,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_cache_write_ttl_tokens_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_cache_write_ttl_tokens_total{{provider="{provider}",ttl="5m"}} {stats["cache_write_5m_tokens"]}'
                     )
@@ -1481,7 +1651,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_cache_write_ttl_requests_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_cache_write_ttl_requests_total{{provider="{provider}",ttl="5m"}} {stats["cache_write_5m_requests"]}'
                     )
@@ -1495,7 +1665,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_uncached_input_tokens_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_uncached_input_tokens_total{{provider="{provider}"}} {stats["uncached_input_tokens"]}'
                     )
@@ -1506,7 +1676,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_provider_cache_requests_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_provider_cache_requests_total{{provider="{provider}"}} {stats["requests"]}'
                     )
@@ -1517,7 +1687,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_provider_cache_hit_requests_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_provider_cache_hit_requests_total{{provider="{provider}"}} {stats["hit_requests"]}'
                     )
@@ -1528,7 +1698,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_provider_cache_bust_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_provider_cache_bust_total{{provider="{provider}"}} {stats["bust_count"]}'
                     )
@@ -1539,7 +1709,7 @@ class PrometheusMetrics:
                         "# TYPE headroom_provider_cache_bust_write_tokens_total counter",
                     ]
                 )
-                for provider, stats in self.cache_by_provider.items():
+                for provider, stats in cache_by_provider.items():
                     lines.append(
                         f'headroom_provider_cache_bust_write_tokens_total{{provider="{provider}"}} {stats["bust_write_tokens"]}'
                     )
diff --git a/headroom/proxy/route_advice.py b/headroom/proxy/route_advice.py
new file mode 100644
index 000000000..84ad31e21
--- /dev/null
+++ b/headroom/proxy/route_advice.py
@@ -0,0 +1,206 @@
+"""Per-request backend selection, published by an extension.
+
+WHY THIS EXISTS
+    Headroom picks its egress backend ONCE, at startup: `create_proxy_backend`
+    returns a single `Backend` (or None for the direct Anthropic path) and
+    every request goes through it. That is right for "run this whole proxy
+    against Bedrock instead of Anthropic", and it is the wrong shape for "this
+    request is cheaper on a different provider than the last one".
+
+    Meanwhile `ModelRouter` already lets an extension change `body["model"]`
+    per request -- but only within whatever protocol the request arrived in,
+    because a model id alone cannot move a request to another provider.
+
+    So a router extension can currently decide something Headroom has no way to
+    carry out. This module is the missing half: a routing decision that names a
+    PROVIDER as well as a model, and a per-request backend to serve it.
+
+THE CONTRACT, AND WHY IT IS VENDOR-NEUTRAL
+    An extension sets `request.state.headroom_route` to a `RouteAdvice`.
+    Headroom reads it, resolves a backend for `advice.provider`, and dispatches
+    there. Nothing in core names any particular extension.
+
+ABSENT MEANS UNCHANGED
+    This is the property that matters most. With no extension installed, no
+    extension setting the field, an unresolvable provider, or a backend that
+    fails to construct, `backend_for()` returns exactly what
+    `self.anthropic_backend` would have been -- including None, which keeps the
+    direct-API path. Nothing about the default deployment moves.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+STATE_ATTR = "headroom_route"
+
+# Providers that speak the Anthropic Messages API natively, i.e. the shape the
+# proxy already holds. Everything else needs a translating backend.
+_NATIVE = ("anthropic",)
+
+
+@dataclass(frozen=True)
+class RouteAdvice:
+    """A routing decision an extension wants Headroom to carry out.
+
+    Only `model` and `provider` are required; the rest is explanatory and is
+    logged rather than acted on, so an extension can be as terse as it likes.
+    """
+
+    model: str
+    provider: str = ""
+    reason: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.model:
+            raise ValueError("RouteAdvice needs a model")
+
+
+def advice_from(request: Any) -> RouteAdvice | None:
+    """The advice an extension published, if any. Never raises.
+
+    Duck-typed on purpose: an extension should not have to import Headroom to
+    talk to Headroom. Anything carrying `.model` (and optionally `.provider`)
+    works, which also keeps extensions from breaking when this dataclass gains
+    a field.
+    """
+    obj = getattr(getattr(request, "state", None), STATE_ATTR, None)
+    if obj is None:
+        return None
+    model = getattr(obj, "model", None)
+    if not isinstance(model, str) or not model:
+        return None
+    provider = getattr(obj, "provider", "") or ""
+    return RouteAdvice(
+        model=model,
+        provider=provider if isinstance(provider, str) else "",
+        reason=str(getattr(obj, "reason", "") or "")[:400],
+    )
+
+
+class BackendResolver:
+    """Lazily builds and caches one translating backend per provider.
+
+    Construction is not free -- the Bedrock path calls out to AWS to enumerate
+    inference profiles -- so backends are built on first use for a provider and
+    kept. A provider that fails to construct is remembered as a failure and not
+    retried on every request; the request falls back to the default backend
+    rather than erroring, because a routing preference must never be able to
+    take traffic down.
+    """
+
+    def __init__(self, default: Any = None) -> None:
+        self._default = default
+        self._cache: dict[str, Any] = {}
+        self._failed: set[str] = set()
+
+    @property
+    def default(self) -> Any:
+        return self._default
+
+    def for_request(self, request: Any, *, body: dict | None = None) -> Any:
+        """The backend to serve this request. Falls back to the default."""
+        advice = advice_from(request)
+        if advice is None:
+            return self._default
+
+        provider = advice.provider or _provider_of(advice.model)
+        if not provider or provider in _NATIVE:
+            # Same protocol the proxy already speaks -- a `body["model"]`
+            # rewrite is enough and the extension has already done it. Nothing
+            # to switch.
+            return self._default
+        if provider in self._failed:
+            return self._default
+
+        backend = self._cache.get(provider)
+        if backend is None:
+            try:
+                backend = self._build(provider)
+            except Exception as exc:  # noqa: BLE001 - see the class docstring
+                log.warning("route advice: building %r raised (%s)", provider, exc)
+                backend = None
+            if backend is None:
+                self._failed.add(provider)
+                return self._default
+            self._cache[provider] = backend
+
+        if body is not None:
+            # The extension chose the model; make sure the body agrees, since
+            # it could not safely write a foreign model id itself. Log here
+            # too -- a caller asking without a body is only checking WHICH
+            # backend will serve the request, and would log the same decision
+            # a second time.
+            body["model"] = advice.model
+            log.info(
+                "route advice: %s via %s (%s)",
+                advice.model,
+                provider,
+                advice.reason or "no reason given",
+            )
+        return backend
+
+    def _build(self, provider: str) -> Any:
+        # Validate the name FIRST. `LiteLLMBackend` accepts an unknown provider
+        # happily -- the registry falls through to a generic pass-through
+        # config -- so a typo builds a backend that only fails later, at
+        # request time, with an error that points nowhere near the typo.
+        if not _known_provider(provider):
+            log.warning("route advice: %r is not a litellm provider; ignoring", provider)
+            return None
+        try:
+            from headroom.backends.litellm import LiteLLMBackend
+
+            return LiteLLMBackend(provider=provider)
+        except Exception as exc:  # noqa: BLE001 - never fail a request for this
+            log.warning(
+                "route advice: cannot build a backend for %r (%s); "
+                "falling back to the configured backend",
+                provider,
+                exc,
+            )
+            return None
+
+
+def resolver_for(handler: Any) -> BackendResolver:
+    """The handler's resolver, built once and reused.
+
+    Lives here rather than on a handler mixin so every protocol handler can
+    reach it without depending on a sibling mixin. Rebuilt if
+    `anthropic_backend` is reassigned (tests do this), so the resolver can
+    never serve a stale default.
+    """
+    default = getattr(handler, "anthropic_backend", None)
+    cached = getattr(handler, "_route_resolver_cache", None)
+    if cached is None or cached.default is not default:
+        cached = BackendResolver(default)
+        handler._route_resolver_cache = cached
+    return cached
+
+
+def _known_provider(provider: str) -> bool:
+    """Is this a provider litellm actually knows about?"""
+    try:
+        import litellm
+
+        names = {getattr(p, "value", None) or str(p) for p in getattr(litellm, "provider_list", [])}
+        return provider in names
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _provider_of(model: str) -> str:
+    """Provider from a `provider/model` spec, else from litellm's table."""
+    if "/" in model:
+        return model.split("/", 1)[0]
+    try:
+        import litellm
+
+        entry = litellm.model_cost.get(model) or {}
+        return str(entry.get("litellm_provider") or "")
+    except Exception:  # noqa: BLE001
+        return ""
diff --git a/headroom/proxy/runtime_env.py b/headroom/proxy/runtime_env.py
index 22a84a8ec..bc4c03bc2 100644
--- a/headroom/proxy/runtime_env.py
+++ b/headroom/proxy/runtime_env.py
@@ -2,7 +2,7 @@
 
 Most Headroom settings are read once at proxy startup into ``Config`` and are
 visible in ``/health``. A second, smaller class of environment variables is
-read *live* — on every request (the output-shaper family) or captured at module
+read *live* — on every request (output-shaper tuning) or captured at module
 import (the ast-grep read-rewrite threshold). The proxy reads these from its own
 process environment, so a *reused* proxy — one ``headroom wrap`` attaches to
 rather than starting fresh — never sees values a user exports afterwards. The
@@ -18,6 +18,10 @@ instead of ``os.environ.get`` so an override wins over the launch-time
 environment; with no override set, behaviour is byte-for-byte identical to
 reading the environment directly.
 
+The output-shaper master switch is rollout-managed. Hot-reloading that legacy
+alias also replaces the proxy's immutable rollout snapshot; the active channel
+and named kill switch still bound the resulting decision.
+
 Scope rule: a variable belongs here only if the proxy reads it *after* startup
 (or captures it at import) AND it is not already reflected in the ``/health``
 ``config`` block that ``wrap`` compares for reuse. Startup-captured settings
diff --git a/headroom/proxy/savings_attribution.py b/headroom/proxy/savings_attribution.py
new file mode 100644
index 000000000..db7f517e9
--- /dev/null
+++ b/headroom/proxy/savings_attribution.py
@@ -0,0 +1,110 @@
+"""Bounded attribution for savings that do not have a built-in metric."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from collections.abc import MutableMapping
+from typing import Any
+
+SAVINGS_ATTRIBUTION_TAG = "_headroom_savings_attribution"
+_NAME_RE = re.compile(r"[^a-z0-9_.-]+")
+MAX_SOURCES = 32
+_SCOPE_KEY = "headroom_savings_attribution"
+
+
+def _source_name(value: object) -> str:
+    name = _NAME_RE.sub("_", str(value or "other").strip().lower()).strip("_.-")
+    return (name or "other")[:64]
+
+
+def _ledger(tags: MutableMapping[str, Any]) -> list[dict[str, Any]]:
+    current = tags.get(SAVINGS_ATTRIBUTION_TAG)
+    if isinstance(current, list):
+        return current
+    current = []
+    tags[SAVINGS_ATTRIBUTION_TAG] = current
+    return current
+
+
+def bind_scope(tags: MutableMapping[str, Any], scope: MutableMapping[str, Any]) -> None:
+    """Share one ledger between ASGI middleware and the request handler."""
+    state = scope.setdefault("state", {})
+    ledger = state.get(_SCOPE_KEY)
+    if not isinstance(ledger, list):
+        ledger = []
+        state[_SCOPE_KEY] = ledger
+    tags[SAVINGS_ATTRIBUTION_TAG] = ledger
+
+
+def record_scope_savings(scope: MutableMapping[str, Any], source: object, **values: Any) -> None:
+    state = scope.setdefault("state", {})
+    ledger = state.get(_SCOPE_KEY)
+    if not isinstance(ledger, list):
+        ledger = []
+        state[_SCOPE_KEY] = ledger
+    record_savings({SAVINGS_ATTRIBUTION_TAG: ledger}, source, **values)
+
+
+def record_savings(
+    tags: MutableMapping[str, Any],
+    source: object,
+    *,
+    tokens: int = 0,
+    usd: float = 0.0,
+    realized: bool = True,
+    estimated: bool = False,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """Attribute savings to a source; this never changes headline totals."""
+    ledger = _ledger(tags)
+    if len(ledger) >= MAX_SOURCES:
+        return
+    item: dict[str, Any] = {
+        "source": _source_name(source),
+        "realized": bool(realized),
+        "estimated": bool(estimated),
+        "tokens": max(0, int(tokens or 0)),
+        "usd": round(float(usd or 0.0), 12),
+    }
+    if details:
+        item["details"] = {
+            _source_name(key): value
+            for key, value in list(details.items())[:12]
+            if isinstance(value, (str, int, float, bool)) or value is None
+        }
+    ledger.append(item)
+
+
+def from_tags(tags: MutableMapping[str, Any] | None) -> list[dict[str, Any]]:
+    raw = (tags or {}).get(SAVINGS_ATTRIBUTION_TAG)
+    if not isinstance(raw, list):
+        return []
+    return [dict(item) for item in raw[:MAX_SOURCES] if isinstance(item, dict)]
+
+
+def public_tags(tags: MutableMapping[str, Any] | None) -> dict[str, Any]:
+    return {key: value for key, value in (tags or {}).items() if key != SAVINGS_ATTRIBUTION_TAG}
+
+
+def encode(items: list[dict[str, Any]]) -> str:
+    if not items:
+        return "none"
+    payload = json.dumps(items, separators=(",", ":"), sort_keys=True).encode()
+    return base64.urlsafe_b64encode(payload).decode().rstrip("=")
+
+
+def decode(value: str) -> list[dict[str, Any]]:
+    if not value or value == "none":
+        return []
+    try:
+        padded = value + "=" * (-len(value) % 4)
+        decoded = json.loads(base64.urlsafe_b64decode(padded).decode())
+    except Exception:
+        return []
+    return (
+        [dict(item) for item in decoded if isinstance(item, dict)]
+        if isinstance(decoded, list)
+        else []
+    )
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index 75ff59ce5..44ba43e12 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -14,8 +14,10 @@ import math
 import os
 import tempfile
 import threading
+from collections.abc import Mapping
 from csv import DictWriter
 from datetime import datetime, timedelta, timezone
+from functools import lru_cache
 from io import StringIO
 from pathlib import Path
 from typing import Any
@@ -164,6 +166,23 @@ def _normalize_model(value: Any) -> str:
     return cleaned or MODEL_UNKNOWN
 
 
+# `_resolve_litellm_model` is called on every savings-tracking update (i.e.
+# every request), and `model` is client-controlled — it comes straight off
+# the request body. For a model LiteLLM can't price (a custom / local /
+# gateway name), the uncached fallback below calls `litellm.cost_per_token`
+# purely to probe resolvability, which prints LiteLLM's noisy "Provider
+# List: https://docs.litellm.ai/docs/providers" banner on every failed probe
+# (#2851). Cache the resolution per model name so that probe runs at most
+# once per distinct model — bounded, not a plain dict: a request-facing
+# proxy must not let a caller grow an unbounded cache for free by sending a
+# fresh model string on every request. `maxsize` caps memory; LRU eviction
+# means a model that stops being sent eventually falls out and simply
+# re-probes if it's ever sent again — never a correctness issue, only
+# whether the probe (and its noisy failure banner) reruns.
+_MODEL_RESOLUTION_CACHE_MAXSIZE = 256
+
+
+@lru_cache(maxsize=_MODEL_RESOLUTION_CACHE_MAXSIZE)
 def _resolve_litellm_model(model: str) -> str:
     """Resolve model name to one LiteLLM recognizes.
 
@@ -173,6 +192,12 @@ def _resolve_litellm_model(model: str) -> str:
     "claude-opus" identically to the live /stats path. Uses the shared result
     only when it maps to a priced model_cost key; otherwise falls through to the
     bare-prefix logic below. Fail-soft: pricing never breaks bookkeeping.
+
+    Bounded LRU cache, keyed by model name — see
+    ``_MODEL_RESOLUTION_CACHE_MAXSIZE`` above. Tests that mock the LiteLLM
+    module across calls with the same model name must call
+    ``_resolve_litellm_model.cache_clear()`` between cases, or results from
+    an earlier case leak in.
     """
     litellm = _get_litellm_module()
     if litellm is None:
@@ -304,6 +329,37 @@ def _estimate_cache_savings_usd(model: str, cache_read_tokens: int) -> float:
         return 0.0
 
 
+def estimate_request_savings_usd(
+    model: str,
+    *,
+    compression_tokens_saved: int = 0,
+    tool_schema_tokens_saved: int = 0,
+    output_tokens_saved: int = 0,
+    cache_read_tokens: int = 0,
+) -> dict[str, float]:
+    """Price one request's distinct savings layers for external telemetry.
+
+    The values use the same pricing functions as the built-in dashboard. They
+    stay separate because provider-cache benefit is not caused by compression,
+    and extension attribution can be explanatory rather than additive.
+    """
+
+    return {
+        "compression": _estimate_compression_savings_usd(
+            model, max(_coerce_int(compression_tokens_saved), 0)
+        ),
+        "tool_schema": _estimate_compression_savings_usd(
+            model, max(_coerce_int(tool_schema_tokens_saved), 0)
+        ),
+        "output_shaping": _estimate_output_savings_usd(
+            model, max(_coerce_int(output_tokens_saved), 0)
+        ),
+        "provider_cache": _estimate_cache_savings_usd(
+            model, max(_coerce_int(cache_read_tokens), 0)
+        ),
+    }
+
+
 def _estimate_input_cost_usd(
     model: str,
     input_tokens: int,
@@ -696,6 +752,7 @@ class SavingsTracker:
         uncached_input_tokens: int = 0,
         total_input_tokens: int | None = None,
         total_input_cost_usd: float | None = None,
+        estimated_savings_usd: Mapping[str, float] | None = None,
         timestamp: datetime | str | None = None,
     ) -> bool:
         """Persist a canonical display-session update for every request."""
@@ -711,11 +768,24 @@ class SavingsTracker:
 
         delta_tokens_saved = _coerce_int(tokens_saved)
         delta_input_tokens = _coerce_int(input_tokens)
-        delta_savings_usd = _estimate_compression_savings_usd(model, delta_tokens_saved)
         delta_output_tokens_saved = max(_coerce_int(output_tokens_saved), 0)
-        delta_output_savings_usd = _estimate_output_savings_usd(model, delta_output_tokens_saved)
         delta_cache_read_tokens = _coerce_int(cache_read_tokens)
-        delta_cache_savings_usd = _estimate_cache_savings_usd(model, delta_cache_read_tokens)
+        priced = estimated_savings_usd
+        delta_savings_usd = (
+            max(_coerce_float(priced.get("compression")), 0.0)
+            if priced is not None
+            else _estimate_compression_savings_usd(model, delta_tokens_saved)
+        )
+        delta_output_savings_usd = (
+            max(_coerce_float(priced.get("output_shaping")), 0.0)
+            if priced is not None
+            else _estimate_output_savings_usd(model, delta_output_tokens_saved)
+        )
+        delta_cache_savings_usd = (
+            max(_coerce_float(priced.get("provider_cache")), 0.0)
+            if priced is not None
+            else _estimate_cache_savings_usd(model, delta_cache_read_tokens)
+        )
         delta_input_cost_usd = _estimate_input_cost_usd(
             model,
             delta_input_tokens,
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index c03c76ee8..5a15f5f4a 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -470,6 +470,18 @@ logging.basicConfig(
 )
 logger = logging.getLogger("headroom.proxy")
 
+
+class _SuppressCancelledErrorFilter(logging.Filter):
+    """Hide expected uvicorn CancelledError tracebacks during shutdown."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.levelno == logging.ERROR and record.exc_info:
+            exc_type = record.exc_info[0]
+            if exc_type is not None and issubclass(exc_type, asyncio.CancelledError):
+                return False
+        return True
+
+
 LoopExceptionHandler = Callable[[asyncio.AbstractEventLoop, dict[str, Any]], object]
 
 
@@ -945,7 +957,8 @@ class HeadroomProxy(
         self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"
 
         _intercept_prefix: list = []
-        if os.environ.get("HEADROOM_INTERCEPT_ENABLED"):
+        assert config.rollout is not None
+        if config.rollout.is_enabled("tool_result_interceptors"):
             from headroom.proxy.interceptors import ToolResultInterceptorTransform
 
             _intercept_prefix = [ToolResultInterceptorTransform()]
@@ -1144,6 +1157,19 @@ class HeadroomProxy(
         self._compression_timed_out_in_flight_max: int = 0
         self._compression_quarantine_activations: int = 0
         self._compression_quarantine_skips: int = 0
+        # Time cap on the timeout-debt quarantine. Python cannot preempt a
+        # worker, so one that never returns (a hung/pathological compression)
+        # would keep ``_compression_timed_out_in_flight > 0`` forever and pin the
+        # quarantine open — zeroing out ALL further compression (#2360). The
+        # deadline is (re)set on every fresh timeout; once it lapses with no new
+        # timeouts the leaked worker is presumed abandoned and compression
+        # resumes. The bounded executor still caps thread growth, and any new
+        # timeout re-arms the quarantine.
+        self._compression_quarantine_deadline: float = 0.0
+        self._compression_quarantine_max_seconds: float = _get_env_float(
+            "HEADROOM_COMPRESSION_QUARANTINE_MAX_SECONDS", 60.0
+        )
+        self._compression_quarantine_releases: int = 0
         self._compression_metrics_lock = threading.Lock()
 
         # Backend for Anthropic API (direct, LiteLLM, or any-llm)
@@ -1401,12 +1427,36 @@ class HeadroomProxy(
             ``asyncio.TimeoutError`` subclass) if a prior timed-out worker is
             still running.
         """
+        now = time.monotonic()
         with self._compression_metrics_lock:
             timed_out_in_flight = self._compression_timed_out_in_flight
-            if timed_out_in_flight > 0:
+            quarantined = timed_out_in_flight > 0 and now < self._compression_quarantine_deadline
+            # Debt outlived the cap: presume the worker leaked/hung and stop
+            # blocking on it. Count the release once per lapse (while debt stands
+            # and the deadline has passed) so operators can see it happened.
+            released = (
+                timed_out_in_flight > 0
+                and not quarantined
+                and self._compression_quarantine_deadline > 0.0
+            )
+            if quarantined:
                 self._compression_quarantine_skips += 1
+            if released:
+                self._compression_quarantine_releases += 1
+                # Clear the deadline so the release is recorded once, not on
+                # every subsequent request until the worker (maybe never) exits.
+                self._compression_quarantine_deadline = 0.0
 
-        if timed_out_in_flight > 0:
+        if released:
+            self.metrics.record_compression_quarantine("released")
+            logger.warning(
+                "Compression quarantine released after %.0fs cap; %d timed-out "
+                "worker(s) presumed leaked. Compression resumes.",
+                self._compression_quarantine_max_seconds,
+                timed_out_in_flight,
+            )
+
+        if quarantined:
             self.metrics.record_compression_quarantine("skipped")
             raise CompressionQuarantinedError(
                 f"compression quarantined: {timed_out_in_flight} timed-out worker(s) still running"
@@ -1445,6 +1495,12 @@ class HeadroomProxy(
                 self._compression_timed_out_in_flight_max,
                 self._compression_timed_out_in_flight,
             )
+            # (Re)arm the quarantine time cap on every fresh timeout, so ongoing
+            # slowness keeps quarantining while a single leaked worker cannot
+            # hold it past the cap (#2360).
+            self._compression_quarantine_deadline = (
+                time.monotonic() + self._compression_quarantine_max_seconds
+            )
             state["timeout_debt_recorded"] = True
             if was_clear:
                 self._compression_quarantine_activations += 1
@@ -1626,6 +1682,26 @@ class HeadroomProxy(
                 for key, value in transform_status.items():
                     eager_status.setdefault(key, value)
                 transform_statuses.append(transform_status)
+
+        # LiteLLM's pricing tables. MEASURED 2.9-3.8s to import, and it was
+        # being imported lazily ON THE EVENT LOOP during the first request:
+        # emit_request_outcome -> record_request -> _estimate_compression_savings_usd
+        # calls it before its own `tokens_saved <= 0` early return, so even a
+        # request that saved nothing pays for it. Nothing about that is visible
+        # as a failure; it just makes one unlucky user wait ~3s.
+        #
+        # This function already runs under asyncio.to_thread, so importing here
+        # cannot delay the port bind.
+        try:
+            from .savings_tracker import _get_litellm_module
+
+            eager_status.setdefault(
+                "litellm", "ready" if _get_litellm_module() is not None else "not installed"
+            )
+        except Exception as exc:  # pricing is optional; never block startup on it
+            logger.debug("LiteLLM pre-load skipped: %s", exc)
+            eager_status.setdefault("litellm", "skipped")
+
         return eager_status, transform_statuses
 
     async def startup(self):
@@ -2052,16 +2128,18 @@ class HeadroomProxy(
         construct their body from scratch, so canonical serialization is
         correct and original bytes do not exist).
         """
-        from headroom.proxy.body_forwarding import prepare_outbound_body_bytes
+        from headroom.proxy.body_forwarding import select_outbound_body
         from headroom.proxy.helpers import log_outbound_request
 
         last_error = None
         reasons = list(mutation_reasons or [])
-        outbound_bytes, source = prepare_outbound_body_bytes(
+        outbound = select_outbound_body(
             body=body,
             original_body_bytes=original_body_bytes,
             body_mutated=body_mutated,
+            mutation_reasons=reasons,
         )
+        outbound_bytes, source = outbound.content, outbound.source
         outbound_headers = {**headers, "content-type": "application/json"}
 
         log_outbound_request(
@@ -2073,6 +2151,7 @@ class HeadroomProxy(
             mutation_reasons=reasons,
             request_id=request_id,
             source=source,
+            dropped_mutation_reasons=outbound.dropped_mutation_reasons,
         )
 
         post_kwargs: dict = {"content": outbound_bytes, "headers": outbound_headers}
@@ -2521,6 +2600,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         app.state.started_at = time.time()
         app.state.ready = False
         app.state.startup_error = None
+        app.state.periodic_toin_stats_task = None
 
         try:
             try:
@@ -2528,7 +2608,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
                 # Startup
                 await proxy.startup()
                 if config.periodic_toin_stats_enabled:
-                    asyncio.create_task(_log_toin_stats_periodically())
+                    app.state.periodic_toin_stats_task = asyncio.create_task(
+                        _log_toin_stats_periodically()
+                    )
                 if proxy.usage_reporter:
                     await proxy.usage_reporter.start(proxy)
                 if proxy.traffic_learner:
@@ -2565,21 +2647,49 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
                 loop.set_exception_handler(previous)
 
             app.state.ready = False
-            # Shutdown
+            logger.info("event=proxy_shutdown reason=signal pid=%d", os.getpid())
+
+            async def _timed(coro: Any, *, label: str, timeout: float) -> None:
+                try:
+                    await asyncio.wait_for(coro, timeout=timeout)
+                except Exception as exc:
+                    logger.warning(
+                        "event=shutdown_step_timeout_or_error label=%s timeout=%.1fs exc=%r",
+                        label,
+                        timeout,
+                        exc,
+                    )
+
+            periodic_toin_stats_task = app.state.periodic_toin_stats_task
+            if periodic_toin_stats_task is not None:
+                periodic_toin_stats_task.cancel()
+                await _timed(
+                    asyncio.gather(periodic_toin_stats_task, return_exceptions=True),
+                    label="periodic_toin_stats.stop",
+                    timeout=3.0,
+                )
+                app.state.periodic_toin_stats_task = None
+
             if _cc_reconciler is not None:
-                await _cc_reconciler.stop()
+                await _timed(_cc_reconciler.stop(), label="cc_reconciler.stop", timeout=3.0)
             if _beacon_is_owner[0]:
                 _release_beacon_lock()
             if proxy.usage_reporter:
-                await proxy.usage_reporter.stop()
+                await _timed(proxy.usage_reporter.stop(), label="usage_reporter.stop", timeout=3.0)
             if proxy.traffic_learner:
-                await proxy.traffic_learner.stop()
+                await _timed(
+                    proxy.traffic_learner.stop(), label="traffic_learner.stop", timeout=3.0
+                )
             if proxy._background_compression_enabled:
-                await proxy._background_compressor.stop()
+                await _timed(
+                    proxy._background_compressor.stop(),
+                    label="background_compressor.stop",
+                    timeout=3.0,
+                )
             proxy._background_compression_executor.shutdown(wait=False)
             if proxy.code_graph_watcher:
                 proxy.code_graph_watcher.stop()
-            await proxy.shutdown()
+            await _timed(proxy.shutdown(), label="proxy.shutdown", timeout=5.0)
             shutdown_headroom_tracing()
             shutdown_otel_metrics()
 
@@ -2622,15 +2732,29 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         *,
         enabled: bool,
         ready: bool,
+        optional: bool = False,
         **details: Any,
     ) -> dict[str, Any]:
-        status = "disabled" if not enabled else ("healthy" if ready else "unhealthy")
-        return {
+        if not enabled:
+            status = "disabled"
+        elif ready:
+            status = "healthy"
+        elif optional:
+            # Optional/non-gating components report "degraded" rather than
+            # "unhealthy" so the top-level status: "healthy" / ready: true
+            # payload is not contradicted by a component-level failure label.
+            status = "degraded"
+        else:
+            status = "unhealthy"
+        result: dict[str, Any] = {
             "enabled": enabled,
             "ready": (ready if enabled else True),
             "status": status,
-            **details,
         }
+        if optional:
+            result["optional"] = True
+        result.update(details)
+        return result
 
     def _kompress_health_routers() -> list[ContentRouter]:
         routers: list[ContentRouter] = []
@@ -2740,6 +2864,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             "kompress": _component_health(
                 enabled=kompress_enabled,
                 ready=proxy.warmup.kompress.status == "loaded",
+                optional=True,
                 backend=proxy.warmup.kompress.info.get("backend", None),
             ),
         }
@@ -3279,6 +3404,40 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
     from headroom.proxy.loopback_guard import require_loopback as _require_loopback
     from headroom.proxy.loopback_guard import require_same_origin as _require_same_origin
 
+    def _require_loopback_or_trusted_dashboard_client(request: Request) -> None:
+        """Allow loopback callers, or gateway-forwarded dashboard clients.
+
+        Mirrors the trust chain already used by /stats and /stats-lifetime
+        (see _request_can_view_dashboard_metadata) so the settings UI works
+        the same way behind a reverse-proxy/gateway (issue #2466).
+        """
+        if not _request_can_view_dashboard_metadata(request, trusted_dashboard_client_cidrs):
+            raise HTTPException(status_code=404)
+
+    def _require_same_origin_or_trusted_dashboard_client(request: Request) -> None:
+        """Same-origin CSRF guard for settings writes, trusted-dashboard aware.
+
+        ``require_same_origin`` only accepts an ``Origin`` that itself names a
+        loopback host, so a browser POST from a trusted-gateway dashboard
+        client was rejected even though the paired GET routes allow that same
+        caller (issue #2466). For non-loopback callers, accept an ``Origin``
+        that matches this request's own Host header, provided the caller is
+        already an IP-literal-Host, CIDR-trusted dashboard client. Loopback
+        callers keep the stricter loopback-only origin check unchanged.
+        """
+        if not _request_is_loopback(request):
+            origin = request.headers.get("origin")
+            host_header = request.headers.get("host")
+            if (
+                origin
+                and origin != "null"
+                and host_header
+                and _request_has_same_origin_or_no_provenance(request, host_header)
+                and _request_can_view_dashboard_metadata(request, trusted_dashboard_client_cidrs)
+            ):
+                return
+        _require_same_origin(request)
+
     @app.get("/admin/upstream", dependencies=[Depends(_require_loopback)])
     async def get_upstream():
         """Current Anthropic upstream + cc-switch reconciler state (loopback-only).
@@ -3342,8 +3501,8 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
 
         Loopback-only. The body is a flat ``{ENV_NAME: "value"}`` map; unknown
         keys and non-string values are ignored. Returns what was applied plus
-        the resulting live config. Last writer wins (overrides are global to the
-        proxy, which is inherent — every wrapper shares one process).
+        the resulting live config. Last writer wins in a single-worker proxy;
+        multi-worker proxies reject the update because overrides are process-local.
         """
         try:
             body = await request.json()
@@ -3354,7 +3513,27 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
                 status_code=400,
                 content={"error": "expected a JSON object of {ENV_NAME: value}"},
             )
+        if proxy.config.worker_processes > 1:
+            return JSONResponse(
+                status_code=409,
+                content={
+                    "error": (
+                        "runtime environment hot reload is unavailable with multiple "
+                        "worker processes; restart the proxy with the desired environment"
+                    ),
+                    "worker_processes": proxy.config.worker_processes,
+                },
+            )
         applied = runtime_env.set_overrides(body)
+        rollout_aliases = {
+            key: value for key, value in applied.items() if key == "HEADROOM_OUTPUT_SHAPER"
+        }
+        if rollout_aliases:
+            assert proxy.config.rollout is not None
+            proxy.config.rollout = proxy.config.rollout.with_legacy_env(rollout_aliases)
+            async with _stats_snapshot_lock:
+                _stats_snapshot["value"] = None
+                _stats_snapshot["expires_at"] = 0.0
         if applied:
             logger.info("runtime-env hot-reload applied: %s", sorted(applied))
             # Record which runtime-env keys changed (the "what" of a config
@@ -3369,7 +3548,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             )
         return JSONResponse(
             status_code=200,
-            content={"applied": applied, "runtime_env": runtime_env.effective_runtime_env()},
+            content={
+                "applied": applied,
+                "runtime_env": runtime_env.effective_runtime_env(),
+                "rollout": proxy.config.rollout.to_dict() if proxy.config.rollout else None,
+            },
         )
 
     # Vendored dashboard JS (tailwind/htmx/alpine). Mounted before
@@ -3399,7 +3582,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
     # (Phase 3's /settings/apply drives that).
     from headroom import settings_store
 
-    @app.get("/settings/schema", dependencies=[Depends(_require_loopback)])
+    @app.get(
+        "/settings/schema", dependencies=[Depends(_require_loopback_or_trusted_dashboard_client)]
+    )
     async def settings_schema(_request: Request):
         """Registry + grouped fields + effective values for the settings form."""
         schema = settings_store.to_schema()
@@ -3416,12 +3601,18 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             schema["supervised"] = False
         return JSONResponse(status_code=200, content=schema)
 
-    @app.get("/settings", dependencies=[Depends(_require_loopback)])
+    @app.get("/settings", dependencies=[Depends(_require_loopback_or_trusted_dashboard_client)])
     async def settings_get(_request: Request):
         """Return stored (file) values only; secret fields masked."""
         return JSONResponse(status_code=200, content=settings_store.stored_values())
 
-    @app.post("/settings", dependencies=[Depends(_require_loopback), Depends(_require_same_origin)])
+    @app.post(
+        "/settings",
+        dependencies=[
+            Depends(_require_loopback_or_trusted_dashboard_client),
+            Depends(_require_same_origin_or_trusted_dashboard_client),
+        ],
+    )
     async def settings_post(request: Request):
         """Persist settings. Unknown key -> 400; bad type/enum/range -> 422.
 
@@ -3466,7 +3657,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         )
 
     @app.post(
-        "/settings/apply", dependencies=[Depends(_require_loopback), Depends(_require_same_origin)]
+        "/settings/apply",
+        dependencies=[
+            Depends(_require_loopback_or_trusted_dashboard_client),
+            Depends(_require_same_origin_or_trusted_dashboard_client),
+        ],
     )
     async def settings_apply(request: Request):
         """Persist settings (optional body) then restart the proxy to apply them.
@@ -3529,7 +3724,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
     @app.get(
         "/dashboard/settings",
         response_class=HTMLResponse,
-        dependencies=[Depends(_require_loopback)],
+        dependencies=[Depends(_require_loopback_or_trusted_dashboard_client)],
     )
     async def dashboard_settings():
         """Serve the Headroom settings GUI."""
@@ -3611,6 +3806,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
                     "has_exact_tokens": token_accounting_status == "complete",
                     "token_accounting_status": token_accounting_status,
                     "transforms_applied": log.get("transforms_applied", []),
+                    "savings_breakdown": log.get("savings_breakdown", []),
                     "waste_signals": log.get("waste_signals"),
                     "tool_schema_saved_tokens": _tool_schema_saved_from_tags(log.get("tags")),
                 }
@@ -3835,6 +4031,12 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             "savings": {
                 "total_tokens": total_tokens_all_layers,
                 "per_project": persistent_savings.get("projects", {}),
+                # Attribution only: these rows explain the canonical headline
+                # and are not added to it again.
+                "by_source": sorted(
+                    (dict(row) for row in m.savings_by_source.values()),
+                    key=lambda row: (-int(row.get("tokens", 0)), str(row["source"])),
+                ),
                 "by_layer": {
                     "compression": {
                         "tokens": proxy_compression_tokens,
@@ -4116,6 +4318,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             "log_full_messages": proxy.config.log_full_messages if proxy else False,
             **get_quota_registry().get_all_stats(),
             "throughput": throughput,
+            # Effective state from the running process. This is the supported
+            # black-box provenance surface for benchmark/qualification tools.
+            "rollout": proxy.config.rollout.to_dict() if proxy.config.rollout else None,
         }
 
     def _dashboard_config_payload() -> dict[str, Any]:
@@ -4515,7 +4720,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         }
 
     # Telemetry endpoints (Data Flywheel)
-    @app.get("/v1/telemetry")
+    @app.get("/v1/telemetry", dependencies=[Depends(_require_loopback)])
     async def telemetry_stats():
         """Get telemetry statistics for the data flywheel.
 
@@ -4538,7 +4743,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         telemetry = get_telemetry_collector()
         return telemetry.get_stats()
 
-    @app.get("/v1/telemetry/export")
+    @app.get("/v1/telemetry/export", dependencies=[Depends(_require_loopback)])
     async def telemetry_export():
         """Export full telemetry data for aggregation.
 
@@ -4554,7 +4759,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         telemetry = get_telemetry_collector()
         return telemetry.export_stats()
 
-    @app.post("/v1/telemetry/import")
+    @app.post("/v1/telemetry/import", dependencies=[Depends(_require_loopback)])
     async def telemetry_import(request: Request):
         """Import telemetry data from another source.
 
@@ -4568,7 +4773,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         telemetry.import_stats(data)
         return {"status": "imported", "current_stats": telemetry.get_stats()}
 
-    @app.get("/v1/telemetry/tools")
+    @app.get("/v1/telemetry/tools", dependencies=[Depends(_require_loopback)])
     async def telemetry_tools():
         """Get telemetry statistics for all tracked tool signatures.
 
@@ -4584,7 +4789,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             "tools": {sig_hash: stats.to_dict() for sig_hash, stats in all_stats.items()},
         }
 
-    @app.get("/v1/telemetry/tools/{signature_hash}")
+    @app.get("/v1/telemetry/tools/{signature_hash}", dependencies=[Depends(_require_loopback)])
     async def telemetry_tool_detail(signature_hash: str):
         """Get detailed telemetry for a specific tool signature.
 
@@ -4606,7 +4811,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         }
 
     # TOIN (Tool Output Intelligence Network) endpoints
-    @app.get("/v1/toin/stats")
+    @app.get("/v1/toin/stats", dependencies=[Depends(_require_loopback)])
     async def toin_stats():
         """Get overall TOIN statistics.
 
@@ -4624,7 +4829,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         toin = get_toin()
         return toin.get_stats()
 
-    @app.get("/v1/toin/patterns")
+    @app.get("/v1/toin/patterns", dependencies=[Depends(_require_loopback)])
     async def toin_patterns(limit: int = 20):
         """List TOIN patterns with most samples.
 
@@ -4679,7 +4884,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
 
         return patterns_list[:limit]
 
-    @app.get("/v1/toin/pattern/{hash_prefix}")
+    @app.get("/v1/toin/pattern/{hash_prefix}", dependencies=[Depends(_require_loopback)])
     async def toin_pattern_detail(hash_prefix: str):
         """Get detailed TOIN pattern info by hash prefix.
 
@@ -4698,7 +4903,17 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         # Search for pattern with matching hash prefix
         for sig_hash, pattern_dict in patterns_data.items():
             if sig_hash.startswith(hash_prefix):
-                return pattern_dict
+                # Keep this response aligned with /v1/toin/patterns while
+                # excluding query text, field semantics, and other internal
+                # learning state from the detail endpoint.
+                return {
+                    "compressions": pattern_dict.get("total_compressions", 0),
+                    "retrievals": pattern_dict.get("total_retrievals", 0),
+                    "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),
+                    "confidence": pattern_dict.get("confidence", 0.0),
+                    "skip_recommended": pattern_dict.get("skip_compression_recommended", False),
+                    "optimal_max_items": pattern_dict.get("optimal_max_items", 20),
+                }
 
         raise HTTPException(
             status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"
@@ -4881,6 +5096,10 @@ def _json_ready(value: Any) -> Any:
 def _proxy_config_payload(config: ProxyConfig) -> dict[str, Any]:
     payload: dict[str, Any] = {}
     for field in fields(config):
+        if field.name == "rollout":
+            assert config.rollout is not None
+            payload["_rollout_snapshot"] = config.rollout.to_internal_dict()
+            continue
         value = _json_ready(getattr(config, field.name))
         try:
             json.dumps(value)
@@ -4894,13 +5113,25 @@ def _proxy_config_from_env() -> ProxyConfig:
     raw_config = os.environ.get(_MULTI_WORKER_CONFIG_ENV)
     if raw_config:
         try:
-            return ProxyConfig(**json.loads(raw_config))
-        except (TypeError, ValueError, json.JSONDecodeError):
+            values = json.loads(raw_config)
+            if not isinstance(values, dict):
+                raise TypeError("proxy config JSON must be an object")
+            if "_rollout_snapshot" in values:
+                rollout_value = values.pop("_rollout_snapshot")
+                from headroom.rollout import RolloutSnapshot
+
+                values["rollout"] = RolloutSnapshot.from_internal_dict(rollout_value)
+            return ProxyConfig(**values)
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError):
             logger.warning(
                 "Invalid %s; falling back to HEADROOM_* env vars", _MULTI_WORKER_CONFIG_ENV
             )
 
+    from headroom.rollout import resolve_rollout
+
+    rollout = resolve_rollout()
     return ProxyConfig(
+        rollout=rollout,
         host=_get_env_str("HEADROOM_HOST", "127.0.0.1"),
         port=_get_env_int("HEADROOM_PORT", 8787),
         openai_api_url=os.environ.get("OPENAI_TARGET_API_URL"),
@@ -4938,7 +5169,7 @@ def _proxy_config_from_env() -> ProxyConfig:
         # posture (compress_user, protect_recent, min_tokens). HEADROOM_SAVINGS_PROFILE
         # overrides.
         savings_profile=os.environ.get("HEADROOM_SAVINGS_PROFILE") or "coding",
-        read_maturation=_get_env_bool("HEADROOM_READ_MATURATION", False),
+        read_maturation=rollout.is_enabled("read_maturation"),
         read_maturation_quiesce_turns=_get_env_int("HEADROOM_READ_MATURATION_QUIESCE_TURNS", 5),
         read_maturation_max_hold_turns=_get_env_int("HEADROOM_READ_MATURATION_MAX_HOLD_TURNS", 25),
         read_maturation_min_size_bytes=_get_env_int(
@@ -5028,6 +5259,9 @@ def run_server(
     seed_proxy_env_defaults()
 
     config = config or ProxyConfig()
+    if workers < 1:
+        raise ValueError("workers must be >= 1")
+    config.worker_processes = workers
     code_aware_status = _get_code_aware_banner_status(config)
 
     # Format connection pool info
@@ -5095,6 +5329,12 @@ def run_server(
 ╚══════════════════════════════════════════════════════════════════════╝
 """)
 
+    uvicorn_error_logger = logging.getLogger("uvicorn.error")
+    if not any(
+        isinstance(item, _SuppressCancelledErrorFilter) for item in uvicorn_error_logger.filters
+    ):
+        uvicorn_error_logger.addFilter(_SuppressCancelledErrorFilter())
+
     app_target: Any
     uvicorn_kwargs: dict[str, Any] = {}
     if sys.platform == "win32":
@@ -5150,6 +5390,7 @@ def run_server(
         # default. Disabling proxy_headers here guarantees the guard sees the
         # real peer address regardless of env.
         proxy_headers=False,
+        timeout_graceful_shutdown=10,
         **uvicorn_kwargs,
     )
 
@@ -5597,7 +5838,11 @@ if __name__ == "__main__":
         args.protect_tool_results or os.environ.get("HEADROOM_PROTECT_TOOL_RESULTS")
     )
 
+    from headroom.rollout import resolve_rollout
+
+    rollout = resolve_rollout()
     config = ProxyConfig(
+        rollout=rollout,
         host=_get_env_str("HEADROOM_HOST", args.host),
         port=_get_env_int("HEADROOM_PORT", args.port),
         openai_api_url=_get_env_str("OPENAI_TARGET_API_URL", args.openai_api_url),
@@ -5651,7 +5896,7 @@ if __name__ == "__main__":
         keepalive_expiry=_get_env_float("HEADROOM_KEEPALIVE_EXPIRY", args.keepalive_expiry),
         http2=not args.no_http2 and _get_env_bool("HEADROOM_HTTP2", True),
         http_proxy=_get_env_str("HEADROOM_HTTP_PROXY", args.http_proxy or "") or None,
-        read_maturation=_get_env_bool("HEADROOM_READ_MATURATION", False),
+        read_maturation=rollout.is_enabled("read_maturation"),
         read_maturation_quiesce_turns=_get_env_int("HEADROOM_READ_MATURATION_QUIESCE_TURNS", 5),
         read_maturation_max_hold_turns=_get_env_int("HEADROOM_READ_MATURATION_MAX_HOLD_TURNS", 25),
         read_maturation_min_size_bytes=_get_env_int(
diff --git a/headroom/proxy/tool_injection_logging.py b/headroom/proxy/tool_injection_logging.py
index b6e9baa1d..b400bea7e 100644
--- a/headroom/proxy/tool_injection_logging.py
+++ b/headroom/proxy/tool_injection_logging.py
@@ -8,6 +8,9 @@ from typing import Literal
 ToolInjectionDecision = Literal[
     "inject_first_time",
     "inject_sticky_replay",
+    # Sessionless path: history already references headroom_retrieve, so the
+    # tool definition is re-injected even without fresh compression (#2440).
+    "inject_history_reference",
     "skip",
     "skip_disabled_via_env",
 ]
diff --git a/headroom/proxy/turn_hooks.py b/headroom/proxy/turn_hooks.py
index 1da65fd47..05d22c1cf 100644
--- a/headroom/proxy/turn_hooks.py
+++ b/headroom/proxy/turn_hooks.py
@@ -23,7 +23,7 @@ from __future__ import annotations
 
 import logging
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Protocol, runtime_checkable
 
 log = logging.getLogger(__name__)
@@ -47,6 +47,35 @@ class TurnContext:
     messages: list[dict[str, Any]]
     tools: Any = None  # provider-native tools value (list, or None)
     config: Any = None
+    # The handler's live request tags and provider-native counters let the hook
+    # runner attribute savings with the exact same tokenizer as the canonical
+    # RequestOutcome. Optional defaults preserve the public extension API.
+    tags: dict[str, Any] = field(default_factory=dict)
+    count_messages: Callable[[list[dict[str, Any]]], int] | None = None
+    count_tools: Callable[[Any], int] | None = None
+
+    def record_savings(
+        self,
+        source: str,
+        *,
+        tokens: int = 0,
+        usd: float = 0.0,
+        realized: bool = True,
+        estimated: bool = False,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Attribute savings without changing the request's headline totals."""
+        from headroom.proxy.savings_attribution import record_savings
+
+        record_savings(
+            self.tags,
+            source,
+            tokens=tokens,
+            usd=usd,
+            realized=realized,
+            estimated=estimated,
+            details=details,
+        )
 
 
 @runtime_checkable
@@ -111,8 +140,32 @@ def run_request_hooks(ctx: TurnContext, *, stream_safe_only: bool = False) -> No
         fn = getattr(hook, "on_request", None)
         if fn is None:
             continue
+        before_messages = before_tools = None
         try:
+            if ctx.count_messages is not None:
+                before_messages = ctx.count_messages(ctx.messages)
+            if ctx.count_tools is not None:
+                before_tools = ctx.count_tools(ctx.tools)
             fn(ctx)
+            message_saved = (
+                max(0, before_messages - ctx.count_messages(ctx.messages))
+                if before_messages is not None and ctx.count_messages is not None
+                else 0
+            )
+            tool_saved = (
+                max(0, before_tools - ctx.count_tools(ctx.tools))
+                if before_tools is not None and ctx.count_tools is not None
+                else 0
+            )
+            if message_saved or tool_saved:
+                ctx.record_savings(
+                    getattr(hook, "savings_source", getattr(hook, "name", type(hook).__name__)),
+                    tokens=message_saved + tool_saved,
+                    details={
+                        "message_tokens_saved": message_saved,
+                        "tool_tokens_saved": tool_saved,
+                    },
+                )
         except Exception:  # a hook must never break the proxy
             log.exception("turn hook %r on_request failed", getattr(hook, "name", hook))
 
diff --git a/headroom/rollout.py b/headroom/rollout.py
new file mode 100644
index 000000000..859b6e80c
--- /dev/null
+++ b/headroom/rollout.py
@@ -0,0 +1,487 @@
+"""Deterministic runtime rollout policy and provenance.
+
+Rollout channels control behavior exposed by an already-installed artifact.
+They do not select a Headroom release, package, or distribution version.
+Environment access is confined to :func:`resolve_rollout`; downstream code
+receives the resulting immutable :class:`RolloutSnapshot`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+ROLLOUT_SCHEMA_VERSION = 1
+ROLLOUT_POLICY_VERSION = "1"
+
+_TRUE_VALUES = {"1", "true", "yes", "on", "enabled"}
+_FALSE_VALUES = {"0", "false", "no", "off", "disabled"}
+
+
+class RolloutConfigurationError(ValueError):
+    """A supplied rollout configuration is invalid."""
+
+
+class RolloutChannel(str, Enum):
+    """Ordered runtime-behavior channels; unrelated to artifact releases."""
+
+    STABLE = "stable"
+    BETA = "beta"
+    CANARY = "canary"
+    DEV = "dev"
+
+    @classmethod
+    def parse(cls, value: str | None, *, strict: bool = False) -> RolloutChannel:
+        if not value:
+            return cls.STABLE
+        normalized = value.strip().lower().replace("-", "_")
+        aliases = {
+            "prod": cls.STABLE,
+            "production": cls.STABLE,
+            "preview": cls.BETA,
+            "nightly": cls.CANARY,
+            "development": cls.DEV,
+        }
+        if normalized in aliases:
+            return aliases[normalized]
+        try:
+            return cls(normalized)
+        except ValueError:
+            message = f"unknown rollout channel {value!r}"
+            if strict:
+                raise RolloutConfigurationError(message) from None
+            logger.warning("%s; falling back to 'stable'", message)
+            return cls.STABLE
+
+    @property
+    def order(self) -> int:
+        return {
+            RolloutChannel.STABLE: 0,
+            RolloutChannel.BETA: 1,
+            RolloutChannel.CANARY: 2,
+            RolloutChannel.DEV: 3,
+        }[self]
+
+    def allows(self, required: RolloutChannel) -> bool:
+        return self.order >= required.order
+
+
+class FeatureDecisionReason(str, Enum):
+    DEFAULT = "default"
+    EXPLICIT = "explicit"
+    LEGACY_ALIAS = "legacy_alias"
+    DISABLED = "disabled"
+    BLOCKED_BY_CHANNEL = "blocked_by_channel"
+    UNSAFE_OVERRIDE = "unsafe_override"
+    NOT_REQUESTED = "not_requested"
+
+
+@dataclass(frozen=True)
+class FeatureSpec:
+    name: str
+    available_in: RolloutChannel
+    default_enabled_in: RolloutChannel | None = None
+    legacy_env: tuple[str, ...] = ()
+    description: str = ""
+
+    def default_enabled(self, channel: RolloutChannel) -> bool:
+        return self.default_enabled_in is not None and channel.allows(self.default_enabled_in)
+
+
+FEATURES: dict[str, FeatureSpec] = {
+    "tool_result_interceptors": FeatureSpec(
+        name="tool_result_interceptors",
+        available_in=RolloutChannel.CANARY,
+        legacy_env=("HEADROOM_INTERCEPT_ENABLED",),
+        description="AST-aware Read/tool-result interceptors used before compression.",
+    ),
+    "proxy_output_shaper": FeatureSpec(
+        name="proxy_output_shaper",
+        available_in=RolloutChannel.BETA,
+        legacy_env=("HEADROOM_OUTPUT_SHAPER",),
+        description="Proxy output-shaping path for response-side experiments.",
+    ),
+    "read_maturation": FeatureSpec(
+        name="read_maturation",
+        available_in=RolloutChannel.BETA,
+        legacy_env=("HEADROOM_READ_MATURATION",),
+        description="Hold-back Read maturation before provider cache entry.",
+    ),
+}
+
+
+def _split_names(raw: str | None) -> set[str]:
+    if not raw:
+        return set()
+    return {
+        part.strip().lower().replace("-", "_")
+        for part in raw.replace(";", ",").split(",")
+        if part.strip()
+    }
+
+
+def _truthy(value: str | None) -> bool:
+    return bool(value and value.strip().lower() in _TRUE_VALUES)
+
+
+def _falsey(value: str | None) -> bool:
+    return bool(value and value.strip().lower() in _FALSE_VALUES)
+
+
+def _canonical_json(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def _sha256(value: object) -> str:
+    return "sha256:" + hashlib.sha256(_canonical_json(value).encode()).hexdigest()
+
+
+def registry_digest(registry: Mapping[str, FeatureSpec] = FEATURES) -> str:
+    """Return a stable identity for all behavior-affecting registry fields."""
+
+    canonical = [
+        {
+            "name": spec.name,
+            "available_in": spec.available_in.value,
+            "default_enabled_in": (
+                spec.default_enabled_in.value if spec.default_enabled_in is not None else None
+            ),
+            "legacy_env": sorted(spec.legacy_env),
+        }
+        for _, spec in sorted(registry.items())
+    ]
+    return _sha256(canonical)
+
+
+@dataclass(frozen=True)
+class RolloutConfig:
+    channel: RolloutChannel
+    requested: frozenset[str]
+    disabled: frozenset[str]
+    unsafe_allow_unstable: bool
+    # Retain source provenance so a supported live compatibility alias can be
+    # re-resolved without erasing a generic kill switch or converting an
+    # explicit request into an alias request. These stay out of the JSON schema.
+    explicit_requested: frozenset[str] = frozenset()
+    explicit_disabled: frozenset[str] = frozenset()
+    legacy_requested: frozenset[str] = frozenset()
+    legacy_disabled: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True)
+class FeatureDecision:
+    name: str
+    available_in: RolloutChannel
+    default_enabled_in: RolloutChannel | None
+    requested: bool
+    disabled: bool
+    enabled: bool
+    reason: FeatureDecisionReason
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "available_in": self.available_in.value,
+            "default_enabled_in": (
+                self.default_enabled_in.value if self.default_enabled_in is not None else None
+            ),
+            "requested": self.requested,
+            "disabled": self.disabled,
+            "enabled": self.enabled,
+            "decision": self.reason.value,
+        }
+
+
+@dataclass(frozen=True)
+class RolloutSnapshot:
+    schema_version: int
+    policy_version: str
+    registry_digest: str
+    config: RolloutConfig
+    decisions: tuple[FeatureDecision, ...]
+
+    @property
+    def channel(self) -> RolloutChannel:
+        return self.config.channel
+
+    @property
+    def unsafe_allow_unstable(self) -> bool:
+        return self.config.unsafe_allow_unstable
+
+    @property
+    def qualification_eligible(self) -> bool:
+        return not self.unsafe_allow_unstable
+
+    @property
+    def snapshot_digest(self) -> str:
+        return _sha256(self._canonical_dict())
+
+    def decision(self, feature: str) -> FeatureDecision:
+        normalized = feature.strip().lower().replace("-", "_")
+        for decision in self.decisions:
+            if decision.name == normalized:
+                return decision
+        raise KeyError(feature)
+
+    def is_available(self, feature: str) -> bool:
+        decision = self.decision(feature)
+        return self.channel.allows(decision.available_in) or self.unsafe_allow_unstable
+
+    def is_enabled(self, feature: str, **_: object) -> bool:
+        """Return the pre-resolved decision; extra legacy kwargs are ignored."""
+
+        return self.decision(feature).enabled
+
+    @property
+    def enabled(self) -> frozenset[str]:
+        return frozenset(item.name for item in self.decisions if item.enabled)
+
+    @property
+    def disabled(self) -> frozenset[str]:
+        return self.config.disabled
+
+    def _canonical_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": self.schema_version,
+            "policy_version": self.policy_version,
+            "channel": self.channel.value,
+            "unsafe_override": self.unsafe_allow_unstable,
+            "registry_digest": self.registry_digest,
+            "features": [item.to_dict() for item in self.decisions],
+        }
+
+    def to_dict(self) -> dict[str, object]:
+        result = self._canonical_dict()
+        result["snapshot_digest"] = self.snapshot_digest
+        result["qualification_eligible"] = self.qualification_eligible
+        if not self.qualification_eligible:
+            result["qualification_ineligible_reason"] = "unsafe_rollout_override_active"
+        return result
+
+    def to_internal_dict(self) -> dict[str, object]:
+        """Serialize source-separated state for trusted worker handoff."""
+
+        return {
+            "schema_version": self.schema_version,
+            "policy_version": self.policy_version,
+            "registry_digest": self.registry_digest,
+            "snapshot_digest": self.snapshot_digest,
+            "channel": self.channel.value,
+            "unsafe_allow_unstable": self.unsafe_allow_unstable,
+            "explicit_requested": sorted(self.config.explicit_requested),
+            "explicit_disabled": sorted(self.config.explicit_disabled),
+            "legacy_requested": sorted(self.config.legacy_requested),
+            "legacy_disabled": sorted(self.config.legacy_disabled),
+        }
+
+    @classmethod
+    def from_internal_dict(cls, value: Mapping[str, object]) -> RolloutSnapshot:
+        """Validate and restore a snapshot serialized for worker handoff."""
+
+        if not isinstance(value, Mapping):
+            raise RolloutConfigurationError("invalid rollout worker snapshot")
+        try:
+            if value.get("schema_version") != ROLLOUT_SCHEMA_VERSION:
+                raise RolloutConfigurationError("unsupported rollout worker schema version")
+            if value.get("policy_version") != ROLLOUT_POLICY_VERSION:
+                raise RolloutConfigurationError("rollout worker policy version mismatch")
+            channel = RolloutChannel.parse(str(value["channel"]), strict=True)
+            unsafe = value["unsafe_allow_unstable"]
+            if not isinstance(unsafe, bool):
+                raise RolloutConfigurationError("invalid rollout worker unsafe override")
+
+            def names(field: str) -> set[str]:
+                raw = value[field]
+                if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):
+                    raise RolloutConfigurationError(f"invalid rollout worker field {field!r}")
+                return set(_validate_names(set(raw), source=field, strict=True))
+
+            snapshot = _resolve_snapshot(
+                channel=channel,
+                explicit_requested=names("explicit_requested"),
+                explicit_disabled=names("explicit_disabled"),
+                legacy_requested=names("legacy_requested"),
+                legacy_disabled=names("legacy_disabled"),
+                unsafe=unsafe,
+            )
+        except (KeyError, TypeError) as exc:
+            raise RolloutConfigurationError("invalid rollout worker snapshot") from exc
+        if value.get("registry_digest") != snapshot.registry_digest:
+            raise RolloutConfigurationError("rollout worker registry digest mismatch")
+        if value.get("snapshot_digest") != snapshot.snapshot_digest:
+            raise RolloutConfigurationError("rollout worker snapshot digest mismatch")
+        return snapshot
+
+    def with_legacy_env(self, environ: Mapping[str, str]) -> RolloutSnapshot:
+        """Return a new snapshot after applying supplied legacy alias values.
+
+        This intentionally supports existing hot-reloadable aliases without
+        re-reading ambient process state or weakening named disable precedence.
+        Both the old and new snapshots remain immutable, so requests observe a
+        complete policy rather than partially updated fields.
+        """
+
+        legacy_requested = set(self.config.legacy_requested)
+        legacy_disabled = set(self.config.legacy_disabled)
+        for spec in FEATURES.values():
+            for alias in spec.legacy_env:
+                if alias not in environ:
+                    continue
+                legacy_requested.discard(spec.name)
+                legacy_disabled.discard(spec.name)
+                if _truthy(environ[alias]):
+                    legacy_requested.add(spec.name)
+                elif _falsey(environ[alias]):
+                    legacy_disabled.add(spec.name)
+        return _resolve_snapshot(
+            channel=self.channel,
+            explicit_requested=set(self.config.explicit_requested),
+            explicit_disabled=set(self.config.explicit_disabled),
+            legacy_requested=legacy_requested,
+            legacy_disabled=legacy_disabled,
+            unsafe=self.unsafe_allow_unstable,
+        )
+
+
+def _validate_names(names: set[str], *, source: str, strict: bool) -> frozenset[str]:
+    unknown = sorted(names - FEATURES.keys())
+    if unknown:
+        valid = ", ".join(sorted(FEATURES))
+        message = f"unknown rollout feature(s) in {source}: {', '.join(unknown)}; valid: {valid}"
+        if strict:
+            raise RolloutConfigurationError(message)
+        logger.warning("%s; ignoring unknown names (fail-closed)", message)
+    return frozenset(names & FEATURES.keys())
+
+
+def resolve_rollout(
+    environ: Mapping[str, str] | None = None,
+    *,
+    requested: Iterable[str] = (),
+    disabled: Iterable[str] = (),
+    strict: bool = False,
+) -> RolloutSnapshot:
+    """Resolve all rollout inputs exactly once into an immutable snapshot."""
+
+    env = os.environ if environ is None else environ
+    channel = RolloutChannel.parse(env.get("HEADROOM_ROLLOUT_CHANNEL"), strict=strict)
+    requested_names = _split_names(env.get("HEADROOM_FEATURES")) | {
+        normalized for name in requested if (normalized := name.strip().lower().replace("-", "_"))
+    }
+    disabled_names = _split_names(env.get("HEADROOM_DISABLE_FEATURES")) | {
+        normalized for name in disabled if (normalized := name.strip().lower().replace("-", "_"))
+    }
+    requested_names = set(
+        _validate_names(requested_names, source="requested features", strict=strict)
+    )
+    disabled_names = set(_validate_names(disabled_names, source="disabled features", strict=strict))
+    legacy_requested: set[str] = set()
+    legacy_disabled: set[str] = set()
+    for spec in FEATURES.values():
+        for alias in spec.legacy_env:
+            if _truthy(env.get(alias)):
+                legacy_requested.add(spec.name)
+            elif _falsey(env.get(alias)):
+                legacy_disabled.add(spec.name)
+
+    unsafe = _truthy(env.get("HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES"))
+    return _resolve_snapshot(
+        channel=channel,
+        explicit_requested=requested_names,
+        explicit_disabled=disabled_names,
+        legacy_requested=legacy_requested,
+        legacy_disabled=legacy_disabled,
+        unsafe=unsafe,
+    )
+
+
+def _resolve_snapshot(
+    *,
+    channel: RolloutChannel,
+    explicit_requested: set[str],
+    explicit_disabled: set[str],
+    legacy_requested: set[str],
+    legacy_disabled: set[str],
+    unsafe: bool,
+) -> RolloutSnapshot:
+    """Resolve validated, source-separated inputs into one snapshot."""
+
+    requested_names = explicit_requested | legacy_requested
+    disabled_names = explicit_disabled | legacy_disabled
+    config = RolloutConfig(
+        channel=channel,
+        requested=frozenset(requested_names),
+        disabled=frozenset(disabled_names),
+        unsafe_allow_unstable=unsafe,
+        explicit_requested=frozenset(explicit_requested),
+        explicit_disabled=frozenset(explicit_disabled),
+        legacy_requested=frozenset(legacy_requested),
+        legacy_disabled=frozenset(legacy_disabled),
+    )
+    decisions: list[FeatureDecision] = []
+    for name, spec in sorted(FEATURES.items()):
+        is_requested = name in config.requested
+        is_disabled = name in config.disabled
+        normally_available = channel.allows(spec.available_in)
+        if is_disabled:
+            enabled, reason = False, FeatureDecisionReason.DISABLED
+        elif is_requested and not normally_available and not unsafe:
+            enabled, reason = False, FeatureDecisionReason.BLOCKED_BY_CHANNEL
+        elif is_requested and not normally_available and unsafe:
+            enabled, reason = True, FeatureDecisionReason.UNSAFE_OVERRIDE
+        elif name in legacy_requested:
+            enabled, reason = True, FeatureDecisionReason.LEGACY_ALIAS
+        elif name in explicit_requested:
+            enabled, reason = True, FeatureDecisionReason.EXPLICIT
+        elif spec.default_enabled(channel):
+            enabled, reason = True, FeatureDecisionReason.DEFAULT
+        else:
+            enabled, reason = False, FeatureDecisionReason.NOT_REQUESTED
+        decisions.append(
+            FeatureDecision(
+                name=name,
+                available_in=spec.available_in,
+                default_enabled_in=spec.default_enabled_in,
+                requested=is_requested,
+                disabled=is_disabled,
+                enabled=enabled,
+                reason=reason,
+            )
+        )
+    return RolloutSnapshot(
+        schema_version=ROLLOUT_SCHEMA_VERSION,
+        policy_version=ROLLOUT_POLICY_VERSION,
+        registry_digest=registry_digest(),
+        config=config,
+        decisions=tuple(decisions),
+    )
+
+
+def current_rollout(environ: Mapping[str, str] | None = None) -> RolloutSnapshot:
+    """Compatibility name for resolving a snapshot at a composition boundary."""
+
+    return resolve_rollout(environ)
+
+
+def feature_enabled(
+    feature: str,
+    *,
+    explicit: bool = False,
+    environ: Mapping[str, str] | None = None,
+) -> bool:
+    """Compatibility helper for composition roots; do not use in deep components."""
+
+    requested = (feature,) if explicit else ()
+    return resolve_rollout(environ, requested=requested).is_enabled(feature)
+
+
+# The PR was never released, but this narrow source alias keeps in-branch callers
+# importable while the correction migrates them. It is intentionally undocumented.
+Rollout = RolloutSnapshot
diff --git a/headroom/settings_store.py b/headroom/settings_store.py
index c085c181f..ad134ebc0 100644
--- a/headroom/settings_store.py
+++ b/headroom/settings_store.py
@@ -136,6 +136,21 @@ SETTINGS: tuple[SettingField, ...] = (
         help="Disable CCR entirely (no markers, no injected retrieve tool).",
         tier="basic",
     ),
+    SettingField(
+        "HEADROOM_CCR_INLINE_RESOLVE",
+        "ccr_inline_resolve",
+        "Resolve CCR markers inline",
+        "Compression",
+        "bool",
+        default=False,
+        help=(
+            "Resolve <<ccr:...>> markers on the response path instead of "
+            "relying on headroom_retrieve tool calls. For callers with no "
+            "tool-call round-trip (e.g. a LiteLLM guardrail/proxy hop). "
+            "Non-streaming responses only."
+        ),
+        tier="advanced",
+    ),
     # --- Limits ---
     SettingField(
         "HEADROOM_RPM",
@@ -697,6 +712,7 @@ SETTINGS: tuple[SettingField, ...] = (
 )
 
 _BY_KEY: dict[str, SettingField] = {f.key: f for f in SETTINGS}
+_BY_ENV: dict[str, SettingField] = {f.env: f for f in SETTINGS}
 
 
 class SettingsValidationError(Exception):
@@ -714,6 +730,27 @@ class SettingsValidationError(Exception):
         )
 
 
+def _normalize_values(values: dict[str, Any]) -> dict[str, Any]:
+    """Rewrite known env aliases to their JSON/API keys."""
+    normalized: dict[str, Any] = {}
+    source_keys: dict[str, str] = {}
+    conflicts: dict[str, str] = {}
+    for incoming_key, value in values.items():
+        field = _BY_ENV.get(incoming_key)
+        key = field.key if field is not None else incoming_key
+        if key in normalized:
+            if normalized[key] != value:
+                conflicts[key] = (
+                    f"conflicting values supplied for {source_keys[key]!r} and {incoming_key!r}"
+                )
+            continue
+        normalized[key] = value
+        source_keys[key] = incoming_key
+    if conflicts:
+        raise SettingsValidationError([], conflicts)
+    return normalized
+
+
 def _coerce(field: SettingField, value: Any) -> Any:
     """Coerce a raw JSON/env value to the field's Python type.
 
@@ -792,6 +829,7 @@ def validate(values: dict[str, Any]) -> dict[str, Any]:
     Raises :class:`SettingsValidationError` when any key is unknown or any value
     fails coercion. Returns the coerced dict (``None`` values dropped) on success.
     """
+    values = _normalize_values(values)
     unknown = [key for key in values if key not in _BY_KEY]
     field_errors: dict[str, str] = {}
     coerced: dict[str, Any] = {}
@@ -879,6 +917,7 @@ def save(values: dict[str, Any]) -> None:
     secret's display value verbatim when the user hasn't touched it; anything
     else is validated/coerced and stored.
     """
+    values = _normalize_values(values)
     clear_keys = {key for key, value in values.items() if value is None and key in _BY_KEY}
     retained_keys = {
         key
diff --git a/headroom/subscription/session_tracking.py b/headroom/subscription/session_tracking.py
index 9ace709fa..9bcb557bb 100644
--- a/headroom/subscription/session_tracking.py
+++ b/headroom/subscription/session_tracking.py
@@ -134,8 +134,26 @@ def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens:
     totals = WindowTokens()
     by_model: dict[str, WindowTokens] = {}
     unattributed = WindowTokens()
+    # Claude Code can store one assistant response across multiple transcript
+    # lines (e.g. one entry per content block), each carrying the SAME
+    # request-level ``message.usage``. Summing per line therefore multiplies a
+    # single response's tokens by its block count (observed 19x for one 420K
+    # response, #2340). Count each response's usage once, keyed by the unique
+    # Anthropic ``message.id``. Entries without an id keep the per-line
+    # behavior, so this only ever removes true duplicates.
+    seen_message_ids: set[str] = set()
 
     for path in find_transcript_files():
+        # Skip transcripts that cannot contain entries inside the window.
+        # Transcripts are append-only and chronological, so a file whose mtime is
+        # older than the window start has no entry within [start_ts, end_ts).
+        # Without this guard every poll json.loads()es every line of every
+        # transcript under ~/.claude/projects.
+        try:
+            if path.stat().st_mtime < start_ts:
+                continue
+        except OSError:
+            continue
         for line in _read_transcript_lines(path):
             try:
                 entry: dict[str, Any] = json.loads(line)
@@ -161,6 +179,12 @@ def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens:
             if not usage:
                 continue
 
+            msg_id = msg.get("id")
+            if isinstance(msg_id, str) and msg_id:
+                if msg_id in seen_message_ids:
+                    continue
+                seen_message_ids.add(msg_id)
+
             _add_usage_to_tokens(totals, usage)
 
             model_id: str | None = msg.get("model")
diff --git a/headroom/telemetry/backends/filesystem.py b/headroom/telemetry/backends/filesystem.py
index cd192bf1d..8c5d52691 100644
--- a/headroom/telemetry/backends/filesystem.py
+++ b/headroom/telemetry/backends/filesystem.py
@@ -28,8 +28,9 @@ class FileSystemTOINBackend:
         path: Path to the JSON storage file.
     """
 
-    def __init__(self, path: str) -> None:
+    def __init__(self, path: str, *, max_load_bytes: int | None = None) -> None:
         self._path = Path(path)
+        self._max_load_bytes = max_load_bytes
 
     def load(self) -> dict[str, Any]:
         """Load TOIN data from the JSON file.
@@ -41,6 +42,17 @@ class FileSystemTOINBackend:
             return {}
 
         try:
+            if (
+                self._max_load_bytes is not None
+                and self._path.stat().st_size > self._max_load_bytes
+            ):
+                logger.warning(
+                    "TOIN data file %s exceeds the configured load limit (%d bytes); "
+                    "ignoring it until the store is rebuilt",
+                    self._path,
+                    self._max_load_bytes,
+                )
+                return {}
             with open(self._path) as f:
                 data: dict[str, Any] = json.load(f)
                 return data
@@ -60,12 +72,13 @@ class FileSystemTOINBackend:
         try:
             self._path.parent.mkdir(parents=True, exist_ok=True)
 
-            json_data = json.dumps(data, indent=2)
-
             fd, tmp_path = tempfile.mkstemp(dir=self._path.parent, prefix=".toin_", suffix=".tmp")
             try:
+                # Stream compact JSON directly to the temp file. Building a
+                # second multi-gigabyte string was the primary autosave RSS
+                # spike reported in #2886.
                 with open(fd, "w") as f:
-                    f.write(json_data)
+                    json.dump(data, f, separators=(",", ":"))
                 Path(tmp_path).replace(self._path)
             except Exception:
                 try:
diff --git a/headroom/telemetry/context.py b/headroom/telemetry/context.py
index e845b1ed7..93d5d3956 100644
--- a/headroom/telemetry/context.py
+++ b/headroom/telemetry/context.py
@@ -46,6 +46,14 @@ _STACK_SLUG_RE = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
 # header values.
 MAX_DISTINCT_STACKS = 32
 
+# Cardinality cap on the per-process requests_by_model / _cache_requests_by_model
+# dicts. Protects the Prometheus scrape, the in-memory counters, and telemetry
+# from unbounded label explosion when clients send arbitrary `model` values.
+# 32x MAX_DISTINCT_STACKS: models are a larger legitimate vocabulary (provider
+# and snapshot variants across a multi-tenant deployment) than stacks, while the
+# cap stays a hard ceiling. Over-cap models bucket into the "other" sentinel.
+MAX_DISTINCT_MODELS = 1024
+
 
 def normalize_stack(raw: str | None) -> str | None:
     """Validate and normalize a stack slug.
diff --git a/headroom/telemetry/session.py b/headroom/telemetry/session.py
index 26e45a303..9aa287cb2 100644
--- a/headroom/telemetry/session.py
+++ b/headroom/telemetry/session.py
@@ -94,6 +94,39 @@ _SLUG_RE = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
 # vocabulary. Values are slug-validated before they are counted.
 _REASON_TAGS = ("passthrough_reason", "image_skip_reason", "memory_skip_reason")
 
+# Cardinality cap on `by_strategy`. The real vocabulary is CompressionStrategy
+# plus a couple of literals — under a dozen — but `record_compression` takes a
+# free string, so an extension or a future caller could invent keys per request.
+# Matches the same guard on `requests_by_stack` (MAX_DISTINCT_STACKS).
+MAX_STRATEGIES = 32
+
+# Compression events arrive on the compression executor thread, mid-request,
+# before that request's outcome ever reaches `SessionAggregator.record`. They
+# are staged here rather than written straight into the live session, which
+# keeps three things true at once:
+#
+#   * The executor thread never takes the aggregator's lock, so compression
+#     cannot serialise against the request path. The beacon is on by default,
+#     and ContentRouter observes once per routing decision — once per content
+#     section per request — so that contention would be real.
+#   * A compression event cannot CREATE a session. Sessions are started only by
+#     an outcome, which preserves the invariant that every emitted session has
+#     turns >= 1; otherwise a request abandoned between compression and its
+#     outcome (Claude Code users interrupt streaming routinely) would emit a
+#     phantom all-zero row that inflates fleet session and install counts.
+#   * The first turn's numbers still survive, because the outcome that follows
+#     milliseconds later drains this into the session it opens.
+#
+# A request that dies before its outcome leaves its events staged, and they are
+# attributed to the next session instead. That is a rounding error against
+# inventing a session that never happened.
+_staged_lock = threading.Lock()
+_staged_strategies: dict[str, list[int]] = {}
+# Per-request stack slugs, for `detect_stack`'s by_stack branch. Same staging
+# and the same reason: the proxy sees the X-Headroom-Stack header per request,
+# and this is the only place the beacon can learn it without importing proxy.
+_staged_stacks: dict[str, int] = {}
+
 
 def _pct(numerator: float, denominator: float) -> float:
     """Percentage to 2dp, or 0.0 when undefined.
@@ -218,6 +251,28 @@ def resource_attributes(
     }
     if install_mode:
         attrs["headroom.install_mode"] = install_mode
+    # Detect when the caller did not supply one. Every caller so far supplies
+    # nothing, so `headroom.stack` was absent from the entire corpus while the
+    # detector sat unused — which made the fleet unsegmentable by agent, the
+    # question the corpus is most often asked ("what does this look like under
+    # Claude Code?").
+    #
+    # The env vars detect_stack checks first are only set by `headroom wrap`.
+    # The common deployment points an agent at a persistent proxy through
+    # ANTHROPIC_BASE_URL and sets neither, so environment-only detection would
+    # answer the literal "proxy" for almost the whole fleet — a populated,
+    # authoritative-looking column that cannot answer the question it exists
+    # for. The slugs staged by `record_stack` are that fleet's only real
+    # signal, so they are fed to detect_stack's by_stack branch.
+    if stack is None:
+        try:
+            from headroom.telemetry.context import detect_stack
+
+            with _staged_lock:
+                by_stack = dict(_staged_stacks)
+            stack = detect_stack({"requests": {"by_stack": by_stack}} if by_stack else None)
+        except Exception:  # a broken detector must not silence telemetry
+            logger.debug("telemetry: stack detection failed", exc_info=True)
     if stack:
         attrs["headroom.stack"] = stack
     return attrs
@@ -246,11 +301,16 @@ class _Session:
     cache_write_tokens: int = 0
     uncached_tokens: int = 0
     failures: int = 0
+    failure_statuses: dict[str, int] = field(default_factory=dict)
     passthrough_turns: int = 0
     response_cache_hits: int = 0
     overhead_ms: float = 0.0
     latency_ms: float = 0.0
     transforms: dict[str, int] = field(default_factory=dict)
+    # strategy slug -> [events, tokens_in, tokens_out]. `transforms` says which
+    # compressors ran; this says whether they were worth running. A list rather
+    # than three parallel dicts so the three numbers cannot drift apart.
+    strategies: dict[str, list[int]] = field(default_factory=dict)
     skips: dict[str, int] = field(default_factory=dict)
     sources: dict[str, int] = field(default_factory=dict)
     providers: set[str] = field(default_factory=set)
@@ -362,6 +422,37 @@ class _Session:
             },
             "compression": {
                 "transforms": dict(self.transforms),
+                # Per-strategy effectiveness. `transforms` counts invocations,
+                # which cannot tell a compressor that saved 60% from one that
+                # ran constantly and saved nothing — the fleet's top transform
+                # by count contributes an unknown share of `tokens.saved`.
+                #
+                # These do NOT sum to `tokens.saved`, and must not be presented
+                # as if they do: strategies compose (the router routes, a
+                # strategy runs inside it) so the same text is measured by more
+                # than one, and tool-schema savings never appear here at all.
+                # Read a row as "of what this strategy was handed, it removed
+                # this much" — a per-strategy yield, not a share of the total.
+                #
+                # A LIST of uniform records, not a {strategy: {...}} object,
+                # and that shape is deliberate. DuckDB infers a JSON object as
+                # a STRUCT while its keys are few and consistent and as a MAP
+                # once they are not, so an object keyed by strategy would
+                # change COLUMN TYPE as the fleet adopts new compressors —
+                # exactly the break that silently took out the `transforms`
+                # report. A list of records has fixed field names, so the type
+                # is the same on day one and after the 30th strategy ships, and
+                # a new field inside a record is absorbed by union_by_name.
+                # Sorted so a payload is byte-comparable between heartbeats.
+                "by_strategy": [
+                    {
+                        "strategy": name,
+                        "n": counts[0],
+                        "tokens_in": counts[1],
+                        "tokens_out": counts[2],
+                    }
+                    for name, counts in sorted(self.strategies.items())
+                ],
                 "overhead_ms_total": round(self.overhead_ms, 1),
                 # Sum of per-request durations, NOT elapsed time: concurrent turns
                 # make this exceed `session.duration_s`. Kept under the original
@@ -392,6 +483,12 @@ class _Session:
             "providers": sorted(self.providers),
             "models": sorted(self.models),
             "failures": self.failures,
+            # The same failures split by status, because the count alone cannot
+            # answer the only question worth asking about it: a 529 is the
+            # provider shedding load (nothing to fix here) and a 500 is usually
+            # ours. Keys are the bare status string; the set is closed and tiny
+            # (500/502/503/504/529), so this needs no slug bounding.
+            "failure_statuses": dict(self.failure_statuses),
         }
         self.seq += 1
         return snapshot
@@ -498,6 +595,20 @@ def _fold(sess: _Session, outcome: Any, now: float, source: str = "proxy") -> No
     sess.last_seen = now
     sess.turns += 1
     sess.sources[source] = sess.sources.get(source, 0) + 1
+
+    # Compression ran on the executor thread before this outcome arrived; take
+    # what it staged. Done here rather than in the observer so the executor
+    # thread never touches the aggregator lock — see the note on _staged_lock.
+    for name, staged in _drain_staged_strategies().items():
+        counts = sess.strategies.get(name)
+        if counts is None:
+            if len(sess.strategies) >= MAX_STRATEGIES:
+                continue
+            counts = [0, 0, 0]
+            sess.strategies[name] = counts
+        counts[0] += staged[0]
+        counts[1] += staged[1]
+        counts[2] += staged[2]
     sess.original_tokens += int(get("original_tokens") or 0)
     sess.attempted_tokens += int(get("attempted_input_tokens") or 0)
     # Billed/volume figure, so prefer the provider's own count and fall back to
@@ -513,8 +624,14 @@ def _fold(sess: _Session, outcome: Any, now: float, source: str = "proxy") -> No
     sess.uncached_tokens += int(get("uncached_input_tokens") or 0)
     sess.overhead_ms += float(get("overhead_ms", 0.0) or 0.0)
     sess.latency_ms += float(get("total_latency_ms", 0.0) or 0.0)
-    if int(get("status_code", 200) or 200) >= 500:
+    status = int(get("status_code", 200) or 200)
+    if status >= 500:
         sess.failures += 1
+        # ponytail: str(status) verbatim for the 5xx range, one bucket for
+        # anything outside it. Nothing here can be user data, and the range
+        # check is what keeps a garbage status_code from inventing map keys.
+        key = str(status) if status < 600 else "other"
+        sess.failure_statuses[key] = sess.failure_statuses.get(key, 0) + 1
     if get("from_response_cache", False):
         sess.response_cache_hits += 1
 
@@ -763,6 +880,116 @@ def record_mcp_compression(
     )
 
 
+def record_compression(strategy: str, original_tokens: int, compressed_tokens: int) -> None:
+    """Beacon entry point for one compression event.
+
+    Signature-compatible with
+    :class:`headroom.transforms.observability.CompressionObserver`, so the
+    proxy's existing observer can forward here without a second measurement
+    pass — the numbers are already computed on the hot path for Prometheus
+    (``PrometheusMetrics.tokens_saved_by_strategy``); they just never left the
+    process.
+
+    Same discipline as the rest of this module: off by default and cheap when
+    off, never raises. This runs once per routing decision, so it must not do
+    anything a request would notice.
+    """
+    from headroom.telemetry.beacon import is_beacon_enabled
+
+    if not is_beacon_enabled():
+        return
+    # A slug, not the raw string. The real values are CompressionStrategy enum
+    # tags, but the observer protocol takes a free string, and anything that is
+    # not already a bounded lowercase identifier collapses to "other" rather
+    # than reaching the wire.
+    slug = _safe_slug(strategy)
+    try:
+        before = int(original_tokens or 0)
+        after = int(compressed_tokens or 0)
+    except (TypeError, ValueError):
+        return
+    if before <= 0:
+        return
+    # Clamped at the input: a compressor that emits more than it received is a
+    # bug, and letting `out` exceed `in` would surface downstream as negative
+    # savings rather than as the bug it is. Prometheus clamps the same way.
+    after = min(max(after, 0), before)
+    with _staged_lock:
+        counts = _staged_strategies.get(slug)
+        if counts is None:
+            if len(_staged_strategies) >= MAX_STRATEGIES:
+                return
+            counts = [0, 0, 0]
+            _staged_strategies[slug] = counts
+        counts[0] += 1
+        counts[1] += before
+        counts[2] += after
+
+
+def record_stack(slug: str) -> None:
+    """Beacon entry point for one request's stack slug.
+
+    The harness identity lives in the ``X-Headroom-Stack`` header, which only
+    the proxy sees, and per request rather than per process. Counting slugs
+    here lets :func:`resource_attributes` answer ``detect_stack``'s by_stack
+    branch without the telemetry package importing ``headroom.proxy``.
+
+    Without this the beacon can only read the two environment variables, so
+    every install that points an agent at a persistent proxy — the common
+    deployment for Claude Code, Cursor, Codex and the adapters — reports the
+    literal ``"proxy"`` and the fleet is unsegmentable by agent.
+    """
+    from headroom.telemetry.beacon import is_beacon_enabled
+
+    if not is_beacon_enabled():
+        return
+    # normalize_stack is the same chokepoint the proxy applies at ingress; an
+    # unbounded header value must not reach the wire or grow this dict.
+    from headroom.telemetry.context import normalize_stack
+
+    clean = normalize_stack(slug)
+    if not clean:
+        return
+    with _staged_lock:
+        if clean not in _staged_stacks and len(_staged_stacks) >= MAX_STRATEGIES:
+            return
+        _staged_stacks[clean] = _staged_stacks.get(clean, 0) + 1
+
+
+class BeaconCompressionObserver:
+    """A `CompressionObserver` that forwards to the beacon and nothing else.
+
+    The proxy's `PrometheusMetrics` is already an observer and forwards from
+    there, so this is for the paths that never had one: the MCP servers, the
+    bare transform pipeline, and the LangChain/Strands integrations. Those
+    processes report `tokens.saved` either way, so without this they emit
+    sessions with real token totals and an empty `by_strategy` — a silently
+    biased subset that cannot be reconciled with the fleet totals.
+
+    Only `record_compression` is implemented. ContentRouter's two other
+    observer hooks (`record_kompress_size_gate`, `record_router_route_counts`)
+    are each individually guarded at the call site, and both feed `/stats`
+    rather than the beacon.
+    """
+
+    __slots__ = ()
+
+    def record_compression(
+        self, strategy: str, original_tokens: int, compressed_tokens: int
+    ) -> None:
+        record_compression(strategy, original_tokens, compressed_tokens)
+
+
+def _drain_staged_strategies() -> dict[str, list[int]]:
+    """Take everything staged since the last drain. Caller merges it."""
+    with _staged_lock:
+        if not _staged_strategies:
+            return {}
+        drained = {name: counts[:] for name, counts in _staged_strategies.items()}
+        _staged_strategies.clear()
+        return drained
+
+
 def record_outcome(outcome: Any) -> None:
     """Beacon entry point, called from the proxy's outcome funnel.
 
@@ -855,11 +1082,103 @@ def demo() -> None:
     assert event["compression"]["transforms"] == {"crush": 2, "dedupe": 2}
     assert event["providers"] == ["anthropic"]
     assert event["failures"] == 0
+    assert event["failure_statuses"] == {}
 
     # The new burst is a distinct session, not a continuation.
     agg.flush_all()
     assert len(emitted) == 2, emitted
     assert emitted[1]["session"]["turns"] == 1
+
+    # --- per-strategy compression -----------------------------------------
+    # Compression runs on the executor thread before its request's outcome
+    # arrives, so events are staged and drained by the next outcome. That is
+    # what keeps the first turn's numbers while letting only an outcome open a
+    # session. `_staged_*` is module state, so clear it between cases.
+    _staged_strategies.clear()
+    _staged_stacks.clear()
+
+    strat: list[dict[str, Any]] = []
+    sa = SessionAggregator(strat.append, idle_s=10.0)
+    record_compression("smart_crusher", 1000, 400)
+    record_compression("smart_crusher", 500, 300)
+    record_compression("code_aware", 800, 800)
+    assert sa._current is None, "a compression event must not open a session"
+    sa.record(FakeOutcome(), now=2000.0)
+    sa.flush_all()
+    by = {row["strategy"]: row for row in strat[-1]["compression"]["by_strategy"]}
+    assert by["smart_crusher"] == {
+        "strategy": "smart_crusher",
+        "n": 2,
+        "tokens_in": 1500,
+        "tokens_out": 700,
+    }, by
+    # A strategy that ran and saved nothing must still appear: "ran 800 tokens
+    # through and removed none" is the finding, and dropping it would make
+    # every strategy look effective.
+    assert by["code_aware"]["tokens_in"] == by["code_aware"]["tokens_out"] == 800, by
+    assert strat[-1]["session"]["turns"] == 1, "compression events are not turns"
+    # A list of records, not an object keyed by strategy: the type must not
+    # change as strategies are added. See the note in payload().
+    assert isinstance(strat[-1]["compression"]["by_strategy"], list)
+    assert [r["strategy"] for r in strat[-1]["compression"]["by_strategy"]] == sorted(
+        r["strategy"] for r in strat[-1]["compression"]["by_strategy"]
+    ), "sorted so heartbeats are byte-comparable"
+
+    # Draining is exhaustive: a second session must not re-count the first
+    # session's events.
+    assert not _staged_strategies, "record() drains everything it staged"
+    again: list[dict[str, Any]] = []
+    sb = SessionAggregator(again.append, idle_s=10.0)
+    sb.record(FakeOutcome(), now=3000.0)
+    sb.flush_all()
+    assert again[-1]["compression"]["by_strategy"] == [], again[-1]
+
+    # An abandoned request — compression ran, the outcome never arrived — must
+    # not invent a session. Before staging, this emitted a phantom turns=0 row
+    # with all-zero tokens that inflated fleet session and install counts.
+    ghost: list[dict[str, Any]] = []
+    sc = SessionAggregator(ghost.append, idle_s=10.0)
+    record_compression("smart_crusher", 900, 100)
+    sc.flush_all()
+    assert ghost == [], "no outcome, no session"
+    _staged_strategies.clear()
+
+    # Over the cardinality cap, extra strategies are dropped rather than
+    # allowed to grow the payload without bound.
+    cap: list[dict[str, Any]] = []
+    cc = SessionAggregator(cap.append, idle_s=10.0)
+    for i in range(MAX_STRATEGIES + 5):
+        record_compression(f"s{i}", 100, 50)
+    cc.record(FakeOutcome(), now=4000.0)
+    cc.flush_all()
+    assert len(cap[-1]["compression"]["by_strategy"]) == MAX_STRATEGIES, cap[-1]
+    _staged_strategies.clear()
+
+    # Strategy names are slugged, never passed through: the observer protocol
+    # takes a free string and this is the only chokepoint before the wire.
+    assert _safe_slug("smart_crusher") == "smart_crusher"
+    assert _safe_slug("../../etc/passwd") == "other"
+
+    # --- stack detection ---------------------------------------------------
+    # Environment-only detection answers "proxy" for every install that points
+    # an agent at a persistent proxy instead of using `headroom wrap` — i.e.
+    # most of the fleet. The per-request slugs are the only real signal.
+    _staged_stacks.clear()
+    for _ in range(9):
+        record_stack("wrap_claude")
+    record_stack("wrap_cursor")
+    assert resource_attributes()["headroom.stack"] == "wrap_claude", "dominant stack wins"
+    _staged_stacks.clear()
+    for _ in range(5):
+        record_stack("wrap_claude")
+    for _ in range(5):
+        record_stack("wrap_cursor")
+    assert resource_attributes()["headroom.stack"] == "mixed", "no dominant stack"
+    _staged_stacks.clear()
+    record_stack("../../etc/passwd")
+    assert not _staged_stacks, "junk slugs never reach the wire"
+    assert resource_attributes()["headroom.stack"] == "proxy", "falls back with no signal"
+
     assert emitted[1]["session"]["id"] != emitted[0]["session"]["id"]
     assert emitted[1]["session"]["ended"] == "shutdown"
 
@@ -976,10 +1295,18 @@ def demo() -> None:
     class Failed(FakeOutcome):
         status_code = 529
 
+    class Broke(FakeOutcome):
+        status_code = 500
+
     agg2 = SessionAggregator(emitted.append)
     agg2.record(Failed(), now=2000.0)
+    agg2.record(Failed(), now=2001.0)
+    agg2.record(Broke(), now=2002.0)
     agg2.flush_all()
-    assert emitted[-1]["failures"] == 1
+    assert emitted[-1]["failures"] == 3
+    # Provider load-shedding and our own 500s have to be separable, or the
+    # count says "0.7% of turns failed" and nothing about whose fault it is.
+    assert emitted[-1]["failure_statuses"] == {"529": 2, "500": 1}
 
     # Flushing an empty aggregator is a no-op, not a null event.
     before = len(emitted)
diff --git a/headroom/telemetry/toin.py b/headroom/telemetry/toin.py
index 792cc9fd6..34fb3579d 100644
--- a/headroom/telemetry/toin.py
+++ b/headroom/telemetry/toin.py
@@ -97,6 +97,13 @@ DEFAULT_MODEL_FAMILY: Final[str] = "unknown"
 # environment; this is the production default the Rust proxy expects.
 DEFAULT_MIN_OBSERVATIONS_TO_PUBLISH: Final[int] = 50
 
+# TOIN is a diagnostic learning store, not an archive. Keep its default
+# footprint bounded so a long-lived proxy cannot turn observations into an
+# unbounded memory/disk liability.
+DEFAULT_MAX_PATTERNS: Final[int] = 10_000
+DEFAULT_MAX_STORAGE_BYTES: Final[int] = 128 * 1024 * 1024
+MAX_QUERY_PATTERN_LENGTH: Final[int] = 512
+
 # Aggregation-key serialization separator. Used to encode the
 # `(auth_mode, model_family, sig_hash)` tuple as a string for JSON
 # storage (JSON object keys must be strings) and for cross-instance
@@ -391,6 +398,8 @@ class TOINConfig:
     # Default path is ~/.headroom/toin.json (or HEADROOM_TOIN_PATH env var)
     storage_path: str = field(default_factory=get_default_toin_storage_path)
     auto_save_interval: int = 600  # Auto-save every 10 minutes
+    max_patterns: int = DEFAULT_MAX_PATTERNS
+    max_storage_bytes: int = DEFAULT_MAX_STORAGE_BYTES
 
     # Network learning thresholds
     min_samples_for_recommendation: int = 10
@@ -452,7 +461,10 @@ class ToolIntelligenceNetwork:
         if backend is not None:
             self._backend = backend
         elif self._config.storage_path:
-            self._backend = FileSystemTOINBackend(self._config.storage_path)
+            self._backend = FileSystemTOINBackend(
+                self._config.storage_path,
+                max_load_bytes=self._config.max_storage_bytes,
+            )
         else:
             self._backend = None
 
@@ -696,6 +708,7 @@ class ToolIntelligenceNetwork:
             pattern.last_updated = time.time()
             pattern.confidence = self._calculate_confidence(pattern)
             self._dirty = True
+            self._prune_patterns_locked()
 
         # Auto-save if needed (outside lock)
         self._maybe_auto_save()
@@ -775,6 +788,59 @@ class ToolIntelligenceNetwork:
             )[:100]
             pattern.field_semantics = dict(sorted_fields)
 
+    def _prune_patterns_locked(self) -> None:
+        """Bound the pattern table, evicting least-useful observations first.
+
+        The lock must be held by the caller. Patterns below the publish
+        threshold are disposable learning noise; within each class, oldest
+        observations are evicted first. If every pattern is mature, oldest
+        wins, keeping the table bounded without silently preferring a tenant.
+        """
+        limit = max(1, self._config.max_patterns)
+        if len(self._patterns) <= limit:
+            return
+
+        excess = len(self._patterns) - limit
+        evict = sorted(
+            self._patterns,
+            key=lambda key: (
+                self._patterns[key].sample_size >= DEFAULT_MIN_OBSERVATIONS_TO_PUBLISH,
+                self._patterns[key].last_updated,
+            ),
+        )[:excess]
+        for key in evict:
+            del self._patterns[key]
+
+        logger.info(
+            "TOIN pattern table pruned",
+            extra={
+                "event": "toin_patterns_pruned",
+                "evicted": excess,
+                "remaining": len(self._patterns),
+            },
+        )
+
+    def _sanitize_loaded_pattern(self, pattern: ToolPattern) -> bool:
+        """Remove legacy raw query keys from a loaded pattern."""
+        import re
+
+        safe_pattern = re.compile(r"(?:\w+:\*)(?:\s+\w+:\*)*")
+        changed = False
+        frequencies: dict[str, int] = {}
+        for raw_key, count in pattern.query_pattern_frequency.items():
+            if safe_pattern.fullmatch(raw_key) and len(raw_key) <= MAX_QUERY_PATTERN_LENGTH:
+                frequencies[raw_key] = max(0, int(count))
+            else:
+                changed = True
+        if frequencies != pattern.query_pattern_frequency:
+            changed = True
+            pattern.query_pattern_frequency = frequencies
+        safe_common = [key for key in pattern.common_query_patterns if key in frequencies]
+        if safe_common != pattern.common_query_patterns:
+            changed = True
+            pattern.common_query_patterns = safe_common[: self._config.max_query_patterns]
+        return changed
+
     def record_retrieval(
         self,
         tool_signature_hash: str,
@@ -949,6 +1015,7 @@ class ToolIntelligenceNetwork:
 
             pattern.last_updated = time.time()
             self._dirty = True
+            self._prune_patterns_locked()
 
         self._maybe_auto_save()
 
@@ -1050,14 +1117,22 @@ class ToolIntelligenceNetwork:
         if not query:
             return None
 
-        # Simple pattern extraction: replace values after : or =
+        # Only retain structured field/value predicates. Returning an
+        # unchanged free-form prompt here would persist the prompt verbatim,
+        # violating TOIN's privacy contract (and can produce multi-MB keys).
         import re
 
         # Match field:value or field="value" patterns, but don't include spaces in unquoted values
-        pattern = re.sub(r'(\w+)[=:](?:"[^"]*"|\'[^\']*\'|\w+)', r"\1:*", query)
+        matches = re.findall(r'(\w+)[=:](?:"[^"]*"|\'[^\']*\'|\w+)', query)
+        if not matches:
+            return None
+
+        # Preserve useful field shape while dropping operators, values, and
+        # all unrelated text (which may contain arbitrary prompt data).
+        pattern = " ".join(f"{field}:*" for field in matches)
 
         # Remove if it's just generic
-        if pattern in ("*", ""):
+        if not pattern or len(pattern) > MAX_QUERY_PATTERN_LENGTH:
             return None
 
         return pattern
@@ -1217,6 +1292,7 @@ class ToolIntelligenceNetwork:
             for serialized_key, pattern_dict in patterns_data.items():
                 key = _deserialize_pattern_key(serialized_key)
                 imported = ToolPattern.from_dict(pattern_dict)
+                self._sanitize_loaded_pattern(imported)
                 # Make sure dataclass fields agree with the dict key — pre-B5
                 # dumps don't carry auth_mode/model_family on the pattern;
                 # promote from the (possibly default) key.
@@ -1241,6 +1317,7 @@ class ToolIntelligenceNetwork:
                             # CRITICAL: Always increment user_count (even after cap)
                             pattern.user_count += 1
 
+            self._prune_patterns_locked()
             self._dirty = True
 
     def _merge_patterns(self, existing: ToolPattern, imported: ToolPattern) -> None:
@@ -1472,7 +1549,15 @@ class ToolIntelligenceNetwork:
             data = self._backend.load()
             if data:
                 self.import_patterns(data)
-                self._dirty = False
+                with self._lock:
+                    changed = any(
+                        self._sanitize_loaded_pattern(pattern)
+                        for pattern in self._patterns.values()
+                    )
+                    before = len(self._patterns)
+                    self._prune_patterns_locked()
+                    changed = changed or len(self._patterns) != before
+                    self._dirty = changed
         except Exception as e:
             logger.warning(
                 "TOIN storage load failed",
diff --git a/headroom/tokenizers/base.py b/headroom/tokenizers/base.py
index 5d291216d..cc9f12515 100644
--- a/headroom/tokenizers/base.py
+++ b/headroom/tokenizers/base.py
@@ -17,6 +17,68 @@ from typing import Any, Protocol, runtime_checkable
 #: encode. Truncating keeps the estimate finite and the request alive.
 _MAX_COERCED_FIELD_CHARS = 200_000
 
+#: Admission policy for :class:`TokenCountCache`. These bound memory only — they
+#: never change a returned count, so they are not a behavioural threshold.
+#: Strings below the floor encode in microseconds, so caching them would only
+#: evict the large entries that the cache exists for.
+_COUNT_CACHE_MIN_CHARS = 256
+_COUNT_CACHE_MAX_ENTRIES = 4096
+_COUNT_CACHE_MAX_CHARS = 8_000_000
+
+
+class TokenCountCache:
+    """Exact memo for ``count_text``.
+
+    ``count_text`` is a pure function of its text, so replaying a stored count is
+    value-identical. That is the whole safety argument: the result is the same
+    integer, which is why this is safe even at the call sites whose count feeds a
+    routing decision (``context_pressure`` -> ``min_ratio``) rather than a log line.
+
+    Keyed on the text itself rather than a hash. A hash collision here would hand
+    back the wrong count for real content and silently change what gets
+    compressed; the counts are too load-bearing to trade correctness for a
+    smaller key. The price is holding the strings, so entries *and* total
+    characters are capped.
+
+    No lock: ``dict`` get/set/clear are atomic under the GIL, and the pipeline
+    runs on a thread pool. An LRU would need ``move_to_end``, which is not
+    atomic — hence clear-on-full rather than eviction. A cleared cache costs one
+    re-encode, never a wrong answer.
+    """
+
+    __slots__ = ("_chars", "_counts", "_max_chars", "_max_entries", "_min_chars")
+
+    def __init__(
+        self,
+        *,
+        min_chars: int = _COUNT_CACHE_MIN_CHARS,
+        max_entries: int = _COUNT_CACHE_MAX_ENTRIES,
+        max_chars: int = _COUNT_CACHE_MAX_CHARS,
+    ) -> None:
+        self._counts: dict[str, int] = {}
+        self._chars = 0
+        self._min_chars = min_chars
+        self._max_entries = max_entries
+        self._max_chars = max_chars
+
+    def get(self, text: str) -> int | None:
+        """Return the stored count for *text*, or None."""
+        return self._counts.get(text)
+
+    def put(self, text: str, count: int) -> None:
+        """Store *count* for *text* if it is worth caching."""
+        if len(text) < self._min_chars:
+            return
+        if len(self._counts) >= self._max_entries or self._chars >= self._max_chars:
+            self._counts.clear()
+            self._chars = 0
+        self._counts[text] = count
+        self._chars += len(text)
+
+    def clear(self) -> None:
+        self._counts.clear()
+        self._chars = 0
+
 
 def coerce_countable_text(value: Any) -> str:
     """Return *value* as text safe to pass to ``count_text``.
diff --git a/headroom/tokenizers/estimator.py b/headroom/tokenizers/estimator.py
index e20ea15d5..a3ee9683e 100644
--- a/headroom/tokenizers/estimator.py
+++ b/headroom/tokenizers/estimator.py
@@ -11,7 +11,7 @@ import json
 import re
 from typing import Any
 
-from .base import BaseTokenizer
+from .base import BaseTokenizer, TokenCountCache
 
 
 class EstimatingTokenCounter(BaseTokenizer):
@@ -87,6 +87,7 @@ class EstimatingTokenCounter(BaseTokenizer):
                             If None, auto-detects based on content type.
         """
         self._fixed_ratio = chars_per_token
+        self._count_cache = TokenCountCache()
 
     def count_text(self, text: str) -> int:
         """Estimate token count for text.
@@ -100,6 +101,14 @@ class EstimatingTokenCounter(BaseTokenizer):
         if not text:
             return 0
 
+        cached = self._count_cache.get(text)
+        if cached is not None:
+            return cached
+        count = self._count_text_uncached(text)
+        self._count_cache.put(text, count)
+        return count
+
+    def _count_text_uncached(self, text: str) -> int:
         # Use fixed ratio if provided. Dense scripts (CJK/Kana/Hangul) still
         # tokenize at ~1 token per character, so pricing them at the (Latin)
         # fixed ratio under-counts by 2-4x — the same correction the auto path
diff --git a/headroom/tokenizers/tiktoken_counter.py b/headroom/tokenizers/tiktoken_counter.py
index 1aa987037..4ec8fadc2 100644
--- a/headroom/tokenizers/tiktoken_counter.py
+++ b/headroom/tokenizers/tiktoken_counter.py
@@ -16,7 +16,7 @@ import threading
 from functools import lru_cache
 from typing import Any
 
-from .base import BaseTokenizer, coerce_countable_text
+from .base import BaseTokenizer, TokenCountCache, coerce_countable_text
 
 logger = logging.getLogger(__name__)
 
@@ -237,6 +237,7 @@ class TiktokenCounter(BaseTokenizer):
         self.model = model
         self.encoding_name = encoding or get_encoding_for_model(model)
         self._encoding = None  # Lazy load
+        self._count_cache = TokenCountCache()
 
     @property
     def encoding(self):
@@ -256,6 +257,14 @@ class TiktokenCounter(BaseTokenizer):
         """
         if not text:
             return 0
+        cached = self._count_cache.get(text)
+        if cached is not None:
+            return cached
+        count = self._count_text_uncached(text)
+        self._count_cache.put(text, count)
+        return count
+
+    def _count_text_uncached(self, text: str) -> int:
         try:
             return len(self.encoding.encode(text))
         except ValueError:
diff --git a/headroom/transforms/adaptive_sizer.py b/headroom/transforms/adaptive_sizer.py
index 9a867d60a..5f73aabd8 100644
--- a/headroom/transforms/adaptive_sizer.py
+++ b/headroom/transforms/adaptive_sizer.py
@@ -51,7 +51,12 @@ def compute_optimal_k(
 
     # Tier 1: Fast path
     if n <= 8:
-        return n
+        # Still honor the caller's hard cap: ``max_k`` is documented as "never
+        # return more than this". Returning the raw ``n`` let a small ``max_k``
+        # (e.g. a tight search/log budget) be exceeded on tiny inputs, so the
+        # caller kept more items than it asked for. The near-duplicate branch
+        # below already clamps to ``effective_max``; do the same here.
+        return min(n, effective_max)
 
     # Check for near-total redundancy
     unique_count = count_unique_simhash(items)
diff --git a/headroom/transforms/compression_units.py b/headroom/transforms/compression_units.py
index c499446c1..063b55b7f 100644
--- a/headroom/transforms/compression_units.py
+++ b/headroom/transforms/compression_units.py
@@ -52,8 +52,10 @@ class CompressionUnit:
 # - compressor_noop:   router returned identical bytes (no compression possible)
 # - already_compressed: input already carried a CCR retrieval marker
 # - rejected_not_smaller: compressor produced output >= input tokens
-# - cache_hit:         result returned from result_cache (placeholder; not
-#                      currently wired into the unit path — see follow-up)
+# - cache_hit:         reserved; cached unit reuse is caller-level (the OpenAI
+#                      Responses handler's unit-result cache) and is surfaced
+#                      via RouterCompressionResult.cache_hit, not as a reason
+#                      here — no code path produces this category today
 UNIT_REASON_CATEGORIES = {
     None: "applied",
     "protected_user_message": "protected_role",
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 4aeb03f3e..0ba64cb17 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -98,7 +98,6 @@ split_into_sections = _mixed_content.split_into_sections
 _detect_backend_warned = False
 _detect_panic_warned = False
 _detect_native_unhealthy = False  # circuit breaker: native detect hung once (#575)
-_detect_native_verified = False  # native detect has returned once -> skip the watchdog
 
 
 # Shared calibrated fallback estimator (tiktoken cl100k_base ~90% accuracy,
@@ -917,7 +916,6 @@ def _detect_content(content: str) -> DetectionResult:
     `_strategy_from_detection` keys off that field alone.
     """
     global _detect_backend_warned, _detect_panic_warned, _detect_native_unhealthy
-    global _detect_native_verified
 
     # Detect on the unwrapped payload so a tool-output envelope's tags don't get
     # the whole result misclassified as HTML/XML (#route-converter corruption).
@@ -940,22 +938,30 @@ def _detect_content(content: str) -> DetectionResult:
         # another stuck daemon thread, so route straight to pure-Python.
         return _regex_detect_content_type(content)
 
+    # fastembed enables ort's API-24 feature. Entering the native initializer
+    # with an older pip ONNX Runtime does not raise: ort recursively re-enters
+    # its OnceLock error path and parks forever (#2960). Preflight before the
+    # extension call so supported Python 3.10 installs degrade immediately.
+    from headroom._ort import rust_ort_runtime_compatible
+
+    if not rust_ort_runtime_compatible():
+        _detect_native_unhealthy = True
+        logger.warning(
+            "Native content detection requires ONNX Runtime 1.24+; "
+            "using pure-Python detection for this process."
+        )
+        return _regex_detect_content_type(content)
+
     from headroom._core import detect_content_type as _rust_detect
 
     try:
-        # The native detector can deadlock on FIRST use (#575 — seen on Windows
-        # and macOS/arm64). Bound it with a watchdog so a hang degrades to the
-        # pure-Python detector; the previous win32-only guard left other
-        # platforms unprotected, so a hung Linux sidecar silently stopped
-        # compressing (every request failed open to passthrough). Watchdog until
-        # the native detector has returned once, then use the direct fast path —
-        # the hang is first-use only, so steady state pays no per-call thread
-        # overhead. win32 keeps watchdogging every call (unchanged).
-        if sys.platform == "win32" or not _detect_native_verified:
-            rust_result = _rust_detect_watchdogged(_rust_detect, content, _detect_timeout_secs())
-        else:
-            rust_result = _rust_detect(content)
-        _detect_native_verified = True  # returned without hanging -> trusted hot path
+        # Native detector state can become wedged after an earlier successful
+        # call (for example when another test or component initializes ORT).
+        # A one-time "verified" fast path therefore turns a later native stall
+        # into an unbounded process hang. Keep every call bounded; on timeout
+        # the process-wide circuit breaker below makes subsequent calls use the
+        # pure-Python detector without spawning more watchdog threads.
+        rust_result = _rust_detect_watchdogged(_rust_detect, content, _detect_timeout_secs())
         # Rust's `content_type` is the lowercase string tag (e.g.
         # "json_array"); translate to the Python `ContentType` enum so
         # downstream mapping keys match.
@@ -1394,11 +1400,12 @@ class RouterCompressionResult:
             LOG fallback chain it's three. Lets log readers see *how*
             we got to the final compressor without parsing the
             decision_reason string.
-        cache_hit: True when this result came from the router's
-            result_cache (no fresh compression ran). Currently the
-            single-content compress() path doesn't populate the cache,
-            so this is False in practice — placeholder for the
-            cache-wire-up follow-up.
+        cache_hit: True when this result was reused from a cache
+            instead of a fresh compression run. compress() itself
+            never sets this (only apply() has the router-internal
+            two-tier cache); it is set by callers that cache unit
+            results — e.g. the OpenAI Responses handler marks reused
+            units via ``replace(router_result, cache_hit=True)``.
     """
 
     compressed: str
@@ -2406,7 +2413,24 @@ class ContentRouter(Transform):
         Returns:
             RouterCompressionResult with reassembled content.
         """
-        sections = split_into_sections(content)
+        from .tag_protector import protect_tags, restore_tags
+
+        # Protect custom-tag blocks BEFORE splitting into sections. Section
+        # boundaries (code fences, blank lines) split a
+        # ``<system-reminder>...</system-reminder>`` pair across sections, so
+        # the per-section tag protection inside ``_try_ml_compressor`` never
+        # sees a matched pair (an unmatched tag protects nothing) and
+        # instruction blocks — Claude Code ships CLAUDE.md inside
+        # <system-reminder> — leak into lossy ML compression and arrive
+        # word-dropped. Protecting here keeps the whole block as one
+        # placeholder that spans sections intact.
+        cleaned, protected = protect_tags(
+            content,
+            compress_tagged_content=self.config.compress_tagged_content,
+        )
+        sections_source = cleaned if protected else content
+
+        sections = split_into_sections(sections_source)
         if logger.isEnabledFor(logging.DEBUG):
             _log_router_debug(
                 "content_router_mixed_sections",
@@ -2422,10 +2446,32 @@ class ContentRouter(Transform):
                 strategy_used=CompressionStrategy.PASSTHROUGH,
             )
 
+        # Placeholders must survive byte-exact: ``restore_tags`` DISCARDS a
+        # protected block whose placeholder was stripped or rewritten
+        # (Hotfix-A9), so a compressor eating a placeholder would silently
+        # drop the whole tag block — worse than the mangling this fixes.
+        # Any section carrying a placeholder is passed through verbatim
+        # instead of ever entering a compressor.
+        placeholders = [placeholder for placeholder, _ in protected]
+
         compressed_sections: list[str] = []
         routing_log: list[RoutingDecision] = []
 
         for i, section in enumerate(sections):
+            if placeholders and any(ph in section.content for ph in placeholders):
+                section_tokens = _estimate_tokens(section.content)
+                compressed_sections.append(section.content)
+                routing_log.append(
+                    RoutingDecision(
+                        content_type=section.content_type,
+                        strategy=CompressionStrategy.PASSTHROUGH,
+                        original_tokens=section_tokens,
+                        compressed_tokens=section_tokens,
+                        section_index=i,
+                    )
+                )
+                continue
+
             # Get strategy for this section
             strategy = self._strategy_from_detection_type(section.content_type)
 
@@ -2455,8 +2501,12 @@ class ContentRouter(Transform):
                 )
             )
 
+        compressed = "\n\n".join(compressed_sections)
+        if protected:
+            compressed = restore_tags(compressed, protected)
+
         return RouterCompressionResult(
-            compressed="\n\n".join(compressed_sections),
+            compressed=compressed,
             original=content,
             strategy_used=CompressionStrategy.MIXED,
             routing_log=routing_log,
@@ -4186,11 +4236,42 @@ class ContentRouter(Transform):
             else:
                 status["code_aware"] = "not installed"
 
-        # 4. SmartCrusher (lightweight init, but ensures import + TOIN ready)
+        # 4. SmartCrusher (lightweight init)
         smart_crusher = self._get_smart_crusher()
         if smart_crusher:
             status["smart_crusher"] = "ready"
 
+        # 5. HTML extractor.
+        #
+        # By far the most expensive lazy import in the transform tree: MEASURED
+        # 978ms for trafilatura -> htmldate -> dateparser and its timezone
+        # tables, against 1-20ms for every other compressor module. It fires
+        # from _get_html_extractor() on the first request carrying an HTML-ish
+        # block or mixed-content section, so a real user pays the full second
+        # mid-request. That is the single largest first-request stall in the
+        # pipeline, which is why it is worth a line here.
+        try:
+            if self._get_html_extractor() is not None:
+                status["html_extractor"] = "ready"
+            else:
+                status["html_extractor"] = "not installed"
+        except Exception as e:
+            logger.debug("HTML extractor pre-load skipped: %s", e)
+            status["html_extractor"] = "skipped"
+
+        # 6. TOIN singleton. Constructing it reads the learned-pattern file off
+        # disk (MEASURED ~150ms at 5MB, and it grows with use). SmartCrusher
+        # above does NOT pull it in, despite what a previous comment here
+        # claimed — the first request did.
+        try:
+            from ..telemetry.toin import get_toin
+
+            get_toin()
+            status["toin"] = "ready"
+        except Exception as e:
+            logger.debug("TOIN pre-load skipped: %s", e)
+            status["toin"] = "skipped"
+
         return status
 
     def _get_kompress(self) -> Any:
diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.py
index 37c4260cf..84caa0896 100644
--- a/headroom/transforms/kompress_compressor.py
+++ b/headroom/transforms/kompress_compressor.py
@@ -746,15 +746,27 @@ def _load_kompress_onnx(
 
 
 def _load_modernbert_tokenizer(auto_tokenizer: Any, *, allow_download: bool) -> Any:
-    """Load the ModernBERT tokenizer, cache-only when ``allow_download`` is False."""
+    """Load the ModernBERT tokenizer, cache-only when ``allow_download`` is False.
+
+    Always tries the local cache FIRST, even when downloading is allowed. With
+    ``local_files_only=False`` transformers re-validates against the Hub on every
+    load — a tree listing plus a HEAD per tokenizer file — even when the repo is
+    fully cached. MEASURED ~900ms warm-cache versus ~150ms local-only, i.e. ~750ms
+    of pure network round-trip on every process start, and it is also what makes
+    a cold start slow on a bad network rather than merely offline.
+
+    Same files, same tokenizer, so the loaded object is identical; this only
+    changes whether the Hub is consulted to confirm what is already on disk.
+    Mirrors ``onnx_runtime.hf_hub_download_local_first``, which the ONNX half of
+    this loader already uses.
+    """
     try:
-        return auto_tokenizer.from_pretrained(
-            "answerdotai/ModernBERT-base", local_files_only=not allow_download
-        )
+        return auto_tokenizer.from_pretrained("answerdotai/ModernBERT-base", local_files_only=True)
     except _NOT_CACHED_ERRORS as exc:
         if not allow_download:
             raise KompressModelNotCached("answerdotai/ModernBERT-base") from exc
-        raise
+    # Genuine cache miss and downloading is permitted: fetch it.
+    return auto_tokenizer.from_pretrained("answerdotai/ModernBERT-base", local_files_only=False)
 
 
 # Sub-state-dict keys inside a merged v2-style checkpoint (see
@@ -1039,6 +1051,45 @@ def unload_kompress_model(model_id: str | None = None) -> bool:
 _download_threads: dict[str, threading.Thread] = {}
 _download_threads_lock = threading.Lock()
 
+#: Retry backoff for a FAILED background download, in seconds. A finished-or-failed
+#: thread is replaced on the next call so a transient network blip recovers, but
+#: without a floor an unreachable Hub means every request spawns a fresh download
+#: thread for the life of the process — each one importing transformers and
+#: resolving the Hub, all holding the GIL against the event loop. The window grows
+#: per consecutive failure and resets on success, so the happy path and the
+#: transient-failure path are both unchanged; only the permanently-broken case is
+#: bounded.
+_DOWNLOAD_RETRY_BASE_SECONDS = 5.0
+_DOWNLOAD_RETRY_MAX_SECONDS = 300.0
+_download_failures: dict[str, tuple[int, float]] = {}
+
+
+def _record_download_failure(model_id: str) -> None:
+    with _download_threads_lock:
+        failures, _ = _download_failures.get(model_id, (0, 0.0))
+        _download_failures[model_id] = (failures + 1, time.monotonic())
+
+
+def _clear_download_failures(model_id: str) -> None:
+    with _download_threads_lock:
+        _download_failures.pop(model_id, None)
+
+
+def _download_retry_blocked(model_id: str) -> bool:
+    """True when the last attempt failed and the backoff window has not elapsed.
+
+    Caller must hold ``_download_threads_lock``.
+    """
+    entry = _download_failures.get(model_id)
+    if entry is None:
+        return False
+    failures, last_attempt = entry
+    window = min(
+        _DOWNLOAD_RETRY_MAX_SECONDS,
+        _DOWNLOAD_RETRY_BASE_SECONDS * (2 ** (failures - 1)),
+    )
+    return bool((time.monotonic() - last_attempt) < window)
+
 
 def _background_download(model_id: str, device: str) -> None:
     try:
@@ -1046,7 +1097,10 @@ def _background_download(model_id: str, device: str) -> None:
         _load_kompress(model_id, device, allow_download=True)
         logger.info("Kompress: background model download complete for %s", model_id)
     except Exception as exc:
+        _record_download_failure(model_id)
         logger.warning("Kompress: background model download failed for %s: %s", model_id, exc)
+    else:
+        _clear_download_failures(model_id)
 
 
 def ensure_background_download(model_id: str = HF_MODEL_ID, device: str = "auto") -> None:
@@ -1054,7 +1108,9 @@ def ensure_background_download(model_id: str = HF_MODEL_ID, device: str = "auto"
 
     Idempotent and non-blocking: at most one download thread runs per model_id,
     and a finished or failed thread is replaced on the next call so a transient
-    network failure can be retried by a later request. Once the download
+    network failure can be retried by a later request — subject to a growing
+    backoff after consecutive failures, so an unreachable Hub cannot turn every
+    request into another download thread. Once the download
     completes the deep path activates on subsequent requests without ever
     blocking one on the network.
     """
@@ -1066,6 +1122,8 @@ def ensure_background_download(model_id: str = HF_MODEL_ID, device: str = "auto"
         existing = _download_threads.get(model_id)
         if existing is not None and existing.is_alive():
             return
+        if _download_retry_blocked(model_id):
+            return
         thread = threading.Thread(
             target=_background_download,
             args=(model_id, device),
diff --git a/headroom/transforms/mixed_content.py b/headroom/transforms/mixed_content.py
index 6991c1acb..3ec7b2b80 100644
--- a/headroom/transforms/mixed_content.py
+++ b/headroom/transforms/mixed_content.py
@@ -43,16 +43,32 @@ def mixed_content_indicators(content: str) -> dict[str, bool]:
     }
 
 
+def _any_nonblank(lines: list[str], start: int, stop: int) -> bool:
+    """True when some line in [start, stop) has non-whitespace.
+
+    Equivalent to ``bool("\n".join(lines[start:stop]).strip())`` — a join of
+    lines is blank exactly when every line is blank — but it short-circuits
+    instead of building a copy of the whole body for each candidate.
+    """
+    return any(lines[i].strip() for i in range(start, stop))
+
+
 def _has_valid_json_block_with_text(content: str) -> bool:
     """Return true when prose or log text wraps a valid JSON block."""
     lines = content.split("\n")
+    # Built only after a scan has run to the end without balancing — see
+    # _extract_json_block. Content that balances promptly never allocates it and
+    # so pays nothing for it.
+    scan_cache: dict[tuple[int, bool, bool], tuple[int, int, bool, bool]] | None = None
 
     for index, line in enumerate(lines):
         if not line.strip().startswith(("[", "{")):
             continue
 
-        json_content, end_index = _extract_json_block(lines, index)
+        json_content, end_index = _extract_json_block(lines, index, cache=scan_cache)
         if json_content is None:
+            if scan_cache is None:
+                scan_cache = {}
             continue
 
         try:
@@ -60,9 +76,7 @@ def _has_valid_json_block_with_text(content: str) -> bool:
         except (TypeError, ValueError):
             continue
 
-        leading_text = "\n".join(lines[:index]).strip()
-        trailing_text = "\n".join(lines[end_index + 1 :]).strip()
-        if leading_text or trailing_text:
+        if _any_nonblank(lines, 0, index) or _any_nonblank(lines, end_index + 1, len(lines)):
             return True
 
     return False
@@ -72,6 +86,7 @@ def split_into_sections(content: str) -> list[ContentSection]:
     """Parse mixed content into typed sections."""
     sections: list[ContentSection] = []
     lines = content.split("\n")
+    scan_cache: dict[tuple[int, bool, bool], tuple[int, int, bool, bool]] | None = None
 
     i = 0
     while i < len(lines):
@@ -101,7 +116,11 @@ def split_into_sections(content: str) -> list[ContentSection]:
             continue
 
         if line.strip().startswith(("[", "{")):
-            json_content, end_i = _extract_json_block(lines, i)
+            json_content, end_i = _extract_json_block(lines, i, cache=scan_cache)
+            if json_content is None and scan_cache is None:
+                # First scan that ran to the end without balancing: from here on
+                # every later candidate would re-walk the same tail.
+                scan_cache = {}
             if json_content:
                 sections.append(
                     ContentSection(
@@ -159,41 +178,84 @@ def split_into_sections(content: str) -> list[ContentSection]:
     return sections
 
 
-def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]:
-    """Extract a complete JSON object or array block from line-oriented content."""
+def _scan_line(line: str, in_string: bool, escaped: bool) -> tuple[int, int, bool, bool]:
+    """Bracket/brace deltas for one line, given the parser state entering it.
+
+    Split out so the per-line result can be memoised across scans: what a line
+    does to the counters is a pure function of the line and the two entry-state
+    flags, nothing else.
+    """
+    bracket = 0
+    brace = 0
+    for ch in line:
+        if escaped:
+            escaped = False
+            continue
+        if ch == "\\":
+            if in_string:
+                escaped = True
+            continue
+        if ch == '"':
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if ch == "[":
+            bracket += 1
+        elif ch == "]":
+            bracket -= 1
+        elif ch == "{":
+            brace += 1
+        elif ch == "}":
+            brace -= 1
+    return bracket, brace, in_string, escaped
+
+
+def _extract_json_block(
+    lines: list[str],
+    start: int,
+    *,
+    cache: dict[tuple[int, bool, bool], tuple[int, int, bool, bool]] | None = None,
+) -> tuple[str | None, int]:
+    """Extract a complete JSON object or array block from line-oriented content.
+
+    ``cache`` memoises the per-line scan across repeated calls over the SAME
+    ``lines``. Callers that try every ``{``-leading line share one dict; without
+    it each candidate that never balances re-scans character-by-character to the
+    end of the content, which is quadratic.
+
+    Callers pass ``None`` until a scan has actually run to the end without
+    balancing, and only build the dict from then on. That matters: on content
+    that balances on the first try — pretty-printed JSON, the common case — the
+    memo has nothing to reuse and its per-line dict traffic made that shape ~2x
+    SLOWER. A failed scan is the signal that later candidates will re-walk the
+    same tail, and it is the only point at which the memo pays. MEASURED before the cache: 4643ms for
+    1200 lines of JS-style object logs and 3737ms for truncated JSONL, growing
+    exactly 4x per doubling. Ordinary shapes — pretty-printed JSON, valid JSONL,
+    source, stack traces, prose — were ~1-6ms and never hit it, which is why this
+    stayed invisible.
+
+    Keyed on the entry state as well as the line, so a cached entry is only
+    reused where the parser is in the same string/escape state. Same deltas,
+    same result: this is a memo, not a heuristic.
+    """
     bracket_count = 0
     brace_count = 0
-    json_lines = []
     in_string = False
     escaped = False
 
     for i in range(start, len(lines)):
-        line = lines[i]
-        json_lines.append(line)
+        key = (i, in_string, escaped)
+        step = cache.get(key) if cache is not None else None
+        if step is None:
+            step = _scan_line(lines[i], in_string, escaped)
+            if cache is not None:
+                cache[key] = step
+        d_bracket, d_brace, in_string, escaped = step
+        bracket_count += d_bracket
+        brace_count += d_brace
 
-        for ch in line:
-            if escaped:
-                escaped = False
-                continue
-            if ch == "\\":
-                if in_string:
-                    escaped = True
-                continue
-            if ch == '"':
-                in_string = not in_string
-                continue
-            if in_string:
-                continue
-            if ch == "[":
-                bracket_count += 1
-            elif ch == "]":
-                bracket_count -= 1
-            elif ch == "{":
-                brace_count += 1
-            elif ch == "}":
-                brace_count -= 1
-
-        if bracket_count <= 0 and brace_count <= 0 and json_lines:
-            return "\n".join(json_lines), i
+        if bracket_count <= 0 and brace_count <= 0:
+            return "\n".join(lines[start : i + 1]), i
 
     return None, start
diff --git a/headroom/transforms/pipeline.py b/headroom/transforms/pipeline.py
index c7061dee1..305e888f6 100644
--- a/headroom/transforms/pipeline.py
+++ b/headroom/transforms/pipeline.py
@@ -138,15 +138,10 @@ class TransformPipeline:
 
         # 0. Tool-result interceptors (ast-grep Read outline, etc.) run first
         # so downstream compressors operate on the already-shrunk content.
-        # OPT-IN: enable via HeadroomConfig.intercept_tool_results, or for
-        # non-config callers (CLI / SDK / tests) the env var
-        # HEADROOM_INTERCEPT_ENABLED=1. Off by default while this ships — lets
-        # users try it and compare before we make it the default.
-        import os as _os
-
-        if getattr(self.config, "intercept_tool_results", False) or _os.environ.get(
-            "HEADROOM_INTERCEPT_ENABLED"
-        ):
+        # Rollout was resolved once by HeadroomConfig. Never re-read process
+        # environment here: this pipeline must match its recorded provenance.
+        assert self.config.rollout is not None
+        if self.config.rollout.is_enabled("tool_result_interceptors"):
             from headroom.proxy.interceptors import ToolResultInterceptorTransform
 
             transforms.append(ToolResultInterceptorTransform())
@@ -163,7 +158,13 @@ class TransformPipeline:
         # - Logs -> LogCompressor
         # - Search results -> SearchCompressor
         # - HTML -> HTMLExtractor
-        transforms.append(ContentRouter())
+        # observer: the proxy passes PrometheusMetrics; this bare pipeline is
+        # used by the library/adapter paths, which would otherwise report
+        # tokens.saved with an empty by_strategy. Imported here rather than at
+        # module scope — transforms sits below telemetry in the import graph.
+        from headroom.telemetry.session import BeaconCompressionObserver
+
+        transforms.append(ContentRouter(observer=BeaconCompressionObserver()))
         logger.info("Pipeline using ContentRouter for intelligent content-aware compression")
 
         return transforms
diff --git a/headroom/transforms/smart_crusher.py b/headroom/transforms/smart_crusher.py
index 4dde88736..6ec0e4443 100644
--- a/headroom/transforms/smart_crusher.py
+++ b/headroom/transforms/smart_crusher.py
@@ -1202,7 +1202,12 @@ class SmartCrusher(Transform):
             if msg.get("role") == "assistant" and msg.get("tool_calls"):
                 for tc in msg.get("tool_calls", []):
                     if isinstance(tc, dict):
-                        func = tc.get("function", {})
+                        # `tc.get("function", {})` returns None for an explicit
+                        # {"function": null} (the default only applies to a
+                        # missing key), and `.get` on None raises AttributeError,
+                        # crashing apply(). Use the null-safe form the sibling
+                        # `_build_tool_name_index` already uses (line ~118).
+                        func = tc.get("function") or {}
                         args = func.get("arguments", "")
                         if isinstance(args, str) and args:
                             context_parts.append(args)
diff --git a/llms.txt b/llms.txt
index 84cc27da9..fe2412fdb 100644
--- a/llms.txt
+++ b/llms.txt
@@ -19,7 +19,7 @@ The canonical, always-current documentation index lives at the docs site below.
 
 - Python: `pip install headroom-ai` (add `[all]` for every optional extra)
 - TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
-- Docker: `docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest`
+- Docker: `docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest`
 - Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
 - Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`)
 
diff --git a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
index 2ba021479..4257625a4 100644
--- a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
+++ b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "headroom",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
   "author": {
     "name": "Headroom Contributors",
diff --git a/plugins/headroom-agent-hooks/.github/plugin/plugin.json b/plugins/headroom-agent-hooks/.github/plugin/plugin.json
index aa29c7291..974363f1d 100644
--- a/plugins/headroom-agent-hooks/.github/plugin/plugin.json
+++ b/plugins/headroom-agent-hooks/.github/plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "headroom",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
   "author": {
     "name": "Headroom Contributors",
diff --git a/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py b/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py
index e4ffe31d3..b202caf39 100644
--- a/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py
+++ b/plugins/headroom-oauth2/src/headroom_oauth2/__init__.py
@@ -13,7 +13,7 @@ from typing import Any
 from .middleware import OAuth2Middleware
 from .provider import OAuth2ClientCredentials, OAuth2Error
 
-__all__ = ["install", "OAuth2ClientCredentials", "OAuth2Error", "OAuth2Middleware", "parse_headers"]
+__all__ = ["OAuth2ClientCredentials", "OAuth2Error", "OAuth2Middleware", "install", "parse_headers"]
 __version__ = "0.1.0"
 log = logging.getLogger("headroom_oauth2")
 
@@ -116,7 +116,13 @@ def install(app: Any, config: Any) -> None:
             os.environ.update(_before)
             litellm.headers = {**(getattr(litellm, "headers", None) or {}), **static}
             log.info("headroom-oauth2: static upstream headers: %s", list(static))
-        except Exception as e:  # pragma: no cover
+        except (
+            ImportError,
+            AttributeError,
+            OSError,
+            TypeError,
+            ValueError,
+        ) as e:  # pragma: no cover
             log.warning("headroom-oauth2: could not set litellm.headers: %s", e)
     # The litellm backend auths bedrock/vertex/sagemaker from env and ignores a forwarded
     # bearer, so this extension is a no-op there -- warn loudly rather than silently do nothing.
diff --git a/plugins/headroom-oauth2/src/headroom_oauth2/provider.py b/plugins/headroom-oauth2/src/headroom_oauth2/provider.py
index dbcf92df6..49f00d996 100644
--- a/plugins/headroom-oauth2/src/headroom_oauth2/provider.py
+++ b/plugins/headroom-oauth2/src/headroom_oauth2/provider.py
@@ -14,6 +14,7 @@ import threading
 import time
 import urllib.parse
 import urllib.request
+from contextlib import suppress
 from urllib.error import HTTPError, URLError
 
 log = logging.getLogger("headroom_oauth2")
@@ -128,10 +129,8 @@ class OAuth2ClientCredentials:
             with urllib.request.urlopen(req, timeout=self.timeout) as resp:
                 payload = json.load(resp)
         except HTTPError as e:
-            try:
+            with suppress(Exception):
                 e.read()  # drain; do NOT surface the IdP body (may echo sensitive context)
-            except Exception:
-                pass
             raise OAuth2Error(f"token endpoint returned HTTP {e.code}") from None
         except (URLError, OSError) as e:
             raise OAuth2Error(f"token endpoint unreachable: {e}") from None
diff --git a/plugins/headroom-oauth2/tests/test_oauth2.py b/plugins/headroom-oauth2/tests/test_oauth2.py
index 5372cb599..4a8b03d35 100644
--- a/plugins/headroom-oauth2/tests/test_oauth2.py
+++ b/plugins/headroom-oauth2/tests/test_oauth2.py
@@ -1,9 +1,11 @@
 import asyncio
 import base64
 import json
+import logging
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.error import HTTPError
 
 import pytest
 
@@ -161,6 +163,26 @@ def test_error_on_bad_status_hides_body(idp):
     assert "SENSITIVE" not in str(ei.value)  # IdP error body must not leak into the exception
 
 
+def test_error_body_drain_failure_is_sanitized(monkeypatch, caplog):
+    class _UnreadableHTTPError(HTTPError):
+        def read(self):
+            raise RuntimeError("SENSITIVE")
+
+    def fail(*_args, **_kwargs):
+        raise _UnreadableHTTPError("https://idp.example/token", 503, "unavailable", {}, None)
+
+    monkeypatch.setattr("urllib.request.urlopen", fail)
+    caplog.set_level(logging.DEBUG, logger="headroom_oauth2")
+    p = OAuth2ClientCredentials(
+        token_url="https://idp.example/token", client_id="c", client_secret="s"
+    )
+
+    with pytest.raises(OAuth2Error, match="HTTP 503") as exc_info:
+        p.token()
+    assert "SENSITIVE" not in str(exc_info.value)
+    assert "SENSITIVE" not in caplog.text
+
+
 def test_malformed_200_no_token(idp):
     _IdP.tok = None  # HTTP 200 but no access_token field
     p = OAuth2ClientCredentials(token_url=idp, client_id="c", client_secret="s")
@@ -492,3 +514,24 @@ def test_install_sets_static_headers(monkeypatch):
 
     install(App(), _cfg("litellm-openai"))
     assert fake.headers == {"X-App": "demo"}  # valid header set on litellm; malformed key dropped
+
+
+def test_install_handles_invalid_litellm_headers(monkeypatch, caplog):
+    import sys
+    import types
+
+    fake = types.ModuleType("litellm")
+    fake.headers = object()
+    monkeypatch.setitem(sys.modules, "litellm", fake)
+    monkeypatch.setenv("HEADROOM_OAUTH2_TOKEN_URL", "https://idp.example.com/token")
+    monkeypatch.setenv("HEADROOM_OAUTH2_CLIENT_ID", "c")
+    monkeypatch.setenv("HEADROOM_OAUTH2_CLIENT_SECRET", "s")
+    monkeypatch.setenv("HEADROOM_OAUTH2_HEADERS", "X-App=demo")
+    caplog.set_level(logging.WARNING, logger="headroom_oauth2")
+
+    class App:
+        def add_middleware(self, *a, **k):
+            pass
+
+    install(App(), _cfg("litellm-openai"))
+    assert "could not set litellm.headers" in caplog.text
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index a721377b3..25e2d324b 100644
--- a/plugins/openclaw/README.md
+++ b/plugins/openclaw/README.md
@@ -205,6 +205,9 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored
 | `pythonPath` | auto-detected | Optional Python executable override for Python fallback launcher. |
 | `autoStart` | `false` | Opt-in auto-start for a local `headroom proxy` if not already running (local URLs only; ignored for remote proxies). Keep `false` when systemd owns the proxy. |
 | `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
+| `requestTimeoutMs` | `30000` | Maximum milliseconds to wait for a single `compress()` call. If the proxy hangs or is slow, the call is cancelled after this deadline and the original uncompressed messages are used as a fallback. |
+| `circuitBreakerThreshold` | `3` | Number of consecutive `assemble()` errors before the circuit breaker opens and all requests bypass the proxy. Prevents cascading failures when the proxy is unhealthy. |
+| `circuitBreakerCooldownMs` | `60000` | How long (ms) the circuit breaker stays open after the threshold is reached. After the cool-down the breaker resets automatically and the next request re-probes the proxy via `/health`. |
 | `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. |
 | `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |
 
diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json
index 4c942a038..d482384ae 100644
--- a/plugins/openclaw/openclaw.plugin.json
+++ b/plugins/openclaw/openclaw.plugin.json
@@ -22,6 +22,18 @@
       "label": "Connect Timeout Seconds",
       "help": "Optional upstream connection timeout for the auto-started local Headroom proxy. Lower values surface network failures sooner."
     },
+    "requestTimeoutMs": {
+      "label": "Compression Request Timeout",
+      "help": "Maximum milliseconds to wait for one compression request before returning the original messages."
+    },
+    "circuitBreakerThreshold": {
+      "label": "Circuit Breaker Threshold",
+      "help": "Consecutive compression failures before temporarily bypassing Headroom."
+    },
+    "circuitBreakerCooldownMs": {
+      "label": "Circuit Breaker Cooldown",
+      "help": "Milliseconds to bypass compression after the circuit breaker opens."
+    },
     "routeCodexViaProxy": {
       "label": "Route OpenAI Codex Via Headroom",
       "help": "When enabled, OpenClaw will use the active Headroom proxy as the in-memory upstream base URL for the built-in openai-codex provider so provider traffic flows through Headroom."
@@ -69,6 +81,21 @@
         "type": "integer",
         "minimum": 1
       },
+      "requestTimeoutMs": {
+        "type": "integer",
+        "minimum": 1,
+        "default": 30000
+      },
+      "circuitBreakerThreshold": {
+        "type": "integer",
+        "minimum": 1,
+        "default": 3
+      },
+      "circuitBreakerCooldownMs": {
+        "type": "integer",
+        "minimum": 1,
+        "default": 60000
+      },
       "routeCodexViaProxy": {
         "type": "boolean",
         "default": true
diff --git a/plugins/openclaw/package.json b/plugins/openclaw/package.json
index f80ea5e00..77f26d5c0 100644
--- a/plugins/openclaw/package.json
+++ b/plugins/openclaw/package.json
@@ -1,6 +1,6 @@
 {
   "name": "headroom-openclaw",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Headroom context compression plugin for OpenClaw — 70-90% token savings with zero LLM calls",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/plugins/openclaw/src/engine.ts b/plugins/openclaw/src/engine.ts
index f07783ba2..0abe0b2db 100644
--- a/plugins/openclaw/src/engine.ts
+++ b/plugins/openclaw/src/engine.ts
@@ -11,8 +11,22 @@ import { compress } from "headroom-ai";
 import { ProxyManager, defaultLogger, type ProxyManagerConfig, type ProxyManagerLogger } from "./proxy-manager.js";
 import { agentToOpenAI, normalizeAgentMessages, openAIToAgent } from "./convert.js";
 
+/** Race a promise against a timeout and always release the timer. */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timerId: ReturnType<typeof setTimeout> | undefined;
+  const timer = new Promise<never>((_, reject) => {
+    timerId = setTimeout(() => reject(new Error(`headroom compress() timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timer]).finally(() => {
+    if (timerId !== undefined) clearTimeout(timerId);
+  });
+}
+
 export interface HeadroomEngineConfig extends ProxyManagerConfig {
   enabled?: boolean;
+  requestTimeoutMs?: number;
+  circuitBreakerThreshold?: number;
+  circuitBreakerCooldownMs?: number;
 }
 
 export class HeadroomContextEngine {
@@ -36,6 +50,7 @@ export class HeadroomContextEngine {
     totalTokensBefore: 0,
     compactions: 0,
   };
+  private circuit = { errors: 0, openUntilMs: 0 };
 
   constructor(config: HeadroomEngineConfig = {}, logger?: ProxyManagerLogger) {
     this.config = config;
@@ -97,19 +112,28 @@ export class HeadroomContextEngine {
       return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };
     }
 
+    if (this.isCircuitOpen()) {
+      this.logger.warn("[headroom] Circuit open — using uncompressed messages");
+      return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };
+    }
+
     try {
       // Convert AgentMessage → OpenAI format
       const openaiMessages = agentToOpenAI(params.messages);
 
       // Compress via proxy — pass tokenBudget so RollingWindow enforces it
-      const result = await compress(openaiMessages, {
-        model: params.model ?? "claude-sonnet-4-5",
-        baseUrl: this.proxyUrl,
-        fallback: true,
-        tokenBudget: params.tokenBudget,
-      } as any);
+      const result = await withTimeout(
+        compress(openaiMessages, {
+          model: params.model ?? "claude-sonnet-4-5",
+          baseUrl: this.proxyUrl,
+          fallback: true,
+          tokenBudget: params.tokenBudget,
+        } as any),
+        this.config.requestTimeoutMs ?? 30_000,
+      );
 
       if (!result.compressed || result.tokensSaved === 0) {
+        this.resetCircuit();
         return {
           messages: normalizeAgentMessages(params.messages),
           estimatedTokens: result.tokensBefore,
@@ -118,6 +142,7 @@ export class HeadroomContextEngine {
 
       // Convert back to AgentMessage format
       const compressedAgentMessages = openAIToAgent(result.messages);
+      this.resetCircuit();
 
       // Track stats
       this.stats.totalCompressions++;
@@ -138,6 +163,7 @@ export class HeadroomContextEngine {
       };
     } catch (error) {
       this.logger.error(`Assemble failed: ${error}`);
+      this.tripCircuit(error);
       // Graceful fallback: return original messages
       return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };
     }
@@ -240,6 +266,30 @@ export class HeadroomContextEngine {
     return this.proxyStartupError;
   }
 
+  private isCircuitOpen(): boolean {
+    const threshold = this.config.circuitBreakerThreshold ?? 3;
+    if (this.circuit.errors < threshold) return false;
+    if (Date.now() < this.circuit.openUntilMs) return true;
+    this.circuit = { errors: 0, openUntilMs: 0 };
+    return false;
+  }
+
+  private tripCircuit(error: unknown): void {
+    this.circuit.errors += 1;
+    const threshold = this.config.circuitBreakerThreshold ?? 3;
+    if (this.circuit.errors < threshold) return;
+    const cooldownMs = this.config.circuitBreakerCooldownMs ?? 60_000;
+    this.circuit.openUntilMs = Date.now() + cooldownMs;
+    this.logger.warn(
+      `[headroom] Circuit breaker opened after ${this.circuit.errors} errors ` +
+        `(last: ${String(error)}); bypassing compression for ${cooldownMs}ms`,
+    );
+  }
+
+  private resetCircuit(): void {
+    this.circuit = { errors: 0, openUntilMs: 0 };
+  }
+
   ensureProxyStarted(): void {
     if (this.config.enabled === false || this.proxyUrl || this.proxyStartupPromise) {
       return;
diff --git a/plugins/openclaw/test/engine.test.ts b/plugins/openclaw/test/engine.test.ts
index e456d72c3..6ef7792b5 100644
--- a/plugins/openclaw/test/engine.test.ts
+++ b/plugins/openclaw/test/engine.test.ts
@@ -24,8 +24,10 @@ vi.mock("../src/proxy-manager.js", () => ({
 }));
 
 import { HeadroomContextEngine } from "../src/engine.js";
+import { compress } from "headroom-ai";
 
 afterEach(() => {
+  vi.mocked(compress).mockReset();
   mocked.start.mockReset();
   mocked.start.mockResolvedValue("http://127.0.0.1:8787");
   mocked.stop.mockClear();
@@ -196,4 +198,56 @@ describe("HeadroomContextEngine proxy startup helpers", () => {
     });
     expect(mocked.start).toHaveBeenCalledTimes(1);
   });
+
+  it("clears the request timeout after successful compression", async () => {
+    vi.useFakeTimers();
+    try {
+      vi.mocked(compress).mockResolvedValue({
+        compressed: false,
+        messages: [{ role: "user", content: "hello" }],
+        tokensBefore: 5,
+        tokensAfter: 5,
+        tokensSaved: 0,
+      });
+
+      const engine = new HeadroomContextEngine({ requestTimeoutMs: 30_000 });
+      (engine as { proxyUrl: string | null }).proxyUrl = "http://127.0.0.1:8787";
+
+      await expect(
+        engine.assemble({
+          sessionId: "session-1",
+          messages: [{ role: "user", content: "hello" }],
+        }),
+      ).resolves.toEqual({
+        messages: [{ role: "user", content: "hello" }],
+        estimatedTokens: 5,
+      });
+
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("opens the circuit after consecutive compression failures", async () => {
+    vi.mocked(compress).mockRejectedValue(new Error("proxy stalled"));
+    const messages = [{ role: "user", content: "hello" }];
+    const engine = new HeadroomContextEngine({
+      circuitBreakerThreshold: 2,
+      circuitBreakerCooldownMs: 60_000,
+    });
+    (engine as { proxyUrl: string | null }).proxyUrl = "http://127.0.0.1:8787";
+
+    await engine.assemble({ sessionId: "session-1", messages });
+    await engine.assemble({ sessionId: "session-1", messages });
+    await expect(engine.assemble({ sessionId: "session-1", messages })).resolves.toEqual({
+      messages,
+      estimatedTokens: 0,
+    });
+
+    expect(compress).toHaveBeenCalledTimes(2);
+    expect(mocked.logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Circuit breaker opened"),
+    );
+  });
 });
diff --git a/plugins/openclaw/test/proxy-manager.test.ts b/plugins/openclaw/test/proxy-manager.test.ts
index 600ce268c..02f7302bc 100644
--- a/plugins/openclaw/test/proxy-manager.test.ts
+++ b/plugins/openclaw/test/proxy-manager.test.ts
@@ -364,7 +364,7 @@ describe("ProxyManager launch internals", () => {
       expect(pathSpec.checkUseShell).toBe(false);
     } else {
       expect(pathSpec.checkCommand).toBe("sh");
-      expect(pathSpec.checkArgs).toEqual(["-lc", "command -v headroom >/dev/null 2>&1"]);
+      expect(pathSpec.checkArgs).toEqual(["-c", "command -v headroom >/dev/null 2>&1"]);
     }
   });
 
diff --git a/plugins/opencode/package-lock.json b/plugins/opencode/package-lock.json
index 700553f65..c9e6afc6d 100644
--- a/plugins/opencode/package-lock.json
+++ b/plugins/opencode/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "headroom-opencode",
-  "version": "0.1.0",
+  "version": "0.32.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "headroom-opencode",
-      "version": "0.1.0",
+      "version": "0.32.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@opencode-ai/plugin": "^1.18.2",
diff --git a/plugins/opencode/package.json b/plugins/opencode/package.json
index 1f84f8aba..355f9f589 100644
--- a/plugins/opencode/package.json
+++ b/plugins/opencode/package.json
@@ -1,6 +1,6 @@
 {
   "name": "headroom-opencode",
-  "version": "0.1.0",
+  "version": "0.35.0",
   "description": "Headroom proxy integration plugin for OpenCode - routes LLM traffic through the Headroom proxy for token compression",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/plugins/opencode/src/hook-shim.ts b/plugins/opencode/src/hook-shim.ts
new file mode 100644
index 000000000..de15cd01d
--- /dev/null
+++ b/plugins/opencode/src/hook-shim.ts
@@ -0,0 +1,26 @@
+// Self-contained Node `--import` loader for the OpenCode transport, built
+// standalone (see tsup.standalone.config.ts) and shipped inside the Python wheel
+// at headroom/providers/opencode/hook-shim/handler.js.
+//
+// transport.ts wraps `fetch`/`http`/`https` in the plugin's own process, but a
+// spawned Node child (an `npx` MCP server, `tokensave serve`, ...) is a fresh
+// process, so its traffic is only routed if this loader runs at that child's
+// startup via NODE_OPTIONS=--import. `shimImportSpecifier()` in transport.ts
+// resolves `../hook-shim/handler.js` next to the loaded entry, which is this
+// file in a wheel install.
+//
+// The checkout uses plugins/opencode/hook-shim/handler.js instead, which imports
+// the non-bundled `../dist/index.js`; pip installs have no node_modules, so this
+// variant inlines the transport. Without it shipped, the loader path did not
+// exist, so child-process routing was silently disabled for wheel installs
+// (before #2806 it crashed every Node child with ERR_MODULE_NOT_FOUND) (#2850).
+import { installHeadroomTransport } from "./transport.js";
+
+const proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;
+if (!proxyUrl) {
+  throw new Error(
+    "Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL",
+  );
+}
+
+installHeadroomTransport({ proxyUrl });
diff --git a/plugins/opencode/tsup.standalone.config.ts b/plugins/opencode/tsup.standalone.config.ts
index 3045a98c3..1391e4024 100644
--- a/plugins/opencode/tsup.standalone.config.ts
+++ b/plugins/opencode/tsup.standalone.config.ts
@@ -6,7 +6,12 @@ import { defineConfig } from "tsup";
 // with node_modules present; pip installs have no node_modules, so this
 // variant bundles every dependency into a single loadable file.
 export default defineConfig({
-  entry: { "entry.opencode": "src/entry.opencode.ts" },
+  // `hook-shim/handler` is the self-contained Node `--import` loader shipped
+  // alongside the entry so spawned Node children route their traffic too (#2850).
+  entry: {
+    "entry.opencode": "src/entry.opencode.ts",
+    "hook-shim/handler": "src/hook-shim.ts",
+  },
   outDir: "dist-standalone",
   format: ["esm"],
   splitting: false,
diff --git a/pyproject.toml b/pyproject.toml
index bb5ea79a3..e36dca4ae 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "headroom-ai"
-version = "0.34.0"
+version = "0.35.0"
 description = "The Context Optimization Layer for LLM Applications - Cut costs by 50-90%"
 readme = "README.md"
 license = "Apache-2.0"
@@ -78,11 +78,17 @@ proxy = [
     "orjson>=3.9.14; platform_python_implementation != 'PyPy'",
     "httpx[http2]>=0.24.0",
     "openai>=2.14.0",             # OpenAI API format support
+    # The server still uses the v1 low-level Server decorator API. Keep this
+    # cap until the SDK 2.x port lands (GH #2658 / regression GH #2977).
     "mcp>=1.28.1,<2.0.0",         # MCP server (headroom_compress, retrieve, stats)
     "magika>=0.6.0",              # ML content detection for ContentRouter
     "zstandard>=0.20.0",          # Decompress zstd request bodies (Codex, etc.)
     "websockets>=13.0",           # WebSocket proxy for /v1/responses (Codex gpt-5.4+)
-    "onnxruntime>=1.16.0",        # Kompress ONNX INT8 text compression (no torch needed)
+    # Rust fastembed enables ORT C API 24. ORT <1.24 deadlocks instead of
+    # returning an initialization error; 1.24+ no longer ships Python 3.10
+    # wheels, so 3.10 keeps Python-only ORT and bypasses native detection.
+    "onnxruntime>=1.24.0; python_version>='3.11'",
+    "onnxruntime>=1.16.0,<1.24.0; python_version<'3.11'",
     "transformers>=5.5.0,<6.0",   # Tokenizer only (for Kompress)
     "watchdog>=4.0.0",            # File watcher for live code graph reindexing (--code-graph)
     "sqlite-vec>=0.1.6",          # Vector index for memory (--memory). Lightweight, no torch.
@@ -232,7 +238,8 @@ mcp = [
 ]
 # Voice filler detection
 voice = [
-    "onnxruntime>=1.16.0",
+    "onnxruntime>=1.24.0; python_version>='3.11'",
+    "onnxruntime>=1.16.0,<1.24.0; python_version<'3.11'",
     "transformers>=5.5.0,<6.0",
     "torch>=2.12.1; sys_platform != 'darwin' or platform_machine != 'x86_64'",
 ]
@@ -270,7 +277,7 @@ dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "pytest-asyncio>=0.21.0",
-    "ruff==0.15.17",
+    "ruff==0.15.22",
     "mypy>=1.0.0",
     "pre-commit>=3.0.0",
     "openai>=1.0.0",
@@ -495,6 +502,7 @@ markers = [
     "slow: slow tests (model loads, large fixtures)",
     "real_llm: tests that hit real LLM APIs; skipped unless explicitly enabled",
     "live: opt-in multi-turn tests that hit real upstream APIs; require provider keys",
+    "proxy_dependency_gate: exercises ensure_proxy_dependencies() without mocking",
 ]
 
 [tool.coverage.run]
diff --git a/run-all-plugins.sh b/run-all-plugins.sh
new file mode 100755
index 000000000..f8b9b2ec9
--- /dev/null
+++ b/run-all-plugins.sh
@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# run-all-plugins.sh — install + configure + run the Headroom proxy with ALL 5
+# enterprise plugins, the coding savings-profile, and ML compression offloaded
+# to the Kompress-v2 Modal endpoint. Then confirm everything loaded.
+#
+#   Plugins : lossless_guard, skill_search, observability, tier_router, tool_search
+#   Extra   : headroom-ai[sandbox]  (torch-free proxy; ML offloaded to Modal)
+#   Profile : coding  (HEADROOM_SAVINGS_PROFILE) + cache mode (prefix-cache safe)
+#
+# Secrets are SOURCED from ~/env.txt and ~/.headroom/plugins.env — never inlined.
+# Re-runnable: install is skipped when already satisfied (FORCE_INSTALL=1 forces).
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+HR=/Users/tcms/demo/headroom
+VENV="$HR/.venv"
+PORT="${HEADROOM_PORT:-8787}"
+ENV_TXT="${ENV_TXT:-$HOME/env.txt}"
+PLUGINS_ENV="$HOME/.headroom/plugins.env"
+LOG="${HEADROOM_LOG:-$HOME/.headroom/logs/proxy-all-plugins.log}"
+mkdir -p "$(dirname "$LOG")"
+
+# ── 1. venv ──────────────────────────────────────────────────────────────────
+# `python`/`pip`/`uv` are broken system-wide on this box — always use the venv,
+# and `python -m pip` (the .venv/bin/pip shim is broken too).
+# shellcheck disable=SC1091
+source "$VENV/bin/activate"
+PY="$VENV/bin/python"
+
+# ── 2. install (guarded) ──────────────────────────────────────────────────────
+# headroom-ai[sandbox] pulls proxy,code,relevance,reports,otel,html,mcp,spreadsheet
+# (all torch-free — heavy ML is offloaded to the Modal Kompress endpoint below).
+# The 5 plugins install --no-deps so pip won't drag PyPI's headroom-ai over the
+# local editable one; headroom-license is their shared Ed25519 verifier.
+need_install=1
+if [ "${FORCE_INSTALL:-0}" != "1" ]; then
+  n=$("$PY" -c 'import opentelemetry; from headroom.proxy.extensions import discover; print(len(list(discover())))' 2>/dev/null || echo 0)
+  [ "$n" = "5" ] && need_install=0
+fi
+if [ "$need_install" = "1" ]; then
+  avail=$(df -g "$HR" 2>/dev/null | awk 'NR==2{print $4}')
+  echo "▶ disk: ${avail:-?}Gi free before install"
+  if [ -n "$avail" ] && [ "$avail" -lt 2 ]; then
+    echo "!! <2Gi free — aborting before heavy install (free space, then re-run)"; exit 1
+  fi
+  echo "▶ installing pip+maturin, then headroom-ai[sandbox] + license + 5 plugins (editable)…"
+  "$PY" -m pip install -U pip maturin
+  # litellm >=1.92 ships an sdist-only Rust bridge whose AWS-SDK crates need rustc>=1.94.1;
+  # the default rustup toolchain here is older (pip builds litellm in a temp dir that misses
+  # the repo's 1.95 pin), so pin to the last pure-Python wheel line (1.91.4). Satisfies
+  # headroom's litellm>=1.86.2,<2.0 and skips the Rust build entirely.
+  "$PY" -m pip install "litellm<1.92"
+  "$PY" -m pip install -e "${HR}[sandbox]" "litellm<1.92"
+  "$PY" -m pip install -e /Users/tcms/demo/headroom-license
+  for p in lossless-guard skill-search observability tier-router tool-search; do
+    "$PY" -m pip install -e "/Users/tcms/demo/headroom-${p}" --no-deps
+  done
+else
+  echo "▶ install satisfied (5 extensions discovered) — skipping (FORCE_INSTALL=1 to force)"
+fi
+
+# ── 3. secrets from ~/env.txt ─────────────────────────────────────────────────
+# Provides: OPENAI_API_KEY, ANTHROPIC_API_KEY, FIREWORKS_API_KEY (upstream creds);
+#           LANGFUSE_{PUBLIC,SECRET}_KEY + LANGFUSE_BASE_URL (observability sink);
+#           HEADROOM_KOMPRESS_ENDPOINT + _TOKEN (Modal ML offload).
+[ -f "$ENV_TXT" ] || { echo "!! $ENV_TXT not found"; exit 1; }
+set -a; # shellcheck disable=SC1090
+source "$ENV_TXT"; set +a
+
+# ── 4. plugin license (Ed25519, offline, wildcard) ────────────────────────────
+# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. This is SEPARATE from the OSS cloud
+# key (HEADROOM_LICENSE_KEY) — the banner will still say "OSS (no license key)",
+# but each plugin prints "license accepted". Fallback: skip verification entirely.
+if [ -f "$PLUGINS_ENV" ]; then
+  set -a; # shellcheck disable=SC1090
+  source "$PLUGINS_ENV"; set +a
+else
+  echo "▶ $PLUGINS_ENV missing — using dev license bypass"
+  export HEADROOM_LICENSE_DEV=1
+fi
+
+# ── 5. Kompress ML offload → Modal ────────────────────────────────────────────
+# Setting HEADROOM_KOMPRESS_ENDPOINT (+_TOKEN) alone routes Kompress inference to
+# the Modal endpoint (content_router._get_kompress_remote). No other flag needed;
+# HEADROOM_COMPRESS_ALLOW_REMOTE is a different thing (remote upstreams, not this).
+: "${HEADROOM_KOMPRESS_ENDPOINT:?must be set in $ENV_TXT}"
+export HEADROOM_KOMPRESS_ENDPOINT_TOKEN="${HEADROOM_KOMPRESS_ENDPOINT_TOKEN:-}"
+
+# ── 6. observability sink → Langfuse + spend attribution ──────────────────────
+# HEADROOM_LANGFUSE_ENABLED must be explicitly truthy (LANGFUSE_* creds come from
+# env.txt). Traces (agent.turn / llm.turn spans with gen_ai.usage.cost) land in
+# Langfuse. Spend is opt-in: HEADROOM_MODEL_PRICES is {model-substr:{in,out}} in
+# USD per 1K tokens. (Per-request identity — org/team/user/session — is supplied
+# by the CLIENT via x-headroom-* headers, not settable here.)
+export HEADROOM_LANGFUSE_ENABLED=1
+export HEADROOM_LANGFUSE_SERVICE_NAME=headroom-proxy
+export HEADROOM_MODEL_PRICES='{"claude-opus":{"in":0.015,"out":0.075},"claude-sonnet":{"in":0.003,"out":0.015},"gpt-5":{"in":0.00125,"out":0.01},"gpt-4":{"in":0.003,"out":0.012}}'
+# Metrics (counters) need a separate OTLP endpoint — none in env.txt, so left off:
+# export HEADROOM_OTEL_METRICS_ENABLED=1 HEADROOM_OTEL_METRICS_ENDPOINT=http://localhost:4318
+
+# ── 7. tier_router ─────────────────────────────────────────────────────────────
+# Only stamps service_tier on the wire (no token delta). OpenAI 'flex' is only
+# auto-selected for models declared eligible here. Anthropic tiers are a no-op by
+# default. Clients force a tier with x-headroom-tier / x-headroom-background: 1.
+export HEADROOM_TIER_FLEX_MODELS="${HEADROOM_TIER_FLEX_MODELS:-gpt-5,gpt-4.1,o4-mini}"
+
+# ── 8. plugin tuning (defaults shown; override as needed) ─────────────────────
+# skill_search fires on Anthropic w/ >=min skills; tool_search on synthetic-tier
+# providers w/ >=min tools; lossless_guard lossy tier is opt-in (kept OFF).
+export HEADROOM_SKILL_SEARCH_MIN_SKILLS="${HEADROOM_SKILL_SEARCH_MIN_SKILLS:-8}"
+export HEADROOM_TOOL_SEARCH_MIN_TOOLS="${HEADROOM_TOOL_SEARCH_MIN_TOOLS:-5}"
+# export HEADROOM_LOSSLESS_GUARD_LOSSY=1   # opt-in irreversible Bash-noise drop
+
+# ── 9. coding profile + mode ───────────────────────────────────────────────────
+# savings_profile=coding tunes the pipeline for coding-agent traffic; cache mode
+# freezes prior turns to preserve the provider prefix-cache (what coding wants).
+export HEADROOM_SAVINGS_PROFILE=coding
+
+# ── 10. run + confirm ──────────────────────────────────────────────────────────
+cleanup() { [ -n "${PROXY_PID:-}" ] && kill "$PROXY_PID" 2>/dev/null || true; }
+trap cleanup INT TERM EXIT
+
+echo "▶ starting proxy on :$PORT  (profile=coding, mode=cache, all 5 extensions)…"
+headroom proxy --port "$PORT" --mode cache --proxy-extension '*' > "$LOG" 2>&1 &
+PROXY_PID=$!
+
+# wait for readiness (no foreground sleep on this harness)
+curl -s --retry 40 --retry-delay 1 --retry-all-errors --max-time 60 \
+  "http://127.0.0.1:$PORT/health" >/dev/null 2>&1 || true
+
+echo
+echo "══════════════════ CONFIRMATION ══════════════════"
+echo "── extensions loaded (from $LOG) ──"
+grep -iE "Extensions:|license accepted|installed \(" "$LOG" | sed 's/^/  /' || true
+
+echo "── Modal Kompress endpoint reachable? ──"
+code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 "$HEADROOM_KOMPRESS_ENDPOINT" || echo "unreachable")
+echo "  $HEADROOM_KOMPRESS_ENDPOINT -> HTTP $code (any response = up; offload runs on real traffic)"
+
+echo "── /stats surfaces (empty until traffic flows) ──"
+curl -s --max-time 5 "http://127.0.0.1:$PORT/stats" | "$PY" -c '
+import sys,json
+d=json.load(sys.stdin)
+print("  extension_savings   :", d.get("extension_savings"))
+print("  by_layer            :", list(d.get("savings",{}).get("by_layer",{})))
+print("  tokens_saved_by_strat:", d.get("tokens_saved_by_strategy"))
+print("  otel.enabled        :", d.get("otel",{}).get("enabled"))
+print("  langfuse.enabled    :", d.get("langfuse",{}).get("enabled"))
+' 2>/dev/null || echo "  (stats not ready)"
+
+cat <<EOF
+
+── where each effect shows up ──
+  lossless_guard  -> dashboard (compression layer)  + /stats.tokens_saved_by_strategy
+  skill_search    -> /stats.extension_savings  (NOT dashboard) — Anthropic client, >=8 skills
+  tool_search     -> /stats.extension_savings  (NOT dashboard) — synthetic-tier client, >=5 tools
+  observability   -> Langfuse UI (spans + gen_ai.usage.cost)   — send x-headroom-org/user/session
+  tier_router     -> service_tier on the wire / provider bill  (no token delta)
+
+── drive traffic (two clients — they exercise different plugins) ──
+  Claude Code : ANTHROPIC_BASE_URL=http://localhost:$PORT claude        # lossless_guard + skill_search
+  OpenAI/opencode: OPENAI_BASE_URL=http://localhost:$PORT/v1 <client>    # tool_search
+  Dashboard   : headroom dashboard   (http://127.0.0.1:$PORT/dashboard)
+  Raw stats   : curl -s localhost:$PORT/stats | python3 -m json.tool
+
+Proxy is running (pid $PROXY_PID). Ctrl-C to stop. Logs: $LOG
+═══════════════════════════════════════════════════
+EOF
+
+wait "$PROXY_PID" || true
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index e8abb7378..b7444fb2a 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -36,6 +36,19 @@ function Ensure-PathEntry {
 function Ensure-ProfileBlock {
     param([string]$PathEntry)
 
+    # $PROFILE is empty when PowerShell cannot resolve the profile path for the
+    # current user (a fresh account with no Documents folder, a service/CI
+    # context, a redirected profile). Split-Path below would then throw
+    # "Cannot bind argument to parameter 'Path' because it is an empty string",
+    # and with $ErrorActionPreference = 'Stop' that aborts the whole installer
+    # AFTER the wrapper and persistent User PATH were already written. Skip the
+    # profile convenience block instead: Ensure-PathEntry has already persisted
+    # the PATH for new sessions.
+    if ([string]::IsNullOrEmpty($PROFILE)) {
+        Write-Info 'Skipping PowerShell profile update: $PROFILE is not set in this environment (PATH was still updated for new sessions).'
+        return
+    }
+
     $markerStart = '# >>> headroom docker-native >>>'
     $markerEnd = '# <<< headroom docker-native <<<'
     $escapedPathEntry = $PathEntry.Replace("'", "''")
@@ -346,6 +359,29 @@ function Get-PersistentDockerArgs {
     return ,$args.ToArray()
 }
 
+function Add-DashboardGatewayEnv {
+    param([System.Collections.Generic.List[string]]$ArgsList)
+
+    # This default is safe only because the published dashboard port is bound
+    # to the host loopback interface below. A host request published through
+    # Docker's default bridge reaches the
+    # container from the bridge gateway (for example, 172.17.0.1), not from
+    # 127.0.0.1. Trust only that exact gateway by default so the dashboard's
+    # metadata gate works for the first-party persistent Docker preset while
+    # preserving an explicitly configured allowlist.
+    if (Test-Path Env:HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS) {
+        return
+    }
+
+    $gateway = (& docker network inspect bridge --format '{{(index .IPAM.Config 0).Gateway}}' 2>$null | Out-String).Trim()
+    if ($LASTEXITCODE -eq 0 -and $gateway) {
+        $ArgsList.Add('--env')
+        $ArgsList.Add("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=$gateway/32")
+    } else {
+        Write-Warning 'Could not determine Docker bridge gateway; dashboard metadata remains restricted'
+    }
+}
+
 function Get-ManifestProxyArgs {
     param(
         [int]$Port,
@@ -492,8 +528,9 @@ function Start-PersistentDockerInstall {
     docker rm -f $containerName | Out-Null 2>$null
 
     $dockerArgs = New-Object System.Collections.Generic.List[string]
-    $dockerArgs.AddRange([string[]]@('run','-d','--restart','unless-stopped','--name',$containerName,'-p',"$Port`:$Port"))
+    $dockerArgs.AddRange([string[]]@('run','-d','--restart','unless-stopped','--name',$containerName,'-p',"127.0.0.1`:$Port`:$Port"))
     $dockerArgs.AddRange((Get-PersistentDockerArgs))
+    Add-DashboardGatewayEnv -ArgsList $dockerArgs
     $dockerArgs.AddRange([string[]]@(
         '--env',"HEADROOM_DEPLOYMENT_PROFILE=$Profile",
         '--env','HEADROOM_DEPLOYMENT_PRESET=persistent-docker',
diff --git a/scripts/install.sh b/scripts/install.sh
index cfd2259df..d65a6db59 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -292,6 +292,29 @@ append_persistent_container_args() {
   append_passthrough_envs "$1"
 }
 
+append_dashboard_gateway_env() {
+  local -n ref=$1
+
+  # This default is safe only because the published dashboard port is bound
+  # to the host loopback interface below. A host request published through
+  # Docker's default bridge reaches the
+  # container from the bridge gateway (for example, 172.17.0.1), not from
+  # 127.0.0.1. Trust only that exact gateway by default so the dashboard's
+  # metadata gate works for the first-party persistent Docker preset while
+  # preserving an explicitly configured allowlist.
+  if [[ -n "${HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS+x}" ]]; then
+    return
+  fi
+
+  local gateway
+  gateway="$(docker network inspect bridge --format '{{(index .IPAM.Config 0).Gateway}}' 2>/dev/null || true)"
+  if [[ -n "${gateway}" ]]; then
+    ref+=(--env "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=${gateway}/32")
+  else
+    warn "Could not determine Docker bridge gateway; dashboard metadata remains restricted"
+  fi
+}
+
 build_manifest_proxy_args() {
   local -n out_args=$1
   local port="$2"
@@ -466,8 +489,9 @@ start_persistent_docker_install() {
 
   docker rm -f "${container_name}" >/dev/null 2>&1 || true
 
-  args=(docker run -d --restart unless-stopped --name "${container_name}" -p "${port}:${port}")
+  args=(docker run -d --restart unless-stopped --name "${container_name}" -p "127.0.0.1:${port}:${port}")
   append_persistent_container_args args
+  append_dashboard_gateway_env args
   args+=(
     --env "HEADROOM_DEPLOYMENT_PROFILE=${profile}"
     --env "HEADROOM_DEPLOYMENT_PRESET=persistent-docker"
diff --git a/scripts/pr-governance.py b/scripts/pr-governance.py
index cfda86b3a..8c5165e39 100644
--- a/scripts/pr-governance.py
+++ b/scripts/pr-governance.py
@@ -22,6 +22,7 @@ REQUIRED_SECTIONS = (
     "Changes Made",
     "Testing",
     "Real Behavior Proof",
+    "Runtime Rollout Safety",
     "Review Readiness",
 )
 PROOF_FIELDS = (
@@ -30,6 +31,15 @@ PROOF_FIELDS = (
     "Observed result",
     "Not tested",
 )
+ROLLOUT_FIELDS = (
+    "Rollout-managed feature(s)",
+    "Minimum rollout channel",
+    "Stable/default behavior changed",
+    "Kill switch / disable path",
+    "Unsafe override required",
+    "Qualification impact",
+    "Rollback path",
+)
 
 SECTION_RE = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
 CHECKBOX_RE = re.compile(r"^- \[(?P<checked>[ xX])\] (?P<label>.+)$", re.MULTILINE)
@@ -193,6 +203,12 @@ def validate_pull_request(event: dict[str, Any]) -> GovernanceReport:
         if proof_section and not proof_values.get(field_name):
             problems.append(f"Fill in `Real Behavior Proof` → `{field_name}`.")
 
+    rollout_section = sections.get("Runtime Rollout Safety", "")
+    rollout_values = proof_field_values(rollout_section)
+    for field_name in ROLLOUT_FIELDS:
+        if rollout_section and not rollout_values.get(field_name):
+            problems.append(f"Fill in `Runtime Rollout Safety` → `{field_name}`.")
+
     readiness_checked = normalize_checkbox_map(checked_items(sections.get("Review Readiness", "")))
     has_self_review = "i have performed a self-review" in readiness_checked
     has_ready_checkbox = "this pr is ready for human review" in readiness_checked
diff --git a/scripts/tests/test_pr_governance.py b/scripts/tests/test_pr_governance.py
index 810edd0e3..b3505959a 100644
--- a/scripts/tests/test_pr_governance.py
+++ b/scripts/tests/test_pr_governance.py
@@ -64,6 +64,16 @@ pytest scripts/tests/test_pr_governance.py -q
 - Observed result: The governance check fails and the PR gets a needs-author-action label.
 - Not tested: Automatic Copilot review rulesets in repository settings.
 
+## Runtime Rollout Safety
+
+- Rollout-managed feature(s): None.
+- Minimum rollout channel: Stable.
+- Stable/default behavior changed: No.
+- Kill switch / disable path: Not applicable.
+- Unsafe override required: No.
+- Qualification impact: None.
+- Rollback path: Revert the workflow and script changes.
+
 ## Review Readiness
 
 - [x] I have performed a self-review
@@ -186,6 +196,16 @@ Fixes #123
 - Observed result:
 - Not tested:
 
+## Runtime Rollout Safety
+
+- Rollout-managed feature(s):
+- Minimum rollout channel:
+- Stable/default behavior changed:
+- Kill switch / disable path:
+- Unsafe override required:
+- Qualification impact:
+- Rollback path:
+
 ## Review Readiness
 
 - [ ] I have performed a self-review
@@ -201,6 +221,7 @@ Fixes #123
     assert any("Type of Change" in problem for problem in report.problems)
     assert any("Test Output" in problem for problem in report.problems)
     assert any("Real Behavior Proof" in problem for problem in report.problems)
+    assert any("Runtime Rollout Safety" in problem for problem in report.problems)
 
 
 def test_validate_pull_request_skips_bot_authored_prs() -> None:
diff --git a/scripts/tests/test_version_sync.py b/scripts/tests/test_version_sync.py
index c25c72e07..5d6225edc 100644
--- a/scripts/tests/test_version_sync.py
+++ b/scripts/tests/test_version_sync.py
@@ -22,6 +22,8 @@ def temp_project(tmp_path: Path) -> dict[str, Path]:
     plugins = root / "plugins"
     openclaw = plugins / "openclaw"
     openclaw.mkdir(parents=True)
+    opencode = plugins / "opencode"
+    opencode.mkdir(parents=True)
     agent_hooks_claude = plugins / "headroom-agent-hooks" / ".claude-plugin"
     agent_hooks_claude.mkdir(parents=True)
     agent_hooks_github = plugins / "headroom-agent-hooks" / ".github" / "plugin"
@@ -50,6 +52,17 @@ def temp_project(tmp_path: Path) -> dict[str, Path]:
         )
     )
 
+    opencode_pkg = opencode / "package.json"
+    opencode_pkg.write_text(
+        json.dumps(
+            {
+                "name": "test-opencode",
+                "version": "0.5.25",
+                "dependencies": {"headroom-ai": "^0.22.3"},
+            }
+        )
+    )
+
     repo_claude_marketplace = repo_claude_plugin / "marketplace.json"
     repo_claude_marketplace.write_text(
         json.dumps(
@@ -99,6 +112,7 @@ def temp_project(tmp_path: Path) -> dict[str, Path]:
         "pyproject": pyproject,
         "version_py": version_py,
         "openclaw_pkg": openclaw_pkg,
+        "opencode_pkg": opencode_pkg,
         "repo_claude_marketplace": repo_claude_marketplace,
         "repo_github_marketplace": repo_github_marketplace,
         "claude_plugin": claude_plugin,
@@ -134,6 +148,10 @@ def test_version_sync_explicit_version(temp_project: dict[str, Path]) -> None:
     assert openclaw_pkg["version"] == "0.7.0"
     assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
 
+    opencode_pkg = json.loads(temp_project["opencode_pkg"].read_text())
+    assert opencode_pkg["version"] == "0.7.0"
+    assert opencode_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
+
     # Verify sdk/typescript/package.json
     typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
     assert typescript_pkg["version"] == "0.7.0"
@@ -160,6 +178,7 @@ def test_version_sync_explicit_version(temp_project: dict[str, Path]) -> None:
     assert metadata["packages"]["pypi"] == "0.7.0"
     assert metadata["packages"]["npm-sdk"] == "0.7.0"
     assert metadata["packages"]["npm-openclaw"] == "0.7.0"
+    assert metadata["packages"]["npm-opencode"] == "0.7.0"
     assert metadata["packages"]["agent-hooks-plugin"] == "0.7.0"
 
 
@@ -187,6 +206,10 @@ def test_bump_patch(temp_project: dict[str, Path]) -> None:
     assert openclaw_pkg["version"] == "0.5.26"
     assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
 
+    opencode_pkg = json.loads(temp_project["opencode_pkg"].read_text())
+    assert opencode_pkg["version"] == "0.5.26"
+    assert opencode_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
+
     typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
     assert typescript_pkg["version"] == "0.5.26"
 
@@ -218,6 +241,10 @@ def test_bump_minor(temp_project: dict[str, Path]) -> None:
     assert openclaw_pkg["version"] == "0.6.0"
     assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
 
+    opencode_pkg = json.loads(temp_project["opencode_pkg"].read_text())
+    assert opencode_pkg["version"] == "0.6.0"
+    assert opencode_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
+
     typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
     assert typescript_pkg["version"] == "0.6.0"
 
@@ -249,6 +276,10 @@ def test_bump_major(temp_project: dict[str, Path]) -> None:
     assert openclaw_pkg["version"] == "1.0.0"
     assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
 
+    opencode_pkg = json.loads(temp_project["opencode_pkg"].read_text())
+    assert opencode_pkg["version"] == "1.0.0"
+    assert opencode_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
+
     typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
     assert typescript_pkg["version"] == "1.0.0"
 
@@ -279,6 +310,7 @@ def test_release_metadata_written(temp_project: dict[str, Path]) -> None:
             "pypi": "0.6.0",
             "npm-sdk": "0.6.0",
             "npm-openclaw": "0.6.0",
+            "npm-opencode": "0.6.0",
             "agent-hooks-plugin": "0.6.0",
         },
     }
@@ -309,6 +341,7 @@ def test_plugin_manifests_only_leaves_package_versions_unchanged(
     assert 'version = "0.5.25"' in temp_project["pyproject"].read_text()
     assert '__version__ = "0.5.25"' in temp_project["version_py"].read_text()
     assert json.loads(temp_project["openclaw_pkg"].read_text())["version"] == "0.5.25"
+    assert json.loads(temp_project["opencode_pkg"].read_text())["version"] == "0.5.25"
     assert json.loads(temp_project["typescript_pkg"].read_text())["version"] == "0.5.25"
     assert json.loads(temp_project["claude_plugin"].read_text())["version"] == "0.8.0"
     assert (
@@ -362,3 +395,22 @@ def test_server_json_version_is_synchronized(temp_project: dict[str, Path]) -> N
     # Untouched keys must survive so the file still matches the builder's output.
     assert server_json["name"] == "io.github.headroomlabs-ai/headroom"
     assert server_json["packages"][0]["registryType"] == "pypi"
+
+
+def test_opencode_headroom_dependency_is_preserved_for_registry_installability(
+    temp_project: dict[str, Path],
+) -> None:
+    """Source package stays installable even when the next SDK is not on npm yet."""
+    root = temp_project["root"]
+    script = Path(__file__).parent.parent / "version-sync.py"
+
+    result = subprocess.run(
+        [sys.executable, str(script), "--root", str(root), "--version", "0.28.0"],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, f"Script failed: {result.stderr}"
+    opencode_pkg = json.loads(temp_project["opencode_pkg"].read_text())
+    assert opencode_pkg["version"] == "0.28.0"
+    assert opencode_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
diff --git a/scripts/verify-versions.py b/scripts/verify-versions.py
index 5e7e92987..57d4a1f8a 100644
--- a/scripts/verify-versions.py
+++ b/scripts/verify-versions.py
@@ -40,6 +40,7 @@ def main() -> None:
     versions = {
         "pyproject.toml": py_ver,
         "plugins/openclaw/package.json": _read_json_version(ROOT / "plugins/openclaw/package.json"),
+        "plugins/opencode/package.json": _read_json_version(ROOT / "plugins/opencode/package.json"),
         "sdk/typescript/package.json": _read_json_version(ROOT / "sdk/typescript/package.json"),
         "plugins/headroom-agent-hooks/.claude-plugin/plugin.json": _read_json_version(
             ROOT / "plugins/headroom-agent-hooks/.claude-plugin/plugin.json"
diff --git a/scripts/version-sync.py b/scripts/version-sync.py
index c4bcdf81c..76309fcef 100644
--- a/scripts/version-sync.py
+++ b/scripts/version-sync.py
@@ -124,6 +124,21 @@ def update_openclaw_package_json(file_path: Path, version: str) -> None:
         f.write("\n")
 
 
+def update_opencode_package_json(file_path: Path, version: str) -> None:
+    """Update opencode package.json version.
+
+    Keep the source `headroom-ai` dependency registry-installable. The release
+    workflow rewrites the packed dependency to the exact release range right
+    before npm publication.
+    """
+    with open(file_path, encoding="utf-8") as f:
+        data = json.load(f)
+    data["version"] = version
+    with open(file_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
 def update_pyproject_version(root: Path, version: str) -> None:
     """Update pyproject.toml version."""
     pyproject_path = root / "pyproject.toml"
@@ -145,6 +160,7 @@ def write_release_metadata(root: Path, version: str) -> None:
             "pypi": version,
             "npm-sdk": version,
             "npm-openclaw": version,
+            "npm-opencode": version,
             "agent-hooks-plugin": version,
         },
     }
@@ -192,6 +208,7 @@ def main() -> None:
     # Update all versioned files
     update_pyproject_version(args.root, version)
     update_openclaw_package_json(args.root / "plugins" / "openclaw" / "package.json", version)
+    update_opencode_package_json(args.root / "plugins" / "opencode" / "package.json", version)
     update_package_json(args.root / "sdk" / "typescript" / "package.json", version)
     update_plugin_versions(args.root, version)
     update_server_json(args.root / "server.json", version)
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 73b4931e7..5671d07cc 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "headroom-ai",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Compress LLM context. Save tokens. Fit more into every request.",
   "type": "module",
   "main": "./dist/index.cjs",
diff --git a/server.json b/server.json
index e95ade50f..8292acb0f 100644
--- a/server.json
+++ b/server.json
@@ -9,13 +9,13 @@
     "source": "github",
     "id": "1129940957"
   },
-  "version": "0.34.0",
+  "version": "0.35.0",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "headroom-ai",
-      "version": "0.34.0",
+      "version": "0.35.0",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {
diff --git a/tests/_gemini_live.py b/tests/_gemini_live.py
new file mode 100644
index 000000000..482814917
--- /dev/null
+++ b/tests/_gemini_live.py
@@ -0,0 +1,24 @@
+"""Helpers for optional live Gemini tests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+GEMINI_QUOTA_STATUS = 429
+_GEMINI_QUOTA_MARKERS = (
+    "quota",
+    "rate limit",
+    "rate-limit",
+    "too many requests",
+)
+
+
+def skip_if_gemini_quota_exhausted(response: Any) -> None:
+    """Skip live Gemini tests when the configured key has no available quota."""
+    if getattr(response, "status_code", None) != GEMINI_QUOTA_STATUS:
+        return
+    body = getattr(response, "text", "") or ""
+    if any(marker in body.lower() for marker in _GEMINI_QUOTA_MARKERS):
+        pytest.skip("Gemini live API quota/rate limit exhausted")
diff --git a/tests/conftest.py b/tests/conftest.py
index 2aecdbc4a..9b202b6cb 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -22,6 +22,22 @@ from tests._skip_helpers import external_model_skip_reason
 # those up inside CliRunner, so assertions would see the developer's proxy
 # config instead of the test's. Scrub them so local runs match CI; tests
 # that need a value set it explicitly via monkeypatch or CliRunner env.
+@pytest.fixture(autouse=True)
+def _skip_proxy_dependency_gate_unless_exercised(
+    request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Most CLI tests run without headroom-ai[proxy] extras installed."""
+    if request.node.get_closest_marker("proxy_dependency_gate") is not None:
+        return
+    try:
+        from headroom.cli import proxy
+    except ModuleNotFoundError:
+        # Native-wrapper jobs intentionally install only pytest and exercise the
+        # installer scripts without importing Headroom's runtime dependencies.
+        return
+    monkeypatch.setattr(proxy, "ensure_proxy_dependencies", lambda: None)
+
+
 @pytest.fixture(autouse=True)
 def _scrub_developer_headroom_env(monkeypatch):
     for key in list(os.environ):
@@ -91,6 +107,29 @@ def _reset_copilot_routing_flag():
     reset_request_routed_to_copilot()
 
 
+# `savings_tracker._resolve_litellm_model` is an `lru_cache`d, module-global,
+# process-lifetime cache keyed by model name (bounded — see #2860). Many test
+# files monkeypatch `savings_tracker.litellm` to a fake with different
+# `model_cost`/`cost_per_token` behavior per test, but reuse common model
+# names like "gpt-4o" across them. Without a reset, whichever test resolves
+# "gpt-4o" first "wins" the cache entry for the rest of the run, and later
+# tests silently stop exercising their own fake — a real-not-hypothetical
+# order-dependence bug once the cache is process-lifetime instead of per-call.
+# Clear before AND after so a test's own within-test resolutions never leak
+# in from, or leak out to, a neighboring test either.
+@pytest.fixture(autouse=True)
+def _reset_litellm_model_resolution_cache():
+    try:
+        from headroom.proxy.savings_tracker import _resolve_litellm_model
+    except ModuleNotFoundError:
+        yield
+        return
+
+    _resolve_litellm_model.cache_clear()
+    yield
+    _resolve_litellm_model.cache_clear()
+
+
 # =============================================================================
 # Global test hooks
 # =============================================================================
diff --git a/tests/fixtures/rollout_policy_vectors.json b/tests/fixtures/rollout_policy_vectors.json
new file mode 100644
index 000000000..e8ab18789
--- /dev/null
+++ b/tests/fixtures/rollout_policy_vectors.json
@@ -0,0 +1,8 @@
+[
+  {"channel":"stable","requested":false,"disabled":false,"unsafe":false,"enabled":false,"decision":"not_requested"},
+  {"channel":"stable","requested":true,"disabled":false,"unsafe":false,"enabled":false,"decision":"blocked_by_channel"},
+  {"channel":"canary","requested":true,"disabled":false,"unsafe":false,"enabled":true,"decision":"explicit"},
+  {"channel":"stable","requested":true,"disabled":false,"unsafe":true,"enabled":true,"decision":"unsafe_override"},
+  {"channel":"stable","requested":true,"disabled":true,"unsafe":true,"enabled":false,"decision":"disabled"},
+  {"channel":"dev","requested":false,"disabled":false,"unsafe":false,"enabled":false,"decision":"not_requested"}
+]
diff --git a/tests/test_adaptive_sizer.py b/tests/test_adaptive_sizer.py
index f20746d56..f9ae55c6d 100644
--- a/tests/test_adaptive_sizer.py
+++ b/tests/test_adaptive_sizer.py
@@ -107,6 +107,18 @@ class TestSmallArrays:
         items = _make_unique_items(8)
         assert compute_optimal_k(items) == 8
 
+    def test_small_array_respects_max_k(self):
+        """A small array (n <= 8) must still honor a tight ``max_k`` cap.
+
+        ``max_k`` is documented as "never return more than this"; the fast path
+        used to return the raw ``n`` and blow past a small cap.
+        """
+        items = _make_unique_items(8)
+        assert compute_optimal_k(items, max_k=5) == 5
+        assert compute_optimal_k(items, max_k=3) == 3
+        # A cap >= n leaves the array unchanged.
+        assert compute_optimal_k(items, max_k=20) == 8
+
 
 class TestNearTotalRedundancy:
     def test_identical_items_returns_min(self):
diff --git a/tests/test_anthropic_stage_timings.py b/tests/test_anthropic_stage_timings.py
index 93b3e1944..db8a2d3a1 100644
--- a/tests/test_anthropic_stage_timings.py
+++ b/tests/test_anthropic_stage_timings.py
@@ -101,18 +101,24 @@ class _DummyAnthropicHandler(AnthropicHandlerMixin):
                 get_last_original_messages=lambda: [],
                 get_last_forwarded_messages=lambda: [],
                 record_request=lambda *a, **k: None,
+                update_from_response=lambda *a, **k: None,
             ),
             resolve_tracker=lambda *a, **k: SimpleNamespace(
+                _cached_token_count=0,
                 get_frozen_message_count=lambda: 0,
                 get_last_original_messages=lambda: [],
                 get_last_forwarded_messages=lambda: [],
                 record_request=lambda *a, **k: None,
+                update_from_response=lambda *a, **k: None,
             ),
         )
 
     async def _next_request_id(self) -> str:
         return "req-anth-test"
 
+    async def _record_request_outcome(self, outcome) -> None:
+        return None
+
     def _extract_tags(self, headers):
         return {}
 
@@ -287,6 +293,132 @@ def test_anthropic_no_optimize_preserves_client_tool_order():
     assert [tool["name"] for tool in forwarded_body["tools"]] == ["Read", "Bash"]
 
 
+def test_anthropic_third_party_upstream_strips_tool_search_tools():
+    tools = [
+        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
+        {
+            "name": "Bash",
+            "description": "run a command",
+            "input_schema": {"type": "object", "properties": {}},
+        },
+        {"type": "web_search_20250305", "name": "web_search"},
+    ]
+    request = _build_request(
+        {
+            "model": "claude-3-5-sonnet-latest",
+            "max_tokens": 100,
+            "messages": [{"role": "user", "content": "use a tool"}],
+            "tools": tools,
+        },
+        {"authorization": "Bearer sk-ant-api-test"},
+    )
+    handler = _DummyAnthropicHandler()
+
+    import headroom.tokenizers as _tk
+
+    orig_get = _tk.get_tokenizer
+    _tk.get_tokenizer = lambda model: _DummyTokenizer()
+    try:
+        response = anyio.run(
+            handler.handle_anthropic_messages,
+            request,
+            "https://api.deepseek.com/anthropic",
+        )
+    finally:
+        _tk.get_tokenizer = orig_get
+
+    assert response.status_code == 200
+    _, forwarded_url, _, forwarded_body = handler.captured
+    assert forwarded_url == "https://api.deepseek.com/anthropic/v1/messages"
+    assert forwarded_body["tools"] == [tools[1], tools[2]]
+    assert not any(
+        str(tool.get("type", "")).startswith("tool_search_tool_")
+        for tool in forwarded_body["tools"]
+    )
+
+
+def test_anthropic_direct_path_repairs_typeless_tool_search_regression():
+    """Do not double-inject a typeless search tool; heal its stale history."""
+    tools = [
+        {
+            "name": f"mcp_tool_{index}",
+            "description": f"tool {index}",
+            "input_schema": {"type": "object", "properties": {}},
+        }
+        for index in range(20)
+    ]
+    tools.append(
+        {
+            "name": "tool_search_tool_regex",
+            "description": "client-provided tool search",
+            "input_schema": {"type": "object", "properties": {}},
+        }
+    )
+    messages = [
+        {"role": "user", "content": "search for a tool"},
+        {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "server_tool_use",
+                    "id": "srvtoolu_regex",
+                    "name": "tool_search_tool_regex",
+                    "input": {"pattern": "regex"},
+                },
+                {
+                    "type": "tool_search_tool_result",
+                    "tool_use_id": "srvtoolu_regex",
+                    "content": {
+                        "type": "tool_search_tool_search_result",
+                        "tool_references": [
+                            {
+                                "type": "tool_reference",
+                                "tool_name": "tool_search_tool_regex",
+                            }
+                        ],
+                    },
+                },
+            ],
+        },
+        {"role": "user", "content": "continue"},
+    ]
+    request = _build_request(
+        {
+            "model": "claude-sonnet-4-6",
+            "max_tokens": 100,
+            "messages": messages,
+            "tools": tools,
+        },
+        {"authorization": "Bearer sk-ant-api-test"},
+    )
+    handler = _DummyAnthropicHandler()
+
+    import headroom.tokenizers as _tk
+
+    orig_get = _tk.get_tokenizer
+    _tk.get_tokenizer = lambda model: _DummyTokenizer()
+    try:
+        response = anyio.run(handler.handle_anthropic_messages, request)
+    finally:
+        _tk.get_tokenizer = orig_get
+
+    assert response.status_code == 200
+    _, _, _, forwarded_body = handler.captured
+    # The client-owned typeless entry suppresses Headroom's typed search-tool
+    # injection, and the tools array remains byte-for-byte equivalent.
+    assert forwarded_body["tools"] == tools
+    assert not any(tool.get("type") for tool in forwarded_body["tools"])
+    # The stale server-side round trip is removed before Anthropic validates it.
+    block_types = [
+        block.get("type")
+        for message in forwarded_body["messages"]
+        for block in message.get("content", [])
+        if isinstance(message.get("content"), list) and isinstance(block, dict)
+    ]
+    assert "server_tool_use" not in block_types
+    assert "tool_search_tool_result" not in block_types
+
+
 def test_anthropic_http_invalid_body_still_emits_stage_timings(stage_log_capture):
     async def receive():
         # Invalid JSON — produces ``ValueError`` from ``_read_request_json``.
diff --git a/tests/test_backend_anyllm.py b/tests/test_backend_anyllm.py
index 3d56fcb0a..7ecc933cd 100644
--- a/tests/test_backend_anyllm.py
+++ b/tests/test_backend_anyllm.py
@@ -293,6 +293,81 @@ async def test_send_message_builds_anthropic_response(monkeypatch: pytest.Monkey
     assert instance.calls[0]["stop"] == ["END"]
 
 
+@pytest.mark.asyncio
+async def test_send_message_converts_anthropic_tools_and_tool_choice(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Anthropic tools/tool_choice must reach any-llm in the OpenAI shape.
+
+    any-llm speaks OpenAI; forwarding the raw Anthropic ``input_schema`` tool and
+    the ``{"type": ...}`` tool_choice makes the provider ignore or reject them,
+    so the model never calls a tool. Regression for tool use silently not
+    working on the any-llm backend.
+    """
+    backend, instance = make_backend(monkeypatch)
+    instance.response = make_response(make_choice("ok", "stop"))
+
+    await backend.send_message(
+        {
+            "model": "claude",
+            "messages": [{"role": "user", "content": "hi"}],
+            "tools": [
+                {
+                    "name": "get_weather",
+                    "description": "look up weather",
+                    "input_schema": {
+                        "type": "object",
+                        "properties": {"city": {"type": "string"}},
+                    },
+                }
+            ],
+            "tool_choice": {"type": "any"},
+        },
+        {},
+    )
+
+    sent = instance.calls[0]
+    assert sent["tools"] == [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_weather",
+                "description": "look up weather",
+                "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
+            },
+        }
+    ]
+    assert sent["tool_choice"] == "required"
+
+
+@pytest.mark.asyncio
+async def test_stream_message_converts_anthropic_tools_and_tool_choice(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The streaming request path converts tools/tool_choice the same way."""
+    backend, instance = make_backend(monkeypatch)
+    instance.response = FakeAsyncStream([])
+
+    _events = [
+        event
+        async for event in backend.stream_message(
+            {
+                "model": "claude",
+                "messages": [],
+                "tools": [{"name": "t", "input_schema": {"type": "object"}}],
+                "tool_choice": {"type": "tool", "name": "t"},
+            },
+            {},
+        )
+    ]
+
+    sent = instance.calls[0]
+    assert sent["tools"] == [
+        {"type": "function", "function": {"name": "t", "parameters": {"type": "object"}}}
+    ]
+    assert sent["tool_choice"] == {"type": "function", "function": {"name": "t"}}
+
+
 @pytest.mark.asyncio
 async def test_send_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:
     backend, instance = make_backend(monkeypatch)
@@ -344,6 +419,173 @@ async def test_stream_message_yields_events_and_error(monkeypatch: pytest.Monkey
     assert error_events[-1].data["error"]["message"] == "stream broke"
 
 
+def _tool_call_delta(*, index, tc_id=None, name=None, arguments=None):  # noqa: ANN001, ANN202
+    """Build an OpenAI-style streaming tool_call delta chunk."""
+    func = SimpleNamespace(name=name, arguments=arguments)
+    tc = SimpleNamespace(index=index, id=tc_id, function=func)
+    return SimpleNamespace(
+        choices=[SimpleNamespace(delta=SimpleNamespace(tool_calls=[tc]), finish_reason=None)]
+    )
+
+
+@pytest.mark.asyncio
+async def test_stream_message_emits_tool_use_blocks(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A tool call streamed over any-llm must surface as an Anthropic tool_use block.
+
+    Regression: the streamer only handled text deltas, so ``tools`` were
+    forwarded upstream but any tool call the model streamed back was dropped and
+    the client saw an empty turn with stop_reason=end_turn. The block must open,
+    stream its arguments as input_json_delta, and the turn must end tool_use.
+    """
+    backend, instance = make_backend(monkeypatch)
+    instance.response = FakeAsyncStream(
+        [
+            _tool_call_delta(index=0, tc_id="call_abc", name="get_weather"),
+            _tool_call_delta(index=0, arguments='{"city":'),
+            _tool_call_delta(index=0, arguments='"paris"}'),
+            SimpleNamespace(
+                choices=[SimpleNamespace(delta=SimpleNamespace(), finish_reason="tool_calls")]
+            ),
+        ]
+    )
+
+    events = [
+        event async for event in backend.stream_message({"model": "claude", "messages": []}, {})
+    ]
+    types = [e.event_type for e in events]
+
+    # The tool call is buffered and flushed as one complete block: start, a
+    # single input_json_delta with the reassembled arguments, then stop.
+    assert types == [
+        "message_start",
+        "content_block_start",
+        "content_block_delta",
+        "content_block_stop",
+        "message_delta",
+        "message_stop",
+    ]
+
+    start = next(e for e in events if e.event_type == "content_block_start")
+    assert start.data["content_block"]["type"] == "tool_use"
+    assert start.data["content_block"]["id"] == "call_abc"
+    assert start.data["content_block"]["name"] == "get_weather"
+
+    arg_deltas = [e for e in events if e.event_type == "content_block_delta"]
+    assert [d.data["delta"]["type"] for d in arg_deltas] == ["input_json_delta"]
+    joined = "".join(d.data["delta"]["partial_json"] for d in arg_deltas)
+    assert joined == '{"city":"paris"}'
+
+    message_delta = next(e for e in events if e.event_type == "message_delta")
+    assert message_delta.data["delta"]["stop_reason"] == "tool_use"
+
+
+@pytest.mark.asyncio
+async def test_stream_message_handles_parallel_tool_calls(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Interleaved parallel tool calls must produce valid, disjoint Anthropic blocks.
+
+    OpenAI can introduce two tool indices in one chunk and then stream argument
+    fragments for each across later chunks. Each Anthropic tool_use block must be
+    fully framed (exactly one start and stop, arguments reassembled) with no
+    delta emitted after that block's stop.
+    """
+    backend, instance = make_backend(monkeypatch)
+    instance.response = FakeAsyncStream(
+        [
+            # One chunk introduces BOTH tool indices at once.
+            SimpleNamespace(
+                choices=[
+                    SimpleNamespace(
+                        delta=SimpleNamespace(
+                            tool_calls=[
+                                SimpleNamespace(
+                                    index=0,
+                                    id="call_0",
+                                    function=SimpleNamespace(name="alpha", arguments='{"a":'),
+                                ),
+                                SimpleNamespace(
+                                    index=1,
+                                    id="call_1",
+                                    function=SimpleNamespace(name="beta", arguments='{"b":'),
+                                ),
+                            ]
+                        ),
+                        finish_reason=None,
+                    )
+                ]
+            ),
+            # Interleaved argument fragments: index 0, then index 1.
+            _tool_call_delta(index=0, arguments="1}"),
+            _tool_call_delta(index=1, arguments="2}"),
+            SimpleNamespace(
+                choices=[SimpleNamespace(delta=SimpleNamespace(), finish_reason="tool_calls")]
+            ),
+        ]
+    )
+
+    events = [
+        event async for event in backend.stream_message({"model": "claude", "messages": []}, {})
+    ]
+
+    # Each tool block index must have exactly one start and one stop, and no
+    # delta may appear after that index's stop.
+    stopped: set[int] = set()
+    starts: dict[int, int] = {}
+    stops: dict[int, int] = {}
+    args: dict[int, str] = {}
+    for e in events:
+        if e.event_type == "content_block_start":
+            idx = e.data["index"]
+            starts[idx] = starts.get(idx, 0) + 1
+            assert e.data["content_block"]["type"] == "tool_use"
+        elif e.event_type == "content_block_delta":
+            idx = e.data["index"]
+            assert idx not in stopped, f"delta for block {idx} after its stop"
+            args[idx] = args.get(idx, "") + e.data["delta"]["partial_json"]
+        elif e.event_type == "content_block_stop":
+            idx = e.data["index"]
+            stops[idx] = stops.get(idx, 0) + 1
+            stopped.add(idx)
+
+    assert starts == {0: 1, 1: 1}
+    assert stops == {0: 1, 1: 1}
+    assert args == {0: '{"a":1}', 1: '{"b":2}'}
+
+    block0 = next(
+        e for e in events if e.event_type == "content_block_start" and e.data["index"] == 0
+    )
+    block1 = next(
+        e for e in events if e.event_type == "content_block_start" and e.data["index"] == 1
+    )
+    assert block0.data["content_block"]["name"] == "alpha"
+    assert block0.data["content_block"]["id"] == "call_0"
+    assert block1.data["content_block"]["name"] == "beta"
+    assert block1.data["content_block"]["id"] == "call_1"
+
+
+@pytest.mark.asyncio
+async def test_stream_message_maps_length_finish_reason(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A truncated (length) text stream must report stop_reason=max_tokens."""
+    backend, instance = make_backend(monkeypatch)
+    instance.response = FakeAsyncStream(
+        [
+            SimpleNamespace(
+                choices=[SimpleNamespace(delta=SimpleNamespace(content="hi"), finish_reason=None)]
+            ),
+            SimpleNamespace(
+                choices=[SimpleNamespace(delta=SimpleNamespace(), finish_reason="length")]
+            ),
+        ]
+    )
+
+    events = [
+        event async for event in backend.stream_message({"model": "claude", "messages": []}, {})
+    ]
+    message_delta = next(e for e in events if e.event_type == "message_delta")
+    assert message_delta.data["delta"]["stop_reason"] == "max_tokens"
+
+
 @pytest.mark.asyncio
 async def test_send_openai_message_maps_choices_and_tool_calls(
     monkeypatch: pytest.MonkeyPatch,
diff --git a/tests/test_backend_nonstreaming_cache_metrics.py b/tests/test_backend_nonstreaming_cache_metrics.py
index 9dbbb6c77..6eb87e44d 100644
--- a/tests/test_backend_nonstreaming_cache_metrics.py
+++ b/tests/test_backend_nonstreaming_cache_metrics.py
@@ -362,3 +362,133 @@ def test_anthropic_backend_nonstreaming_perf_zeros_when_upstream_omits_cache_usa
     handler = log_handle[0]
     cr, cw, chp = _find_perf_record(handler.records)
     assert (cr, cw, chp) == (0, 0, 0)
+
+
+def test_anthropic_backend_nonstreaming_uncached_from_usage_input_tokens() -> None:
+    """The buffered anthropic-backend path must report uncached input tokens
+    from the backend's ``usage.input_tokens`` (which is already prompt minus
+    cache), not re-derive it from the live-zone tokenizer count.
+
+    The old code computed ``uncached = attempted_input_tokens - cache_read -
+    cache_write``, where ``attempted_input_tokens`` is the small live-zone token
+    count kept for the compression-ratio denominator. On any turn whose cached
+    prefix is larger than the new turn that underflows to 0, so uncached input
+    was reported as 0. Here ``usage.input_tokens=1000`` while the live zone is a
+    couple of tokens, so the two behaviours are distinguishable.
+    """
+    from headroom.proxy.server import HeadroomProxy
+
+    config = ProxyConfig(
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        backend="anyllm",
+        anyllm_provider="anthropic",
+    )
+    body = {
+        "id": "msg_1",
+        "type": "message",
+        "role": "assistant",
+        "model": "claude-3-5-sonnet-20241022",
+        "content": [{"type": "text", "text": "hi"}],
+        "stop_reason": "end_turn",
+        "usage": {
+            "input_tokens": 1000,
+            "output_tokens": 50,
+            "cache_read_input_tokens": 500,
+            "cache_creation_input_tokens": 200,
+        },
+    }
+    backend = _make_anthropic_backend(body)
+
+    captured: list[Any] = []
+    orig_record = HeadroomProxy._record_request_outcome
+
+    async def _spy(self, outcome):  # noqa: ANN001, ANN202
+        captured.append(outcome)
+        return await orig_record(self, outcome)
+
+    with (
+        patch("headroom.proxy.server.AnyLLMBackend", return_value=backend),
+        patch.object(HeadroomProxy, "_record_request_outcome", _spy),
+    ):
+        app = create_app(config)
+        with TestClient(app) as client:
+            resp = client.post(
+                "/v1/messages",
+                json={
+                    "model": "claude-3-5-sonnet-20241022",
+                    "messages": [{"role": "user", "content": "hi"}],
+                    "max_tokens": 64,
+                },
+                headers={"x-api-key": "sk-ant-test", "anthropic-version": "2023-06-01"},
+            )
+            assert resp.status_code == 200, resp.text[:200]
+
+    assert captured, "expected a recorded RequestOutcome"
+    outcome = captured[-1]
+    assert outcome.uncached_input_tokens == 1000
+    assert outcome.cache_read_tokens == 500
+    assert outcome.cache_write_tokens == 200
+
+
+def test_anthropic_backend_nonstreaming_uncached_falls_back_when_input_tokens_absent() -> None:
+    """When the backend omits ``input_tokens``, uncached must NOT collapse to 0.
+
+    ``usage.input_tokens`` is authoritative when present, but a backend that
+    does not report it must fall back to the live-zone derivation rather than
+    silently record uncached=0 (which is what ``usage.get("input_tokens", 0)``
+    would do). With no cache counters the derivation is just the live-zone
+    tokenizer count, so the recorded value is a positive estimate, not 0.
+    """
+    from headroom.proxy.server import HeadroomProxy
+
+    config = ProxyConfig(
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        backend="anyllm",
+        anyllm_provider="anthropic",
+    )
+    # No ``input_tokens`` in usage — only output. A real backend that fails to
+    # translate the prompt-token field lands here.
+    body = {
+        "id": "msg_1",
+        "type": "message",
+        "role": "assistant",
+        "model": "claude-3-5-sonnet-20241022",
+        "content": [{"type": "text", "text": "hi"}],
+        "stop_reason": "end_turn",
+        "usage": {"output_tokens": 50},
+    }
+    backend = _make_anthropic_backend(body)
+
+    captured: list[Any] = []
+    orig_record = HeadroomProxy._record_request_outcome
+
+    async def _spy(self, outcome):  # noqa: ANN001, ANN202
+        captured.append(outcome)
+        return await orig_record(self, outcome)
+
+    with (
+        patch("headroom.proxy.server.AnyLLMBackend", return_value=backend),
+        patch.object(HeadroomProxy, "_record_request_outcome", _spy),
+    ):
+        app = create_app(config)
+        with TestClient(app) as client:
+            resp = client.post(
+                "/v1/messages",
+                json={
+                    "model": "claude-3-5-sonnet-20241022",
+                    "messages": [{"role": "user", "content": "hello there"}],
+                    "max_tokens": 64,
+                },
+                headers={"x-api-key": "sk-ant-test", "anthropic-version": "2023-06-01"},
+            )
+            assert resp.status_code == 200, resp.text[:200]
+
+    assert captured, "expected a recorded RequestOutcome"
+    outcome = captured[-1]
+    # No input_tokens reported and no cache: the live-zone derivation yields the
+    # non-zero token count of the new turn, never the 0 the naive default gave.
+    assert outcome.uncached_input_tokens > 0
diff --git a/tests/test_backends/test_litellm_cache_stats.py b/tests/test_backends/test_litellm_cache_stats.py
index 083a7a5d1..4ec6e057f 100644
--- a/tests/test_backends/test_litellm_cache_stats.py
+++ b/tests/test_backends/test_litellm_cache_stats.py
@@ -215,3 +215,30 @@ async def test_no_cache_fields_means_no_cache_keys_in_usage_block() -> None:
     assert "cache_read_input_tokens" not in body_usage
     assert "cache_creation_input_tokens" not in body_usage
     assert "prompt_tokens_details" not in body_usage
+
+
+async def test_none_core_counts_coerced_to_zero() -> None:
+    """A provider can leave prompt/completion/total token counts None on the
+    Usage object. The OpenAI-shape usage block must emit ints, not None, so the
+    backend-routed OpenAI handler (which reads these straight into arithmetic
+    and RequestOutcome) does not crash with a TypeError."""
+    usage = _FakeUsage(
+        prompt_tokens=None,  # type: ignore[arg-type]
+        completion_tokens=None,  # type: ignore[arg-type]
+        total_tokens=None,  # type: ignore[arg-type]
+    )
+    response = _make_response(usage)
+
+    backend = _make_backend()
+    with patch("headroom.backends.litellm.acompletion", new_callable=AsyncMock) as mock_acomp:
+        mock_acomp.return_value = response
+        result = await backend.send_openai_message(_request_body(), {})
+
+    body_usage = result.body["usage"]
+    assert body_usage["prompt_tokens"] == 0
+    assert body_usage["completion_tokens"] == 0
+    assert body_usage["total_tokens"] == 0
+    assert all(
+        isinstance(body_usage[k], int)
+        for k in ("prompt_tokens", "completion_tokens", "total_tokens")
+    )
diff --git a/tests/test_bedrock_region.py b/tests/test_bedrock_region.py
index f96cff1a6..306748245 100644
--- a/tests/test_bedrock_region.py
+++ b/tests/test_bedrock_region.py
@@ -374,6 +374,69 @@ class TestBedrockModelMapping:
                 "bedrock/global.anthropic.claude-opus-4-8"
             )
 
+    def test_cross_region_prefixed_id_passes_through_directly(self):
+        """au./us./eu./apac./global. prefixed IDs must be passed straight to
+        Bedrock without discovery remapping.  Remapping can route to an
+        APPLICATION inference profile owned by another team, causing a 403.
+        Regression test for the bug reported in BUG_FIX.md."""
+        # Simulate a discovery map that contains an APPLICATION-type profile
+        # for the same underlying model (the bad case: wrong profile selected).
+        bad_app_profile = "bedrock/arn:aws:bedrock:ap-southeast-2:002037730852:application-inference-profile/6lgt8epqa0wf"
+        with patch(
+            "headroom.backends.litellm._fetch_bedrock_inference_profiles",
+            return_value={"claude-opus-4-8": bad_app_profile},
+        ):
+            backend = LiteLLMBackend(provider="bedrock", region="ap-southeast-2")
+            # The au. prefix must bypass discovery and pass through directly.
+            assert backend.map_model_id("au.anthropic.claude-opus-4-8") == (
+                "bedrock/au.anthropic.claude-opus-4-8"
+            )
+
+    def test_cross_region_prefixes_all_pass_through(self):
+        """All five cross-region prefix families pass through without remapping."""
+        with patch(
+            "headroom.backends.litellm._fetch_bedrock_inference_profiles",
+            return_value={},
+        ):
+            backend = LiteLLMBackend(provider="bedrock", region="us-east-1")
+            cases = [
+                ("au.anthropic.claude-opus-4-8", "bedrock/au.anthropic.claude-opus-4-8"),
+                (
+                    "us.anthropic.claude-sonnet-4-20250514-v1:0",
+                    "bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0",
+                ),
+                (
+                    "eu.anthropic.claude-3-5-sonnet-20241022-v2:0",
+                    "bedrock/eu.anthropic.claude-3-5-sonnet-20241022-v2:0",
+                ),
+                (
+                    "apac.anthropic.claude-3-5-haiku-20241022-v1:0",
+                    "bedrock/apac.anthropic.claude-3-5-haiku-20241022-v1:0",
+                ),
+                ("global.anthropic.claude-opus-4-8", "bedrock/global.anthropic.claude-opus-4-8"),
+            ]
+            for model_in, expected in cases:
+                assert backend.map_model_id(model_in) == expected, (
+                    f"Expected {expected!r} for input {model_in!r}"
+                )
+
+    def test_litellm_qualified_cross_region_id_passes_through_with_contaminated_map(self):
+        """'bedrock/<cross-region-prefix>...' — the already LiteLLM-qualified form
+        documented in map_model_id's docstring — must also bypass discovery
+        remapping. Regression for the gap where only the bare 'us.anthropic...'
+        form was checked, so 'bedrock/us.anthropic...' still fell through to
+        normalization and could be remapped to a contaminating APPLICATION
+        profile in the discovery map."""
+        bad_app_profile = "bedrock/arn:aws:bedrock:ap-southeast-2:002037730852:application-inference-profile/6lgt8epqa0wf"
+        with patch(
+            "headroom.backends.litellm._fetch_bedrock_inference_profiles",
+            return_value={"claude-opus-4-8": bad_app_profile},
+        ):
+            backend = LiteLLMBackend(provider="bedrock", region="ap-southeast-2")
+            assert backend.map_model_id("bedrock/au.anthropic.claude-opus-4-8") == (
+                "bedrock/au.anthropic.claude-opus-4-8"
+            )
+
 
 # =============================================================================
 # Normalize Bedrock Profile ID (edge cases)
diff --git a/tests/test_binaries.py b/tests/test_binaries.py
index 2472b4e38..39af0fb21 100644
--- a/tests/test_binaries.py
+++ b/tests/test_binaries.py
@@ -257,6 +257,30 @@ def test_fetch_extract_zip(monkeypatch, fake_urlopen):
     assert path.read_bytes() == payload
 
 
+def test_download_retries_transient_network_failure(monkeypatch, tmp_path):
+    attempts = 0
+    sleeps: list[float] = []
+
+    def flaky_urlopen(req, timeout=None):  # noqa: ARG001
+        nonlocal attempts
+        attempts += 1
+        if attempts < 3:
+            import urllib.error
+
+            raise urllib.error.URLError("temporary GitHub release failure")
+        return _FakeResponse(b"binary")
+
+    monkeypatch.setattr(binaries.urllib.request, "urlopen", flaky_urlopen)
+    monkeypatch.setattr(binaries.time, "sleep", sleeps.append)
+
+    destination = tmp_path / "download"
+    binaries._download("https://github.com/example/tool", destination, progress=False)
+
+    assert attempts == 3
+    assert sleeps == [0.25, 0.5]
+    assert destination.read_bytes() == b"binary"
+
+
 def test_sha256_mismatch_raises_and_deletes(monkeypatch, fake_urlopen, tmp_path):
     _set_platform(monkeypatch, sys_plat="darwin", machine="arm64")
     monkeypatch.setattr(binaries.shutil, "which", lambda _name: None)
diff --git a/tests/test_cache_breakpoint_diagnostics.py b/tests/test_cache_breakpoint_diagnostics.py
new file mode 100644
index 000000000..03786dc31
--- /dev/null
+++ b/tests/test_cache_breakpoint_diagnostics.py
@@ -0,0 +1,180 @@
+"""Tests for cache_control breakpoint diagnostics and log-privacy switches.
+
+Covers the three pieces added for the uncached-tail investigation:
+- ``count_cache_breakpoints`` / ``log_cache_breakpoints`` (proxy helpers)
+- the ``HEADROOM_LOG_PAYLOAD_PREVIEW`` kill switch (compression store)
+- the injection guard that keeps proactive expansion out of breakpointed blocks
+"""
+
+from __future__ import annotations
+
+import logging
+
+from headroom.cache.compression_store import _payload_for_retrieval_log
+from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
+from headroom.proxy.helpers import count_cache_breakpoints, log_cache_breakpoints
+
+_CC = {"cache_control": {"type": "ephemeral"}}
+
+
+def _claude_code_style_request() -> tuple[list[dict], list[dict], list[dict]]:
+    """System/messages/tools shaped like a real Claude Code request."""
+    system = [
+        {"type": "text", "text": "You are Claude Code."},
+        {"type": "text", "text": "project instructions", **_CC},
+    ]
+    tools = [
+        {"name": "Bash", "input_schema": {}},
+        {"name": "Read", "input_schema": {}, **_CC},
+    ]
+    messages = [
+        {"role": "user", "content": [{"type": "text", "text": "hi", **_CC}]},
+        {"role": "assistant", "content": [{"type": "text", "text": "ack"}]},
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "t1",
+                    "content": [{"type": "text", "text": "big output"}],
+                    **_CC,
+                }
+            ],
+        },
+    ]
+    return system, messages, tools
+
+
+def test_count_cache_breakpoints_counts_all_sections() -> None:
+    system, messages, tools = _claude_code_style_request()
+    stats = count_cache_breakpoints(system, messages, tools)
+    assert stats["system"] == 1
+    assert stats["tools"] == 1
+    assert stats["messages"] == 2
+    assert stats["total"] == 4
+    assert stats["message_count"] == 3
+    assert stats["last_marker_tail"] == 0  # last message carries a marker
+
+
+def test_count_cache_breakpoints_counts_nested_tool_result_markers() -> None:
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "t1",
+                    "content": [{"type": "text", "text": "out", **_CC}],
+                }
+            ],
+        }
+    ]
+    stats = count_cache_breakpoints("plain system string", messages, None)
+    assert stats["system"] == 0
+    assert stats["tools"] == 0
+    assert stats["messages"] == 1
+    assert stats["last_marker_tail"] == 0
+
+
+def test_count_cache_breakpoints_tail_tracks_last_marker() -> None:
+    messages = [
+        {"role": "user", "content": [{"type": "text", "text": "a", **_CC}]},
+        {"role": "assistant", "content": [{"type": "text", "text": "b"}]},
+        {"role": "user", "content": [{"type": "text", "text": "c"}]},
+    ]
+    stats = count_cache_breakpoints(None, messages, None)
+    assert stats["last_marker_tail"] == 2
+    assert count_cache_breakpoints(None, [], None)["last_marker_tail"] == -1
+
+
+def test_log_cache_breakpoints_warns_on_dropped_marker(caplog) -> None:
+    system, messages, tools = _claude_code_style_request()
+    inbound = count_cache_breakpoints(system, messages, tools)
+    # Transform "lost" the final breakpoint: strip it from the last message.
+    stripped = [dict(m) for m in messages]
+    stripped[2] = {
+        "role": "user",
+        "content": [{"type": "tool_result", "tool_use_id": "t1", "content": "compressed"}],
+    }
+    outbound = count_cache_breakpoints(system, stripped, tools)
+    with caplog.at_level(logging.INFO, logger="headroom.proxy"):
+        log_cache_breakpoints(request_id="r1", inbound=inbound, outbound=outbound)
+    [record] = caplog.records
+    assert record.levelno == logging.WARNING
+    assert "dropped=true" in record.getMessage()
+    assert "tail_grew=true" in record.getMessage()
+
+
+def test_log_cache_breakpoints_info_when_preserved(caplog) -> None:
+    system, messages, tools = _claude_code_style_request()
+    stats = count_cache_breakpoints(system, messages, tools)
+    with caplog.at_level(logging.INFO, logger="headroom.proxy"):
+        log_cache_breakpoints(request_id="r1", inbound=stats, outbound=stats)
+    [record] = caplog.records
+    assert record.levelno == logging.INFO
+    assert "dropped=false" in record.getMessage()
+
+
+def test_payload_preview_disabled_omits_content(monkeypatch) -> None:
+    monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", "0")
+    payload = "secret file contents: api_key=sk-abcdefghijklmnop"
+    event = _payload_for_retrieval_log(payload)
+    assert event["payload_preview"] == ""
+    assert event["payload_preview_chars"] == 0
+    assert event["payload_chars"] == len(payload)
+    assert event["payload_truncated"] is True
+
+
+def test_payload_preview_enabled_by_default(monkeypatch) -> None:
+    monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
+    event = _payload_for_retrieval_log("hello world")
+    assert event["payload_preview"] == "hello world"
+
+
+def test_append_context_skips_breakpointed_text_block() -> None:
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "breakpointed", **_CC},
+                {"type": "text", "text": "free"},
+            ],
+        }
+    ]
+    result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
+        messages, "CTX", frozen_message_count=0
+    )
+    blocks = result[0]["content"]
+    assert blocks[0]["text"] == "breakpointed"  # untouched
+    assert blocks[1]["text"].endswith("CTX")
+
+
+def test_append_context_no_eligible_block_returns_unchanged() -> None:
+    messages = [
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": "breakpointed", **_CC}],
+        }
+    ]
+    result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
+        messages, "CTX", frozen_message_count=0
+    )
+    assert result == messages
+
+
+def test_count_cache_breakpoints_tolerates_malformed_shapes() -> None:
+    messages = [
+        "not-a-dict",
+        {"role": "user", "content": ["scalar-block", {"type": "text", "text": "x", **_CC}]},
+        {"role": "user", "content": "plain string"},
+    ]
+    stats = count_cache_breakpoints("system-as-string", messages, "tools-as-string")
+    assert stats["system"] == 0
+    assert stats["tools"] == 0
+    assert stats["messages"] == 1
+    assert stats["message_count"] == 3
+    assert stats["last_marker_tail"] == 1
+
+    empty = count_cache_breakpoints(None, None, None)
+    assert empty["total"] == 0
+    assert empty["message_count"] == 0
diff --git a/tests/test_cache_control_move_bust.py b/tests/test_cache_control_move_bust.py
index 0b74ff92d..3816c7b38 100644
--- a/tests/test_cache_control_move_bust.py
+++ b/tests/test_cache_control_move_bust.py
@@ -224,3 +224,177 @@ def test_normalize_ttl_survives_many_turns():
         conv = normalize_message_cache_control(conv)
         assert _markers(conv) == 1
         assert conv[-1]["content"][-1]["cache_control"] == {"type": "ephemeral", "ttl": "1h"}
+
+
+# ── fix-4: mirror the CLIENT's marker positions (20-block lookback chain) ────
+# Anthropic resolves each breakpoint by walking back at most ~20 content
+# blocks. Agentic clients keep a marker on the previous turn's newest message
+# as the read anchor; collapsing to a single newest-block marker breaks the
+# chain on tool-heavy turns. With client_messages provided, normalize must
+# keep exactly the client's positions.
+
+
+def test_normalize_mirrors_client_marker_positions():
+    client = [
+        B("user", "a", cc=True),
+        B("assistant", "b"),
+        B("user", "c", cc=True),  # read anchor (previous newest)
+        B("assistant", "d"),
+        B("user", "e", cc=True),  # newest
+    ]
+    # Forwarded form: replay leftovers piled markers onto other messages too.
+    merged = [
+        B("user", "a", cc=True),
+        B("assistant", "b", cc=True),
+        B("user", "c", cc=True),
+        B("assistant", "d", cc=True),
+        B("user", "e", cc=True),
+    ]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 3  # exactly the client's three, not one
+    for idx in (0, 2, 4):
+        assert "cache_control" in out[idx]["content"][-1], idx
+    for idx in (1, 3):
+        assert _markers([out[idx]]) == 0, idx
+    assert _strip_cache_control(out) == _strip_cache_control(merged)
+
+
+def test_normalize_mirror_preserves_per_position_ttl():
+    client = [B_ttl("user", "a", "1h"), B("user", "b", cc=True)]
+    merged = [B("user", "a", cc=True), B("user", "b", cc=True)]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert out[0]["content"][-1]["cache_control"] == {"type": "ephemeral", "ttl": "1h"}
+    assert out[1]["content"][-1]["cache_control"] == {"type": "ephemeral"}
+
+
+def test_normalize_mirror_bounded_across_many_turns():
+    """Client moves its pair of markers forward; forwarded stays at client count."""
+    conv = []
+    for t in range(1, 12):
+        conv = conv + [B("user", f"turn-{t}")]
+        # Client marks the newest and second-newest marked position (CC pattern).
+        client = [dict(m) for m in conv]
+        client[-1] = B("user", f"turn-{t}", cc=True)
+        if len(client) >= 2:
+            client[-2] = B(client[-2]["role"], client[-2]["content"][0]["text"], cc=True)
+        # Forwarded side accumulated replay leftovers everywhere.
+        merged = [B(m["role"], m["content"][0]["text"], cc=True) for m in client]
+        out = normalize_message_cache_control(merged, client_messages=client)
+        assert _markers(out) == min(2, len(client))
+        assert "cache_control" in out[-1]["content"][-1]
+
+
+def test_normalize_falls_back_when_counts_mismatch():
+    client = [B("user", "a", cc=True)]  # transform changed message count
+    merged = [B("user", "a", cc=True), B("user", "b", cc=True)]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 1  # legacy consolidation
+    assert "cache_control" in out[-1]["content"][-1]
+
+
+def test_normalize_falls_back_when_client_has_no_markers():
+    client = [B("user", "a"), B("user", "b")]
+    merged = [B("user", "a", cc=True), B("user", "b")]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 1  # legacy: still place one so the prefix caches
+    assert "cache_control" in out[-1]["content"][-1]
+
+
+def test_normalize_mirror_skips_string_content_positions():
+    # Client marked message 0; forwarded counterpart is string-content (cannot
+    # carry a marker) — the position is skipped, the rest still mirror.
+    client = [B("user", "a", cc=True), B("user", "b", cc=True)]
+    merged = [{"role": "user", "content": "a"}, B("user", "b", cc=True)]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 1
+    assert "cache_control" in out[1]["content"][-1]
+
+
+# ── fix-5: block-level mirroring (multiple client markers in one message) ────
+
+
+def test_normalize_mirrors_multiple_markers_within_one_message():
+    """A 2-message request where the client marks TWO blocks of message 0
+    (Claude Code's pattern on large first messages) keeps all three markers."""
+    big = {
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "part-1", "cache_control": {"type": "ephemeral"}},
+            {"type": "text", "text": "part-2"},
+            {"type": "text", "text": "part-3", "cache_control": {"type": "ephemeral"}},
+        ],
+    }
+    client = [big, B("user", "follow-up", cc=True)]
+    # Forwarded form: an extra replay leftover on message 1's sibling... use
+    # identical structure with markers everywhere to prove selective stripping.
+    merged = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "part-1", "cache_control": {"type": "ephemeral"}},
+                {"type": "text", "text": "part-2", "cache_control": {"type": "ephemeral"}},
+                {"type": "text", "text": "part-3", "cache_control": {"type": "ephemeral"}},
+            ],
+        },
+        B("user", "follow-up", cc=True),
+    ]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 3
+    assert "cache_control" in out[0]["content"][0]
+    assert "cache_control" not in out[0]["content"][1]
+    assert "cache_control" in out[0]["content"][2]
+    assert "cache_control" in out[1]["content"][-1]
+    assert _strip_cache_control(out) == _strip_cache_control(merged)
+
+
+def test_normalize_mirror_clamps_out_of_range_block_index():
+    # Client marked block 2; forwarded message only has 1 block (transform
+    # merged content) — marker falls back to the last block, not dropped.
+    client = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "a"},
+                {"type": "text", "text": "b"},
+                {"type": "text", "text": "c", "cache_control": {"type": "ephemeral"}},
+            ],
+        },
+        B("user", "tail", cc=True),
+    ]
+    merged = [B("user", "abc-merged"), B("user", "tail", cc=True)]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 2
+    assert "cache_control" in out[0]["content"][-1]
+    assert "cache_control" in out[1]["content"][-1]
+
+
+def test_normalize_mirror_scalar_only_content_is_left_unchanged():
+    """Client marks a message whose forwarded counterpart carries only scalar
+    blocks: nothing can hold a marker and nothing was stripped, so the input
+    comes back unchanged (identity, not a copy)."""
+    client = [B("user", "a", cc=True)]
+    merged = [{"role": "user", "content": ["scalar-only"]}]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert out is merged
+    assert _markers(out) == 0
+
+
+def test_normalize_mirror_scalar_target_still_strips_leftovers():
+    # Message 0's forwarded content is scalar-only (marker unplaceable) but a
+    # replay leftover on message 1 still gets stripped, and message 1 keeps
+    # its client marker.
+    client = [B("user", "a", cc=True), B("user", "b", cc=True)]
+    merged = [
+        {"role": "user", "content": ["scalar-only"]},
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "left-over", "cache_control": {"type": "ephemeral"}},
+                {"type": "text", "text": "b"},
+            ],
+        },
+    ]
+    out = normalize_message_cache_control(merged, client_messages=client)
+    assert _markers(out) == 1
+    assert "cache_control" not in out[1]["content"][0]
+    assert "cache_control" in out[1]["content"][-1]
diff --git a/tests/test_cache_control_ttl_order.py b/tests/test_cache_control_ttl_order.py
new file mode 100644
index 000000000..74bf146f6
--- /dev/null
+++ b/tests/test_cache_control_ttl_order.py
@@ -0,0 +1,354 @@
+"""The forwarded body must satisfy Anthropic's cache_control TTL ordering.
+
+Anthropic evaluates cache breakpoints in one global walk -- ``tools``, then
+``system``, then ``messages`` -- and rejects the whole request when a
+``ttl="1h"`` marker appears after a 5-minute one (a bare ``{"type":
+"ephemeral"}`` marker *is* 5m)::
+
+    400 messages.15.content.1.cache_control.ttl: a ttl='1h' cache_control block
+    must not come after a ttl='5m' cache_control block.
+
+Headroom rewrites markers in several independent places, section by section,
+and until #2939 nothing checked the rule that spans them. The failure is a dead
+turn rather than a silent cost regression, so it needs tests that pin both
+repair directions and, just as importantly, pin that a legal request is passed
+through by identity.
+"""
+
+from typing import Any
+
+import pytest
+
+from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
+from headroom.proxy.helpers import (
+    cache_control_ttl_lane,
+    cache_control_ttl_lanes,
+    enforce_cache_control_ttl_order,
+    inject_tool_search_deferral,
+)
+
+TTL_1H: dict[str, Any] = {"type": "ephemeral", "ttl": "1h"}
+BARE: dict[str, Any] = {"type": "ephemeral"}
+TTL_5M: dict[str, Any] = {"type": "ephemeral", "ttl": "5m"}
+
+
+def _text(text: str, marker: dict[str, Any] | None = None) -> dict[str, Any]:
+    block: dict[str, Any] = {"type": "text", "text": text}
+    if marker is not None:
+        block["cache_control"] = marker
+    return block
+
+
+def _msg(*blocks: dict[str, Any], role: str = "user") -> dict[str, Any]:
+    return {"role": role, "content": list(blocks)}
+
+
+def _markers(system: Any, messages: Any, tools: Any) -> list[dict[str, Any]]:
+    """Every marker in Anthropic's evaluation order."""
+    found: list[dict[str, Any]] = []
+    for tool in tools or []:
+        if isinstance(tool, dict) and isinstance(tool.get("cache_control"), dict):
+            found.append(tool["cache_control"])
+    for block in system or []:
+        if isinstance(block, dict) and isinstance(block.get("cache_control"), dict):
+            found.append(block["cache_control"])
+    for msg in messages or []:
+        if isinstance(msg.get("cache_control"), dict):
+            found.append(msg["cache_control"])
+        for block in msg.get("content") or []:
+            if not isinstance(block, dict):
+                continue
+            if isinstance(block.get("cache_control"), dict):
+                found.append(block["cache_control"])
+            for sub in block.get("content") or []:
+                if isinstance(sub, dict) and isinstance(sub.get("cache_control"), dict):
+                    found.append(sub["cache_control"])
+    return found
+
+
+def _is_legal(system: Any, messages: Any, tools: Any) -> bool:
+    """Reimplements the API's rule independently of the code under test."""
+    seen_short = False
+    for marker in _markers(system, messages, tools):
+        lane = cache_control_ttl_lane(marker)
+        if lane == "5m":
+            seen_short = True
+        elif lane == "1h" and seen_short:
+            return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Lane classification
+
+
+@pytest.mark.parametrize(
+    ("marker", "expected"),
+    [
+        ({"type": "ephemeral"}, "5m"),
+        ({"type": "ephemeral", "ttl": "5m"}, "5m"),
+        ({"type": "ephemeral", "ttl": "1h"}, "1h"),
+        ({"type": "ephemeral", "ttl": "24h"}, "other"),
+        ("not-a-dict", "other"),
+    ],
+)
+def test_lane_classification(marker: Any, expected: str) -> None:
+    # A bare marker must read as 5m, not "unknown": every ordinary Claude Code
+    # request sends bare markers, and calling those unknown would either mask
+    # real violations or invent imaginary ones.
+    assert cache_control_ttl_lane(marker) == expected
+
+
+def test_lanes_survey_covers_all_three_sections() -> None:
+    lanes = cache_control_ttl_lanes(
+        [_text("sys", BARE)],
+        [_msg(_text("hi", TTL_1H))],
+        [{"name": "read", "cache_control": {"type": "ephemeral", "ttl": "7d"}}],
+    )
+    assert lanes == {"5m", "1h", "other"}
+
+
+# ---------------------------------------------------------------------------
+# Repair 1: lane containment -- the /btw case from #2939
+
+
+def test_replayed_1h_is_stripped_when_client_asked_for_5m() -> None:
+    # Claude Code's `/btw` forks the conversation as a "side question", which is
+    # not on its 1h allowlist: the fork's tools/system breakpoints are bare 5m
+    # and it does not send the extended-cache-ttl beta header. Headroom's
+    # overlay of the previous turn's forwarded bytes drags a 1h marker into
+    # messages behind them, which is exactly the reported 400.
+    tools = [{"name": "read", "cache_control": dict(BARE)}]
+    system = [_text("sys", dict(BARE))]
+    messages = [_msg(_text("old"), _text("replayed", dict(TTL_1H)))]
+
+    system, messages, tools, stats = enforce_cache_control_ttl_order(
+        system, messages, tools, client_uses_1h=False
+    )
+
+    assert stats["violation"] is True
+    assert stats["demoted"] == 1
+    assert stats["first_long_section"] == "messages"
+    assert _markers(system, messages, tools) == [BARE, BARE, BARE], (
+        "the leaked 1h ttl should be dropped, leaving the marker itself in place"
+    )
+    assert _is_legal(system, messages, tools)
+
+
+def test_containment_keeps_non_ttl_marker_fields() -> None:
+    # Claude Code also sends `scope` on its markers; only the ttl is at fault.
+    scoped = {"type": "ephemeral", "ttl": "1h", "scope": "global"}
+    _, messages, _, stats = enforce_cache_control_ttl_order(
+        None, [_msg(_text("x", scoped))], None, client_uses_1h=False
+    )
+    assert stats["demoted"] == 1
+    assert messages[0]["content"][0]["cache_control"] == {
+        "type": "ephemeral",
+        "scope": "global",
+    }
+
+
+def test_client_1h_is_never_stripped() -> None:
+    system = [_text("sys", dict(TTL_1H))]
+    messages = [_msg(_text("hi", dict(TTL_1H)))]
+    out_system, out_messages, out_tools, stats = enforce_cache_control_ttl_order(
+        system, messages, None, client_uses_1h=True
+    )
+    assert stats["violation"] is False
+    assert out_system is system and out_messages is messages and out_tools is None
+
+
+# ---------------------------------------------------------------------------
+# Repair 2: ordering -- the #2767 case
+
+
+def test_5m_in_tools_before_1h_in_messages_is_promoted() -> None:
+    # A transform downgraded the tools breakpoint while the client's message
+    # breakpoints are still 1h. Promoting restores what the client asked for;
+    # demoting would throw away 1h caching it is already paying for.
+    tools = [{"name": "read", "cache_control": dict(BARE)}]
+    messages = [_msg(_text("hi", dict(TTL_1H)))]
+
+    _, messages, tools, stats = enforce_cache_control_ttl_order(
+        None, messages, tools, client_uses_1h=True
+    )
+
+    assert stats["promoted"] == 1
+    assert stats["first_short_section"] == "tools"
+    assert stats["first_long_section"] == "messages"
+    assert tools[0]["cache_control"] == TTL_1H
+    assert messages[0]["content"][0]["cache_control"] == TTL_1H
+    assert _is_legal(None, messages, tools)
+
+
+def test_5m_in_system_before_1h_in_messages_is_promoted() -> None:
+    system = [_text("sys", dict(TTL_5M))]
+    messages = [_msg(_text("hi", dict(TTL_1H)))]
+
+    system, messages, _, stats = enforce_cache_control_ttl_order(
+        system, messages, None, client_uses_1h=True
+    )
+
+    assert stats["first_short_section"] == "system"
+    assert system[0]["cache_control"] == TTL_1H
+
+
+def test_violation_within_messages_is_promoted() -> None:
+    messages = [
+        _msg(_text("a", dict(BARE))),
+        _msg(_text("b"), _text("c", dict(TTL_1H))),
+    ]
+    _, messages, _, stats = enforce_cache_control_ttl_order(
+        None, messages, None, client_uses_1h=True
+    )
+    assert stats["promoted"] == 1
+    assert messages[0]["content"][0]["cache_control"] == TTL_1H
+
+
+def test_nested_tool_result_markers_participate() -> None:
+    # tool_result carries its own content list; a marker hiding in there is
+    # still a breakpoint the API walks, so it must count for the ordering.
+    messages = [
+        _msg(
+            {
+                "type": "tool_result",
+                "tool_use_id": "t1",
+                "content": [_text("inner", dict(BARE))],
+            }
+        ),
+        _msg(_text("later", dict(TTL_1H))),
+    ]
+    _, messages, _, stats = enforce_cache_control_ttl_order(
+        None, messages, None, client_uses_1h=True
+    )
+    assert stats["promoted"] == 1
+    assert messages[0]["content"][0]["content"][0]["cache_control"] == TTL_1H
+
+
+def test_only_markers_before_the_last_1h_are_promoted() -> None:
+    # A 5m marker AFTER every 1h one is legal and must be left alone -- that is
+    # the ordering the API documents, not something to normalise away.
+    messages = [
+        _msg(_text("a", dict(BARE))),
+        _msg(_text("b", dict(TTL_1H))),
+        _msg(_text("c", dict(BARE))),
+    ]
+    _, messages, _, stats = enforce_cache_control_ttl_order(
+        None, messages, None, client_uses_1h=True
+    )
+    assert stats["promoted"] == 1
+    assert [m["content"][0]["cache_control"] for m in messages] == [TTL_1H, TTL_1H, BARE]
+
+
+# ---------------------------------------------------------------------------
+# Pass-through cases
+
+
+@pytest.mark.parametrize(
+    "markers",
+    [
+        pytest.param([TTL_1H, TTL_1H], id="all-1h"),
+        pytest.param([BARE, BARE], id="all-5m"),
+        pytest.param([TTL_1H, BARE], id="1h-then-5m"),
+        pytest.param([], id="no-markers"),
+    ],
+)
+def test_legal_requests_are_returned_by_identity(markers: list[dict[str, Any]]) -> None:
+    messages = [_msg(_text(f"m{i}", dict(m))) for i, m in enumerate(markers)] or [_msg(_text("m"))]
+    out_system, out_messages, out_tools, stats = enforce_cache_control_ttl_order(
+        None, messages, None, client_uses_1h=True
+    )
+    assert stats["violation"] is False
+    assert out_messages is messages, "a legal body must not be rebuilt"
+    assert out_system is None and out_tools is None
+
+
+def test_unknown_ttl_is_left_alone() -> None:
+    # Mirrors TtlOrderingWalk::observe in headroom-core: a TTL lane we don't
+    # model takes no part in the rule and is never rewritten.
+    messages = [_msg(_text("a", {"type": "ephemeral", "ttl": "24h"})), _msg(_text("b", dict(BARE)))]
+    _, out, _, stats = enforce_cache_control_ttl_order(None, messages, None, client_uses_1h=False)
+    assert stats["violation"] is False
+    assert out is messages
+
+
+def test_kill_switch_disables_the_guard(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HEADROOM_CACHE_CONTROL_TTL_GUARD", "0")
+    tools = [{"name": "read", "cache_control": dict(BARE)}]
+    messages = [_msg(_text("hi", dict(TTL_1H)))]
+    _, out_messages, out_tools, stats = enforce_cache_control_ttl_order(
+        None, messages, tools, client_uses_1h=True
+    )
+    assert stats["violation"] is False
+    assert out_messages is messages and out_tools is tools
+
+
+# ---------------------------------------------------------------------------
+# Tool sort must not reorder markers
+
+
+def _tools(count: int, marked: dict[int, dict[str, Any]] | None = None) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for i in range(count):
+        # Names descend so an alphabetical sort is guaranteed to reorder them.
+        tool: dict[str, Any] = {"name": f"tool_{count - i:02d}", "input_schema": {}}
+        if marked and i in marked:
+            tool["cache_control"] = dict(marked[i])
+        out.append(tool)
+    return out
+
+
+def test_tool_sort_is_skipped_when_a_tool_carries_a_marker() -> None:
+    # A breakpoint on a tool means "cache through here"; sorting changes which
+    # tools are inside that prefix, and with two TTLs it can put the 1h marker
+    # behind the 5m one. The Rust proxy already refuses for the same reason.
+    tools = _tools(4, {1: TTL_1H, 3: BARE})
+    assert AnthropicHandlerMixin._sort_tools_deterministically(tools) is tools
+
+
+def test_tool_sort_still_sorts_unmarked_tools() -> None:
+    tools = _tools(4)
+    ordered = AnthropicHandlerMixin._sort_tools_deterministically(tools)
+    assert [t["name"] for t in ordered] == sorted(t["name"] for t in tools), (
+        "clients that mark no tools must keep the deterministic ordering they rely on"
+    )
+
+
+def test_tool_sort_would_have_created_the_violation() -> None:
+    # Pins the hazard itself: without the guard, the alphabetical sort moves the
+    # 5m-marked tool ahead of the 1h-marked one, which is a 400 on its own.
+    tools = _tools(4, {1: TTL_1H, 3: BARE})
+    assert _is_legal(None, [], tools)
+    assert not _is_legal(None, [], sorted(tools, key=AnthropicHandlerMixin._tool_sort_key))
+
+
+# ---------------------------------------------------------------------------
+# End-to-end regression for #2939 / #2767
+
+
+def test_deferral_downgrade_then_guard_yields_a_legal_body() -> None:
+    # The #2767 shape: 13 tools, a 1h marker on one deferred tool and a bare
+    # marker on a LATER deferred tool. inject_tool_search_deferral keeps the
+    # last marker it stripped, so the tools prefix lands at 5m while the
+    # client's message breakpoints are still 1h -- a 400. The guard repairs it.
+    tools: list[dict[str, Any]] = [{"name": "read", "description": "core", "input_schema": {}}]
+    for i in range(12):
+        tool: dict[str, Any] = {"name": f"rare_{i}", "description": "rare", "input_schema": {}}
+        if i == 4:
+            tool["cache_control"] = dict(TTL_1H)
+        if i == 9:
+            tool["cache_control"] = dict(BARE)
+        tools.append(tool)
+    messages = [_msg(_text("history")), _msg(_text("newest", dict(TTL_1H)))]
+
+    deferred = inject_tool_search_deferral(tools)
+    assert deferred is not tools, "fixture no longer triggers the deferral"
+    assert not _is_legal(None, messages, deferred), (
+        "expected the downgraded tools breakpoint to make the body illegal"
+    )
+
+    _, messages, deferred, stats = enforce_cache_control_ttl_order(
+        None, messages, deferred, client_uses_1h=True
+    )
+    assert stats["violation"] is True
+    assert _is_legal(None, messages, deferred)
diff --git a/tests/test_cache_mode_cold_start.py b/tests/test_cache_mode_cold_start.py
new file mode 100644
index 000000000..3acc75bcd
--- /dev/null
+++ b/tests/test_cache_mode_cold_start.py
@@ -0,0 +1,239 @@
+"""Issue #2357: cache mode must not silently forward everything uncompressed.
+
+Cache mode compresses only the inter-turn delta against the previously
+forwarded prefix. Before this fix, both delta-miss cases fell through to a
+silent passthrough:
+
+- session cold start (no previous turn recorded) — including a resumed
+  100k-token transcript, so a fresh proxy never compressed anything while the
+  dashboard kept reporting "optimization enabled";
+- mid-session prefix mismatch (client rewrote history) — an intentional
+  passthrough, but with no tag or log explaining the 0 savings.
+
+Now a cold start runs the same full-message compression as non-cache modes
+(there is no provider cache prefix to protect yet), and the mismatch
+passthrough is tagged with ``passthrough_reason=cache_mode_prefix_mismatch``.
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import anyio
+from fastapi import Request
+
+from headroom.config import TransformResult
+from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
+from headroom.proxy.models import ProxyConfig
+
+_COMPRESSED_TEXT = "compressed tool output"
+
+
+class _DummyTokenizer:
+    def count_messages(self, messages) -> int:
+        return json.dumps(messages).count(" ") + 1
+
+    def count_text(self, text: str) -> int:
+        return max(1, text.count(" ") + 1)
+
+
+class _DummyMetrics:
+    async def record_request(self, **kwargs):
+        return None
+
+    async def record_stage_timings(self, path, timings):
+        return None
+
+    async def record_failed(self, **kwargs):
+        return None
+
+    def record_compression_failed(self, reason: str) -> None:
+        return None
+
+    async def record_rate_limited(self, **kwargs):
+        return None
+
+
+class _ResponseStub:
+    status_code = 200
+    headers: dict[str, str] = {}
+    content = b'{"id":"msg_1","type":"message","role":"assistant","content":[],"usage":{"input_tokens":1,"output_tokens":1}}'
+
+    def json(self):
+        return {
+            "id": "msg_1",
+            "type": "message",
+            "role": "assistant",
+            "content": [],
+            "usage": {"input_tokens": 1, "output_tokens": 1},
+        }
+
+
+def _fake_pipeline_apply(messages, model, **kwargs):
+    compressed = []
+    for msg in messages:
+        new = dict(msg)
+        if msg.get("role") == "user" and isinstance(msg.get("content"), list):
+            new["content"] = [
+                {**part, "content": _COMPRESSED_TEXT}
+                if isinstance(part, dict) and part.get("type") == "tool_result"
+                else part
+                for part in msg["content"]
+            ]
+        compressed.append(new)
+    return TransformResult(
+        messages=compressed,
+        tokens_before=1000,
+        tokens_after=100,
+        transforms_applied=["read_lifecycle:stale:test.py"],
+    )
+
+
+class _DummyAnthropicHandler(AnthropicHandlerMixin):
+    ANTHROPIC_API_URL = "https://api.anthropic.com"
+
+    def __init__(self, previous_messages: list | None = None) -> None:
+        self.rate_limiter = None
+        self.metrics = _DummyMetrics()
+        self.config = ProxyConfig(
+            optimize=True,
+            image_optimize=False,
+            retry_max_attempts=1,
+            retry_base_delay_ms=1,
+            retry_max_delay_ms=1,
+            connect_timeout_seconds=10,
+            mode="cache",
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            fallback_enabled=False,
+            fallback_provider=None,
+            prefix_freeze_enabled=False,
+            memory_enabled=False,
+        )
+        self.usage_reporter = None
+        self.anthropic_provider = SimpleNamespace(get_context_limit=lambda model: 200_000)
+        self.anthropic_pipeline = SimpleNamespace(apply=MagicMock(side_effect=_fake_pipeline_apply))
+        self.anthropic_backend = None
+        self.cost_tracker = None
+        self.memory_handler = None
+        self.cache = None
+        self.security = None
+        self.ccr_context_tracker = None
+        self.ccr_injector = None
+        self.ccr_response_handler = None
+        self.ccr_feedback = None
+        self.ccr_batch_processor = None
+        self.ccr_mcp_server = None
+        self.traffic_learner = None
+        self.tool_injector = None
+        self.read_lifecycle_manager = None
+        self.logger = SimpleNamespace(log=lambda *a, **k: None)
+        self.request_logger = self.logger
+        self.usage_observer = None
+        self.image_compressor = None
+        prev = previous_messages or []
+        tracker = MagicMock()
+        tracker.get_frozen_message_count.return_value = 0
+        tracker.get_last_original_messages.return_value = prev
+        tracker.get_last_forwarded_messages.return_value = prev
+        tracker._cached_token_count = 0
+        tracker.classify_cache_miss.return_value = SimpleNamespace(is_miss=False)
+        self.session_tracker_store = SimpleNamespace(
+            compute_session_id=lambda *a, **k: "sess-1",
+            get_or_create=lambda *a, **k: tracker,
+            resolve_tracker=lambda *a, **k: tracker,
+        )
+        self._background_compression_enabled = False
+        self.recorded_tags: dict = {}
+
+    async def _record_request_outcome(self, outcome) -> None:
+        self.recorded_tags = dict(outcome.tags or {})
+
+    async def _run_compression_in_executor(self, fn, timeout):
+        return fn()
+
+    async def _next_request_id(self) -> str:
+        return "req-cache-cold-start-test"
+
+    async def _retry_request(self, method, url, headers, body, **_kwargs):
+        self.captured_body = body
+        return _ResponseStub()
+
+
+def _build_request(body: dict) -> Request:
+    payload = json.dumps(body).encode("utf-8")
+
+    async def receive():
+        return {"type": "http.request", "body": payload, "more_body": False}
+
+    scope = {
+        "type": "http",
+        "asgi": {"version": "3.0"},
+        "http_version": "1.1",
+        "method": "POST",
+        "scheme": "https",
+        "path": "/v1/messages",
+        "raw_path": b"/v1/messages",
+        "query_string": b"",
+        "headers": [(b"authorization", b"Bearer sk-ant-api-test")],
+        "client": ("127.0.0.1", 12345),
+        "server": ("testserver", 443),
+    }
+    return Request(scope, receive)
+
+
+_TOOL_RESULT_MESSAGE = {
+    "role": "user",
+    "content": [
+        {
+            "type": "tool_result",
+            "tool_use_id": "toolu_1",
+            "content": "verbose stale tool output " * 200,
+        }
+    ],
+}
+
+
+def test_cache_mode_cold_start_compresses_full_request(monkeypatch):
+    import headroom.tokenizers as _tk
+
+    monkeypatch.setattr(_tk, "get_tokenizer", lambda model: _DummyTokenizer())
+
+    handler = _DummyAnthropicHandler(previous_messages=[])
+    request = _build_request(
+        {"model": "claude-3-5-sonnet-latest", "messages": [_TOOL_RESULT_MESSAGE]}
+    )
+
+    anyio.run(handler.handle_anthropic_messages, request)
+
+    # The full pipeline ran and its output was forwarded upstream.
+    assert handler.anthropic_pipeline.apply.call_count == 1
+    forwarded = handler.captured_body["messages"]
+    assert forwarded[0]["content"][0]["content"] == _COMPRESSED_TEXT
+    # No passthrough tag: compression genuinely ran.
+    assert "passthrough_reason" not in handler.recorded_tags
+
+
+def test_cache_mode_prefix_mismatch_passes_through_with_tag(monkeypatch):
+    import headroom.tokenizers as _tk
+
+    monkeypatch.setattr(_tk, "get_tokenizer", lambda model: _DummyTokenizer())
+
+    # A previous turn exists but is NOT a prefix of the current request.
+    previous = [{"role": "user", "content": [{"type": "text", "text": "totally different"}]}]
+    handler = _DummyAnthropicHandler(previous_messages=previous)
+    original_text = "verbose stale tool output " * 200
+    request = _build_request(
+        {"model": "claude-3-5-sonnet-latest", "messages": [_TOOL_RESULT_MESSAGE]}
+    )
+
+    anyio.run(handler.handle_anthropic_messages, request)
+
+    # Conservative passthrough preserved: bytes forwarded unmodified...
+    assert handler.anthropic_pipeline.apply.call_count == 0
+    forwarded = handler.captured_body["messages"]
+    assert forwarded[0]["content"][0]["content"] == original_text
+    # ...but now visibly tagged instead of silent.
+    assert handler.recorded_tags["passthrough_reason"] == "cache_mode_prefix_mismatch"
diff --git a/tests/test_ccr_buffered_stream_signed_thinking.py b/tests/test_ccr_buffered_stream_signed_thinking.py
new file mode 100644
index 000000000..b90a599d2
--- /dev/null
+++ b/tests/test_ccr_buffered_stream_signed_thinking.py
@@ -0,0 +1,219 @@
+"""Buffered-CCR streaming vs. byte-faithful passthrough (issue #2952).
+
+The buffered-CCR path is the one place the Anthropic handler changes the
+request *for its own benefit*: it flips ``stream`` to False so the reply comes
+back as one JSON document it can inspect for ``headroom_retrieve`` calls, then
+resynthesizes SSE for the client.
+
+That only works if the flip reaches the wire. When conversation history carries
+a signed ``thinking`` block, ``select_outbound_body`` forwards the client's
+original bytes instead — ``"stream": true`` and all — so upstream streams, the
+JSON parse fails, resynthesis is skipped, and the client is left with a 200 and
+nothing it can read. These tests pin the three defenses: don't take the path,
+survive the reply if we somehow do, and never cache a body in the wrong format.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+httpx = pytest.importorskip("httpx")
+
+from fastapi.testclient import TestClient  # noqa: E402
+
+from headroom.proxy.models import CacheEntry  # noqa: E402
+from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+
+RETRIEVE_TOOL = {
+    "name": "headroom_retrieve",
+    "description": "Retrieve original content",
+    "input_schema": {"type": "object", "properties": {}},
+}
+
+SIGNED_THINKING_TURN = {
+    "role": "assistant",
+    "content": [
+        {
+            "type": "thinking",
+            "thinking": "private reasoning",
+            "signature": "sig-abc123",
+        },
+        {"type": "text", "text": "Answered."},
+    ],
+}
+
+SSE_BODY = (
+    b'event: message_start\ndata: {"type":"message_start","message":{"id":"msg_1"}}\n\n'
+    b'event: message_stop\ndata: {"type":"message_stop"}\n\n'
+)
+
+
+def _config() -> ProxyConfig:
+    return ProxyConfig(
+        optimize=False,
+        cache_enabled=True,
+        rate_limit_enabled=False,
+        memory_enabled=False,
+    )
+
+
+def _body(*, with_thinking: bool) -> dict:
+    messages: list[dict] = [{"role": "user", "content": "hi"}]
+    if with_thinking:
+        messages.append(SIGNED_THINKING_TURN)
+        messages.append({"role": "user", "content": "continue"})
+    return {
+        "model": "claude-sonnet-4-20250514",
+        "max_tokens": 64,
+        "stream": True,
+        "tools": [RETRIEVE_TOOL],
+        "messages": messages,
+    }
+
+
+def _headers() -> dict[str, str]:
+    return {"Authorization": "Bearer test-key", "x-api-key": "test-key"}
+
+
+@pytest.mark.parametrize(
+    ("with_thinking", "expect_plain_streaming"),
+    [(True, True), (False, False)],
+)
+def test_signed_thinking_history_skips_the_buffered_ccr_path(
+    with_thinking: bool, expect_plain_streaming: bool
+) -> None:
+    """The buffered path is only chosen when the stream:false flip can land."""
+    calls: dict[str, object] = {}
+
+    async def fake_stream_response(url, headers, body, *args, **kwargs):  # noqa: ANN001
+        calls["stream_body"] = body
+        return fastapi.responses.StreamingResponse(iter([SSE_BODY]), media_type="text/event-stream")
+
+    async def fake_retry(method, url, headers, req_body, *args, **kwargs):  # noqa: ANN001
+        calls["buffered_body"] = json.loads(json.dumps(req_body))
+        return httpx.Response(
+            200,
+            json={
+                "id": "msg_1",
+                "type": "message",
+                "role": "assistant",
+                "model": "claude-sonnet-4-20250514",
+                "content": [{"type": "text", "text": "ok"}],
+                "stop_reason": "end_turn",
+                "usage": {"input_tokens": 10, "output_tokens": 5},
+            },
+            headers={"content-type": "application/json"},
+        )
+
+    app = create_app(_config())
+    with TestClient(app) as client:
+        client.app.state.proxy._stream_response = fake_stream_response
+        client.app.state.proxy._retry_request = fake_retry
+        resp = client.post(
+            "/v1/messages", json=_body(with_thinking=with_thinking), headers=_headers()
+        )
+
+    assert resp.status_code == 200, resp.text
+    if expect_plain_streaming:
+        # Passthrough is locked in, so we must not pretend we can buffer.
+        assert "stream_body" in calls, "expected the plain streaming path"
+        assert "buffered_body" not in calls
+        # The turn still leaves as a streaming request, matching the bytes
+        # that passthrough will actually forward.
+        assert calls["stream_body"]["stream"] is True
+    else:
+        assert "buffered_body" in calls, "expected the buffered CCR path"
+        assert calls["buffered_body"]["stream"] is False
+
+
+@pytest.mark.parametrize("upstream_delay", [0.0, 1.2], ids=["prompt", "past-keepalive"])
+def test_buffered_ccr_relays_an_unexpected_sse_reply_and_does_not_cache_it(
+    upstream_delay: float,
+) -> None:
+    """A 200 SSE reply on the buffered path reaches the client as a stream.
+
+    The delay matters: ``_BufferedCCRResponse`` commits SSE response headers
+    after a 1 s keepalive, and past that point it can only forward a result
+    that exposes a ``body_iterator``. A plain ``Response`` there degrades to a
+    bare ``event: error`` — which is what a real (multi-second) Anthropic turn
+    hit in #2952.
+    """
+
+    async def fake_retry(method, url, headers, req_body, *args, **kwargs):  # noqa: ANN001
+        if upstream_delay:
+            await asyncio.sleep(upstream_delay)
+        return httpx.Response(200, content=SSE_BODY, headers={"content-type": "text/event-stream"})
+
+    app = create_app(_config())
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy._retry_request = fake_retry
+        resp = client.post("/v1/messages", json=_body(with_thinking=False), headers=_headers())
+
+        assert resp.status_code == 200, resp.text
+        assert resp.headers["content-type"].startswith("text/event-stream")
+        assert b"message_start" in resp.content
+        # Caching SSE bytes under a key with no `stream` component is what
+        # served a stream to a buffered caller in the first place.
+        assert proxy.cache is not None
+        assert len(proxy.cache._cache) == 0, "an unparseable body must never be cached"
+
+
+def test_cache_hit_never_replays_a_foreign_content_type() -> None:
+    """A cache entry cannot hand a caller a wire format it did not ask for."""
+    body = {
+        "model": "claude-sonnet-4-20250514",
+        "max_tokens": 64,
+        "stream": False,
+        "messages": [{"role": "user", "content": "hi"}],
+    }
+    payload = json.dumps(
+        {
+            "id": "msg_1",
+            "type": "message",
+            "role": "assistant",
+            "model": "claude-sonnet-4-20250514",
+            "content": [{"type": "text", "text": "cached"}],
+            "stop_reason": "end_turn",
+            "usage": {"input_tokens": 1, "output_tokens": 1},
+        }
+    ).encode()
+
+    async def fail_retry(*args, **kwargs):  # noqa: ANN001, ANN002, ANN003
+        raise AssertionError("upstream must not be called on a cache hit")
+
+    app = create_app(_config())
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy._retry_request = fail_retry
+        key = proxy.cache._compute_key(
+            body["messages"],
+            body["model"],
+            system=None,
+            tools=None,
+            tool_choice=None,
+            temperature=None,
+            top_p=None,
+            top_k=None,
+            max_tokens=64,
+            stop=None,
+            thinking=None,
+            output_config=None,
+        )
+        proxy.cache._cache[key] = CacheEntry(
+            response_body=payload,
+            response_headers={"content-type": "text/event-stream"},
+            created_at=datetime.now(),
+            ttl_seconds=3600,
+        )
+
+        resp = client.post("/v1/messages", json=body, headers=_headers())
+
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"].startswith("application/json")
+    assert resp.json()["content"][0]["text"] == "cached"
diff --git a/tests/test_ccr_inline_resolve_handlers.py b/tests/test_ccr_inline_resolve_handlers.py
new file mode 100644
index 000000000..51cab54c6
--- /dev/null
+++ b/tests/test_ccr_inline_resolve_handlers.py
@@ -0,0 +1,173 @@
+"""Handler-level wiring for ``--ccr-inline-resolve`` (issue #2509).
+
+The pure-module tests in ``test_ccr_marker_resolution.py`` prove the
+substitution logic. These tests prove the thing that actually broke: the
+resolve call has to run on the response path *when the model never emitted a
+``headroom_retrieve`` tool call at all*. That is the whole #2509 shape —
+Headroom behind a LiteLLM guardrail hop with no tool-call turn — so any wiring
+that sits behind a ``has_ccr_tool_calls`` gate is a no-op for its own use case.
+
+Every response fixture below therefore has zero tool calls.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+httpx = pytest.importorskip("httpx")
+
+from fastapi.testclient import TestClient  # noqa: E402
+
+from headroom.cache.compression_store import (  # noqa: E402
+    get_compression_store,
+    reset_compression_store,
+)
+from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+
+ORIGINAL = "the original uncompressed content"
+
+
+@pytest.fixture(autouse=True)
+def reset_store():
+    reset_compression_store()
+    yield
+    reset_compression_store()
+
+
+def _marker() -> str:
+    hash_key = get_compression_store().store(
+        original=ORIGINAL,
+        compressed="[]",
+        original_item_count=1,
+        compressed_item_count=0,
+    )
+    return f"<<ccr:{hash_key},string,23.6KB>>"
+
+
+def _config(*, inline_resolve: bool) -> ProxyConfig:
+    # No backend -> the "Direct OpenAI API (no backend configured)" path.
+    return ProxyConfig(
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        ccr_resolve_markers_inline=inline_resolve,
+    )
+
+
+def _chat_response(marker: str) -> dict:
+    return {
+        "id": "chatcmpl-1",
+        "object": "chat.completion",
+        "model": "gpt-4o",
+        "choices": [
+            {
+                "index": 0,
+                "message": {"role": "assistant", "content": f"here it is: {marker}"},
+                "finish_reason": "stop",
+            }
+        ],
+        "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+    }
+
+
+def _responses_response(marker: str) -> dict:
+    return {
+        "id": "resp_1",
+        "object": "response",
+        "model": "gpt-4o",
+        "status": "completed",
+        "output": [
+            {
+                "type": "message",
+                "role": "assistant",
+                "content": [{"type": "output_text", "text": f"here it is: {marker}"}],
+            }
+        ],
+        "usage": {"input_tokens": 10, "output_tokens": 5, "total_tokens": 15},
+    }
+
+
+def _anthropic_response(marker: str) -> dict:
+    return {
+        "id": "msg_1",
+        "type": "message",
+        "role": "assistant",
+        "model": "claude-sonnet-4-20250514",
+        "content": [{"type": "text", "text": f"here it is: {marker}"}],
+        "stop_reason": "end_turn",
+        "usage": {"input_tokens": 10, "output_tokens": 5},
+    }
+
+
+def _run(config: ProxyConfig, path: str, body: dict, upstream: dict) -> httpx.Response:
+    async def fake_retry(method, url, headers, req_body, *args, **kwargs):
+        return httpx.Response(200, json=upstream, headers={"content-type": "application/json"})
+
+    app = create_app(config)
+    with TestClient(app) as client:
+        client.app.state.proxy._retry_request = fake_retry
+        return client.post(
+            path,
+            json=body,
+            headers={"Authorization": "Bearer test-key", "x-api-key": "test-key"},
+        )
+
+
+@pytest.mark.parametrize("inline_resolve", [True, False])
+def test_openai_chat_direct_path(inline_resolve):
+    marker = _marker()
+    resp = _run(
+        _config(inline_resolve=inline_resolve),
+        "/v1/chat/completions",
+        {"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}], "stream": False},
+        _chat_response(marker),
+    )
+
+    assert resp.status_code == 200, resp.text
+    text = resp.json()["choices"][0]["message"]["content"]
+    if inline_resolve:
+        assert text == f"here it is: {ORIGINAL}"
+    else:
+        assert text == f"here it is: {marker}"
+
+
+@pytest.mark.parametrize("inline_resolve", [True, False])
+def test_openai_responses_path(inline_resolve):
+    marker = _marker()
+    resp = _run(
+        _config(inline_resolve=inline_resolve),
+        "/v1/responses",
+        {"model": "gpt-4o", "input": "hi", "stream": False},
+        _responses_response(marker),
+    )
+
+    assert resp.status_code == 200, resp.text
+    text = resp.json()["output"][0]["content"][0]["text"]
+    if inline_resolve:
+        assert text == f"here it is: {ORIGINAL}"
+    else:
+        assert text == f"here it is: {marker}"
+
+
+@pytest.mark.parametrize("inline_resolve", [True, False])
+def test_anthropic_messages_path(inline_resolve):
+    marker = _marker()
+    resp = _run(
+        _config(inline_resolve=inline_resolve),
+        "/v1/messages",
+        {
+            "model": "claude-sonnet-4-20250514",
+            "max_tokens": 64,
+            "messages": [{"role": "user", "content": "hi"}],
+            "stream": False,
+        },
+        _anthropic_response(marker),
+    )
+
+    assert resp.status_code == 200, resp.text
+    text = resp.json()["content"][0]["text"]
+    if inline_resolve:
+        assert text == f"here it is: {ORIGINAL}"
+    else:
+        assert text == f"here it is: {marker}"
diff --git a/tests/test_ccr_marker_resolution.py b/tests/test_ccr_marker_resolution.py
new file mode 100644
index 000000000..ab2609c3b
--- /dev/null
+++ b/tests/test_ccr_marker_resolution.py
@@ -0,0 +1,99 @@
+"""Tests for inline <<ccr:...>> marker resolution (issue #2509)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from headroom.cache.compression_store import get_compression_store, reset_compression_store
+from headroom.ccr.marker_resolution import (
+    resolve_markers_in_response,
+    resolve_markers_in_text,
+)
+
+
+@pytest.fixture(autouse=True)
+def reset_store():
+    reset_compression_store()
+    yield
+    reset_compression_store()
+
+
+def _store_entry(original: str) -> str:
+    store = get_compression_store()
+    return store.store(
+        original=original,
+        compressed="[]",
+        original_item_count=1,
+        compressed_item_count=0,
+    )
+
+
+def test_resolve_markers_in_text_no_marker_is_noop():
+    assert resolve_markers_in_text("plain text, no markers here") == "plain text, no markers here"
+
+
+def test_resolve_markers_in_text_replaces_hit():
+    hash_key = _store_entry("the original uncompressed content")
+    text = f"before <<ccr:{hash_key},string,23.6KB>> after"
+
+    resolved = resolve_markers_in_text(text)
+
+    assert resolved == "before the original uncompressed content after"
+
+
+def test_resolve_markers_in_text_replaces_multiple_hits():
+    hash_a = _store_entry("AAA")
+    hash_b = _store_entry("BBB")
+    text = f"<<ccr:{hash_a},string,1KB>> and <<ccr:{hash_b},string,1KB>>"
+
+    resolved = resolve_markers_in_text(text)
+
+    assert resolved == "AAA and BBB"
+
+
+def test_resolve_markers_in_text_json_array_original_content():
+    store = get_compression_store()
+    hash_key = store.store(
+        original=json.dumps([1, 2, 3]),
+        compressed="[]",
+        original_item_count=3,
+        compressed_item_count=0,
+    )
+    text = f"<<ccr:{hash_key},array,3>>"
+
+    resolved = resolve_markers_in_text(text)
+
+    assert json.loads(resolved) == [1, 2, 3]
+
+
+def test_resolve_markers_in_text_miss_leaves_marker_with_reason():
+    text = "<<ccr:deadbeefdeadbeef,string,1KB>>"
+
+    resolved = resolve_markers_in_text(text)
+
+    assert text in resolved
+    assert "[unresolved:" in resolved
+
+
+def test_resolve_markers_in_response_walks_nested_structure():
+    hash_key = _store_entry("full tool output")
+    response = {
+        "choices": [
+            {
+                "message": {
+                    "role": "assistant",
+                    "content": f"here it is: <<ccr:{hash_key},string,1KB>>",
+                }
+            }
+        ],
+        "unrelated": 42,
+        "nested": {"list": ["a", f"<<ccr:{hash_key},string,1KB>>", "c"]},
+    }
+
+    resolved = resolve_markers_in_response(response)
+
+    assert resolved["choices"][0]["message"]["content"] == "here it is: full tool output"
+    assert resolved["nested"]["list"] == ["a", "full tool output", "c"]
+    assert resolved["unrelated"] == 42
diff --git a/tests/test_ccr_response_handler_extra.py b/tests/test_ccr_response_handler_extra.py
index 20883ee19..1e8d97d93 100644
--- a/tests/test_ccr_response_handler_extra.py
+++ b/tests/test_ccr_response_handler_extra.py
@@ -137,6 +137,27 @@ def test_create_tool_result_message_google_and_generic_formats() -> None:
     assert invalid_google["parts"][0]["functionResponse"]["response"] == {"content": "not-json"}
 
 
+def test_create_tool_result_message_google_preserves_call_id() -> None:
+    handler = CCRResponseHandler()
+    message = handler._create_tool_result_message(
+        [
+            CCRToolResult(
+                tool_call_id="call-1",
+                tool_name="headroom_retrieve",
+                content='{"count": 1}',
+                success=True,
+            )
+        ],
+        "google",
+    )
+
+    assert message["parts"][0]["functionResponse"] == {
+        "name": "headroom_retrieve",
+        "id": "call-1",
+        "response": {"count": 1},
+    }
+
+
 def test_extract_assistant_message_google_and_generic() -> None:
     handler = CCRResponseHandler()
     google_message = handler._extract_assistant_message(
@@ -299,6 +320,60 @@ def test_streaming_buffer_and_parse_sse_helpers() -> None:
     )
 
 
+def test_reconstruct_openai_response_tolerates_null_tool_calls_and_function() -> None:
+    # Some OpenAI-compatible providers put ``"tool_calls": null`` (and
+    # ``"function": null``) in a streaming delta instead of omitting the key.
+    # Only checking key presence made the reconstruction iterate ``None`` and
+    # raise ``TypeError``, aborting the whole CCR round.
+    handler = StreamingCCRHandler(CCRResponseHandler(), provider="openai")
+
+    parsed = handler._reconstruct_openai_response(
+        [
+            {"choices": [{"delta": {"content": "Hi", "tool_calls": None}}]},
+            {"choices": [{"delta": {"tool_calls": [{"index": 0, "function": None}]}}]},
+            {
+                "choices": [
+                    {
+                        "delta": {
+                            "tool_calls": [
+                                {
+                                    "index": 0,
+                                    "id": "call_1",
+                                    "function": {"name": "f", "arguments": "{}"},
+                                }
+                            ]
+                        }
+                    }
+                ]
+            },
+        ]
+    )
+
+    message = parsed["choices"][0]["message"]
+    # The null frames did not crash, and the real tool call still reconstructs.
+    assert message["content"] == "Hi"
+    assert message["tool_calls"][0]["id"] == "call_1"
+    assert message["tool_calls"][0]["function"] == {"name": "f", "arguments": "{}"}
+
+
+def test_extract_assistant_message_responses_output_null_coerces_to_list() -> None:
+    # A Responses turn with a present-but-null `output` (some gateways send this
+    # on an empty/filtered turn) must not become None: handle_response later
+    # does `current_messages.extend(...)` on it, which would raise TypeError.
+    handler = CCRResponseHandler()
+
+    assert handler._extract_assistant_message({"output": None}, "openai_responses") == {
+        "_openai_responses_output_items": []
+    }
+    # An absent output is also an empty list, and a real output passes through.
+    assert handler._extract_assistant_message({}, "openai_responses") == {
+        "_openai_responses_output_items": []
+    }
+    assert handler._extract_assistant_message(
+        {"output": [{"type": "message"}]}, "openai_responses"
+    ) == {"_openai_responses_output_items": [{"type": "message"}]}
+
+
 @pytest.mark.asyncio
 async def test_streaming_handler_process_stream_pass_through_and_ccr(
     monkeypatch: pytest.MonkeyPatch,
diff --git a/tests/test_ccr_retrieve_history_repair.py b/tests/test_ccr_retrieve_history_repair.py
new file mode 100644
index 000000000..bbd840d95
--- /dev/null
+++ b/tests/test_ccr_retrieve_history_repair.py
@@ -0,0 +1,119 @@
+"""Regression tests for the CCR headroom_retrieve history repair (#2814).
+
+A passthrough side-request (prompt-type Stop hook evaluator, /compact) replays a
+transcript whose history contains a ``headroom_retrieve`` tool_use, but the
+request's own ``tools`` array does not declare that tool. Anthropic 400s on the
+dangling reference. The repair neutralizes those history blocks so the 400 is
+structurally impossible, without breaking user/assistant alternation.
+"""
+
+from __future__ import annotations
+
+from headroom.ccr.tool_injection import CCR_TOOL_NAME
+from headroom.proxy.helpers import strip_unsupported_ccr_retrieve_blocks
+
+
+def _transcript_with_retrieve() -> list[dict]:
+    return [
+        {"role": "user", "content": [{"type": "text", "text": "read config"}]},
+        {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "Let me expand that."},
+                {
+                    "type": "tool_use",
+                    "id": "toolu_ccr_1",
+                    "name": CCR_TOOL_NAME,
+                    "input": {"hash": "abc123def456abc123def456"},
+                },
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "toolu_ccr_1",
+                    "content": "the full expanded config text",
+                }
+            ],
+        },
+        {"role": "assistant", "content": [{"type": "text", "text": "Done."}]},
+    ]
+
+
+def test_noop_when_tool_is_declared() -> None:
+    messages = _transcript_with_retrieve()
+    tools = [{"name": CCR_TOOL_NAME}]
+    out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools)
+    assert n == 0
+    assert out is messages  # identity: caller skips the write-back
+
+
+def test_noop_when_no_retrieve_history() -> None:
+    messages = [
+        {"role": "user", "content": [{"type": "text", "text": "hi"}]},
+        {"role": "assistant", "content": [{"type": "text", "text": "hello"}]},
+    ]
+    out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[])
+    assert n == 0
+    assert out is messages
+
+
+def test_neutralizes_retrieve_reference_when_tool_absent() -> None:
+    messages = _transcript_with_retrieve()
+    out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[{"name": "Bash"}])
+
+    assert n == 2  # tool_use + its paired tool_result
+    # No dangling references survive anywhere.
+    for message in out:
+        for block in message["content"]:
+            assert block.get("type") != "tool_use" or block.get("name") != CCR_TOOL_NAME
+            assert not (
+                block.get("type") == "tool_result" and block.get("tool_use_id") == "toolu_ccr_1"
+            )
+
+    # Message count and roles are unchanged (alternation intact).
+    assert [m["role"] for m in out] == [m["role"] for m in messages]
+    # The assistant's own text survives; the tool_use became a text block.
+    assistant = out[1]["content"]
+    assert assistant[0] == {"type": "text", "text": "Let me expand that."}
+    assert assistant[1]["type"] == "text"
+    # The retrieved result text is preserved, not dropped.
+    assert out[2]["content"][0] == {
+        "type": "text",
+        "text": "the full expanded config text",
+    }
+
+
+def test_leaves_foreign_tool_use_untouched() -> None:
+    messages = [
+        {
+            "role": "assistant",
+            "content": [
+                {"type": "tool_use", "id": "toolu_bash_1", "name": "Bash", "input": {"cmd": "ls"}}
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {"type": "tool_result", "tool_use_id": "toolu_bash_1", "content": "file.txt"}
+            ],
+        },
+    ]
+    out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[{"name": "Bash"}])
+    assert n == 0
+    assert out is messages
+
+
+def test_result_falls_back_to_placeholder_without_text() -> None:
+    messages = [
+        {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "id": "t1", "name": CCR_TOOL_NAME, "input": {}}],
+        },
+        {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t1", "content": []}]},
+    ]
+    out, n = strip_unsupported_ccr_retrieve_blocks(messages, tools=[])
+    assert n == 2
+    assert out[1]["content"][0] == {"type": "text", "text": "[headroom_retrieve result omitted]"}
diff --git a/tests/test_ccr_tool_always_on.py b/tests/test_ccr_tool_always_on.py
index 4bc457b62..60be59c7d 100644
--- a/tests/test_ccr_tool_always_on.py
+++ b/tests/test_ccr_tool_always_on.py
@@ -30,6 +30,7 @@ from headroom.proxy.helpers import (
     _reset_session_ccr_tracker_for_test,
     apply_session_sticky_ccr_tool,
     get_session_ccr_tracker,
+    history_references_ccr_tool,
     serialize_tool_definition_canonical,
 )
 
@@ -228,6 +229,68 @@ def test_no_session_id_falls_back_to_per_turn_decision():
     assert _has_ccr_tool(tools)
 
 
+def test_history_references_ccr_tool_detects_both_provider_shapes():
+    # Anthropic: assistant tool_use content block.
+    anthropic_hist = [
+        {"role": "user", "content": "hi"},
+        {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "name": CCR_TOOL_NAME, "id": "t1", "input": {}}],
+        },
+    ]
+    assert history_references_ccr_tool(anthropic_hist) is True
+
+    # OpenAI: assistant tool_calls[].function.name.
+    openai_hist = [
+        {
+            "role": "assistant",
+            "tool_calls": [{"id": "c1", "function": {"name": CCR_TOOL_NAME, "arguments": "{}"}}],
+        }
+    ]
+    assert history_references_ccr_tool(openai_hist) is True
+
+    # No reference, and malformed shapes must not crash.
+    assert history_references_ccr_tool([{"role": "user", "content": "hi"}]) is False
+    assert (
+        history_references_ccr_tool([{"content": None}, {"tool_calls": None}, "x", None]) is False
+    )
+    assert history_references_ccr_tool("not-a-list") is False
+
+
+def test_sessionless_history_reference_forces_reinjection():
+    """#2440: no session_id + no fresh compression, but history already
+    references headroom_retrieve → the tool definition MUST be re-injected,
+    otherwise the provider rejects the request (400 tool not found)."""
+    history = [
+        {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "name": CCR_TOOL_NAME, "id": "t1", "input": {}}],
+        }
+    ]
+
+    tools, injected = apply_session_sticky_ccr_tool(
+        provider="anthropic",
+        session_id=None,
+        request_id="r3",
+        existing_tools=None,
+        has_compressed_content_this_turn=False,
+        history_has_ccr_reference=history_references_ccr_tool(history),
+    )
+    assert injected is True
+    assert _has_ccr_tool(tools)
+
+    # No history reference and no fresh compression → still skip.
+    tools, injected = apply_session_sticky_ccr_tool(
+        provider="anthropic",
+        session_id=None,
+        request_id="r4",
+        existing_tools=None,
+        has_compressed_content_this_turn=False,
+        history_has_ccr_reference=False,
+    )
+    assert injected is False
+
+
 # ─── Byte-stable tool definition ───────────────────────────────────────
 
 
diff --git a/tests/test_ccr_tool_injection.py b/tests/test_ccr_tool_injection.py
index 6bf2ccc13..e5e5b5a76 100644
--- a/tests/test_ccr_tool_injection.py
+++ b/tests/test_ccr_tool_injection.py
@@ -11,6 +11,16 @@ from headroom.ccr import (
 )
 
 
+class _AlwaysOwnStore:
+    """Stub compression store for verify_ownership() (issue #2836) in tests
+    that only exercise injection plumbing with hand-typed marker hashes,
+    not real CompressionStore-backed storage.
+    """
+
+    def exists(self, hash_key: str, clean_expired: bool = False) -> bool:
+        return True
+
+
 class TestCCRToolDefinition:
     """Test tool definition creation for different providers."""
 
@@ -271,6 +281,10 @@ class TestCCRToolInjector:
             provider="anthropic",
             inject_tool=True,
             inject_system_instructions=True,
+            # verify_ownership() (issue #2836) requires the store to
+            # recognize the hash; this test only exercises injection
+            # plumbing, not real storage, so stub ownership as always-true.
+            compression_store=_AlwaysOwnStore(),
         )
         updated_messages, updated_tools, was_injected = injector.process_request(messages, None)
 
@@ -620,3 +634,164 @@ class TestAlternativeMarkerFormats:
 
         assert len(hashes) == 1
         assert "fedcba9876543210fedcba98" in hashes
+
+
+class TestVerifyOwnership:
+    """Regression tests for issue #2836.
+
+    Shape-only marker scanning (``scan_for_markers``) matches markers from
+    ANY context tool that happens to use the same bracket format, not just
+    Headroom's own. ``verify_ownership`` closes that gap by checking each
+    detected hash against the actual compression store before it can drive
+    retrieve-tool injection.
+    """
+
+    def test_foreign_marker_is_dropped(self):
+        """The exact repro from issue #2836: a marker Headroom never
+        created must not be adopted, even though its shape matches.
+        """
+        from headroom.cache.compression_store import reset_compression_store
+
+        reset_compression_store()
+        try:
+            foreign = (
+                "[374 items compressed to 267 (from 65 source lines). "
+                "Retrieve more: hash=ddc3d69afad7bc53fbee11e2]"
+            )
+            injector = CCRToolInjector(provider="anthropic")
+            injector.scan_for_markers([{"role": "user", "content": foreign}])
+
+            # Shape-only scan still finds it — that's the bug surface.
+            assert injector.detected_hashes == ["ddc3d69afad7bc53fbee11e2"]
+
+            injector.verify_ownership()
+
+            assert injector.detected_hashes == []
+            assert injector.has_compressed_content is False
+        finally:
+            reset_compression_store()
+
+    def test_real_hash_survives_verification(self):
+        """A hash Headroom actually stored must still be recognized."""
+        from headroom.cache.compression_store import (
+            get_compression_store,
+            reset_compression_store,
+        )
+
+        reset_compression_store()
+        try:
+            store = get_compression_store()
+            real_hash = store.store(
+                original="original content",
+                compressed="compressed content",
+                explicit_hash="abc123def456abc123def456",
+            )
+
+            marker = f"[100 items compressed to 10. Retrieve more: hash={real_hash}]"
+            injector = CCRToolInjector(provider="anthropic")
+            injector.scan_for_markers([{"role": "user", "content": marker}])
+            injector.verify_ownership()
+
+            assert injector.detected_hashes == [real_hash]
+            assert injector.has_compressed_content is True
+        finally:
+            reset_compression_store()
+
+    def test_mixed_own_and_foreign_hashes_keeps_only_own(self):
+        """One own hash and one foreign hash in the same scan — only the
+        own hash survives verification.
+        """
+        from headroom.cache.compression_store import (
+            get_compression_store,
+            reset_compression_store,
+        )
+
+        reset_compression_store()
+        try:
+            store = get_compression_store()
+            store.store(
+                original="mine",
+                compressed="mine-compressed",
+                explicit_hash="111111111111111111111111",
+            )
+            messages = [
+                {
+                    "role": "user",
+                    "content": (
+                        "[10 items compressed to 5. Retrieve more: hash=111111111111111111111111]"
+                        "\n[20 items compressed to 8. Retrieve more: hash=222222222222222222222222]"
+                    ),
+                }
+            ]
+            injector = CCRToolInjector(provider="anthropic")
+            injector.scan_for_markers(messages)
+            assert set(injector.detected_hashes) == {
+                "111111111111111111111111",
+                "222222222222222222222222",
+            }
+
+            injector.verify_ownership()
+
+            assert injector.detected_hashes == ["111111111111111111111111"]
+        finally:
+            reset_compression_store()
+
+    def test_explicit_store_takes_precedence_over_global(self):
+        """A store passed to verify_ownership() overrides the default
+        (global/request-scoped) resolution — matches the constructor's
+        compression_store field too.
+        """
+
+        class _NeverOwnStore:
+            def exists(self, hash_key, clean_expired=False):  # noqa: ANN001
+                return False
+
+        injector = CCRToolInjector(provider="anthropic", compression_store=_NeverOwnStore())
+        injector.scan_for_markers(
+            [
+                {
+                    "role": "user",
+                    "content": "[1 items compressed to 1. Retrieve more: hash=abcabcabcabcabcabcabcabc]",
+                }
+            ]
+        )
+        injector.verify_ownership()
+
+        assert injector.detected_hashes == []
+
+    def test_store_lookup_exception_is_treated_as_not_owned(self):
+        """A store lookup failure must not crash CCR verification — it
+        should drop the marker (the safe direction), not raise.
+        """
+
+        class _BrokenStore:
+            def exists(self, hash_key, clean_expired=False):  # noqa: ANN001
+                raise RuntimeError("store backend unavailable")
+
+        injector = CCRToolInjector(provider="anthropic", compression_store=_BrokenStore())
+        injector.scan_for_markers(
+            [
+                {
+                    "role": "user",
+                    "content": "[1 items compressed to 1. Retrieve more: hash=abcabcabcabcabcabcabcabc]",
+                }
+            ]
+        )
+        injector.verify_ownership()  # must not raise
+
+        assert injector.detected_hashes == []
+
+    def test_verify_ownership_is_noop_on_empty_hashes(self):
+        """No detected hashes -> verify_ownership must not touch the store
+        at all (nothing to verify).
+        """
+
+        class _ExplodingStore:
+            def exists(self, hash_key, clean_expired=False):  # noqa: ANN001
+                raise AssertionError("should not be called with no detected hashes")
+
+        injector = CCRToolInjector(provider="anthropic", compression_store=_ExplodingStore())
+        injector.scan_for_markers([{"role": "user", "content": "no markers here"}])
+        result = injector.verify_ownership()
+
+        assert result == []
diff --git a/tests/test_cli/test_init_enable_tool_search.py b/tests/test_cli/test_init_enable_tool_search.py
index de65e56ed..6606163ae 100644
--- a/tests/test_cli/test_init_enable_tool_search.py
+++ b/tests/test_cli/test_init_enable_tool_search.py
@@ -16,7 +16,8 @@ from headroom.cli import init as init_cli
 from headroom.providers.claude import install as claude_install
 
 
-def test_ensure_claude_hooks_sets_enable_tool_search(tmp_path: Path) -> None:
+def test_ensure_claude_hooks_sets_enable_tool_search(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.delenv("CLAUDE_CODE_USE_FOUNDRY", raising=False)
     settings = tmp_path / "settings.json"
     init_cli._ensure_claude_hooks(settings, profile="init-user", port=8787)
 
@@ -25,6 +26,16 @@ def test_ensure_claude_hooks_sets_enable_tool_search(tmp_path: Path) -> None:
     assert env["ENABLE_TOOL_SEARCH"] == "true"
 
 
+def test_ensure_claude_hooks_disables_tool_search_for_foundry(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_USE_FOUNDRY", "1")
+    settings = tmp_path / "settings.json"
+
+    init_cli._ensure_claude_hooks(settings, profile="init-user", port=8787)
+
+    env = json.loads(settings.read_text(encoding="utf-8"))["env"]
+    assert env["ENABLE_TOOL_SEARCH"] == "false"
+
+
 def test_ensure_claude_hooks_respects_user_tool_search_value(tmp_path: Path) -> None:
     settings = tmp_path / "settings.json"
     settings.write_text(
diff --git a/tests/test_cli/test_install_cli.py b/tests/test_cli/test_install_cli.py
index 691f12143..8e82d6ec6 100644
--- a/tests/test_cli/test_install_cli.py
+++ b/tests/test_cli/test_install_cli.py
@@ -1,11 +1,124 @@
 from __future__ import annotations
 
+from types import SimpleNamespace
+
 import click
+import pytest
 from click.testing import CliRunner
 
+from headroom.cli import install as inst
 from headroom.cli.main import main
 
 
+def test_require_manifest_resolves_single_profile_when_default_missing(monkeypatch):
+    """On an init'd machine (one profile, e.g. init-user), a bare lifecycle
+    command whose --profile defaults to 'default' resolves to the single
+    installed deployment instead of dead-ending (#2811)."""
+    only = SimpleNamespace(profile="init-user")
+    monkeypatch.delenv("HEADROOM_DEPLOYMENT_PROFILE", raising=False)
+    monkeypatch.setattr(inst, "load_manifest", lambda profile: None)
+    monkeypatch.setattr(inst, "list_manifests", lambda: [only])
+
+    assert inst._require_manifest("default") is only
+
+
+def test_require_manifest_honors_env_profile(monkeypatch):
+    """An explicit HEADROOM_DEPLOYMENT_PROFILE (exported by the runtime) selects
+    the target even when the requested profile is not installed."""
+    target = SimpleNamespace(profile="init-user")
+    monkeypatch.setenv("HEADROOM_DEPLOYMENT_PROFILE", "init-user")
+    monkeypatch.setattr(
+        inst, "load_manifest", lambda profile: target if profile == "init-user" else None
+    )
+    monkeypatch.setattr(inst, "list_manifests", lambda: [target])
+
+    assert inst._require_manifest("default") is target
+
+
+def test_require_manifest_lists_installed_profiles_when_ambiguous(monkeypatch):
+    """With several installed profiles and no signal, the error names them and
+    points at --profile instead of dead-ending on 'default'."""
+    monkeypatch.delenv("HEADROOM_DEPLOYMENT_PROFILE", raising=False)
+    monkeypatch.setattr(inst, "load_manifest", lambda profile: None)
+    monkeypatch.setattr(
+        inst,
+        "list_manifests",
+        lambda: [SimpleNamespace(profile="init-user"), SimpleNamespace(profile="ci")],
+    )
+
+    with pytest.raises(click.ClickException) as exc:
+        inst._require_manifest("default")
+    msg = str(exc.value)
+    assert "ci" in msg and "init-user" in msg and "--profile" in msg
+
+
+def _status_manifest(profile: str) -> SimpleNamespace:
+    return SimpleNamespace(
+        profile=profile,
+        preset="persistent-task",
+        runtime_kind="python",
+        supervisor_kind="none",
+        scope="user",
+        port=8787,
+        health_url="http://127.0.0.1:8787/readyz",
+        backend="anthropic",
+    )
+
+
+def test_install_status_explicit_missing_profile_is_not_redirected_to_env(monkeypatch):
+    """An explicit --profile must be honored or rejected verbatim, never
+    redirected to HEADROOM_DEPLOYMENT_PROFILE or a lone installed deployment: a
+    typo must fail even when the env profile exists (#2832 review). Only a
+    CliRunner invocation exercises the default-vs-explicit distinction."""
+    init_user = _status_manifest("init-user")
+    monkeypatch.setenv("HEADROOM_DEPLOYMENT_PROFILE", "init-user")
+    monkeypatch.setattr(inst, "load_manifest", lambda p: init_user if p == "init-user" else None)
+    monkeypatch.setattr(inst, "list_manifests", lambda: [init_user])
+
+    res = CliRunner().invoke(main, ["install", "status", "--profile", "typo"])
+
+    assert res.exit_code != 0
+    assert "typo" in res.output
+    # The error names the installed profile, but the command never operated on it.
+    assert "Preset:" not in res.output
+    assert "Status:" not in res.output
+
+
+def test_install_status_stale_env_profile_is_not_redirected_to_lone_manifest(monkeypatch):
+    """A non-empty HEADROOM_DEPLOYMENT_PROFILE is an explicit selection: if it
+    names a missing/stale profile the command must fail naming that profile, never
+    silently redirect to a different lone installed deployment (#2832 review)."""
+    init_user = _status_manifest("init-user")
+    monkeypatch.setenv("HEADROOM_DEPLOYMENT_PROFILE", "missing")
+    monkeypatch.setattr(inst, "load_manifest", lambda p: init_user if p == "init-user" else None)
+    monkeypatch.setattr(inst, "list_manifests", lambda: [init_user])
+
+    res = CliRunner().invoke(main, ["install", "status"])
+
+    assert res.exit_code != 0
+    assert "missing" in res.output
+    # Never operated on the lone init-user deployment.
+    assert "Preset:" not in res.output
+    assert "Status:" not in res.output
+
+
+def test_install_status_omitted_profile_resolves_env_deployment(monkeypatch):
+    """With --profile omitted (Click default), HEADROOM_DEPLOYMENT_PROFILE selects
+    the target so the documented bare command works on an init'd machine."""
+    init_user = _status_manifest("init-user")
+    monkeypatch.setenv("HEADROOM_DEPLOYMENT_PROFILE", "init-user")
+    monkeypatch.setattr(inst, "load_manifest", lambda p: init_user if p == "init-user" else None)
+    monkeypatch.setattr(inst, "list_manifests", lambda: [init_user])
+    monkeypatch.setattr(inst, "probe_json", lambda url: None)
+    monkeypatch.setattr(inst, "runtime_status", lambda m: "running")
+    monkeypatch.setattr(inst, "probe_ready", lambda url: True)
+
+    res = CliRunner().invoke(main, ["install", "status"])
+
+    assert res.exit_code == 0, res.output
+    assert "Profile:    init-user" in res.output
+
+
 def test_install_apply_starts_service_supervisor(monkeypatch) -> None:
     runner = CliRunner()
     calls: list[str] = []
@@ -59,6 +172,44 @@ def test_install_apply_starts_service_supervisor(monkeypatch) -> None:
     assert calls == ["save", "start_service", "apply", "save"]
 
 
+def test_install_apply_announces_windows_service_fallback(monkeypatch) -> None:
+    runner = CliRunner()
+    calls: list[str] = []
+
+    class Manifest:
+        profile = "default"
+        preset = "persistent-task"
+        runtime_kind = "python"
+        supervisor_kind = "task"
+        scope = "user"
+        health_url = "http://127.0.0.1:8787/readyz"
+        mutations: list[object] = []
+        targets: list[str] = []
+        artifacts: list[object] = []
+
+    monkeypatch.setattr("headroom.cli.install._is_windows", lambda: True)
+    monkeypatch.setattr("headroom.cli.install.build_manifest", lambda **_: Manifest())
+    monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: None)
+    monkeypatch.setattr("headroom.cli.install.install_supervisor", lambda deployment: [])
+    monkeypatch.setattr("headroom.cli.install.save_manifest", lambda deployment: None)
+    monkeypatch.setattr("headroom.cli.install.apply_mutations", lambda deployment: [])
+    monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: False)
+    monkeypatch.setattr("headroom.cli.install.runtime_status", lambda manifest: "stopped")
+    monkeypatch.setattr(
+        "headroom.cli.install.start_detached_agent", lambda profile: calls.append("start_agent")
+    )
+    monkeypatch.setattr(
+        "headroom.cli.install.wait_ready", lambda deployment, timeout_seconds=45: True
+    )
+
+    result = runner.invoke(main, ["install", "apply", "--preset", "persistent-service"])
+
+    assert result.exit_code == 0, result.output
+    assert "Falling back to persistent-task with Task Scheduler" in result.output
+    assert "sc.exe" not in result.output
+    assert calls == ["start_agent"]
+
+
 def test_install_apply_forwards_no_http2_to_build_manifest(monkeypatch) -> None:
     runner = CliRunner()
     captured: dict[str, object] = {}
diff --git a/tests/test_cli/test_unwrap_claude.py b/tests/test_cli/test_unwrap_claude.py
index 4bb79e7c8..a562e05a3 100644
--- a/tests/test_cli/test_unwrap_claude.py
+++ b/tests/test_cli/test_unwrap_claude.py
@@ -7,6 +7,7 @@ from unittest.mock import patch
 import pytest
 from click.testing import CliRunner
 
+from headroom import paths
 from headroom.cli import wrap as wrap_cli
 from headroom.cli.main import main
 
@@ -68,8 +69,14 @@ def test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy(
     home = str(tmp_path)
     monkeypatch.setenv("HOME", home)
     monkeypatch.setenv("USERPROFILE", home)
+    monkeypatch.delenv("HEADROOM_WORKSPACE_DIR", raising=False)
+    bin_dir = paths.bin_dir()
     claude_dir = tmp_path / ".claude"
     claude_dir.mkdir()
+    hooks_dir = claude_dir / "hooks"
+    hooks_dir.mkdir()
+    hook_script = hooks_dir / "rtk-rewrite.sh"
+    hook_script.write_text(f'#!/bin/sh\nexec {bin_dir / "rtk"} "$@"\n', encoding="utf-8")
     settings = claude_dir / "settings.json"
     settings.write_text(
         json.dumps(
@@ -78,9 +85,7 @@ def test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy(
                     "PreToolUse": [
                         {
                             "matcher": "Bash",
-                            "hooks": [
-                                {"type": "command", "command": str(claude_dir / "rtk-rewrite.sh")}
-                            ],
+                            "hooks": [{"type": "command", "command": str(hook_script)}],
                         }
                     ]
                 }
diff --git a/tests/test_cli/test_wrap_bridge.py b/tests/test_cli/test_wrap_bridge.py
index a948c4df8..c6c98172d 100644
--- a/tests/test_cli/test_wrap_bridge.py
+++ b/tests/test_cli/test_wrap_bridge.py
@@ -42,7 +42,8 @@ def test_wrap_codex_prepare_only_updates_config(monkeypatch, tmp_path: Path) ->
     _set_test_home(monkeypatch, tmp_path)
     runner = CliRunner()
 
-    result = runner.invoke(main, ["wrap", "codex", "--prepare-only", "--port", "8787"])
+    with patch("headroom.cli.wrap.ensure_proxy_dependencies", return_value=None):
+        result = runner.invoke(main, ["wrap", "codex", "--prepare-only", "--port", "8787"])
 
     assert result.exit_code == 0, result.output
     config_file = tmp_path / ".codex" / "config.toml"
diff --git a/tests/test_cli/test_wrap_claude.py b/tests/test_cli/test_wrap_claude.py
new file mode 100644
index 000000000..fa722eb2d
--- /dev/null
+++ b/tests/test_cli/test_wrap_claude.py
@@ -0,0 +1,59 @@
+"""Focused tests for Claude wrap tool-search defaults."""
+
+from __future__ import annotations
+
+import pytest
+
+from headroom.cli.wrap import (
+    _TOOL_SEARCH_DEFAULT,
+    _TOOL_SEARCH_ENV,
+    _configure_tool_search_env,
+)
+
+
+def test_foundry_without_override_disables_tool_search() -> None:
+    env = {"CLAUDE_CODE_USE_FOUNDRY": "1"}
+
+    result = _configure_tool_search_env(env, None)
+
+    assert result == "false"
+    assert env[_TOOL_SEARCH_ENV] == "false"
+
+
+@pytest.mark.parametrize("flag_value", ["auto", "false"])
+def test_explicit_flag_wins_in_foundry(flag_value: str) -> None:
+    env = {"CLAUDE_CODE_USE_FOUNDRY": "1"}
+
+    result = _configure_tool_search_env(env, flag_value)
+
+    assert result == flag_value
+    assert env[_TOOL_SEARCH_ENV] == flag_value
+
+
+def test_existing_environment_value_wins_in_foundry() -> None:
+    env = {"CLAUDE_CODE_USE_FOUNDRY": "1", _TOOL_SEARCH_ENV: "auto:30"}
+
+    result = _configure_tool_search_env(env, None)
+
+    assert result is None
+    assert env[_TOOL_SEARCH_ENV] == "auto:30"
+
+
+@pytest.mark.parametrize("blank", ["", "   ", "\t"])
+def test_blank_environment_uses_mode_default(blank: str) -> None:
+    foundry_env = {"CLAUDE_CODE_USE_FOUNDRY": "1", _TOOL_SEARCH_ENV: blank}
+    generic_env = {_TOOL_SEARCH_ENV: blank}
+
+    assert _configure_tool_search_env(foundry_env, None) == "false"
+    assert foundry_env[_TOOL_SEARCH_ENV] == "false"
+    assert _configure_tool_search_env(generic_env, None) == _TOOL_SEARCH_DEFAULT
+    assert generic_env[_TOOL_SEARCH_ENV] == _TOOL_SEARCH_DEFAULT
+
+
+def test_non_foundry_without_override_keeps_generic_default() -> None:
+    env: dict[str, str] = {}
+
+    result = _configure_tool_search_env(env, None)
+
+    assert result == _TOOL_SEARCH_DEFAULT
+    assert env[_TOOL_SEARCH_ENV] == _TOOL_SEARCH_DEFAULT
diff --git a/tests/test_cli/test_wrap_claude_base_url.py b/tests/test_cli/test_wrap_claude_base_url.py
index 5c252877e..591ba9c1d 100644
--- a/tests/test_cli/test_wrap_claude_base_url.py
+++ b/tests/test_cli/test_wrap_claude_base_url.py
@@ -34,6 +34,29 @@ def test_write_preserves_other_env_keys(tmp_path: Path) -> None:
     assert payload["env"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787"
 
 
+def test_tool_search_write_and_restore_reaches_daemon_worker_settings(tmp_path: Path) -> None:
+    path = _settings(tmp_path)
+    path.parent.mkdir(parents=True)
+    path.write_text(
+        json.dumps({"env": {"ENABLE_TOOL_SEARCH": "true", "KEEP": "1"}}),
+        encoding="utf-8",
+    )
+
+    previous = wrap_cli._write_claude_wrap_tool_search("false", settings_path=path)
+
+    assert previous == "true"
+    assert json.loads(path.read_text(encoding="utf-8"))["env"] == {
+        "ENABLE_TOOL_SEARCH": "false",
+        "KEEP": "1",
+    }
+
+    wrap_cli._restore_claude_wrap_tool_search(previous, settings_path=path)
+    assert json.loads(path.read_text(encoding="utf-8"))["env"] == {
+        "ENABLE_TOOL_SEARCH": "true",
+        "KEEP": "1",
+    }
+
+
 def test_write_returns_none_when_key_absent(tmp_path: Path) -> None:
     path = _settings(tmp_path)
     prev = wrap_cli._write_claude_wrap_base_url("http://127.0.0.1:8787", settings_path=path)
diff --git a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
index 4d888ba61..62efa7308 100644
--- a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
+++ b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
@@ -78,6 +78,13 @@ def _invoke_wrap_claude(
 
     monkeypatch.setattr(wrap_mod, "_write_claude_wrap_base_url", fake_write_base_url)
     monkeypatch.setattr(wrap_mod, "_restore_claude_wrap_base_url", lambda *_args, **_kwargs: None)
+
+    def fake_write_tool_search(value: str, **kwargs: object) -> None:
+        captured["write_tool_search_value"] = value
+        captured["write_tool_search_kwargs"] = kwargs
+
+    monkeypatch.setattr(wrap_mod, "_write_claude_wrap_tool_search", fake_write_tool_search)
+    monkeypatch.setattr(wrap_mod, "_restore_claude_wrap_tool_search", lambda *_a, **_k: None)
     monkeypatch.setattr(wrap_mod, "_print_telemetry_notice", lambda: None)
 
     def fake_ensure_proxy(*args: object, **kwargs: object) -> tuple[None, int]:
@@ -141,6 +148,57 @@ def test_wrap_claude_plain_mode_api_key_auth_skips_remote_control_warning(
     assert "Remote Control" not in output
 
 
+def test_wrap_claude_rejects_conflicting_auth_before_proxy_mutation(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    user_settings = tmp_path / "user-settings.json"
+    user_settings.write_text('{"env":{"ANTHROPIC_AUTH_TOKEN":"token-value"}}', encoding="utf-8")
+    monkeypatch.setattr(wrap_mod, "claude_user_settings_path", lambda: user_settings)
+    monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
+    proxy_calls: list[int] = []
+    monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda port: proxy_calls.append(port))
+
+    result = runner.invoke(
+        main,
+        ["wrap", "claude", "--no-mcp", "--no-tokensave", "--no-serena"],
+        env={"ANTHROPIC_API_KEY": "api-value"},
+    )
+
+    assert result.exit_code != 0
+    assert "both ANTHROPIC_API_KEY" in result.output
+    assert "shell environment" in result.output
+    assert str(user_settings) in result.output
+    assert "api-value" not in result.output
+    assert "token-value" not in result.output
+    assert proxy_calls == []
+
+
+def test_wrap_claude_includes_shared_project_settings_in_auth_precedence(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    user_settings = tmp_path / "user-settings.json"
+    user_settings.write_text("{}", encoding="utf-8")
+    project_dir = tmp_path / ".claude"
+    project_dir.mkdir()
+    shared_settings = project_dir / "settings.json"
+    shared_settings.write_text('{"env":{"ANTHROPIC_AUTH_TOKEN":"token-value"}}', encoding="utf-8")
+    monkeypatch.setattr(wrap_mod, "claude_user_settings_path", lambda: user_settings)
+    monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
+
+    result = runner.invoke(
+        main,
+        ["wrap", "claude", "--no-mcp", "--no-tokensave", "--no-serena"],
+        env={"ANTHROPIC_API_KEY": "api-value"},
+    )
+
+    assert result.exit_code != 0
+    assert str(shared_settings) in result.output
+    assert "api-value" not in result.output
+    assert "token-value" not in result.output
+
+
 def test_wrap_claude_sibling_note_accurate_under_1m_and_tool_search_optouts(
     runner: CliRunner, monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -160,6 +218,46 @@ def test_wrap_claude_sibling_note_accurate_under_1m_and_tool_search_optouts(
     assert "kept on" not in output
 
 
+def test_wrap_claude_1m_adds_suffix_to_passthrough_model_flag(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # #2915: Claude Code's --model CLI flag outranks ANTHROPIC_MODEL, so with
+    # both --1m and an explicit --model the env-var [1m] suffix is shadowed and
+    # the window silently caps at 200k. The wrapper must add the suffix to the
+    # pass-through flag so the 1M window actually activates.
+    captured, output = _invoke_wrap_claude(
+        runner,
+        monkeypatch,
+        env={},
+        extra_args=("--1m", "--model", "opusplan"),
+    )
+    assert captured["child_cmd"] == ["/usr/bin/claude", "--model", "opusplan[1m]"]
+    # The banner reports what actually takes effect, not the shadowed env value.
+    assert "--model opusplan[1m]" in output
+
+
+def test_wrap_claude_1m_adds_suffix_to_equals_model_flag(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured, _output = _invoke_wrap_claude(
+        runner,
+        monkeypatch,
+        env={},
+        extra_args=("--1m", "--model=opusplan"),
+    )
+    assert captured["child_cmd"] == ["/usr/bin/claude", "--model=opusplan[1m]"]
+
+
+def test_wrap_claude_1m_without_model_flag_still_uses_env(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # No pass-through --model: ANTHROPIC_MODEL carries the suffix as before, and
+    # the launched command is untouched.
+    captured, _output = _invoke_wrap_claude(runner, monkeypatch, env={}, extra_args=("--1m",))
+    assert captured["child_cmd"] == ["/usr/bin/claude"]
+    assert captured["child_env"]["ANTHROPIC_MODEL"].endswith("[1m]")
+
+
 def test_wrap_claude_tool_search_banner_line_still_accurate_when_active(
     runner: CliRunner, monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -169,6 +267,24 @@ def test_wrap_claude_tool_search_banner_line_still_accurate_when_active(
     assert "on-demand tool loading kept on" in output
     assert "keeps it on for this session" in output
     assert "DISABLED per your setting" not in output
+    assert _captured["write_tool_search_value"] == "true"
+
+
+def test_wrap_claude_foundry_persists_disabled_tool_search_for_workers(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured, output = _invoke_wrap_claude(
+        runner,
+        monkeypatch,
+        env={
+            "CLAUDE_CODE_USE_FOUNDRY": "1",
+            "ANTHROPIC_FOUNDRY_BASE_URL": "https://tenant.services.ai.azure.com/anthropic",
+        },
+    )
+
+    assert captured["child_env"]["ENABLE_TOOL_SEARCH"] == "false"
+    assert captured["write_tool_search_value"] == "false"
+    assert "on-demand tool loading DISABLED" in output
 
 
 def test_wrap_claude_vertex_passes_custom_base_url_to_proxy_before_child_redirect(
@@ -370,6 +486,36 @@ def test_start_proxy_clears_inherited_vertex_target_env(
     assert "VERTEX_TARGET_API_URL" not in proxy_env
 
 
+def test_start_proxy_sets_pythonsafepath_to_avoid_cwd_shadow(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """`python -m headroom.cli` prepends the launch cwd to sys.path, so running
+    wrap from a directory that contains a `headroom/` folder (a clone of this
+    repo) shadows the installed wheel with the raw source tree, which has no
+    compiled `headroom._core`, and the proxy dies importing it (#2793). The
+    subprocess env must set PYTHONSAFEPATH=1 to disable that cwd prepend."""
+    fake_proc = _FakeProxyProcess()
+    captured: dict[str, Any] = {}
+
+    monkeypatch.setattr(wrap_mod, "_get_log_path", lambda: tmp_path / "proxy.log")
+    monkeypatch.setattr(wrap_mod, "_check_proxy", lambda _port: True)
+    monkeypatch.setattr(wrap_mod.time, "sleep", lambda _seconds: None)
+
+    def fake_popen(cmd: list[str], **kwargs: object) -> _FakeProxyProcess:
+        captured["cmd"] = cmd
+        captured["kwargs"] = kwargs
+        return fake_proc
+
+    monkeypatch.setattr(wrap_mod.subprocess, "Popen", fake_popen)
+
+    proc = wrap_mod._start_proxy(8787, agent_type="claude")
+
+    assert proc is fake_proc
+    assert captured["kwargs"]["env"]["PYTHONSAFEPATH"] == "1"
+    # Still launched as a module of the installed package.
+    assert captured["cmd"][:4] == [wrap_mod.sys.executable, "-m", "headroom.cli", "proxy"]
+
+
 def test_ensure_proxy_restarts_idle_proxy_for_vertex_api_url_mismatch(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.py
index 38da91c73..bbade27ab 100644
--- a/tests/test_cli/test_wrap_codex.py
+++ b/tests/test_cli/test_wrap_codex.py
@@ -40,6 +40,24 @@ def runner() -> CliRunner:
     return CliRunner()
 
 
+_PROXY_DEP_TESTS = frozenset(
+    {
+        "test_wrap_codex_aborts_before_mutating_config_when_proxy_deps_missing",
+        "test_wrap_codex_skips_proxy_dependency_check_with_no_proxy",
+    }
+)
+
+
+@pytest.fixture(autouse=True)
+def _skip_wrap_proxy_dependency_gate_unless_exercised(
+    request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Wrap-codex integration tests run in the base CI env without [proxy] extras."""
+    if request.node.name in _PROXY_DEP_TESTS:
+        return
+    monkeypatch.setattr("headroom.cli.wrap.ensure_proxy_dependencies", lambda: None)
+
+
 # ---------------------------------------------------------------------------
 # Unit tests: helpers operating on ~/.codex/config.toml
 # ---------------------------------------------------------------------------
@@ -990,6 +1008,55 @@ def test_wrap_codex_prepare_only_creates_backup_and_config(
     assert backup.read_text(encoding="utf-8") == original
 
 
+def test_wrap_codex_aborts_before_mutating_config_when_proxy_deps_missing(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _set_test_home(monkeypatch, tmp_path)
+    config_file = tmp_path / ".codex" / "config.toml"
+    config_file.parent.mkdir(parents=True)
+    original = 'model_provider = "openai"\n'
+    config_file.write_text(original, encoding="utf-8")
+
+    with patch("headroom.cli.wrap.ensure_proxy_dependencies", side_effect=SystemExit(1)):
+        result = runner.invoke(
+            main,
+            ["wrap", "codex", "--prepare-only", "--no-serena", "--port", "8787"],
+        )
+
+    assert result.exit_code == 1, result.output
+    assert config_file.read_text(encoding="utf-8") == original
+    assert "[mcp_servers.headroom]" not in config_file.read_text(encoding="utf-8")
+    assert not (tmp_path / ".codex" / "config.toml.headroom-backup").exists()
+
+
+def test_wrap_codex_skips_proxy_dependency_check_with_no_proxy(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _set_test_home(monkeypatch, tmp_path)
+    config_file = tmp_path / ".codex" / "config.toml"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text('model_provider = "openai"\n', encoding="utf-8")
+
+    with patch(
+        "headroom.cli.wrap.ensure_proxy_dependencies",
+        side_effect=AssertionError("should not run with --no-proxy"),
+    ):
+        result = runner.invoke(
+            main,
+            [
+                "wrap",
+                "codex",
+                "--prepare-only",
+                "--no-proxy",
+                "--no-serena",
+                "--port",
+                "8787",
+            ],
+        )
+
+    assert result.exit_code == 0, result.output
+
+
 def test_wrap_codex_registers_mcp_when_codex_home_does_not_exist_yet(
     runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
diff --git a/tests/test_cli/test_wrap_copilot.py b/tests/test_cli/test_wrap_copilot.py
index cc4fe724c..98f261f09 100644
--- a/tests/test_cli/test_wrap_copilot.py
+++ b/tests/test_cli/test_wrap_copilot.py
@@ -279,6 +279,78 @@ def test_wrap_copilot_prefers_existing_oauth_session(
     assert f"COPILOT_PROVIDER_API_URL={DEFAULT_API_URL}" in captured["env_vars_display"]
 
 
+@pytest.mark.parametrize(
+    ("model", "expected_wire_api"),
+    [
+        ("gpt-5.4", "responses"),
+        ("gpt-4.1", "completions"),
+    ],
+)
+def test_wrap_copilot_oauth_defaults_wire_api_for_selected_model(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    monkeypatch: pytest.MonkeyPatch,
+    model: str,
+    expected_wire_api: str,
+) -> None:
+    """OAuth sessions use the same model-aware wire API default as subscriptions."""
+    _wrap_cli, main = wrap_modules
+    _clear_copilot_env(monkeypatch)
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with (
+        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
+        patch("headroom.cli.wrap.resolve_client_bearer_token", return_value="gho-existing"),
+        patch("headroom.cli.wrap.has_oauth_auth", return_value=True),
+        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
+    ):
+        result = runner.invoke(
+            main,
+            ["wrap", "copilot", "--no-rtk", "--", "--model", model],
+        )
+
+    assert result.exit_code == 0, result.output
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_WIRE_API"] == expected_wire_api
+    assert f"COPILOT_PROVIDER_WIRE_API={expected_wire_api}" in captured["env_vars_display"]
+
+
+@pytest.mark.parametrize("wire_api", ["completions", "responses"])
+def test_wrap_copilot_oauth_honors_existing_wire_api(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    monkeypatch: pytest.MonkeyPatch,
+    wire_api: str,
+) -> None:
+    _wrap_cli, main = wrap_modules
+    _clear_copilot_env(monkeypatch)
+    monkeypatch.setenv("COPILOT_PROVIDER_WIRE_API", wire_api)
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with (
+        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
+        patch("headroom.cli.wrap.resolve_client_bearer_token", return_value="gho-existing"),
+        patch("headroom.cli.wrap.has_oauth_auth", return_value=True),
+        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
+    ):
+        result = runner.invoke(
+            main,
+            ["wrap", "copilot", "--no-rtk", "--", "--model", "gpt-5.4"],
+        )
+
+    assert result.exit_code == 0, result.output
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_WIRE_API"] == wire_api
+
+
 def test_wrap_copilot_subscription_uses_github_auth_without_provider_key(
     runner: CliRunner,
     wrap_modules: tuple[types.ModuleType, click.Group],
diff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.py
index a1366b47e..2fad26a26 100644
--- a/tests/test_cli/test_wrap_helpers.py
+++ b/tests/test_cli/test_wrap_helpers.py
@@ -16,6 +16,7 @@ import errno
 import json
 import os
 import signal
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
@@ -109,6 +110,35 @@ def test_wrap_claude_allows_claude_print_short_flag_in_passthrough_args() -> Non
     assert result.exit_code == 0, result.output
 
 
+# ---------------------------------------------------------------------------
+# _apply_1m_to_claude_args — add the [1m] suffix to an explicit pass-through
+# --model so it survives Claude Code's CLI-over-env precedence (#2915).
+# ---------------------------------------------------------------------------
+def test_apply_1m_rewrites_model_flag_value() -> None:
+    args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model", "opusplan"))
+    assert args == ("--model", "opusplan[1m]")
+    assert rewritten == "opusplan[1m]"
+
+
+def test_apply_1m_rewrites_equals_model_flag() -> None:
+    args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model=opusplan",))
+    assert args == ("--model=opusplan[1m]",)
+    assert rewritten == "opusplan[1m]"
+
+
+def test_apply_1m_is_idempotent_on_already_suffixed_model() -> None:
+    args, rewritten = wrap_mod._apply_1m_to_claude_args(("--model", "opusplan[1m]"))
+    assert args == ("--model", "opusplan[1m]")
+    assert rewritten == "opusplan[1m]"
+
+
+def test_apply_1m_noop_without_model_flag() -> None:
+    original = ("--permission-mode", "auto", "--resume")
+    args, rewritten = wrap_mod._apply_1m_to_claude_args(original)
+    assert args == original
+    assert rewritten is None
+
+
 # ---------------------------------------------------------------------------
 # _run_proxy_only_watcher — must print banner, call setup callback, install
 # signal handlers, and clean up. Heavily mocked since the real watcher
@@ -788,3 +818,43 @@ class TestFindAvailablePort:
         )
         with pytest.raises(RuntimeError, match="No available port found"):
             wrap_mod._find_available_port(8787, max_attempts=3)
+
+
+def test_ensure_proxy_serializes_startup_per_port(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A normal wrap must enter the per-port startup critical section."""
+    events: list[object] = []
+
+    @contextmanager
+    def fake_lock(port: int):
+        events.append(("lock-enter", port))
+        try:
+            yield
+        finally:
+            events.append(("lock-exit", port))
+
+    monkeypatch.setattr(wrap_mod, "_proxy_start_lock", fake_lock)
+    monkeypatch.setattr(
+        wrap_mod,
+        "_ensure_proxy_unlocked",
+        lambda port, no_proxy, **kwargs: events.append(("ensure", port, no_proxy)) or (None, port),
+    )
+
+    assert wrap_mod._ensure_proxy(8787, False) == (None, 8787)
+    assert events == [("lock-enter", 8787), ("ensure", 8787, False), ("lock-exit", 8787)]
+
+
+def test_no_proxy_does_not_create_startup_lock(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Explicit --no-proxy reuses an existing service without taking the lock."""
+    entered = False
+
+    @contextmanager
+    def fail_lock(port: int):
+        nonlocal entered
+        entered = True
+        yield
+
+    monkeypatch.setattr(wrap_mod, "_proxy_start_lock", fail_lock)
+    monkeypatch.setattr(wrap_mod, "_ensure_proxy_unlocked", lambda *args, **kwargs: (None, 8787))
+
+    assert wrap_mod._ensure_proxy(8787, True) == (None, 8787)
+    assert entered is False
diff --git a/tests/test_cli/test_wrap_opencode.py b/tests/test_cli/test_wrap_opencode.py
index f7cdaf1e5..ee0bea009 100644
--- a/tests/test_cli/test_wrap_opencode.py
+++ b/tests/test_cli/test_wrap_opencode.py
@@ -20,6 +20,16 @@ def _no_retired_context_tool_env(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
 
 
+@pytest.fixture(autouse=True)
+def _mock_ensure_proxy(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Wrap-opencode tests should not spawn a real proxy subprocess in CI."""
+
+    def fake_ensure_proxy(port: int, no_proxy: bool, **kwargs):  # noqa: ANN002, ANN003
+        return None, port
+
+    monkeypatch.setattr(wrap_mod, "_ensure_proxy", fake_ensure_proxy)
+
+
 @pytest.fixture
 def runner() -> CliRunner:
     return CliRunner()
@@ -364,6 +374,35 @@ def test_wrap_opencode_missing_binary_errors_clearly(
     assert "'opencode' not found in PATH" in result.output
 
 
+def test_wrap_opencode_missing_binary_does_not_mutate_config(
+    runner: CliRunner,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A missing opencode binary must not leave memory side-effects behind (#1614 class).
+
+    The MCP/Serena registrations are already gated on ``registrar.detect()``, but
+    the ``--memory`` injections (AGENTS.md, the .headroom dir, the memory MCP
+    config) are not -- they ran unconditionally before the binary check. Verify
+    the binary first, like claude/codex/goose/omp, so an absent tool cannot write
+    those and then error with nothing launched.
+    """
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+    _set_test_home(monkeypatch, tmp_path)
+
+    agents_md = tmp_path / "AGENTS.md"
+    headroom_dir = tmp_path / ".headroom"
+
+    with patch.object(wrap_mod.shutil, "which", return_value=None):
+        result = runner.invoke(main, ["wrap", "opencode", "--memory"])
+
+    assert result.exit_code == 1
+    assert "'opencode' not found in PATH" in result.output
+    assert not agents_md.exists(), "AGENTS.md was created before the missing-binary check"
+    assert not headroom_dir.exists(), ".headroom dir was created before the missing-binary check"
+
+
 def test_wrap_opencode_prepare_only_injects_config(
     runner: CliRunner,
     tmp_path: Path,
diff --git a/tests/test_cli/test_wrap_serena_boost.py b/tests/test_cli/test_wrap_serena_boost.py
index 8a29086b3..cc3f4ef81 100644
--- a/tests/test_cli/test_wrap_serena_boost.py
+++ b/tests/test_cli/test_wrap_serena_boost.py
@@ -107,80 +107,311 @@ def _stub_uvx(monkeypatch: pytest.MonkeyPatch, present: bool = True) -> None:
     )
 
 
+class _FakeProc:
+    """Minimal stand-in for the ``serena project index`` child process."""
+
+    def __init__(
+        self,
+        *,
+        returncode: int = 0,
+        stderr: str = "",
+        communicate_error: BaseException | None = None,
+    ) -> None:
+        self.pid = 4242
+        self.returncode = returncode
+        self.stdin = None
+        self.stdout = None
+        self.stderr = None
+        self._stderr = stderr
+        self._communicate_error = communicate_error
+        self.killed = False
+        self.waited = False
+
+    def communicate(self, timeout: float | None = None) -> tuple[str, str]:
+        if self._communicate_error is not None:
+            raise self._communicate_error
+        return "", self._stderr
+
+    def kill(self) -> None:
+        self.killed = True
+
+    def wait(self, timeout: float | None = None) -> int:
+        self.waited = True
+        return self.returncode
+
+
+def _stub_popen(monkeypatch: pytest.MonkeyPatch, proc: _FakeProc) -> Mock:
+    mock_popen = Mock(return_value=proc)
+    monkeypatch.setattr(wrap_cli.subprocess, "Popen", mock_popen)
+    return mock_popen
+
+
 def test_preindex_runs_serena_in_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.chdir(tmp_path)
     _stub_uvx(monkeypatch)
-    mock_run = Mock(
-        return_value=subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
-    )
-    monkeypatch.setattr(wrap_cli, "run", mock_run)
+    mock_popen = _stub_popen(monkeypatch, _FakeProc())
 
     wrap_cli._index_serena_project()
 
-    mock_run.assert_called_once()
-    args, kwargs = mock_run.call_args
+    mock_popen.assert_called_once()
+    args, kwargs = mock_popen.call_args
     cmd = args[0]
     assert cmd[0] == "uvx"
     assert cmd[-3:] == ["serena", "project", "index"]
-    assert "git+https://github.com/oraios/serena" in cmd
+    # PyPI package with prebuilt wheels, not the git source (#2871).
+    assert "serena-agent" in cmd
+    assert "git+https://github.com/oraios/serena" not in cmd
     assert kwargs["cwd"] == str(tmp_path)  # invoked in the project cwd
-    assert "timeout" in kwargs  # timeout-guarded
+
+
+def test_preindex_is_timeout_guarded(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    _stub_uvx(monkeypatch)
+    proc = _FakeProc()
+    _stub_popen(monkeypatch, proc)
+    seen: list[float | None] = []
+    monkeypatch.setattr(
+        proc, "communicate", lambda timeout=None: (seen.append(timeout), ("", ""))[1]
+    )
+
+    wrap_cli._index_serena_project()
+
+    assert seen == [wrap_cli._SERENA_INDEX_TIMEOUT]
+
+
+def test_preindex_never_inherits_stdin(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Serena prompts ``[y/N]`` behind a captured stdout; stdin must be EOF (#2938)."""
+    monkeypatch.chdir(tmp_path)
+    _stub_uvx(monkeypatch)
+    mock_popen = _stub_popen(monkeypatch, _FakeProc())
+
+    wrap_cli._index_serena_project()
+
+    assert mock_popen.call_args.kwargs["stdin"] == subprocess.DEVNULL
+
+
+def test_preindex_child_gets_its_own_process_group(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Without this the ``uvx`` grandchild survives the timeout kill (#2938)."""
+    monkeypatch.chdir(tmp_path)
+    _stub_uvx(monkeypatch)
+    mock_popen = _stub_popen(monkeypatch, _FakeProc())
+
+    wrap_cli._index_serena_project()
+
+    kwargs = mock_popen.call_args.kwargs
+    if wrap_cli.sys.platform == "win32":
+        assert kwargs["creationflags"] & subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        assert kwargs["start_new_session"] is True
 
 
 def test_preindex_skips_without_uvx(monkeypatch: pytest.MonkeyPatch) -> None:
     _stub_uvx(monkeypatch, present=False)
-    mock_run = Mock(side_effect=AssertionError("run must not be called without uvx"))
-    monkeypatch.setattr(wrap_cli, "run", mock_run)
+    mock_popen = Mock(side_effect=AssertionError("Popen must not be called without uvx"))
+    monkeypatch.setattr(wrap_cli.subprocess, "Popen", mock_popen)
 
     wrap_cli._index_serena_project()  # no exception
 
-    mock_run.assert_not_called()
+    mock_popen.assert_not_called()
 
 
-def test_preindex_timeout_is_non_fatal(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_preindex_timeout_kills_the_tree_and_is_non_fatal(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
     _stub_uvx(monkeypatch)
+    proc = _FakeProc(communicate_error=subprocess.TimeoutExpired(cmd="serena", timeout=1))
+    _stub_popen(monkeypatch, proc)
+    killed: list[object] = []
+    monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
+
+    wrap_cli._index_serena_project(verbose=True)  # must not propagate
+
+    assert killed == [proc]
+
+
+def test_preindex_generic_error_kills_the_tree_and_is_non_fatal(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    _stub_uvx(monkeypatch)
+    proc = _FakeProc(communicate_error=RuntimeError("boom"))
+    _stub_popen(monkeypatch, proc)
+    killed: list[object] = []
+    monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
+
+    wrap_cli._index_serena_project(verbose=True)  # must not propagate
+
+    assert killed == [proc]
+
+
+def test_preindex_spawn_failure_is_non_fatal(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    _stub_uvx(monkeypatch)
+    monkeypatch.setattr(wrap_cli.subprocess, "Popen", Mock(side_effect=OSError("no exec")))
+
+    wrap_cli._index_serena_project(verbose=True)  # must not propagate
+
+
+# ---------------------------------------------------------------------------
+# _kill_serena_index_tree — no orphaned `serena project index` on timeout
+# ---------------------------------------------------------------------------
+
+
+def test_kill_tree_signals_the_group_on_posix(monkeypatch: pytest.MonkeyPatch) -> None:
+    if wrap_cli.sys.platform == "win32":
+        pytest.skip("POSIX process groups")
+    proc = _FakeProc()
+    signalled: list[tuple[int, int]] = []
+    monkeypatch.setattr(wrap_cli.os, "getpgid", lambda pid: pid)
+    monkeypatch.setattr(wrap_cli.os, "killpg", lambda pgid, sig: signalled.append((pgid, sig)))
+
+    wrap_cli._kill_serena_index_tree(proc)  # type: ignore[arg-type]
+
+    assert signalled == [(proc.pid, wrap_cli.signal.SIGKILL)]
+    assert proc.killed and proc.waited  # backstop still runs
+
+
+def test_kill_tree_walks_the_tree_on_windows(monkeypatch: pytest.MonkeyPatch) -> None:
+    if wrap_cli.sys.platform != "win32":
+        pytest.skip("Windows taskkill")
+    proc = _FakeProc()
+    calls: list[list[str]] = []
     monkeypatch.setattr(
-        wrap_cli,
+        wrap_cli.subprocess,
         "run",
-        Mock(side_effect=subprocess.TimeoutExpired(cmd="serena", timeout=1)),
+        lambda cmd, **kw: calls.append(cmd),
     )
-    # Must not propagate.
-    wrap_cli._index_serena_project(verbose=True)
+
+    wrap_cli._kill_serena_index_tree(proc)  # type: ignore[arg-type]
+
+    assert calls == [["taskkill", "/F", "/T", "/PID", str(proc.pid)]]
+    assert proc.killed and proc.waited
 
 
-def test_preindex_generic_error_is_non_fatal(monkeypatch: pytest.MonkeyPatch) -> None:
-    _stub_uvx(monkeypatch)
-    monkeypatch.setattr(wrap_cli, "run", Mock(side_effect=RuntimeError("boom")))
-    # Must not propagate.
-    wrap_cli._index_serena_project(verbose=True)
+def test_kill_tree_survives_a_dead_child(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Cleanup is best-effort: a child that already exited must not raise."""
+    proc = _FakeProc()
+    monkeypatch.setattr(proc, "kill", Mock(side_effect=ProcessLookupError()))
+    if wrap_cli.sys.platform == "win32":
+        monkeypatch.setattr(wrap_cli.subprocess, "run", Mock(side_effect=OSError("gone")))
+    else:
+        monkeypatch.setattr(wrap_cli.os, "getpgid", Mock(side_effect=ProcessLookupError()))
+
+    wrap_cli._kill_serena_index_tree(proc)  # type: ignore[arg-type]
 
 
 # ---------------------------------------------------------------------------
 # _serena_project_skip_reason — keep per-project setup off non-project roots
 # ---------------------------------------------------------------------------
 
+_NO_PROJECT_YML = "no .serena/project.yml yet — Serena will create it and index on demand"
+
+
+def _with_project_yml(root: Path) -> Path:
+    """Give *root* the ``.serena/project.yml`` Serena writes on first MCP start."""
+    (root / ".serena").mkdir(parents=True, exist_ok=True)
+    (root / ".serena" / "project.yml").write_text("project_name: demo\n")
+    return root
+
 
 def test_skip_reason_none_for_ordinary_project(tmp_path: Path) -> None:
+    _with_project_yml(tmp_path)
+
     assert wrap_cli._serena_project_skip_reason(tmp_path) is None
 
 
 def test_skip_reason_none_for_normal_checkout(tmp_path: Path) -> None:
     (tmp_path / ".git").mkdir()  # real checkout: .git is a directory
+    _with_project_yml(tmp_path)
 
     assert wrap_cli._serena_project_skip_reason(tmp_path) is None
 
 
 def test_skip_reason_flags_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(Path, "home", classmethod(lambda cls: tmp_path))
+    _with_project_yml(tmp_path)
 
     assert wrap_cli._serena_project_skip_reason(tmp_path) == "$HOME is not a project"
 
 
 def test_skip_reason_flags_linked_worktree(tmp_path: Path) -> None:
     (tmp_path / ".git").write_text("gitdir: /repo/.git/worktrees/wt\n")
+    _with_project_yml(tmp_path)
 
     assert wrap_cli._serena_project_skip_reason(tmp_path) == "linked git worktree"
 
 
+def test_skip_reason_flags_missing_project_yml(tmp_path: Path) -> None:
+    """The pre-index cannot succeed here — Serena would stop on a hidden prompt (#2938)."""
+    assert wrap_cli._serena_project_skip_reason(tmp_path) == _NO_PROJECT_YML
+
+
+def test_skip_reason_flags_serena_dir_without_project_yml(tmp_path: Path) -> None:
+    (tmp_path / ".serena").mkdir()  # cache dir exists, config does not
+
+    assert wrap_cli._serena_project_skip_reason(tmp_path) == _NO_PROJECT_YML
+
+
 def test_skip_reason_survives_unresolvable_root(tmp_path: Path) -> None:
-    assert wrap_cli._serena_project_skip_reason(tmp_path / "gone") is None
+    # Missing directory: resolves fine (non-strict), no config, no exception.
+    assert wrap_cli._serena_project_skip_reason(tmp_path / "gone") == _NO_PROJECT_YML
+
+
+# ---------------------------------------------------------------------------
+# _setup_serena_mcp wiring — the launch path must not wait on a doomed index
+# ---------------------------------------------------------------------------
+
+
+class _FakeRegistrar:
+    """Just enough registrar for the post-registration branch of the setup."""
+
+    name = "claude"
+    display_name = "Claude"
+
+    def detect(self) -> bool:
+        return True
+
+    def get_server(self, server_name: str) -> None:
+        return None
+
+    def register_server(self, spec: object, *, force: bool = False) -> object:
+        from headroom.mcp_registry.base import RegisterResult, RegisterStatus
+
+        return RegisterResult(RegisterStatus.REGISTERED, "registered")
+
+
+def _drive_setup(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> list[str]:
+    """Run ``_setup_serena_mcp`` in *tmp_path*, returning pre-index call markers."""
+    monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
+    monkeypatch.chdir(tmp_path)
+    _stub_uvx(monkeypatch)
+    monkeypatch.setattr(wrap_cli, "_inject_serena_instructions", lambda *a, **k: True)
+    calls: list[str] = []
+    monkeypatch.setattr(wrap_cli, "_index_serena_project", lambda **k: calls.append("indexed"))
+
+    wrap_cli._setup_serena_mcp(_FakeRegistrar(), context="claude-code", verbose=True)
+    return calls
+
+
+def test_setup_does_not_preindex_a_project_without_serena_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """First wrap of a fresh project: launch immediately, do not wait out the timeout."""
+    calls = _drive_setup(tmp_path, monkeypatch)
+
+    assert calls == []
+    assert "skipping pre-index" in capsys.readouterr().out
+
+
+def test_setup_preindexes_once_serena_config_exists(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Second wrap: Serena's MCP server has written project.yml, so the index can run."""
+    _with_project_yml(tmp_path)
+
+    assert _drive_setup(tmp_path, monkeypatch) == ["indexed"]
diff --git a/tests/test_cli/test_wrap_vscode.py b/tests/test_cli/test_wrap_vscode.py
index 6d3496991..fccab5cac 100644
--- a/tests/test_cli/test_wrap_vscode.py
+++ b/tests/test_cli/test_wrap_vscode.py
@@ -66,6 +66,7 @@ def test_wrap_vscode_no_configure_prints_transparent_settings(tmp_path: Path) ->
     assert result.exit_code == 0, result.output
     assert not path.exists()
     assert "overrideProxyUrl" in result.output
+    assert "overrideCapiUrl" in result.output
     assert "overrideAuthType" in result.output
 
 
diff --git a/tests/test_cli/test_wrap_vscode_claude.py b/tests/test_cli/test_wrap_vscode_claude.py
index ec3a37662..e57029240 100644
--- a/tests/test_cli/test_wrap_vscode_claude.py
+++ b/tests/test_cli/test_wrap_vscode_claude.py
@@ -25,7 +25,7 @@ def test_wrap_vscode_claude_configures_actual_port(tmp_path: Path) -> None:
     assert result.exit_code == 0, result.output
     env = json.loads(path.read_text(encoding="utf-8"))["env"]
     assert env["ANTHROPIC_BASE_URL"].startswith("http://127.0.0.1:9999/p/")
-    assert env["ENABLE_TOOL_SEARCH"] == "true"
+    assert env["ENABLE_TOOL_SEARCH"] == "false"
     assert "Reload VS Code" in result.output
     assert captured["agent_type"] == "claude"
 
diff --git a/tests/test_cli_doctor.py b/tests/test_cli_doctor.py
index 6bce283e8..6fe42581d 100644
--- a/tests/test_cli_doctor.py
+++ b/tests/test_cli_doctor.py
@@ -390,6 +390,17 @@ class TestShellEnv:
         env = {"ANTHROPIC_BASE_URL": "https://api.anthropic.com"}
         assert check_shell_env(env, 8787).status == WARN
 
+    def test_ollama_launch_url_names_the_collision(self):
+        # `ollama launch claude` points Claude Code at Ollama's :11434, which
+        # outranks the persistent Headroom route (issue #2199). The diagnostic
+        # must name Ollama, not tell the user to re-probe port 11434.
+        env = {"ANTHROPIC_BASE_URL": "http://127.0.0.1:11434"}
+        result = check_shell_env(env, 8787)
+        assert result.status == WARN
+        assert "Ollama" in result.summary
+        assert "#2199" in (result.hint or "")
+        assert "--port 11434" not in (result.hint or "")
+
 
 class TestSavings:
     def test_from_stats_passes_with_totals(self, tmp_path):
@@ -535,7 +546,16 @@ class TestDoctorCommand:
         monkeypatch.setattr(doctor_mod, "codex_config_path", lambda: tmp_path / "config.toml")
         monkeypatch.setattr(doctor_mod, "savings_path", lambda: tmp_path / "savings.json")
         monkeypatch.setattr(doctor_mod, "list_manifests", lambda: [])
-        for var in ("ANTHROPIC_BASE_URL", "OPENAI_BASE_URL", "HEADROOM_PORT"):
+        for var in (
+            "ANTHROPIC_API_KEY",
+            "ANTHROPIC_AUTH_TOKEN",
+            "ANTHROPIC_BASE_URL",
+            "CLAUDE_CODE_USE_BEDROCK",
+            "CLAUDE_CODE_USE_FOUNDRY",
+            "CLAUDE_CODE_USE_VERTEX",
+            "OPENAI_BASE_URL",
+            "HEADROOM_PORT",
+        ):
             monkeypatch.delenv(var, raising=False)
         return tmp_path
 
@@ -555,6 +575,23 @@ class TestDoctorCommand:
         assert result.exit_code == 2
         assert "not reachable" in result.output
 
+    def test_conflicting_claude_auth_is_a_redacted_failure(self, runner, isolated, monkeypatch):
+        settings = isolated / "settings.json"
+        settings.write_text('{"env":{"ANTHROPIC_AUTH_TOKEN":"token-value"}}', encoding="utf-8")
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "api-value")
+        monkeypatch.setattr(doctor_mod, "probe_json", self._probe(None, None))
+
+        result = runner.invoke(main, ["doctor", "--json"])
+
+        assert result.exit_code == 2
+        payload = json.loads(result.output)
+        auth = next(check for check in payload["checks"] if check["name"] == "claude auth")
+        assert auth["status"] == "fail"
+        assert "shell environment" in auth["summary"]
+        assert str(settings) in auth["summary"]
+        assert "api-value" not in result.output
+        assert "token-value" not in result.output
+
     def test_warnings_only_exits_1(self, runner, isolated, monkeypatch):
         monkeypatch.setattr(doctor_mod, "probe_json", self._probe(LIVEZ_OK, STATS_OK))
         monkeypatch.setattr(doctor_mod, "get_version", lambda: "0.26.0")
@@ -565,6 +602,7 @@ class TestDoctorCommand:
     def test_remote_control_warning_exits_1(self, runner, isolated, monkeypatch):
         monkeypatch.setattr(doctor_mod, "probe_json", self._probe(LIVEZ_OK, STATS_OK))
         monkeypatch.setattr(doctor_mod, "get_version", lambda: "0.26.0")
+        monkeypatch.setattr(doctor_mod, "detect_claude_code_version", lambda: None)
         (isolated / "settings.json").write_text(
             json.dumps({"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"}}),
             encoding="utf-8",
diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.py
index b160ea8d8..0142e8fc9 100644
--- a/tests/test_cli_learn.py
+++ b/tests/test_cli_learn.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 from pathlib import Path
 from types import SimpleNamespace
@@ -472,3 +473,59 @@ def test_learn_target_ignored_for_unsupported_agent(
 
     assert result.exit_code == 0, result.output
     assert "Note: --target is not supported for codex" in result.output
+
+
+@pytest.mark.parametrize(("enabled", "expected"), [(True, "live"), (False, "blocked")])
+def test_activate_output_shaper_reports_effective_rollout_decision(
+    monkeypatch: pytest.MonkeyPatch, enabled: bool, expected: str
+) -> None:
+    import urllib.request
+
+    from headroom.cli.learn import _activate_output_shaper
+
+    class Response:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *args):
+            return False
+
+        def read(self) -> bytes:
+            return json.dumps(
+                {
+                    "rollout": {
+                        "features": [
+                            {"name": "proxy_output_shaper", "enabled": enabled},
+                        ]
+                    }
+                }
+            ).encode()
+
+    monkeypatch.setattr(urllib.request, "urlopen", lambda *args, **kwargs: Response())
+
+    status, port = _activate_output_shaper(9876)
+
+    assert status == expected
+    assert port == 9876
+
+
+def test_activate_output_shaper_handles_malformed_response(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import urllib.request
+
+    from headroom.cli.learn import _activate_output_shaper
+
+    class Response:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *args):
+            return False
+
+        def read(self) -> bytes:
+            return b"not-json"
+
+    monkeypatch.setattr(urllib.request, "urlopen", lambda *args, **kwargs: Response())
+
+    assert _activate_output_shaper(9876) == ("error", 9876)
diff --git a/tests/test_cli_memory_index_sync.py b/tests/test_cli_memory_index_sync.py
new file mode 100644
index 000000000..b4578d05f
--- /dev/null
+++ b/tests/test_cli_memory_index_sync.py
@@ -0,0 +1,508 @@
+"""Tests for memory CLI index synchronization (issue #2856).
+
+Verifies that headroom memory delete/prune/purge/edit remove stale entries
+from the FTS5 and vector search indexes, not just from the primary store.
+
+Vector index tests require sqlite-vec and are skipped when it is not installed.
+They exercise the real SQLiteVectorIndex schema (vec0 virtual table) so that
+the extension-aware connection path in _remove_from_search_indexes and
+_clear_all_search_indexes is exercised rather than a plain-table stand-in.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+from click.testing import CliRunner
+
+import headroom.cli.memory as memory_cli
+from headroom.cli.main import main
+from headroom.cli.memory import (
+    _clear_all_search_indexes,
+    _remove_from_search_indexes,
+)
+from headroom.memory.adapters.fts5 import FTS5TextIndex
+from headroom.memory.adapters.sqlite import SQLiteMemoryStore
+from headroom.memory.models import Memory
+
+# ---------------------------------------------------------------------------
+# sqlite-vec availability guard
+# ---------------------------------------------------------------------------
+
+try:
+    from headroom.memory.adapters.sqlite_vector import (
+        SQLiteVectorIndex,
+        is_sqlite_vec_available,
+    )
+
+    SQLITE_VEC_AVAILABLE = is_sqlite_vec_available()
+except ImportError:
+    SQLITE_VEC_AVAILABLE = False
+    SQLiteVectorIndex = None  # type: ignore[assignment,misc]
+
+requires_sqlite_vec = pytest.mark.skipif(
+    not SQLITE_VEC_AVAILABLE, reason="sqlite-vec not available"
+)
+
+_VEC_DIM = 4  # small dimension keeps test seeding fast
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_memory(memory_id: str, content: str = "test content") -> Memory:
+    return Memory(
+        id=memory_id,
+        content=content,
+        user_id="test-user",
+    )
+
+
+def _seed_fts(db_path: Path, memories: list[Memory]) -> None:
+    """Index memories into the FTS5 table."""
+    fts = FTS5TextIndex(db_path=str(db_path))
+    for mem in memories:
+        asyncio.run(fts.index_memory(mem))
+
+
+def _seed_vector(db_path: Path, memory_ids: list[str]) -> None:
+    """Seed the vector DB using the real SQLiteVectorIndex (requires sqlite-vec).
+
+    Creates the true vec0 virtual-table schema so the helpers under test
+    exercise the extension-aware connection path.
+    """
+    vector_db = db_path.parent / f"{db_path.stem}_vectors.db"
+    index = SQLiteVectorIndex(dimension=_VEC_DIM, db_path=str(vector_db))
+    for mid in memory_ids:
+        embedding = list(
+            np.random.default_rng(abs(hash(mid))).standard_normal(_VEC_DIM).astype(float)
+        )
+        mem = Memory(id=mid, content="test", user_id="u", embedding=embedding)
+        asyncio.run(index.index(mem))
+
+
+def _fts_count(db_path: Path) -> int:
+    with sqlite3.connect(str(db_path)) as conn:
+        return conn.execute("SELECT COUNT(*) FROM memory_fts").fetchone()[0]
+
+
+def _fts_ids(db_path: Path) -> set[str]:
+    with sqlite3.connect(str(db_path)) as conn:
+        rows = conn.execute("SELECT memory_id FROM memory_fts").fetchall()
+    return {r[0] for r in rows}
+
+
+def _vector_ids(db_path: Path) -> set[str]:
+    """Read surviving memory_ids from the metadata table (regular, no extension needed)."""
+    vector_db = db_path.parent / f"{db_path.stem}_vectors.db"
+    if not vector_db.exists():
+        return set()
+    with sqlite3.connect(str(vector_db)) as conn:
+        rows = conn.execute("SELECT memory_id FROM vec_metadata").fetchall()
+    return {r[0] for r in rows}
+
+
+# ---------------------------------------------------------------------------
+# _remove_from_search_indexes — FTS5 (no sqlite-vec required)
+# ---------------------------------------------------------------------------
+
+
+def test_remove_from_search_indexes_clears_fts_entries(tmp_path):
+    db_path = tmp_path / "memory.db"
+    mems = [_make_memory(f"id-{i}") for i in range(3)]
+    _seed_fts(db_path, mems)
+    assert _fts_count(db_path) == 3
+
+    _remove_from_search_indexes(str(db_path), ["id-0", "id-2"])
+
+    assert _fts_ids(db_path) == {"id-1"}
+
+
+def test_remove_from_search_indexes_no_vector_db_is_noop(tmp_path):
+    db_path = tmp_path / "memory.db"
+    mems = [_make_memory("id-0")]
+    _seed_fts(db_path, mems)
+
+    # No vector DB → should not raise
+    _remove_from_search_indexes(str(db_path), ["id-0"])
+
+    assert _fts_count(db_path) == 0
+
+
+def test_remove_from_search_indexes_empty_list_is_noop(tmp_path):
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [_make_memory("id-0")])
+    assert _fts_count(db_path) == 1
+
+    _remove_from_search_indexes(str(db_path), [])
+
+    assert _fts_count(db_path) == 1
+
+
+def test_remove_from_search_indexes_absent_optional_indexes_is_noop(tmp_path):
+    """A primary-only store must not fail after its mutation already succeeded."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    asyncio.run(store.save(_make_memory("id-0")))
+
+    assert _remove_from_search_indexes(str(db_path), ["id-0"]) is True
+    assert _clear_all_search_indexes(str(db_path)) is True
+
+
+def test_empty_uninitialized_vector_database_is_noop_without_sqlite_vec(tmp_path, monkeypatch):
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    asyncio.run(store.save(_make_memory("id-0")))
+    (tmp_path / "memory_vectors.db").touch()
+    monkeypatch.setitem(sys.modules, "sqlite_vec", None)
+
+    assert _remove_from_search_indexes(str(db_path), ["id-0"]) is True
+    assert _clear_all_search_indexes(str(db_path)) is True
+
+
+# ---------------------------------------------------------------------------
+# _remove_from_search_indexes — vector index (real vec0 schema, requires sqlite-vec)
+# ---------------------------------------------------------------------------
+
+
+@requires_sqlite_vec
+def test_remove_from_search_indexes_clears_vector_entries(tmp_path):
+    """Exercise the real vec0 virtual-table schema so the extension-aware
+    connection path in _remove_from_search_indexes is covered."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [])  # ensure memory.db exists
+    _seed_vector(db_path, ["id-0", "id-1", "id-2"])
+    assert _vector_ids(db_path) == {"id-0", "id-1", "id-2"}
+
+    _remove_from_search_indexes(str(db_path), ["id-0", "id-2"])
+
+    assert _vector_ids(db_path) == {"id-1"}
+
+
+@requires_sqlite_vec
+def test_remove_from_search_indexes_no_vector_rows_to_delete_is_noop(tmp_path):
+    """IDs not present in the vector index must be silently skipped."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [])
+    _seed_vector(db_path, ["id-0"])
+    assert _vector_ids(db_path) == {"id-0"}
+
+    _remove_from_search_indexes(str(db_path), ["id-99"])  # not in index
+
+    assert _vector_ids(db_path) == {"id-0"}
+
+
+# ---------------------------------------------------------------------------
+# _clear_all_search_indexes — FTS5 (no sqlite-vec required)
+# ---------------------------------------------------------------------------
+
+
+def test_clear_all_search_indexes_removes_all_fts_entries(tmp_path):
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [_make_memory(f"id-{i}") for i in range(5)])
+    assert _fts_count(db_path) == 5
+
+    _clear_all_search_indexes(str(db_path))
+
+    assert _fts_count(db_path) == 0
+
+
+def test_clear_all_search_indexes_no_vector_db_is_noop(tmp_path):
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [_make_memory("id-0")])
+
+    _clear_all_search_indexes(str(db_path))
+
+    assert _fts_count(db_path) == 0  # FTS cleared; no vector DB is fine
+
+
+# ---------------------------------------------------------------------------
+# _clear_all_search_indexes — vector index (real vec0 schema, requires sqlite-vec)
+# ---------------------------------------------------------------------------
+
+
+@requires_sqlite_vec
+def test_clear_all_search_indexes_removes_all_vector_entries(tmp_path):
+    """Exercise the real vec0 virtual-table schema so the extension-aware
+    connection path in _clear_all_search_indexes is covered."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [])
+    _seed_vector(db_path, ["id-0", "id-1"])
+    assert _vector_ids(db_path) == {"id-0", "id-1"}
+
+    _clear_all_search_indexes(str(db_path))
+
+    assert _vector_ids(db_path) == set()
+
+
+# ---------------------------------------------------------------------------
+# Integration: CLI commands wire up index sync correctly
+# ---------------------------------------------------------------------------
+
+
+def test_delete_command_removes_from_fts(tmp_path):
+    """Simulate delete command: delete_batch then _remove_from_search_indexes."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    mem = _make_memory("abc123")
+    asyncio.run(store.save(mem))
+    _seed_fts(db_path, [mem])
+    assert _fts_count(db_path) == 1
+
+    asyncio.run(store.delete_batch(["abc123"]))
+    _remove_from_search_indexes(str(db_path), ["abc123"])
+
+    assert _fts_count(db_path) == 0
+
+
+@requires_sqlite_vec
+def test_delete_command_removes_from_vector_index(tmp_path):
+    """Simulate delete command end-to-end with the real vec0 schema."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    mem = _make_memory("abc123")
+    asyncio.run(store.save(mem))
+    _seed_fts(db_path, [mem])
+    _seed_vector(db_path, ["abc123"])
+    assert _vector_ids(db_path) == {"abc123"}
+
+    asyncio.run(store.delete_batch(["abc123"]))
+    _remove_from_search_indexes(str(db_path), ["abc123"])
+
+    assert _fts_count(db_path) == 0
+    assert _vector_ids(db_path) == set()
+
+
+def test_purge_command_clears_fts(tmp_path):
+    """Simulate purge command: clear_all then _clear_all_search_indexes."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    for i in range(3):
+        asyncio.run(store.save(_make_memory(f"id-{i}")))
+    _seed_fts(db_path, [_make_memory(f"id-{i}") for i in range(3)])
+    assert _fts_count(db_path) == 3
+
+    asyncio.run(store.clear_all())
+    _clear_all_search_indexes(str(db_path))
+
+    assert _fts_count(db_path) == 0
+
+
+@requires_sqlite_vec
+def test_purge_command_clears_vector_index(tmp_path):
+    """Simulate purge command end-to-end with the real vec0 schema."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    for i in range(3):
+        asyncio.run(store.save(_make_memory(f"id-{i}")))
+    _seed_fts(db_path, [_make_memory(f"id-{i}") for i in range(3)])
+    _seed_vector(db_path, [f"id-{i}" for i in range(3)])
+    assert _vector_ids(db_path) == {"id-0", "id-1", "id-2"}
+
+    asyncio.run(store.clear_all())
+    _clear_all_search_indexes(str(db_path))
+
+    assert _fts_count(db_path) == 0
+    assert _vector_ids(db_path) == set()
+
+
+# ---------------------------------------------------------------------------
+# Failure-path: return value and exit-code impact
+# ---------------------------------------------------------------------------
+
+
+def test_remove_from_search_indexes_fts_failure_returns_false(tmp_path):
+    """When FTS5 delete raises, the function returns False (not True)."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [_make_memory("id-0")])
+
+    # sqlite3 is imported locally inside the helper so we patch the global module.
+    original_connect = sqlite3.connect
+    call_count = [0]
+
+    def failing_connect(path, **kwargs):
+        call_count[0] += 1
+        if call_count[0] == 1:  # first call is the FTS5 db open
+            raise sqlite3.OperationalError("simulated FTS5 failure")
+        return original_connect(path, **kwargs)
+
+    with patch("sqlite3.connect", side_effect=failing_connect):
+        result = _remove_from_search_indexes(str(db_path), ["id-0"])
+
+    assert result is False
+
+
+def test_remove_from_search_indexes_sqlite_vec_missing_returns_false(tmp_path):
+    """When sqlite_vec is absent and a vector DB exists, returns False."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [])
+    # Create a non-empty vector DB file so the code doesn't short-circuit.
+    vector_db = tmp_path / "memory_vectors.db"
+    vector_db.write_bytes(b"placeholder")
+
+    # Remove sqlite_vec from sys.modules so `import sqlite_vec` raises ImportError.
+    with patch.dict(sys.modules, {"sqlite_vec": None}):
+        result = _remove_from_search_indexes(str(db_path), ["id-0"])
+
+    assert result is False
+
+
+def test_clear_all_search_indexes_fts_failure_returns_false(tmp_path):
+    """When FTS5 DELETE raises, _clear_all_search_indexes returns False."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [_make_memory("id-0")])
+
+    original_connect = sqlite3.connect
+    call_count = [0]
+
+    def failing_connect(path, **kwargs):
+        call_count[0] += 1
+        if call_count[0] == 1:
+            raise sqlite3.OperationalError("simulated FTS5 failure")
+        return original_connect(path, **kwargs)
+
+    with patch("sqlite3.connect", side_effect=failing_connect):
+        result = _clear_all_search_indexes(str(db_path))
+
+    assert result is False
+
+
+def test_clear_all_search_indexes_sqlite_vec_missing_returns_false(tmp_path):
+    """When sqlite_vec is absent and a vector DB exists, returns False."""
+    db_path = tmp_path / "memory.db"
+    _seed_fts(db_path, [])
+    vector_db = tmp_path / "memory_vectors.db"
+    vector_db.write_bytes(b"placeholder")
+
+    with patch.dict(sys.modules, {"sqlite_vec": None}):
+        result = _clear_all_search_indexes(str(db_path))
+
+    assert result is False
+
+
+def test_reindex_pages_through_complete_store(tmp_path, monkeypatch):
+    """Records beyond the first page remain represented in rebuilt FTS."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    memories = [_make_memory(f"id-{i}", f"content {i}") for i in range(5)]
+    for memory in memories:
+        asyncio.run(store.save(memory))
+    _seed_fts(db_path, memories[:2])
+    monkeypatch.setattr(memory_cli, "_REINDEX_PAGE_SIZE", 2)
+
+    result = CliRunner().invoke(main, ["memory", "reindex", "--db-path", str(db_path)])
+
+    assert result.exit_code == 0, result.output
+    assert _fts_ids(db_path) == {memory.id for memory in memories}
+    assert "Re-indexed 5/5 memories" in result.output
+
+
+@requires_sqlite_vec
+def test_reindex_keeps_valid_vectors_beyond_first_page(tmp_path, monkeypatch):
+    """Complete primary IDs, not one page, determine vector orphans."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    memories = [_make_memory(f"id-{i}", f"content {i}") for i in range(5)]
+    for memory in memories:
+        asyncio.run(store.save(memory))
+    _seed_vector(db_path, [memory.id for memory in memories] + ["orphan"])
+    monkeypatch.setattr(memory_cli, "_REINDEX_PAGE_SIZE", 2)
+
+    result = CliRunner().invoke(main, ["memory", "reindex", "--db-path", str(db_path)])
+
+    assert result.exit_code == 0, result.output
+    assert _vector_ids(db_path) == {memory.id for memory in memories}
+
+
+def test_delete_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch):
+    """The real Click command must not report a partially synced delete as success."""
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    memory = _make_memory("abc123")
+    asyncio.run(store.save(memory))
+    monkeypatch.setattr(memory_cli, "_remove_from_search_indexes", lambda *_args: False)
+
+    result = CliRunner().invoke(
+        main,
+        ["memory", "delete", memory.id, "--force", "--db-path", str(db_path)],
+    )
+
+    assert result.exit_code == 1
+    assert asyncio.run(store.get(memory.id)) is None
+    assert "index sync incomplete" in result.output
+
+
+def test_edit_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch):
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    memory = _make_memory("abc123", "before")
+    asyncio.run(store.save(memory))
+    monkeypatch.setattr(memory_cli, "_remove_from_search_indexes", lambda *_args: False)
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "memory",
+            "edit",
+            memory.id,
+            "--content",
+            "after",
+            "--db-path",
+            str(db_path),
+        ],
+    )
+
+    assert result.exit_code == 1
+    assert asyncio.run(store.get(memory.id)).content == "after"
+    assert "index sync incomplete" in result.output
+
+
+def test_prune_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch):
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    memory = _make_memory("abc123")
+    asyncio.run(store.save(memory))
+    monkeypatch.setattr(memory_cli, "_remove_from_search_indexes", lambda *_args: False)
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "memory",
+            "prune",
+            "--low-importance",
+            "1.0",
+            "--force",
+            "--db-path",
+            str(db_path),
+        ],
+    )
+
+    assert result.exit_code == 1
+    assert asyncio.run(store.get(memory.id)) is None
+    assert "index sync incomplete" in result.output
+
+
+def test_purge_command_exits_nonzero_when_index_sync_fails(tmp_path, monkeypatch):
+    db_path = tmp_path / "memory.db"
+    store = SQLiteMemoryStore(str(db_path))
+    memory = _make_memory("abc123")
+    asyncio.run(store.save(memory))
+    monkeypatch.setattr(memory_cli, "_clear_all_search_indexes", lambda *_args: False)
+
+    result = CliRunner().invoke(
+        main,
+        ["memory", "purge", "--confirm", "--db-path", str(db_path)],
+        input="y\n",
+    )
+
+    assert result.exit_code == 1
+    assert asyncio.run(store.get(memory.id)) is None
+    assert "index sync incomplete" in result.output
diff --git a/tests/test_cli_proxy_improvements.py b/tests/test_cli_proxy_improvements.py
index e400ae35b..aa5d58eb8 100644
--- a/tests/test_cli_proxy_improvements.py
+++ b/tests/test_cli_proxy_improvements.py
@@ -299,32 +299,58 @@ class TestMemoryTopKValidation:
 class TestMissingProxyDepsError:
     """When proxy dependencies are absent the CLI should print an actionable error and exit 1."""
 
-    def test_import_error_exits_nonzero(self, runner: CliRunner) -> None:
-        with patch.dict(
-            "sys.modules",
-            {"headroom.proxy.server": None},
+    @pytest.mark.proxy_dependency_gate
+    def test_proxy_command_exits_when_mcp_missing(
+        self, runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        import builtins
+
+        real_import = builtins.__import__
+
+        def fake_import(
+            name: str,
+            globals: dict | None = None,
+            locals: dict | None = None,
+            fromlist: tuple = (),
+            level: int = 0,
         ):
-            result = runner.invoke(main, ["proxy"])
-        # Click CliRunner may raise SystemExit or catch it; exit code must be non-zero
-        assert result.exit_code != 0
+            if name == "mcp":
+                raise ImportError("No module named 'mcp'")
+            return real_import(name, globals, locals, fromlist, level)
 
-    def test_import_error_message_is_actionable(self, runner: CliRunner) -> None:
-        """The error message should tell the user how to fix the problem."""
-        original_import = (
-            __builtins__.__import__ if hasattr(__builtins__, "__import__") else __import__
-        )
+        monkeypatch.setattr(builtins, "__import__", fake_import)
+        result = runner.invoke(main, ["proxy"])
+        assert result.exit_code == 1, result.output
+        assert "pip install headroom-ai[proxy]" in result.output
+        assert "No module named 'mcp'" in result.output
 
-        def patched_import(name, *args, **kwargs):
-            if name == "headroom.proxy.server":
-                raise ImportError("No module named 'headroom.proxy.server'")
-            return original_import(name, *args, **kwargs)
+    @pytest.mark.proxy_dependency_gate
+    def test_ensure_proxy_dependencies_exits_when_fastapi_missing(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        import builtins
 
-        with patch("builtins.__import__", side_effect=patched_import):
-            result = runner.invoke(main, ["proxy"])
+        from headroom.cli.proxy import ensure_proxy_dependencies
 
-        # Either exit code 1 or output with actionable guidance
-        # (some test environments may shadow the import differently)
-        assert result.exit_code != 0 or "proxy" in result.output.lower()
+        real_import = builtins.__import__
+
+        def fake_import(
+            name: str,
+            globals: dict | None = None,
+            locals: dict | None = None,
+            fromlist: tuple = (),
+            level: int = 0,
+        ):
+            if name == "fastapi":
+                raise ImportError("No module named 'fastapi'")
+            return real_import(name, globals, locals, fromlist, level)
+
+        monkeypatch.setattr(builtins, "__import__", fake_import)
+
+        with pytest.raises(SystemExit) as exc_info:
+            ensure_proxy_dependencies()
+
+        assert exc_info.value.code == 1
 
 
 class TestKeyboardInterruptExitCode:
diff --git a/tests/test_cli_update.py b/tests/test_cli_update.py
index 372649461..8f3ea107f 100644
--- a/tests/test_cli_update.py
+++ b/tests/test_cli_update.py
@@ -40,7 +40,16 @@ def test_detect_editable(monkeypatch):
 
 
 def test_detect_docker(monkeypatch):
+    # A bare /.dockerenv container whose system interpreter owns the install
+    # (no venv / pipx / uv / user-site) still refuses. When an install method
+    # owns it, ownership wins over the container environment (#2816) -- see
+    # test_update_helpers.test_venv_inside_bare_dockerenv_still_self_updates.
+    monkeypatch.delenv("HEADROOM_IN_DOCKER", raising=False)
     monkeypatch.setattr(up, "_in_docker", lambda: True)
+    monkeypatch.setattr(up, "_in_virtualenv", lambda: False)
+    monkeypatch.setattr(up, "_is_user_site_install", lambda loc: False)
+    monkeypatch.setattr(up.sys, "prefix", "/usr")
+    monkeypatch.setattr(up.sys, "executable", "/usr/bin/python3")
     m = up.detect_install_method()
     assert m.kind == "docker" and m.can_self_update is False
 
diff --git a/tests/test_codex_ws_compression_scheduler.py b/tests/test_codex_ws_compression_scheduler.py
index 69b842285..7561c9b2b 100644
--- a/tests/test_codex_ws_compression_scheduler.py
+++ b/tests/test_codex_ws_compression_scheduler.py
@@ -300,30 +300,14 @@ def test_concurrent_compression_has_no_semaphore_tail() -> None:
     )
 
     assert not errors, f"Got {len(errors)} errors; first: {errors[0].error}"
-    ratio = p99 / max(p50, 1)
     SEMAPHORE_P99_CEILING_MS = 1_000.0
     assert p99 < SEMAPHORE_P99_CEILING_MS, (
         f"p99 is {p99:.0f}ms; expected < {SEMAPHORE_P99_CEILING_MS:.0f}ms on "
         "uniform-size workload. The pre-fix semaphore baseline was ~2433ms."
     )
-    # The p99/p50 ratio only signals contention when the tail is also
-    # *absolutely* large. On a fast/quiet runner p50 rounds toward 0ms, so the
-    # ratio collapses to "p99 in ms" and a few milliseconds of ordinary
-    # scheduler jitter reads as a spurious multiple (e.g. p50=0ms, p99=5ms →
-    # ~5×) that has nothing to do with the semaphore. The deleted semaphore
-    # produced a tail of *tens* of milliseconds (and ~27×); a healthy run keeps
-    # p99 in the single-digit-ms range regardless of ratio. So only treat a high
-    # ratio as a regression once p50 is measurable and p99 clears a noise floor.
-    # Hosted CI can occasionally park one worker for a few dozen milliseconds
-    # even when the compression path is healthy; the semaphore regression this
-    # test guards against had a seconds-scale p99 and is still bounded by the
-    # hard p99 guard above.
-    SEMAPHORE_TAIL_FLOOR_MS = 75.0
-    assert p50 < 1.0 or ratio < 4.0 or p99 < SEMAPHORE_TAIL_FLOOR_MS, (
-        f"p99/p50 ratio is {ratio:.1f}× (p50={p50:.0f}ms, p99={p99:.0f}ms). "
-        f"Expected < 4× on uniform-size workload once p50 is measurable and p99 clears "
-        f"the {SEMAPHORE_TAIL_FLOOR_MS:.0f}ms noise floor — a high ratio with a large "
-        f"absolute tail means the semaphore-induced contention tail may be back. "
-        f"Pre-fix baseline ratio on this same workload shape was ~27× regardless "
-        f"of CPU speed."
-    )
+    # Do not add a p99/p50 wall-clock ratio here. A hosted runner can park one
+    # worker independently of this code path, making an otherwise healthy
+    # 2ms/76ms distribution look like a 35x contention tail. The property is
+    # covered structurally above (the semaphore and nested executor must stay
+    # absent), while this absolute ceiling still rejects the measured 2433ms
+    # pre-fix behavior without pretending scheduler jitter is product state.
diff --git a/tests/test_compression_cache.py b/tests/test_compression_cache.py
index 20cfc82cc..3a8f04efe 100644
--- a/tests/test_compression_cache.py
+++ b/tests/test_compression_cache.py
@@ -17,6 +17,116 @@ def small_cache() -> CompressionCache:
     return CompressionCache(max_entries=3)
 
 
+class TestCompressionCacheRetention:
+    def test_stable_hashes_are_bounded(self) -> None:
+        cache = CompressionCache(max_entries=3)
+        hashes = [CompressionCache.content_hash(f"stable-{index}") for index in range(4)]
+
+        for content_hash in hashes:
+            cache.mark_stable(content_hash)
+
+        assert len(cache._stable_hashes) == 3
+        assert hashes[0] not in cache._stable_hashes
+        assert hashes[-1] in cache._stable_hashes
+
+    def test_first_seen_is_bounded(self) -> None:
+        cache = CompressionCache(max_entries=3)
+        hashes = [CompressionCache.content_hash(f"first-seen-{index}") for index in range(4)]
+
+        for content_hash in hashes:
+            cache.should_defer_compression(content_hash)
+
+        assert len(cache._first_seen) == 3
+        assert hashes[0] not in cache._first_seen
+        assert hashes[-1] in cache._first_seen
+
+    def test_expired_first_seen_starts_new_window(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        cache = CompressionCache(max_entries=3)
+        content_hash = CompressionCache.content_hash("repeated content")
+        timestamps = iter([1_000.0, 1_271.0, 1_272.0])
+
+        monkeypatch.setattr(
+            "headroom.cache.compression_cache.time.time",
+            lambda: next(timestamps),
+        )
+
+        assert (
+            cache.should_defer_compression(
+                content_hash,
+                ttl_seconds=300,
+                batch_window=30,
+            )
+            is False
+        )
+        assert (
+            cache.should_defer_compression(
+                content_hash,
+                ttl_seconds=300,
+                batch_window=30,
+            )
+            is False
+        )
+        assert cache._first_seen[content_hash] == 1_271.0
+        assert (
+            cache.should_defer_compression(
+                content_hash,
+                ttl_seconds=300,
+                batch_window=30,
+            )
+            is True
+        )
+
+    def test_evicted_stable_hash_does_not_extend_frozen_prefix(self) -> None:
+        cache = CompressionCache(max_entries=1)
+        old_content = "old stable tool output"
+        new_content = "new stable tool output"
+
+        cache.mark_stable(CompressionCache.content_hash(old_content))
+        cache.mark_stable(CompressionCache.content_hash(new_content))
+
+        messages = [
+            {"role": "user", "content": "start"},
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": "tool-1",
+                        "content": old_content,
+                    }
+                ],
+            },
+            {"role": "user", "content": "follow up"},
+        ]
+
+        assert cache.compute_frozen_count(messages) == 1
+
+    def test_concurrent_bookkeeping_stays_bounded(self) -> None:
+        import threading
+
+        cache = CompressionCache(max_entries=50)
+        errors: list[Exception] = []
+
+        def worker(thread_id: int) -> None:
+            try:
+                for index in range(100):
+                    content_hash = CompressionCache.content_hash(f"thread-{thread_id}-{index}")
+                    cache.mark_stable(content_hash)
+                    cache.should_defer_compression(content_hash)
+            except Exception as exc:  # pragma: no cover
+                errors.append(exc)
+
+        threads = [threading.Thread(target=worker, args=(index,)) for index in range(8)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join()
+
+        assert errors == []
+        assert len(cache._stable_hashes) <= cache.max_entries
+        assert len(cache._first_seen) <= cache.max_entries
+
+
 class TestCompressionCache:
     def test_cache_miss_returns_none(self, cache: CompressionCache) -> None:
         h = CompressionCache.content_hash("some content")
diff --git a/tests/test_context_tool_cleanup.py b/tests/test_context_tool_cleanup.py
index 5b2e709ea..a5a2a42fe 100644
--- a/tests/test_context_tool_cleanup.py
+++ b/tests/test_context_tool_cleanup.py
@@ -11,6 +11,8 @@ else.
 from __future__ import annotations
 
 import json
+import os
+import sys
 
 import pytest
 
@@ -37,6 +39,19 @@ def _write(path, content):
 
 
 def test_removes_hooks_for_both_tools_but_keeps_user_hooks(home):
+    bin_dir = paths.bin_dir()
+    hooks_dir = home / ".claude" / "hooks"
+    # Managed: a script whose body execs the Headroom-installed binary.
+    managed_script = _write(
+        hooks_dir / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n',
+    )
+    # User-owned: same marker-matching filename, but the body execs the
+    # user's own install — no path inside bin_dir anywhere.
+    user_script = _write(
+        hooks_dir / "lean-ctx-redirect.sh",
+        '#!/bin/sh\nexec /usr/bin/lean-ctx "$@"\n',
+    )
     settings = _write(
         home / ".claude" / "settings.json",
         json.dumps(
@@ -44,12 +59,16 @@ def test_removes_hooks_for_both_tools_but_keeps_user_hooks(home):
                 "permissions": {"allow": ["Bash"]},
                 "hooks": {
                     "PreToolUse": [
+                        {"hooks": [{"type": "command", "command": str(managed_script)}]},
                         {
                             "hooks": [
-                                {"type": "command", "command": "~/.claude/hooks/rtk-rewrite.sh"}
+                                {
+                                    "type": "command",
+                                    "command": f"{bin_dir / 'lean-ctx'} hook rewrite",
+                                }
                             ]
                         },
-                        {"hooks": [{"type": "command", "command": "lean-ctx hook rewrite"}]},
+                        {"hooks": [{"type": "command", "command": str(user_script)}]},
                         {"hooks": [{"type": "command", "command": "my-own-linter --check"}]},
                     ],
                     "SessionStart": [{"hooks": [{"type": "command", "command": "echo hi"}]}],
@@ -64,7 +83,7 @@ def test_removes_hooks_for_both_tools_but_keeps_user_hooks(home):
     commands = [
         item["command"] for entry in payload["hooks"]["PreToolUse"] for item in entry["hooks"]
     ]
-    assert commands == ["my-own-linter --check"]
+    assert commands == [str(user_script), "my-own-linter --check"]
     # Unrelated events and unrelated top-level keys survive untouched.
     assert payload["hooks"]["SessionStart"][0]["hooks"][0]["command"] == "echo hi"
     assert payload["permissions"] == {"allow": ["Bash"]}
@@ -72,11 +91,21 @@ def test_removes_hooks_for_both_tools_but_keeps_user_hooks(home):
 
 
 def test_removes_binaries_hook_scripts_and_backups(home):
-    bin_dir = home / ".headroom" / "bin"
+    bin_dir = paths.bin_dir()
+    hooks_dir = home / ".claude" / "hooks"
     rtk = _write(bin_dir / "rtk", "binary")
     lean = _write(bin_dir / "lean-ctx", "binary")
-    script = _write(home / ".claude" / "hooks" / "lean-ctx-rewrite.sh", "#!/bin/sh\n")
-    backup = _write(home / ".claude" / "hooks" / "lean-ctx-rewrite.sh.lean-ctx.bak", "#!/bin/sh\n")
+    script = _write(
+        hooks_dir / "lean-ctx-rewrite.sh", f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n'
+    )
+    backup = _write(
+        hooks_dir / "lean-ctx-rewrite.sh.lean-ctx.bak",
+        f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n',
+    )
+    managed_rtk_script = _write(
+        hooks_dir / "rtk-rewrite.sh", f'#!/bin/sh\nexec {bin_dir / "rtk"} "$@"\n'
+    )
+    managed_rtk_digest = _write(hooks_dir / ".rtk-hook.sha256", "deadbeef\n")
 
     context_tool_cleanup.purge_context_tool_artifacts()
 
@@ -84,6 +113,22 @@ def test_removes_binaries_hook_scripts_and_backups(home):
     assert not lean.exists()
     assert not script.exists()
     assert not backup.exists()
+    # .rtk-hook.sha256 follows rtk-rewrite.sh's classification: both managed,
+    # both removed.
+    assert not managed_rtk_script.exists()
+    assert not managed_rtk_digest.exists()
+
+
+def test_leaves_a_users_own_rtk_digest_alone(home):
+    """The digest is a hex hash, so it can only follow the script it authenticates."""
+    hooks_dir = home / ".claude" / "hooks"
+    script = _write(hooks_dir / "rtk-rewrite.sh", '#!/bin/sh\nexec /usr/bin/rtk "$@"\n')
+    digest = _write(hooks_dir / ".rtk-hook.sha256", "cafef00d\n")
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert script.exists()
+    assert digest.exists()
 
 
 def test_leaves_a_users_own_binary_on_path_alone(home):
@@ -100,13 +145,14 @@ def test_leaves_a_users_own_binary_on_path_alone(home):
 
 
 def test_removes_mcp_entry_and_preserves_siblings(home):
+    bin_dir = paths.bin_dir()
     config = _write(
         home / ".claude.json",
         json.dumps(
             {
                 "projects": {"/some/path": {"history": []}},
                 "mcpServers": {
-                    "lean-ctx": {"command": "lean-ctx", "args": ["mcp"]},
+                    "lean-ctx": {"command": str(bin_dir / "lean-ctx"), "args": ["mcp"]},
                     "headroom": {"command": "headroom", "args": ["mcp"]},
                 },
             }
@@ -146,13 +192,25 @@ def test_skips_malformed_json_instead_of_clobbering_it(home):
 
 
 def test_is_idempotent(home):
-    _write(home / ".headroom" / "bin" / "rtk", "binary")
+    """Re-running the purge body reports nothing new.
+
+    Normally the completion stamp stops a second run, but a workspace the
+    stamp cannot be written to falls back to running every time — so the body
+    itself has to stay idempotent. Removing the stamp between runs is what
+    that machine does.
+    """
+    bin_dir = paths.bin_dir()
+    _write(bin_dir / "rtk", "binary")
+    script = _write(
+        home / ".claude" / "hooks" / "rtk-rewrite.sh", f'#!/bin/sh\nexec {bin_dir / "rtk"} "$@"\n'
+    )
     _write(
         home / ".claude" / "settings.json",
-        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": "rtk rewrite"}]}]}}),
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
     )
 
     assert context_tool_cleanup.purge_context_tool_artifacts()
+    (bin_dir.parent / ".context-tools-purged").unlink()
     # Steady state after the first run: nothing left to report.
     assert context_tool_cleanup.purge_context_tool_artifacts() == []
 
@@ -161,6 +219,98 @@ def test_no_op_on_a_clean_machine(home):
     assert context_tool_cleanup.purge_context_tool_artifacts() == []
 
 
+def test_a_completed_purge_never_runs_again(home):
+    """Machine-global artifacts stay stamped-done: no per-launch re-audit.
+
+    A tool installed under the *global* half (hooks, binaries) after the
+    migration is not a leftover, so a later run must leave it alone without
+    even looking — this is what stops `headroom wrap` from re-litigating
+    machine-global state on every launch, forever. Project- and config-
+    directory-scoped guidance is a different story: see
+    `test_a_completed_purge_still_cleans_a_different_project`.
+    """
+    bin_dir = paths.bin_dir()
+    bin_dir.parent.mkdir(parents=True)
+
+    assert context_tool_cleanup.purge_context_tool_artifacts() == []
+    assert (bin_dir.parent / ".context-tools-purged").exists()
+
+    # Artifacts that would otherwise be removed, installed after the migration.
+    binary = _write(bin_dir / "lean-ctx", "binary")
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n',
+    )
+
+    assert context_tool_cleanup.purge_context_tool_artifacts() == []
+    assert binary.exists()
+    assert script.exists()
+
+
+def test_a_completed_purge_still_cleans_a_different_project(home, monkeypatch):
+    """The one-time stamp is machine-global; project guidance is not.
+
+    A completed run in project A must not leave project B's fenced guidance in
+    place forever — the stamp only ever covered a snapshot of ``Path.cwd()``.
+    """
+    paths.bin_dir().parent.mkdir(parents=True)
+    assert context_tool_cleanup.purge_context_tool_artifacts() == []
+    assert (paths.bin_dir().parent / ".context-tools-purged").exists()
+
+    project_b = home / "project-b"
+    project_b.mkdir()
+    agents = _write(
+        project_b / "AGENTS.md",
+        "# Project B\n\n<!-- headroom:rtk-instructions -->\nAlways prefix with rtk.\n"
+        "<!-- /headroom:rtk-instructions -->\n",
+    )
+    monkeypatch.chdir(project_b)
+
+    report = context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert "rtk" not in agents.read_text()
+    assert any(str(agents) in line for line in report)
+
+
+def test_a_completed_purge_still_inspects_a_repointed_codex_home(home, monkeypatch):
+    """``CODEX_HOME`` can point somewhere new after the stamp; that target is not exempt."""
+    paths.bin_dir().parent.mkdir(parents=True)
+    assert context_tool_cleanup.purge_context_tool_artifacts() == []
+    assert (paths.bin_dir().parent / ".context-tools-purged").exists()
+
+    new_codex_home = home / "elsewhere-codex"
+    new_codex_home.mkdir()
+    agents = _write(
+        new_codex_home / "AGENTS.md",
+        "<!-- headroom:rtk-instructions -->\nAlways prefix with rtk.\n"
+        "<!-- /headroom:rtk-instructions -->\n",
+    )
+    monkeypatch.setenv("CODEX_HOME", str(new_codex_home))
+
+    report = context_tool_cleanup.purge_context_tool_artifacts()
+
+    # Nothing but the fence was in the file, so it is removed outright.
+    assert not agents.exists()
+    assert any(str(agents) in line for line in report)
+
+
+def test_a_scoped_deferral_does_not_withhold_the_global_stamp(home):
+    """A scoped step's leftover must not re-run the whole global half forever.
+
+    Only the invocation-scoped half is unprovable here (malformed Continue
+    config); the machine-global half has nothing to defer, so its stamp must
+    still be written — otherwise a permanently-broken ``.continue/config.json``
+    would force every hook/binary/MCP step to be re-walked on every launch.
+    """
+    paths.bin_dir().parent.mkdir(parents=True)
+    _write(home / "project" / ".continue" / "config.json", "{not json")
+
+    report = context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert any(line.startswith("skipped ") for line in report)
+    assert (paths.bin_dir().parent / ".context-tools-purged").exists()
+
+
 def test_purge_reports_on_stderr_so_json_stdout_stays_parseable(home):
     """`wrap openclaw --prepare-only` emits machine-readable JSON as its whole contract.
 
@@ -216,3 +366,442 @@ def test_selfheal_does_not_purge(home, monkeypatch):
     CliRunner().invoke(main, ["wrap", "selfheal", "--marker", "headroom-wrap-selfheal"])
 
     assert binary.exists(), "selfheal performed filesystem cleanup"
+
+
+def test_leaves_a_users_own_mcp_entry_alone(home):
+    config = _write(
+        home / ".claude.json",
+        json.dumps({"mcpServers": {"lean-ctx": {"command": "lean-ctx", "args": ["mcp"]}}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    payload = json.loads(config.read_text())
+    assert payload["mcpServers"] == {"lean-ctx": {"command": "lean-ctx", "args": ["mcp"]}}
+
+
+def test_leaves_a_users_own_hook_script_and_hook_entry_alone(home):
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        '#!/bin/sh\nexec /usr/bin/lean-ctx "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert script.exists()
+    payload = json.loads(settings.read_text())
+    assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == str(script)
+
+
+def test_removes_the_managed_hook_script_and_its_hook_entry(home):
+    bin_dir = paths.bin_dir()
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert not script.exists()
+    payload = json.loads(settings.read_text())
+    assert "hooks" not in payload
+
+
+def test_removes_a_hook_entry_pointing_at_the_managed_binary_directly(home):
+    bin_dir = paths.bin_dir()
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps(
+            {
+                "hooks": {
+                    "PreToolUse": [
+                        {
+                            "hooks": [
+                                {
+                                    "type": "command",
+                                    "command": f"{bin_dir / 'lean-ctx'} hook rewrite",
+                                }
+                            ]
+                        }
+                    ]
+                }
+            }
+        ),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    payload = json.loads(settings.read_text())
+    assert "hooks" not in payload
+
+
+def test_matches_a_managed_path_written_in_tilde_form(home):
+    """The dangling-hook regression test: bin_dir is <tmp>/.headroom/bin, and the
+    script references it in unexpanded tilde form — the guard must normalize
+    both sides before comparing, or it wrongly treats this as unprovable and
+    leaves a hook pointing at a script Headroom itself no longer manages.
+    """
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        '#!/bin/sh\nexec ~/.headroom/bin/lean-ctx "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert not script.exists()
+    payload = json.loads(settings.read_text())
+    assert "hooks" not in payload
+
+
+def test_leaves_a_hook_script_in_a_sibling_bin_named_directory_alone(home):
+    """A directory that merely starts with the bin dir's name is not the bin dir.
+
+    ``<workspace>/.headroom/binaries`` shares a prefix with
+    ``<workspace>/.headroom/bin`` but is a different, user-owned directory —
+    a naive substring match (no directory-boundary check) would treat the
+    shared prefix as a reference to the managed bin dir and wrongly delete
+    this script.
+    """
+    bin_dir = paths.bin_dir()
+    sibling = bin_dir.parent / "binaries"
+    own_binary = _write(sibling / "lean-ctx", "my own build")
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {own_binary} "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert script.exists()
+    payload = json.loads(settings.read_text())
+    assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == str(script)
+
+
+def test_leaves_an_mcp_entry_in_a_sibling_bin_named_directory_alone(home):
+    """Same sibling-directory hazard as above, for the MCP-entry command check."""
+    bin_dir = paths.bin_dir()
+    sibling_command = str(bin_dir.parent / "bin-backup" / "lean-ctx")
+    config = _write(
+        home / ".claude.json",
+        json.dumps({"mcpServers": {"lean-ctx": {"command": sibling_command, "args": ["mcp"]}}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    payload = json.loads(config.read_text())
+    assert payload["mcpServers"] == {"lean-ctx": {"command": sibling_command, "args": ["mcp"]}}
+
+
+def test_leaves_a_parent_traversal_path_through_the_bin_dir_alone(home):
+    """``bin/../evil`` contains the managed prefix as literal text but does not
+    resolve inside it — the guard must collapse ``..`` before comparing, or a
+    crafted (or coincidental) traversal path would be treated as Headroom's.
+    """
+    bin_dir = paths.bin_dir()
+    evil_binary = _write(bin_dir.parent / "evil" / "lean-ctx", "not ours")
+    traversal_command = f"{bin_dir}/../evil/lean-ctx"
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {traversal_command} "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert script.exists()
+    assert evil_binary.exists()
+    payload = json.loads(settings.read_text())
+    assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == str(script)
+
+
+def test_leaves_a_hook_script_whose_body_has_the_bin_dir_as_a_path_segment_alone(home):
+    """``/prefix<bin_dir>/lean-ctx`` contains the managed prefix as literal text
+    but at a position with no boundary before it — the run of characters
+    immediately preceding the match is a filename character (``x``), not
+    whitespace or a :data:`_PATH_BOUNDARY_CHARS` character, so this names a
+    different, user-owned directory that only happens to end in the managed
+    path's tail. Only checking the trailing boundary (the pre-fix behavior)
+    would misclassify this as Headroom's and delete the user's script.
+    """
+    bin_dir = paths.bin_dir()
+    lookalike = f"/prefix{bin_dir}/lean-ctx"
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {lookalike} "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert script.exists()
+    payload = json.loads(settings.read_text())
+    assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == str(script)
+
+
+def test_leaves_an_mcp_entry_whose_command_has_the_bin_dir_as_a_path_segment_alone(home):
+    """Same leading-boundary hazard as above, for the MCP-entry command check."""
+    bin_dir = paths.bin_dir()
+    lookalike_command = f"/prefix{bin_dir}/lean-ctx"
+    config = _write(
+        home / ".claude.json",
+        json.dumps({"mcpServers": {"lean-ctx": {"command": lookalike_command, "args": ["mcp"]}}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    payload = json.loads(config.read_text())
+    assert payload["mcpServers"] == {"lean-ctx": {"command": lookalike_command, "args": ["mcp"]}}
+
+
+def test_leaves_a_hook_entry_whose_command_has_the_bin_dir_as_a_path_segment_alone(home):
+    """Same hazard for a hook entry whose ``command`` names the managed
+    directory directly (no script indirection). The command still carries a
+    ``_HOOK_COMMAND_MARKERS`` token (``lean-ctx hook``) so it reaches the
+    provenance guard rather than being filtered out earlier.
+    """
+    bin_dir = paths.bin_dir()
+    lookalike_command = f"/prefix{bin_dir}/lean-ctx hook rewrite"
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps(
+            {
+                "hooks": {
+                    "PreToolUse": [{"hooks": [{"type": "command", "command": lookalike_command}]}]
+                }
+            }
+        ),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    payload = json.loads(settings.read_text())
+    assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == lookalike_command
+
+
+def test_removes_a_hook_script_whose_body_has_a_lookalike_prefix_before_a_genuine_managed_path(
+    home,
+):
+    """A body can contain both a rejected lookalike occurrence and a later
+    genuine, boundary-correct occurrence of the managed path. Rejecting the
+    first must not short-circuit the scan (``continue``, not
+    ``return False``) or the genuine occurrence right after it would never
+    be seen.
+    """
+    bin_dir = paths.bin_dir()
+    lookalike = f"/prefix{bin_dir}/lean-ctx-fake"
+    genuine = str(bin_dir / "lean-ctx")
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {lookalike} --check\nexec {genuine} "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert not script.exists()
+    payload = json.loads(settings.read_text())
+    assert "hooks" not in payload
+
+
+def test_removes_a_hook_script_whose_body_names_the_managed_dir_only_via_quoting_or_delimiters(
+    home,
+):
+    """Real shell scripts quote paths and join them with `=`/`:`/`()`, not bare
+    whitespace. The guard must not miss the managed directory just because it
+    sits inside a quoted string, a `VAR=` assignment, a `PATH=...:` join, or a
+    subshell — a naive whitespace-token split would sever every one of these
+    (and the quote/paren characters would still be glued onto the token).
+    """
+    bin_dir = paths.bin_dir()
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        "#!/bin/sh\n"
+        f'exec "{bin_dir}/lean-ctx" "$@"\n'
+        f"# or: exec '{bin_dir}/lean-ctx'\n"
+        f'export PATH="{bin_dir}:$PATH"\n'
+        f"BIN={bin_dir}/lean-ctx\n"
+        f"({bin_dir}/lean-ctx)\n",
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert not script.exists()
+    payload = json.loads(settings.read_text())
+    assert "hooks" not in payload
+
+
+def test_matches_a_managed_path_when_home_contains_a_space(home, monkeypatch):
+    """A ``$HOME`` with a space is real, and yields a bin dir with a literal
+    space inside it. Splitting a script's body on whitespace before searching
+    would sever the path at that space and miss it entirely.
+    """
+    bin_dir = home / "space here" / ".headroom" / "bin"
+    monkeypatch.setattr(paths, "bin_dir", lambda: bin_dir)
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {bin_dir}/lean-ctx "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert not script.exists()
+    payload = json.loads(settings.read_text())
+    assert "hooks" not in payload
+
+
+def test_leaves_a_same_named_hook_script_in_a_different_directory_alone(home):
+    """A hook entry's command must name the exact managed script in
+    ``~/.claude/hooks`` — not merely share a basename with one. A user's own
+    ``~/mytools/lean-ctx-rewrite.sh`` must never inherit the classification of
+    Headroom's ``~/.claude/hooks/lean-ctx-rewrite.sh`` just because the
+    filename matches — but a wrapper invocation (``bash <script>``), a quoted
+    command, or a redundant ``./`` segment naming the *managed* script by
+    absolute path must still be recognised, or the entry survives while step
+    2 deletes the very script it names (the same class of stale, silently
+    no-op hook the rtk case documents as an accepted limitation, not one to
+    introduce here).
+
+    A *relative* command (``.claude/hooks/lean-ctx-rewrite.sh``) must survive
+    even though it shares wording with the managed script's home-relative
+    form: a relative hook command is resolved by the harness against the
+    project's cwd, never against home, so it names a project-local script
+    this purge never inspects — treating it as a home-relative reference
+    would delete a different file than the one the guard just proved nothing
+    about.
+    """
+    bin_dir = paths.bin_dir()
+    hooks_dir = home / ".claude" / "hooks"
+    # The managed script that gives "lean-ctx-rewrite.sh" a True verdict.
+    managed_script = _write(
+        hooks_dir / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n',
+    )
+    # The user's own script: same basename, different directory, own binary.
+    user_script = _write(
+        home / "mytools" / "lean-ctx-rewrite.sh",
+        '#!/bin/sh\nexec /usr/bin/lean-ctx "$@"\n',
+    )
+    relative_command = ".claude/hooks/lean-ctx-rewrite.sh"
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps(
+            {
+                "hooks": {
+                    "PreToolUse": [
+                        {"hooks": [{"command": f"bash {managed_script}"}]},
+                        {"hooks": [{"command": f'"{managed_script}"'}]},
+                        {"hooks": [{"command": f"{hooks_dir}/./lean-ctx-rewrite.sh"}]},
+                        {"hooks": [{"command": relative_command}]},
+                        {"hooks": [{"command": str(user_script)}]},
+                    ]
+                }
+            }
+        ),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert user_script.exists()
+    payload = json.loads(settings.read_text())
+    commands = [
+        item["command"] for entry in payload["hooks"]["PreToolUse"] for item in entry["hooks"]
+    ]
+    assert commands == [relative_command, str(user_script)]
+
+
+def test_reports_an_unreadable_hook_script_instead_of_guessing(home):
+    if sys.platform.startswith("win") or os.geteuid() == 0:
+        pytest.skip("chmod 0o000 does not deny access on Windows or when running as root")
+
+    bin_dir = paths.bin_dir()
+    script = _write(
+        home / ".claude" / "hooks" / "lean-ctx-rewrite.sh",
+        f'#!/bin/sh\nexec {bin_dir / "lean-ctx"} "$@"\n',
+    )
+    settings = _write(
+        home / ".claude" / "settings.json",
+        json.dumps({"hooks": {"PreToolUse": [{"hooks": [{"command": str(script)}]}]}}),
+    )
+    script.chmod(0o000)
+
+    try:
+        report = context_tool_cleanup.purge_context_tool_artifacts()
+    finally:
+        if script.exists():
+            script.chmod(0o644)
+
+    # Unprovable, so kept — not deleted on a guess — but named in the report.
+    assert script.exists()
+    assert any(str(script) in line for line in report)
+    payload = json.loads(settings.read_text())
+    assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"] == str(script)
+    # A run that could not decide is not the completed migration: leaving the
+    # stamp off is what gets this script looked at again once it is readable.
+    assert not (paths.bin_dir().parent / ".context-tools-purged").exists()
+
+
+def test_an_unparseable_config_defers_the_migration_stamp(home):
+    """A config the user must fix by hand still holds a leftover.
+
+    Stamping the migration complete here would retire the only reminder they
+    get, and the entry would never be cleaned once the typo is fixed.
+    """
+    _write(home / ".claude" / "settings.json", "{not json")
+
+    report = context_tool_cleanup.purge_context_tool_artifacts()
+
+    assert any(line.startswith("skipped ") for line in report)
+    assert not (paths.bin_dir().parent / ".context-tools-purged").exists()
+
+
+def test_leaves_an_mcp_entry_without_a_command_alone(home):
+    config = _write(
+        home / ".claude.json",
+        json.dumps(
+            {
+                "mcpServers": {
+                    "lean-ctx": {"args": ["mcp"]},
+                    "rtk": "not-a-dict",
+                    "lean_ctx": {"command": ["lean-ctx", "mcp"]},
+                }
+            }
+        ),
+    )
+
+    context_tool_cleanup.purge_context_tool_artifacts()
+
+    payload = json.loads(config.read_text())
+    assert set(payload["mcpServers"]) == {"lean-ctx", "rtk", "lean_ctx"}
diff --git a/tests/test_cost_tracker_totals.py b/tests/test_cost_tracker_totals.py
new file mode 100644
index 000000000..ec7108487
--- /dev/null
+++ b/tests/test_cost_tracker_totals.py
@@ -0,0 +1,80 @@
+"""CostTracker.totals() must be stats() minus the work, not minus the accuracy.
+
+It exists only so the per-request metrics path stops walking 31 days of cost
+records to read two fields. If the two ever disagree, the savings history
+silently drifts from /stats.
+"""
+
+from __future__ import annotations
+
+import random
+
+import pytest
+
+from headroom.proxy.cost import CostTracker
+
+
+def _tracker(seed: int, n_models: int, n_requests: int) -> CostTracker:
+    r = random.Random(seed)
+    tracker = CostTracker()
+    models = [
+        "claude-sonnet-5",
+        "claude-opus-4-1",
+        "gpt-4o",
+        "gpt-4o-mini",
+        "some-unpriceable-model",
+    ][:n_models]
+    for _ in range(n_requests):
+        model = r.choice(models)
+        sent = r.randint(0, 20000)
+        # Alternate between requests that carry an API cache breakdown and ones
+        # that do not — totals() has a branch for each, and only the second
+        # falls back to list price.
+        with_cache = r.random() < 0.5
+        tracker.record_tokens(
+            model=model,
+            tokens_saved=r.randint(0, 5000),
+            tokens_sent=sent,
+            cache_read_tokens=r.randint(0, sent) if with_cache else 0,
+            cache_write_tokens=r.randint(0, 500) if with_cache else 0,
+            uncached_tokens=r.randint(0, sent) if with_cache else 0,
+            output_tokens=r.randint(0, 2000),
+        )
+    return tracker
+
+
+@pytest.mark.parametrize(
+    ("n_models", "n_requests"),
+    [(0, 0), (1, 1), (1, 50), (3, 200), (5, 500)],
+)
+def test_totals_matches_stats(n_models: int, n_requests: int) -> None:
+    tracker = _tracker(seed=n_models * 100 + n_requests, n_models=n_models, n_requests=n_requests)
+    stats = tracker.stats()
+    assert tracker.totals() == (
+        stats["total_input_tokens"],
+        stats["total_input_cost_usd"],
+    )
+
+
+def test_totals_matches_stats_on_a_fresh_tracker() -> None:
+    tracker = CostTracker()
+    stats = tracker.stats()
+    assert tracker.totals() == (stats["total_input_tokens"], stats["total_input_cost_usd"])
+
+
+def test_totals_does_not_walk_the_cost_records() -> None:
+    """The point of the method: no period_cost_breakdown, at any ledger size."""
+    tracker = _tracker(seed=7, n_models=3, n_requests=100)
+    called = False
+    real = tracker.period_cost_breakdown
+
+    def spy(*a, **kw):
+        nonlocal called
+        called = True
+        return real(*a, **kw)
+
+    tracker.period_cost_breakdown = spy  # type: ignore[method-assign]
+    tracker.totals()
+    assert not called, "totals() still walks the cost records"
+    tracker.stats()
+    assert called, "stats() should still report budget_basis"
diff --git a/tests/test_dashboard_cache_lifetime_playwright.py b/tests/test_dashboard_cache_lifetime_playwright.py
index d52642e48..fb4638080 100644
--- a/tests/test_dashboard_cache_lifetime_playwright.py
+++ b/tests/test_dashboard_cache_lifetime_playwright.py
@@ -1,11 +1,8 @@
-"""Playwright validation for the persisted lifetime Cache Reads tile.
+"""Playwright validation for persisted lifetime Prefix Cache metrics.
 
-The Prefix Cache Impact card historically rendered only from in-memory
-session counters, so every proxy restart blanked the operator's cache
-savings. These tests pin the durable behavior: the card renders from
-``persistent_savings.lifetime.cache_read_tokens`` alone after a restart
-with zero traffic, session-scoped tiles read "no activity since restart",
-and the card stays hidden when neither session nor lifetime data exists.
+The Session dashboard now reports only current-process cache activity,
+while durable cache totals live behind the Lifetime view. These tests pin
+that split after a restart with zero session traffic.
 """
 
 from __future__ import annotations
@@ -29,24 +26,44 @@ expect = playwright.expect
 sync_playwright = playwright.sync_playwright
 
 
-def _stats_lifetime_only() -> dict:
-    """Post-restart shape: zero session cache traffic, persisted lifetime present."""
+def _session_stats_no_cache() -> dict:
+    """Post-restart session payload: zero current-process cache traffic."""
     stats = copy.deepcopy(_sample_stats())
     totals = stats.setdefault("prefix_cache", {}).setdefault("totals", {})
     totals.update({"requests": 0, "cache_read_tokens": 0, "cache_write_tokens": 0})
-    stats.setdefault("persistent_savings", {})["lifetime"] = {
-        "requests": 6088,
-        "tokens_saved": 42_181,
-        "compression_savings_usd": 0.5,
-        "cache_read_tokens": 629_537_547,
-        "cache_savings_usd": 7.2,
-        "total_input_tokens": 1_294_591_655,
-        "total_input_cost_usd": 12.5,
-    }
     return stats
 
 
-def _install_dashboard_routes(page: Page, stats: dict) -> None:
+def _lifetime_cache_payload(
+    *,
+    cache_read_tokens: int = 629_537_547,
+    cache_savings_usd: float = 7.2,
+) -> dict:
+    return {
+        "requests": {"total": 6088, "failed": 0, "rate_limited": 0, "cached": 0},
+        "tokens": {"saved": 42_181},
+        "cost": {
+            "input_usd": 12.5,
+            "compression_savings_usd": 0.5,
+            "cache_savings_usd": cache_savings_usd,
+        },
+        "prefix_cache": {
+            "cache_read_tokens": cache_read_tokens,
+            "cache_write_tokens": 0,
+            "hit_requests": 0,
+            "requests": 0,
+            "bust_count": 0,
+            "bust_tokens": 0,
+        },
+        "projects": {},
+        "by_model": {},
+        "by_stack": {},
+        "waste_signals": {},
+        "persistence": {"healthy": True, "enabled": True, "pending_records": 0},
+    }
+
+
+def _install_dashboard_routes(page: Page, stats: dict, lifetime: dict) -> None:
     history = _sample_history()
     health = {"status": "healthy", "version": "0.3.0"}
     dashboard_html = get_dashboard_html()
@@ -61,6 +78,9 @@ def _install_dashboard_routes(page: Page, stats: dict) -> None:
         if "/stats-history" in path:
             route.fulfill(status=200, content_type="application/json", body=json.dumps(history))
             return
+        if path.endswith("/stats-lifetime"):
+            route.fulfill(status=200, content_type="application/json", body=json.dumps(lifetime))
+            return
         if path.endswith("/stats"):
             route.fulfill(status=200, content_type="application/json", body=json.dumps(stats))
             return
@@ -72,8 +92,8 @@ def _install_dashboard_routes(page: Page, stats: dict) -> None:
     page.route("**/*", handler)
 
 
-def _open_dashboard(page: Page, stats: dict) -> None:
-    _install_dashboard_routes(page, stats)
+def _open_dashboard(page: Page, stats: dict, lifetime: dict) -> None:
+    _install_dashboard_routes(page, stats, lifetime)
     page.goto("http://headroom.local/dashboard")
     page.wait_for_load_state("networkidle")
 
@@ -82,31 +102,25 @@ def test_card_renders_lifetime_cache_reads_after_zero_traffic_restart() -> None:
     with sync_playwright() as p:
         browser = p.chromium.launch()
         page = browser.new_page(viewport={"width": 1440, "height": 1600})
-        _open_dashboard(page, _stats_lifetime_only())
+        _open_dashboard(page, _session_stats_no_cache(), _lifetime_cache_payload())
 
-        expect(page.get_by_text("Prefix Cache Impact", exact=True)).to_be_visible()
-        expect(page.get_by_text("Cache Reads (lifetime)", exact=True)).to_be_visible()
-        expect(page.get_by_text("629.5M", exact=True)).to_be_visible()
-        expect(page.get_by_text("$7.20 saved")).to_be_visible()
-        # Session-scoped siblings read as inactive, not as literal zeros.
-        expect(page.get_by_text("no activity since restart").first).to_be_visible()
-        assert page.get_by_text("no activity since restart").count() >= 5
-        # x-show hides via CSS (element stays in the DOM), so assert
-        # visibility, not count — unlike the x-if card gate below.
-        expect(page.get_by_text("Cache Efficiency", exact=True)).to_be_hidden()
+        expect(page.get_by_text("Prefix Cache Impact", exact=True)).to_have_count(0)
+        page.get_by_role("button", name="Lifetime", exact=True).click()
+        expect(page.get_by_role("heading", name="Prefix Cache", exact=True)).to_be_visible()
+        expect(page.get_by_text("629.5M / 0", exact=True)).to_be_visible()
+        expect(page.get_by_text("$7.20", exact=True)).to_be_visible()
 
         browser.close()
 
 
 def test_card_hidden_when_no_session_and_no_lifetime_data() -> None:
-    stats = _stats_lifetime_only()
-    stats["persistent_savings"]["lifetime"]["cache_read_tokens"] = 0
-    stats["persistent_savings"]["lifetime"]["cache_savings_usd"] = 0.0
+    stats = _session_stats_no_cache()
+    lifetime = _lifetime_cache_payload(cache_read_tokens=0, cache_savings_usd=0.0)
 
     with sync_playwright() as p:
         browser = p.chromium.launch()
         page = browser.new_page(viewport={"width": 1440, "height": 1600})
-        _open_dashboard(page, stats)
+        _open_dashboard(page, stats, lifetime)
 
         expect(page.get_by_text("Prefix Cache Impact", exact=True)).to_have_count(0)
 
diff --git a/tests/test_dashboard_cache_ttl_playwright.py b/tests/test_dashboard_cache_ttl_playwright.py
index 7d87546d3..28337e10f 100644
--- a/tests/test_dashboard_cache_ttl_playwright.py
+++ b/tests/test_dashboard_cache_ttl_playwright.py
@@ -175,6 +175,7 @@ def _fulfill_static_asset(route, path: str) -> bool:  # type: ignore[no-untyped-
 def _install_dashboard_routes(page: Page) -> None:
     stats = _sample_stats()
     history = _sample_history()
+    lifetime = {"projects": {}}
     health = {"status": "healthy", "version": "0.3.0"}
     dashboard_html = get_dashboard_html()
 
@@ -195,6 +196,9 @@ def _install_dashboard_routes(page: Page) -> None:
                 body=json.dumps(history),
             )
             return
+        if path.endswith("/stats-lifetime"):
+            route.fulfill(status=200, content_type="application/json", body=json.dumps(lifetime))
+            return
         if path.endswith("/stats"):
             route.fulfill(status=200, content_type="application/json", body=json.dumps(stats))
             return
@@ -213,7 +217,7 @@ def test_dashboard_per_project_setup_url_uses_current_origin() -> None:
         _install_dashboard_routes(page)
 
         page.goto("http://127.0.0.1:8788/dashboard", wait_until="load")
-        page.get_by_role("button", name="Lifetime").click()
+        page.get_by_role("button", name="Lifetime", exact=True).click()
         expect(page.get_by_text("Per-Project Savings")).to_be_visible()
         expect(
             page.get_by_text(
@@ -227,7 +231,7 @@ def test_dashboard_per_project_setup_url_uses_current_origin() -> None:
         ).to_have_count(0)
 
         page.goto("http://headroom.local:9393/dashboard", wait_until="load")
-        page.get_by_role("button", name="Lifetime").click()
+        page.get_by_role("button", name="Lifetime", exact=True).click()
         expect(page.get_by_text("Per-Project Savings")).to_be_visible()
         expect(
             page.get_by_text(
diff --git a/tests/test_graceful_shutdown.py b/tests/test_graceful_shutdown.py
new file mode 100644
index 000000000..7bff1e5a1
--- /dev/null
+++ b/tests/test_graceful_shutdown.py
@@ -0,0 +1,285 @@
+"""Tests for graceful shutdown and Ctrl+C signal handling.
+
+Covers:
+- _SuppressCancelledErrorFilter suppresses "Exception in ASGI application"
+  log records whose exc_info is CancelledError
+- _SuppressCancelledErrorFilter passes through unrelated error records
+- timeout_graceful_shutdown is present in the uvicorn.run() call path
+- The lifespan shutdown branch logs the proxy_shutdown event
+- Lifespan shutdown completes even when individual steps block/raise
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import pytest
+
+from headroom.proxy.server import (
+    ProxyConfig,
+    _SuppressCancelledErrorFilter,
+    create_app,
+)
+
+# ---------------------------------------------------------------------------
+# Unit tests for the logging filter
+# ---------------------------------------------------------------------------
+
+
+class TestSuppressCancelledErrorFilter:
+    """_SuppressCancelledErrorFilter silences CancelledError noise from uvicorn."""
+
+    def _make_record(
+        self,
+        level: int = logging.ERROR,
+        exc_type: type | None = None,
+    ) -> logging.LogRecord:
+        record = logging.LogRecord(
+            name="uvicorn.error",
+            level=level,
+            pathname="",
+            lineno=0,
+            msg="Exception in ASGI application",
+            args=(),
+            exc_info=(exc_type, exc_type() if exc_type else None, None) if exc_type else None,
+        )
+        return record
+
+    def test_suppresses_cancelled_error_at_error_level(self) -> None:
+        f = _SuppressCancelledErrorFilter()
+        record = self._make_record(logging.ERROR, asyncio.CancelledError)
+        assert f.filter(record) is False
+
+    def test_passes_through_cancelled_error_at_warning_level(self) -> None:
+        # Only suppress ERROR, not lower-severity records
+        f = _SuppressCancelledErrorFilter()
+        record = self._make_record(logging.WARNING, asyncio.CancelledError)
+        assert f.filter(record) is True
+
+    def test_passes_through_other_exception_at_error_level(self) -> None:
+        f = _SuppressCancelledErrorFilter()
+        record = self._make_record(logging.ERROR, ValueError)
+        assert f.filter(record) is True
+
+    def test_passes_through_record_without_exc_info(self) -> None:
+        f = _SuppressCancelledErrorFilter()
+        record = self._make_record(logging.ERROR, None)
+        # exc_info is set to None tuple when exc_type is None
+        record.exc_info = None
+        assert f.filter(record) is True
+
+    def test_passes_through_record_with_none_exc_type(self) -> None:
+        f = _SuppressCancelledErrorFilter()
+        record = self._make_record(logging.ERROR, None)
+        record.exc_info = (None, None, None)
+        assert f.filter(record) is True
+
+    def test_suppresses_subclass_of_cancelled_error(self) -> None:
+        """BaseException subclasses of CancelledError are also suppressed."""
+
+        class MyCancelled(asyncio.CancelledError):
+            pass
+
+        f = _SuppressCancelledErrorFilter()
+        record = self._make_record(logging.ERROR, MyCancelled)
+        assert f.filter(record) is False
+
+
+# ---------------------------------------------------------------------------
+# Integration: filter is installed on uvicorn.error in run_server()
+# ---------------------------------------------------------------------------
+
+
+def test_run_server_installs_cancelled_error_filter(monkeypatch: pytest.MonkeyPatch) -> None:
+    """run_server() attaches _SuppressCancelledErrorFilter to uvicorn.error logger."""
+    installed_filters: list = []
+
+    original_add_filter = logging.Logger.addFilter
+
+    def capturing_add_filter(self: logging.Logger, f: logging.Filter) -> None:
+        if self.name == "uvicorn.error" and isinstance(f, _SuppressCancelledErrorFilter):
+            installed_filters.append(f)
+        original_add_filter(self, f)
+
+    monkeypatch.setattr(logging.Logger, "addFilter", capturing_add_filter)
+
+    # Intercept uvicorn.run so we don't actually start a server
+    monkeypatch.setattr("uvicorn.run", lambda *a, **kw: None)
+
+    from headroom.proxy.server import run_server
+
+    run_server(ProxyConfig(), print_banner=False)
+
+    assert len(installed_filters) == 1, "Expected exactly one _SuppressCancelledErrorFilter"
+
+
+# ---------------------------------------------------------------------------
+# Integration: timeout_graceful_shutdown is forwarded to uvicorn.run()
+# ---------------------------------------------------------------------------
+
+
+def test_run_server_passes_timeout_graceful_shutdown(monkeypatch: pytest.MonkeyPatch) -> None:
+    """run_server() passes timeout_graceful_shutdown=10 to uvicorn.run()."""
+    captured: dict = {}
+
+    def fake_uvicorn_run(*args: object, **kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("uvicorn.run", fake_uvicorn_run)
+
+    from headroom.proxy.server import run_server
+
+    run_server(ProxyConfig(), print_banner=False)
+
+    assert "timeout_graceful_shutdown" in captured, (
+        "uvicorn.run() must receive timeout_graceful_shutdown kwarg"
+    )
+    assert captured["timeout_graceful_shutdown"] == 10
+
+
+# ---------------------------------------------------------------------------
+# Integration: lifespan logs proxy_shutdown event on teardown
+# ---------------------------------------------------------------------------
+
+
+def test_lifespan_logs_shutdown_event(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The lifespan finally-block logs event=proxy_shutdown when the app tears down.
+
+    caplog cannot capture records from loggers that emit before propagation is
+    configured, so this test installs a custom handler directly on
+    ``headroom.proxy`` and checks that handler's records.
+    """
+    # Collect log records manually because caplog propagation is unreliable
+    # when the root logger has pre-existing basicConfig handlers.
+    captured: list[logging.LogRecord] = []
+
+    class _Capture(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            captured.append(record)
+
+    proxy_logger = logging.getLogger("headroom.proxy")
+    capture_handler = _Capture()
+    proxy_logger.addHandler(capture_handler)
+
+    try:
+        # Prevent sys.exit(78) from _check_rust_core when Rust extension absent
+        monkeypatch.setattr(
+            "headroom.proxy.server._check_rust_core", lambda: ("disabled", "test-mock")
+        )
+
+        config = ProxyConfig(
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            cost_tracking_enabled=False,
+            log_requests=False,
+            ccr_inject_tool=False,
+            ccr_handle_responses=False,
+            ccr_context_tracking=False,
+            image_optimize=False,
+        )
+        app = create_app(config)
+
+        from fastapi.testclient import TestClient
+
+        with TestClient(app, raise_server_exceptions=False):
+            pass  # lifespan shutdown runs when the context manager exits
+
+    finally:
+        proxy_logger.removeHandler(capture_handler)
+
+    shutdown_records = [r for r in captured if "event=proxy_shutdown" in r.getMessage()]
+    assert shutdown_records, "Expected at least one log record containing 'event=proxy_shutdown'"
+
+
+# ---------------------------------------------------------------------------
+# Lifespan shutdown: bounded await (_timed helper)
+# ---------------------------------------------------------------------------
+
+
+def test_lifespan_shutdown_completes_when_proxy_shutdown_hangs(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Lifespan shutdown must complete even if proxy.shutdown() never returns.
+
+    Before the fix, an unbounded ``await _beacon.stop()`` would block the
+    lifespan finally-block forever, requiring a second Ctrl+C.  The fix wraps
+    every shutdown await with asyncio.wait_for so a slow step is skipped
+    after its timeout and teardown continues.
+    """
+    import asyncio
+
+    async def hanging_stop() -> None:
+        await asyncio.sleep(9999)  # simulate a blocked network call
+
+    # Prevent sys.exit(78) from the Rust-core check
+    monkeypatch.setattr("headroom.proxy.server._check_rust_core", lambda: ("disabled", "test-mock"))
+
+    config = ProxyConfig(
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+        log_requests=False,
+        ccr_inject_tool=False,
+        ccr_handle_responses=False,
+        ccr_context_tracking=False,
+        image_optimize=False,
+    )
+    app = create_app(config)
+
+    import headroom.proxy.server as server_mod
+
+    monkeypatch.setattr(server_mod.HeadroomProxy, "shutdown", lambda self: hanging_stop())
+
+    # If the fix is absent this would hang; with the fix it returns quickly.
+    import time
+
+    from fastapi.testclient import TestClient
+
+    start = time.monotonic()
+    with TestClient(app, raise_server_exceptions=False):
+        pass
+    elapsed = time.monotonic() - start
+    # Teardown should complete well within 15 s even with the timeout; hanging
+    # without the fix would block until the test runner times out (~60 s).
+    assert elapsed < 15.0, f"Lifespan shutdown took too long: {elapsed:.1f}s"
+
+
+def test_lifespan_shutdown_completes_when_proxy_shutdown_raises(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Lifespan shutdown must complete even if proxy.shutdown() raises.
+
+    The _timed wrapper catches both TimeoutError and arbitrary exceptions,
+    logs a warning, and continues so all subsequent teardown steps still run.
+    """
+
+    async def raising_shutdown() -> None:
+        raise RuntimeError("simulated shutdown failure")
+
+    monkeypatch.setattr("headroom.proxy.server._check_rust_core", lambda: ("disabled", "test-mock"))
+
+    config = ProxyConfig(
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+        log_requests=False,
+        ccr_inject_tool=False,
+        ccr_handle_responses=False,
+        ccr_context_tracking=False,
+        image_optimize=False,
+    )
+    app = create_app(config)
+
+    import headroom.proxy.server as server_mod
+
+    monkeypatch.setattr(server_mod.HeadroomProxy, "shutdown", lambda self: raising_shutdown())
+
+    from fastapi.testclient import TestClient
+
+    # Should not raise — the _timed helper swallows the exception with a warning
+    with TestClient(app, raise_server_exceptions=False):
+        pass
diff --git a/tests/test_image_types_torch_decoupling.py b/tests/test_image_types_torch_decoupling.py
new file mode 100644
index 000000000..4c7f37426
--- /dev/null
+++ b/tests/test_image_types_torch_decoupling.py
@@ -0,0 +1,55 @@
+"""Importing the image compressor must not eagerly import trained_router (torch).
+
+#2513 (secondary): ``from .trained_router import Technique`` at module scope
+pulled in torch / transformers, which on Python 3.13+ crashed with
+``AttributeError: module 'torch' has no attribute 'compiler'`` before torch had
+finished initializing. The routing types now live in a dependency-free module.
+
+The "does not import" checks run in a fresh subprocess so module caching from
+other tests can't mask the import graph.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def _assert_import_excludes(module_name: str, excluded: str) -> None:
+    code = (
+        "import sys, importlib\n"
+        f"importlib.import_module({module_name!r})\n"
+        f"assert {excluded!r} not in sys.modules, {excluded!r} + ' was imported'\n"
+        "print('ok')\n"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, timeout=120
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "ok"
+
+
+def test_importing_compressor_does_not_import_trained_router() -> None:
+    _assert_import_excludes("headroom.image.compressor", "headroom.image.trained_router")
+
+
+def test_importing_onnx_router_does_not_import_trained_router() -> None:
+    _assert_import_excludes("headroom.image.onnx_router", "headroom.image.trained_router")
+
+
+def test_image_types_module_does_not_import_torch() -> None:
+    _assert_import_excludes("headroom.image.image_types", "torch")
+
+
+def test_technique_reexports_are_the_same_object() -> None:
+    from headroom.image import Technique as via_package
+    from headroom.image.image_types import ImageSignals, RouteDecision, Technique
+    from headroom.image.trained_router import ImageSignals as tr_signals
+    from headroom.image.trained_router import RouteDecision as tr_decision
+    from headroom.image.trained_router import Technique as tr_technique
+
+    assert via_package is Technique
+    assert tr_technique is Technique
+    assert tr_signals is ImageSignals
+    assert tr_decision is RouteDecision
+    assert Technique.PRESERVE.value == "preserve"
diff --git a/tests/test_install/test_native_installers.py b/tests/test_install/test_native_installers.py
index bbad56621..94fee0ba9 100644
--- a/tests/test_install/test_native_installers.py
+++ b/tests/test_install/test_native_installers.py
@@ -105,6 +105,16 @@ def main() -> int:
     if command == "pull":
         return 0
 
+    if command == "network" and len(args) > 1 and args[1] == "inspect":
+        # Match the default bridge gateway used by the native installer when
+        # it configures the dashboard metadata allowlist.
+        gateway = os.environ.get("FAKE_DOCKER_GATEWAY", "172.17.0.1")
+        if gateway == "FAIL":
+            return 1
+        if "--format" in args and gateway:
+            print(gateway)
+        return 0
+
     if command == "run":
         detached = "-d" in args
         if not detached:
@@ -112,17 +122,29 @@ def main() -> int:
 
         name = None
         publish = None
+        container_env = {}
         for index, arg in enumerate(args):
             if arg == "--name":
                 name = args[index + 1]
             elif arg == "-p":
                 publish = args[index + 1]
+            elif arg == "--env":
+                spec = args[index + 1]
+                if "=" in spec:
+                    env_name, value = spec.split("=", 1)
+                    container_env[env_name] = value
+                elif spec in os.environ:
+                    container_env[spec] = os.environ[spec]
 
         if name is None or publish is None:
             raise SystemExit("missing --name or -p in fake docker run")
 
         port = host_port_from_publish(publish)
-        state["containers"][name] = {"pid": start_server(port), "port": port}
+        state["containers"][name] = {
+            "pid": start_server(port),
+            "port": port,
+            "env": container_env,
+        }
         save_state(state)
         print(name)
         return 0
@@ -225,6 +247,84 @@ def _read_fake_docker_log(env: dict[str, str]) -> list[list[str]]:
     return [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines() if line]
 
 
+def _persistent_run_call(env: dict[str, str], profile: str) -> list[str]:
+    container_name = f"headroom-{profile}"
+    return next(
+        call
+        for call in _read_fake_docker_log(env)
+        if call[:2] == ["run", "-d"]
+        and "--name" in call
+        and call[call.index("--name") + 1] == container_name
+    )
+
+
+def _persistent_container_env(env: dict[str, str], profile: str) -> dict[str, str]:
+    state = json.loads(Path(env["FAKE_DOCKER_STATE"]).read_text(encoding="utf-8"))
+    return state["containers"][f"headroom-{profile}"]["env"]
+
+
+def _exercise_dashboard_gateway_overrides(wrapper_command: list[str], env: dict[str, str]) -> None:
+    trusted_cidrs = "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS"
+
+    try:
+        for profile, configured_value in (("configured", "10.20.0.0/16"), ("empty", "")):
+            env[trusted_cidrs] = configured_value
+            port = _free_port()
+            _run(
+                [
+                    *wrapper_command,
+                    "install",
+                    "apply",
+                    "--profile",
+                    profile,
+                    "--port",
+                    str(port),
+                    "--image",
+                    "fake/headroom:test",
+                ],
+                env=env,
+            )
+
+            install_call = _persistent_run_call(env, profile)
+            assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
+            # Docker's name-only --env form preserves the caller's value,
+            # including an explicitly empty value, instead of installing the
+            # discovered bridge gateway default.
+            assert trusted_cidrs in install_call
+            assert not any(arg.startswith(f"{trusted_cidrs}=") for arg in install_call)
+            assert _persistent_container_env(env, profile)[trusted_cidrs] == configured_value
+            _run([*wrapper_command, "install", "remove", "--profile", profile], env=env)
+
+        env.pop(trusted_cidrs, None)
+        env["FAKE_DOCKER_GATEWAY"] = "FAIL"
+        port = _free_port()
+        result = _run(
+            [
+                *wrapper_command,
+                "install",
+                "apply",
+                "--profile",
+                "no-gateway",
+                "--port",
+                str(port),
+                "--image",
+                "fake/headroom:test",
+            ],
+            env=env,
+        )
+        install_call = _persistent_run_call(env, "no-gateway")
+        assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
+        assert not any(
+            arg == trusted_cidrs or arg.startswith(f"{trusted_cidrs}=") for arg in install_call
+        )
+        assert trusted_cidrs not in _persistent_container_env(env, "no-gateway")
+        assert "dashboard metadata remains restricted" in (result.stdout + result.stderr)
+        _run([*wrapper_command, "install", "remove", "--profile", "no-gateway"], env=env)
+    finally:
+        env.pop(trusted_cidrs, None)
+        env.pop("FAKE_DOCKER_GATEWAY", None)
+
+
 def _run(
     command: list[str],
     *,
@@ -402,11 +502,19 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa
         install_call = next(
             call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
         )
+        assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
         assert "/tmp/headroom-home/.headroom/memory.db" in install_call
         # Canonical filesystem contract env vars (issue #175) forwarded into
         # the container so the proxy resolves state/config to the bind mount.
         assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in install_call
         assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in install_call
+        assert "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32" in install_call
+        assert (
+            _persistent_container_env(env, "smoke")["HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS"]
+            == "172.17.0.1/32"
+        )
+
+        _exercise_dashboard_gateway_overrides([str(wrapper)], env)
 
         status_result = _run(
             [str(wrapper), "install", "status", "--profile", "smoke"],
@@ -654,10 +762,21 @@ def test_powershell_native_installer_supports_persistent_docker_lifecycle(tmp_pa
         install_call = next(
             call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
         )
+        assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
         assert "/tmp/headroom-home/.headroom/memory.db" in install_call
         # Canonical filesystem contract env vars (issue #175).
         assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in install_call
         assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in install_call
+        assert "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32" in install_call
+        assert (
+            _persistent_container_env(env, "smoke")["HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS"]
+            == "172.17.0.1/32"
+        )
+
+        _exercise_dashboard_gateway_overrides(
+            [powershell, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(wrapper)],
+            env,
+        )
 
         status_result = _run(
             [
diff --git a/tests/test_install/test_planner.py b/tests/test_install/test_planner.py
index ffb559149..b4389e611 100644
--- a/tests/test_install/test_planner.py
+++ b/tests/test_install/test_planner.py
@@ -46,6 +46,57 @@ def test_build_manifest_for_persistent_docker_sets_expected_defaults() -> None:
     assert manifest.tool_envs["claude"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787"
     assert manifest.tool_envs["copilot"]["COPILOT_PROVIDER_TYPE"] == "anthropic"
     assert "--memory" in manifest.proxy_args
+    # A container runtime must NOT carry the host memory DB path: it does not
+    # exist inside the container and would keep /readyz at 503 (#2803). The proxy
+    # resolves the DB under its own cwd, which is the bind-mounted ~/.headroom.
+    assert "--memory-db-path" not in manifest.proxy_args
+
+
+def test_build_manifest_python_runtime_keeps_explicit_memory_db_path() -> None:
+    manifest = build_manifest(
+        profile="default",
+        preset=InstallPreset.PERSISTENT_SERVICE.value,
+        runtime_kind="python",
+        scope="user",
+        provider_mode="manual",
+        targets=["claude"],
+        port=8787,
+        backend="anthropic",
+        anyllm_provider=None,
+        region=None,
+        proxy_mode="token",
+        memory_enabled=True,
+        telemetry_enabled=False,
+        image="ghcr.io/headroomlabs-ai/headroom:latest",
+    )
+
+    # On the host the resolved path is correct, so it is still passed explicitly.
+    assert "--memory" in manifest.proxy_args
+    assert "--memory-db-path" in manifest.proxy_args
+
+
+def test_build_manifest_falls_back_from_windows_service_to_task(monkeypatch) -> None:
+    monkeypatch.setattr("headroom.install.planner.sys.platform", "win32")
+
+    manifest = build_manifest(
+        profile="default",
+        preset=InstallPreset.PERSISTENT_SERVICE.value,
+        runtime_kind="python",
+        scope="user",
+        provider_mode="manual",
+        targets=["claude"],
+        port=8787,
+        backend="anthropic",
+        anyllm_provider=None,
+        region=None,
+        proxy_mode="token",
+        memory_enabled=False,
+        telemetry_enabled=False,
+        image="ghcr.io/headroomlabs-ai/headroom:latest",
+    )
+
+    assert manifest.preset == InstallPreset.PERSISTENT_TASK.value
+    assert manifest.supervisor_kind == "task"
 
 
 def test_build_manifest_uses_provider_slice_env_builders_for_all_supported_targets() -> None:
@@ -238,6 +289,17 @@ def test_build_manifest_persists_intercept_tool_results() -> None:
     manifest = build_manifest(**_base_manifest_kwargs(intercept_tool_results=True))
 
     assert "--intercept-tool-results" in manifest.proxy_args
+    assert manifest.base_env["HEADROOM_ROLLOUT_CHANNEL"] == "canary"
+
+
+def test_build_manifest_rejects_interceptor_below_required_rollout_channel() -> None:
+    with pytest.raises(click.ClickException, match="requires HEADROOM_ROLLOUT_CHANNEL=canary"):
+        build_manifest(
+            **_base_manifest_kwargs(
+                intercept_tool_results=True,
+                extra_env={"HEADROOM_ROLLOUT_CHANNEL": "stable"},
+            )
+        )
 
 
 def test_build_manifest_persists_protect_tool_results() -> None:
diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py
index ce654d859..8b5e08ed4 100644
--- a/tests/test_install/test_runtime.py
+++ b/tests/test_install/test_runtime.py
@@ -281,6 +281,9 @@ def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Pat
     monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
     monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)
     monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)
+    # Force the Docker path deterministically regardless of the test host's
+    # `docker` binary (it might resolve to a podman shim).
+    monkeypatch.setenv("HEADROOM_CONTAINER_RUNTIME", "docker")
     docker_manifest = DeploymentManifest(
         profile="default",
         preset="persistent-docker",
@@ -299,6 +302,37 @@ def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Pat
     command = build_runtime_command(docker_manifest)
     assert "--user" in command
     assert "1000:1001" in command
+    assert "--userns=keep-id" not in command
+
+
+def test_build_runtime_command_podman_uses_keep_id_not_user(monkeypatch, tmp_path: Path) -> None:
+    """Under rootless Podman, --user <host-uid>:<host-gid> selects a subordinate
+    UID that owns none of the bind mounts, so writes into ~/.headroom fail. The
+    command must use --userns=keep-id and drop --user instead (#2804)."""
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
+    monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)
+    monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)
+    monkeypatch.setenv("HEADROOM_CONTAINER_RUNTIME", "podman")
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-docker",
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        image="ghcr.io/headroomlabs-ai/headroom:latest",
+        base_env={"HEADROOM_PORT": "8787"},
+        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
+    )
+    command = build_runtime_command(manifest)
+    assert "--userns=keep-id" in command
+    assert "--user" not in command
+    assert "1000:1001" not in command
 
 
 def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None:
diff --git a/tests/test_install/test_supervisors.py b/tests/test_install/test_supervisors.py
index 15a105bea..60d1f85b1 100644
--- a/tests/test_install/test_supervisors.py
+++ b/tests/test_install/test_supervisors.py
@@ -13,6 +13,9 @@ from headroom.install.supervisors import (
     _macos_launchd_plist,
     _render_unix_runner,
     _render_windows_runner,
+    _windows_boot_trigger,
+    _windows_health_trigger,
+    _windows_task_xml,
     install_supervisor,
     remove_supervisor,
     render_runner_scripts,
@@ -21,6 +24,31 @@ from headroom.install.supervisors import (
 )
 
 
+def test_windows_task_xml_user_scope_is_hidden_s4u() -> None:
+    # #2453: user-scope tasks must run S4U (non-interactive, no window) and
+    # hidden so the 5-minute health run never steals keyboard focus.
+    xml = _windows_task_xml(
+        "C:\\tmp\\default\\ensure-headroom.cmd",
+        trigger_xml=_windows_health_trigger(),
+        scope="user",
+    )
+    assert "<LogonType>S4U</LogonType>" in xml
+    assert "<Hidden>true</Hidden>" in xml
+    assert "<Interval>PT5M</Interval>" in xml
+    assert "<Command>C:\\tmp\\default\\ensure-headroom.cmd</Command>" in xml
+
+
+def test_windows_task_xml_system_scope_uses_localsystem() -> None:
+    xml = _windows_task_xml(
+        "C:\\tmp\\default\\ensure-headroom.cmd",
+        trigger_xml=_windows_boot_trigger(),
+        scope="system",
+    )
+    assert "<UserId>S-1-5-18</UserId>" in xml
+    assert "<LogonType>ServiceAccount</LogonType>" in xml
+    assert "<BootTrigger>" in xml
+
+
 def _manifest(
     *,
     profile: str = "default",
@@ -377,19 +405,16 @@ def test_install_supervisor_darwin_windows_and_unsupported(monkeypatch, tmp_path
         "sc.exe create headroom-default "
         'binPath= "cmd.exe /c \\"C:\\tmp\\default\\run-headroom.cmd\\"" start= auto'
     ) in calls
-    assert [
-        "schtasks",
-        "/Create",
-        "/TN",
-        "headroom-default-health",
-        "/TR",
-        "C:\\tmp\\default\\ensure-headroom.cmd",
-        "/SC",
-        "MINUTE",
-        "/MO",
-        "5",
-        "/F",
-    ] in calls
+    # #2453: tasks are registered from S4U/hidden XML via `schtasks /XML`, not
+    # interactive-token flag creation. Assert the startup and health tasks are
+    # each created from an XML file (the temp path varies).
+    task_creates = [
+        c for c in calls if isinstance(c, list) and c[:2] == ["schtasks", "/Create"] and "/XML" in c
+    ]
+    created_names = {c[c.index("/TN") + 1] for c in task_creates}
+    assert {"headroom-default-startup", "headroom-default-health"} <= created_names
+    for c in task_creates:
+        assert c[-1] == "/F"
 
     monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")
     monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")
diff --git a/tests/test_integrations/test_litellm_callback.py b/tests/test_integrations/test_litellm_callback.py
index 50f698316..ddf71d4da 100644
--- a/tests/test_integrations/test_litellm_callback.py
+++ b/tests/test_integrations/test_litellm_callback.py
@@ -5,6 +5,7 @@ from __future__ import annotations
 import importlib
 import inspect
 from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
@@ -52,3 +53,30 @@ class TestHeadroomCallbackPostCallSuccessHook:
             response=sentinel,
         )
         assert result is sentinel
+
+
+class TestHeadroomCallbackClientLifecycle:
+    """Cloud client cleanup must be explicit and safe to repeat."""
+
+    @pytest.mark.asyncio
+    async def test_aclose_closes_and_clears_initialized_client(self) -> None:
+        cb = HeadroomCallback(api_key="hdr_test")
+        client = MagicMock()
+        client.aclose = AsyncMock()
+        cb._client = client
+
+        await cb.aclose()
+
+        client.aclose.assert_awaited_once_with()
+        assert cb._client is None
+
+        await cb.aclose()
+        client.aclose.assert_awaited_once_with()
+
+    @pytest.mark.asyncio
+    async def test_aclose_without_initialized_client_is_a_noop(self) -> None:
+        cb = HeadroomCallback(api_key="hdr_test")
+
+        await cb.aclose()
+
+        assert cb._client is None
diff --git a/tests/test_issue_1779_remote_control_gate.py b/tests/test_issue_1779_remote_control_gate.py
index 0a7a17e5b..a1ac9ab99 100644
--- a/tests/test_issue_1779_remote_control_gate.py
+++ b/tests/test_issue_1779_remote_control_gate.py
@@ -19,6 +19,8 @@ import pytest
 from headroom.providers.claude.runtime import (
     REMOTE_CONTROL_GATED_MIN_VERSION,
     REMOTE_CONTROL_SIBLING_GATE_NOTE,
+    claude_auth_conflict_message,
+    claude_auth_conflict_sources,
     detect_claude_code_version,
     is_custom_anthropic_base_url,
     parse_claude_code_version,
@@ -34,6 +36,34 @@ _GATED = REMOTE_CONTROL_GATED_MIN_VERSION  # (2, 1, 196)
 _OLD = (2, 1, 195)
 
 
+def test_claude_auth_conflict_tracks_precedence_without_returning_values() -> None:
+    conflict = claude_auth_conflict_sources(
+        ("user settings", {"ANTHROPIC_AUTH_TOKEN": "secret-token"}),
+        ("project settings", {"ANTHROPIC_API_KEY": "secret-api"}),
+        ("shell environment", {}),
+    )
+
+    assert conflict == {
+        "ANTHROPIC_API_KEY": "project settings",
+        "ANTHROPIC_AUTH_TOKEN": "user settings",
+    }
+    message = claude_auth_conflict_message(conflict)
+    assert "secret-token" not in message
+    assert "secret-api" not in message
+    assert "project settings" in message
+    assert "user settings" in message
+
+
+def test_claude_auth_conflict_higher_precedence_empty_value_clears_key() -> None:
+    assert (
+        claude_auth_conflict_sources(
+            ("settings", {"ANTHROPIC_AUTH_TOKEN": "token", "ANTHROPIC_API_KEY": "key"}),
+            ("shell", {"ANTHROPIC_API_KEY": ""}),
+        )
+        is None
+    )
+
+
 # ---------------------------------------------------------------------------
 # Message accuracy — deterministic wording, not "may"
 # ---------------------------------------------------------------------------
diff --git a/tests/test_issue_2671_block_growth_cache.py b/tests/test_issue_2671_block_growth_cache.py
new file mode 100644
index 000000000..160d4c22a
--- /dev/null
+++ b/tests/test_issue_2671_block_growth_cache.py
@@ -0,0 +1,288 @@
+"""Comprehensive regression for #2671's block-growing Anthropic histories.
+
+The provider writes cache entries only at explicit breakpoints and searches at
+most 20 block boundaries backwards on the next request.  Consequently:
+
+* a pure append must advance the breakpoint to the newest block;
+* a rewritten tail must anchor at the last byte-stable leading block;
+* both shapes must retain one conversation lineage across turns;
+* different tools/thinking profiles must never share that lineage, because
+  Anthropic renders those segments before messages in its cache key.
+
+The small cache oracle below models those write/lookback rules.  It catches a
+green-but-inert implementation: merely moving a marker in a unit-built message
+is insufficient unless the real resolve -> normalize -> record sequence carries
+the previous turn's state forward.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from headroom.cache.prefix_tracker import (
+    RELATION_BLOCK_APPEND,
+    RELATION_BLOCK_REWRITE_TAIL,
+    RELATION_DIVERGED,
+    PrefixFreezeConfig,
+    SessionTrackerStore,
+    _strip_cache_control,
+    classify_history_relation,
+    extract_cache_stable_delta,
+    normalize_message_cache_control,
+    overlay_cached_prefix,
+    segment_fingerprint,
+)
+
+
+def _text(text: str, *, cache: bool = False) -> dict[str, Any]:
+    block: dict[str, Any] = {"type": "text", "text": text}
+    if cache:
+        block["cache_control"] = {"type": "ephemeral"}
+    return block
+
+
+def _message(blocks: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [{"role": "user", "content": blocks}]
+
+
+def _pure_append(total: int) -> list[dict[str, Any]]:
+    return _message([_text(f"block-{index}") for index in range(total)])
+
+
+def _rewritten_tail(
+    turn: int,
+    churn_blocks: int,
+    *,
+    stable_blocks: int = 30,
+    instruction: str = "instruction: summarize",
+) -> list[dict[str, Any]]:
+    blocks = [_text(f"stable-{index}") for index in range(stable_blocks)]
+    blocks += [_text(f"turn-{turn}-changing-{index}") for index in range(churn_blocks)]
+    # The captured production shape keeps a two-block identity suffix pinned at
+    # the end while the blocks immediately before it are rewritten.
+    blocks += [_text(instruction), _text("fixed end-of-transcript reminder")]
+    return _message(blocks)
+
+
+def _breakpoint(messages: list[dict[str, Any]]) -> tuple[int, int]:
+    found = [
+        (message_index, block_index)
+        for message_index, message in enumerate(messages)
+        if isinstance(message.get("content"), list)
+        for block_index, block in enumerate(message["content"])
+        if isinstance(block, dict) and "cache_control" in block
+    ]
+    assert len(found) == 1
+    return found[0]
+
+
+@dataclass
+class _AnthropicBreakpointCache:
+    """Deterministic model of Anthropic's explicit-breakpoint cache lookup."""
+
+    entries: dict[str, int] = field(default_factory=dict)
+    lookback_blocks: int = 20
+
+    @staticmethod
+    def _blocks(messages: list[dict[str, Any]]) -> list[Any]:
+        blocks: list[Any] = []
+        for message in messages:
+            content = message.get("content")
+            if isinstance(content, list):
+                blocks.extend(_strip_cache_control(content))
+        return blocks
+
+    @staticmethod
+    def _key(blocks: list[Any], end: int) -> str:
+        return json.dumps(blocks[: end + 1], sort_keys=True, separators=(",", ":"))
+
+    def request(self, messages: list[dict[str, Any]]) -> tuple[int, int]:
+        """Return simulated ``(cache_read_blocks, cache_write_blocks)``."""
+        _, breakpoint = _breakpoint(messages)
+        blocks = self._blocks(messages)
+        read = 0
+        first = max(0, breakpoint - self.lookback_blocks + 1)
+        for candidate in range(breakpoint, first - 1, -1):
+            key = self._key(blocks, candidate)
+            if key in self.entries:
+                read = self.entries[key]
+                break
+        written_prefix = breakpoint + 1
+        write = max(0, written_prefix - read)
+        self.entries[self._key(blocks, breakpoint)] = written_prefix
+        return read, write
+
+
+def _record(tracker, original, forwarded, *, read=0, write=10_000):  # noqa: ANN001
+    tracker.update_from_response(
+        cache_read_tokens=read,
+        cache_write_tokens=write,
+        messages=forwarded,
+        original_messages=original,
+    )
+
+
+def test_classifier_separates_pure_append_from_rewritten_tail() -> None:
+    append = classify_history_relation(_pure_append(35), _pure_append(30))
+    rewrite = classify_history_relation(_rewritten_tail(2, 5), _rewritten_tail(1, 3))
+
+    assert append.kind == RELATION_BLOCK_APPEND
+    assert append.stable_prefix_blocks == 30
+    assert rewrite.kind == RELATION_BLOCK_REWRITE_TAIL
+    assert rewrite.stable_prefix_blocks == 30
+    assert rewrite.stable_suffix_blocks == 2
+
+
+def test_rewritten_tail_requires_a_real_previous_divergence() -> None:
+    """The #2702 bug classified a pure append as a rewritten tail."""
+    previous = _pure_append(30)
+    current = _pure_append(31)
+    relation = classify_history_relation(current, previous)
+
+    assert relation.kind == RELATION_BLOCK_APPEND
+    assert relation.stable_prefix_blocks == relation.previous_block_count
+
+
+def test_rewritten_tail_requires_a_two_block_identity_suffix() -> None:
+    """Sibling sub-calls sharing a transcript and generic reminder must split."""
+    previous = _rewritten_tail(1, 3, instruction="instruction: summarize")
+    sibling = _rewritten_tail(2, 5, instruction="instruction: title")
+
+    assert classify_history_relation(sibling, previous).kind == RELATION_DIVERGED
+
+
+def test_lineage_survives_rewritten_tail_growth_and_delivers_previous_state() -> None:
+    store = SessionTrackerStore(PrefixFreezeConfig(min_cached_tokens=0))
+    first_tracker = None
+
+    for turn, churn in enumerate((3, 5, 8, 11), start=1):
+        original = _rewritten_tail(turn, churn)
+        tracker = store.resolve_tracker("shared", "anthropic", messages=original)
+        first_tracker = first_tracker or tracker
+        assert tracker is first_tracker
+        previous = tracker.get_last_forwarded_messages()
+        if turn > 1:
+            assert previous, "lineage match must deliver the previous forwarded request"
+        forwarded = normalize_message_cache_control(original, previous)
+        _record(tracker, original, forwarded)
+
+    assert store.active_sessions == 1
+    assert first_tracker._turn_number == 4
+
+
+def test_sibling_rewritten_tail_streams_do_not_ping_pong() -> None:
+    store = SessionTrackerStore()
+    seen = {}
+    for turn, churn in enumerate((3, 5, 8), start=1):
+        for instruction in ("instruction: summarize", "instruction: title"):
+            original = _rewritten_tail(turn, churn, instruction=instruction)
+            tracker = store.resolve_tracker("shared", "anthropic", messages=original)
+            seen.setdefault(instruction, tracker)
+            assert tracker is seen[instruction]
+            forwarded = normalize_message_cache_control(
+                original, tracker.get_last_forwarded_messages()
+            )
+            _record(tracker, original, forwarded)
+
+    assert seen["instruction: summarize"] is not seen["instruction: title"]
+
+
+def test_cache_affinity_splits_identical_histories_with_different_tools() -> None:
+    store = SessionTrackerStore()
+    history = _pure_append(30)
+    shell = segment_fingerprint({"model": "claude", "tools": [{"name": "shell"}]})
+    search = segment_fingerprint({"model": "claude", "tools": [{"name": "search"}]})
+
+    shell_tracker = store.resolve_tracker(
+        "shared", "anthropic", messages=history, cache_affinity=shell
+    )
+    search_tracker = store.resolve_tracker(
+        "shared", "anthropic", messages=history, cache_affinity=search
+    )
+
+    assert search_tracker is not shell_tracker
+    assert (
+        store.resolve_tracker("shared", "anthropic", messages=history, cache_affinity=shell)
+        is shell_tracker
+    )
+
+
+def test_cache_affinity_ignores_only_cache_directive_movement() -> None:
+    base = {
+        "model": "claude",
+        "tools": [{"name": "shell", "cache_control": {"type": "ephemeral"}}],
+    }
+    moved = {"model": "claude", "tools": [{"name": "shell"}]}
+    changed = {"model": "claude", "tools": [{"name": "search"}]}
+
+    assert segment_fingerprint(base) == segment_fingerprint(moved)
+    assert segment_fingerprint(base) != segment_fingerprint(changed)
+
+
+def test_pure_append_replays_forwarded_blocks_and_advances_breakpoint() -> None:
+    previous_original = _pure_append(30)
+    previous_forwarded = _message([_text(f"COMPRESSED-{index}") for index in range(30)])
+    current = _pure_append(34)
+
+    overlaid = overlay_cached_prefix(current, current, previous_original, previous_forwarded)
+    normalized = normalize_message_cache_control(overlaid, previous_forwarded)
+
+    assert [block["text"] for block in normalized[0]["content"][:30]] == [
+        f"COMPRESSED-{index}" for index in range(30)
+    ]
+    assert [block["text"] for block in normalized[0]["content"][30:]] == [
+        f"block-{index}" for index in range(30, 34)
+    ]
+    assert _breakpoint(normalized) == (0, 33)
+
+
+def test_whole_message_delta_path_cannot_discard_appended_blocks() -> None:
+    """Block appends require a splice, never an empty whole-message delta."""
+    previous = _pure_append(30)
+
+    assert extract_cache_stable_delta(_pure_append(34), previous, previous) is None
+
+
+def test_cache_oracle_proves_pure_append_chains_without_rewrites() -> None:
+    oracle = _AnthropicBreakpointCache()
+    previous = None
+    outcomes = []
+    for total in (30, 34, 38, 43):
+        current = _pure_append(total)
+        forwarded = normalize_message_cache_control(current, previous)
+        outcomes.append(oracle.request(forwarded))
+        previous = forwarded
+
+    assert outcomes == [(0, 30), (30, 4), (34, 4), (38, 5)]
+
+
+def test_cache_oracle_proves_rewritten_tail_stops_perpetual_full_writes() -> None:
+    oracle = _AnthropicBreakpointCache()
+    previous = None
+    outcomes = []
+    breakpoints = []
+    for turn, churn in enumerate((3, 5, 8, 11), start=1):
+        current = _rewritten_tail(turn, churn)
+        forwarded = normalize_message_cache_control(current, previous)
+        breakpoints.append(_breakpoint(forwarded)[1])
+        outcomes.append(oracle.request(forwarded))
+        previous = forwarded
+
+    # Cold turn writes its varying tail.  Turn two establishes the new stable
+    # boundary; subsequent turns read it and perform no repeated full write.
+    assert breakpoints == [34, 29, 29, 29]
+    assert outcomes[0] == (0, 35)
+    assert outcomes[1] == (0, 30)
+    assert outcomes[2:] == [(30, 0), (30, 0)]
+
+
+def test_relocation_kill_switch_restores_newest_block(monkeypatch) -> None:  # noqa: ANN001
+    previous = normalize_message_cache_control(_rewritten_tail(1, 3))
+    monkeypatch.setenv("HEADROOM_STABLE_BOUNDARY_BREAKPOINT", "0")
+    current = _rewritten_tail(2, 5)
+
+    forwarded = normalize_message_cache_control(current, previous)
+
+    assert _breakpoint(forwarded) == (0, len(current[0]["content"]) - 1)
diff --git a/tests/test_issue_746_tool_search.py b/tests/test_issue_746_tool_search.py
index 74c0d4b9a..4b31cb7f8 100644
--- a/tests/test_issue_746_tool_search.py
+++ b/tests/test_issue_746_tool_search.py
@@ -176,7 +176,9 @@ from headroom.proxy.helpers import (  # noqa: E402
     _TOOL_SEARCH_DEFAULT_NAME,
     _TOOL_SEARCH_DEFAULT_TYPE,
     _TOOL_SEARCH_MIN_TOOLS,
+    anthropic_first_party_tool_search_supported,
     inject_tool_search_deferral,
+    strip_first_party_tool_search_tools_for_third_party_upstream,
 )
 
 
@@ -259,6 +261,53 @@ def test_non_dict_and_typed_tools_stay_resident() -> None:
     assert len(typed) == 1 and typed[0].get("defer_loading") is None
 
 
+def test_third_party_upstream_strips_first_party_tool_search_from_headroom_issue_2526() -> None:
+    tools = [
+        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
+        {"name": "Bash", "description": "run a command", "input_schema": {}},
+        {"type": "web_search_20250305", "name": "web_search"},
+    ]
+    out = strip_first_party_tool_search_tools_for_third_party_upstream(
+        tools,
+        "https://api.deepseek.com/anthropic",
+    )
+    assert out is not tools
+    assert [tool.get("name") for tool in out if isinstance(tool, dict)] == ["Bash", "web_search"]
+    assert all(
+        not str(tool.get("type", "")).startswith("tool_search_tool_")
+        for tool in out
+        if isinstance(tool, dict)
+    )
+
+
+def test_first_party_anthropic_preserves_client_tool_search_entry() -> None:
+    tools = [
+        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
+        {"name": "Bash", "description": "run a command", "input_schema": {}},
+    ]
+    assert anthropic_first_party_tool_search_supported("https://api.anthropic.com")
+    assert (
+        strip_first_party_tool_search_tools_for_third_party_upstream(
+            tools,
+            "https://api.anthropic.com",
+        )
+        is tools
+    )
+
+
+@pytest.mark.parametrize(
+    ("api_base_url", "expected_supported"),
+    [
+        ("https://api.anthropic.com", True),
+        ("https://api.anthropic.com/v1", True),
+        ("https://api.deepseek.com/anthropic", False),
+        ("http://127.0.0.1:8787", False),
+    ],
+)
+def test_third_party_or_first_party_matrix(api_base_url: str, expected_supported: bool) -> None:
+    assert anthropic_first_party_tool_search_supported(api_base_url) is expected_supported
+
+
 # ---------------------------------------------------------------------------
 # PascalCase clients (Claude Code). The core-tool exemption is spelled in
 # lowercase, so an exact-match comparison never fired for Claude Code: every
@@ -422,3 +471,141 @@ def test_repair_strips_search_history_when_only_the_tool_is_missing() -> None:
         _poisoned_transcript(), [{"name": "AskUserQuestion", "input_schema": {}}]
     )
     assert removed == 2
+
+
+# ---------------------------------------------------------------------------
+# Regression tests for the direct-Anthropic regression reported in PR #2539
+# comment #5280259642: "Tool reference 'tool_search_tool_regex' not found in
+# available tools".
+#
+# Root cause: when a client sends ``tool_search_tool_regex`` as a *typeless*
+# tool, ``inject_tool_search_deferral`` would (a) not early-exit because the
+# guard only checked ``type``, and (b) defer the tool.  Anthropic then found
+# the deferred copy via the server-side search and stored the tool's name in a
+# ``tool_reference`` entry.  On subsequent requests where the typed injected
+# search tool was present, ``strip_unsupported_tool_search_blocks`` incorrectly
+# treated the injected search tool's *name* as proof the reference was
+# resolvable — but the typed server tool is not a valid deferred-tool target, so
+# Anthropic rejected the request with 400.
+#
+# The two-part fix:
+#   1. ``inject_tool_search_deferral`` early-exit also fires on a name-prefix
+#      match, preventing double-injection when the client carries a typeless
+#      ``tool_search_tool_*`` entry.
+#   2. ``strip_unsupported_tool_search_blocks`` excludes typed search tools
+#      from the ``available`` set — they are the search mechanism, not targets.
+# ---------------------------------------------------------------------------
+
+
+def _transcript_with_search_tool_regex_reference() -> list[dict]:
+    """Transcript where the search found 'tool_search_tool_regex' itself.
+
+    This happens when inject_tool_search_deferral defers a typeless client tool
+    named 'tool_search_tool_regex': Anthropic finds it and stores it as a
+    tool_reference.  On subsequent requests the repair must drop the block
+    rather than falsely keep it because the typed injected search-tool shares
+    the same name.
+    """
+    return [
+        {"role": "user", "content": [{"type": "text", "text": "search for a tool"}]},
+        {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "server_tool_use",
+                    "id": "srvtoolu_REGEX",
+                    "name": _TOOL_SEARCH_DEFAULT_NAME,
+                    "input": {"pattern": "regex"},
+                },
+                {
+                    "type": "tool_search_tool_result",
+                    "tool_use_id": "srvtoolu_REGEX",
+                    "content": {
+                        "type": "tool_search_tool_search_result",
+                        "tool_references": [
+                            {
+                                "type": "tool_reference",
+                                # The search found the deferred 'tool_search_tool_regex'
+                                # typeless tool — this is the broken reference.
+                                "tool_name": _TOOL_SEARCH_DEFAULT_NAME,
+                            }
+                        ],
+                    },
+                },
+            ],
+        },
+    ]
+
+
+@pytest.mark.parametrize(
+    "name",
+    [_TOOL_SEARCH_DEFAULT_NAME, "TOOL_SEARCH_TOOL_BM25"],
+)
+def test_inject_deferral_exits_early_on_typeless_tool_search_name(name: str) -> None:
+    # A client that sends tool_search_tool_regex without a ``type`` field should
+    # be treated as already using tool search (name-prefix guard), so Headroom
+    # must not inject a second search tool on top of it.
+    typeless_search = {"name": name, "input_schema": {}}
+    tools = _tools(20) + [typeless_search]
+    result = inject_tool_search_deferral(tools)
+    assert result is tools  # no injection
+
+
+def test_inject_deferral_does_not_false_match_similar_typeless_tool_name() -> None:
+    # Keep ordinary tools whose names merely resemble the reserved prefix on the
+    # normal deferral path; the trailing underscore is part of the match.
+    tools = _tools(20) + [{"name": "tool_search_toolbox", "input_schema": {}}]
+    result = inject_tool_search_deferral(tools)
+    assert result is not tools
+    by_name = {tool.get("name"): tool for tool in result}
+    assert by_name["tool_search_toolbox"]["defer_loading"] is True
+
+
+def test_repair_drops_search_tool_self_reference_when_inject_ran() -> None:
+    # Regression for PR #2539 comment #5280259642.
+    #
+    # Scenario: inject ran on a previous turn (has_search_tool=True because the
+    # typed search tool is present), but the transcript's tool_reference names
+    # 'tool_search_tool_regex' — the search tool itself.  The typed injected
+    # search tool must NOT count as a valid reference target; the block must be
+    # dropped so Anthropic never sees an unresolvable tool_reference.
+    transcript = _transcript_with_search_tool_regex_reference()
+    # tools array after inject: typed search tool + regular deferred tools
+    tools = [
+        _SEARCH_TOOL,  # typed search tool — must NOT be in 'available'
+        {"name": "Bash", "input_schema": {}},
+        {"name": "mcp_tool_x", "input_schema": {}, "defer_loading": True},
+    ]
+    messages, removed = strip_unsupported_tool_search_blocks(transcript, tools)
+    assert removed == 2  # server_tool_use + tool_search_tool_result both dropped
+    # The assistant turn is entirely stripped (only search blocks were present).
+    assert len(messages) == 1
+    assert messages[0]["role"] == "user"
+
+
+def test_repair_noop_when_referenced_tool_is_regular_deferred_tool() -> None:
+    # Baseline: when the transcript references a normal deferred tool (not the
+    # search tool itself) and that tool is in the current tools array, the block
+    # must be kept — no false-positive stripping from the typed-search exclusion.
+    transcript = _poisoned_transcript()  # references "AskUserQuestion"
+    tools = [
+        _SEARCH_TOOL,
+        {"name": "AskUserQuestion", "input_schema": {}, "defer_loading": True},
+    ]
+    messages, removed = strip_unsupported_tool_search_blocks(transcript, tools)
+    assert removed == 0
+    assert messages is transcript
+
+
+def test_repair_drops_when_referenced_tool_absent_despite_search_tool_present() -> None:
+    # The referenced tool is NOT in the current tools array even though the
+    # typed search tool is present (e.g. a compact request with a different tool
+    # subset).  The block must be dropped.
+    transcript = _poisoned_transcript()  # references "AskUserQuestion"
+    tools = [
+        _SEARCH_TOOL,
+        {"name": "Bash", "input_schema": {}},
+        # AskUserQuestion intentionally absent
+    ]
+    messages, removed = strip_unsupported_tool_search_blocks(transcript, tools)
+    assert removed == 2
diff --git a/tests/test_kompress_download_backoff.py b/tests/test_kompress_download_backoff.py
new file mode 100644
index 000000000..538413c14
--- /dev/null
+++ b/tests/test_kompress_download_backoff.py
@@ -0,0 +1,116 @@
+"""An unreachable HuggingFace must not turn every request into a download thread.
+
+The request path calls ensure_background_download() on every Kompress miss. A
+finished-or-failed thread is replaced on the next call, which is what lets a
+transient blip recover — but with no floor, a permanently unreachable Hub means
+one new thread per request forever, each importing transformers and holding the
+GIL against the event loop.
+"""
+
+from __future__ import annotations
+
+import threading
+
+import pytest
+
+from headroom.transforms import kompress_compressor as kc
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    with kc._download_threads_lock:
+        kc._download_threads.clear()
+        kc._download_failures.clear()
+    yield
+    with kc._download_threads_lock:
+        kc._download_threads.clear()
+        kc._download_failures.clear()
+
+
+def _spawned(monkeypatch, *, fails: bool) -> list[str]:
+    """Run ensure_background_download with the real load stubbed out."""
+    started: list[str] = []
+
+    def fake_load(model_id, device, allow_download=True):
+        started.append(model_id)
+        if fails:
+            raise OSError("hub unreachable")
+        return object(), object(), "onnx"
+
+    monkeypatch.setattr(kc, "_load_kompress", fake_load)
+    return started
+
+
+def _drain():
+    for t in list(kc._download_threads.values()):
+        t.join(timeout=10)
+
+
+def test_repeated_failure_stops_spawning_threads(monkeypatch):
+    started = _spawned(monkeypatch, fails=True)
+    for _ in range(25):
+        kc.ensure_background_download("some/model")
+        _drain()
+    assert len(started) < 25, f"no backoff: spawned {len(started)} downloads for 25 calls"
+    assert len(started) >= 1, "never even tried once"
+
+
+def test_backoff_window_elapsing_allows_another_attempt(monkeypatch):
+    started = _spawned(monkeypatch, fails=True)
+    kc.ensure_background_download("some/model")
+    _drain()
+    assert len(started) == 1
+
+    kc.ensure_background_download("some/model")
+    _drain()
+    assert len(started) == 1, "retried inside the backoff window"
+
+    # Rewind the clock past the window instead of sleeping through it.
+    with kc._download_threads_lock:
+        failures, _ = kc._download_failures["some/model"]
+        kc._download_failures["some/model"] = (failures, 0.0)
+    kc.ensure_background_download("some/model")
+    _drain()
+    assert len(started) == 2, "backoff never expires"
+
+
+def test_success_clears_the_backoff(monkeypatch):
+    _spawned(monkeypatch, fails=False)
+    kc.ensure_background_download("some/model")
+    _drain()
+    assert "some/model" not in kc._download_failures
+
+
+def test_window_grows_with_consecutive_failures():
+    kc._download_failures["m"] = (1, 0.0)
+    assert kc._DOWNLOAD_RETRY_BASE_SECONDS == 5.0
+    # Same last-attempt time, more failures -> still blocked at a later clock.
+    import time as _t
+
+    now = _t.monotonic()
+    kc._download_failures["m"] = (1, now)
+    with kc._download_threads_lock:
+        first = kc._download_retry_blocked("m")
+    kc._download_failures["m"] = (6, now)
+    with kc._download_threads_lock:
+        later = kc._download_retry_blocked("m")
+    assert first and later
+
+
+def test_a_live_thread_is_never_duplicated(monkeypatch):
+    gate = threading.Event()
+    started: list[str] = []
+
+    def slow_load(model_id, device, allow_download=True):
+        started.append(model_id)
+        gate.wait(timeout=10)
+        return object(), object(), "onnx"
+
+    monkeypatch.setattr(kc, "_load_kompress", slow_load)
+    for _ in range(10):
+        kc.ensure_background_download("some/model")
+    try:
+        assert len(started) == 1
+    finally:
+        gate.set()
+        _drain()
diff --git a/tests/test_learn/test_gemini_scanner.py b/tests/test_learn/test_gemini_scanner.py
index 0e0ebb34e..fb04e0277 100644
--- a/tests/test_learn/test_gemini_scanner.py
+++ b/tests/test_learn/test_gemini_scanner.py
@@ -105,6 +105,24 @@ class TestProjectDiscovery:
         assert len(projects) == 1
         assert projects[0].data_path == chats_dir
 
+    def test_detects_project_path_from_jsonl_cwd(self, tmp_path):
+        # A JSONL session must not be read with a whole-file json.load (which
+        # raises on the 2nd line and silently fell back to cwd). The project
+        # cwd carried in the session_metadata line must be recovered.
+        gemini_dir, chats_dir = _setup_gemini_dir(tmp_path)
+        project = tmp_path / "myproject"
+        project.mkdir()
+        session_path = _write_jsonl_session(
+            chats_dir,
+            [
+                {"type": "session_metadata", "id": "s1", "cwd": str(project)},
+                {"type": "user", "parts": [{"text": "hi"}]},
+            ],
+        )
+
+        scanner = GeminiScanner(gemini_dir=gemini_dir)
+        assert scanner._detect_project_path(session_path) == project
+
 
 # =============================================================================
 # JSON Session Parsing
@@ -155,6 +173,30 @@ class TestJsonSessionParsing:
         assert tc.output == "port: 8080\nhost: localhost"
         assert not tc.is_error
 
+    def test_token_counts_not_double_counted(self, tmp_path):
+        # promptTokenCount is the full input (cachedContentTokenCount is a subset
+        # of it) and totalTokenCount == prompt + candidates, so the input must be
+        # promptTokenCount and the output candidatesTokenCount, each once.
+        gemini_dir, _ = _setup_gemini_dir(tmp_path)
+        scanner = GeminiScanner(gemini_dir=gemini_dir)
+        messages = [
+            {
+                "role": "model",
+                "parts": [{"text": "ok"}],
+                "usageMetadata": {
+                    "promptTokenCount": 1000,
+                    "cachedContentTokenCount": 300,
+                    "candidatesTokenCount": 500,
+                    "totalTokenCount": 1500,
+                },
+            },
+        ]
+
+        session = scanner._parse_messages("s1", messages)
+
+        assert session.total_input_tokens == 1000
+        assert session.total_output_tokens == 500
+
     def test_multiple_tool_calls(self, tmp_path):
         gemini_dir, chats_dir = _setup_gemini_dir(tmp_path)
         session = _make_gemini_session(
diff --git a/tests/test_learn/test_integration.py b/tests/test_learn/test_integration.py
index c1b21215c..3ed01d189 100644
--- a/tests/test_learn/test_integration.py
+++ b/tests/test_learn/test_integration.py
@@ -114,6 +114,20 @@ class TestFalsePositiveFiltering:
         )
         assert is_error_content("bash: unknown_cmd: command not found")
 
+    def test_exit_code_zero_is_not_an_error(self):
+        """Agent harnesses append 'exit code 0' to every successful command;
+        that must not be classified as an error."""
+        from headroom.learn.scanner import is_error_content
+
+        assert not is_error_content("Ran the tests.\nProcess finished with exit code 0")
+
+    def test_nonzero_exit_code_is_an_error(self):
+        """A nonzero exit code (any casing / with a colon) is still an error."""
+        from headroom.learn.scanner import is_error_content
+
+        assert is_error_content("build failed\ncommand exited with exit code 1")
+        assert is_error_content("npm run build\nExit code: 127")
+
 
 # =============================================================================
 # Real-World Integration Tests (skipped if data not present)
diff --git a/tests/test_learn_grok_plugin.py b/tests/test_learn_grok_plugin.py
index 3d774b5b7..2bab24cb2 100644
--- a/tests/test_learn_grok_plugin.py
+++ b/tests/test_learn_grok_plugin.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import sys
 from pathlib import Path
 
 from headroom.learn.plugins.grok import GrokPlugin
@@ -57,3 +58,26 @@ def test_grok_plugin_scans_tool_calls(tmp_path: Path) -> None:
     assert len(sessions) == 1
     assert len(sessions[0].tool_calls) == 1
     assert sessions[0].tool_calls[0].is_error is True
+
+
+def test_grok_plugin_resolves_absolute_workspace_path(tmp_path: Path) -> None:
+    # The workspace dir name is a URL-encoded absolute cwd. It must resolve to
+    # that path, not fall back to the process cwd. The Windows branch is the
+    # real guard for the fix (a drive-letter path does not start with "/"); the
+    # POSIX branch confirms no regression. Detection uses Path.is_absolute().
+    grok_dir = tmp_path / ".grok"
+    if sys.platform == "win32":
+        workspace = "C%3A%5Cproj%5Capp"
+        expected = Path(r"C:\proj\app")
+    else:
+        workspace = "%2Ftmp%2Fproj%2Fapp"
+        expected = Path("/tmp/proj/app")
+    session_dir = grok_dir / "sessions" / workspace / "session-1"
+    session_dir.mkdir(parents=True)
+    (session_dir / "updates.jsonl").write_text("{}\n", encoding="utf-8")
+
+    plugin = GrokPlugin(grok_dir=grok_dir)
+    projects = plugin.discover_projects()
+
+    assert len(projects) == 1
+    assert projects[0].project_path == expected
diff --git a/tests/test_litellm_caller_key.py b/tests/test_litellm_caller_key.py
new file mode 100644
index 000000000..d9dd2440c
--- /dev/null
+++ b/tests/test_litellm_caller_key.py
@@ -0,0 +1,67 @@
+"""A caller's key must not be dropped unless we are certain it cannot work.
+
+The proxy forwards the inbound credential to the upstream provider. When a
+routing extension rewrites the model across families mid-request, that key stops
+matching the target and the 401 that follows is indistinguishable, downstream,
+from "the cheap model failed the task".
+
+Refusing to forward is the fix, but it is also the more dangerous direction: a
+false positive silently strips a credential from a deployment that was working,
+and litellm then falls back to an env key that may not exist. So the rule is
+positive evidence only -- an unrecognised credential always travels.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from headroom.backends.litellm import _caller_key_travels_to
+
+ANTHROPIC_KEY = "sk-ant-api03-abc123"
+
+
+@pytest.mark.parametrize(
+    "model",
+    ["gpt-5-mini", "gpt-4o", "azure/gpt-4", "gemini/gemini-2.0-flash"],
+)
+def test_anthropic_key_is_refused_for_a_provider_that_cannot_accept_it(model: str) -> None:
+    """The bug this exists for: claude-* rewritten to a non-Anthropic target."""
+    pytest.importorskip("litellm")
+    assert _caller_key_travels_to(model, ANTHROPIC_KEY) is False
+
+
+@pytest.mark.parametrize(
+    "model",
+    ["claude-opus-4-5-20251101", "anthropic/claude-sonnet-4-5-20250929"],
+)
+def test_anthropic_key_travels_to_anthropic(model: str) -> None:
+    pytest.importorskip("litellm")
+    assert _caller_key_travels_to(model, ANTHROPIC_KEY) is True
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        "sk-proj-openai-style",  # a dozen vendors mint this shape
+        "Bearer-ish-opaque-token",  # a plain gateway token
+        "hf_abc123",
+        "sk-ant",  # near miss, not the prefix
+        "",
+    ],
+)
+def test_only_the_anthropic_prefix_is_ever_classified(key: str) -> None:
+    """Everything else is unclassifiable from the string, so it passes through.
+
+    This is the regression the review caught: the first version returned
+    `not provider.startswith("anthropic")`, which dropped every one of these
+    against an Anthropic-class target.
+    """
+    assert _caller_key_travels_to("gpt-5-mini", key) is True
+    assert _caller_key_travels_to("claude-opus-4-5-20251101", key) is True
+
+
+def test_unknown_provider_keeps_the_pass_through() -> None:
+    """A compatible or self-hosted gateway we cannot classify must not lose its
+    key -- including when `get_llm_provider` raises on the model string."""
+    assert _caller_key_travels_to("some-self-hosted-thing", ANTHROPIC_KEY) is True
+    assert _caller_key_travels_to("", ANTHROPIC_KEY) is True
diff --git a/tests/test_litellm_upstream_timeout.py b/tests/test_litellm_upstream_timeout.py
new file mode 100644
index 000000000..9d6918e46
--- /dev/null
+++ b/tests/test_litellm_upstream_timeout.py
@@ -0,0 +1,70 @@
+"""Every upstream call must be bounded.
+
+There was no timeout in this backend at all. Observed 2026-08-07 under load:
+four agent workers blocked on ESTABLISHED connections for 36+ minutes while
+the proxy answered /readyz in 0.11s. No error, no retry, no log line -- the
+caller simply stops, forever, and that is indistinguishable from slow work.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+
+from headroom.backends.litellm import (
+    DEFAULT_UPSTREAM_TIMEOUT,
+    UPSTREAM_TIMEOUT_ENV,
+    _upstream_timeout,
+)
+
+_SRC = Path(__file__).resolve().parents[1] / "headroom" / "backends" / "litellm.py"
+
+
+def test_every_acompletion_call_is_bounded():
+    """A new dispatch path added without a timeout reintroduces the hang.
+
+    Checked structurally rather than by mocking, because the failure mode is a
+    call site someone ADDS later -- which no mock of the existing paths sees.
+    """
+    tree = ast.parse(_SRC.read_text())
+    calls, guards = 0, 0
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        fn = node.func
+        if isinstance(fn, ast.Name) and fn.id == "acompletion":
+            calls += 1
+        if (
+            isinstance(fn, ast.Attribute)
+            and fn.attr == "setdefault"
+            and node.args
+            and isinstance(node.args[0], ast.Constant)
+            and node.args[0].value == "timeout"
+        ):
+            guards += 1
+    assert calls > 0, "no acompletion call sites found -- test is stale"
+    assert guards >= calls, (
+        f"{calls} acompletion call site(s) but only {guards} timeout guard(s); "
+        "an unbounded upstream call blocks its caller forever"
+    )
+
+
+def test_a_junk_env_value_cannot_disable_the_timeout(monkeypatch):
+    """`0` means 'no timeout' to httpx, i.e. exactly the bug. So does junk."""
+    for bad in ("", "0", "-1", "nonsense", "None"):
+        monkeypatch.setenv(UPSTREAM_TIMEOUT_ENV, bad)
+        assert _upstream_timeout() == DEFAULT_UPSTREAM_TIMEOUT, bad
+
+
+def test_an_operator_can_still_tune_it(monkeypatch):
+    monkeypatch.setenv(UPSTREAM_TIMEOUT_ENV, "42.5")
+    assert _upstream_timeout() == pytest.approx(42.5)
+
+
+def test_the_default_is_generous_enough_for_real_work():
+    """Streaming: litellm expands a float across all httpx phases, so this is
+    the max gap BETWEEN CHUNKS, not a cap on total generation. A steady long
+    answer is never cut off."""
+    assert 60.0 <= DEFAULT_UPSTREAM_TIMEOUT <= 1800.0
diff --git a/tests/test_mcp_dependency_contract.py b/tests/test_mcp_dependency_contract.py
new file mode 100644
index 000000000..69d200e65
--- /dev/null
+++ b/tests/test_mcp_dependency_contract.py
@@ -0,0 +1,29 @@
+"""Keep the installed MCP SDK compatible with Headroom's live server API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import tomllib
+from packaging.requirements import Requirement
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _mcp_requirement(dependencies: list[str]) -> Requirement:
+    matches = [Requirement(value) for value in dependencies if Requirement(value).name == "mcp"]
+    assert len(matches) == 1, "expected exactly one mcp requirement"
+    return matches[0]
+
+
+def test_all_shipping_mcp_extras_exclude_incompatible_sdk_v2() -> None:
+    """SDK 2 removed Server.list_tools()/call_tool(); #2658 owns that port."""
+    project = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]
+    optional = project["optional-dependencies"]
+
+    for extra in ("proxy", "mcp"):
+        requirement = _mcp_requirement(optional[extra])
+        assert requirement.specifier.contains("1.28.1")
+        assert not requirement.specifier.contains("2.0.0"), (
+            f"the {extra!r} extra admits MCP SDK 2.x before the server port in #2658"
+        )
diff --git a/tests/test_mcp_registry/test_install.py b/tests/test_mcp_registry/test_install.py
index 674199992..3e22e5b1e 100644
--- a/tests/test_mcp_registry/test_install.py
+++ b/tests/test_mcp_registry/test_install.py
@@ -89,8 +89,9 @@ def test_build_serena_spec_uses_agent_context() -> None:
     assert spec.name == "serena"
     assert spec.command == "uvx"
     assert spec.args == (
+        # PyPI package with prebuilt wheels, not the git source (#2871).
         "--from",
-        "git+https://github.com/oraios/serena",
+        "serena-agent",
         "serena",
         "start-mcp-server",
         "--project-from-cwd",
@@ -102,6 +103,15 @@ def test_build_serena_spec_uses_agent_context() -> None:
     assert spec.env == {}
 
 
+def test_build_serena_spec_uses_pypi_not_git_source() -> None:
+    """Serena is installed from the PyPI package (prebuilt wheels), not the git
+    source, which forces a from-source build that fails under proot-based
+    filesystems where uv cannot hardlink into a build venv (#2871)."""
+    spec = build_serena_spec("codex")
+    assert "serena-agent" in spec.args
+    assert not any("git+" in arg for arg in spec.args)
+
+
 def test_build_serena_spec_disables_dashboard_popup_by_default() -> None:
     # Headroom installs Serena by default; the dashboard browser tab must not
     # auto-open. The flag overrides the user's serena_config.yml at startup,
diff --git a/tests/test_memory/test_core_metadata_index_sync.py b/tests/test_memory/test_core_metadata_index_sync.py
new file mode 100644
index 000000000..c017f7ee4
--- /dev/null
+++ b/tests/test_memory/test_core_metadata_index_sync.py
@@ -0,0 +1,59 @@
+"""Regression tests for primary-store and vector-metadata consistency."""
+
+from unittest.mock import AsyncMock
+
+import numpy as np
+import pytest
+
+from headroom.memory.core import HierarchicalMemory
+from headroom.memory.models import Memory
+
+
+def _memory_system(memory: Memory, *, cache=None):
+    store = AsyncMock()
+    store.get.return_value = memory
+    vector_index = AsyncMock()
+    text_index = AsyncMock()
+    embedder = AsyncMock()
+    system = HierarchicalMemory(store, vector_index, text_index, embedder, cache=cache)
+    return system, store, vector_index, text_index
+
+
+@pytest.mark.asyncio
+async def test_metadata_only_update_refreshes_vector_metadata() -> None:
+    memory = Memory(
+        id="memory-1",
+        content="stable content",
+        user_id="default",
+        embedding=np.array([0.1, 0.2], dtype=np.float32),
+        metadata={"evidence_count": 5},
+    )
+    system, store, vector_index, text_index = _memory_system(memory)
+
+    updated = await system.update(memory.id, metadata={"evidence_count": 7})
+
+    assert updated is memory
+    store.save.assert_awaited_once_with(memory)
+    vector_index.index.assert_awaited_once_with(memory)
+    text_index.index.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_refresh_memory_indexes_reloads_store_and_cache() -> None:
+    memory = Memory(
+        id="memory-1",
+        content="stable content",
+        user_id="default",
+        embedding=np.array([0.1, 0.2], dtype=np.float32),
+        metadata={"evidence_count": 7},
+    )
+    cache = AsyncMock()
+    system, store, vector_index, _ = _memory_system(memory, cache=cache)
+
+    refreshed = await system.refresh_memory_indexes(memory.id)
+
+    assert refreshed is memory
+    store.get.assert_awaited_once_with(memory.id)
+    vector_index.index.assert_awaited_once_with(memory)
+    cache.invalidate.assert_awaited_once_with(memory.id)
+    cache.put.assert_awaited_once_with(memory)
diff --git a/tests/test_memory/test_direct_mem0.py b/tests/test_memory/test_direct_mem0.py
new file mode 100644
index 000000000..2a00e229a
--- /dev/null
+++ b/tests/test_memory/test_direct_mem0.py
@@ -0,0 +1,184 @@
+"""Tests for the Direct Mem0 adapter lifecycle."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from headroom.memory.backends.direct_mem0 import DirectMem0Adapter, Mem0Config
+
+
+def _adapter() -> DirectMem0Adapter:
+    return DirectMem0Adapter(Mem0Config(enable_graph=True))
+
+
+@pytest.mark.asyncio
+async def test_close_drains_tasks_and_closes_initialized_resources() -> None:
+    adapter = _adapter()
+    resources = {
+        "_mem0_client": MagicMock(),
+        "_openai_client": MagicMock(),
+        "_qdrant_client": MagicMock(),
+        "_neo4j_driver": MagicMock(),
+    }
+    resources["_mem0_client"].close = AsyncMock()
+    for name, resource in resources.items():
+        setattr(adapter, name, resource)
+
+    task = asyncio.create_task(asyncio.sleep(0, result="saved"))
+    adapter._background_tasks["task_1"] = task
+
+    await adapter.close(timeout=1.0)
+
+    assert adapter.get_pending_tasks() == []
+    assert adapter.get_task_status("task_1") == {
+        "status": "completed",
+        "result": "saved",
+    }
+    resources["_mem0_client"].close.assert_awaited_once_with()
+    for resource in resources.values():
+        resource.close.assert_called_once_with()
+    assert adapter._initialized is False
+    assert adapter._mem0_client is None
+    assert adapter._openai_client is None
+    assert adapter._qdrant_client is None
+    assert adapter._neo4j_driver is None
+
+    await adapter.close(timeout=0.01)
+    resources["_mem0_client"].close.assert_awaited_once_with()
+    for resource in resources.values():
+        resource.close.assert_called_once_with()
+
+
+@pytest.mark.asyncio
+async def test_close_timeout_keeps_tasks_and_resources_attached() -> None:
+    adapter = _adapter()
+    release = asyncio.Event()
+    resource = MagicMock()
+    adapter._mem0_client = resource
+    task = asyncio.create_task(release.wait())
+    adapter._background_tasks["task_1"] = task
+    await asyncio.sleep(0)
+
+    with pytest.raises(TimeoutError, match="task_1"):
+        await adapter.close(timeout=0.01)
+
+    assert not task.done()
+    assert adapter.get_pending_tasks() == ["task_1"]
+    assert adapter._mem0_client is resource
+    resource.close.assert_not_called()
+
+    release.set()
+    await adapter.close(timeout=1.0)
+
+    assert adapter.get_pending_tasks() == []
+    assert adapter.get_task_status("task_1") == {
+        "status": "completed",
+        "result": True,
+    }
+    resource.close.assert_called_once_with()
+
+
+@pytest.mark.asyncio
+async def test_close_does_not_close_resources_while_sync_worker_is_running() -> None:
+    adapter = _adapter()
+    worker_started = threading.Event()
+    release_worker = threading.Event()
+
+    class BlockingMem0Client:
+        def __init__(self) -> None:
+            self.close_calls = 0
+
+        def add(self, *_args: object, **_kwargs: object) -> dict[str, list[dict[str, str]]]:
+            worker_started.set()
+            assert release_worker.wait(timeout=5.0), "test did not release worker"
+            return {"results": [{"id": "memory-1", "memory": "saved"}]}
+
+        def close(self) -> None:
+            self.close_calls += 1
+
+    client = BlockingMem0Client()
+    adapter._mem0_client = client
+    adapter._initialized = True
+
+    memory = await adapter.save_memory(
+        content="saved",
+        user_id="user-1",
+        importance=0.5,
+        background=True,
+    )
+    task_id = memory.metadata["_task_id"]
+
+    for _ in range(100):
+        if worker_started.is_set():
+            break
+        await asyncio.sleep(0.01)
+    assert worker_started.is_set()
+
+    with pytest.raises(TimeoutError, match=task_id):
+        await adapter.close(timeout=0.01)
+
+    assert client.close_calls == 0
+    assert adapter._mem0_client is client
+    assert adapter.get_pending_tasks() == [task_id]
+
+    release_worker.set()
+    await adapter.close(timeout=1.0)
+
+    assert client.close_calls == 1
+    assert adapter._mem0_client is None
+    assert adapter.get_pending_tasks() == []
+    assert adapter.get_task_status(task_id)["status"] == "completed"
+
+
+@pytest.mark.asyncio
+async def test_concurrent_close_calls_serialize_resource_cleanup() -> None:
+    adapter = _adapter()
+    close_started = asyncio.Event()
+    release_close = asyncio.Event()
+    resource = MagicMock()
+
+    async def slow_close() -> None:
+        close_started.set()
+        await release_close.wait()
+
+    resource.close = AsyncMock(side_effect=slow_close)
+    adapter._mem0_client = resource
+
+    first = asyncio.create_task(adapter.close())
+    await close_started.wait()
+    second = asyncio.create_task(adapter.close())
+    await asyncio.sleep(0)
+
+    resource.close.assert_awaited_once_with()
+    assert not first.done()
+    assert not second.done()
+
+    release_close.set()
+    await asyncio.gather(first, second)
+
+    resource.close.assert_awaited_once_with()
+
+
+@pytest.mark.asyncio
+async def test_wait_for_task_timeout_does_not_cancel_background_write() -> None:
+    adapter = _adapter()
+    release = asyncio.Event()
+    task = asyncio.create_task(release.wait())
+    adapter._background_tasks["task_1"] = task
+
+    assert await adapter.wait_for_task("task_1", timeout=0.01) == {
+        "status": "timeout",
+        "task_id": "task_1",
+    }
+    assert not task.done()
+    assert adapter.get_pending_tasks() == ["task_1"]
+
+    release.set()
+    assert await adapter.wait_for_task("task_1", timeout=1.0) == {
+        "status": "completed",
+        "result": True,
+    }
diff --git a/tests/test_memory/test_entity_ref_sanitization.py b/tests/test_memory/test_entity_ref_sanitization.py
new file mode 100644
index 000000000..70bbd6592
--- /dev/null
+++ b/tests/test_memory/test_entity_ref_sanitization.py
@@ -0,0 +1,302 @@
+"""Regression tests for entity_refs type safety.
+
+`entity_refs` is typed `list[str]` everywhere, but nothing enforced that at
+runtime. A caller that mistakenly passed the typed
+`{"entity": ..., "entity_type": ...}` shape (the format `extracted_entities`
+expects) into the plain `entities` field of `save_memory` got those dicts
+persisted verbatim into `entity_refs` -- both in the `memories` table and in
+the duplicated copy the vector index keeps for post-filtering.
+
+Every later `search_memories` call does `set().update(memory.entity_refs)`
+while collecting entities for graph expansion. Hashing a dict raises
+`TypeError: unhashable type: 'dict'`, and because that happens inside the
+vector-result loop (not guarded per-item) it aborted the *entire* search for
+any query whose top-k included one poisoned row. The proxy's memory handler
+swallows the exception and returns no memories, so recall went quietly dark
+rather than failing loudly.
+
+See https://github.com/headroomlabs-ai/headroom/issues/2947.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from headroom.memory.adapters.hnsw import IndexedMemoryMetadata
+from headroom.memory.adapters.sqlite_vector import VectorMetadata
+from headroom.memory.backends.local import LocalBackend
+from headroom.memory.models import Memory, normalize_entity_refs
+
+# The malformed shape that started all of this: the extracted_entities format
+# passed into a field that expects plain names.
+DICT_REF = {"entity": "Project X", "entity_type": "project"}
+
+
+# =============================================================================
+# The helper itself
+# =============================================================================
+
+
+def test_normalize_entity_refs_unwraps_dicts_and_drops_junk() -> None:
+    """Dicts are unwrapped to their name; anything unusable is dropped."""
+    assert normalize_entity_refs(["Alice", DICT_REF]) == ["Alice", "Project X"]
+
+    # Nothing usable in these: no name to recover, so they are dropped rather
+    # than stringified into garbage entity names like "{'foo': 'bar'}".
+    assert normalize_entity_refs([{"entity_type": "project"}, {}, None, 42, ""]) == []
+
+    # Common no-op cases stay untouched.
+    assert normalize_entity_refs(["Alice", "Bob"]) == ["Alice", "Bob"]
+    assert normalize_entity_refs(None) == []
+    assert normalize_entity_refs([]) == []
+
+
+def test_normalize_entity_refs_preserves_order_and_deduplicates() -> None:
+    """A name already present is not appended twice, and order is stable."""
+    assert normalize_entity_refs(["Alice", DICT_REF, "Alice", "Project X"]) == [
+        "Alice",
+        "Project X",
+    ]
+
+
+# =============================================================================
+# Write path: stop new corruption at the door
+# =============================================================================
+
+
+@pytest.mark.asyncio
+async def test_save_memory_sanitizes_dict_shaped_entities_param() -> None:
+    """`entities` items that are dicts get coerced to plain names before storage."""
+    backend = LocalBackend()
+    backend._initialized = True
+
+    saved: list[Memory] = []
+
+    async def fake_add(**kwargs: object) -> Memory:
+        memory = Memory(
+            id="new-memory",
+            content=str(kwargs["content"]),
+            user_id=str(kwargs["user_id"]),
+            entity_refs=list(kwargs["entity_refs"]),  # type: ignore[arg-type]
+        )
+        saved.append(memory)
+        return memory
+
+    backend._hierarchical_memory = SimpleNamespace(add=AsyncMock(side_effect=fake_add))
+    backend._graph = SimpleNamespace(
+        get_entity_by_name=AsyncMock(return_value=None),
+        add_entity=AsyncMock(return_value=SimpleNamespace(id="entity-id")),
+        add_relationship=AsyncMock(),
+    )
+
+    # Without the fix this raises AttributeError: 'dict' object has no
+    # attribute 'lower' during graph linking.
+    await backend.save_memory(
+        content="Alice manages Project X",
+        user_id="alice",
+        entities=[DICT_REF],  # type: ignore[list-item]
+    )
+
+    assert saved[0].entity_refs == ["Project X"]
+
+
+@pytest.mark.asyncio
+async def test_save_memory_merges_dict_entities_with_extracted_entities() -> None:
+    """A name arriving through both `entities` and `extracted_entities` is stored once."""
+    backend = LocalBackend()
+    backend._initialized = True
+
+    saved: list[Memory] = []
+
+    async def fake_add(**kwargs: object) -> Memory:
+        memory = Memory(
+            id="new-memory",
+            content=str(kwargs["content"]),
+            user_id=str(kwargs["user_id"]),
+            entity_refs=list(kwargs["entity_refs"]),  # type: ignore[arg-type]
+        )
+        saved.append(memory)
+        return memory
+
+    backend._hierarchical_memory = SimpleNamespace(add=AsyncMock(side_effect=fake_add))
+    backend._graph = SimpleNamespace(
+        get_entity_by_name=AsyncMock(return_value=None),
+        add_entity=AsyncMock(return_value=SimpleNamespace(id="entity-id")),
+        add_relationship=AsyncMock(),
+    )
+
+    await backend.save_memory(
+        content="Alice manages Project X",
+        user_id="alice",
+        entities=[DICT_REF],  # type: ignore[list-item]
+        extracted_entities=[{"entity": "Project X", "entity_type": "project"}],
+    )
+
+    assert saved[0].entity_refs == ["Project X"]
+
+
+# =============================================================================
+# Read path: heal rows that were already written before the fix
+# =============================================================================
+
+
+def test_memory_from_dict_heals_stored_dict_refs() -> None:
+    """Rows persisted before the fix load as plain names instead of dicts."""
+    now = datetime.now(timezone.utc).isoformat()
+    memory = Memory.from_dict(
+        {
+            "id": "poisoned-memory",
+            "content": "Alice manages Project X",
+            "user_id": "alice",
+            "created_at": now,
+            "valid_from": now,
+            "importance": 0.5,
+            "entity_refs": [DICT_REF, "Alice"],
+        }
+    )
+
+    assert memory.entity_refs == ["Project X", "Alice"]
+
+
+def test_vector_metadata_from_json_heals_stored_dict_refs() -> None:
+    """The vector index keeps its own copy of entity_refs; heal that one too."""
+    now = datetime.now(timezone.utc).isoformat()
+    metadata = VectorMetadata.from_json(
+        json.dumps(
+            {
+                "memory_id": "poisoned-memory",
+                "user_id": "alice",
+                "session_id": None,
+                "agent_id": None,
+                "valid_until": None,
+                "entity_refs": [DICT_REF],
+                "content": "Alice manages Project X",
+                "created_at": now,
+                "importance": 0.5,
+                "metadata": {},
+            }
+        )
+    )
+
+    assert metadata.entity_refs == ["Project X"]
+    assert metadata.to_memory().entity_refs == ["Project X"]
+
+
+def test_indexed_memory_metadata_from_dict_heals_stored_dict_refs() -> None:
+    """Same for the HNSW index's metadata copy."""
+    now = datetime.now(timezone.utc).isoformat()
+    metadata = IndexedMemoryMetadata.from_dict(
+        {
+            "memory_id": "poisoned-memory",
+            "user_id": "alice",
+            "session_id": None,
+            "agent_id": None,
+            "valid_until": None,
+            "entity_refs": [DICT_REF],
+            "content": "Alice manages Project X",
+            "created_at": now,
+            "importance": 0.5,
+            "metadata": {},
+        }
+    )
+
+    assert metadata.entity_refs == ["Project X"]
+
+
+# =============================================================================
+# Search: a single bad row must not take the whole query down
+# =============================================================================
+
+
+def _backend_with_results(memories: list[Memory]) -> LocalBackend:
+    backend = LocalBackend()
+    backend._initialized = True
+    backend._hierarchical_memory = SimpleNamespace(
+        search=AsyncMock(return_value=[SimpleNamespace(memory=m, similarity=0.9) for m in memories])
+    )
+    backend._graph = SimpleNamespace(
+        get_entity_by_name=AsyncMock(return_value=None),
+        query_subgraph=AsyncMock(return_value=SimpleNamespace(entities=[], relationships=[])),
+    )
+    return backend
+
+
+@pytest.mark.asyncio
+async def test_search_memories_tolerates_dict_shaped_entity_refs() -> None:
+    """A single legacy/corrupted row with dict entity_refs must not crash search."""
+    poisoned = Memory(
+        id="poisoned-memory",
+        content="Alice manages Project X",
+        user_id="alice",
+        entity_refs=[DICT_REF],  # type: ignore[list-item]
+    )
+    clean = Memory(
+        id="clean-memory",
+        content="Bob manages Project Y",
+        user_id="alice",
+        entity_refs=["Project Y"],
+    )
+    backend = _backend_with_results([poisoned, clean])
+
+    # Without the fix this raises TypeError: unhashable type: 'dict'.
+    results = await backend.search_memories("Alice's work", "alice", include_related=True)
+
+    assert [r.memory.id for r in results] == ["poisoned-memory", "clean-memory"]
+    # The recovered name is still usable for graph expansion and is reported
+    # back to the caller as a plain string, not a dict.
+    assert results[0].related_entities == ["Project X"]
+    backend._graph.get_entity_by_name.assert_awaited()
+
+
+@pytest.mark.asyncio
+async def test_search_memories_entity_filter_matches_healed_refs() -> None:
+    """The `entities` filter lowercases each ref, which dicts also break.
+
+    On unfixed code this never gets that far -- the unconditional
+    `set().update()` above raises first -- but once refs are strings again the
+    filter has to actually match the recovered name.
+    """
+    poisoned = Memory(
+        id="poisoned-memory",
+        content="Alice manages Project X",
+        user_id="alice",
+        entity_refs=[DICT_REF],  # type: ignore[list-item]
+    )
+    backend = _backend_with_results([poisoned])
+
+    results = await backend.search_memories(
+        "Alice's work",
+        "alice",
+        include_related=False,
+        entities=["project x"],
+    )
+
+    assert [r.memory.id for r in results] == ["poisoned-memory"]
+
+
+@pytest.mark.asyncio
+async def test_search_memories_tolerates_dict_shaped_entities_filter() -> None:
+    """The filter argument comes from LLM tool input too, so it can be malformed."""
+    clean = Memory(
+        id="clean-memory",
+        content="Alice manages Project X",
+        user_id="alice",
+        entity_refs=["Project X"],
+    )
+    backend = _backend_with_results([clean])
+
+    # Without normalization this raises AttributeError: 'dict' object has no
+    # attribute 'lower' while building the filter set.
+    results = await backend.search_memories(
+        "Alice's work",
+        "alice",
+        include_related=False,
+        entities=[DICT_REF],  # type: ignore[list-item]
+    )
+
+    assert [r.memory.id for r in results] == ["clean-memory"]
diff --git a/tests/test_memory/test_mcp_server.py b/tests/test_memory/test_mcp_server.py
index cd2779627..b55f28218 100644
--- a/tests/test_memory/test_mcp_server.py
+++ b/tests/test_memory/test_mcp_server.py
@@ -219,6 +219,77 @@ def test_concurrent_tool_calls_share_backend_initialization(monkeypatch) -> None
     asyncio.run(scenario())
 
 
+def test_server_cleanup_closes_initialized_backend_once(monkeypatch) -> None:
+    async def scenario() -> None:
+        backend = SimpleNamespace(close=AsyncMock())
+        monkeypatch.setattr(mcp_server_mod, "Server", _CapturingServer)
+        monkeypatch.setattr(mcp_server_mod, "LocalBackend", lambda config: backend)
+        monkeypatch.setattr(mcp_server_mod, "_warm_up_backend", AsyncMock())
+
+        server = mcp_server_mod.create_memory_server("memory.db", user_id="alice")
+        await server.list_tools_handler()
+        await asyncio.sleep(0)
+
+        close_backend = server._headroom_close
+        await close_backend()
+        await close_backend()
+
+        backend.close.assert_awaited_once()
+
+    asyncio.run(scenario())
+
+
+def test_server_cleanup_cancels_pending_backend_initialization(monkeypatch) -> None:
+    async def scenario() -> None:
+        init_started = asyncio.Event()
+        backend = SimpleNamespace(close=AsyncMock())
+
+        async def warm_up(_backend, _user_id: str) -> None:
+            init_started.set()
+            await asyncio.Event().wait()
+
+        monkeypatch.setattr(mcp_server_mod, "Server", _CapturingServer)
+        monkeypatch.setattr(mcp_server_mod, "LocalBackend", lambda config: backend)
+        monkeypatch.setattr(mcp_server_mod, "_warm_up_backend", warm_up)
+
+        server = mcp_server_mod.create_memory_server("memory.db", user_id="alice")
+        await server.list_tools_handler()
+        await init_started.wait()
+
+        await server._headroom_close()
+
+        backend.close.assert_awaited_once()
+
+    asyncio.run(scenario())
+
+
+def test_run_closes_backend_when_stdio_exits(monkeypatch) -> None:
+    async def scenario() -> None:
+        close_backend = AsyncMock()
+        server = SimpleNamespace(
+            create_initialization_options=lambda: {},
+            run=AsyncMock(),
+            _headroom_close=close_backend,
+        )
+
+        class _StdioContext:
+            async def __aenter__(self):
+                return object(), object()
+
+            async def __aexit__(self, exc_type, exc_value, traceback):
+                return False
+
+        monkeypatch.setattr(mcp_server_mod, "create_memory_server", lambda *args: server)
+        monkeypatch.setattr(mcp_server_mod, "stdio_server", lambda: _StdioContext())
+
+        await mcp_server_mod._run("memory.db", "alice")
+
+        server.run.assert_awaited_once()
+        close_backend.assert_awaited_once()
+
+    asyncio.run(scenario())
+
+
 def test_memory_mcp_startup_context_reports_dynamic_project_db(tmp_path) -> None:
     project_dir = tmp_path / "project-a"
     project_dir.mkdir()
diff --git a/tests/test_memory/test_traffic_learner.py b/tests/test_memory/test_traffic_learner.py
index eee21450b..4faa037b8 100644
--- a/tests/test_memory/test_traffic_learner.py
+++ b/tests/test_memory/test_traffic_learner.py
@@ -362,6 +362,56 @@ class TestTrafficLearner:
         stats = learner.get_stats()
         assert stats["patterns_extracted"] >= 3
 
+    def test_pending_accumulator_is_bounded(self):
+        """One-off patterns that never reach ``min_evidence`` must not grow the
+        pending ``_pattern_counts`` accumulator without bound — the sibling
+        ``_saved_hashes`` is already trimmed to ``dedup_window`` and this one was
+        missed, so a long-lived proxy leaked memory across varied traffic. It is
+        now LRU-capped at ``max_pending_patterns``.
+
+        Sync test (drives the async accumulate via ``asyncio.run``) so it runs
+        without the pytest-asyncio plugin.
+        """
+        import asyncio
+
+        learner = TrafficLearner(backend=None, min_evidence=5, max_pending_patterns=8)
+
+        async def feed_one_offs() -> None:
+            for i in range(500):
+                await learner._accumulate(
+                    ExtractedPattern(
+                        category=PatternCategory.PREFERENCE,
+                        content=f"one-off pattern number {i}",
+                        importance=0.5,
+                    )
+                )
+
+        asyncio.run(feed_one_offs())
+        assert len(learner._pattern_counts) <= 8  # capped, not 500
+
+    def test_pending_accumulator_lru_still_promotes_corroborated_pattern(self):
+        """Capping the accumulator must not break promotion: a pattern
+        corroborated to ``min_evidence`` without interruption is still removed
+        from pending and recorded in ``_saved_hashes``."""
+        import asyncio
+
+        learner = TrafficLearner(backend=None, min_evidence=3, max_pending_patterns=100)
+        pattern = ExtractedPattern(
+            category=PatternCategory.PREFERENCE,
+            content="corroborated preference",
+            importance=0.5,
+        )
+
+        async def corroborate() -> None:
+            await learner._accumulate(pattern)  # count 1
+            await learner._accumulate(pattern)  # count 2
+            assert pattern.content_hash in learner._pattern_counts
+            await learner._accumulate(pattern)  # count 3 == min_evidence -> promote
+
+        asyncio.run(corroborate())
+        assert pattern.content_hash not in learner._pattern_counts  # removed on promotion
+        assert pattern.content_hash in learner._saved_hashes
+
     @pytest.mark.asyncio
     async def test_dedup(self, learner: TrafficLearner):
         """Test that identical patterns are deduplicated."""
@@ -854,6 +904,10 @@ class _FakeBackend:
 
         self._config = _types.SimpleNamespace(db_path=str(db_path))
         self._db_path = str(db_path)
+        self.refreshed_ids = []
+
+    async def refresh_memory_indexes(self, memory_id: str):
+        self.refreshed_ids.append(memory_id)
 
     async def save_memory(
         self,
@@ -1415,6 +1469,7 @@ class TestBumpEdgeCases:
         learner = TrafficLearner(backend=backend, min_evidence=1)
         await learner._bump_persisted_evidence("no-such-id")
         assert _read_traffic_rows(db) == []
+        assert backend.refreshed_ids == []
 
 
 # =============================================================================
@@ -2042,6 +2097,7 @@ class TestBumpPersistsLastSeenAt:
         # Should be parseable back.
         parsed = _parse_iso_timestamp(meta["last_seen_at"])
         assert parsed is not None
+        assert backend.refreshed_ids == ["row-1"]
 
 
 class TestHydrateLegacyRow:
diff --git a/tests/test_memory_query_policy.py b/tests/test_memory_query_policy.py
index cc80d6a62..0397f685d 100644
--- a/tests/test_memory_query_policy.py
+++ b/tests/test_memory_query_policy.py
@@ -69,6 +69,42 @@ def test_extract_sources_captures_anthropic_user_text_blocks() -> None:
     assert user_text == "help me refactor auth"
 
 
+def test_extract_sources_skips_system_reminder_blocks() -> None:
+    """Claude Code appends <system-reminder> harness blocks to the user turn.
+    Concatenated into the embedding input they dilute the real question below the
+    similarity floor so nothing is retrieved (#2195); they must be filtered out."""
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "how do I add caching to the auth handler?"},
+                {
+                    "type": "text",
+                    "text": "<system-reminder>\nThe user opened file x.\n</system-reminder>",
+                },
+            ],
+        },
+    ]
+
+    user_text, _tool_outputs, _assistant_turns = extract_memory_query_sources(messages)
+
+    assert user_text == "how do I add caching to the auth handler?"
+    assert "system-reminder" not in user_text
+
+
+def test_extract_sources_reminder_only_turn_yields_no_user_text() -> None:
+    messages = [
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": "<system-reminder>x</system-reminder>"}],
+        },
+    ]
+
+    user_text, _tool_outputs, _assistant_turns = extract_memory_query_sources(messages)
+
+    assert user_text == ""
+
+
 def test_extract_sources_captures_user_text_alongside_tool_result() -> None:
     """A user turn mixing a tool_result and a text block yields both: the text as
     the user query and the tool output as context."""
diff --git a/tests/test_memory_storage_router.py b/tests/test_memory_storage_router.py
index 9a1c7857c..90b36c946 100644
--- a/tests/test_memory_storage_router.py
+++ b/tests/test_memory_storage_router.py
@@ -48,10 +48,25 @@ def test_resolver_tier1_explicit_project_id_wins() -> None:
     )
     assert out is not None
     key, display = out
-    assert key == "billing-svc"
+    # The sanitized id stays as a human-readable prefix; a sha256 digest is
+    # appended so distinct ids that sanitize alike cannot collide.
+    assert key.startswith("billing-svc-")
+    assert len(key.split("-")[-1]) == 16
     assert display == "billing-svc"
 
 
+def test_resolver_tier1_distinct_ids_that_sanitize_alike_dont_collide() -> None:
+    r = ProjectResolver()
+    # "acme/api" and "acme api" both sanitize to "acme-api"; without the digest
+    # they would share one project store (cross-project memory leak).
+    k1, _ = r.resolve(_ctx(headers={"x-headroom-project-id": "acme/api"}))  # type: ignore[misc]
+    k2, _ = r.resolve(_ctx(headers={"x-headroom-project-id": "acme api"}))  # type: ignore[misc]
+    assert k1 != k2
+    # Same id resolves to a stable key across calls.
+    k1b, _ = r.resolve(_ctx(headers={"x-headroom-project-id": "acme/api"}))  # type: ignore[misc]
+    assert k1 == k1b
+
+
 def test_resolver_tier2_explicit_cwd_header() -> None:
     r = ProjectResolver()
     out = r.resolve(_ctx(headers={"x-headroom-cwd": "/Users/foo/code/project-b"}))
@@ -353,6 +368,20 @@ def test_router_user_mode_partitions_by_user(
     assert scope_b.display_name == "bob"
 
 
+def test_router_user_mode_distinct_ids_that_sanitize_alike_dont_collide(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # "alice/qa" and "alice qa" both sanitize to "alice-qa"; without the digest
+    # they would share one users/alice-qa/memory.db — a cross-user leak, the one
+    # thing USER mode exists to prevent.
+    router = _make_router(tmp_path, MemoryStorageMode.USER, monkeypatch)
+
+    _, scope_a = router.backend_for(_ctx(base_user_id="alice/qa"))
+    _, scope_b = router.backend_for(_ctx(base_user_id="alice qa"))
+
+    assert scope_a.db_path != scope_b.db_path
+
+
 def test_router_global_mode_reuses_legacy_path(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
diff --git a/tests/test_memory_wrapper.py b/tests/test_memory_wrapper.py
index c09a4c5e3..0bd009713 100644
--- a/tests/test_memory_wrapper.py
+++ b/tests/test_memory_wrapper.py
@@ -205,3 +205,22 @@ def test_memory_api_methods_delegate_to_underlying_memory() -> None:
     assert api.clear() == 2
     assert api.stats() == {"total": 2}
     assert fake_memory.last_clear == {"user_id": "alice"}
+
+
+def test_parse_response_with_memory_tolerates_non_object_memory_block() -> None:
+    from headroom.memory.inline_extractor import parse_response_with_memory
+
+    # The model controls the <memory> block. A valid-JSON non-object (a bare
+    # array) or a non-list `memories` field must not crash the parse: the
+    # `json.loads` succeeds, so the JSONDecodeError guard does not apply, and
+    # `.get`/iteration on the wrong type would otherwise raise.
+    assert parse_response_with_memory('hi <memory>["x"]</memory> bye').memories == []
+    assert parse_response_with_memory('<memory>{"memories": "nope"}</memory>').memories == []
+
+    # Malformed JSON is still handled, and a well-formed block still parses.
+    assert parse_response_with_memory("<memory>{not json</memory>").memories == []
+    parsed = parse_response_with_memory(
+        'text <memory>{"memories": [{"content": "User likes Python"}]}</memory>'
+    )
+    assert parsed.memories == [{"content": "User likes Python"}]
+    assert parsed.content == "text"
diff --git a/tests/test_mid_turn_steering.py b/tests/test_mid_turn_steering.py
index 1776190a6..81534ae0d 100644
--- a/tests/test_mid_turn_steering.py
+++ b/tests/test_mid_turn_steering.py
@@ -201,3 +201,115 @@ class TestMidTurnSteering:
         finally:
             proxy._active_streams.discard(session_key)
             proxy._mid_turn_queues.pop(session_key, None)
+
+    # --- #1608: mid-turn coalescing must be gated to Claude Code clients ---
+
+    def _normal_stream(self):
+        return self._create_mock_upstream_response(
+            [
+                b'event: message_start\ndata: {"type":"message_start"}\n\n',
+                b'event: message_stop\ndata: {"type":"message_stop"}\n\n',
+            ]
+        )
+
+    async def _run_stream(self, proxy, session_key, user_agent):
+        mock_response = self._normal_stream()
+        proxy.http_client.build_request = MagicMock(return_value=MagicMock())
+        proxy.http_client.send = AsyncMock(return_value=mock_response)
+        return await proxy._stream_response(
+            url="https://api.anthropic.com/v1/messages",
+            headers={"x-api-key": "sk-test", "user-agent": user_agent},
+            body={
+                "model": "claude-sonnet-4-20250514",
+                "max_tokens": 100,
+                "stream": True,
+                "messages": [{"role": "user", "content": "hi"}],
+            },
+            provider="anthropic",
+            model="claude-sonnet-4-20250514",
+            request_id="test-1608",
+            original_tokens=10,
+            optimized_tokens=10,
+            tokens_saved=0,
+            transforms_applied=[],
+            tags={},
+            optimization_latency=0.0,
+            session_key=session_key,
+        )
+
+    @pytest.mark.asyncio
+    async def test_non_claude_client_not_registered_active(self):
+        # An OpenCode subagent shares the main agent's body-derived session
+        # key; if it registered as active, the concurrent request would be
+        # swallowed. Non-Claude-Code clients must never be registered.
+        proxy = self._create_mock_proxy()
+        session_key = "opencode-session"
+        result = await self._run_stream(proxy, session_key, "opencode/1.0")
+        try:
+            assert session_key not in proxy._active_streams
+        finally:
+            async for _chunk in result.body_iterator:
+                pass
+            proxy._active_streams.discard(session_key)
+            proxy._mid_turn_queues.pop(session_key, None)
+
+    @pytest.mark.asyncio
+    async def test_claude_code_client_registered_active(self):
+        proxy = self._create_mock_proxy()
+        session_key = "claude-session"
+        result = await self._run_stream(proxy, session_key, "claude-code/1.2.3")
+        try:
+            assert session_key in proxy._active_streams
+        finally:
+            async for _chunk in result.body_iterator:
+                pass
+            proxy._active_streams.discard(session_key)
+            proxy._mid_turn_queues.pop(session_key, None)
+
+    @pytest.mark.asyncio
+    async def test_pending_event_not_emitted_for_non_claude(self):
+        # Even with a queued message, a non-Claude-Code stream must not emit the
+        # custom `headroom_pending_messages` SSE event — @ai-sdk/anthropic can't
+        # parse it and throws "invalid_union / No matching discriminator".
+        proxy = self._create_mock_proxy()
+        session_key = "opencode-pending"
+        proxy._queue_mid_turn_message(
+            session_key, {"messages": [{"role": "user", "content": "queued"}]}
+        )
+        result = await self._run_stream(proxy, session_key, "opencode/1.0")
+        try:
+            body = b"".join([chunk async for chunk in result.body_iterator])
+            assert b"headroom_pending_messages" not in body
+        finally:
+            proxy._active_streams.discard(session_key)
+            proxy._mid_turn_queues.pop(session_key, None)
+
+    @pytest.mark.asyncio
+    async def test_pending_event_emitted_for_claude_code(self):
+        proxy = self._create_mock_proxy()
+        session_key = "claude-pending"
+        proxy._queue_mid_turn_message(
+            session_key, {"messages": [{"role": "user", "content": "queued"}]}
+        )
+        result = await self._run_stream(proxy, session_key, "claude-code/1.2.3")
+        try:
+            body = b"".join([chunk async for chunk in result.body_iterator])
+            assert b"headroom_pending_messages" in body
+        finally:
+            proxy._active_streams.discard(session_key)
+            proxy._mid_turn_queues.pop(session_key, None)
+
+
+class TestCoalescingCapability:
+    """The capability predicate that gates the mid-turn coalescing protocol."""
+
+    def test_claude_code_supports_coalescing(self):
+        from headroom.proxy.auth_mode import supports_mid_turn_coalescing
+
+        assert supports_mid_turn_coalescing("claude-code") is True
+
+    def test_other_clients_do_not_support_coalescing(self):
+        from headroom.proxy.auth_mode import supports_mid_turn_coalescing
+
+        for client in ("opencode", "codex", "cursor", "aider", "", None):
+            assert supports_mid_turn_coalescing(client) is False
diff --git a/tests/test_mixed_content_scan_cache.py b/tests/test_mixed_content_scan_cache.py
new file mode 100644
index 000000000..a0dd22625
--- /dev/null
+++ b/tests/test_mixed_content_scan_cache.py
@@ -0,0 +1,197 @@
+"""The memoised JSON-block scan must be indistinguishable from the original.
+
+This is a parser change, so equality is checked against a literal transcription
+of the pre-cache implementation rather than against expected values — a golden
+test would only encode whatever the new code does.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+
+import pytest
+
+from headroom.transforms.mixed_content import (
+    _extract_json_block,
+    _has_valid_json_block_with_text,
+    is_mixed_content,
+    split_into_sections,
+)
+
+
+def _extract_json_block_original(lines: list[str], start: int) -> tuple[str | None, int]:
+    """Verbatim pre-cache implementation, kept as the oracle."""
+    bracket_count = 0
+    brace_count = 0
+    json_lines = []
+    in_string = False
+    escaped = False
+
+    for i in range(start, len(lines)):
+        line = lines[i]
+        json_lines.append(line)
+
+        for ch in line:
+            if escaped:
+                escaped = False
+                continue
+            if ch == "\\":
+                if in_string:
+                    escaped = True
+                continue
+            if ch == '"':
+                in_string = not in_string
+                continue
+            if in_string:
+                continue
+            if ch == "[":
+                bracket_count += 1
+            elif ch == "]":
+                bracket_count -= 1
+            elif ch == "{":
+                brace_count += 1
+            elif ch == "}":
+                brace_count -= 1
+
+        if bracket_count <= 0 and brace_count <= 0 and json_lines:
+            return "\n".join(json_lines), i
+
+    return None, start
+
+
+def _corpus() -> list[str]:
+    r = random.Random(20260806)
+    out = [
+        "",
+        "\n",
+        "   \n\t\n",
+        "{",
+        "}",
+        '{"a": 1}',
+        '[\n{"id": 1}\n]',
+        '{"s": "a ] b } c"}',  # delimiters inside strings
+        '{"s": "escaped \\" quote }"}',  # escaped quote
+        '{"s": "trailing backslash \\\\"}',
+        '{"s": "line one\\',  # line ends mid-escape
+        'text before\n{"a": 1}\ntext after',
+        '```json\n{"a": 1}\n```\nprose here',
+        "\n".join(f'{{ level: "info", seq: {i}, msg: "x"' for i in range(40)),  # never balances
+        "\n".join(json.dumps({"id": i})[:9] for i in range(40)),  # truncated JSONL
+        "\n".join(json.dumps({"id": i, "m": "ok"}) for i in range(40)),  # valid JSONL
+        json.dumps([{"id": i, "n": f"x{i}"} for i in range(40)], indent=2),
+        "\n".join(f"2026-08-06 13:00:{i % 60:02d} INFO did thing {i}" for i in range(40)),
+        "\n".join(f"    cfg = {{'k{i}': 'v{i}'," for i in range(40)),
+    ]
+    # Randomised mixtures, including unbalanced and string-heavy fragments.
+    frags = [
+        '{"a": 1}',
+        "[",
+        "]",
+        "{",
+        "}",
+        "plain prose line",
+        '{"s": "] } ["}',
+        '{"x": "\\\\"}',
+        "",
+        "   ",
+        '{ unquoted: "value"',
+        "```",
+        "path/to/f.py:12: hit",
+    ]
+    for _ in range(120):
+        out.append("\n".join(r.choice(frags) for _ in range(r.randint(1, 30))))
+    return out
+
+
+CORPUS = _corpus()
+
+
+@pytest.mark.parametrize("content", CORPUS, ids=range(len(CORPUS)))
+def test_every_candidate_index_matches_the_original(content: str) -> None:
+    lines = content.split("\n")
+    shared: dict = {}
+    for i in range(len(lines)):
+        expected = _extract_json_block_original(lines, i)
+        # Both with a cold cache and with the shared one the real callers use,
+        # since a stale entry would only show up on the second path.
+        assert _extract_json_block(lines, i) == expected, f"cold cache, line {i}"
+        assert _extract_json_block(lines, i, cache=shared) == expected, f"shared cache, line {i}"
+        assert _extract_json_block(lines, i, cache=shared) == expected, f"replayed, line {i}"
+
+
+@pytest.mark.parametrize("content", CORPUS, ids=range(len(CORPUS)))
+def test_public_behaviour_is_unchanged(content: str) -> None:
+    """The three functions built on the scan must agree with the oracle."""
+    lines = content.split("\n")
+
+    def oracle_has_json_with_text() -> bool:
+        for index, line in enumerate(lines):
+            if not line.strip().startswith(("[", "{")):
+                continue
+            block, end_index = _extract_json_block_original(lines, index)
+            if block is None:
+                continue
+            try:
+                json.loads(block)
+            except (TypeError, ValueError):
+                continue
+            if "\n".join(lines[:index]).strip() or "\n".join(lines[end_index + 1 :]).strip():
+                return True
+        return False
+
+    assert _has_valid_json_block_with_text(content) == oracle_has_json_with_text()
+    # split_into_sections must partition the content exactly as before.
+    sections = split_into_sections(content)
+    assert [(s.content, s.content_type, s.start_line, s.end_line) for s in sections] == [
+        (s.content, s.content_type, s.start_line, s.end_line) for s in split_into_sections(content)
+    ]
+    is_mixed_content(content)  # must not raise
+
+
+def test_each_line_is_scanned_once_per_state(monkeypatch) -> None:
+    """The memo's actual guarantee, asserted without timing.
+
+    Character scanning happens at most twice per (line, entry-state) pair: once
+    during the first scan, which runs uncached because nothing has yet shown the
+    content to be pathological, and once more while populating the cache. Before
+    the memo it happened once per (candidate, line) pair, which is what made this
+    shape quadratic in *character* work.
+
+    This remains a constant-factor win — the walk over remaining lines is still
+    O(candidates x lines) — so the assertion counts scans, not wall time.
+    """
+    from collections import Counter
+
+    from headroom.transforms import mixed_content as mc
+
+    calls: list[tuple[str, bool, bool]] = []
+    real = mc._scan_line
+
+    def counting(line, in_string, escaped):
+        calls.append((line, in_string, escaped))
+        return real(line, in_string, escaped)
+
+    monkeypatch.setattr(mc, "_scan_line", counting)
+
+    n = 400
+    body = "\n".join(f'{{ level: "info", seq: {i}, msg: "did a thing"' for i in range(n))
+    mc.split_into_sections(body)
+
+    worst = max(Counter(calls).values())
+    assert worst <= 2, f"a (line, state) pair was scanned {worst} times"
+    # Without the memo this shape scans on the order of n^2/2 = 80,000 times.
+    assert len(calls) <= 3 * n, f"{len(calls)} scans for {n} lines"
+
+
+def test_pathological_shape_stays_within_a_sane_budget() -> None:
+    """Absolute smoke check: this input took 2.4s before the memo."""
+    import time
+
+    body = "\n".join(f'{{ level: "info", seq: {i}, msg: "did a thing"' for i in range(1600))
+    best = float("inf")
+    for _ in range(3):
+        start = time.perf_counter()
+        split_into_sections(body)
+        best = min(best, time.perf_counter() - start)
+    assert best < 1.5, f"{best:.2f}s for 1600 lines; was 2.4s before the scan memo"
diff --git a/tests/test_observability_metrics.py b/tests/test_observability_metrics.py
index 5a7297476..eb8c2c521 100644
--- a/tests/test_observability_metrics.py
+++ b/tests/test_observability_metrics.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -12,10 +13,13 @@ from opentelemetry.sdk.metrics.export import InMemoryMetricReader
 from headroom.observability import (
     HeadroomOtelMetrics,
     get_otel_meter,
+    register_otel_metric_attribute_provider,
     reset_otel_metrics,
     set_otel_metrics,
+    unregister_otel_metric_attribute_provider,
 )
 from headroom.proxy.prometheus_metrics import PrometheusMetrics
+from headroom.telemetry.context import MAX_DISTINCT_MODELS
 from headroom.transforms.pipeline import TransformPipeline
 
 
@@ -49,6 +53,7 @@ def test_headroom_otel_metrics_records_proxy_and_pipeline_metrics() -> None:
         input_tokens=120,
         output_tokens=30,
         tokens_saved=45,
+        tool_search_saved=15,
         latency_ms=18.5,
         cached=True,
         overhead_ms=4.0,
@@ -58,6 +63,16 @@ def test_headroom_otel_metrics_records_proxy_and_pipeline_metrics() -> None:
         cache_write_5m_tokens=10,
         cache_write_1h_tokens=25,
         uncached_input_tokens=60,
+        attempted_input_tokens=165,
+        output_tokens_saved=8,
+        savings_usd={
+            "compression": 0.001,
+            "tool_schema": 0.0003,
+            "output_shaping": 0.0008,
+            "provider_cache": 0.0002,
+        },
+        project="checkout",
+        client="claude-code",
     )
     otel_metrics.record_proxy_cache_bust(tokens_lost=7)
     otel_metrics.record_pipeline_run(
@@ -82,6 +97,56 @@ def test_headroom_otel_metrics_records_proxy_and_pipeline_metrics() -> None:
     )
     assert request_point.value == 1
 
+    saved_tokens = metrics["headroom.proxy.tokens.saved"]
+    saved_point = _find_point(
+        saved_tokens,
+        provider="anthropic",
+        model="claude-opus-4-6",
+        cached=True,
+    )
+    assert saved_point.value == 60
+
+    tool_schema_saved = metrics["headroom.proxy.tokens.tool_schema_saved"]
+    tool_schema_point = _find_point(
+        tool_schema_saved,
+        provider="anthropic",
+        model="claude-opus-4-6",
+        cached=True,
+    )
+    assert tool_schema_point.value == 15
+
+    attempted_input = metrics["headroom.proxy.tokens.attempted_input"]
+    attempted_point = _find_point(
+        attempted_input,
+        **{
+            "headroom.project": "checkout",
+            "headroom.client": "claude-code",
+        },
+    )
+    assert attempted_point.value == 165
+
+    output_saved = metrics["headroom.proxy.tokens.output_saved"]
+    output_saved_point = _find_point(
+        output_saved,
+        **{
+            "headroom.project": "checkout",
+            "headroom.client": "claude-code",
+        },
+    )
+    assert output_saved_point.value == 8
+
+    savings_usd = metrics["headroom.proxy.savings.usd"]
+    compression_usd = _find_point(savings_usd, source="compression", estimated=True)
+    assert compression_usd.value == pytest.approx(0.001)
+
+    compression_saved = metrics["headroom.compression.tokens.saved"]
+    compression_saved_point = _find_point(
+        compression_saved,
+        provider="anthropic",
+        model="claude-opus-4-6",
+    )
+    assert compression_saved_point.value == 45
+
     latency = metrics["headroom.proxy.request.duration"]
     latency_point = _find_point(
         latency,
@@ -147,6 +212,77 @@ def test_get_otel_meter_uses_headrooms_configured_provider() -> None:
         reset_otel_metrics()
 
 
+def test_request_attribute_provider_enriches_core_and_savings_metrics() -> None:
+    reader = InMemoryMetricReader()
+    provider = MeterProvider(metric_readers=[reader])
+    otel_metrics = HeadroomOtelMetrics(meter_provider=provider)
+
+    def identity_attributes() -> dict[str, str]:
+        return {
+            "headroom.org": "acme",
+            "headroom.team": "payments",
+            "headroom.user": "alice",
+            # Canonical call-site dimensions must win over an extension.
+            "model": "must-not-override",
+            "source": "must-not-override",
+        }
+
+    register_otel_metric_attribute_provider(identity_attributes)
+    try:
+        otel_metrics.record_proxy_request(
+            provider="anthropic",
+            model="claude-sonnet-4-5",
+            input_tokens=100,
+            output_tokens=10,
+            tokens_saved=25,
+            latency_ms=20,
+        )
+        otel_metrics.record_savings_attribution(
+            [{"source": "tool_search", "tokens": 20, "usd": 0.001}]
+        )
+
+        metrics = _collect_metrics(reader)
+        request = _find_point(
+            metrics["headroom.proxy.requests"],
+            model="claude-sonnet-4-5",
+            **{
+                "headroom.org": "acme",
+                "headroom.team": "payments",
+                "headroom.user": "alice",
+            },
+        )
+        assert request.value == 1
+        attributed = _find_point(
+            metrics["headroom.savings.attributed.tokens"],
+            source="tool_search",
+            **{"headroom.user": "alice"},
+        )
+        assert attributed.value == 20
+    finally:
+        unregister_otel_metric_attribute_provider(identity_attributes)
+
+
+def test_failing_request_attribute_provider_is_fail_open() -> None:
+    reader = InMemoryMetricReader()
+    provider = MeterProvider(metric_readers=[reader])
+    otel_metrics = HeadroomOtelMetrics(meter_provider=provider)
+
+    def broken_provider() -> dict[str, str]:
+        raise RuntimeError("identity unavailable")
+
+    register_otel_metric_attribute_provider(broken_provider)
+    try:
+        otel_metrics.record_proxy_failed(provider="openai", model="gpt-5")
+        point = _find_point(
+            _collect_metrics(reader)["headroom.proxy.requests.failed"],
+            provider="openai",
+            model="gpt-5",
+        )
+        assert point.value == 1
+    finally:
+        unregister_otel_metric_attribute_provider(broken_provider)
+
+
 @dataclass
 class _SpyMetrics:
     pipeline_calls: list[dict[str, Any]] = field(default_factory=list)
@@ -157,9 +293,13 @@ class _SpyMetrics:
 
 @dataclass
 class _SpyProxyMetrics:
+    request_calls: list[dict[str, Any]] = field(default_factory=list)
     failed_calls: list[dict[str, Any]] = field(default_factory=list)
     rate_limited_calls: list[dict[str, Any]] = field(default_factory=list)
 
+    def record_proxy_request(self, **kwargs: Any) -> None:
+        self.request_calls.append(kwargs)
+
     def record_proxy_failed(self, **kwargs: Any) -> None:
         self.failed_calls.append(kwargs)
 
@@ -221,6 +361,49 @@ async def test_prometheus_metrics_reads_late_configured_otel_metrics() -> None:
         reset_otel_metrics()
 
 
+@pytest.mark.asyncio
+async def test_prometheus_metrics_forwards_savings_drilldown_fields_to_otel(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    expected_usd = {
+        "compression": 0.003,
+        "tool_schema": 0.0,
+        "output_shaping": 0.004,
+        "provider_cache": 0.0,
+    }
+    monkeypatch.setattr(
+        "headroom.proxy.prometheus_metrics.estimate_request_savings_usd",
+        lambda *_args, **_kwargs: expected_usd,
+    )
+    spy = _SpyProxyMetrics()
+    metrics = PrometheusMetrics(stateless=True)
+    set_otel_metrics(spy)  # type: ignore[arg-type]
+
+    try:
+        await metrics.record_request(
+            provider="anthropic",
+            model="claude-sonnet-4-5",
+            input_tokens=90,
+            output_tokens=12,
+            tokens_saved=30,
+            latency_ms=5.0,
+            attempted_input_tokens=120,
+            output_tokens_saved=4,
+            project="checkout",
+            client="claude-code",
+        )
+
+        assert len(spy.request_calls) == 1
+        call = spy.request_calls[0]
+        assert call["attempted_input_tokens"] == 120
+        assert call["output_tokens_saved"] == 4
+        assert call["savings_usd"] == expected_usd
+        assert call["project"] == "checkout"
+        assert call["client"] == "claude-code"
+    finally:
+        reset_otel_metrics()
+
+
 @pytest.mark.asyncio
 async def test_prometheus_metrics_clamps_negative_token_savings() -> None:
     metrics = PrometheusMetrics()
@@ -236,3 +419,108 @@ async def test_prometheus_metrics_clamps_negative_token_savings() -> None:
 
     assert metrics.tokens_saved_total == 0
     assert metrics.savings_history[-1][1] == 0
+
+
+@pytest.mark.asyncio
+async def test_prometheus_metrics_caps_model_cardinality() -> None:
+    """A client sending unbounded distinct models cannot grow the per-model dicts
+    past MAX_DISTINCT_MODELS + the "other" sentinel, while accounting stays exact."""
+    metrics = PrometheusMetrics(stateless=True)
+
+    async def record(model: str) -> None:
+        await metrics.record_request(
+            provider="anthropic",
+            model=model,
+            input_tokens=10,
+            output_tokens=1,
+            tokens_saved=1,
+            latency_ms=1.0,
+            cache_read_tokens=1,  # enter the prefix-cache block -> _cache_requests_by_model
+        )
+
+    # Fill exactly to the cap with distinct models: no bucketing yet.
+    for i in range(MAX_DISTINCT_MODELS):
+        await record(f"model_{i}")
+    assert len(metrics.requests_by_model) == MAX_DISTINCT_MODELS
+    assert len(metrics._cache_requests_by_model) == MAX_DISTINCT_MODELS
+    assert "other" not in metrics.requests_by_model
+
+    # New distinct models past the cap bucket into "other", never their own key.
+    for i in range(5):
+        await record(f"overflow_{i}")
+    assert "overflow_0" not in metrics.requests_by_model
+    assert metrics.requests_by_model["other"] == 5
+    assert metrics._cache_requests_by_model["other"] == 5
+    assert len(metrics.requests_by_model) == MAX_DISTINCT_MODELS + 1
+    assert len(metrics._cache_requests_by_model) == MAX_DISTINCT_MODELS + 1
+
+    # An already-tracked model keeps incrementing after the cap is reached.
+    await record("model_0")
+    assert metrics.requests_by_model["model_0"] == 2
+
+    # Accounting is preserved: every request is counted somewhere.
+    total_calls = MAX_DISTINCT_MODELS + 5 + 1
+    assert metrics.requests_total == total_calls
+    assert sum(metrics.requests_by_model.values()) == total_calls
+
+
+@pytest.mark.asyncio
+async def test_prometheus_metrics_model_cardinality_warns_once(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Bucketing into "other" logs exactly one warning, not one per request."""
+    metrics = PrometheusMetrics(stateless=True)
+    with caplog.at_level(logging.WARNING, logger="headroom.proxy"):
+        for i in range(MAX_DISTINCT_MODELS + 10):
+            await metrics.record_request(
+                provider="openai",
+                model=f"model_{i}",
+                input_tokens=10,
+                output_tokens=1,
+                tokens_saved=1,
+                latency_ms=1.0,
+            )
+    cap_warnings = [r for r in caplog.records if "cardinality cap" in r.getMessage()]
+    assert len(cap_warnings) == 1
+
+
+@pytest.mark.asyncio
+async def test_prometheus_metrics_reset_rearms_cardinality_warning() -> None:
+    """reset_runtime clears the model dicts and re-arms the one-shot cap warning."""
+    metrics = PrometheusMetrics(stateless=True)
+    for i in range(MAX_DISTINCT_MODELS + 5):
+        await metrics.record_request(
+            provider="openai",
+            model=f"model_{i}",
+            input_tokens=1,
+            output_tokens=1,
+            tokens_saved=1,
+            latency_ms=1.0,
+            cache_read_tokens=1,
+        )
+    assert metrics._model_cardinality_warned is True
+
+    await metrics.reset_runtime()
+
+    assert metrics._model_cardinality_warned is False
+    assert len(metrics.requests_by_model) == 0
+    assert len(metrics._cache_requests_by_model) == 0
+
+
+@pytest.mark.asyncio
+async def test_prometheus_metrics_export_bounds_model_series() -> None:
+    """export() emits at most MAX_DISTINCT_MODELS model series plus the 'other' bucket."""
+    metrics = PrometheusMetrics(stateless=True)
+    for i in range(MAX_DISTINCT_MODELS + 20):
+        await metrics.record_request(
+            provider="openai",
+            model=f"model_{i}",
+            input_tokens=1,
+            output_tokens=1,
+            tokens_saved=1,
+            latency_ms=1.0,
+        )
+    text = await metrics.export()
+    series = text.count("headroom_requests_by_model{")
+    assert series <= MAX_DISTINCT_MODELS + 1
+    assert 'headroom_requests_by_model{model="other"}' in text
diff --git a/tests/test_onnx_dependency_contract.py b/tests/test_onnx_dependency_contract.py
new file mode 100644
index 000000000..03c95cfa8
--- /dev/null
+++ b/tests/test_onnx_dependency_contract.py
@@ -0,0 +1,35 @@
+"""Dependency contract between Rust ort API 24 and pip ONNX Runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import tomllib
+from packaging.requirements import Requirement
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_shipping_ort_dependencies_require_api24_where_wheels_exist() -> None:
+    project = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]
+    optional = project["optional-dependencies"]
+
+    for extra in ("proxy", "voice"):
+        requirements = [
+            Requirement(value)
+            for value in optional[extra]
+            if Requirement(value).name == "onnxruntime"
+        ]
+        assert len(requirements) == 2
+        modern = next(
+            req
+            for req in requirements
+            if req.marker and req.marker.evaluate({"python_version": "3.11"})
+        )
+        legacy = next(
+            req
+            for req in requirements
+            if req.marker and req.marker.evaluate({"python_version": "3.10"})
+        )
+        assert modern.specifier.contains("1.24.0")
+        assert not legacy.specifier.contains("1.24.0")
diff --git a/tests/test_onnx_runtime.py b/tests/test_onnx_runtime.py
index 63d29abe6..3e7f6f949 100644
--- a/tests/test_onnx_runtime.py
+++ b/tests/test_onnx_runtime.py
@@ -2,10 +2,12 @@ import os
 import sys
 
 from headroom.onnx_runtime import (
+    ONNX_ALLOW_SPINNING_ENV,
     ONNX_CPU_ARENA_ENV,
     cpu_arena_enabled,
     create_cpu_session_options,
     hf_entry_known_absent,
+    onnx_thread_spinning_enabled,
 )
 
 
@@ -15,6 +17,10 @@ class _FakeSessionOptions:
         self.inter_op_num_threads = None
         self.enable_cpu_mem_arena = True
         self.enable_mem_pattern = True
+        self.config_entries: dict[str, str] = {}
+
+    def add_session_config_entry(self, key: str, value: str) -> None:
+        self.config_entries[key] = value
 
 
 class _FakeOrt:
@@ -26,6 +32,10 @@ class _FakeSessionOptionsWithoutToggles:
         self.intra_op_num_threads = None
         self.inter_op_num_threads = None
 
+    def add_session_config_entry(self, key: str, value: str) -> None:
+        # No config storage on this stand-in; ORT here just accepts the call.
+        return None
+
 
 class _FakeOrtWithoutToggles:
     SessionOptions = _FakeSessionOptionsWithoutToggles
@@ -108,6 +118,53 @@ def test_create_cpu_session_options_handles_older_session_options(monkeypatch):
     assert options.inter_op_num_threads is None
 
 
+def test_thread_spinning_disabled_by_default(monkeypatch):
+    # #2495: ORT thread pools spin-wait on all cores between inferences, so a
+    # long-lived proxy pegs every core while idle. Disable spinning by default.
+    monkeypatch.delenv(ONNX_ALLOW_SPINNING_ENV, raising=False)
+    monkeypatch.delenv(ONNX_CPU_ARENA_ENV, raising=False)
+
+    assert onnx_thread_spinning_enabled() is False
+    options = create_cpu_session_options(_FakeOrt)
+    assert options.config_entries.get("session.intra_op.allow_spinning") == "0"
+    assert options.config_entries.get("session.inter_op.allow_spinning") == "0"
+
+
+def test_thread_spinning_env_can_reenable(monkeypatch):
+    monkeypatch.setenv(ONNX_ALLOW_SPINNING_ENV, "1")
+    monkeypatch.delenv(ONNX_CPU_ARENA_ENV, raising=False)
+
+    assert onnx_thread_spinning_enabled() is True
+    options = create_cpu_session_options(_FakeOrt)
+    assert "session.intra_op.allow_spinning" not in options.config_entries
+    assert "session.inter_op.allow_spinning" not in options.config_entries
+
+
+def test_thread_spinning_env_explicit_off(monkeypatch):
+    monkeypatch.setenv(ONNX_ALLOW_SPINNING_ENV, "0")
+
+    assert onnx_thread_spinning_enabled() is False
+    options = create_cpu_session_options(_FakeOrt)
+    assert options.config_entries.get("session.intra_op.allow_spinning") == "0"
+
+
+def test_spinning_disable_is_best_effort_on_older_ort(monkeypatch):
+    # An ORT build that rejects the config key must not break session creation.
+    monkeypatch.delenv(ONNX_ALLOW_SPINNING_ENV, raising=False)
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    class _RejectingSessionOptions(_FakeSessionOptions):
+        def add_session_config_entry(self, key: str, value: str) -> None:
+            raise RuntimeError(f"unknown config key: {key}")
+
+    class _RejectingOrt:
+        SessionOptions = _RejectingSessionOptions
+
+    # Must not raise.
+    options = create_cpu_session_options(_RejectingOrt)
+    assert options.enable_cpu_mem_arena is False
+
+
 def _write_fake_hf_cache(
     root: str, repo_id: str, revision: str, *, no_exist_files: list[str]
 ) -> None:
diff --git a/tests/test_openai_codex_routing.py b/tests/test_openai_codex_routing.py
index 16a44ea1b..471d0d8ca 100644
--- a/tests/test_openai_codex_routing.py
+++ b/tests/test_openai_codex_routing.py
@@ -2,10 +2,12 @@ import asyncio
 import base64
 import json
 import sys
+from copy import deepcopy
 from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
 import anyio
+import httpx
 import pytest
 from fastapi import Request
 
@@ -14,6 +16,7 @@ from headroom.proxy.handlers.openai import (
     _is_allowed_websocket_origin,
     _openai_responses_unit_cache_key,
     _resolve_codex_routing_headers,
+    _responses_stateless_output_items,
 )
 
 
@@ -135,6 +138,30 @@ def test_openai_responses_unit_cache_key_includes_target_ratio() -> None:
     assert aggressive_key != balanced_key
 
 
+def test_responses_stateless_output_items_drop_unencrypted_reasoning() -> None:
+    assert _responses_stateless_output_items(None) == []
+    assert _responses_stateless_output_items(
+        [
+            {"type": "reasoning", "id": "rs-unusable", "summary": []},
+            {
+                "type": "reasoning",
+                "id": "rs-reusable",
+                "summary": [],
+                "encrypted_content": "encrypted",
+            },
+            {"type": "function_call", "call_id": "call-1"},
+        ]
+    ) == [
+        {
+            "type": "reasoning",
+            "id": "rs-reusable",
+            "summary": [],
+            "encrypted_content": "encrypted",
+        },
+        {"type": "function_call", "call_id": "call-1"},
+    ]
+
+
 class _DummyMetrics:
     async def record_request(self, **kwargs):  # noqa: ANN003
         return None
@@ -274,6 +301,106 @@ class _MemoryToolsOnlyHandler:
         return False
 
 
+class _MemoryContinuationHandler(_MemoryToolsOnlyHandler):
+    async def _ensure_initialized(self) -> None:
+        self._backend = True
+
+    async def _execute_memory_tool(
+        self,
+        name: str,
+        args: dict,
+        user_id: str,
+        provider: str,
+    ) -> str:
+        assert (name, args, user_id, provider) == (
+            "memory_search",
+            {},
+            "user-1",
+            "openai",
+        )
+        return '{"memories": []}'
+
+    def has_memory_tool_calls(self, response: dict, provider: str) -> bool:
+        assert provider == "openai"
+        return any(
+            item.get("name") == "memory_search"
+            for item in response.get("output", [])
+            if isinstance(item, dict)
+        )
+
+
+class _ZdrResponsesHandler(_DummyOpenAIHandler):
+    def __init__(self) -> None:
+        super().__init__()
+        self.memory_handler = _MemoryContinuationHandler()
+        self.requests: list[dict] = []
+
+    async def _retry_request(self, method: str, url: str, headers: dict, body: dict, **kwargs):
+        assert (method, url) == ("POST", "https://api.openai.com/v1/responses")
+        self.requests.append(deepcopy(body))
+        request = httpx.Request(method, url)
+        if len(self.requests) == 1:
+            return httpx.Response(
+                200,
+                json={
+                    "id": "resp-initial",
+                    "output": [
+                        {
+                            "type": "reasoning",
+                            "id": "reasoning-1",
+                            "summary": [],
+                            "encrypted_content": "encrypted-1",
+                        },
+                        {
+                            "type": "function_call",
+                            "id": "fc-1",
+                            "call_id": "call-1",
+                            "name": "memory_search",
+                            "arguments": "{}",
+                        },
+                    ],
+                    "usage": {"input_tokens": 3, "output_tokens": 2},
+                },
+                request=request,
+            )
+        if any(
+            isinstance(item, dict)
+            and item.get("type") == "reasoning"
+            and not item.get("encrypted_content")
+            for item in body.get("input", [])
+            if isinstance(body.get("input"), list)
+        ):
+            return httpx.Response(
+                400,
+                json={
+                    "error": {"message": "Reasoning item is not reusable without encrypted_content"}
+                },
+                request=request,
+            )
+        if "previous_response_id" in body:
+            return httpx.Response(
+                400,
+                json={
+                    "error": {
+                        "message": "Unknown parameter: 'previous_response_id'.",
+                        "type": "invalid_request_error",
+                        "param": "previous_response_id",
+                        "code": "unsupported_parameter",
+                    }
+                },
+                request=request,
+            )
+        return httpx.Response(
+            200,
+            json={
+                "id": "resp-final",
+                "output": [{"type": "message", "id": "message-1"}],
+                "usage": {"input_tokens": 8, "output_tokens": 3},
+            },
+            request=request,
+        )
+
+
 def _build_request(body: dict, headers: dict[str, str]) -> Request:
     payload = json.dumps(body).encode("utf-8")
 
@@ -423,7 +550,7 @@ def test_handle_openai_responses_chatgpt_codex_timeout_fails_open(monkeypatch):
     assert body["store"] is False
 
 
-def test_handle_openai_responses_api_auth_store_false_skips_memory_tools(monkeypatch):
+def test_handle_openai_responses_api_auth_store_false_injects_stateless_memory_tools(monkeypatch):
     request = _build_request(
         {"model": "gpt-4o-mini", "input": "hello", "store": False},
         {"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},
@@ -444,10 +571,113 @@ def test_handle_openai_responses_api_auth_store_false_skips_memory_tools(monkeyp
     _, url, _, body = handler.captured_request
     assert url == "https://api.openai.com/v1/responses"
     assert body["store"] is False
-    assert "tools" not in body
+    assert [tool["name"] for tool in body["tools"]] == ["memory_search"]
+    assert body["include"] == ["reasoning.encrypted_content"]
     assert memory_handler.compute_calls == 1
 
 
+@pytest.mark.parametrize("store", [pytest.param(None, id="omitted"), True, False])
+@pytest.mark.parametrize(
+    "include",
+    [
+        pytest.param(None, id="omitted"),
+        pytest.param(["response.output_text.done"], id="missing-marker"),
+        pytest.param(
+            ["response.output_text.done", "reasoning.encrypted_content"],
+            id="existing-marker",
+        ),
+        pytest.param("not-a-list", id="non-list"),
+    ],
+)
+def test_openai_responses_memory_continuation_is_zdr_safe(store, include, monkeypatch):
+    body = {
+        "model": "gpt-5.4",
+        "previous_response_id": "resp-inherited",
+        "input": [
+            {
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "hello"}],
+            },
+            {
+                "type": "reasoning",
+                "id": "prior-reasoning",
+                "summary": [],
+                "encrypted_content": "prior-encrypted",
+            },
+            {
+                "type": "reasoning",
+                "id": "prior-unencrypted-reasoning",
+                "summary": [],
+            },
+        ],
+    }
+    if include is not None:
+        body["include"] = include
+    if store is not None:
+        body["store"] = store
+    request = _build_request(
+        body,
+        {"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},
+    )
+    handler = _ZdrResponsesHandler()
+
+    monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
+
+    response = anyio.run(handler.handle_openai_responses, request)
+
+    assert response.status_code == 200
+    assert len(handler.requests) == 2
+    first_body, continuation_body = handler.requests
+    expected_include = (
+        ["reasoning.encrypted_content"]
+        if include is None
+        else (
+            include
+            if not isinstance(include, list)
+            else (
+                include
+                if "reasoning.encrypted_content" in include
+                else [*include, "reasoning.encrypted_content"]
+            )
+        )
+    )
+    assert first_body["include"] == expected_include
+    assert continuation_body["include"] == expected_include
+    assert first_body["previous_response_id"] == "resp-inherited"
+    assert ("store" in first_body) is (store is not None)
+    if store is not None:
+        assert first_body["store"] is store
+    else:
+        assert "store" not in first_body
+    assert continuation_body["input"] == [
+        body["input"][0],
+        body["input"][1],
+        {
+            "type": "reasoning",
+            "id": "reasoning-1",
+            "summary": [],
+            "encrypted_content": "encrypted-1",
+        },
+        {
+            "type": "function_call",
+            "id": "fc-1",
+            "call_id": "call-1",
+            "name": "memory_search",
+            "arguments": "{}",
+        },
+        {
+            "type": "function_call_output",
+            "call_id": "call-1",
+            "output": '{"memories": []}',
+        },
+    ]
+    assert "previous_response_id" not in continuation_body
+    assert ("store" in continuation_body) is (store is not None)
+    if store is not None:
+        assert continuation_body["store"] is store
+
+
 def test_handle_openai_responses_routes_api_key_auth_direct_to_openai(monkeypatch):
     request = _build_request(
         {"model": "gpt-4o-mini", "input": "hello"},
@@ -468,6 +698,74 @@ def test_handle_openai_responses_routes_api_key_auth_direct_to_openai(monkeypatc
     assert response.status_code == 200
 
 
+def test_handle_openai_responses_non_stream_adapts_sse_upstream(monkeypatch):
+    """A ``stream: false`` request whose upstream replies ``200
+    text/event-stream`` must be adapted to the terminal response JSON, not
+    converted into a 502 proxy_error (#2613)."""
+    import httpx
+
+    sse = (
+        b"event: response.completed\n"
+        b'data: {"type":"response.completed","response":{"id":"resp_sse_repro",'
+        b'"output":[],"usage":{"input_tokens":2,"output_tokens":1}}}\n\n'
+    )
+
+    class _SSEUpstreamHandler(_DummyOpenAIHandler):
+        async def _retry_request(self, method, url, headers, body, **kwargs):
+            self.captured_request = (method, url, headers, body)
+            return httpx.Response(
+                200,
+                headers={"content-type": "text/event-stream"},
+                content=sse,
+            )
+
+    request = _build_request(
+        {"model": "gpt-5.4", "stream": False, "input": "hello"},
+        {"Authorization": "Bearer sk-test"},
+    )
+    handler = _SSEUpstreamHandler()
+
+    monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
+
+    response = anyio.run(handler.handle_openai_responses, request)
+
+    assert response.status_code == 200, response.body
+    payload = json.loads(response.body)
+    assert payload["id"] == "resp_sse_repro"
+    assert response.headers["content-type"].startswith("application/json")
+
+
+def test_handle_openai_responses_non_stream_passes_through_unparseable_sse(monkeypatch):
+    """A 200 SSE upstream body with no recognizable terminal response event
+    must be forwarded as-is — never converted into a 502 (#2613)."""
+    import httpx
+
+    sse = b"event: response.weird\ndata: not-json\n\n"
+
+    class _SSEUpstreamHandler(_DummyOpenAIHandler):
+        async def _retry_request(self, method, url, headers, body, **kwargs):
+            self.captured_request = (method, url, headers, body)
+            return httpx.Response(
+                200,
+                headers={"content-type": "text/event-stream"},
+                content=sse,
+            )
+
+    request = _build_request(
+        {"model": "gpt-5.4", "stream": False, "input": "hello"},
+        {"Authorization": "Bearer sk-test"},
+    )
+    handler = _SSEUpstreamHandler()
+
+    monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
+
+    response = anyio.run(handler.handle_openai_responses, request)
+
+    assert response.status_code == 200, response.body
+    assert response.body == sse
+    assert response.headers["content-type"] == "text/event-stream"
+
+
 def test_handle_openai_responses_stream_skips_python_compression(monkeypatch):
     """PR-C5: Python no longer compresses /v1/responses (Rust handles it
     natively). The streaming forward path must still fire — only the
diff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.py
index 40d54680a..259c58838 100644
--- a/tests/test_openai_codex_ws_lifecycle.py
+++ b/tests/test_openai_codex_ws_lifecycle.py
@@ -70,6 +70,47 @@ class _DummyMetrics:
         self.codex_ws_frames.append(dict(kwargs))
 
 
+class _MemoryWsHandler:
+    def __init__(self) -> None:
+        self.config = SimpleNamespace(
+            inject_context=False,
+            inject_tools=True,
+            project_root_override="",
+        )
+        self._backend = False
+
+    def compute_memory_tool_definitions(self, provider: str) -> list[dict]:
+        assert provider == "openai"
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "memory_search",
+                    "description": "Search memory.",
+                    "parameters": {"type": "object", "properties": {}},
+                },
+            }
+        ]
+
+    async def _ensure_initialized(self) -> None:
+        self._backend = True
+
+    async def _execute_memory_tool(
+        self,
+        name: str,
+        args: dict,
+        user_id: str,
+        provider: str,
+    ) -> str:
+        assert (name, args, user_id, provider) == (
+            "memory_search",
+            {},
+            user_id,
+            "openai",
+        )
+        return '{"memories": []}'
+
+
 class _DummyOpenAIHandler(OpenAIHandlerMixin):
     OPENAI_API_URL = "https://api.openai.com"
 
@@ -114,6 +155,14 @@ class _DummyOpenAIHandler(OpenAIHandlerMixin):
         await emit_request_outcome(self, outcome)
 
 
+class _CapturingLogger:
+    def __init__(self) -> None:
+        self.entries = []
+
+    def log(self, entry) -> None:  # noqa: ANN001
+        self.entries.append(entry)
+
+
 class _FakeWebSocketDisconnect(Exception):
     """Mirrors the ``WebSocketDisconnect`` type-name check in the handler.
 
@@ -588,6 +637,131 @@ async def test_ws_first_frame_non_timeout_exception_keeps_generic_reason(
     assert "reason=compression_exception" in caplog.text
 
 
+@pytest.mark.asyncio
+async def test_ws_later_frame_compression_is_actually_forwarded(monkeypatch):
+    """Regression for issue #2819: a later (2nd+) Codex WS response.create
+    frame whose compressor reports ``modified=True`` must have the REWRITTEN
+    payload sent upstream — not the original raw frame.
+
+    A misplaced ``return`` (introduced in #1579) sat at the same indentation
+    as the surrounding ``except`` block, so it fired unconditionally after
+    every later-frame compression attempt — success or failure — and always
+    forwarded ``raw_after_store`` (the pre-compression frame). Compressed
+    later frames were silently discarded on the wire, and the token/savings
+    accounting that only runs on the (dead) success path never accumulated,
+    which is why ``headroom perf`` showed 0 tokens for Codex sessions with
+    multiple turns.
+    """
+    second_frame = _first_frame()
+    upstream = _FakeUpstream([], hold_after_events=True)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+
+    client_ws = _FakeWebSocket(
+        frames=[_first_frame(), second_frame],
+        hold_after_initial=True,
+        disconnect_after_n_sends=None,
+    )
+    handler = _DummyOpenAIHandler()
+    handler.config.optimize = True
+    monkeypatch.setattr(openai_module, "COMPRESSION_TIMEOUT_SECONDS", 30.0)
+
+    compressed_inner = {"model": "gpt-5.4", "input": "compressed"}
+    calls = 0
+
+    def _compress(payload, *, model, request_id, timing=None, client=None):
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            # First frame: not modified (exercises the other call site).
+            return payload, False, 0, [], "router_no_compression", 10, 10, 0
+        # Later frame: compressor DID find savings.
+        return compressed_inner, True, 5, ["text"], "compressed", 10, 5, 10
+
+    async def _trigger() -> None:
+        await asyncio.sleep(0.05)
+        client_ws.trigger_disconnect()
+
+    handler._compress_openai_responses_payload = _compress  # type: ignore[method-assign]
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        trigger_task = asyncio.create_task(_trigger())
+        try:
+            await asyncio.wait_for(handler.handle_openai_responses_ws(client_ws), timeout=2.0)
+        finally:
+            trigger_task.cancel()
+            try:
+                await trigger_task
+            except asyncio.CancelledError:
+                pass
+
+    # The compressed payload must reach upstream for the later frame — not
+    # the untouched original second_frame.
+    assert upstream.sent[-1] != second_frame
+    assert json.loads(upstream.sent[-1])["response"] == compressed_inner
+
+    # The success-path bookkeeping (tokens_saved / frame count) must run —
+    # proof the "modified" branch executed rather than short-circuiting.
+    modified_frames = [frame for frame in handler.metrics.codex_ws_frames if frame.get("modified")]
+    assert modified_frames, "expected at least one frame recorded as modified=True"
+
+
+@pytest.mark.asyncio
+async def test_ws_later_frame_non_timeout_exception_falls_back_to_original(caplog, monkeypatch):
+    """A non-timeout compression exception on a later frame must forward the
+    original frame via the except-block return (the line this PR moved back
+    inside the except), not fall through to the (now correctly gated)
+    success-path handling below it.
+    """
+    second_frame = _first_frame()
+    upstream = _FakeUpstream([], hold_after_events=True)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+
+    client_ws = _FakeWebSocket(
+        frames=[_first_frame(), second_frame],
+        hold_after_initial=True,
+    )
+    handler = _DummyOpenAIHandler()
+    handler.config.optimize = True
+    monkeypatch.setattr(openai_module, "COMPRESSION_TIMEOUT_SECONDS", 30.0)
+
+    calls = 0
+
+    async def _run(fn, *, timeout: float):
+        nonlocal calls
+        calls += 1
+        handler.compression_executor_calls += 1
+        handler.compression_executor_timeouts.append(timeout)
+        if calls == 2:
+            raise RuntimeError("simulated later-frame compression failure")
+        return fn()
+
+    def _noop_compress(payload, *, model, request_id, timing=None, client=None):
+        return payload, False, 0, [], "test_noop", 10, 10, 0
+
+    async def _trigger() -> None:
+        await asyncio.sleep(0.05)
+        client_ws.trigger_disconnect()
+
+    handler._compress_openai_responses_payload = _noop_compress  # type: ignore[method-assign]
+    handler._run_compression_in_executor = _run  # type: ignore[method-assign]
+    caplog.set_level(logging.INFO, logger="headroom.proxy")
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        trigger_task = asyncio.create_task(_trigger())
+        try:
+            await asyncio.wait_for(handler.handle_openai_responses_ws(client_ws), timeout=2.0)
+        finally:
+            trigger_task.cancel()
+            try:
+                await trigger_task
+            except asyncio.CancelledError:
+                pass
+
+    # The failed later frame must forward the original, unmodified frame.
+    assert upstream.sent[-1] == second_frame
+    assert "reason=compression_exception" in caplog.text
+
+
 @pytest.mark.asyncio
 async def test_ws_later_frame_timeout_records_failed_frame(caplog, monkeypatch):
     """Later Codex WS compression timeout records failed frame metrics."""
@@ -769,6 +943,145 @@ async def test_ws_session_metrics_include_dashboard_performance_timings():
     )
 
 
+@pytest.mark.asyncio
+async def test_ws_multi_turn_request_ids_are_unique():
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r_1"}}),
+        json.dumps(
+            {
+                "type": "response.completed",
+                "response": {
+                    "id": "r_1",
+                    "usage": {
+                        "input_tokens": 100,
+                        "input_tokens_details": {"cached_tokens": 75},
+                        "output_tokens": 12,
+                    },
+                },
+            }
+        ),
+        json.dumps({"type": "response.created", "response": {"id": "r_2"}}),
+        json.dumps(
+            {
+                "type": "response.completed",
+                "response": {
+                    "id": "r_2",
+                    "usage": {
+                        "input_tokens": 160,
+                        "input_tokens_details": {"cached_tokens": 120},
+                        "output_tokens": 20,
+                    },
+                },
+            }
+        ),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    handler = _DummyOpenAIHandler()
+    handler.logger = _CapturingLogger()
+
+    counter = 0
+
+    async def _next_request_id() -> str:
+        nonlocal counter
+        counter += 1
+        return f"req-ws-{counter}"
+
+    handler._next_request_id = _next_request_id  # type: ignore[method-assign]
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    logged = handler.logger.entries
+    assert len(logged) == 2
+    request_ids = [entry.request_id for entry in logged]
+    assert len(set(request_ids)) == len(request_ids)
+    assert [entry.input_tokens_optimized for entry in logged] == [100, 160]
+    assert [entry.output_tokens for entry in logged] == [12, 20]
+
+
+@pytest.mark.asyncio
+async def test_ws_no_delta_turn_emits_no_extra_request_log():
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r_1"}}),
+        json.dumps({"type": "response.completed", "response": {"id": "r_1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    handler = _DummyOpenAIHandler()
+    handler.logger = _CapturingLogger()
+
+    counter = 0
+
+    async def _next_request_id() -> str:
+        nonlocal counter
+        counter += 1
+        return f"req-ws-{counter}"
+
+    handler._next_request_id = _next_request_id  # type: ignore[method-assign]
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert len(handler.logger.entries) == 1
+    assert all(entry.input_tokens_optimized == 0 for entry in handler.logger.entries)
+    assert all(entry.output_tokens == 0 for entry in handler.logger.entries)
+
+
+@pytest.mark.asyncio
+async def test_ws_session_log_prefix_uses_session_id(caplog: pytest.LogCaptureFixture):
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r_1"}}),
+        json.dumps(
+            {
+                "type": "response.completed",
+                "response": {
+                    "id": "r_1",
+                    "usage": {
+                        "input_tokens": 100,
+                        "input_tokens_details": {"cached_tokens": 75},
+                        "output_tokens": 12,
+                    },
+                },
+            }
+        ),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    handler = _DummyOpenAIHandler()
+    handler.logger = _CapturingLogger()
+
+    counter = 0
+
+    async def _next_request_id() -> str:
+        nonlocal counter
+        counter += 1
+        return f"req-ws-{counter}"
+
+    handler._next_request_id = _next_request_id  # type: ignore[method-assign]
+    caplog.set_level(logging.INFO, logger="headroom.proxy")
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert handler.logger.entries
+    turn_request_id = handler.logger.entries[0].request_id
+    assert turn_request_id != "req-ws-1"
+    # Session lifecycle and PERF lines keep the session id so a session's log
+    # lines stay greppable together. The dashboard feed row retains its fresh
+    # per-turn id independently.
+    assert "[req-ws-1] WS /v1/responses accepted" in caplog.text
+    assert "[req-ws-1] WS /v1/responses completed" in caplog.text
+    assert "[req-ws-1] PERF" in caplog.text
+    assert f"[{turn_request_id}] PERF" not in caplog.text
+
+
 @pytest.mark.asyncio
 async def test_ws_opt_in_flattens_response_create_for_openai_compatible_upstream(monkeypatch):
     """Some OpenAI-compatible WS gateways expect top-level response.create payloads."""
@@ -1467,3 +1780,466 @@ async def test_ws_recognized_client_with_real_path_is_not_restamped():
     # the caller already self-identifies via its User-Agent.
     assert "x-client" not in {k.lower() for k in client_ws.headers}
     assert handler.ws_sessions.active_count() == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("store", [True, False])
+@pytest.mark.parametrize(
+    "include",
+    [
+        pytest.param(None, id="omitted"),
+        pytest.param(["response.output_text.done"], id="missing-marker"),
+        pytest.param(
+            ["response.output_text.done", "reasoning.encrypted_content"],
+            id="existing-marker",
+        ),
+        pytest.param("not-a-list", id="non-list"),
+    ],
+)
+async def test_ws_memory_continuation_replays_history_without_previous_response_id(include, store):
+    function_call = {
+        "type": "function_call",
+        "id": "fc-1",
+        "call_id": "call-1",
+        "name": "memory_search",
+        "arguments": "{}",
+    }
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.output_item.added", "item": function_call}),
+        json.dumps({"type": "response.output_item.done", "item": function_call}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(
+        frames=[
+            json.dumps(
+                {
+                    "type": "response.create",
+                    "response": {
+                        "model": "gpt-5.4",
+                        "input": "remember this",
+                        "store": store,
+                    },
+                }
+            )
+        ],
+        hold_after_initial=True,
+    )
+    if include is not None:
+        client_ws._frames[0] = json.dumps(
+            {
+                "type": "response.create",
+                "response": {
+                    "model": "gpt-5.4",
+                    "input": "remember this",
+                    "store": store,
+                    "include": include,
+                },
+            }
+        )
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert len(upstream.sent) >= 2
+    expected_include = (
+        ["reasoning.encrypted_content"]
+        if include is None
+        else (
+            include
+            if not isinstance(include, list)
+            else (
+                include
+                if "reasoning.encrypted_content" in include
+                else [*include, "reasoning.encrypted_content"]
+            )
+        )
+    )
+    assert json.loads(upstream.sent[0])["response"]["include"] == expected_include
+    continuation = json.loads(upstream.sent[1])
+    assert "previous_response_id" not in continuation["response"]
+    assert continuation["response"]["model"] == "gpt-5.4"
+    assert continuation["response"]["store"] is store
+    assert continuation["response"]["include"] == expected_include
+    assert continuation["response"]["tools"]
+    assert continuation["response"]["instructions"]
+    assert continuation["response"]["input"] == [
+        {"role": "user", "content": "remember this"},
+        function_call,
+        {
+            "type": "function_call_output",
+            "call_id": "call-1",
+            "output": '{"memories": []}',
+        },
+    ]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "initial_frame",
+    [
+        pytest.param("not-json", id="initial-non-json"),
+        pytest.param(
+            json.dumps({"type": "response.create", "response": []}),
+            id="initial-non-mapping-response",
+        ),
+    ],
+)
+async def test_ws_memory_frame_shape_guards_fail_open(initial_frame):
+    later_frames = [
+        json.dumps(
+            {
+                "type": "response.create",
+                "response": {"model": "gpt-5.4", "input": []},
+            }
+        ),
+        json.dumps({"type": "response.create", "response": "invalid"}),
+    ]
+    frames = [initial_frame, *later_frames]
+    upstream = _FakeUpstream([], hold_after_events=True)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(frames=frames, hold_after_initial=True)
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+
+    async def _trigger_disconnect() -> None:
+        await asyncio.sleep(0.05)
+        client_ws.trigger_disconnect()
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        trigger_task = asyncio.create_task(_trigger_disconnect())
+        try:
+            await asyncio.wait_for(handler.handle_openai_responses_ws(client_ws), timeout=2.0)
+        finally:
+            trigger_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await trigger_task
+
+    assert upstream.sent[0] == initial_frame
+    forwarded_valid = json.loads(upstream.sent[1])["response"]
+    assert forwarded_valid["model"] == "gpt-5.4"
+    assert forwarded_valid["input"] == []
+    assert forwarded_valid["tools"]
+    assert forwarded_valid["include"] == ["reasoning.encrypted_content"]
+    assert upstream.sent[2] == later_frames[1]
+
+
+@pytest.mark.asyncio
+async def test_ws_memory_enabled_non_memory_response_streams_completion():
+    message_item = {
+        "type": "message",
+        "id": "message-1",
+        "role": "assistant",
+        "content": [{"type": "output_text", "text": "hello"}],
+    }
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.output_item.added", "item": message_item}),
+        json.dumps({"type": "response.output_item.done", "item": message_item}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    forwarded_initial = json.loads(upstream.sent[0])["response"]
+    assert forwarded_initial["model"] == "gpt-5.4"
+    assert forwarded_initial["input"] == "hi"
+    assert forwarded_initial["tools"]
+    assert forwarded_initial["include"] == ["reasoning.encrypted_content"]
+    assert client_ws.sent_text == upstream_events
+    assert len(upstream.sent) == 1
+
+
+@pytest.mark.asyncio
+async def test_ws_late_memory_call_after_streamed_message_passes_through():
+    message_item = {
+        "type": "message",
+        "id": "message-1",
+        "role": "assistant",
+        "content": [{"type": "output_text", "text": "searching"}],
+    }
+    function_call = {
+        "type": "function_call",
+        "id": "fc-1",
+        "call_id": "call-1",
+        "name": "memory_search",
+        "arguments": "{}",
+    }
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.output_item.added", "item": message_item}),
+        json.dumps({"type": "response.output_item.done", "item": message_item}),
+        json.dumps({"type": "response.output_item.added", "item": function_call}),
+        json.dumps({"type": "response.output_item.done", "item": function_call}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+    executed: list[tuple[str, dict, str, str]] = []
+
+    async def _execute_memory_tool(name, args, user_id, provider):
+        executed.append((name, args, user_id, provider))
+        return '{"memories": []}'
+
+    handler.memory_handler._execute_memory_tool = _execute_memory_tool
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert client_ws.sent_text == upstream_events
+    assert len(upstream.sent) == 1
+    assert executed == []
+
+
+@pytest.mark.asyncio
+async def test_ws_memory_continuation_handles_invalid_item_arguments_and_unavailable_backend():
+    function_call = {
+        "type": "function_call",
+        "id": "fc-1",
+        "call_id": "call-1",
+        "name": "memory_search",
+        "arguments": "{malformed",
+    }
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.output_item.done", "item": "invalid"}),
+        json.dumps({"type": "response.output_item.added", "item": function_call}),
+        json.dumps({"type": "response.output_item.done", "item": function_call}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+
+    async def _leave_backend_unavailable():
+        return None
+
+    handler.memory_handler._ensure_initialized = _leave_backend_unavailable
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert len(upstream.sent) == 2
+    continuation = json.loads(upstream.sent[1])["response"]
+    assert continuation["input"] == [
+        {"role": "user", "content": "hi"},
+        function_call,
+        {
+            "type": "function_call_output",
+            "call_id": "call-1",
+            "output": '{"error": "backend not ready"}',
+        },
+    ]
+    assert continuation["input"][-1] == {
+        "type": "function_call_output",
+        "call_id": "call-1",
+        "output": '{"error": "backend not ready"}',
+    }
+
+
+@pytest.mark.asyncio
+async def test_ws_memory_continuation_normalizes_malformed_arguments():
+    function_call = {
+        "type": "function_call",
+        "id": "fc-1",
+        "call_id": "call-1",
+        "name": "memory_search",
+        "arguments": "{malformed",
+    }
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.output_item.done", "item": "invalid"}),
+        json.dumps({"type": "response.output_item.added", "item": function_call}),
+        json.dumps({"type": "response.output_item.done", "item": function_call}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(frames=[_first_frame()])
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+    executed: list[tuple[str, dict, str, str]] = []
+
+    async def _execute_memory_tool(name, args, user_id, provider):
+        executed.append((name, args, user_id, provider))
+        return '{"memories": []}'
+
+    handler.memory_handler._execute_memory_tool = _execute_memory_tool
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert executed == [("memory_search", {}, "user-1", "openai")]
+
+
+@pytest.mark.asyncio
+async def test_ws_memory_tools_preserve_explicit_store_false_while_injecting():
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(
+        frames=[
+            json.dumps(
+                {
+                    "type": "response.create",
+                    "response": {
+                        "model": "gpt-5.4",
+                        "input": "use stateless memory",
+                        "store": False,
+                    },
+                }
+            )
+        ],
+        hold_after_initial=True,
+    )
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert len(upstream.sent) == 1
+    initial = json.loads(upstream.sent[0])["response"]
+    assert initial["store"] is False
+    assert [tool["name"] for tool in initial["tools"]] == ["memory_search"]
+    assert initial["include"] == ["reasoning.encrypted_content"]
+
+
+@pytest.mark.asyncio
+async def test_ws_memory_continuation_continues_pre_stream_and_passes_late_call():
+    function_call_one = {
+        "type": "function_call",
+        "id": "fc-1",
+        "call_id": "call-1",
+        "name": "memory_search",
+        "arguments": "{}",
+    }
+    function_call_two = {
+        "type": "function_call",
+        "id": "fc-2",
+        "call_id": "call-2",
+        "name": "memory_search",
+        "arguments": "{}",
+    }
+    reasoning_without_encryption = {
+        "type": "reasoning",
+        "id": "reasoning-1",
+        "summary": [],
+    }
+    reasoning_with_encryption = {
+        "type": "reasoning",
+        "id": "reasoning-2",
+        "summary": [],
+        "encrypted_content": "encrypted-2",
+    }
+    message_item = {
+        "type": "message",
+        "id": "message-2",
+        "role": "assistant",
+        "content": [{"type": "output_text", "text": "searching"}],
+    }
+    upstream_events = [
+        json.dumps({"type": "response.created", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.output_item.added", "item": reasoning_without_encryption}),
+        json.dumps({"type": "response.output_item.done", "item": reasoning_without_encryption}),
+        json.dumps({"type": "response.output_item.added", "item": function_call_one}),
+        json.dumps({"type": "response.output_item.done", "item": function_call_one}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-1"}}),
+        json.dumps({"type": "response.created", "response": {"id": "r-2"}}),
+        json.dumps({"type": "response.output_item.added", "item": reasoning_with_encryption}),
+        json.dumps({"type": "response.output_item.done", "item": reasoning_with_encryption}),
+        json.dumps({"type": "response.output_item.added", "item": message_item}),
+        json.dumps({"type": "response.output_item.done", "item": message_item}),
+        json.dumps({"type": "response.output_item.added", "item": function_call_two}),
+        json.dumps({"type": "response.output_item.done", "item": function_call_two}),
+        json.dumps({"type": "response.completed", "response": {"id": "r-2"}}),
+    ]
+    upstream = _FakeUpstream(upstream_events)
+    fake_ws_mod = _make_fake_websockets_module(upstream)
+    client_ws = _FakeWebSocket(
+        frames=[
+            json.dumps(
+                {
+                    "type": "response.create",
+                    "response": {
+                        "model": "gpt-5.4",
+                        "input": "remember this",
+                        "client_metadata": {
+                            "ws_request_header_x_openai_internal_codex_responses_lite": "true",
+                            "keep": "yes",
+                        },
+                    },
+                }
+            )
+        ],
+        hold_after_initial=True,
+    )
+    client_ws.headers["x-headroom-user-id"] = "user-1"
+    handler = _DummyOpenAIHandler()
+    handler.memory_handler = _MemoryWsHandler()
+    executed: list[tuple[str, dict, str, str]] = []
+
+    async def _execute_memory_tool(name, args, user_id, provider):
+        executed.append((name, args, user_id, provider))
+        return '{"memories": []}'
+
+    handler.memory_handler._execute_memory_tool = _execute_memory_tool
+
+    with patch.dict(sys.modules, {"websockets": fake_ws_mod}):
+        await handler.handle_openai_responses_ws(client_ws)
+
+    assert len(upstream.sent) == 2
+    first_continuation = json.loads(upstream.sent[1])["response"]["input"]
+    assert reasoning_without_encryption not in first_continuation
+    assert function_call_one in first_continuation
+    assert {
+        "type": "function_call_output",
+        "call_id": "call-1",
+        "output": '{"memories": []}',
+    } in first_continuation
+    assert json.loads(upstream.sent[1])["response"]["client_metadata"] == {"keep": "yes"}
+
+    second_response = [json.loads(frame) for frame in client_ws.sent_text]
+    assert [event["type"] for event in second_response] == [
+        "response.created",
+        "response.output_item.added",
+        "response.output_item.done",
+        "response.output_item.added",
+        "response.output_item.done",
+        "response.output_item.added",
+        "response.output_item.done",
+        "response.completed",
+    ]
+    assert second_response[0]["response"]["id"] == "r-2"
+    assert second_response[2]["item"] == reasoning_with_encryption
+    assert second_response[3]["item"] == message_item
+    assert second_response[4]["item"] == message_item
+    assert second_response[5]["item"] == function_call_two
+    assert second_response[6]["item"] == function_call_two
+    assert second_response[7]["response"]["id"] == "r-2"
+    assert executed == [("memory_search", {}, "user-1", "openai")]
diff --git a/tests/test_openai_responses_context_compaction.py b/tests/test_openai_responses_context_compaction.py
index e29b81dac..74dc99cba 100644
--- a/tests/test_openai_responses_context_compaction.py
+++ b/tests/test_openai_responses_context_compaction.py
@@ -7,7 +7,6 @@ from headroom.proxy.handlers.openai import (
     OpenAIHandlerMixin,
     _compact_openai_responses_tools,
     _openai_responses_context_budget,
-    _responses_request_allows_memory_tool_continuation,
 )
 from headroom.transforms.content_router import (
     CompressionStrategy,
@@ -438,30 +437,6 @@ def test_content_router_retries_kompress_when_structured_strategy_noops(monkeypa
     assert strategy_chain == ["smart_crusher", "kompress"]
 
 
-def test_responses_memory_tools_skip_explicit_store_false() -> None:
-    """Regression: explicit store=false must block Responses memory-tool injection."""
-
-    payload = {"model": "gpt-5.5", "input": "remember this", "store": False}
-
-    assert _responses_request_allows_memory_tool_continuation(payload) is False
-    assert payload["store"] is False
-
-
-def test_responses_memory_tools_allow_default_and_stored_requests() -> None:
-    no_memory_payload = {"model": "gpt-5.5", "input": "plain", "store": False}
-    already_stored_payload = {"model": "gpt-5.5", "input": "plain", "store": True}
-    default_store_payload = {"model": "gpt-5.5", "input": "plain"}
-
-    assert _responses_request_allows_memory_tool_continuation(no_memory_payload) is False
-    assert no_memory_payload["store"] is False
-
-    assert _responses_request_allows_memory_tool_continuation(already_stored_payload) is True
-    assert already_stored_payload["store"] is True
-
-    assert _responses_request_allows_memory_tool_continuation(default_store_payload) is True
-    assert "store" not in default_store_payload
-
-
 def test_responses_turn_hook_message_fold_is_applied_and_counted() -> None:
     """On the Responses path a turn hook may fold the `input` items (in place),
     not just tools. The fold must be written back to the outbound payload AND its
diff --git a/tests/test_openai_responses_null_arguments.py b/tests/test_openai_responses_null_arguments.py
new file mode 100644
index 000000000..bd50487c9
--- /dev/null
+++ b/tests/test_openai_responses_null_arguments.py
@@ -0,0 +1,28 @@
+"""The OpenAI Responses memory tool-call loops must not crash on a null
+``arguments``.
+
+A ``function_call`` item with ``"arguments": null`` makes ``fc.get("arguments",
+"{}")`` return ``None``, and ``json.loads(None)`` raises ``TypeError`` — which the
+``except json.JSONDecodeError`` around it does not catch. The two memory
+tool-execution loops in ``handlers/openai.py`` are deep inside streaming request
+handlers, so this guards the fix at the source level (reading the file, not
+importing the ML stack) plus a behavioural proof in the standalone script.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_OPENAI = Path(__file__).resolve().parents[1] / "headroom" / "proxy" / "handlers" / "openai.py"
+
+
+def test_memory_tool_argument_parsing_is_null_safe():
+    src = _OPENAI.read_text(encoding="utf-8")
+
+    # The vulnerable form (bare default + json.loads that can receive None) is gone.
+    assert 'fc.get("arguments", "{}")' not in src
+
+    # Both memory tool-call loops now coalesce the arguments string and catch
+    # TypeError alongside JSONDecodeError.
+    assert src.count('fc.get("arguments") or "{}"') >= 2
+    assert src.count("except (json.JSONDecodeError, TypeError):") >= 2
diff --git a/tests/test_openai_responses_output_shaper.py b/tests/test_openai_responses_output_shaper.py
index 31104ecca..b28db9373 100644
--- a/tests/test_openai_responses_output_shaper.py
+++ b/tests/test_openai_responses_output_shaper.py
@@ -10,10 +10,19 @@ pytest.importorskip("fastapi")
 
 from fastapi.testclient import TestClient  # noqa: E402
 
+from headroom.proxy import runtime_env  # noqa: E402
 from headroom.proxy.loopback_guard import require_loopback  # noqa: E402
 from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
 
 
+@pytest.fixture(autouse=True)
+def _isolate_runtime_env_overrides():
+    """Keep loopback hot-reload state from leaking into later test modules."""
+    runtime_env.clear_overrides()
+    yield
+    runtime_env.clear_overrides()
+
+
 def _make_client() -> TestClient:
     app = create_app(
         ProxyConfig(
@@ -49,6 +58,7 @@ async def _ok_response(
 
 def test_http_responses_output_shaper_rewrites_and_labels(monkeypatch):
     monkeypatch.setenv("HEADROOM_OUTPUT_SHAPER", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "beta")
     monkeypatch.setenv("HEADROOM_VERBOSITY_LEVEL", "2")
     monkeypatch.delenv("HEADROOM_OUTPUT_HOLDOUT", raising=False)
     captured: dict[str, Any] = {}
@@ -104,6 +114,7 @@ def test_http_responses_output_shaper_rewrites_and_labels(monkeypatch):
 
 def test_http_responses_output_shaper_respects_bypass(monkeypatch):
     monkeypatch.setenv("HEADROOM_OUTPUT_SHAPER", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "beta")
     captured: dict[str, Any] = {}
     payload = {"model": "gpt-5", "input": "hi"}
 
@@ -131,6 +142,7 @@ def test_http_responses_output_shaper_respects_bypass(monkeypatch):
 
 def test_http_responses_output_shaper_holdout_labels_without_rewrite(monkeypatch):
     monkeypatch.setenv("HEADROOM_OUTPUT_SHAPER", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "beta")
     monkeypatch.setenv("HEADROOM_OUTPUT_HOLDOUT", "1")
     captured: dict[str, Any] = {}
     outcomes: list[Any] = []
@@ -160,3 +172,43 @@ def test_http_responses_output_shaper_holdout_labels_without_rewrite(monkeypatch
     transforms = outcomes[-1].transforms_applied
     assert any(t.startswith("output_shaper:control:") for t in transforms)
     assert "output_shaper:verbosity:L2" not in transforms
+
+
+def test_http_output_shaper_hot_reload_changes_the_running_request_path(monkeypatch):
+    """The admin endpoint must not report success while traffic stays unchanged."""
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "beta")
+    monkeypatch.delenv("HEADROOM_OUTPUT_SHAPER", raising=False)
+    payload = {
+        "model": "gpt-5",
+        "input": [{"type": "function_call_output", "call_id": "call_1", "output": "ok"}],
+        "reasoning": {"effort": "high"},
+        "text": {"verbosity": "medium"},
+    }
+    sent: list[dict[str, Any]] = []
+
+    with _make_client() as client:
+        proxy = client.app.state.proxy
+
+        async def _fake_retry(*args: Any, **kwargs: Any) -> httpx.Response:
+            sent.append(copy.deepcopy(args[3]))
+            return await _ok_response(*args, **kwargs)
+
+        proxy._retry_request = _fake_retry
+        first = client.post(
+            "/v1/responses", headers={"authorization": "Bearer test-key"}, json=payload
+        )
+        update = client.post("/admin/runtime-env", json={"HEADROOM_OUTPUT_SHAPER": "1"})
+        second = client.post(
+            "/v1/responses", headers={"authorization": "Bearer test-key"}, json=payload
+        )
+
+    assert first.status_code == second.status_code == update.status_code == 200
+    assert sent[0] == payload
+    assert "<headroom_output_shaping>" in sent[1]["instructions"]
+    decision = next(
+        item
+        for item in update.json()["rollout"]["features"]
+        if item["name"] == "proxy_output_shaper"
+    )
+    assert decision["enabled"] is True
+    assert decision["decision"] == "legacy_alias"
diff --git a/tests/test_openai_responses_traffic_learner.py b/tests/test_openai_responses_traffic_learner.py
index 91e710390..9f1f7397c 100644
--- a/tests/test_openai_responses_traffic_learner.py
+++ b/tests/test_openai_responses_traffic_learner.py
@@ -1,12 +1,16 @@
 from __future__ import annotations
 
+import asyncio
 from typing import Any
 
 import httpx
 from fastapi.testclient import TestClient
 
 from headroom.memory.traffic_learner import TrafficLearner
-from headroom.proxy.handlers.openai import _responses_input_to_learner_messages
+from headroom.proxy.handlers.openai import (
+    OpenAIHandlerMixin,
+    _responses_input_to_learner_messages,
+)
 from headroom.proxy.server import ProxyConfig, create_app
 
 
@@ -80,6 +84,7 @@ def test_responses_input_normalizes_messages_and_tool_results() -> None:
             "input": {"cmd": "missing-command"},
             "output": "command not found",
             "is_error": True,
+            "call_id": "call_1",
         }
     ]
 
@@ -141,3 +146,76 @@ def test_responses_http_request_reaches_traffic_learner() -> None:
             "is_error": True,
         }
     ]
+
+
+def _ws_frame(call_ids: list[str]) -> dict[str, Any]:
+    """A response.create inner payload whose input carries one shell tool
+    round-trip per call id."""
+    input_items: list[dict[str, Any]] = []
+    for cid in call_ids:
+        input_items.append(
+            {"type": "function_call", "call_id": cid, "name": "shell", "arguments": "{}"}
+        )
+        input_items.append(
+            {
+                "type": "function_call_output",
+                "call_id": cid,
+                "output": "ok",
+                "status": "completed",
+            }
+        )
+    return {"input": input_items}
+
+
+def test_ws_response_create_baselines_and_dedups_replayed_transcript() -> None:
+    handler = OpenAIHandlerMixin()
+    learner = _RecordingLearner()
+    handler.traffic_learner = learner
+    seen: set[str] = set()
+
+    # First frame is the baseline: A and B are recorded as seen but NOT learned,
+    # and preference extraction is skipped.
+    asyncio.run(
+        handler._observe_openai_ws_response_create(
+            _ws_frame(["A", "B"]), seen_call_ids=seen, baseline=True, request_id="r"
+        )
+    )
+    assert learner.tool_results == []
+    assert learner.message_batches == []
+    assert seen == {"A", "B"}
+
+    # Second frame replays A, B and appends C -> only C is learned.
+    asyncio.run(
+        handler._observe_openai_ws_response_create(
+            _ws_frame(["A", "B", "C"]), seen_call_ids=seen, baseline=False, request_id="r"
+        )
+    )
+    assert len(learner.tool_results) == 1
+    assert seen == {"A", "B", "C"}
+    assert len(learner.message_batches) == 1
+
+    # Third frame replays A, B, C and appends D -> only D is learned.
+    asyncio.run(
+        handler._observe_openai_ws_response_create(
+            _ws_frame(["A", "B", "C", "D"]), seen_call_ids=seen, baseline=False, request_id="r"
+        )
+    )
+    assert len(learner.tool_results) == 2  # C then D, never A/B again
+    assert seen == {"A", "B", "C", "D"}
+
+
+def test_ws_reconnect_replay_adds_no_evidence() -> None:
+    # A reconnect is a fresh connection: its first frame replays the whole
+    # transcript, which is baselined, so nothing is re-learned.
+    handler = OpenAIHandlerMixin()
+    learner = _RecordingLearner()
+    handler.traffic_learner = learner
+    seen: set[str] = set()
+
+    asyncio.run(
+        handler._observe_openai_ws_response_create(
+            _ws_frame(["A", "B", "C", "D"]), seen_call_ids=seen, baseline=True, request_id="r"
+        )
+    )
+    assert learner.tool_results == []
+    assert seen == {"A", "B", "C", "D"}
diff --git a/tests/test_openai_tool_search_deferral.py b/tests/test_openai_tool_search_deferral.py
index da149f846..32486d06c 100644
--- a/tests/test_openai_tool_search_deferral.py
+++ b/tests/test_openai_tool_search_deferral.py
@@ -60,7 +60,7 @@ def test_env_override_wins_then_falls_back(monkeypatch):
 
 @pytest.mark.parametrize(
     ("client", "supported"),
-    [(None, True), ("codex", False), (" CODEX ", False), ("opencode", True), ("claude", True)],
+    [(None, True), ("codex", False), (" CODEX ", False), ("opencode", False), ("claude", True)],
 )
 def test_client_supported(client, supported):
     assert openai_tool_search_client_supported(client) is supported
@@ -76,7 +76,7 @@ def test_codex_client_does_not_inject():
     assert all("defer_loading" not in tool for tool in out)
 
 
-@pytest.mark.parametrize("client", [None, "opencode"])
+@pytest.mark.parametrize("client", [None, "claude-code"])
 def test_supported_clients_still_inject(client):
     tools = _tools()
 
@@ -187,3 +187,34 @@ def test_resident_names_match_case_insensitively():
     for name in ("Bash", "Read", "Edit", "Terminal", "ToolSearch"):
         assert by_name[name].get("defer_loading") is None, name
     assert by_name["slack_0"].get("defer_loading") is True
+
+
+# --- client-harness exclusion (GH #2660) -------------------------------------
+
+
+def test_noop_for_a_client_that_cannot_execute_the_search_tool():
+    # GH #2660 reports opencode resolving tool calls against its own registry
+    # and rejecting the injected tool as unavailable, so its tools stay resident
+    # and untouched.
+    tools = _tools()
+    snapshot = copy.deepcopy(tools)
+
+    out = inject_tool_search_deferral_openai(tools, "gpt-5.5", client="opencode")
+
+    assert out is tools
+    assert tools == snapshot
+    assert not any(t.get("type") == "tool_search" for t in out)
+    assert not any(t.get("defer_loading") for t in out)
+
+
+def test_supported_clients_keep_the_existing_deferral():
+    # The exclusion is per-client, not a global default flip: anything that can
+    # search still gets the same payload it got before.
+    tools = _tools()
+
+    explicit = inject_tool_search_deferral_openai(tools, "gpt-5.5", client="claude-code")
+    implicit = inject_tool_search_deferral_openai(tools, "gpt-5.5")
+
+    assert explicit == implicit
+    assert implicit[0] == {"type": "tool_search"}
+    assert any(t.get("defer_loading") for t in implicit)
diff --git a/tests/test_platform_stabilization_functional.py b/tests/test_platform_stabilization_functional.py
index 92ab78d7c..946367d05 100644
--- a/tests/test_platform_stabilization_functional.py
+++ b/tests/test_platform_stabilization_functional.py
@@ -56,6 +56,7 @@ def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None:
     proxy = app.state.proxy
     request_messages = [{"role": "user", "content": "summarize this repeated payload"}]
     compressed_messages = [{"role": "user", "content": "summary payload"}]
+    ccr_hash = "abc123def4567890abc123de"
 
     def fake_apply(**kwargs):
         assert kwargs["messages"] == request_messages
@@ -65,7 +66,7 @@ def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None:
             tokens_before=100,
             tokens_after=40,
             transforms_applied=["test:compress"],
-            markers_inserted=["marker-1"],
+            markers_inserted=[ccr_hash],
         )
 
     # The default /v1/compress mode runs a marker-free pipeline derived from
@@ -88,7 +89,7 @@ def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None:
     assert body["compression_ratio"] == 0.4
     assert body["transforms_applied"] == ["test:compress"]
     assert body["transforms_summary"] == {"test:compress": 1}
-    assert body["ccr_hashes"] == ["marker-1"]
+    assert body["ccr_hashes"] == [ccr_hash]
 
 
 def test_v1_compress_timeout_fails_open_quickly(monkeypatch) -> None:
@@ -167,3 +168,35 @@ def test_v1_compress_real_json_tool_payload_reduces_tokens(monkeypatch) -> None:
     assert body["tokens_saved"] > 0
     assert body["compression_ratio"] < 1.0
     assert body["transforms_applied"], body
+
+
+def test_compression_quarantine_releases_after_time_cap(monkeypatch) -> None:
+    """A leaked/hung timed-out worker must not pin the quarantine open forever:
+    once the time cap lapses, compression resumes and the release is counted
+    once (#2360)."""
+    import asyncio
+
+    from headroom.proxy.server import CompressionQuarantinedError
+
+    monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")
+    app = create_app(_proxy_config())
+    proxy = app.state.proxy
+
+    # Simulate a timed-out worker that is still running (debt standing).
+    proxy._compression_timed_out_in_flight = 1
+
+    # Within the cap: new compression is quarantined.
+    proxy._compression_quarantine_deadline = time.monotonic() + 1000.0
+    with pytest.raises(CompressionQuarantinedError):
+        asyncio.run(proxy._run_compression_in_executor(lambda: "unused", timeout=5.0))
+    assert proxy._compression_quarantine_releases == 0
+
+    # Past the cap: the worker is presumed leaked and compression runs again;
+    # the release is recorded once.
+    proxy._compression_quarantine_deadline = time.monotonic() - 1.0
+    assert asyncio.run(proxy._run_compression_in_executor(lambda: "ran", timeout=5.0)) == "ran"
+    assert proxy._compression_quarantine_releases == 1
+
+    # A subsequent request is not re-counted and still runs.
+    assert asyncio.run(proxy._run_compression_in_executor(lambda: "ok", timeout=5.0)) == "ok"
+    assert proxy._compression_quarantine_releases == 1
diff --git a/tests/test_pricing_litellm_model_resolution.py b/tests/test_pricing_litellm_model_resolution.py
index c2098a89b..dcfb21485 100644
--- a/tests/test_pricing_litellm_model_resolution.py
+++ b/tests/test_pricing_litellm_model_resolution.py
@@ -3,6 +3,7 @@ from __future__ import annotations
 from headroom.pricing.litellm_model_resolution import (
     MODEL_ALIASES,
     LiteLLMModelPrefixRule,
+    _strip_vertex_version_suffix,
     pricing_lookup_candidates,
     resolution_candidates,
     resolve_litellm_model_name,
@@ -21,11 +22,11 @@ def test_resolution_candidates_try_bare_then_matching_prefix_then_alias() -> Non
     assert resolution_candidates("MiniMax-M3") == ("MiniMax-M3", "minimax/MiniMax-M3")
 
     retired = "claude-3-5-sonnet-20241022"
-    assert resolution_candidates(retired) == (
-        retired,
-        f"anthropic/{retired}",
-        MODEL_ALIASES[retired],
-    )
+    candidates = resolution_candidates(retired)
+    assert candidates[0] == retired
+    assert f"anthropic/{retired}" in candidates
+    assert f"vertex_ai/{retired}" not in candidates  # no @YYYYMMDD suffix = not Vertex
+    assert MODEL_ALIASES[retired] in candidates
 
 
 def test_pricing_lookup_candidates_include_provider_prefixes_and_aliases() -> None:
@@ -59,3 +60,64 @@ def test_resolve_litellm_model_name_returns_first_known_candidate() -> None:
 
 def test_resolve_litellm_model_name_returns_original_when_unknown() -> None:
     assert resolve_litellm_model_name("mystery-model", lambda _: False) == "mystery-model"
+
+
+def test_strip_vertex_version_suffix() -> None:
+    assert _strip_vertex_version_suffix("claude-haiku-4-5@20251001") == "claude-haiku-4-5"
+    assert _strip_vertex_version_suffix("claude-opus-4@20250514") == "claude-opus-4"
+    assert _strip_vertex_version_suffix("claude-sonnet-4-6") == "claude-sonnet-4-6"
+    assert _strip_vertex_version_suffix("claude-sonnet-4-20250514") == "claude-sonnet-4-20250514"
+
+
+def test_resolution_candidates_vertex_versioned_models() -> None:
+    # Vertex appends @YYYYMMDD — bare name and vertex_ai/ must be candidates
+    candidates = resolution_candidates("claude-haiku-4-5@20251001")
+    assert "claude-haiku-4-5" in candidates
+    assert "anthropic/claude-haiku-4-5" in candidates
+    assert "vertex_ai/claude-haiku-4-5" in candidates  # vertex_ai/ only for versioned
+
+    candidates = resolution_candidates("claude-opus-4@20250514")
+    assert "claude-opus-4" in candidates
+    assert "anthropic/claude-opus-4" in candidates
+    assert "vertex_ai/claude-opus-4" in candidates
+
+    # Non-versioned names should NOT get vertex_ai/ candidates
+    candidates = resolution_candidates("claude-sonnet-4-6")
+    assert candidates[0] == "claude-sonnet-4-6"
+    assert "vertex_ai/claude-sonnet-4-6" not in candidates
+    assert "anthropic/claude-sonnet-4-6" in candidates
+
+
+def test_pricing_lookup_candidates_vertex_versioned_models() -> None:
+    candidates = pricing_lookup_candidates("claude-haiku-4-5@20251001")
+    # Bare name and vertex_ai/ prefix must both be candidates
+    assert "claude-haiku-4-5" in candidates
+    assert "vertex_ai/claude-haiku-4-5" in candidates
+    assert "anthropic/claude-haiku-4-5" in candidates
+
+    candidates = pricing_lookup_candidates("claude-opus-4@20250514")
+    assert "claude-opus-4" in candidates
+    assert "vertex_ai/claude-opus-4" in candidates
+
+    # Non-versioned names should NOT get vertex_ai/ pricing candidates
+    candidates = pricing_lookup_candidates("claude-sonnet-4-6")
+    assert "vertex_ai/claude-sonnet-4-6" not in candidates
+    assert "anthropic/claude-sonnet-4-6" in candidates
+
+
+def test_vertex_versioned_model_resolves_to_known_key() -> None:
+    # Simulate LiteLLM knowing the bare model name (not the versioned one)
+    known = {"claude-haiku-4-5", "anthropic/claude-sonnet-4-6"}
+    assert (
+        resolve_litellm_model_name("claude-haiku-4-5@20251001", known.__contains__)
+        == "claude-haiku-4-5"
+    )
+    assert (
+        resolve_litellm_model_name("claude-sonnet-4-6", known.__contains__)
+        == "anthropic/claude-sonnet-4-6"
+    )
+    # Unknown versioned model falls back to original
+    assert (
+        resolve_litellm_model_name("claude-unknown@20251001", lambda _: False)
+        == "claude-unknown@20251001"
+    )
diff --git a/tests/test_prometheus_label_escaping.py b/tests/test_prometheus_label_escaping.py
new file mode 100644
index 000000000..80dca7a9d
--- /dev/null
+++ b/tests/test_prometheus_label_escaping.py
@@ -0,0 +1,273 @@
+"""Label-value escaping in the Prometheus text exposition output.
+
+``PrometheusMetrics.export()`` builds the exposition text by hand, so every label
+value has to pass through ``_escape_label_value`` before it is interpolated. The
+format reserves ``"``, ``\\`` and the line feed, and a standard scraper does not
+degrade gracefully on a malformed line — it aborts the parse, losing every
+family emitted at or after the bad sample.
+
+``model`` reaches ``requests_by_model`` straight from the parsed client request
+body (``handlers/openai.py`` reads ``body.get("model", "unknown")`` with no
+sanitisation, and the Anthropic path's ``sanitize_anthropic_model_id`` only
+strips ANSI sequences and whitespace), so an unescaped value is remotely
+reachable.
+
+Imports only the metrics module so the test stays free of heavy ML deps.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from headroom.proxy.prometheus_metrics import PrometheusMetrics
+
+# A label whose value contains only unreserved characters or well-formed escape
+# pairs. An unescaped quote inside a value stops this matching, which is exactly
+# the failure a scraper hits.
+_LABEL_RE = re.compile(r'([a-zA-Z_][a-zA-Z0-9_]*)="((?:[^"\\]|\\.)*)"')
+_SAMPLE_RE = re.compile(r"^(?P<name>[a-zA-Z_:][a-zA-Z0-9_:]*)\{(?P<labels>.*)\} \S+$")
+_ESCAPE_RE = re.compile(r"\\(.)")
+_UNESCAPE = {"n": "\n", '"': '"', "\\": "\\"}
+
+
+def _unescape(value: str) -> str:
+    def replace(match: re.Match[str]) -> str:
+        char = match.group(1)
+        if char not in _UNESCAPE:
+            raise ValueError(f"undefined escape sequence '\\{char}' in {value!r}")
+        return _UNESCAPE[char]
+
+    return _ESCAPE_RE.sub(replace, value)
+
+
+def _parse_label_block(block: str) -> dict[str, str]:
+    """Parse ``key="value",key="value"`` the way a scraper would.
+
+    Raises ``ValueError`` on anything the exposition grammar rejects, so a line
+    carrying an unescaped quote fails loudly instead of yielding a
+    plausible-looking dict.
+    """
+    labels: dict[str, str] = {}
+    pos = 0
+    while pos < len(block):
+        match = _LABEL_RE.match(block, pos)
+        if match is None:
+            raise ValueError(f"malformed label block at offset {pos}: {block!r}")
+        labels[match.group(1)] = _unescape(match.group(2))
+        pos = match.end()
+        if pos < len(block):
+            if block[pos] != ",":
+                raise ValueError(f"expected ',' at offset {pos}: {block!r}")
+            pos += 1
+    return labels
+
+
+def _labelled_samples(text: str) -> list[tuple[str, dict[str, str]]]:
+    """Every labelled sample in a scrape, as (metric name, decoded labels).
+
+    Raises on any line a scraper would reject — including the fragments an
+    unescaped line feed splits a sample into.
+    """
+    samples: list[tuple[str, dict[str, str]]] = []
+    for line in text.splitlines():
+        if not line or line.startswith("#") or "{" not in line:
+            continue
+        match = _SAMPLE_RE.match(line)
+        if match is None:
+            raise ValueError(f"malformed sample line: {line!r}")
+        samples.append((match.group("name"), _parse_label_block(match.group("labels"))))
+    return samples
+
+
+async def _record(metrics: PrometheusMetrics, **overrides: object) -> None:
+    kwargs: dict[str, object] = {
+        "provider": "anthropic",
+        "model": "claude-sonnet-4-5",
+        "input_tokens": 100,
+        "output_tokens": 20,
+        # tokens_saved=0 keeps the durable savings-ledger write out of the test.
+        "tokens_saved": 0,
+        "latency_ms": 10.0,
+    }
+    kwargs.update(overrides)
+    await metrics.record_request(**kwargs)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_quote_in_model_is_escaped() -> None:
+    metrics = PrometheusMetrics()
+
+    await _record(metrics, model='claude-sonnet-4-5"evil')
+
+    text = await metrics.export()
+
+    assert 'headroom_requests_by_model{model="claude-sonnet-4-5\\"evil"} 1' in text
+    assert 'headroom_requests_by_model{model="claude-sonnet-4-5"evil"}' not in text
+
+
+@pytest.mark.asyncio
+async def test_quote_in_provider_is_escaped() -> None:
+    metrics = PrometheusMetrics()
+
+    await _record(metrics, provider='anth"ropic')
+
+    text = await metrics.export()
+
+    assert 'headroom_requests_by_provider{provider="anth\\"ropic"} 1' in text
+    assert 'headroom_requests_by_provider{provider="anth"ropic"}' not in text
+
+
+@pytest.mark.asyncio
+async def test_backslash_and_newline_in_model_are_escaped() -> None:
+    metrics = PrometheusMetrics()
+
+    await _record(metrics, model="back\\slash")
+    await _record(metrics, model="line\nfeed")
+
+    text = await metrics.export()
+
+    # Backslash first, so the escapes this inserts are not re-escaped.
+    assert 'headroom_requests_by_model{model="back\\\\slash"} 1' in text
+    assert 'headroom_requests_by_model{model="line\\nfeed"} 1' in text
+    # The line feed must not survive as a real newline splitting the sample.
+    assert "line\nfeed" not in text
+
+
+@pytest.mark.asyncio
+async def test_provider_cache_families_escape_provider() -> None:
+    # The families PR #2450 added inherit `provider` from the same parameter,
+    # so they need naming explicitly rather than assuming coverage.
+    metrics = PrometheusMetrics()
+
+    await _record(
+        metrics,
+        provider='anth"ropic',
+        cache_read_tokens=40,
+        cache_write_tokens=60,
+        cache_write_5m_tokens=10,
+        cache_write_1h_tokens=50,
+        uncached_input_tokens=20,
+    )
+
+    text = await metrics.export()
+
+    families = [
+        "headroom_cache_read_tokens_total",
+        "headroom_cache_write_tokens_total",
+        "headroom_cache_write_ttl_tokens_total",
+        "headroom_cache_write_ttl_requests_total",
+        "headroom_uncached_input_tokens_total",
+        "headroom_provider_cache_requests_total",
+        "headroom_provider_cache_hit_requests_total",
+        "headroom_provider_cache_bust_total",
+        "headroom_provider_cache_bust_write_tokens_total",
+    ]
+    for family in families:
+        assert f'{family}{{provider="anth\\"ropic"' in text, f"{family} left provider raw"
+
+
+@pytest.mark.asyncio
+async def test_cache_miss_attribution_escapes_both_labels() -> None:
+    metrics = PrometheusMetrics()
+
+    await metrics.record_cache_miss_attribution('anth"ropic', 'ttl"expiry')
+
+    text = await metrics.export()
+
+    assert (
+        'headroom_cache_miss_attribution_total{provider="anth\\"ropic",reason="ttl\\"expiry"} 1'
+        in text
+    )
+
+
+@pytest.mark.asyncio
+async def test_no_emitted_label_value_is_malformed() -> None:
+    # The regression guard: poison every reachable label input, then read the
+    # whole scrape the way a scraper does. A future emission that forgets to
+    # escape fails here even when no assertion above names it.
+    metrics = PrometheusMetrics()
+
+    # The model poison carries a comma and an inner quote. The parse alone
+    # can't catch comma-injection (this value raises on the quote first), so the
+    # round-trip assertion below is the real guard: after escaping, the value
+    # must decode back to the exact raw string, comma and all, rather than
+    # splitting into extra labels.
+    await _record(
+        metrics,
+        provider='pro"vider\\one',
+        model='mo"del,evil="1',
+        cache_read_tokens=40,
+        cache_write_tokens=60,
+        cache_write_5m_tokens=10,
+        cache_write_1h_tokens=50,
+        uncached_input_tokens=20,
+    )
+    await metrics.record_cache_miss_attribution('pro"vider\\one', 'rea"son')
+
+    samples = _labelled_samples(await metrics.export())
+
+    values = {value for _, labels in samples for value in labels.values()}
+    assert 'pro"vider\\one' in values, "provider did not round-trip through the escape"
+    assert 'mo"del,evil="1' in values, "model did not round-trip through the escape"
+
+
+@pytest.mark.asyncio
+async def test_non_string_label_values_are_coerced() -> None:
+    # A JSON body can carry `"model": 123`, and the handlers pass the decoded
+    # value through untouched (handlers/openai.py reads body.get("model")). The
+    # hand-rolled f-strings used to call str() implicitly, so escaping has to
+    # keep tolerating a non-str. /metrics has no error handling around export(),
+    # and the key survives in the dict, so a raise here would take out every
+    # later scrape too.
+    metrics = PrometheusMetrics()
+
+    await _record(metrics, provider=456, model=123, cache_read_tokens=5, cache_write_tokens=5)
+    await metrics.record_cache_miss_attribution(456, 789)
+
+    text = await metrics.export()
+
+    assert 'headroom_requests_by_model{model="123"} 1' in text
+    assert 'headroom_requests_by_provider{provider="456"} 1' in text
+    assert 'headroom_cache_read_tokens_total{provider="456"}' in text
+    assert 'headroom_cache_miss_attribution_total{provider="456",reason="789"} 1' in text
+
+
+@pytest.mark.asyncio
+async def test_well_formed_values_are_emitted_unchanged() -> None:
+    metrics = PrometheusMetrics()
+
+    await _record(metrics)
+
+    text = await metrics.export()
+
+    assert 'headroom_requests_by_provider{provider="anthropic"} 1' in text
+    assert 'headroom_requests_by_model{model="claude-sonnet-4-5"} 1' in text
+
+
+@pytest.mark.asyncio
+async def test_export_is_utf8_encodable_with_surrogate_model() -> None:
+    # `/metrics` renders the whole body with `.encode("utf-8")` (server.py). A
+    # client can decode a lone surrogate from JSON (`{"model": "x-\ud83d-y"}`) —
+    # a valid str that is NOT UTF-8-encodable and passes escaping untouched. It
+    # would raise in the response encoder and, because the poisoned key persists
+    # in requests_by_model, 500 every later scrape until restart. Escaping must
+    # leave the whole export encodable.
+    metrics = PrometheusMetrics()
+
+    await _record(metrics, model="x-\ud83d-y")
+    await _record(metrics, model="clean-model")  # a healthy series alongside
+
+    text = await metrics.export()
+
+    # The load-bearing assertion: the body a scraper receives must encode.
+    text.encode("utf-8")
+    # And the healthy series is still readable, i.e. the poison did not corrupt
+    # the surrounding output.
+    assert 'headroom_requests_by_model{model="clean-model"} 1' in text
+    # Legitimate astral characters (a real emoji is one code point, encodable)
+    # are preserved, not scrubbed — only un-encodable lone surrogates change.
+    metrics2 = PrometheusMetrics()
+    await _record(metrics2, model="gpt-\U0001f600")
+    assert 'headroom_requests_by_model{model="gpt-\U0001f600"} 1' in await metrics2.export()
diff --git a/tests/test_provider_claude_vscode_config.py b/tests/test_provider_claude_vscode_config.py
index 61f9e73de..1e470a3f9 100644
--- a/tests/test_provider_claude_vscode_config.py
+++ b/tests/test_provider_claude_vscode_config.py
@@ -55,7 +55,7 @@ def test_configure_and_remove_preserve_unrelated_and_previous_values(tmp_path: P
     assert configured["env"] == {
         "KEEP": "yes",
         "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787/p/demo",
-        "ENABLE_TOOL_SEARCH": "true",
+        "ENABLE_TOOL_SEARCH": "false",
     }
     assert configured["permissions"] == {"allow": ["Read"]}
 
@@ -162,7 +162,7 @@ def test_reconfigure_refuses_incomplete_or_conflicting_state(tmp_path: Path) ->
     state_path.unlink()
     configure_vscode_claude_settings(path, proxy_url)
     payload = json.loads(path.read_text(encoding="utf-8"))
-    payload["env"]["ENABLE_TOOL_SEARCH"] = "false"
+    payload["env"]["ENABLE_TOOL_SEARCH"] = "true"
     path.write_text(json.dumps(payload), encoding="utf-8")
     with pytest.raises(click.ClickException, match="managed values"):
         configure_vscode_claude_settings(path, proxy_url)
diff --git a/tests/test_provider_copilot_vscode_config.py b/tests/test_provider_copilot_vscode_config.py
index c3075bb83..992888e22 100644
--- a/tests/test_provider_copilot_vscode_config.py
+++ b/tests/test_provider_copilot_vscode_config.py
@@ -50,6 +50,7 @@ def test_configure_update_and_remove_preserve_jsonc_verbatim(tmp_path: Path) ->
     assert "editor.fontSize" in configured
     assert "user comment" in configured
     assert '"github.copilot.advanced.debug.overrideProxyUrl"' in configured
+    assert '"github.copilot.advanced.debug.overrideCapiUrl"' in configured
     assert '"github.copilot.advanced.debug.overrideAuthType": "token"' in configured
 
     assert configure_vscode_proxy_settings(path, "http://127.0.0.1:9999") == "updated"
@@ -66,6 +67,7 @@ def test_configure_refuses_malformed_and_unmanaged_override(tmp_path: Path) -> N
     for original in (
         "{broken",
         '{"github.copilot.advanced.debug.overrideProxyUrl":"http://other"}',
+        '{"github.copilot.advanced.debug.overrideCapiUrl":"http://other"}',
     ):
         path.write_text(original, encoding="utf-8")
         with pytest.raises(click.ClickException, match="did not overwrite|refusing"):
diff --git a/tests/test_provider_copilot_wrap.py b/tests/test_provider_copilot_wrap.py
index 849da6b98..45beceb12 100644
--- a/tests/test_provider_copilot_wrap.py
+++ b/tests/test_provider_copilot_wrap.py
@@ -93,6 +93,7 @@ def test_validate_configuration_rejects_invalid_combinations() -> None:
     [
         ("gpt-5.5", True),
         ("gpt-5-codex", True),
+        ("gpt-5.4", True),
         ("openai/gpt-5.4", True),
         ("o1", True),
         ("o3-mini", True),
diff --git a/tests/test_provider_openai_responses.py b/tests/test_provider_openai_responses.py
index 439166ae9..45a88a0fa 100644
--- a/tests/test_provider_openai_responses.py
+++ b/tests/test_provider_openai_responses.py
@@ -23,8 +23,15 @@ def test_openai_responses_route_aliases_are_explicit() -> None:
         "/v1/codex/responses",
         "/backend-api/responses",
         "/backend-api/codex/responses",
+        "/responses",
     )
-    assert OPENAI_RESPONSES_WEBSOCKET_PATHS == OPENAI_RESPONSES_ROOT_PATHS
+    assert OPENAI_RESPONSES_WEBSOCKET_PATHS == (
+        "/v1/responses",
+        "/v1/codex/responses",
+        "/backend-api/responses",
+        "/backend-api/codex/responses",
+    )
+    assert "/responses" not in OPENAI_RESPONSES_WEBSOCKET_PATHS
     assert OPENAI_RESPONSES_SUBPATH_ROUTES == (
         OpenAIResponsesSubpathRoute("/v1/responses/{sub_path:path}", ("GET", "POST", "DELETE")),
         OpenAIResponsesSubpathRoute(
diff --git a/tests/test_provider_proxy_routes.py b/tests/test_provider_proxy_routes.py
index fe7f9ddd0..22698365d 100644
--- a/tests/test_provider_proxy_routes.py
+++ b/tests/test_provider_proxy_routes.py
@@ -274,6 +274,133 @@ def test_provider_passthrough_routes_forward_expected_targets(monkeypatch) -> No
     assert len(anthropic_calls) >= 2
 
 
+def test_codex_alpha_search_route_from_headroom_issue_2525() -> None:
+    class FakeAsyncClient:
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str, dict[str, str], bytes]] = []
+
+        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
+            self.calls.append(
+                (
+                    method,
+                    url,
+                    dict(kwargs.get("headers", {})),
+                    kwargs.get("content", b""),
+                )
+            )
+            return httpx.Response(200, json={"ok": True})
+
+        async def aclose(self) -> None:
+            return None
+
+    with TestClient(_app()) as client:
+        fake_http_client = FakeAsyncClient()
+        client.app.state.proxy.http_client = fake_http_client
+        response = client.post(
+            "/v1/alpha/search?query=weather",
+            headers={
+                "Authorization": "Bearer oauth-token",
+                "ChatGPT-Account-ID": "acct_123",
+            },
+            json={"query": "weather"},
+        )
+
+    assert response.status_code == 200
+    assert response.json() == {"ok": True}
+    assert len(fake_http_client.calls) == 1
+    method, url, headers, body = fake_http_client.calls[0]
+    assert method == "POST"
+    assert url == "https://chatgpt.com/backend-api/codex/alpha/search?query=weather"
+    assert headers["authorization"] == "Bearer oauth-token"
+    assert headers["chatgpt-account-id"] == "acct_123"
+    assert headers["content-length"] == "19"
+    assert headers["content-type"] == "application/json"
+    assert body == b'{"query":"weather"}'
+
+
+def test_non_chatgpt_alpha_search_falls_through_to_openai_upstream(monkeypatch) -> None:
+    calls: list[tuple[str, str, str, str, str]] = []
+
+    async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""):  # type: ignore[no-untyped-def]
+        calls.append((request.method, request.url.path, base_url, sub_path, provider_name))
+        return JSONResponse(
+            {
+                "base_url": base_url,
+                "sub_path": sub_path,
+                "provider": provider_name,
+            }
+        )
+
+    monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
+
+    with TestClient(_app()) as client:
+        response = client.post(
+            "/v1/alpha/search",
+            headers={"Authorization": "Bearer sk-proj-openai-test"},
+            json={"query": "weather"},
+        )
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "base_url": "https://api.openai.test",
+        "sub_path": "",
+        "provider": "",
+    }
+    assert calls == [
+        (
+            "POST",
+            "/v1/alpha/search",
+            "https://api.openai.test",
+            "",
+            "",
+        )
+    ]
+
+
+def test_codex_alpha_search_route_matrix(monkeypatch) -> None:
+    fallback_calls: list[tuple[str, str]] = []
+
+    async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""):  # type: ignore[no-untyped-def]
+        fallback_calls.append((request.url.path, base_url))
+        return JSONResponse({"base_url": base_url, "provider": provider_name})
+
+    monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
+
+    class FakeAsyncClient:
+        def __init__(self) -> None:
+            self.urls: list[str] = []
+
+        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
+            self.urls.append(url)
+            return httpx.Response(200, json={"ok": True})
+
+        async def aclose(self) -> None:
+            return None
+
+    with TestClient(_app()) as client:
+        fake_http_client = FakeAsyncClient()
+        client.app.state.proxy.http_client = fake_http_client
+
+        oauth_response = client.post(
+            "/v1/alpha/search",
+            headers={
+                "Authorization": "Bearer oauth-token",
+                "ChatGPT-Account-ID": "acct_123",
+            },
+            json={"query": "weather"},
+        )
+        api_key_response = client.post(
+            "/v1/alpha/search",
+            headers={"Authorization": "Bearer sk-proj-openai-test"},
+            json={"query": "weather"},
+        )
+
+    assert oauth_response.status_code == 200
+    assert api_key_response.status_code == 200
+    assert fake_http_client.urls == ["https://chatgpt.com/backend-api/codex/alpha/search"]
+    assert fallback_calls == [("/v1/alpha/search", "https://api.openai.test")]
+
+
 def test_proxy_route_helpers_prefer_legacy_targets_and_gemini_passthrough() -> None:
     proxy_routes = importlib.import_module("headroom.providers.proxy_routes")
     proxy = type(
@@ -369,7 +496,9 @@ def test_provider_specific_routes_delegate_to_expected_proxy_handlers(monkeypatc
             "handle_anthropic_batch_passthrough"
         )
         assert client.post("/v1/chat/completions").json()["handler"] == "handle_openai_chat"
+        assert client.post("/chat/completions").json()["handler"] == "handle_openai_chat"
         assert client.post("/v1/responses").json()["handler"] == "handle_openai_responses"
+        assert client.post("/responses").json()["handler"] == "handle_openai_responses"
         assert client.post("/v1/codex/responses").json()["handler"] == "handle_openai_responses"
         assert client.post("/backend-api/responses").json()["handler"] == "handle_openai_responses"
         assert client.post("/backend-api/codex/responses").json()["handler"] == (
diff --git a/tests/test_provider_route_specs.py b/tests/test_provider_route_specs.py
index 52aa8e988..f6a57db0a 100644
--- a/tests/test_provider_route_specs.py
+++ b/tests/test_provider_route_specs.py
@@ -82,6 +82,7 @@ def test_direct_handler_routes_model_endpoint_intent() -> None:
     )
     assert OPENAI_HANDLER_ROUTES == (
         ProviderHandlerRoute("POST", "/v1/chat/completions", "handle_openai_chat"),
+        ProviderHandlerRoute("POST", "/chat/completions", "handle_openai_chat"),
     )
     assert GEMINI_HANDLER_ROUTES == (
         ProviderHandlerRoute(
diff --git a/tests/test_providers/test_anthropic.py b/tests/test_providers/test_anthropic.py
index 63fa1f73f..833a6ffc9 100644
--- a/tests/test_providers/test_anthropic.py
+++ b/tests/test_providers/test_anthropic.py
@@ -54,6 +54,18 @@ class TestAnthropicTokenCounting:
         count = counter.count_messages(messages)
         assert count > 0
 
+    def test_count_messages_tolerates_null_tool_calls(self, anthropic_provider):
+        # OpenAI-format assistant messages routinely carry `tool_calls: null`
+        # (and occasionally `function: null`) on a no-tool turn. The estimated
+        # counter iterated the value after only a key-presence check, so it
+        # raised `TypeError: 'NoneType' object is not iterable`.
+        counter = anthropic_provider.get_token_counter("claude-3-5-sonnet-20241022")
+        messages = [
+            {"role": "assistant", "content": "hi", "tool_calls": None},
+            {"role": "assistant", "content": "x", "tool_calls": [{"id": "a", "function": None}]},
+        ]
+        assert counter.count_messages(messages) > 0
+
     def test_count_text_allows_literal_special_tokens(self, anthropic_provider):
         counter = anthropic_provider.get_token_counter("claude-3-5-sonnet-20241022")
         count = counter.count_text("prefix <|fim_suffix|> suffix")
diff --git a/tests/test_providers/test_openai.py b/tests/test_providers/test_openai.py
index 3b5857447..6d26993d4 100644
--- a/tests/test_providers/test_openai.py
+++ b/tests/test_providers/test_openai.py
@@ -130,3 +130,52 @@ class TestEncodingSelection:
         # Unknown models now get a fallback encoding instead of raising
         encoding = _get_encoding_name_for_model("completely-unknown")
         assert encoding == "o200k_base"  # Default fallback
+
+
+class TestGuardedEncodingLoad:
+    """The provider must never hang on tiktoken's unbounded vocab download.
+
+    Regression for the OpenAI-provider hole in GH #956: `_get_encoding` called
+    `tiktoken.get_encoding` directly, so a stalled vocab download blocked the
+    calling thread (proxy startup included) forever instead of timing out.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _clear_encoding_cache(self):
+        from headroom.providers import openai as openai_module
+
+        openai_module._get_encoding.cache_clear()
+        yield
+        openai_module._get_encoding.cache_clear()
+
+    def test_get_encoding_routes_through_bounded_loader(self, monkeypatch):
+        from headroom.providers.openai import OpenAITokenCounter
+        from headroom.tokenizers import tiktoken_counter
+
+        seen: list[str] = []
+
+        def fake_load_encoding(name: str):
+            seen.append(name)
+            raise tiktoken_counter.TiktokenLoadError(f"{name} load timed out")
+
+        monkeypatch.setattr(tiktoken_counter, "load_encoding", fake_load_encoding)
+        with pytest.raises(tiktoken_counter.TiktokenLoadError):
+            OpenAITokenCounter(model="gpt-4o")
+        assert seen == ["o200k_base"]
+
+    def test_get_token_counter_falls_back_to_estimation(self, monkeypatch):
+        from headroom.providers.openai import OpenAIProvider
+        from headroom.tokenizers import tiktoken_counter
+        from headroom.tokenizers.estimator import EstimatingTokenCounter
+
+        def fake_load_encoding(name: str):
+            raise tiktoken_counter.TiktokenLoadError(f"{name} load timed out")
+
+        monkeypatch.setattr(tiktoken_counter, "load_encoding", fake_load_encoding)
+        provider = OpenAIProvider()
+        counter = provider.get_token_counter("gpt-4o")
+        assert isinstance(counter, EstimatingTokenCounter)
+        assert counter.count_text("hello world") > 0
+        # Cached per model: later requests reuse the fallback instead of
+        # re-blocking on the failed download.
+        assert provider.get_token_counter("gpt-4o") is counter
diff --git a/tests/test_providers_opencode_config.py b/tests/test_providers_opencode_config.py
index 658ba1ea4..aec387013 100644
--- a/tests/test_providers_opencode_config.py
+++ b/tests/test_providers_opencode_config.py
@@ -199,7 +199,10 @@ def test_inject_provider_config_creates_file(
     assert config["provider"]["headroom"]["npm"] == "@ai-sdk/openai-compatible"
     # Bare model ids: OpenCode resolves them as "headroom/<id>" (#1657).
     models = config["provider"]["headroom"]["models"]
-    assert "claude-sonnet-4-6" in models
+    assert set(models) == {"gpt-4o", "gpt-4.1"}
+    # The injected provider is OpenAI-compatible. Claude models must remain on
+    # OpenCode's native Anthropic provider so they are not sent to OpenAI.
+    assert not any(model_id.startswith("claude-") for model_id in models)
     assert all(not model_id.startswith("headroom/") for model_id in models)
     assert "mcp" not in config
     assert "model" not in config  # headroom provider is a transparent pass-through
@@ -456,10 +459,12 @@ def test_build_opencode_config_content_without_mcp(
     providers = config["provider"]
     assert providers["anthropic"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
     assert providers["openai"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
-    # The headroom provider exposes explicit models so "headroom/<id>" resolves (#1657).
+    # The headroom provider exposes only models supported by its
+    # OpenAI-compatible endpoint so "headroom/<id>" resolves safely (#1657).
     assert providers["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
     models = providers["headroom"]["models"]
-    assert "claude-sonnet-4-6" in models
+    assert set(models) == {"gpt-4o", "gpt-4.1"}
+    assert not any(model_id.startswith("claude-") for model_id in models)
     assert all(not model_id.startswith("headroom/") for model_id in models)
     # The transport plugin is injected by absolute path (opencode loads it directly).
     assert config["plugin"] == [str(plugin)]
diff --git a/tests/test_providers_opencode_plugin_path.py b/tests/test_providers_opencode_plugin_path.py
index 98e8dd7eb..c6739bbe1 100644
--- a/tests/test_providers_opencode_plugin_path.py
+++ b/tests/test_providers_opencode_plugin_path.py
@@ -31,6 +31,23 @@ def test_packaged_bundle_is_committed_and_self_contained() -> None:
     assert 'from "@opencode-ai/plugin"' not in text
 
 
+def test_hook_shim_is_committed_next_to_the_entry_bundle() -> None:
+    # transport.ts resolves `../hook-shim/handler.js` next to the loaded entry,
+    # so the shim must ship as a sibling of _dist/. Without it, Node children
+    # spawned under `headroom wrap opencode` lose fetch/http routing (the
+    # existsSync guard skips injection), and before that guard they crashed with
+    # ERR_MODULE_NOT_FOUND on every Node MCP (#2850, #2806).
+    shim = _PACKAGED.resolve().parent.parent / "hook-shim" / "handler.js"
+    assert shim.is_file(), "committed wheel hook-shim missing - run npm run build:standalone"
+    text = shim.read_text(encoding="utf-8")
+    assert len(text) > 5_000, "hook-shim suspiciously small - not the standalone build?"
+    # Self-contained standalone build, not the checkout dev shim (which imports
+    # the non-bundled ../dist/index.js that site-packages has no node_modules for).
+    assert 'from "../dist/index.js"' not in text
+    assert "installHeadroomTransport" in text
+    assert "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL" in text
+
+
 def test_plugin_path_env_override_wins(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     override = tmp_path / "custom.js"
     override.write_text("// plugin")
diff --git a/tests/test_proxy/test_anthropic_buffered_timeout.py b/tests/test_proxy/test_anthropic_buffered_timeout.py
index 69e44e7f5..6e0c753bb 100644
--- a/tests/test_proxy/test_anthropic_buffered_timeout.py
+++ b/tests/test_proxy/test_anthropic_buffered_timeout.py
@@ -110,6 +110,59 @@ def _anthropic_list_response() -> httpx.Response:
     )
 
 
+def _anthropic_null_usage_response() -> dict[str, object]:
+    """An Anthropic Messages response whose usage counts are present but null.
+
+    An Anthropic-compatible gateway (custom ANTHROPIC_TARGET_API_URL) can emit
+    this shape on a stopped or empty turn — the same class that crashed the
+    Gemini path in #2347.
+    """
+    return {
+        "id": "msg_test_null",
+        "type": "message",
+        "role": "assistant",
+        "content": [{"type": "text", "text": "ok"}],
+        "usage": {
+            "input_tokens": None,
+            "output_tokens": None,
+            "cache_read_input_tokens": None,
+            "cache_creation_input_tokens": None,
+        },
+    }
+
+
+def test_anthropic_messages_buffered_survives_null_usage_counts():
+    config = _make_config()
+    app = create_app(config)
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        # Use the real prefix tracker (its `_cached_token_count` is read on this
+        # path); only pin the session id so the tracker resolves deterministically.
+        proxy.session_tracker_store.compute_session_id = lambda request, model, messages: "s1"
+
+        async def _fake_retry(method, url, headers, body, stream=False, **kwargs):  # noqa: ANN001
+            return httpx.Response(200, json=_anthropic_null_usage_response())
+
+        proxy._retry_request = _fake_retry  # type: ignore[assignment]
+
+        response = client.post(
+            "/v1/messages",
+            headers={
+                "x-api-key": "test-key",
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+            json={
+                "model": "claude-sonnet-4-6",
+                "max_tokens": 64,
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    # Null usage counts must not crash outcome recording / cache-bust math.
+    assert response.status_code == 200, response.text
+
+
 def test_anthropic_messages_buffered_timeout_override_reaches_retry_request():
     config = _make_config()
     app = create_app(config)
diff --git a/tests/test_proxy/test_anthropic_ccr_deferred_injection.py b/tests/test_proxy/test_anthropic_ccr_deferred_injection.py
index edccdbee2..a8821a9ba 100644
--- a/tests/test_proxy/test_anthropic_ccr_deferred_injection.py
+++ b/tests/test_proxy/test_anthropic_ccr_deferred_injection.py
@@ -9,11 +9,16 @@ pytest.importorskip("fastapi")
 
 from fastapi.testclient import TestClient
 
+from headroom.cache.compression_store import get_compression_store, reset_compression_store
 from headroom.proxy.helpers import _reset_session_ccr_tracker_for_test
 from headroom.proxy.server import ProxyConfig, create_app
 
 _RAW_TRANSCRIPT = "\n".join(f"row {idx}: payload payload payload" for idx in range(80))
 
+# The hash most fixtures below embed in a "[... Retrieve more: hash=...]"
+# marker to drive CCR tool injection.
+_MARKER_HASH = "abc123def456abc123def456"
+
 
 @pytest.fixture(autouse=True)
 def _reset_ccr_tracker():
@@ -30,6 +35,28 @@ def _reset_ccr_tracker():
     _reset_session_ccr_tracker_for_test()
 
 
+@pytest.fixture(autouse=True)
+def _seed_marker_hash_in_store():
+    """Make ``_MARKER_HASH`` a real, verifiable compression-store entry.
+
+    CCRToolInjector.verify_ownership() (issue #2836) only advertises the
+    retrieve tool for hashes the compression store actually recognizes.
+    These fixtures hand-type marker text rather than compressing real
+    content through the store, so without this the hash would (correctly)
+    be treated as foreign and the tool would never get injected — these
+    tests are about the deferred-injection *policy*, not about exercising
+    real storage, so seed the one hash they all key off of.
+    """
+    reset_compression_store()
+    get_compression_store().store(
+        original="original tool output",
+        compressed="[100 items compressed to 10]",
+        explicit_hash=_MARKER_HASH,
+    )
+    yield
+    reset_compression_store()
+
+
 class _FakePrefixTracker:
     def __init__(self, frozen_count: int):
         self._frozen_count = frozen_count
@@ -592,16 +619,17 @@ def test_cache_mode_compresses_delta_but_replays_cached_prefix_when_markers_are_
         assert response.status_code == 200
         assert len(captured.get("compression_calls", [])) == 1
         forwarded = captured["body"]
-        # Tool injection is deferred (no CCR tool this turn), but the frozen
-        # prefix was cached COMPRESSED last turn. Replay it byte-identical so the
-        # prompt cache still hits instead of busting on original bytes (#1850);
-        # the historical marker does not force tool injection back on. Tool absent
-        # AND cache intact.
+        # The frozen prefix was cached COMPRESSED last turn, so it is replayed
+        # byte-identical to keep the prompt cache warm. The replayed marker is
+        # still redeemable this turn, so `headroom_retrieve` MUST be present or
+        # Anthropic 400s "Tool reference 'headroom_retrieve' not found" (#2766);
+        # injecting it whenever a marker exists is itself cache-stable (toggling
+        # is what busts the tools segment). Message prefix replayed AND tool present.
         assert forwarded["messages"] == previous_forwarded_messages
-        assert "tools" not in forwarded
+        assert [tool["name"] for tool in forwarded["tools"]] == ["headroom_retrieve"]
 
 
-def test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_when_tool_injection_is_deferred(
+def test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_and_injects_retrieve_tool(
     monkeypatch,
 ) -> None:
     captured: dict[str, object] = {}
@@ -684,11 +712,13 @@ def test_cache_mode_exact_prefix_replay_forwards_cached_compressed_prefix_when_t
         assert response.status_code == 200
         assert captured.get("compression_calls", []) == []
         forwarded = captured["body"]
-        # Deferred injection (no CCR tool), single frozen message cached
-        # COMPRESSED last turn: replay it so the cache holds instead of busting
-        # on original bytes (#1850). Tool absent AND cache intact.
+        # Single frozen message cached COMPRESSED last turn: replay it
+        # byte-identical so the cache holds instead of busting on original bytes.
+        # The replayed marker is still redeemable, so `headroom_retrieve` must be
+        # present this turn or Anthropic 400s "Tool reference 'headroom_retrieve'
+        # not found" (#2766). Message prefix replayed AND tool present.
         assert forwarded["messages"] == previous_forwarded_messages
-        assert "tools" not in forwarded
+        assert [tool["name"] for tool in forwarded["tools"]] == ["headroom_retrieve"]
 
 
 def test_token_mode_cached_messages_skip_cache_update_when_pipeline_result_is_unchanged(
diff --git a/tests/test_proxy/test_anthropic_recount_and_reparse_safety.py b/tests/test_proxy/test_anthropic_recount_and_reparse_safety.py
new file mode 100644
index 000000000..1e7f67fad
--- /dev/null
+++ b/tests/test_proxy/test_anthropic_recount_and_reparse_safety.py
@@ -0,0 +1,158 @@
+"""Two request-path safety nets in ``handle_anthropic_messages``.
+
+1. #2810 — the consistency re-count runs ``count_messages`` twice. Both passes
+   are CPU-bound real BPE (since #2543) and used to run directly on the event
+   loop, stalling every other in-flight request on the process (~1s on a 2.3 MB
+   body). They must run off the loop.
+2. #2768 — the byte-faithful forwarder's verification re-parse of the original
+   body is best-effort, but ``MemoryError`` is not a ``ValueError``, so on
+   1M-context payloads it escaped and aborted an otherwise-fine request. The
+   block must never be able to fail the request.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient  # noqa: E402
+
+from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+
+MESSAGES = "/v1/messages"
+MODEL = "claude-sonnet-4-6"
+
+# Only ever present in the PRE-compression snapshot, never in the outbound body.
+# Long enough to clear the handler's min-token floors.
+SENTINEL = "presnapshot-sentinel " * 500
+
+
+def _config(**overrides) -> ProxyConfig:
+    base = {
+        "optimize": True,
+        "cache_enabled": False,
+        "rate_limit_enabled": False,
+        "cost_tracking_enabled": False,
+        "mode": "token",
+    }
+    base.update(overrides)
+    return ProxyConfig(**base)
+
+
+def _upstream_200() -> MagicMock:
+    payload = {
+        "id": "msg_1",
+        "type": "message",
+        "role": "assistant",
+        "content": [{"type": "text", "text": "ok"}],
+        "model": MODEL,
+        "usage": {"input_tokens": 10, "output_tokens": 2},
+    }
+    resp = MagicMock()
+    resp.status_code = 200
+    resp.headers = {"content-type": "application/json"}
+    resp.content = json.dumps(payload).encode()
+    resp.text = json.dumps(payload)
+    resp.json.return_value = payload
+    return resp
+
+
+def test_consistency_recount_runs_off_the_event_loop(monkeypatch):
+    """No ``count_messages`` pass over the pre-compression snapshot may run on
+    the loop thread. The snapshot is identified by SENTINEL, which the pipeline
+    strips, so this pins the re-count specifically: the already-offloaded count
+    at request start also sees the sentinel and passes either way, while the
+    two re-count passes ran inline before #2810 and would fail here.
+    """
+    import headroom.tokenizers as tokenizers_mod
+
+    seen: list[bool] = []  # one entry per snapshot count: True == ran on the loop
+
+    # Patch the class, not the cached instance, so pytest restores it for us.
+    tokenizer_cls = type(tokenizers_mod.get_tokenizer(MODEL))
+    real_count = tokenizer_cls.count_messages
+
+    def counting(self, messages):  # noqa: ANN001, ANN202
+        if SENTINEL in json.dumps(messages, default=str):
+            try:
+                asyncio.get_running_loop()
+            except RuntimeError:
+                seen.append(False)  # worker thread — no running loop here
+            else:
+                seen.append(True)  # blocking the event loop
+        return real_count(self, messages)
+
+    monkeypatch.setattr(tokenizer_cls, "count_messages", counting)
+
+    def stripping_apply(**kwargs):  # noqa: ANN003, ANN202
+        """Return genuinely-changed messages with the sentinel removed."""
+        from types import SimpleNamespace
+
+        compressed = [{**m, "content": "compressed"} for m in kwargs["messages"]]
+        return SimpleNamespace(
+            messages=compressed,
+            transforms_applied=["test_strip"],
+            timing={},
+            tokens_before=100,
+            tokens_after=80,
+            waste_signals=None,
+        )
+
+    app = create_app(_config())
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy.anthropic_pipeline.apply = MagicMock(side_effect=stripping_apply)
+        proxy._retry_request = AsyncMock(return_value=_upstream_200())
+        r = client.post(
+            MESSAGES,
+            json={
+                "model": MODEL,
+                "max_tokens": 16,
+                "messages": [{"role": "user", "content": SENTINEL}],
+            },
+        )
+
+    assert r.status_code == 200, r.text
+    assert seen, "no count_messages pass saw the snapshot; test is not exercising #2810"
+    assert not any(seen), f"{sum(seen)}/{len(seen)} snapshot counts blocked the event loop"
+
+
+def test_memoryerror_in_verification_reparse_does_not_abort_the_request(monkeypatch):
+    """A ``MemoryError`` from the best-effort original-body re-parse must be
+    swallowed (the safe fallback marks the body mutated, forcing canonical
+    re-serialization) rather than escaping and killing the request.
+    """
+    import headroom.proxy.handlers.anthropic as anthropic_mod
+
+    real_loads = json.loads
+    raised = {"n": 0}
+
+    def exploding_loads(s, *args, **kwargs):  # noqa: ANN001, ANN002, ANN003, ANN202
+        # Only the verification re-parse passes the raw original body bytes.
+        if isinstance(s, (bytes, bytearray)) and b"reparse-bomb" in s:
+            raised["n"] += 1
+            raise MemoryError("simulated re-parse spike")
+        return real_loads(s, *args, **kwargs)
+
+    monkeypatch.setattr(anthropic_mod.json, "loads", exploding_loads)
+
+    app = create_app(_config(optimize=False))
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy._retry_request = AsyncMock(return_value=_upstream_200())
+        r = client.post(
+            MESSAGES,
+            json={
+                "model": MODEL,
+                "max_tokens": 16,
+                "messages": [{"role": "user", "content": "reparse-bomb"}],
+            },
+        )
+
+    assert raised["n"] > 0, "the verification re-parse never ran; test is not exercising #2768"
+    assert r.status_code == 200, r.text
diff --git a/tests/test_proxy/test_anthropic_streaming_ccr_retrieve.py b/tests/test_proxy/test_anthropic_streaming_ccr_retrieve.py
index 3fcd3daf4..478eaceba 100644
--- a/tests/test_proxy/test_anthropic_streaming_ccr_retrieve.py
+++ b/tests/test_proxy/test_anthropic_streaming_ccr_retrieve.py
@@ -52,10 +52,6 @@ def _message_response(content: list[dict], *, stop_reason: str = "end_turn") ->
     }
 
 
-def _is_client_visible_sse(body: bytes) -> bool:
-    return b"event:" in body or b"data:" in body
-
-
 class _ContinuationClient:
     def __init__(self, response_json: dict) -> None:
         self.response_json = response_json
@@ -355,7 +351,14 @@ def test_unresolved_ccr_only_streams_through_as_200() -> None:
 
 
 @pytest.mark.asyncio
-async def test_buffered_ccr_emits_keepalive_before_delayed_upstream() -> None:
+async def test_buffered_ccr_withholds_output_until_delayed_upstream_resolves() -> None:
+    """Nothing is sent — no status, no body — until the buffered result exists.
+
+    The response used to commit ``200 text/event-stream`` on a 1s keepalive
+    timer, which made every later failure unreportable: the client saw a 200
+    with no ``message_start`` and the real status was gone. See
+    ``test_buffered_ccr_preserves_late_failure_status_and_headers``.
+    """
     config = _make_config()
     final_response = _message_response([{"type": "text", "text": "done"}])
     started = asyncio.Event()
@@ -367,8 +370,17 @@ async def test_buffered_ccr_emits_keepalive_before_delayed_upstream() -> None:
         "tools": [create_ccr_tool_definition("anthropic")],
         "messages": [{"role": "user", "content": "wait"}],
     }
+    request_delivered = False
 
     async def receive():
+        # Mirror a real ASGI server: the body arrives once, then the channel
+        # stays open because the client is still connected. Returning instantly
+        # on every call spins `StreamingResponse.listen_for_disconnect`, which
+        # never yields, so the response body would never be scheduled.
+        nonlocal request_delivered
+        if request_delivered:
+            await asyncio.Event().wait()
+        request_delivered = True
         return {"type": "http.request", "body": json.dumps(body).encode(), "more_body": False}
 
     scope = {
@@ -400,24 +412,23 @@ async def test_buffered_ccr_emits_keepalive_before_delayed_upstream() -> None:
             await started.wait()
             response = await asyncio.wait_for(asyncio.shield(task), 1)
             events: list[dict] = []
-            first_visible_body = asyncio.Event()
 
             async def send(message):  # noqa: ANN001
                 events.append(message)
-                if message["type"] == "http.response.body" and _is_client_visible_sse(
-                    message["body"]
-                ):
-                    first_visible_body.set()
 
             response_task = asyncio.create_task(response(scope, receive, send))
-            await asyncio.wait_for(first_visible_body.wait(), 2)
-            assert not release.is_set()
+            # Longer than the deleted 1.0s keepalive deadline: an unresolved
+            # upstream must still have produced no ASGI message at all.
+            await asyncio.sleep(1.1)
+            assert events == []
             release.set()
             await response_task
 
-    bodies = [event["body"] for event in events if event["type"] == "http.response.body"]
-    assert bodies[0] == b'event: ping\ndata: {"type":"ping"}\n\n'
-    assert b"done" in b"".join(bodies)
+    start = next(event for event in events if event["type"] == "http.response.start")
+    assert start["status"] == 200
+    bodies = b"".join(event["body"] for event in events if event["type"] == "http.response.body")
+    assert b"event: ping" not in bodies
+    assert b"done" in bodies
 
 
 @pytest.mark.asyncio
@@ -480,7 +491,115 @@ async def test_buffered_ccr_preserves_early_failure_status_and_headers() -> None
 
 
 @pytest.mark.asyncio
-async def test_buffered_ccr_late_failure_emits_sanitized_error_event() -> None:
+async def test_buffered_ccr_preserves_late_failure_status_and_headers() -> None:
+    """The reported failure: a non-200 landing after the old keepalive deadline.
+
+    Headroom had already committed ``200 text/event-stream`` by then, so the 429
+    reached Claude Code as a 200 whose body carried no ``message_start`` — shown
+    as "API returned an empty or malformed response (HTTP 200) — check for a
+    proxy or gateway intercepting the request" — and ``retry-after`` was dropped,
+    so the client never backed off.
+    """
+    config = _make_config()
+    started = asyncio.Event()
+    release = asyncio.Event()
+    body = {
+        "model": "claude-sonnet-4-6",
+        "max_tokens": 64,
+        "stream": True,
+        "tools": [create_ccr_tool_definition("anthropic")],
+        "messages": [{"role": "user", "content": "fail late"}],
+    }
+
+    async def receive():
+        return {"type": "http.request", "body": json.dumps(body).encode(), "more_body": False}
+
+    scope = {
+        "type": "http",
+        "http_version": "1.1",
+        "method": "POST",
+        "scheme": "http",
+        "path": "/v1/messages",
+        "raw_path": b"/v1/messages",
+        "query_string": b"",
+        "headers": [(b"x-api-key", b"test-key"), (b"anthropic-version", b"2023-06-01")],
+        "server": ("testserver", 80),
+        "client": ("testclient", 123),
+        "root_path": "",
+    }
+
+    with patch("headroom.proxy.server.AnyLLMBackend"):
+        app = create_app(config)
+        with TestClient(app):
+            proxy = app.state.proxy
+
+            async def delayed_failure(*args, **kwargs):  # noqa: ANN002, ANN003
+                started.set()
+                await release.wait()
+                return httpx.Response(
+                    429,
+                    headers={"retry-after": "7"},
+                    json={"error": {"message": "slow down"}},
+                )
+
+            proxy._retry_request = delayed_failure
+            task = asyncio.create_task(proxy.handle_anthropic_messages(Request(scope, receive)))
+            await started.wait()
+            response = await asyncio.wait_for(asyncio.shield(task), 1)
+            events: list[dict] = []
+
+            async def send(message):  # noqa: ANN001
+                events.append(message)
+
+            response_task = asyncio.create_task(response(scope, receive, send))
+            # Past the deleted 1.0s keepalive deadline before the upstream fails.
+            await asyncio.sleep(1.1)
+            assert events == []
+            release.set()
+            await response_task
+
+    start = next(event for event in events if event["type"] == "http.response.start")
+    assert start["status"] == 429
+    assert dict(start["headers"])[b"retry-after"] == b"7"
+    assert b"slow down" in b"".join(
+        event["body"] for event in events if event["type"] == "http.response.body"
+    )
+
+
+def test_buffered_ccr_rejects_malformed_success_as_502() -> None:
+    """A non-SSE, non-JSON 200 is an upstream protocol error, not success."""
+    config = _make_config()
+    with patch("headroom.proxy.server.AnyLLMBackend"):
+        app = create_app(config)
+        with TestClient(app) as client:
+            proxy = app.state.proxy
+            proxy._retry_request = AsyncMock(
+                return_value=httpx.Response(
+                    200,
+                    content=b"<html>gateway timeout</html>",
+                    headers={"content-type": "text/html"},
+                )
+            )
+            response = client.post(
+                "/v1/messages",
+                headers={"x-api-key": "test-key", "anthropic-version": "2023-06-01"},
+                json={
+                    "model": "claude-sonnet-4-6",
+                    "max_tokens": 64,
+                    "stream": True,
+                    "tools": [create_ccr_tool_definition("anthropic")],
+                    "messages": [{"role": "user", "content": "fail safely"}],
+                },
+            )
+
+    assert response.status_code == 502
+    assert response.json()["error"]["type"] == "upstream_protocol_error"
+    assert b"gateway timeout" not in response.content
+
+
+@pytest.mark.asyncio
+async def test_buffered_ccr_late_failure_returns_sanitized_json_error() -> None:
+    """A slow crash gets the same 502 the fast one does, not a downgraded 200."""
     config = _make_config()
     started = asyncio.Event()
     release = asyncio.Event()
@@ -533,24 +652,23 @@ async def test_buffered_ccr_late_failure_emits_sanitized_error_event() -> None:
                 await started.wait()
                 response = await asyncio.wait_for(asyncio.shield(task), 1)
                 events: list[dict] = []
-                first_body = asyncio.Event()
 
                 async def send(message):  # noqa: ANN001
                     events.append(message)
-                    if message["type"] == "http.response.body" and message["body"]:
-                        first_body.set()
 
                 response_task = asyncio.create_task(response(scope, receive, send))
-                await asyncio.wait_for(first_body.wait(), 2)
+                await asyncio.sleep(0)
+                assert events == []
                 release.set()
                 await response_task
                 record_failed.assert_awaited_once_with(provider="anthropic")
             proxy_logger.removeHandler(log_handler)
 
-    bodies = [event["body"] for event in events if event["type"] == "http.response.body"]
-    assert bodies[0] == b'event: ping\ndata: {"type":"ping"}\n\n'
-    assert b"An error occurred while processing the request." in bodies[-1]
-    assert b"boom" not in bodies[-1]
+    start = next(event for event in events if event["type"] == "http.response.start")
+    assert start["status"] == 502
+    bodies = b"".join(event["body"] for event in events if event["type"] == "http.response.body")
+    assert b"An error occurred while processing your request." in bodies
+    assert b"boom" not in bodies
     assert events[-1]["more_body"] is False
     assert any(
         record.levelno == logging.ERROR and "RuntimeError: boom" in record.getMessage()
diff --git a/tests/test_proxy/test_gemini_savings_profile.py b/tests/test_proxy/test_gemini_savings_profile.py
index bb67f91fc..21733f293 100644
--- a/tests/test_proxy/test_gemini_savings_profile.py
+++ b/tests/test_proxy/test_gemini_savings_profile.py
@@ -199,3 +199,76 @@ def test_gemini_zero_usage_prompt_count_is_preserved():
     outcome = captured["outcome"]
     assert outcome.optimized_tokens == 0
     assert outcome.uncached_input_tokens == 0
+
+
+def test_gemini_provider_count_above_local_estimate_does_not_inflate_eligible():
+    """When Gemini's promptTokenCount exceeds our local estimate, the outcome must
+    not ship attempted_input_tokens > original_tokens (a structurally impossible
+    eligible_pct > 100) or a phantom tokens_inflated. The local baseline is lifted
+    onto the provider scale, matching the streaming finalizer's tested handling."""
+    config = ProxyConfig(
+        optimize=True,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+    )
+
+    # Local pipeline count: 100 tokens before compression, 80 after (saved 20).
+    # Return genuinely-changed messages so the handler adopts the pipeline's
+    # tokens_before/after (the override only fires when messages actually change).
+    def passthrough_apply(**kwargs):
+        sent = kwargs["messages"]
+        compressed = [dict(m) for m in sent]
+        if compressed:
+            compressed[0] = {**compressed[0], "content": "compressed"}
+        return SimpleNamespace(
+            messages=compressed,
+            transforms_applied=["gemini_compress"],
+            timing={},
+            tokens_before=100,
+            tokens_after=80,
+            waste_signals=None,
+        )
+
+    # Gemini counts the forwarded prompt at 150 -- higher than our local 80, so
+    # attempted = 150 + 20 = 170 would exceed a local original of 100.
+    resp = MagicMock()
+    resp.status_code = 200
+    resp.headers = {"content-type": "application/json"}
+    resp.content = (
+        b'{"candidates":[{"content":{"parts":[{"text":"ok"}]}}],'
+        b'"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":2}}'
+    )
+    resp.json.return_value = {
+        "candidates": [{"content": {"parts": [{"text": "ok"}]}}],
+        "usageMetadata": {"promptTokenCount": 150, "candidatesTokenCount": 2},
+    }
+
+    captured: dict[str, object] = {}
+
+    async def recording_outcome(outcome):  # noqa: ANN001
+        captured["outcome"] = outcome
+
+    big = "word " * 4000
+    app = create_app(config)
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy.openai_pipeline.apply = MagicMock(side_effect=passthrough_apply)
+        proxy._retry_request = AsyncMock(return_value=resp)
+        proxy._record_request_outcome = AsyncMock(side_effect=recording_outcome)
+
+        r = client.post(
+            "/v1beta/models/gemini-2.0-flash:generateContent?key=test-key",
+            json={"contents": [{"parts": [{"text": big}]}]},
+        )
+
+    assert r.status_code == 200, r.text
+    outcome = captured["outcome"]
+    # The provider's own count is still carried for billing/dashboard.
+    assert outcome.optimized_tokens == 150
+    # The eligible ratio cannot exceed 100%: attempted must not exceed original.
+    assert outcome.attempted_input_tokens <= outcome.original_tokens
+    # No phantom growth (optimized - original clamped to >= 0 was 50 before).
+    assert outcome.tokens_inflated == 0
+    # Baseline lifted onto the provider scale: max(local 100, provider 150 + saved 20).
+    assert outcome.original_tokens == 170
diff --git a/tests/test_proxy/test_openai_chat_ccr_injection.py b/tests/test_proxy/test_openai_chat_ccr_injection.py
new file mode 100644
index 000000000..030228685
--- /dev/null
+++ b/tests/test_proxy/test_openai_chat_ccr_injection.py
@@ -0,0 +1,16 @@
+"""Streaming chat CCR injection must not advertise an unredeemable tool."""
+
+from headroom.proxy.handlers.openai import _should_inject_openai_chat_ccr_tool
+
+
+def test_streaming_chat_does_not_inject_ccr_tool() -> None:
+    assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=True, stream=True) is False
+
+
+def test_non_streaming_chat_still_injects_ccr_tool() -> None:
+    assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=True, stream=False) is True
+
+
+def test_disabled_ccr_never_injects_tool() -> None:
+    assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=False, stream=False) is False
+    assert _should_inject_openai_chat_ccr_tool(ccr_inject_tool=False, stream=True) is False
diff --git a/tests/test_proxy/test_openai_responses_ccr.py b/tests/test_proxy/test_openai_responses_ccr.py
index 9bae90cd2..7e63496b0 100644
--- a/tests/test_proxy/test_openai_responses_ccr.py
+++ b/tests/test_proxy/test_openai_responses_ccr.py
@@ -266,7 +266,8 @@ def test_streaming_request_without_retrieve_tool_uses_normal_stream_path():
 
 
 @pytest.mark.asyncio
-async def test_buffered_responses_ccr_emits_keepalive_before_delayed_upstream():
+async def test_buffered_responses_ccr_withholds_output_until_upstream_resolves():
+    """Nothing is sent — no status, no body — until the buffered result exists."""
     app = _make_app()
     body = {
         "model": "gpt-5-codex",
@@ -276,8 +277,17 @@ async def test_buffered_responses_ccr_emits_keepalive_before_delayed_upstream():
     }
     started = asyncio.Event()
     release = asyncio.Event()
+    request_delivered = False
 
     async def receive():
+        # Mirror a real ASGI server: the body arrives once, then the channel
+        # stays open because the client is still connected. Returning instantly
+        # on every call spins `StreamingResponse.listen_for_disconnect`, which
+        # never yields, so the response body would never be scheduled.
+        nonlocal request_delivered
+        if request_delivered:
+            await asyncio.Event().wait()
+        request_delivered = True
         return {"type": "http.request", "body": json.dumps(body).encode(), "more_body": False}
 
     scope = {
@@ -307,22 +317,23 @@ async def test_buffered_responses_ccr_emits_keepalive_before_delayed_upstream():
         await started.wait()
         response = await asyncio.wait_for(asyncio.shield(task), 1)
         events: list[dict] = []
-        first_body = asyncio.Event()
 
         async def send(message):  # noqa: ANN001
             events.append(message)
-            if message["type"] == "http.response.body" and message["body"]:
-                first_body.set()
 
         response_task = asyncio.create_task(response(scope, receive, send))
-        await asyncio.wait_for(first_body.wait(), 2)
-        assert not release.is_set()
+        # Longer than the deleted 1.0s keepalive deadline: an unresolved upstream
+        # must still have produced no ASGI message at all.
+        await asyncio.sleep(1.1)
+        assert events == []
         release.set()
         await response_task
 
-    bodies = [event["body"] for event in events if event["type"] == "http.response.body"]
-    assert bodies[0] == b'event: ping\ndata: {"type":"ping"}\n\n'
-    assert b"Resolved!" in b"".join(bodies)
+    start = next(event for event in events if event["type"] == "http.response.start")
+    assert start["status"] == 200
+    bodies = b"".join(event["body"] for event in events if event["type"] == "http.response.body")
+    assert b"event: ping" not in bodies
+    assert b"Resolved!" in bodies
 
 
 @pytest.mark.asyncio
@@ -382,6 +393,35 @@ async def test_buffered_responses_ccr_preserves_early_failure_status_and_headers
     )
 
 
+def test_buffered_responses_ccr_rejects_malformed_success_as_502():
+    """A malformed upstream 200 must not become a successful streamed turn."""
+    app = _make_app()
+    with TestClient(app) as client:
+        server = app.state.proxy
+        server._retry_request = AsyncMock(
+            return_value=httpx.Response(
+                200,
+                content=b"<html>gateway timeout</html>",
+                headers={"content-type": "text/html"},
+                request=httpx.Request("POST", "https://api.openai.com/v1/responses"),
+            )
+        )
+        response = client.post(
+            "/v1/responses",
+            headers={"authorization": "Bearer sk-test"},
+            json={
+                "model": "gpt-5-codex",
+                "input": "fail safely",
+                "stream": True,
+                "tools": [_RETRIEVE_TOOL],
+            },
+        )
+
+    assert response.status_code == 502
+    assert response.json()["error"]["type"] == "upstream_protocol_error", response.text
+    assert b"gateway timeout" not in response.content
+
+
 @pytest.mark.asyncio
 async def test_buffered_responses_ccr_late_failure_emits_sanitized_error_event():
     app = _make_app()
@@ -431,24 +471,23 @@ async def test_buffered_responses_ccr_late_failure_emits_sanitized_error_event()
             await started.wait()
             response = await asyncio.wait_for(asyncio.shield(task), 1)
             events: list[dict] = []
-            first_body = asyncio.Event()
 
             async def send(message):  # noqa: ANN001
                 events.append(message)
-                if message["type"] == "http.response.body" and message["body"]:
-                    first_body.set()
 
             response_task = asyncio.create_task(response(scope, receive, send))
-            await asyncio.wait_for(first_body.wait(), 2)
+            await asyncio.sleep(0)
+            assert events == []
             release.set()
             await response_task
             record_failed.assert_awaited_once_with(provider="openai")
         proxy_logger.removeHandler(log_handler)
 
-    bodies = [event["body"] for event in events if event["type"] == "http.response.body"]
-    assert bodies[0] == b'event: ping\ndata: {"type":"ping"}\n\n'
-    assert b"An error occurred while processing the request." in bodies[-1]
-    assert b"boom" not in bodies[-1]
+    start = next(event for event in events if event["type"] == "http.response.start")
+    assert start["status"] == 502
+    bodies = b"".join(event["body"] for event in events if event["type"] == "http.response.body")
+    assert b"An error occurred while processing your request." in bodies
+    assert b"boom" not in bodies
     assert events[-1]["more_body"] is False
     assert any(
         record.levelno == logging.ERROR and "RuntimeError: boom" in record.getMessage()
diff --git a/tests/test_proxy/test_settings_store.py b/tests/test_proxy/test_settings_store.py
index c6c1876cc..58f6bce66 100644
--- a/tests/test_proxy/test_settings_store.py
+++ b/tests/test_proxy/test_settings_store.py
@@ -63,6 +63,37 @@ class TestRoundTrip:
 
 
 class TestValidation:
+    def test_validate_accepts_env_aliases(self, workspace):
+        assert settings_store.validate({"HEADROOM_LOSSLESS": True, "HEADROOM_RPM": "30"}) == {
+            "lossless": True,
+            "rpm": 30,
+        }
+
+    def test_save_accepts_env_alias_and_persists_short_key(self, workspace):
+        settings_store.save({"HEADROOM_LOSSLESS": True})
+
+        assert settings_store.load() == {"lossless": True}
+
+    def test_env_alias_clear_removes_short_key(self, workspace):
+        settings_store.save({"lossless": True})
+
+        settings_store.save({"HEADROOM_LOSSLESS": None})
+
+        assert settings_store.load() == {}
+
+    def test_conflicting_env_alias_and_short_key_rejected(self, workspace):
+        with pytest.raises(settings_store.SettingsValidationError) as exc:
+            settings_store.validate({"HEADROOM_LOSSLESS": True, "lossless": False})
+
+        assert exc.value.unknown_keys == []
+        assert "lossless" in exc.value.field_errors
+        assert "HEADROOM_LOSSLESS" in exc.value.field_errors["lossless"]
+
+    def test_same_env_alias_and_short_key_value_is_accepted(self, workspace):
+        assert settings_store.validate({"HEADROOM_LOSSLESS": True, "lossless": True}) == {
+            "lossless": True
+        }
+
     def test_save_rejects_unknown_key(self, workspace):
         with pytest.raises(settings_store.SettingsValidationError) as exc:
             settings_store.save({"nope": 1})
@@ -156,6 +187,7 @@ class TestSecretMasking:
         )
         monkeypatch.setattr(settings_store, "SETTINGS", registry)
         monkeypatch.setattr(settings_store, "_BY_KEY", {f.key: f for f in registry})
+        monkeypatch.setattr(settings_store, "_BY_ENV", {f.env: f for f in registry})
         settings_store.save({"log_file": "/tmp/secret.log"})
 
         stored = settings_store.stored_values()
@@ -187,6 +219,15 @@ class TestSecretMasking:
             "Saving _MASK should retain the stored value, not overwrite it"
         )
 
+    def test_anthropic_extra_headers_retain_on_env_alias_mask(self, workspace, monkeypatch):
+        """Saving _MASK through the env alias retains the stored value."""
+        _clear_env(monkeypatch)
+        settings_store.save({"anthropic_extra_headers": '{"Api-Key": "secret123"}'})
+
+        settings_store.save({"ANTHROPIC_TARGET_API_HEADERS": settings_store._MASK})
+
+        assert settings_store.load().get("anthropic_extra_headers") == '{"Api-Key": "secret123"}'
+
     def test_anthropic_extra_headers_clear_on_none(self, workspace, monkeypatch):
         """Saving None for anthropic_extra_headers removes it."""
         _clear_env(monkeypatch)
diff --git a/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py
new file mode 100644
index 000000000..9d635fc1b
--- /dev/null
+++ b/tests/test_proxy/test_tool_search_repair_after_turn_hooks.py
@@ -0,0 +1,239 @@
+"""Tool-search history repair must run AFTER the turn hooks (#2888).
+
+``strip_unsupported_tool_search_blocks`` (#2807) validates every replayed
+``tool_reference`` against the request's ``tools`` array. A registered turn hook
+may rewrite that array, so repairing before the hook validates against a stale
+view: the reference looks resolvable, the hook then drops the tool it named, and
+upstream 400s with ``Tool reference 'X' not found in available tools``.
+
+These drive the real handler and assert on the forwarded body, because ordering
+is the whole property under test -- a unit test of the helper cannot see it.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import httpx
+import pytest
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient
+
+from headroom.ccr.tool_injection import CCR_TOOL_NAME
+from headroom.proxy.server import ProxyConfig, create_app
+from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook
+
+_SEARCH_TOOL = {"type": "tool_search_tool_20250917", "name": "tool_search"}
+_GREP = {"name": "Grep", "description": "search files", "input_schema": {"type": "object"}}
+_READ = {"name": "Read", "description": "read a file", "input_schema": {"type": "object"}}
+_CCR_TOOL = {
+    "name": CCR_TOOL_NAME,
+    "description": "retrieve compressed content",
+    "input_schema": {"type": "object"},
+}
+
+# A transcript that already carries a resolved tool-search round trip for `Grep`.
+_POISONED_MESSAGES = [
+    {"role": "user", "content": "find the thing"},
+    {
+        "role": "assistant",
+        "content": [
+            {
+                "type": "server_tool_use",
+                "id": "srvtoolu_1",
+                "name": "tool_search_tool_20250917",
+                "input": {"query": "grep"},
+            },
+            {
+                "type": "tool_search_tool_result",
+                "tool_use_id": "srvtoolu_1",
+                "content": {
+                    "type": "tool_search_tool_result_content",
+                    "tool_references": [{"type": "tool_reference", "tool_name": "Grep"}],
+                },
+            },
+        ],
+    },
+    {"role": "user", "content": "now use it"},
+]
+
+_CCR_POISONED_MESSAGES = [
+    {"role": "user", "content": "expand the saved result"},
+    {
+        "role": "assistant",
+        "content": [
+            {
+                "type": "tool_use",
+                "id": "toolu_ccr_1",
+                "name": CCR_TOOL_NAME,
+                "input": {"hash": "abc123def456abc123def456"},
+            }
+        ],
+    },
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": "toolu_ccr_1",
+                "content": "the expanded result",
+            }
+        ],
+    },
+]
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    clear_turn_hooks()
+    yield
+    clear_turn_hooks()
+
+
+class _DropToolHook:
+    """Turn hook that removes one tool from the outbound array."""
+
+    def __init__(self, name: str):
+        self._name = name
+
+    def on_request(self, ctx) -> None:  # noqa: ANN001
+        if ctx.tools:
+            ctx.tools = [t for t in ctx.tools if t.get("name") != self._name]
+
+
+class _InertHook:
+    def on_request(self, ctx) -> None:  # noqa: ANN001, ARG002
+        return None
+
+
+def _run(
+    hook,  # noqa: ANN001
+    *,
+    messages: list[dict] = _POISONED_MESSAGES,
+    tools: list[dict] | None = None,
+) -> dict:
+    """POST a poisoned transcript through the handler, return the forwarded body."""
+    captured: dict[str, object] = {}
+    register_turn_hook(hook)
+
+    config = ProxyConfig(
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+        log_requests=False,
+        ccr_inject_tool=False,
+        ccr_handle_responses=False,
+        ccr_context_tracking=False,
+        image_optimize=False,
+    )
+    with TestClient(create_app(config)) as client:
+        proxy = client.app.state.proxy
+        proxy.pipeline_extensions.emit = lambda *args, **kwargs: SimpleNamespace(
+            messages=kwargs.get("messages"),
+            tools=kwargs.get("tools"),
+            headers=kwargs.get("headers"),
+            metadata=kwargs.get("metadata"),
+        )
+
+        async def _fake_retry(method, url, headers, body, stream=False, **kwargs):  # noqa: ANN001
+            captured["body"] = body
+            return httpx.Response(
+                200,
+                json={
+                    "id": "msg_repair_order",
+                    "type": "message",
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "ok"}],
+                    "usage": {"input_tokens": 20, "output_tokens": 3},
+                },
+            )
+
+        proxy._retry_request = _fake_retry
+
+        response = client.post(
+            "/v1/messages",
+            headers={"x-api-key": "test-key", "anthropic-version": "2023-06-01"},
+            json={
+                "model": "claude-sonnet-4-6",
+                "max_tokens": 64,
+                "messages": messages,
+                "tools": tools or [_SEARCH_TOOL, _GREP, _READ],
+            },
+        )
+        assert response.status_code == 200
+
+    return captured["body"]  # type: ignore[return-value]
+
+
+def _referenced_tool_names(body: dict) -> list[str]:
+    names = []
+    for message in body.get("messages", []):
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if not isinstance(block, dict) or block.get("type") != "tool_search_tool_result":
+                continue
+            inner = block.get("content")
+            entries = inner.get("tool_references") if isinstance(inner, dict) else inner
+            for entry in entries or []:
+                names.append(str(entry.get("tool_name") or entry.get("name")))
+    return names
+
+
+def _block_types(body: dict) -> list[str]:
+    types = []
+    for message in body.get("messages", []):
+        content = message.get("content")
+        if isinstance(content, list):
+            types.extend(str(b.get("type")) for b in content if isinstance(b, dict))
+    return types
+
+
+def test_repair_sees_the_tools_array_the_hook_left_behind() -> None:
+    """A hook that drops `Grep` must leave no dangling reference to it."""
+    forwarded = _run(_DropToolHook("Grep"))
+
+    assert "Grep" not in [t.get("name") for t in forwarded["tools"]]
+    # The whole pair goes: an orphaned server_tool_use 400s on its own.
+    assert _referenced_tool_names(forwarded) == []
+    assert "tool_search_tool_result" not in _block_types(forwarded)
+    assert "server_tool_use" not in _block_types(forwarded)
+
+
+def test_repair_leaves_resolvable_history_alone_when_the_hook_keeps_the_tool() -> None:
+    """The converse: no over-stripping when the hook does not touch `tools`."""
+    forwarded = _run(_InertHook())
+
+    assert _referenced_tool_names(forwarded) == ["Grep"]
+    assert "tool_search_tool_result" in _block_types(forwarded)
+
+
+def test_ccr_repair_sees_the_tools_array_the_hook_left_behind() -> None:
+    """CCR repair also runs after a hook removes headroom_retrieve."""
+    forwarded = _run(
+        _DropToolHook(CCR_TOOL_NAME),
+        messages=_CCR_POISONED_MESSAGES,
+        tools=[_CCR_TOOL, _READ],
+    )
+
+    assert CCR_TOOL_NAME not in [t.get("name") for t in forwarded["tools"]]
+    assert "tool_use" not in _block_types(forwarded)
+    assert "tool_result" not in _block_types(forwarded)
+    assert forwarded["messages"][2]["content"] == [{"type": "text", "text": "the expanded result"}]
+
+
+def test_ccr_repair_leaves_resolvable_history_when_hook_keeps_tool() -> None:
+    """CCR history remains structured when the final tools array declares it."""
+    forwarded = _run(
+        _InertHook(),
+        messages=_CCR_POISONED_MESSAGES,
+        tools=[_CCR_TOOL, _READ],
+    )
+
+    assert CCR_TOOL_NAME in [t.get("name") for t in forwarded["tools"]]
+    assert "tool_use" in _block_types(forwarded)
+    assert "tool_result" in _block_types(forwarded)
diff --git a/tests/test_proxy_anthropic_cache_stability.py b/tests/test_proxy_anthropic_cache_stability.py
index 326b9a193..b7a26d68f 100644
--- a/tests/test_proxy_anthropic_cache_stability.py
+++ b/tests/test_proxy_anthropic_cache_stability.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import copy
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
 
@@ -16,6 +17,15 @@ from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
 from headroom.proxy.server import ProxyConfig, create_app
 
 
+def _force_compression(monkeypatch) -> None:  # noqa: ANN001
+    decision = SimpleNamespace(should_compress=True, passthrough_reason=None)
+    decision.apply_to_tags = lambda tags: None
+    monkeypatch.setattr(
+        "headroom.proxy.handlers.anthropic.CompressionDecision.decide",
+        lambda **kwargs: decision,
+    )
+
+
 class _FakePrefixTracker:
     def __init__(self, frozen_count: int):
         self._frozen_count = frozen_count
@@ -505,6 +515,9 @@ def test_ccr_system_instruction_injection_disabled_when_prefix_frozen(monkeypatc
             def scan_for_markers(self, messages):  # noqa: ANN001
                 return []
 
+            def verify_ownership(self, store=None):  # noqa: ANN001
+                return self.detected_hashes
+
         monkeypatch.setattr("headroom.ccr.CCRToolInjector", _FakeInjector)
 
         async def _fake_retry(method, url, headers, body, stream=False, **kwargs):  # noqa: ANN001
@@ -572,6 +585,9 @@ def test_ccr_tool_injection_disabled_when_prefix_frozen(monkeypatch) -> None:
             def scan_for_markers(self, messages):  # noqa: ANN001
                 return []
 
+            def verify_ownership(self, store=None):  # noqa: ANN001
+                return self.detected_hashes
+
         monkeypatch.setattr("headroom.ccr.CCRToolInjector", _FakeInjector)
 
         async def _fake_retry(method, url, headers, body, stream=False, **kwargs):  # noqa: ANN001
@@ -620,12 +636,24 @@ def test_ccr_tool_stays_in_forwarded_tools_across_frozen_transition() -> None:
     value: unit-testing the old policy in isolation is exactly what let a
     wrong-but-self-consistent decision pass.
     """
+    from headroom.cache.compression_store import get_compression_store, reset_compression_store
     from headroom.ccr.tool_injection import CCR_TOOL_NAME
     from headroom.proxy.helpers import (
         _reset_session_ccr_tracker_for_test,
         serialize_tool_definition_canonical,
     )
 
+    # verify_ownership() (issue #2836) requires the marker's hash to be a
+    # real store entry — seed one with the exact hash the marker text below
+    # references, via explicit_hash (the store's own hash generation from
+    # `original` content wouldn't match this hand-typed literal).
+    reset_compression_store()
+    get_compression_store().store(
+        original="original tool output",
+        compressed="[50 items compressed to 5]",
+        explicit_hash="abc123def456abc123def456",
+    )
+
     marker_message = {
         "role": "user",
         "content": [
@@ -701,6 +729,7 @@ def test_ccr_tool_stays_in_forwarded_tools_across_frozen_transition() -> None:
             assert _post().status_code == 200
     finally:
         _reset_session_ccr_tracker_for_test()
+        reset_compression_store()
 
     assert len(forwarded) == 2, "expected exactly two forwarded requests"
 
@@ -993,7 +1022,8 @@ def test_token_mode_does_not_force_freeze_all_previous_turns() -> None:
         assert captured["frozen_message_count"] >= 0
 
 
-def test_cache_mode_restores_frozen_prefix_if_transform_mutates_history() -> None:
+def test_cache_mode_restores_frozen_prefix_if_transform_mutates_history(monkeypatch) -> None:
+    _force_compression(monkeypatch)
     captured = {}
     with _make_proxy_client() as client:
         proxy = client.app.state.proxy
@@ -1012,6 +1042,11 @@ def test_cache_mode_restores_frozen_prefix_if_transform_mutates_history() -> Non
             {"role": "assistant", "content": "turn1-assistant"},
             {"role": "user", "content": "current turn"},
         ]
+        # Mid-session: the first two messages were already forwarded last turn,
+        # so they form the byte-stable cached prefix the handler must replay
+        # even if a transform tries to mutate them.
+        fake_tracker._last_original_messages = original_messages[:2]
+        fake_tracker._last_forwarded_messages = original_messages[:2]
 
         def _fake_apply(**kwargs):
             mutated = list(kwargs["messages"])
@@ -1063,7 +1098,11 @@ def test_cache_mode_restores_frozen_prefix_if_transform_mutates_history() -> Non
         assert sent_messages[1] == original_messages[1]
 
 
-def test_cache_mode_does_not_forward_latest_turn_rewrites() -> None:
+def test_cache_mode_cold_start_forwards_pipeline_rewrites(monkeypatch) -> None:
+    _force_compression(monkeypatch)
+    # Issue #2357: on a true session cold start (no prior forwarded messages,
+    # no frozen prefix) there is no provider cache to protect, so the full
+    # pipeline output is forwarded and recorded for byte-identical replay.
     captured = {}
     with _make_proxy_client() as client:
         proxy = client.app.state.proxy
@@ -1128,7 +1167,12 @@ def test_cache_mode_does_not_forward_latest_turn_rewrites() -> None:
         )
 
         assert response.status_code == 200
-        assert captured["body"]["messages"] == original_messages
+        sent_messages = captured["body"]["messages"]
+        assert sent_messages[:2] == original_messages[:2]
+        assert sent_messages[2]["content"] == "REWRITTEN_CURRENT_TURN"
+        # Recorded as forwarded so later turns replay this prefix verbatim
+        # (the tracker may append the assistant reply after the forwarded turns).
+        assert fake_tracker._last_forwarded_messages[: len(sent_messages)] == sent_messages
 
 
 def test_cache_mode_reuses_prior_forwarded_prefix_and_compresses_only_new_suffix() -> None:
@@ -1243,6 +1287,156 @@ def test_cache_mode_reuses_prior_forwarded_prefix_and_compresses_only_new_suffix
         ]
 
 
+def test_anthropic_handler_splits_prefix_trackers_when_tool_profiles_differ() -> None:
+    """The handler must pass its non-message cache affinity into resolution.
+
+    Anthropic's cache key begins with tools. Identical messages on two parallel
+    sub-calls therefore cannot safely share frozen-prefix state when their tool
+    arrays differ (#2671 Pattern B).
+    """
+    resolved = []
+    with _make_proxy_client() as client:
+        proxy = client.app.state.proxy
+        proxy.config.optimize = True
+        proxy.config.mode = "cache"
+        proxy.config.image_optimize = False
+
+        real_resolve = proxy.session_tracker_store.resolve_tracker
+
+        def _spy_resolve(session_id, provider, messages=None, cache_affinity=None):  # noqa: ANN001
+            tracker = real_resolve(
+                session_id,
+                provider,
+                messages=messages,
+                cache_affinity=cache_affinity,
+            )
+            resolved.append((cache_affinity, tracker))
+            return tracker
+
+        proxy.session_tracker_store.resolve_tracker = _spy_resolve
+
+        async def _fake_retry(method, url, headers, body, stream=False, **kwargs):  # noqa: ANN001
+            return httpx.Response(
+                200,
+                json={
+                    "id": "msg_affinity",
+                    "type": "message",
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "ok"}],
+                    "usage": {
+                        "input_tokens": 10,
+                        "output_tokens": 1,
+                        "cache_read_input_tokens": 0,
+                        "cache_creation_input_tokens": 0,
+                    },
+                },
+            )
+
+        proxy._retry_request = _fake_retry
+        headers = {"x-api-key": "test-key", "anthropic-version": "2023-06-01"}
+        messages = [{"role": "user", "content": "same parent transcript"}]
+
+        for tool_name in ("shell", "search"):
+            response = client.post(
+                "/v1/messages",
+                headers=headers,
+                json={
+                    "model": "claude-sonnet-4-6",
+                    "max_tokens": 32,
+                    "messages": messages,
+                    "tools": [
+                        {
+                            "name": tool_name,
+                            "description": tool_name,
+                            "input_schema": {"type": "object", "properties": {}},
+                        }
+                    ],
+                },
+            )
+            assert response.status_code == 200
+
+    assert len(resolved) == 2
+    assert resolved[0][0] != resolved[1][0]
+    assert resolved[0][1] is not resolved[1][1]
+
+
+def test_anthropic_handler_anchors_a_proven_rewritten_tail_to_stable_blocks() -> None:
+    """The real handler must feed last turn's bytes into normalization."""
+    bodies = []
+
+    def _history(turn: int, churn: int) -> list[dict]:
+        content = [{"type": "text", "text": f"stable-{index}"} for index in range(30)]
+        content.extend(
+            {"type": "text", "text": f"turn-{turn}-changing-{index}"} for index in range(churn)
+        )
+        content.extend(
+            [
+                {"type": "text", "text": "instruction: summarize"},
+                {"type": "text", "text": "fixed end-of-transcript reminder"},
+            ]
+        )
+        return [{"role": "user", "content": content}]
+
+    with _make_proxy_client() as client:
+        proxy = client.app.state.proxy
+        # Breakpoint ownership and lineage tracking apply even in passthrough
+        # mode. Keeping optimization off isolates that real handler wiring from
+        # the compression pipeline.
+        proxy.config.optimize = False
+        proxy.config.image_optimize = False
+        # This regression models a client whose next request replaces the same
+        # aggregate message. Do not synthesize an assistant history entry in
+        # the tracker, because that is a separate response-reconstruction path.
+        proxy._assistant_message_from_response_json = lambda _body: None
+
+        async def _fake_retry(method, url, headers, body, stream=False, **kwargs):  # noqa: ANN001
+            bodies.append(copy.deepcopy(body))
+            return httpx.Response(
+                200,
+                json={
+                    "id": "msg_rewrite",
+                    "type": "message",
+                    "role": "assistant",
+                    "content": [],
+                    "usage": {
+                        "input_tokens": 10_000,
+                        "output_tokens": 1,
+                        "cache_read_input_tokens": 0,
+                        "cache_creation_input_tokens": 10_000,
+                    },
+                },
+            )
+
+        proxy._retry_request = _fake_retry
+        headers = {"x-api-key": "test-key", "anthropic-version": "2023-06-01"}
+        for turn, churn in enumerate((3, 5, 8), start=1):
+            response = client.post(
+                "/v1/messages",
+                headers=headers,
+                json={
+                    "model": "claude-sonnet-4-6",
+                    "max_tokens": 32,
+                    "messages": _history(turn, churn),
+                },
+            )
+            assert response.status_code == 200
+
+    breakpoint_indices = []
+    for body in bodies:
+        marked = [
+            index
+            for index, block in enumerate(body["messages"][0]["content"])
+            if "cache_control" in block
+        ]
+        assert len(marked) == 1
+        breakpoint_indices.append(marked[0])
+
+    # Cold request caches through its newest block. Once rewrite is proven,
+    # all subsequent calls pin the same 30-block boundary instead of creating
+    # an ever-growing full write on each turn.
+    assert breakpoint_indices == [34, 29, 29]
+
+
 def test_cache_mode_skips_same_message_append_rewrite_to_preserve_stability() -> None:
     captured = {"calls": []}
     with _make_proxy_client() as client:
diff --git a/tests/test_proxy_byte_faithful_forwarding.py b/tests/test_proxy_byte_faithful_forwarding.py
index b02f4e654..eacfdc0bd 100644
--- a/tests/test_proxy_byte_faithful_forwarding.py
+++ b/tests/test_proxy_byte_faithful_forwarding.py
@@ -34,6 +34,7 @@ from headroom.proxy.body_forwarding import (
     BodyMutationTracker,
     OutboundBody,
     get_python_forwarder_mode,
+    outbound_body_is_client_bytes,
     prepare_outbound_body_bytes,
     select_outbound_body,
     serialize_body_canonical,
@@ -172,6 +173,195 @@ def test_prepare_outbound_mutated_uses_canonical() -> None:
     assert source == "canonical"
 
 
+@pytest.mark.parametrize("block_type", ["thinking", "redacted_thinking"])
+def test_signed_thinking_history_with_original_bytes_uses_passthrough(
+    block_type: str,
+) -> None:
+    body = {
+        "model": "claude-sonnet-4-5",
+        "messages": [
+            {"role": "user", "content": "Solve this"},
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": block_type,
+                        "thinking": "private reasoning",
+                        "signature": "sig123",
+                    },
+                    {"type": "text", "text": "The answer is 42."},
+                ],
+            },
+            {"role": "user", "content": "Continue"},
+        ],
+    }
+    original = json.dumps(body, indent=2).encode("utf-8")
+
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=original,
+        body_mutated=True,
+        forwarder_mode="byte_faithful",
+    )
+
+    assert outbound.source == "passthrough"
+    assert outbound.content == original
+
+
+def test_signed_thinking_history_without_original_bytes_uses_canonical() -> None:
+    body = {
+        "messages": [
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "thinking",
+                        "thinking": "private reasoning",
+                        "signature": "sig123",
+                    }
+                ],
+            }
+        ]
+    }
+
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=None,
+        body_mutated=True,
+        forwarder_mode="byte_faithful",
+    )
+
+    assert outbound.source == "canonical"
+    assert outbound.content == serialize_body_canonical(body)
+
+
+def test_signed_thinking_history_overrides_legacy_encoder() -> None:
+    body = {
+        "messages": [
+            {
+                "role": "assistant",
+                "content": [{"type": "thinking", "signature": "sig123"}],
+            }
+        ]
+    }
+    original = json.dumps(body, indent=2).encode("utf-8")
+
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=original,
+        body_mutated=True,
+        forwarder_mode="legacy_json_kwarg",
+    )
+
+    assert outbound == OutboundBody(content=original, source="passthrough", dropped_mutations=True)
+
+
+def test_signed_thinking_passthrough_reports_the_mutations_it_discarded() -> None:
+    """Passthrough silently winning over a mutated body is what hid #2952."""
+    body = {
+        "stream": False,
+        "messages": [
+            {
+                "role": "assistant",
+                "content": [{"type": "thinking", "signature": "sig123"}],
+            }
+        ],
+    }
+    original = json.dumps({**body, "stream": True}).encode("utf-8")
+
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=original,
+        body_mutated=True,
+        forwarder_mode="byte_faithful",
+        mutation_reasons=["ccr_streaming_retrieve_buffered_non_stream"],
+    )
+
+    assert outbound.source == "passthrough"
+    assert outbound.dropped_mutations is True
+    assert outbound.dropped_mutation_reasons == ("ccr_streaming_retrieve_buffered_non_stream",)
+
+
+def test_signed_thinking_passthrough_reports_nothing_when_body_unmutated() -> None:
+    body = {
+        "messages": [
+            {
+                "role": "assistant",
+                "content": [{"type": "thinking", "signature": "sig123"}],
+            }
+        ]
+    }
+    original = json.dumps(body).encode("utf-8")
+
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=original,
+        body_mutated=False,
+        forwarder_mode="byte_faithful",
+        mutation_reasons=["irrelevant"],
+    )
+
+    assert outbound.source == "passthrough"
+    assert outbound.dropped_mutations is False
+    assert outbound.dropped_mutation_reasons == ()
+
+
+def test_canonical_path_reports_no_dropped_mutations() -> None:
+    body = {"messages": [{"role": "user", "content": "hi"}]}
+
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=b'{"messages": []}',
+        body_mutated=True,
+        forwarder_mode="byte_faithful",
+        mutation_reasons=["compression"],
+    )
+
+    assert outbound.source == "canonical"
+    assert outbound.dropped_mutations is False
+    assert outbound.dropped_mutation_reasons == ()
+
+
+@pytest.mark.parametrize(
+    ("original_body_bytes", "expected"),
+    [(b'{"messages": []}', True), (None, False)],
+)
+def test_outbound_body_is_client_bytes_matches_selection(
+    original_body_bytes: bytes | None, expected: bool
+) -> None:
+    """Handlers gate on this before mutating a body for their own upstream call."""
+    body = {
+        "messages": [
+            {
+                "role": "assistant",
+                "content": [{"type": "thinking", "signature": "sig123"}],
+            }
+        ]
+    }
+
+    assert (
+        outbound_body_is_client_bytes(body=body, original_body_bytes=original_body_bytes)
+        is expected
+    )
+    outbound = select_outbound_body(
+        body=body,
+        original_body_bytes=original_body_bytes,
+        body_mutated=True,
+        forwarder_mode="byte_faithful",
+    )
+    assert (outbound.source == "passthrough") is expected
+
+
+def test_outbound_body_is_client_bytes_false_without_thinking_blocks() -> None:
+    assert (
+        outbound_body_is_client_bytes(
+            body={"messages": [{"role": "user", "content": "hi"}]},
+            original_body_bytes=b'{"messages": []}',
+        )
+        is False
+    )
+
+
 def test_prepare_outbound_no_original_bytes_uses_canonical() -> None:
     out, source = prepare_outbound_body_bytes(
         body={"a": 1},
diff --git a/tests/test_proxy_compress_endpoint.py b/tests/test_proxy_compress_endpoint.py
index 53aa74141..c6434e4ed 100644
--- a/tests/test_proxy_compress_endpoint.py
+++ b/tests/test_proxy_compress_endpoint.py
@@ -134,6 +134,45 @@ class TestCompressEndpointBasic:
         assert data["tokens_saved"] >= 0
         assert data["compression_ratio"] > 0
 
+    def test_response_ccr_hashes_extracts_only_retrievable_hashes(self):
+        """Embedded CCR markers are reported without unrelated transform metadata."""
+        from headroom.proxy.handlers.openai import _response_ccr_hashes
+
+        messages = [
+            {
+                "role": "tool",
+                "content": ("[100 rows compressed. Retrieve more: hash=abc123def4567890abc123de]"),
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "<<ccr:feedface00112233 10_rows_offloaded>>",
+                    },
+                    {
+                        "type": "text",
+                        "text": "Retrieve original: hash=ABC123DEF4567890ABC123DE",
+                    },
+                ],
+            },
+        ]
+
+        hashes = _response_ccr_hashes(
+            messages,
+            [
+                "deadbeef0000000000000000",
+                "<headroom:tool_digest sha256=1234567890abcdef>",
+                "stable_prefix_hash:feedface00112233",
+            ],
+        )
+
+        assert hashes == [
+            "deadbeef0000000000000000",
+            "abc123def4567890abc123de",
+            "feedface00112233",
+        ]
+
     def test_bypass_header_returns_uncompressed(self, client):
         """X-Headroom-Bypass header should skip compression."""
         messages = [
@@ -290,6 +329,38 @@ class TestCompressEndpointCompression:
         assert outcome.transforms_applied == ("test_transform",)
         assert outcome.total_latency_ms >= 0
 
+    def test_response_reports_embedded_ccr_hashes(self, client, monkeypatch):
+        """The endpoint reports a CCR marker even when the transform omitted its registry."""
+        proxy = client.app.state.proxy
+        ccr_hash = "abc123def4567890abc123de"
+        result = SimpleNamespace(
+            messages=[
+                {
+                    "role": "tool",
+                    "content": f"<<ccr:{ccr_hash} 10_rows_offloaded>>",
+                }
+            ],
+            tokens_before=12,
+            tokens_after=7,
+            transforms_applied=["test_transform"],
+            transforms_summary={"test_transform": 1},
+            markers_inserted=["<headroom:tool_digest sha256=1234567890abcdef>"],
+        )
+        monkeypatch.setattr(
+            proxy,
+            "_run_compression_in_executor",
+            AsyncMock(return_value=result),
+        )
+        monkeypatch.setattr(proxy, "_record_request_outcome", AsyncMock())
+
+        response = client.post(
+            "/v1/compress",
+            json={"messages": [{"role": "user", "content": "compress me"}], "model": "gpt-4"},
+        )
+
+        assert response.status_code == 200
+        assert response.json()["ccr_hashes"] == [ccr_hash]
+
     def test_compression_error_records_failed_request(self, client, monkeypatch):
         """A hard compression failure should increment failed metrics."""
         proxy = client.app.state.proxy
diff --git a/tests/test_proxy_copilot_auth_hooks.py b/tests/test_proxy_copilot_auth_hooks.py
index eb0eecd4a..7a37a82c7 100644
--- a/tests/test_proxy_copilot_auth_hooks.py
+++ b/tests/test_proxy_copilot_auth_hooks.py
@@ -52,11 +52,22 @@ def _load_handler_module(monkeypatch: pytest.MonkeyPatch, module_name: str, rela
     responses_mod = types.ModuleType("fastapi.responses")
 
     class Response:
-        def __init__(self, content=None, status_code: int = 200, headers=None, media_type=None):
+        def __init__(
+            self,
+            content=None,
+            status_code: int = 200,
+            headers=None,
+            media_type=None,
+            background=None,
+        ):
             self.content = content
             self.status_code = status_code
             self.headers = headers or {}
             self.media_type = media_type
+            # The streaming forwarder attaches a background task that releases the
+            # upstream stream when the body is never consumed (#2882); the double
+            # must accept and store it so the real StreamingResponse call works.
+            self.background = background
 
     class StreamingResponse(Response):
         pass
@@ -228,6 +239,9 @@ def test_streaming_response_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch
     assert sent_headers["Authorization"] == "Bearer upstream-token"
     assert sent_headers["content-type"] == "application/json"
     assert response.status_code == 200
+    # The Copilot auth hook and the #2882 upstream-stream cleanup coexist: the
+    # streaming response still carries its background release task.
+    assert response.background is not None
 
 
 def test_openai_chat_routes_copilot_requests_per_model(monkeypatch: pytest.MonkeyPatch) -> None:
diff --git a/tests/test_proxy_dashboard_stats_cache.py b/tests/test_proxy_dashboard_stats_cache.py
index 571042bb4..4ee95033c 100644
--- a/tests/test_proxy_dashboard_stats_cache.py
+++ b/tests/test_proxy_dashboard_stats_cache.py
@@ -176,7 +176,7 @@ def test_dashboard_uses_cached_stats_and_lazy_history_feed_polling() -> None:
     html = get_dashboard_html()
 
     assert "fetch('/stats?cached=1')" in html
-    assert "statsPollMs: 15000" in html
+    assert "statsPollMs: 5000" in html
     assert "viewRefreshers:" in html
     assert "this.refreshActiveView(force)" in html
     assert "version: 'loading'" in html
diff --git a/tests/test_proxy_debug_endpoints.py b/tests/test_proxy_debug_endpoints.py
index 6cb8e4017..fe1fdd239 100644
--- a/tests/test_proxy_debug_endpoints.py
+++ b/tests/test_proxy_debug_endpoints.py
@@ -35,7 +35,11 @@ from headroom.proxy.ws_session_registry import (
 
 
 @pytest.fixture
-def client():
+def client(monkeypatch):
+    # Debug endpoint tests must not depend on live upstream network access.
+    # Dedicated health-check tests cover both successful and failed upstream
+    # probes in tests/test_proxy_healthchecks.py.
+    monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")
     config = ProxyConfig(
         optimize=False,
         cache_enabled=False,
diff --git a/tests/test_proxy_eager_preload_bind.py b/tests/test_proxy_eager_preload_bind.py
index 6f01a6981..a5923ca6a 100644
--- a/tests/test_proxy_eager_preload_bind.py
+++ b/tests/test_proxy_eager_preload_bind.py
@@ -91,8 +91,15 @@ def test_eager_preload_dedupes_and_swallows_failures():
 
     eager_status, statuses = proxy._eager_preload_transforms()
 
-    assert eager_status == {"shared": "enabled", "kompress": "enabled"}
+    # Keys the preload contributes itself rather than collecting from a
+    # transform, so this assertion stays about dedupe/swallowing.
+    non_transform_keys = {"litellm"}
+    assert {k: v for k, v in eager_status.items() if k not in non_transform_keys} == {
+        "shared": "enabled",
+        "kompress": "enabled",
+    }
     assert statuses == [{"shared": "enabled"}, {"kompress": "enabled"}]
+    assert eager_status["litellm"] in {"ready", "not installed", "skipped"}
 
 
 async def test_startup_binds_despite_hung_preload(monkeypatch):
diff --git a/tests/test_proxy_gemini_integration.py b/tests/test_proxy_gemini_integration.py
index 0aba8d09d..4582a64dd 100644
--- a/tests/test_proxy_gemini_integration.py
+++ b/tests/test_proxy_gemini_integration.py
@@ -23,6 +23,7 @@ pytest.importorskip("httpx")
 from fastapi.testclient import TestClient  # noqa: E402
 
 from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+from tests._gemini_live import skip_if_gemini_quota_exhausted  # noqa: E402
 
 GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai"
 
@@ -63,6 +64,7 @@ class TestGeminiChatCompletions:
                 ],
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -93,6 +95,7 @@ class TestGeminiChatCompletions:
                 ],
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -110,6 +113,7 @@ class TestGeminiChatCompletions:
                 "messages": [{"role": "user", "content": "Count from 1 to 3."}],
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
 
         # Parse SSE stream
@@ -154,6 +158,7 @@ class TestGeminiChatCompletions:
                 "tool_choice": "auto",
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -182,6 +187,7 @@ class TestGeminiChatCompletions:
                 "response_format": {"type": "json_object"},
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -198,6 +204,7 @@ class TestGeminiModels:
     def test_list_models(self, gemini_client, api_key):
         """Can list available models."""
         response = gemini_client.get("/v1/models", headers={"Authorization": f"Bearer {api_key}"})
+        skip_if_gemini_quota_exhausted(response)
         # This goes through passthrough handler
         assert response.status_code == 200
         data = response.json()
@@ -211,11 +218,12 @@ class TestProxyStats:
     def test_stats_track_requests(self, gemini_client, api_key):
         """Proxy stats track Gemini requests."""
         # Make a request
-        gemini_client.post(
+        response = gemini_client.post(
             "/v1/chat/completions",
             headers={"Authorization": f"Bearer {api_key}"},
             json={"model": "gemini-2.0-flash", "messages": [{"role": "user", "content": "Hi"}]},
         )
+        skip_if_gemini_quota_exhausted(response)
 
         # Check stats
         stats_response = gemini_client.get("/stats")
diff --git a/tests/test_proxy_gemini_native_integration.py b/tests/test_proxy_gemini_native_integration.py
index ca05a56af..270c335ff 100644
--- a/tests/test_proxy_gemini_native_integration.py
+++ b/tests/test_proxy_gemini_native_integration.py
@@ -23,6 +23,7 @@ pytest.importorskip("httpx")
 from fastapi.testclient import TestClient  # noqa: E402
 
 from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+from tests._gemini_live import skip_if_gemini_quota_exhausted  # noqa: E402
 
 
 @pytest.fixture
@@ -54,6 +55,7 @@ class TestGeminiNativeGenerateContent:
             f"/v1beta/models/gemini-2.0-flash:generateContent?key={api_key}",
             json={"contents": [{"parts": [{"text": "What is 2+2? Reply with just the number."}]}]},
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -78,6 +80,7 @@ class TestGeminiNativeGenerateContent:
                 "systemInstruction": {"parts": [{"text": "Always respond with exactly one word."}]},
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
         text = data["candidates"][0]["content"]["parts"][0]["text"]
@@ -96,6 +99,7 @@ class TestGeminiNativeGenerateContent:
                 ]
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
         text = data["candidates"][0]["content"]["parts"][0]["text"].lower()
@@ -126,6 +130,7 @@ class TestGeminiNativeGenerateContent:
                 ],
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -150,6 +155,7 @@ class TestGeminiNativeGenerateContent:
                 "generationConfig": {"maxOutputTokens": 50, "temperature": 0.1},
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
         # Response should be limited by maxOutputTokens
@@ -178,6 +184,7 @@ class TestGeminiNativeCompression:
                 ]
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
         text = data["candidates"][0]["content"]["parts"][0]["text"]
@@ -204,6 +211,7 @@ class TestGeminiNativeCompression:
                 ]
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         # The request should succeed - user messages are protected from compression
 
@@ -214,10 +222,11 @@ class TestGeminiNativeStats:
     def test_stats_track_gemini_provider(self, gemini_native_client, api_key):
         """Stats show requests under 'gemini' provider."""
         # Make a request
-        gemini_native_client.post(
+        response = gemini_native_client.post(
             f"/v1beta/models/gemini-2.0-flash:generateContent?key={api_key}",
             json={"contents": [{"parts": [{"text": "Hi"}]}]},
         )
+        skip_if_gemini_quota_exhausted(response)
 
         stats = gemini_native_client.get("/stats").json()
         assert "gemini" in stats["requests"]["by_provider"]
@@ -225,10 +234,11 @@ class TestGeminiNativeStats:
 
     def test_stats_track_model(self, gemini_native_client, api_key):
         """Stats track the specific model used."""
-        gemini_native_client.post(
+        response = gemini_native_client.post(
             f"/v1beta/models/gemini-2.0-flash:generateContent?key={api_key}",
             json={"contents": [{"parts": [{"text": "Hi"}]}]},
         )
+        skip_if_gemini_quota_exhausted(response)
 
         stats = gemini_native_client.get("/stats").json()
         assert "gemini-2.0-flash" in stats["requests"]["by_model"]
@@ -258,6 +268,7 @@ class TestGeminiNativeErrorHandling:
         response = gemini_native_client.post(
             f"/v1beta/models/gemini-2.0-flash:generateContent?key={api_key}", json={"contents": []}
         )
+        skip_if_gemini_quota_exhausted(response)
         # Should either return error or handle gracefully
         assert response.status_code in [200, 400]
 
@@ -272,6 +283,7 @@ class TestGeminiNativeHeaderAuth:
             headers={"x-goog-api-key": api_key},
             json={"contents": [{"parts": [{"text": "Hi"}]}]},
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
 
 
@@ -284,6 +296,7 @@ class TestGeminiNativeCountTokens:
             f"/v1beta/models/gemini-2.0-flash:countTokens?key={api_key}",
             json={"contents": [{"parts": [{"text": "Hello, world!"}]}]},
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -301,6 +314,7 @@ class TestGeminiNativeCountTokens:
                 "systemInstruction": {"parts": [{"text": "You are a helpful assistant."}]},
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         # Note: systemInstruction may not be supported by countTokens in all versions
         assert response.status_code in [200, 400]
         if response.status_code == 200:
@@ -332,6 +346,7 @@ class TestGeminiNativeCountTokens:
                 ]
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
 
@@ -357,6 +372,7 @@ class TestGeminiNativeCountTokens:
                 ]
             },
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
         assert "totalTokens" in data
@@ -369,6 +385,7 @@ class TestGeminiNativeCountTokens:
             headers={"x-goog-api-key": api_key},
             json={"contents": [{"parts": [{"text": "Hello"}]}]},
         )
+        skip_if_gemini_quota_exhausted(response)
         assert response.status_code == 200
         data = response.json()
         assert "totalTokens" in data
diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.py
index 7845396b0..a11e437b3 100644
--- a/tests/test_proxy_handler_helpers.py
+++ b/tests/test_proxy_handler_helpers.py
@@ -17,7 +17,10 @@ from headroom.proxy.handlers.openai import (
     _passthrough_usage_from_json,
     _prefers_http1_passthrough,
 )
-from headroom.proxy.helpers import _headroom_bypass_enabled
+from headroom.proxy.helpers import (
+    _headroom_bypass_enabled,
+    relocate_system_messages_to_top_level,
+)
 from headroom.proxy.server import HeadroomProxy
 
 
@@ -268,6 +271,46 @@ def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:
     assert changed == 1
 
 
+def test_relocate_system_messages_moves_stray_system_into_top_level() -> None:
+    # Issue #765: compression relocated the harness system block into
+    # messages[0] as a role="system" entry, which Anthropic rejects with a 400.
+    # The forwarder guard must move it back to the top-level `system` parameter.
+    messages = [
+        {"role": "system", "content": "You are a harness."},
+        {"role": "user", "content": "hi"},
+    ]
+    clean, system, changed = relocate_system_messages_to_top_level(messages, None)
+
+    assert changed is True
+    # No role="system" entry may survive in messages[] — that is the wire-contract violation.
+    assert all(m.get("role") != "system" for m in clean)
+    assert clean == [{"role": "user", "content": "hi"}]
+    # The relocated content lands in the top-level system parameter.
+    assert system == [{"type": "text", "text": "You are a harness."}]
+
+
+def test_relocate_system_messages_appends_to_existing_system() -> None:
+    messages = [
+        {"role": "system", "content": [{"type": "text", "text": "B"}]},
+        {"role": "user", "content": "hi"},
+    ]
+    clean, system, changed = relocate_system_messages_to_top_level(messages, "A")
+
+    assert changed is True
+    assert clean == [{"role": "user", "content": "hi"}]
+    # Existing system first, relocated content after — wire order preserved.
+    assert system == [{"type": "text", "text": "A"}, {"type": "text", "text": "B"}]
+
+
+def test_relocate_system_messages_noop_without_system_entry() -> None:
+    messages = [{"role": "user", "content": "hi"}]
+    clean, system, changed = relocate_system_messages_to_top_level(messages, "A")
+
+    assert changed is False
+    assert clean is messages
+    assert system == "A"
+
+
 def test_headroom_bypass_helper_is_transport_neutral() -> None:
     assert _headroom_bypass_enabled({"x-headroom-bypass": "true"}) is True
     assert _headroom_bypass_enabled({"x-headroom-bypass": " TRUE "}) is True
@@ -896,7 +939,8 @@ def test_resolve_ccr_workspace_explicit_project_id_wins() -> None:
     request = _fake_request({"x-headroom-project-id": "my-cool-project"})
     body = {}
     key, label = AnthropicHandlerMixin._resolve_ccr_workspace(request, body)
-    assert key == "my-cool-project"
+    assert key.startswith("my-cool-project-")
+    assert len(key.split("-")[-1]) == 16
     assert label == "my-cool-project"
 
 
diff --git a/tests/test_proxy_handlers_batch.py b/tests/test_proxy_handlers_batch.py
index 79c07182e..53e823fcf 100644
--- a/tests/test_proxy_handlers_batch.py
+++ b/tests/test_proxy_handlers_batch.py
@@ -6,7 +6,14 @@ from types import SimpleNamespace
 
 import pytest
 
+from headroom.cache.compression_store import (
+    CompressionEntry,
+    get_compression_store,
+    reset_compression_store,
+)
+from headroom.ccr import response_handler as response_handler_module
 from headroom.proxy.handlers import batch as batch_module
+from headroom.proxy.handlers import gemini as gemini_module
 from headroom.proxy.handlers.gemini import GeminiHandlerMixin
 
 
@@ -148,11 +155,453 @@ class FakeRequest:
         self.headers = headers or {}
         self.method = method
         self.url = SimpleNamespace(path=path, query=query)
+        self.query_params = {}
 
     async def body(self) -> bytes:
         return self._body
 
 
+class NativeGeminiHandler(DummyBatchHandler):
+    def __init__(self, responses: list[FakeResponse]) -> None:
+        super().__init__()
+        self.config.optimize = True
+        self.config.ccr_inject_tool = True
+        self.config.ccr_inject_system_instructions = False
+        self.memory_handler = None
+        self.rate_limiter = None
+        self.usage_reporter = None
+        self.responses = iter(responses)
+        self.sent_bodies: list[dict] = []
+        from headroom.ccr.response_handler import CCRResponseHandler
+
+        self.ccr_response_handler = CCRResponseHandler()
+        self.openai_pipeline = SimpleNamespace(
+            apply=lambda **kwargs: SimpleNamespace(
+                messages=[
+                    {
+                        "role": "user",
+                        "content": "compressed [100 items compressed to 1. Retrieve more: hash=aaaaaaaaaaaaaaaaaaaaaaaa]",
+                    }
+                ],
+                timing={},
+                tokens_before=10,
+                tokens_after=5,
+                transforms_applied=[],
+                waste_signals=SimpleNamespace(to_dict=lambda: {}),
+            )
+        )
+
+    def _gemini_contents_to_messages(
+        self, contents, system_instruction=None, *, include_function_responses=False
+    ):  # noqa: ANN001, ANN201
+        return GeminiHandlerMixin._gemini_contents_to_messages(
+            self,
+            contents,
+            system_instruction,
+            include_function_responses=include_function_responses,
+        )
+
+    def _messages_to_gemini_contents(self, messages):  # noqa: ANN001, ANN201
+        return GeminiHandlerMixin._messages_to_gemini_contents(self, messages)
+
+    async def _retry_request(self, method, url, headers, body, **kwargs):  # noqa: ANN001, ANN201
+        self.sent_bodies.append(body)
+        return next(self.responses)
+
+    async def _run_compression_in_executor(self, fn, *, timeout):  # noqa: ANN001, ANN201
+        return fn()
+
+
+def install_native_gemini_compression(monkeypatch: pytest.MonkeyPatch) -> None:
+    class Decision:
+        should_compress = True
+        passthrough_reason = ""
+
+        def apply_to_tags(self, tags) -> None:  # noqa: ANN001
+            return None
+
+    monkeypatch.setattr(gemini_module.CompressionDecision, "decide", lambda **kwargs: Decision())
+
+
+def native_gemini_request(tools=None) -> dict:  # noqa: ANN001
+    return {
+        "contents": [{"role": "user", "parts": [{"text": "compressed input"}]}],
+        "generationConfig": {"temperature": 0.2},
+        **({"tools": tools} if tools is not None else {}),
+    }
+
+
+def native_ccr_response() -> FakeResponse:
+    return FakeResponse(
+        json_data={
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "functionCall": {
+                                    "name": "headroom_retrieve",
+                                    "id": "call-1",
+                                    "args": {"hash": "aaaaaaaaaaaaaaaaaaaaaaaa"},
+                                }
+                            }
+                        ],
+                    }
+                }
+            ],
+            "usageMetadata": {"promptTokenCount": 5},
+        }
+    )
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_continuation(monkeypatch: pytest.MonkeyPatch) -> None:
+    install_native_gemini_compression(monkeypatch)
+    from headroom.ccr.response_handler import CCRToolResult
+
+    final = FakeResponse(
+        json_data={
+            "candidates": [{"content": {"role": "model", "parts": [{"text": "final answer"}]}}]
+        }
+    )
+    handler = NativeGeminiHandler([native_ccr_response(), final])
+    handler.ccr_response_handler._execute_retrieval = lambda call: CCRToolResult(
+        call.tool_call_id,
+        json.dumps({"hash": call.hash_key, "original_content": [{"type": "code"}]}),
+        True,
+        1,
+        "headroom_retrieve",
+    )
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json", "x-goog-api-key": "secret"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 200
+    assert (
+        json.loads(response.body)["candidates"][0]["content"]["parts"][0]["text"] == "final answer"
+    ), response.body
+    assert len(handler.sent_bodies) == 2
+    continuation = handler.sent_bodies[1]["contents"]
+    assert continuation[-2]["role"] == "model"
+    assert continuation[-2]["parts"][0]["functionCall"]["name"] == "headroom_retrieve"
+    assert continuation[-1]["role"] == "user"
+    assert continuation[-1]["parts"][0]["functionResponse"]["name"] == "headroom_retrieve"
+    assert continuation[-1]["parts"][0]["functionResponse"]["id"] == "call-1"
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_tools(monkeypatch: pytest.MonkeyPatch) -> None:
+    install_native_gemini_compression(monkeypatch)
+    # verify_ownership() (issue #2836) requires the marker's hash to be a
+    # real store entry; NativeGeminiHandler's mocked pipeline hand-types
+    # "hash=aaaa...aaaa" rather than compressing through the real store.
+    reset_compression_store()
+    get_compression_store().store(
+        original="original content",
+        compressed="compressed [100 items compressed to 1]",
+        explicit_hash="aaaaaaaaaaaaaaaaaaaaaaaa",
+    )
+    handler = NativeGeminiHandler(
+        [FakeResponse(json_data={"candidates": [{"content": {"parts": [{"text": "answer"}]}}]})]
+    )
+    tools = [
+        {"functionDeclarations": [{"name": "client_tool"}]},
+        {"functionDeclarations": [{"name": "second_tool"}]},
+        {"googleSearch": {}},
+        {"codeExecution": {}},
+    ]
+
+    await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request(tools)),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    forwarded_tools = handler.sent_bodies[0]["tools"]
+    assert forwarded_tools[2:] == tools[2:]
+    declarations = forwarded_tools[0]["functionDeclarations"]
+    assert {item["name"] for item in declarations} == {"client_tool", "headroom_retrieve"}
+    assert forwarded_tools[1]["functionDeclarations"] == [{"name": "second_tool"}]
+    reset_compression_store()
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_does_not_duplicate_existing_declaration(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_native_gemini_compression(monkeypatch)
+    tools = [
+        {"functionDeclarations": [{"name": "client_tool"}]},
+        {"functionDeclarations": [{"name": "headroom_retrieve"}]},
+    ]
+    handler = NativeGeminiHandler(
+        [FakeResponse(json_data={"candidates": [{"content": {"parts": [{"text": "answer"}]}}]})]
+    )
+
+    await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request(tools)),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    names = [
+        declaration["name"]
+        for tool in handler.sent_bodies[0]["tools"]
+        for declaration in tool.get("functionDeclarations", [])
+    ]
+    assert names.count("headroom_retrieve") == 1
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_does_not_inject_into_streaming_request(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_native_gemini_compression(monkeypatch)
+    handler = NativeGeminiHandler([FakeResponse()])
+    captured: dict[str, object] = {}
+
+    async def fake_stream(*args, **kwargs):  # noqa: ANN002, ANN003, ANN202
+        captured["body"] = args[2]
+        return FakeResponse()
+
+    monkeypatch.setattr(handler, "_stream_response", fake_stream, raising=False)
+    tools = [{"functionDeclarations": [{"name": "client_tool"}]}]
+    await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request(tools)),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:streamGenerateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    streamed_tools = captured["body"]["tools"]  # type: ignore[index]
+    names = [
+        declaration["name"]
+        for tool in streamed_tools
+        for declaration in tool.get("functionDeclarations", [])
+    ]
+    assert names == ["client_tool"]
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_mixed(monkeypatch: pytest.MonkeyPatch) -> None:
+    install_native_gemini_compression(monkeypatch)
+    response_json = {
+        "candidates": [
+            {
+                "content": {
+                    "parts": [
+                        {
+                            "functionCall": {
+                                "name": "headroom_retrieve",
+                                "args": {"hash": "aaaaaaaaaaaaaaaaaaaaaaaa"},
+                            }
+                        },
+                        {"functionCall": {"name": "client_tool", "args": {}}},
+                    ]
+                }
+            }
+        ]
+    }
+    handler = NativeGeminiHandler([FakeResponse(json_data=response_json)])
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 200
+    assert len(handler.sent_bodies) == 1
+    assert json.loads(response.body) == response_json
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_non_ccr_function_call_is_not_intercepted(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_native_gemini_compression(monkeypatch)
+    response_json = {
+        "candidates": [
+            {"content": {"parts": [{"functionCall": {"name": "client_tool", "args": {}}}]}}
+        ]
+    }
+    handler = NativeGeminiHandler([FakeResponse(json_data=response_json)])
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 200
+    assert len(handler.sent_bodies) == 1
+    assert response.body == b"{}"
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_continuation_error_preserves_upstream_response(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_native_gemini_compression(monkeypatch)
+    handler = NativeGeminiHandler(
+        [
+            native_ccr_response(),
+            FakeResponse(status_code=503, content=b"busy", headers={"retry-after": "2"}),
+        ]
+    )
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 503
+    assert response.body == b"busy"
+    assert response.headers["retry-after"] == "2"
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_continuation_non_json_preserves_upstream_response(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_native_gemini_compression(monkeypatch)
+    handler = NativeGeminiHandler(
+        [native_ccr_response(), FakeResponse(status_code=200, content=b"upstream")]
+    )
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 200
+    assert response.body == b"upstream"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "original_content",
+    [[{"type": "code", "text": "print('x')"}], "plain text", {"key": "value"}, 42],
+    ids=["code-aware-array", "kompress-text", "mcp-object", "mcp-scalar"],
+)
+async def test_gemini_native_ccr_uses_real_retrieval_result_shape(
+    monkeypatch: pytest.MonkeyPatch, original_content
+) -> None:  # noqa: ANN001
+    install_native_gemini_compression(monkeypatch)
+    entry = CompressionEntry(
+        hash="a" * 24,
+        original_content=json.dumps(original_content),
+        compressed_content="compressed",
+        original_tokens=10,
+        compressed_tokens=2,
+        original_item_count=1,
+        compressed_item_count=1,
+        tool_name="headroom_retrieve",
+        tool_call_id="headroom_retrieve",
+        query_context=None,
+        created_at=0,
+    )
+
+    class Store:
+        def get_entry_status(self, hash_key, clean_expired=True):  # noqa: ANN001, ARG002
+            return {"status": "available", "default_ttl_seconds": 1800}
+
+        def retrieve(self, hash_key):  # noqa: ANN001, ARG002
+            return entry
+
+    monkeypatch.setattr(response_handler_module, "get_compression_store", lambda: Store())
+    handler = NativeGeminiHandler(
+        [
+            native_ccr_response(),
+            FakeResponse(json_data={"candidates": [{"content": {"parts": [{"text": "done"}]}}]}),
+        ]
+    )
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 200
+    function_response = handler.sent_bodies[1]["contents"][-1]["parts"][0]["functionResponse"]
+    assert function_response["response"]["original_content"] == json.dumps(original_content)
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_preserves_non_ccr_response(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_native_gemini_compression(monkeypatch)
+    handler = NativeGeminiHandler([FakeResponse(status_code=503, content=b"busy")])
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 503
+    assert response.body == b"busy"
+
+
+@pytest.mark.asyncio
+async def test_gemini_native_ccr_residual(monkeypatch: pytest.MonkeyPatch) -> None:
+    install_native_gemini_compression(monkeypatch)
+    from headroom.ccr.response_handler import CCRToolResult
+
+    handler = NativeGeminiHandler([native_ccr_response()] * 4)
+    handler.ccr_response_handler._execute_retrieval = lambda call: CCRToolResult(
+        "headroom_retrieve", "still unresolved", True, 0
+    )
+
+    response = await handler.handle_gemini_generate_content(
+        FakeRequest(
+            json.dumps(native_gemini_request()),
+            headers={"content-type": "application/json"},
+            path="/v1beta/models/gemini-2.5-flash:generateContent",
+        ),
+        "gemini-2.5-flash",
+    )
+
+    assert response.status_code == 502
+
+
 def install_batch_support_modules(
     monkeypatch: pytest.MonkeyPatch,
     *,
@@ -216,6 +665,40 @@ async def test_compress_batch_jsonl_without_optimization_handles_invalid_lines(
     }
 
 
+@pytest.mark.asyncio
+async def test_compress_batch_jsonl_handles_non_object_lines(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # A JSONL line that is valid JSON but not a request object (array/string/
+    # null), or a request whose `body` isn't a dict, must pass through instead
+    # of crashing the whole batch (`.get` on a non-dict raises AttributeError,
+    # which the JSONDecodeError guard does not catch).
+    install_batch_support_modules(monkeypatch, tokenizer_count=12)
+    handler = DummyBatchHandler()
+    content = "\n".join(
+        [
+            json.dumps(
+                {"body": {"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}}
+            ),
+            json.dumps([1, 2, 3]),
+            json.dumps("hello"),
+            "null",
+            json.dumps({"body": "not-a-dict"}),
+        ]
+    )
+
+    lines, stats = await handler._compress_batch_jsonl(content, "req-1")
+
+    assert len(lines) == 5
+    assert json.loads(lines[1]) == [1, 2, 3]
+    assert json.loads(lines[2]) == "hello"
+    assert json.loads(lines[3]) is None
+    assert json.loads(lines[4]) == {"body": "not-a-dict"}
+    assert stats["total_requests"] == 5
+    # None of these are JSON decode errors, so the error counter stays at 0.
+    assert stats["errors"] == 0
+
+
 @pytest.mark.asyncio
 async def test_compress_batch_jsonl_uses_pipeline_and_ccr_injection(
     monkeypatch: pytest.MonkeyPatch,
diff --git a/tests/test_proxy_health.py b/tests/test_proxy_health.py
index efdad4cc1..b45cb42ad 100644
--- a/tests/test_proxy_health.py
+++ b/tests/test_proxy_health.py
@@ -69,7 +69,8 @@ def test_readyz_excludes_kompress_from_aggregate_readiness(monkeypatch):
     assert payload["checks"]["kompress"] == {
         "enabled": True,
         "ready": False,
-        "status": "unhealthy",
+        "status": "degraded",
+        "optional": True,
         "backend": None,
     }
 
@@ -85,6 +86,7 @@ def test_readyz_promotes_deferred_kompress_after_runtime_load(monkeypatch):
         "enabled": True,
         "ready": True,
         "status": "healthy",
+        "optional": True,
         "backend": "onnx",
     }
     # The promotion must also clear the startup marker, otherwise the slot
@@ -110,6 +112,7 @@ def test_readyz_promotes_kompress_from_module_cache(monkeypatch, attached):
         "enabled": True,
         "ready": True,
         "status": "healthy",
+        "optional": True,
         "backend": "onnx",
     }
     assert proxy.warmup.kompress.handle is model
@@ -141,7 +144,8 @@ def test_readyz_keeps_pending_kompress_unloaded(monkeypatch):
     assert payload["checks"]["kompress"] == {
         "enabled": True,
         "ready": False,
-        "status": "unhealthy",
+        "status": "degraded",
+        "optional": True,
         "backend": None,
     }
     assert compressor.calls == ["is_ready"]
@@ -181,6 +185,7 @@ def test_readyz_disabled_kompress_skips_inspection(monkeypatch):
         "enabled": False,
         "ready": True,
         "status": "disabled",
+        "optional": True,
         "backend": None,
     }
     assert compressor.calls == []
@@ -202,6 +207,7 @@ def test_readyz_per_provider_kompress_override_reenables_health(monkeypatch):
         "enabled": True,
         "ready": True,
         "status": "healthy",
+        "optional": True,
         "backend": "onnx",
     }
     assert compressor.calls == ["is_ready", "ready_backend"]
@@ -222,7 +228,8 @@ def test_readyz_never_calls_lazy_kompress_getters(monkeypatch):
     assert payload["checks"]["kompress"] == {
         "enabled": True,
         "ready": False,
-        "status": "unhealthy",
+        "status": "degraded",
+        "optional": True,
         "backend": None,
     }
 
@@ -234,37 +241,73 @@ def test_readyz_never_calls_lazy_kompress_getters(monkeypatch):
             "null",
             None,
             False,
-            {"enabled": True, "ready": False, "status": "unhealthy", "backend": None},
+            {
+                "enabled": True,
+                "ready": False,
+                "status": "degraded",
+                "optional": True,
+                "backend": None,
+            },
         ),
         (
             "null",
             _ReadyCompressor(),
             False,
-            {"enabled": True, "ready": True, "status": "healthy", "backend": "onnx"},
+            {
+                "enabled": True,
+                "ready": True,
+                "status": "healthy",
+                "optional": True,
+                "backend": "onnx",
+            },
         ),
         (
             "null",
             _ReadyCompressor(backend="remote"),
             False,
-            {"enabled": True, "ready": True, "status": "healthy", "backend": "remote"},
+            {
+                "enabled": True,
+                "ready": True,
+                "status": "healthy",
+                "optional": True,
+                "backend": "remote",
+            },
         ),
         (
             "error",
             _ReadyCompressor(),
             False,
-            {"enabled": True, "ready": True, "status": "healthy", "backend": "onnx"},
+            {
+                "enabled": True,
+                "ready": True,
+                "status": "healthy",
+                "optional": True,
+                "backend": "onnx",
+            },
         ),
         (
             "loaded",
             _ReadyCompressor(),
             False,
-            {"enabled": True, "ready": True, "status": "healthy", "backend": "existing"},
+            {
+                "enabled": True,
+                "ready": True,
+                "status": "healthy",
+                "optional": True,
+                "backend": "existing",
+            },
         ),
         (
             "null",
             _ReadyCompressor(),
             True,
-            {"enabled": False, "ready": True, "status": "disabled", "backend": None},
+            {
+                "enabled": False,
+                "ready": True,
+                "status": "disabled",
+                "optional": True,
+                "backend": None,
+            },
         ),
     ],
 )
diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.py
index 62713af86..5e9a1c9cb 100644
--- a/tests/test_proxy_loopback_gating.py
+++ b/tests/test_proxy_loopback_gating.py
@@ -22,6 +22,14 @@ from headroom.proxy.server import ProxyConfig, create_app
 GATED = [
     ("get", "/transformations/feed"),
     ("post", "/cache/clear"),
+    ("get", "/v1/telemetry"),
+    ("get", "/v1/telemetry/export"),
+    ("post", "/v1/telemetry/import"),
+    ("get", "/v1/telemetry/tools"),
+    ("get", "/v1/telemetry/tools/example"),
+    ("get", "/v1/toin/stats"),
+    ("get", "/v1/toin/patterns"),
+    ("get", "/v1/toin/pattern/example"),
 ]
 
 
@@ -71,8 +79,44 @@ def test_non_loopback_caller_gets_404(method: str, path: str) -> None:
 @pytest.mark.parametrize("method,path", GATED)
 def test_loopback_caller_allowed(method: str, path: str) -> None:
     client = _loopback_client()
-    resp = client.request(method, path)
-    assert resp.status_code == 200, resp.text
+    resp = client.request(method, path, json={} if method == "post" else None)
+    # Detail routes legitimately return 404 when their test key is absent;
+    # the companion non-loopback test proves the guard itself.
+    assert resp.status_code in {200, 404, 422}, resp.text
+
+
+def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.MonkeyPatch) -> None:
+    class FakeTOIN:
+        def export_patterns(self):
+            return {
+                "patterns": {
+                    "unknown|unknown|abc123": {
+                        "sample_size": 10,
+                        "total_compressions": 8,
+                        "total_retrievals": 2,
+                        "retrieval_rate": 0.25,
+                        "confidence": 0.4,
+                        "skip_compression_recommended": False,
+                        "optimal_max_items": 20,
+                        "query_pattern_frequency": {"secret prompt": 1},
+                        "common_query_patterns": ["secret prompt"],
+                        "field_semantics": {"secret": "value"},
+                    }
+                }
+            }
+
+    monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: FakeTOIN())
+    response = _loopback_client().get("/v1/toin/pattern/unknown")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "compressions": 8,
+        "retrievals": 2,
+        "retrieval_rate": 0.25,
+        "confidence": 0.4,
+        "skip_recommended": False,
+        "optimal_max_items": 20,
+    }
 
 
 # CCR data endpoints — cached session content, gated to 404 off-loopback (#1227).
@@ -156,6 +200,104 @@ def test_ccr_retrieve_hash_route_blocks_valid_hash_for_non_loopback() -> None:
         reset_compression_store()
 
 
+SETTINGS_GATED = [
+    ("get", "/settings/schema"),
+    ("get", "/settings"),
+    ("get", "/dashboard/settings"),
+]
+
+
+@pytest.mark.parametrize("method,path", SETTINGS_GATED)
+def test_settings_non_loopback_gets_404_without_trusted_cidr(method: str, path: str) -> None:
+    resp = TestClient(_make_app()).request(method, path)
+    assert resp.status_code == 404, resp.text
+
+
+@pytest.mark.parametrize("method,path", SETTINGS_GATED)
+def test_settings_loopback_caller_allowed(method: str, path: str) -> None:
+    resp = _loopback_client().request(method, path)
+    assert resp.status_code == 200, resp.text
+
+
+@pytest.mark.parametrize("method,path", SETTINGS_GATED)
+def test_settings_trusted_gateway_dashboard_client_allowed(
+    monkeypatch: pytest.MonkeyPatch, method: str, path: str
+) -> None:
+    """Settings routes must follow the same trust chain as /stats so the
+    dashboard works behind a reverse-proxy/gateway (#2466)."""
+    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
+    client = TestClient(
+        _make_app(),
+        base_url="http://100.82.0.2:8787",
+        client=("100.90.0.5", 12345),
+    )
+    resp = client.request(method, path)
+    assert resp.status_code == 200, resp.text
+
+
+def test_settings_trusted_gateway_cidr_mismatch_still_404s(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
+    client = TestClient(
+        _make_app(),
+        base_url="http://100.82.0.2:8787",
+        client=("100.90.0.9", 12345),
+    )
+    assert client.get("/settings").status_code == 404
+
+
+@pytest.mark.parametrize(
+    "path,body",
+    [("/settings", {"values": {}}), ("/settings/apply", None)],
+)
+def test_settings_post_trusted_gateway_client_same_origin_allowed(
+    monkeypatch: pytest.MonkeyPatch, path: str, body: dict | None
+) -> None:
+    """Regression for #2491 review: a trusted-gateway dashboard client's real
+    same-origin browser POST (Origin matching this Host) must not be rejected
+    by the loopback-only same-origin guard."""
+    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
+    client = TestClient(
+        _make_app(),
+        base_url="http://100.82.0.2:8787",
+        client=("100.90.0.5", 12345),
+    )
+    resp = client.post(path, json=body, headers={"origin": "http://100.82.0.2:8787"})
+    assert resp.status_code != 403, resp.text
+
+
+@pytest.mark.parametrize(
+    "path,body",
+    [("/settings", {"values": {}}), ("/settings/apply", None)],
+)
+def test_settings_post_trusted_gateway_client_mismatched_origin_rejected(
+    monkeypatch: pytest.MonkeyPatch, path: str, body: dict | None
+) -> None:
+    """A trusted-gateway peer with a foreign Origin is still CSRF-rejected.
+
+    The mismatched Origin also fails the first (loopback-or-trusted-client)
+    gate's own same-origin check, so this surfaces as 404, not 403 -- either
+    way the write must not go through."""
+    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
+    client = TestClient(
+        _make_app(),
+        base_url="http://100.82.0.2:8787",
+        client=("100.90.0.5", 12345),
+    )
+    resp = client.post(path, json=body, headers={"origin": "http://attacker.example"})
+    assert resp.status_code in (403, 404), resp.text
+
+
+def test_settings_post_loopback_null_origin_still_rejected() -> None:
+    """Loopback callers keep the stricter loopback-only origin check: a
+    sandboxed-iframe/file:// "null" Origin must still 403, unaffected by the
+    trusted-dashboard-client carve-out."""
+    client = _loopback_client()
+    resp = client.post("/settings", json={"values": {}}, headers={"origin": "null"})
+    assert resp.status_code == 403, resp.text
+
+
 def test_dns_rebinding_host_header_rejected() -> None:
     # Loopback peer IP but an attacker-controlled Host header (the DNS-rebinding
     # shape) must still be rejected by the second gate.
diff --git a/tests/test_proxy_openai.py b/tests/test_proxy_openai.py
new file mode 100644
index 000000000..f705746ad
--- /dev/null
+++ b/tests/test_proxy_openai.py
@@ -0,0 +1,448 @@
+"""Responses tool-search deferral is skipped for harnesses that cannot run it (GH #2660)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from starlette.datastructures import Headers
+
+from headroom.proxy.auth_mode import classify_client
+from headroom.proxy.handlers.openai import OpenAIHandlerMixin
+from headroom.proxy.helpers import (
+    inject_tool_search_deferral_openai,
+    openai_tool_search_client_supported,
+)
+
+TOOL_SEARCH_MODEL = "gpt-5.5"
+
+
+def _tool_payload() -> list[dict[str, object]]:
+    """Six core coding tools plus ten non-core ones, over the injection minimum."""
+    names = ["bash", "read", "write", "edit", "grep", "glob"]
+    names += [f"slack_{index}" for index in range(10)]
+    return [
+        {"type": "function", "name": name, "parameters": {"type": "object", "properties": {}}}
+        for name in names
+    ]
+
+
+@pytest.mark.parametrize(
+    ("headers", "expected_client", "supported"),
+    [
+        ({"user-agent": "opencode/0.4.2"}, "opencode", False),
+        ({"x-client": "opencode"}, "opencode", False),
+        ({"user-agent": "codex-cli/1.2.3"}, "codex", False),
+        ({"user-agent": "claude-code/2.0"}, "claude-code", True),
+        ({"user-agent": "cursor/1.0"}, "cursor", True),
+        ({}, None, True),
+        ({"user-agent": "some-unknown-sdk/1.0"}, None, True),
+        # CLIENT_UA_MAP matches by substring, so a wrapper that embeds the
+        # opencode UA is classified as opencode and excluded with it.
+        ({"user-agent": "acme-wrapper opencode/1.0"}, "opencode", False),
+    ],
+)
+def test_only_the_reported_harness_is_excluded(
+    headers: dict[str, str], expected_client: str | None, supported: bool
+) -> None:
+    """The exclusion keys on the client name the proxy already resolves."""
+    assert classify_client(headers) == expected_client
+    assert openai_tool_search_client_supported(classify_client(headers)) is supported
+
+
+def test_a_similar_client_name_does_not_match() -> None:
+    """The exclusion set is exact membership on the resolved client name.
+
+    Substring matching happens upstream in ``CLIENT_UA_MAP``; this pins that the
+    set itself does not widen a name that already classified.
+    """
+    assert openai_tool_search_client_supported("opencode-fork") is True
+    assert openai_tool_search_client_supported("open") is True
+    assert openai_tool_search_client_supported("opencode") is False
+
+
+def test_request_headers_decide_the_outbound_tools_payload() -> None:
+    """End of the route: real request headers in, final Responses tools out.
+
+    This is the symptom the issue reports. An opencode request must not find an
+    injected ``{"type": "tool_search"}`` tool it cannot execute, and every other
+    client must still get the deferral it got before.
+    """
+    tools = _tool_payload()
+
+    opencode = Headers({"user-agent": "opencode/0.4.2", "content-type": "application/json"})
+    forwarded = inject_tool_search_deferral_openai(
+        tools,
+        TOOL_SEARCH_MODEL,
+        client=classify_client(opencode),
+    )
+    assert forwarded is tools
+    assert not any(tool.get("type") == "tool_search" for tool in forwarded)
+    assert not any(tool.get("defer_loading") for tool in forwarded)
+
+    codex = Headers({"user-agent": "codex-cli/1.2.3", "content-type": "application/json"})
+    forwarded = inject_tool_search_deferral_openai(
+        tools,
+        TOOL_SEARCH_MODEL,
+        client=classify_client(codex),
+    )
+    assert forwarded is tools
+    assert not any(tool.get("type") == "tool_search" for tool in forwarded)
+    assert not any(tool.get("defer_loading") for tool in tools)
+
+
+def test_websocket_and_http_header_shapes_classify_alike() -> None:
+    """The WebSocket path builds a plain dict from the same multidict."""
+    multidict = Headers({"user-agent": "opencode/0.4.2"})
+
+    assert classify_client(multidict) == "opencode"
+    assert classify_client(dict(multidict)) == "opencode"
+
+
+def test_native_responses_compressor_scopes_the_exclusion_per_call() -> None:
+    """The flag rides one request; a later request is unaffected by an earlier one."""
+    seen: list[dict[str, object]] = []
+    handler = object.__new__(OpenAIHandlerMixin)
+
+    async def _run_compression(fn, *, timeout):  # noqa: ANN001, ANN202
+        return fn()
+
+    def _compress(payload, *, model, request_id, **kwargs):  # noqa: ANN001, ANN202
+        seen.append(kwargs)
+        return (payload, False, 0, [], "no-op", 0, 0, 0, {})
+
+    handler._run_compression_in_executor = _run_compression
+    handler._compress_openai_responses_payload = _compress
+
+    async def _run() -> None:
+        await handler._compress_openai_responses_payload_in_executor(
+            {"input": "hello"},
+            model=TOOL_SEARCH_MODEL,
+            request_id="req-opencode",
+            client="opencode",
+        )
+        await handler._compress_openai_responses_payload_in_executor(
+            {"input": "hello"},
+            model=TOOL_SEARCH_MODEL,
+            request_id="req-codex",
+        )
+
+    asyncio.run(_run())
+
+    assert [{key: value for key, value in call.items() if key != "timing"} for call in seen] == [
+        {"client": "opencode"},
+        {"client": None},
+    ]
+
+
+def test_supported_clients_send_no_extra_compressor_argument() -> None:
+    """A compressor override written before this change keeps its exact signature."""
+    calls: list[str] = []
+    handler = object.__new__(OpenAIHandlerMixin)
+
+    async def _run_compression(fn, *, timeout):  # noqa: ANN001, ANN202
+        return fn()
+
+    def _narrow_compress(payload, *, model, request_id, timing=None):  # noqa: ANN001, ANN202
+        calls.append(request_id)
+        return (payload, False, 0, [], "no-op", 0, 0, 0, {})
+
+    handler._run_compression_in_executor = _run_compression
+    handler._compress_openai_responses_payload = _narrow_compress
+
+    asyncio.run(
+        handler._compress_openai_responses_payload_in_executor(
+            {"input": "hello"},
+            model=TOOL_SEARCH_MODEL,
+            request_id="req-codex",
+        )
+    )
+
+    assert calls == ["req-codex"]
+
+
+def test_a_narrow_compressor_override_still_works_for_an_excluded_client() -> None:
+    """The retry drops the optional keywords rather than failing the request."""
+    calls: list[str] = []
+    handler = object.__new__(OpenAIHandlerMixin)
+
+    async def _run_compression(fn, *, timeout):  # noqa: ANN001, ANN202
+        return fn()
+
+    def _narrow_compress(payload, *, model, request_id):  # noqa: ANN001, ANN202
+        calls.append(request_id)
+        return (payload, False, 0, [], "no-op", 0, 0, 0, {})
+
+    handler._run_compression_in_executor = _run_compression
+    handler._compress_openai_responses_payload = _narrow_compress
+
+    asyncio.run(
+        handler._compress_openai_responses_payload_in_executor(
+            {"input": "hello"},
+            model=TOOL_SEARCH_MODEL,
+            request_id="req-opencode",
+            client="opencode",
+        )
+    )
+
+    assert calls == ["req-opencode"]
+
+
+def test_native_responses_compressor_reraises_internal_type_error() -> None:
+    """An internal compressor TypeError is propagated without a signature retry."""
+    calls = 0
+    handler = object.__new__(OpenAIHandlerMixin)
+    sentinel = TypeError("internal compressor failure")
+
+    async def _run_compression(fn, *, timeout):  # noqa: ANN001, ANN202
+        return fn()
+
+    def _compress(payload, *, model, request_id, client, timing=None):  # noqa: ANN001, ANN202
+        nonlocal calls
+        calls += 1
+        raise sentinel
+
+    handler._run_compression_in_executor = _run_compression
+    handler._compress_openai_responses_payload = _compress
+
+    with pytest.raises(TypeError) as exc_info:
+        asyncio.run(
+            handler._compress_openai_responses_payload_in_executor(
+                {"input": "hello"},
+                model=TOOL_SEARCH_MODEL,
+                request_id="req-opencode",
+                client="opencode",
+            )
+        )
+
+    assert exc_info.value is sentinel
+    assert calls == 1
+
+
+class _ResponsesRequest:
+    method = "POST"
+    url = SimpleNamespace(path="/custom/v1/responses", query="")
+
+    def __init__(self, headers: dict[str, str]) -> None:
+        self.headers = headers
+
+    async def body(self) -> bytes:
+        return json.dumps({"model": TOOL_SEARCH_MODEL, "input": "hello"}).encode()
+
+
+class _UpstreamClient:
+    async def request(self, **kwargs):  # noqa: ANN001, ANN201
+        request = httpx.Request(kwargs["method"], kwargs["url"])
+        return httpx.Response(200, request=request, json={"ok": True})
+
+
+def _passthrough_handler(seen: list[dict[str, object]]) -> OpenAIHandlerMixin:
+    handler = object.__new__(OpenAIHandlerMixin)
+    handler.config = SimpleNamespace(
+        optimize=True,
+        compress_passthrough=True,
+        openai_extra_headers=None,
+    )
+    handler.http_client = _UpstreamClient()
+    handler.http_client_h1 = None
+
+    async def _next_request_id() -> str:
+        return "req-test"
+
+    async def _compress(payload, *, model, request_id, **kwargs):  # noqa: ANN001, ANN202
+        seen.append(kwargs)
+        return (payload, False, 0, [], "no-op", 0, len(json.dumps(payload)), 0, {})
+
+    handler._next_request_id = _next_request_id
+    handler._compress_openai_responses_payload_in_executor = _compress
+    return handler
+
+
+def test_custom_base_path_excludes_the_reported_harness() -> None:
+    seen: list[dict[str, object]] = []
+
+    asyncio.run(
+        _passthrough_handler(seen).handle_passthrough(
+            _ResponsesRequest({"user-agent": "opencode/0.4.2", "content-type": "application/json"}),
+            "https://api.example.com",
+        )
+    )
+
+    assert seen == [{"client": "opencode"}]
+
+
+def test_custom_base_path_leaves_other_clients_alone() -> None:
+    seen: list[dict[str, object]] = []
+
+    asyncio.run(
+        _passthrough_handler(seen).handle_passthrough(
+            _ResponsesRequest(
+                {"user-agent": "codex-cli/1.2.3", "content-type": "application/json"}
+            ),
+            "https://api.example.com",
+        )
+    )
+
+    assert seen == [{"client": "codex"}]
+
+
+# --- production route: the native /v1/responses handler -----------------------
+
+_OPENAI_OK_RESPONSE = {
+    "id": "resp_test",
+    "object": "response",
+    "status": "completed",
+    "model": TOOL_SEARCH_MODEL,
+    "output": [],
+    "usage": {"input_tokens": 10, "output_tokens": 2},
+}
+
+
+class _NativeCapturingTransport(httpx.AsyncBaseTransport):
+    def __init__(self) -> None:
+        self.call_count = 0
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        self.call_count += 1
+        async for _ in request.stream:
+            pass
+        return httpx.Response(200, json=_OPENAI_OK_RESPONSE)
+
+
+def _native_responses_client():  # noqa: ANN202
+    """Boot the real app and observe what the Responses compressor is handed.
+
+    The transport and the spy are installed after the lifespan runs, because
+    startup builds the proxy's HTTP clients.
+    """
+    pytest.importorskip("fastapi")
+    from fastapi.testclient import TestClient
+
+    from headroom.proxy.server import ProxyConfig, create_app
+
+    config = ProxyConfig(
+        optimize=True,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+        log_requests=False,
+        ccr_inject_tool=False,
+        ccr_handle_responses=False,
+        ccr_context_tracking=False,
+        image_optimize=False,
+    )
+    app = create_app(config)
+    seen: list[dict[str, object]] = []
+
+    # Loopback client so the proxy-token middleware treats this as a local call.
+    with TestClient(app, client=("127.0.0.1", 50000)) as client:
+        proxy = app.state.proxy
+        transport = _NativeCapturingTransport()
+        proxy.http_client = httpx.AsyncClient(transport=transport)
+        proxy.http_client_h1 = httpx.AsyncClient(transport=transport)
+
+        original = proxy._compress_openai_responses_payload_in_executor
+
+        async def _spy(payload, **kwargs):  # noqa: ANN001, ANN202
+            seen.append({k: v for k, v in kwargs.items() if k not in {"model", "request_id"}})
+            return await original(payload, **kwargs)
+
+        proxy._compress_openai_responses_payload_in_executor = _spy
+        yield client, seen, transport
+
+
+def _responses_body() -> dict[str, object]:
+    return {"model": TOOL_SEARCH_MODEL, "input": "hello", "tools": _tool_payload()}
+
+
+@pytest.mark.parametrize(
+    ("user_agent", "expected"),
+    [
+        ("opencode/0.4.2", {"client": "opencode"}),
+        ("codex-cli/1.2.3", {"client": "codex"}),
+    ],
+)
+def test_native_responses_route_carries_the_client_decision(
+    user_agent: str, expected: dict[str, object]
+) -> None:
+    """Drives POST /v1/responses on the real app, not a handler method in isolation.
+
+    Deleting the kwargs splat at the native call site leaves every other test in
+    this file green; this one fails.
+    """
+    for client, seen, transport in _native_responses_client():
+        response = client.post(
+            "/v1/responses",
+            headers={
+                "content-type": "application/json",
+                "authorization": "Bearer sk-test-0000000000000000000000000000000000000000000",
+                "user-agent": user_agent,
+            },
+            json=_responses_body(),
+        )
+
+        assert transport.call_count == 1, response.text
+        assert response.status_code == 200, response.text
+        assert seen, "the Responses compressor was never reached"
+        assert {k: v for k, v in seen[0].items() if k not in {"timing", "savings_tags"}} == expected
+
+
+# --- production route: the Codex WebSocket handler ---------------------------
+
+
+@pytest.mark.parametrize(
+    ("user_agent", "expected"),
+    [
+        ("opencode/0.4.2", {"client": "opencode"}),
+        ("codex-cli/1.2.3", {"client": "codex"}),
+    ],
+)
+def test_websocket_route_carries_the_client_decision(
+    user_agent: str, expected: dict[str, object]
+) -> None:
+    """The WS frame path resolves the client the same way the HTTP path does.
+
+    Reuses the repo's existing Codex WS harness so the real
+    ``handle_openai_responses_ws`` ingress runs, rather than asserting the
+    wiring structurally.
+    """
+    import sys
+    from unittest.mock import patch
+
+    from tests.test_openai_codex_ws_lifecycle import (
+        _DummyOpenAIHandler,
+        _FakeUpstream,
+        _FakeWebSocket,
+        _first_frame,
+        _make_fake_websockets_module,
+    )
+
+    upstream = _FakeUpstream(
+        [
+            json.dumps({"type": "response.created", "response": {"id": "r_1"}}),
+            json.dumps({"type": "response.completed", "response": {"id": "r_1"}}),
+        ]
+    )
+    client_ws = _FakeWebSocket(
+        frames=[_first_frame()],
+        headers={"authorization": "Bearer test", "user-agent": user_agent},
+    )
+    handler = _DummyOpenAIHandler()
+    handler.config.optimize = True
+
+    seen: list[dict[str, object]] = []
+
+    def _compress(payload, *, model, request_id, **kwargs):  # noqa: ANN001, ANN202
+        seen.append(kwargs)
+        return (payload, False, 0, [], "router_no_compression", 10, 10)
+
+    handler._compress_openai_responses_payload = _compress
+
+    with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):
+        asyncio.run(handler.handle_openai_responses_ws(client_ws))
+
+    assert seen, "the Responses compressor was never reached on the WS path"
+    assert {k: v for k, v in seen[0].items() if k != "timing"} == expected
diff --git a/tests/test_proxy_scalability.py b/tests/test_proxy_scalability.py
index d0184a2a9..f03528cbd 100644
--- a/tests/test_proxy_scalability.py
+++ b/tests/test_proxy_scalability.py
@@ -275,6 +275,7 @@ class TestWorkerConfiguration:
             payload = json.loads(os.environ[_MULTI_WORKER_CONFIG_ENV])
             assert payload["host"] == "0.0.0.0"
             assert payload["port"] == 8787
+            assert payload["worker_processes"] == 4
             assert payload["max_connections"] == 200
             assert payload["http_proxy"] == "http://proxy.local:8080"
         finally:
diff --git a/tests/test_proxy_settings_endpoints.py b/tests/test_proxy_settings_endpoints.py
index 31880c5ab..1e51f1001 100644
--- a/tests/test_proxy_settings_endpoints.py
+++ b/tests/test_proxy_settings_endpoints.py
@@ -207,6 +207,7 @@ class TestSecretMasking:
         )
         monkeypatch.setattr(settings_store, "SETTINGS", registry)
         monkeypatch.setattr(settings_store, "_BY_KEY", {f.key: f for f in registry})
+        monkeypatch.setattr(settings_store, "_BY_ENV", {f.env: f for f in registry})
         settings_store.save({"log_file": "/tmp/secret.log"})
 
         assert client.get("/settings").json()["log_file"] == settings_store._MASK
diff --git a/tests/test_proxy_stats_recent_requests.py b/tests/test_proxy_stats_recent_requests.py
index 50a877e4a..fcc20fe59 100644
--- a/tests/test_proxy_stats_recent_requests.py
+++ b/tests/test_proxy_stats_recent_requests.py
@@ -5,6 +5,7 @@ from fastapi.testclient import TestClient
 
 from headroom.proxy.models import ProxyConfig
 from headroom.proxy.server import create_app
+from headroom.rollout import resolve_rollout
 
 
 class FakeRequestLogger:
@@ -28,6 +29,35 @@ class FakeLogEntry(dict[str, object]):
         return self.get(name)
 
 
+def test_stats_exposes_actual_running_rollout_snapshot() -> None:
+    rollout = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "canary",
+            "HEADROOM_FEATURES": "tool_result_interceptors",
+        }
+    )
+    app = create_app(
+        ProxyConfig(
+            rollout=rollout,
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            cost_tracking_enabled=False,
+            log_requests=False,
+            ccr_inject_tool=False,
+            ccr_handle_responses=False,
+            ccr_context_tracking=False,
+            http2=False,
+        )
+    )
+
+    with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client:
+        payload = client.get("/stats").json()["rollout"]
+
+    assert payload == rollout.to_dict()
+    assert payload["qualification_eligible"] is True
+
+
 def test_stats_refreshes_recent_requests_when_cached() -> None:
     app = create_app(
         ProxyConfig(
@@ -54,6 +84,14 @@ def test_stats_refreshes_recent_requests_when_cached() -> None:
             "input_tokens_optimized": 60,
             "tokens_saved": 40,
             "savings_percent": 40.0,
+            "savings_breakdown": [
+                {
+                    "source": "tool_search",
+                    "tokens": 40,
+                    "usd": 0.0,
+                    "realized": True,
+                }
+            ],
         }
     )
     second_log = FakeLogEntry(
@@ -74,6 +112,14 @@ def test_stats_refreshes_recent_requests_when_cached() -> None:
         first_response = client.get("/stats?cached=1")
         assert first_response.status_code == 200
         assert first_response.json()["recent_requests"][-1]["model"] == "gpt-4.1"
+        assert first_response.json()["recent_requests"][-1]["savings_breakdown"] == [
+            {
+                "source": "tool_search",
+                "tokens": 40,
+                "usd": 0.0,
+                "realized": True,
+            }
+        ]
 
         logger.logs = [first_log, second_log]
         second_response = client.get("/stats?cached=1")
diff --git a/tests/test_proxy_streaming_ratelimit_headers.py b/tests/test_proxy_streaming_ratelimit_headers.py
index dfedc4915..5983dea54 100644
--- a/tests/test_proxy_streaming_ratelimit_headers.py
+++ b/tests/test_proxy_streaming_ratelimit_headers.py
@@ -463,6 +463,105 @@ class TestStreamingRatelimitHeaderForwarding:
         assert attempts["count"] == 2
         assert chunks
 
+    @pytest.mark.asyncio
+    async def test_upstream_stream_closed_when_body_never_consumed(self):
+        """A never-iterated streaming body must still release the upstream stream (#2797).
+
+        The upstream stream is opened before the body generator, and the
+        generator's own ``aclosing`` only runs if the body is iterated. When a
+        client disconnects before Starlette starts sending the body the
+        generator never runs, so the close must come from the response's
+        ``background`` task instead — otherwise every such request leaks an open
+        HTTP/2 stream and the pooled upstream connection eventually exhausts its
+        100 concurrent streams ("Max outbound streams is 100, 100 open").
+        """
+        proxy = self._create_mock_proxy()
+        mock_response = self._create_mock_upstream_response()
+
+        mock_request = MagicMock()
+        proxy.http_client.build_request = MagicMock(return_value=mock_request)
+        proxy.http_client.send = AsyncMock(return_value=mock_response)
+
+        result = await proxy._stream_response(
+            url="https://api.anthropic.com/v1/messages",
+            headers={"x-api-key": "sk-test"},
+            body={
+                "model": "claude-sonnet-4-20250514",
+                "max_tokens": 100,
+                "stream": True,
+                "messages": [{"role": "user", "content": "hi"}],
+            },
+            provider="anthropic",
+            model="claude-sonnet-4-20250514",
+            request_id="test-abandoned-stream",
+            original_tokens=10,
+            optimized_tokens=10,
+            tokens_saved=0,
+            transforms_applied=[],
+            tags={},
+            optimization_latency=0.0,
+        )
+
+        # Simulate the client disconnecting before the body is consumed: the
+        # generator is never iterated, so its aclosing never runs.
+        mock_response.aclose.assert_not_awaited()
+
+        # Starlette runs the response's background task in exactly this case.
+        assert result.background is not None, "streaming response must carry a cleanup task"
+        await result.background()
+
+        mock_response.aclose.assert_awaited()
+
+    @pytest.mark.asyncio
+    async def test_upstream_stream_released_over_asgi_lifecycle_on_disconnect(self):
+        """Driving the real ASGI response through an early disconnect releases the stream.
+
+        Rather than calling ``result.background()`` directly, this exercises the
+        Starlette response lifecycle with a client that disconnects immediately,
+        and asserts the upstream stream is closed by the end of it -- proving the
+        cleanup this PR attaches is actually invoked by Starlette, not merely
+        present on the response object.
+        """
+        import asyncio
+
+        proxy = self._create_mock_proxy()
+        mock_response = self._create_mock_upstream_response()
+        proxy.http_client.build_request = MagicMock(return_value=MagicMock())
+        proxy.http_client.send = AsyncMock(return_value=mock_response)
+
+        result = await proxy._stream_response(
+            url="https://api.anthropic.com/v1/messages",
+            headers={"x-api-key": "sk-test"},
+            body={
+                "model": "claude-sonnet-4-20250514",
+                "max_tokens": 100,
+                "stream": True,
+                "messages": [{"role": "user", "content": "hi"}],
+            },
+            provider="anthropic",
+            model="claude-sonnet-4-20250514",
+            request_id="test-asgi-lifecycle",
+            original_tokens=10,
+            optimized_tokens=10,
+            tokens_saved=0,
+            transforms_applied=[],
+            tags={},
+            optimization_latency=0.0,
+        )
+
+        async def receive():
+            # The client is already gone before the body is streamed.
+            return {"type": "http.disconnect"}
+
+        async def send(_message):
+            return None
+
+        scope = {"type": "http", "method": "POST", "headers": []}
+        await asyncio.wait_for(result(scope, receive, send), timeout=5.0)
+
+        # By the end of the response lifecycle the upstream stream is released.
+        mock_response.aclose.assert_awaited()
+
     @pytest.mark.asyncio
     async def test_codex_rate_limit_headers_captured_and_forwarded_in_streaming(self):
         """Codex x-codex-* headers must refresh /stats state AND reach the client.
diff --git a/tests/test_proxy_telemetry_env.py b/tests/test_proxy_telemetry_env.py
index e3ffd65a6..0dc51c117 100644
--- a/tests/test_proxy_telemetry_env.py
+++ b/tests/test_proxy_telemetry_env.py
@@ -98,3 +98,33 @@ class TestProxyPeriodicTOINStatsEnv:
             pass
 
         assert requested is True
+
+    def test_lifespan_cancels_periodic_toin_stats_on_shutdown(self, monkeypatch):
+        """Shutdown cancels and awaits the periodic TOIN stats task."""
+        monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")
+
+        async def hold_periodic_stats_task():
+            await asyncio.Event().wait()
+
+        monkeypatch.setattr(
+            "headroom.proxy.server._log_toin_stats_periodically",
+            hold_periodic_stats_task,
+        )
+
+        app = create_app(
+            ProxyConfig(
+                optimize=False,
+                cache_enabled=False,
+                rate_limit_enabled=False,
+                cost_tracking_enabled=False,
+                periodic_toin_stats_enabled=True,
+            )
+        )
+
+        with TestClient(app):
+            task = app.state.periodic_toin_stats_task
+            assert task is not None
+            assert not task.done()
+
+        assert task.cancelled()
+        assert app.state.periodic_toin_stats_task is None
diff --git a/tests/test_read_maturation_handler_nobust.py b/tests/test_read_maturation_handler_nobust.py
index feee132d9..3f9231bd0 100644
--- a/tests/test_read_maturation_handler_nobust.py
+++ b/tests/test_read_maturation_handler_nobust.py
@@ -360,6 +360,7 @@ def test_read_maturation_knobs_from_env(monkeypatch):
     monkeypatch.delenv(_MULTI_WORKER_CONFIG_ENV, raising=False)
 
     monkeypatch.setenv("HEADROOM_READ_MATURATION", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "beta")
     monkeypatch.setenv("HEADROOM_READ_MATURATION_QUIESCE_TURNS", "3")
     monkeypatch.setenv("HEADROOM_READ_MATURATION_MAX_HOLD_TURNS", "10")
     monkeypatch.setenv("HEADROOM_READ_MATURATION_MIN_SIZE_BYTES", "4096")
@@ -370,3 +371,18 @@ def test_read_maturation_knobs_from_env(monkeypatch):
     assert cfg.read_maturation_quiesce_turns == 3
     assert cfg.read_maturation_max_hold_turns == 10
     assert cfg.read_maturation_min_size_bytes == 4096
+
+
+def test_read_maturation_env_cannot_bypass_stable_rollout(monkeypatch):
+    """Every env-driven server composition root must enforce the beta gate."""
+    from headroom.proxy.server import _MULTI_WORKER_CONFIG_ENV, _proxy_config_from_env
+
+    monkeypatch.delenv(_MULTI_WORKER_CONFIG_ENV, raising=False)
+    monkeypatch.setenv("HEADROOM_READ_MATURATION", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "stable")
+
+    cfg = _proxy_config_from_env()
+
+    assert cfg.read_maturation is False
+    assert cfg.rollout is not None
+    assert cfg.rollout.decision("read_maturation").reason.value == "blocked_by_channel"
diff --git a/tests/test_realignment_live_multi_turn.py b/tests/test_realignment_live_multi_turn.py
index b3ff95f2e..8608a51c8 100644
--- a/tests/test_realignment_live_multi_turn.py
+++ b/tests/test_realignment_live_multi_turn.py
@@ -48,6 +48,7 @@ from fastapi.testclient import TestClient  # noqa: E402
 
 from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
 from tests._dotenv import autouse_apply_env, load_env_overrides  # noqa: E402
+from tests._gemini_live import skip_if_gemini_quota_exhausted  # noqa: E402
 
 # ---------------------------------------------------------------------------
 # Module-level config
@@ -639,6 +640,7 @@ def test_gemini_multi_turn_through_proxy(proxy_client: TestClient) -> None:
     ]
 
     resp1 = proxy_client.post(url, json={"contents": contents})
+    skip_if_gemini_quota_exhausted(resp1)
     assert resp1.status_code == 200, resp1.text
     data1 = resp1.json()
     text1 = data1["candidates"][0]["content"]["parts"][0]["text"]
@@ -648,6 +650,7 @@ def test_gemini_multi_turn_through_proxy(proxy_client: TestClient) -> None:
     contents.append({"role": "user", "parts": [{"text": "Now reply with the single word WORLD."}]})
 
     resp2 = proxy_client.post(url, json={"contents": contents})
+    skip_if_gemini_quota_exhausted(resp2)
     assert resp2.status_code == 200, resp2.text
     data2 = resp2.json()
     text2 = data2["candidates"][0]["content"]["parts"][0]["text"]
diff --git a/tests/test_release_workflows.py b/tests/test_release_workflows.py
index 9acd4faa2..207827802 100644
--- a/tests/test_release_workflows.py
+++ b/tests/test_release_workflows.py
@@ -5,10 +5,63 @@ from __future__ import annotations
 from pathlib import Path
 
 import pytest
+import yaml
+from packaging.requirements import Requirement
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10 fallback
+    import tomli as tomllib  # type: ignore[no-redef]
 
 ROOT = Path(__file__).resolve().parent.parent
 
 
+def test_every_published_docker_variant_includes_bedrock_auth_dependencies() -> None:
+    """Every image that advertises ``--backend bedrock`` must ship botocore.
+
+    Temporary AWS credentials take LiteLLM's botocore-backed authentication
+    path.  The default images previously installed only ``proxy``/``code``, so
+    the documented Docker Bedrock command failed at runtime with
+    ``No module named 'botocore'`` (#1551).  Keep the standalone Dockerfile and
+    every bake target on the existing ``bedrock`` package extra.
+    """
+    dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")
+    assert "ARG HEADROOM_EXTRAS=proxy,code,bedrock" in dockerfile
+
+    bake = (ROOT / "docker-bake.hcl").read_text(encoding="utf-8")
+    extras_lines = [
+        line.strip() for line in bake.splitlines() if line.strip().startswith("HEADROOM_EXTRAS =")
+    ]
+    assert len(extras_lines) == 9
+    assert all("bedrock" in line for line in extras_lines), extras_lines
+
+    project = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+    bedrock_names = {
+        Requirement(requirement).name
+        for requirement in project["project"]["optional-dependencies"]["bedrock"]
+    }
+    assert {"boto3", "botocore"} <= bedrock_names
+
+
+def test_public_docker_instructions_use_the_current_organization_package() -> None:
+    """Do not send users back to the personal GHCR package frozen at 0.27.0."""
+    public_docs = (
+        "README.md",
+        "llms.txt",
+        "docker-compose.yml",
+        "TESTING-copilot-subscription.md",
+        "wiki/cli.md",
+        "wiki/docker-install.md",
+    )
+    deprecated = "ghcr.io/chopratejas/headroom"
+    current = "ghcr.io/headroomlabs-ai/headroom"
+
+    for relative_path in public_docs:
+        content = (ROOT / relative_path).read_text(encoding="utf-8")
+        assert deprecated not in content, relative_path
+        assert current in content, relative_path
+
+
 def test_docker_workflow_normalizes_repository_name_for_signing() -> None:
     content = (ROOT / ".github" / "workflows" / "docker.yml").read_text(encoding="utf-8")
 
@@ -17,6 +70,90 @@ def test_docker_workflow_normalizes_repository_name_for_signing() -> None:
     assert "steps.image-name.outputs.image_name" in content
 
 
+def test_docker_latest_promotion_is_owned_by_root_manifest_cell() -> None:
+    workflow = yaml.safe_load((ROOT / ".github" / "workflows" / "docker.yml").read_text())
+    jobs = workflow["jobs"]
+    build = jobs["docker-build"]
+    manifest = jobs["docker-manifest"]
+    variants = manifest["strategy"]["matrix"]["variant"]
+    build_variants = build["strategy"]["matrix"]["variant"]
+    architectures = build["strategy"]["matrix"]["arch"]
+    root = next(entry for entry in variants if entry["name"] == "")
+    nonroot = next(entry for entry in variants if entry["name"] == "nonroot")
+    promotion = next(
+        step for step in manifest["steps"] if step["name"] == "Re-tag root image as :latest"
+    )
+    command = promotion["run"]
+
+    assert len(variants) == 8
+    assert [entry["name"] for entry in build_variants] == [entry["name"] for entry in variants]
+    assert len(architectures) == 2
+    assert {entry["platform"] for entry in architectures} == {"linux/amd64", "linux/arm64"}
+    assert root["name"] == ""
+    assert nonroot["name"] == "nonroot"
+    assert "matrix.variant.name == ''" in promotion["if"]
+    assert "steps.manifest.outputs.index_digest != ''" in promotion["if"]
+    assert "steps.version.outputs.version != ''" in promotion["if"]
+    assert (
+        promotion["if"]
+        == "steps.manifest.outputs.index_digest != '' && matrix.variant.name == '' && steps.version.outputs.version != ''"
+    )
+    assert '"${IMAGE}:latest"' in command
+    assert '"${IMAGE}:${VERSION}"' in command
+    assert "promote-latest" not in jobs
+    assert manifest["needs"] == "docker-build"
+    assert manifest["if"] == "${{ always() }}"
+    step_names = [step["name"] for step in manifest["steps"]]
+    assert step_names.index("Sign multi-arch index manifest with cosign") < step_names.index(
+        "Re-tag root image as :latest"
+    )
+    manifest_script = next(
+        step["run"] for step in manifest["steps"] if step["name"] == "Create multi-arch manifest"
+    )
+    assert 'digest_count="$(find "${DIGEST_DIR}" -maxdepth 1 -type f | wc -l)"' in manifest_script
+    assert '"${digest_count}" -ne 2' in manifest_script
+    assert manifest_script.index('"${digest_count}" -ne 2') < manifest_script.index(
+        "docker buildx imagetools create"
+    )
+    guard_start = manifest_script.index('"${digest_count}" -ne 2')
+    create_start = manifest_script.index("docker buildx imagetools create")
+    assert guard_start < manifest_script.index("exit 1", guard_start) < create_start
+
+
+def test_docker_manifest_downloads_exactly_one_artifact_per_architecture() -> None:
+    """Each manifest cell must download exactly its two architecture digests.
+
+    Keeping the variant before a trailing wildcard makes prefix-related names
+    overlap: ``digests-code-*`` also selects code-nonroot, code-slim, and
+    code-slim-nonroot. The 0.35.0 Docker release exposed this by downloading
+    eight markers into the code manifest job instead of two.
+    """
+    workflow = yaml.safe_load((ROOT / ".github" / "workflows" / "docker.yml").read_text())
+    jobs = workflow["jobs"]
+    build = jobs["docker-build"]
+    manifest = jobs["docker-manifest"]
+    upload = next(step for step in build["steps"] if step.get("name") == "Upload digest marker")
+    downloads = [
+        step
+        for step in manifest["steps"]
+        if step.get("name")
+        in {
+            "Download amd64 digest for this variant",
+            "Download arm64 digest for this variant",
+        }
+    ]
+
+    assert upload["with"]["name"] == (
+        "digests-${{ matrix.variant.name || 'root' }}-${{ matrix.arch.name }}"
+    )
+    assert [step["with"]["name"] for step in downloads] == [
+        "digests-${{ matrix.variant.name || 'root' }}-amd64",
+        "digests-${{ matrix.variant.name || 'root' }}-arm64",
+    ]
+    assert all("pattern" not in step["with"] for step in downloads)
+    assert all(step["with"]["path"] == "${{ runner.temp }}/digests" for step in downloads)
+
+
 def test_release_workflow_publishes_both_node_packages_to_github_packages() -> None:
     content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
 
@@ -624,6 +761,19 @@ def test_openclaw_source_dependency_matches_lockfile_registry_range() -> None:
     assert source_range == lock_range == "^0.22.3"
 
 
+def test_opencode_source_dependency_matches_lockfile_registry_range() -> None:
+    """The source checkout must remain npm-ci installable before a release exists."""
+    import json
+
+    package_json = json.loads((ROOT / "plugins" / "opencode" / "package.json").read_text())
+    package_lock = json.loads((ROOT / "plugins" / "opencode" / "package-lock.json").read_text())
+
+    source_range = package_json["dependencies"]["headroom-ai"]
+    lock_range = package_lock["packages"][""]["dependencies"]["headroom-ai"]
+
+    assert source_range == lock_range == "^0.22.3"
+
+
 def test_python_release_smoke_imports_installed_wheel_outside_source_tree() -> None:
     """The wheel smoke must not import the checkout package by accident."""
     script = (ROOT / "scripts" / "build_python_release_smoke.py").read_text(encoding="utf-8")
@@ -649,6 +799,21 @@ def test_publish_npm_regenerates_openclaw_dist_metadata_after_version_and_depend
     assert version < dependency < prepare_dist < publish
 
 
+def test_publish_npm_rewrites_opencode_dependency_after_version_and_before_publish() -> None:
+    """The direct npm publish path must version and retarget the Opencode dependency."""
+    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
+
+    start = content.index("name: Publish ${{ env.NPM_OPENCODE_PACKAGE }} to npmjs.org")
+    end = content.index("continue-on-error: true", start)
+    block = content[start:end]
+
+    version = block.index('npm version "$version"')
+    dependency = block.index('pkg.dependencies["headroom-ai"]')
+    publish = block.index("npm publish --access public")
+
+    assert version < dependency < publish
+
+
 def test_sdist_license_is_packaged_and_verified_before_upload() -> None:
     """STRUCTURAL INVARIANT: the sdist tarball must physically contain
     every license file PEP 639 declares in PKG-INFO, and the release
@@ -1208,7 +1373,23 @@ def test_release_please_config_and_manifest_are_present_and_consistent() -> None
         "changelog because the bot can't find its baseline."
     )
 
-    # extra-files: TypeScript SDK and openclaw plugin package.json
+    # This manifest has one package. Sending it through the merge plugin
+    # produces the group title `chore: release main`, which contains neither
+    # the package component nor its version. On merge, release-please cannot
+    # associate that title with `headroom-ai`, leaves the PR tagged
+    # `autorelease: pending`, and never emits the release event that publishes
+    # to PyPI. Keep the single package on the normal, versioned PR path and
+    # preserve the component in the title used to match the merged PR.
+    assert config.get("separate-pull-requests") is True, (
+        "The single root package must bypass release-please's merge plugin; "
+        "its grouped PR title is `chore: release main` and cannot be tagged."
+    )
+    assert config.get("pull-request-title-pattern") == ("chore: release${component} ${version}"), (
+        "Release PR titles must include both component and version so "
+        "release-please can match the merged PR back to headroom-ai."
+    )
+
+    # extra-files: TypeScript SDK and npm plugin package.json files
     # files must be in lockstep with pyproject.toml.
     extra_paths = {ef["path"] for ef in root_pkg.get("extra-files", [])}
     assert "sdk/typescript/package.json" in extra_paths, (
@@ -1219,6 +1400,10 @@ def test_release_please_config_and_manifest_are_present_and_consistent() -> None
         "release-please must bump plugins/openclaw/package.json so the "
         "openclaw npm publish stays in sync."
     )
+    assert "plugins/opencode/package.json" in extra_paths, (
+        "release-please must bump plugins/opencode/package.json so the "
+        "opencode npm publish stays in sync."
+    )
 
 
 def test_release_metadata_sync_runs_on_release_please_branch() -> None:
diff --git a/tests/test_request_outcome.py b/tests/test_request_outcome.py
index 09936a094..d2295a5ea 100644
--- a/tests/test_request_outcome.py
+++ b/tests/test_request_outcome.py
@@ -15,6 +15,7 @@ import asyncio
 import contextlib
 import logging
 from dataclasses import FrozenInstanceError
+from datetime import datetime, timezone
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock
 
@@ -325,6 +326,22 @@ async def test_funnel_logs_request_with_derived_cache_hit() -> None:
     assert log_entry.cache_hit is True
 
 
+@pytest.mark.asyncio
+async def test_funnel_logs_request_timestamp_with_utc_offset() -> None:
+    """Recent-request timestamps must identify an absolute instant.
+
+    A naive ISO timestamp is interpreted in the browser's local timezone,
+    which makes the dashboard show negative ages when the proxy and browser
+    use different timezone settings.
+    """
+    h = _FunnelHarness()
+    await h._record_request_outcome(_outcome())
+
+    timestamp = datetime.fromisoformat(h.logger.logs[0].timestamp)
+    assert timestamp.tzinfo is not None
+    assert timestamp.utcoffset() == timezone.utc.utcoffset(timestamp)
+
+
 @pytest.mark.asyncio
 async def test_funnel_skips_request_log_when_logger_absent() -> None:
     """Same pattern as cost_tracker — optional surface."""
diff --git a/tests/test_rollout.py b/tests/test_rollout.py
new file mode 100644
index 000000000..1c2e0f43c
--- /dev/null
+++ b/tests/test_rollout.py
@@ -0,0 +1,465 @@
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from headroom.cli.main import main
+from headroom.config import HeadroomConfig
+from headroom.rollout import (
+    FEATURES,
+    FeatureDecisionReason,
+    FeatureSpec,
+    RolloutChannel,
+    RolloutConfigurationError,
+    RolloutSnapshot,
+    current_rollout,
+    feature_enabled,
+    registry_digest,
+    resolve_rollout,
+)
+from headroom.transforms.pipeline import TransformPipeline
+
+
+def test_default_stable_resolution_is_versioned_and_eligible() -> None:
+    snapshot = resolve_rollout({})
+
+    assert snapshot.channel is RolloutChannel.STABLE
+    assert snapshot.schema_version == 1
+    assert snapshot.policy_version == "1"
+    assert snapshot.qualification_eligible is True
+
+
+@pytest.mark.parametrize("channel", ["beta", "canary", "dev"])
+def test_valid_rollout_channels(channel: str) -> None:
+    assert resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": channel}).channel.value == channel
+
+
+@pytest.mark.parametrize(
+    ("alias", "expected"),
+    [
+        ("prod", RolloutChannel.STABLE),
+        ("production", RolloutChannel.STABLE),
+        ("preview", RolloutChannel.BETA),
+        ("nightly", RolloutChannel.CANARY),
+        ("development", RolloutChannel.DEV),
+    ],
+)
+def test_channel_aliases(alias: str, expected: RolloutChannel) -> None:
+    assert RolloutChannel.parse(alias) is expected
+
+
+def test_strict_channel_configuration_rejects_unknown_input() -> None:
+    with pytest.raises(RolloutConfigurationError, match="unknown rollout channel"):
+        resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "stabel"}, strict=True)
+
+
+def test_unknown_channel_fails_closed_with_diagnostic(caplog: pytest.LogCaptureFixture) -> None:
+    with caplog.at_level(logging.WARNING):
+        snapshot = resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "stabel"})
+
+    assert snapshot.channel is RolloutChannel.STABLE
+    assert "unknown rollout channel 'stabel'; falling back to 'stable'" in caplog.text
+
+
+def test_unknown_requested_and_disabled_features_fail_closed_and_warn(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    with caplog.at_level(logging.WARNING):
+        snapshot = resolve_rollout(
+            {
+                "HEADROOM_FEATURES": "typo_requested",
+                "HEADROOM_DISABLE_FEATURES": "typo_disabled",
+            }
+        )
+
+    assert snapshot.config.requested == frozenset()
+    assert snapshot.config.disabled == frozenset()
+    assert "typo_requested" in caplog.text
+    assert "typo_disabled" in caplog.text
+
+
+def test_strict_configuration_rejects_unknown_input() -> None:
+    with pytest.raises(RolloutConfigurationError, match="unknown rollout feature"):
+        resolve_rollout({"HEADROOM_FEATURES": "typo"}, strict=True)
+
+
+def test_stable_blocks_explicit_canary_feature() -> None:
+    snapshot = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "stable",
+            "HEADROOM_FEATURES": "tool-result-interceptors",
+        }
+    )
+    decision = snapshot.decision("tool_result_interceptors")
+
+    assert decision.enabled is False
+    assert decision.reason is FeatureDecisionReason.BLOCKED_BY_CHANNEL
+
+
+def test_canary_allows_explicit_request() -> None:
+    snapshot = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "canary",
+            "HEADROOM_FEATURES": "tool_result_interceptors",
+        }
+    )
+
+    assert snapshot.decision("tool_result_interceptors").reason is FeatureDecisionReason.EXPLICIT
+
+
+def test_non_default_feature_remains_off_when_not_requested() -> None:
+    decision = resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "dev"}).decision(
+        "tool_result_interceptors"
+    )
+    assert decision.enabled is False
+    assert decision.reason is FeatureDecisionReason.NOT_REQUESTED
+
+
+def test_legacy_alias_obeys_channel_and_has_distinct_reason() -> None:
+    stable = resolve_rollout(
+        {"HEADROOM_ROLLOUT_CHANNEL": "stable", "HEADROOM_INTERCEPT_ENABLED": "1"}
+    )
+    canary = resolve_rollout(
+        {"HEADROOM_ROLLOUT_CHANNEL": "canary", "HEADROOM_INTERCEPT_ENABLED": "1"}
+    )
+
+    assert (
+        stable.decision("tool_result_interceptors").reason
+        is FeatureDecisionReason.BLOCKED_BY_CHANNEL
+    )
+    assert canary.decision("tool_result_interceptors").reason is FeatureDecisionReason.LEGACY_ALIAS
+
+
+@pytest.mark.parametrize("request_source", ["HEADROOM_FEATURES", "HEADROOM_INTERCEPT_ENABLED"])
+def test_disable_beats_explicit_and_legacy_request(request_source: str) -> None:
+    snapshot = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "canary",
+            request_source: "tool_result_interceptors"
+            if request_source.endswith("FEATURES")
+            else "1",
+            "HEADROOM_DISABLE_FEATURES": "tool_result_interceptors",
+        }
+    )
+    decision = snapshot.decision("tool_result_interceptors")
+
+    assert decision.enabled is False
+    assert decision.reason is FeatureDecisionReason.DISABLED
+
+
+def test_unsafe_override_crosses_channel_and_poisons_qualification() -> None:
+    snapshot = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "stable",
+            "HEADROOM_FEATURES": "tool_result_interceptors",
+            "HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES": "1",
+        }
+    )
+    payload = snapshot.to_dict()
+
+    assert (
+        snapshot.decision("tool_result_interceptors").reason
+        is FeatureDecisionReason.UNSAFE_OVERRIDE
+    )
+    assert payload["qualification_eligible"] is False
+    assert payload["qualification_ineligible_reason"] == "unsafe_rollout_override_active"
+
+
+def test_disable_still_beats_unsafe_override() -> None:
+    snapshot = resolve_rollout(
+        {
+            "HEADROOM_FEATURES": "tool_result_interceptors",
+            "HEADROOM_DISABLE_FEATURES": "tool_result_interceptors",
+            "HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES": "1",
+        }
+    )
+    assert snapshot.decision("tool_result_interceptors").reason is FeatureDecisionReason.DISABLED
+
+
+def test_live_legacy_reresolution_preserves_channel_and_named_kill_switch() -> None:
+    eligible = resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "beta"})
+    enabled = eligible.with_legacy_env({"HEADROOM_OUTPUT_SHAPER": "1"})
+    disabled_again = enabled.with_legacy_env({"HEADROOM_OUTPUT_SHAPER": "0"})
+    killed = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "beta",
+            "HEADROOM_DISABLE_FEATURES": "proxy_output_shaper",
+        }
+    ).with_legacy_env({"HEADROOM_OUTPUT_SHAPER": "1"})
+    blocked = resolve_rollout({}).with_legacy_env({"HEADROOM_OUTPUT_SHAPER": "1"})
+
+    assert enabled.decision("proxy_output_shaper").reason is FeatureDecisionReason.LEGACY_ALIAS
+    assert disabled_again.decision("proxy_output_shaper").reason is FeatureDecisionReason.DISABLED
+    assert killed.decision("proxy_output_shaper").reason is FeatureDecisionReason.DISABLED
+    assert (
+        blocked.decision("proxy_output_shaper").reason is FeatureDecisionReason.BLOCKED_BY_CHANNEL
+    )
+    assert enabled.snapshot_digest != eligible.snapshot_digest
+
+
+def test_empty_programmatic_feature_names_are_ignored() -> None:
+    snapshot = resolve_rollout({}, requested=["", "  "], disabled=[""])
+
+    assert snapshot.config.requested == frozenset()
+    assert snapshot.config.disabled == frozenset()
+
+
+def test_multi_worker_config_round_trip_preserves_typed_rollout(monkeypatch) -> None:
+    from headroom.proxy.models import ProxyConfig
+    from headroom.proxy.server import (
+        _MULTI_WORKER_CONFIG_ENV,
+        _proxy_config_from_env,
+        _proxy_config_payload,
+    )
+
+    rollout = resolve_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "beta",
+            "HEADROOM_OUTPUT_SHAPER": "1",
+            "HEADROOM_DISABLE_FEATURES": "read_maturation",
+        }
+    )
+    original = ProxyConfig(rollout=rollout, worker_processes=2)
+    monkeypatch.setenv(_MULTI_WORKER_CONFIG_ENV, json.dumps(_proxy_config_payload(original)))
+
+    restored = _proxy_config_from_env()
+
+    assert restored.rollout is not None
+    assert restored.rollout.to_internal_dict() == rollout.to_internal_dict()
+    assert restored.rollout.is_enabled("proxy_output_shaper") is True
+    assert restored.rollout.is_enabled("read_maturation") is False
+    assert restored.worker_processes == 2
+
+
+def test_documented_proxy_json_without_internal_snapshot_is_preserved(monkeypatch) -> None:
+    from headroom.proxy.server import _MULTI_WORKER_CONFIG_ENV, _proxy_config_from_env
+
+    monkeypatch.setenv(
+        _MULTI_WORKER_CONFIG_ENV,
+        json.dumps(
+            {
+                "port": 39099,
+                "rate_limit_enabled": False,
+                "proxy_token": "required-token",
+                "offline": True,
+            }
+        ),
+    )
+
+    restored = _proxy_config_from_env()
+
+    assert restored.port == 39099
+    assert restored.rate_limit_enabled is False
+    assert restored.proxy_token == "required-token"
+    assert restored.offline is True
+    assert restored.rollout is not None
+
+
+def test_internal_proxy_json_still_rejects_tampered_rollout_snapshot(monkeypatch) -> None:
+    from headroom.proxy.models import ProxyConfig
+    from headroom.proxy.server import (
+        _MULTI_WORKER_CONFIG_ENV,
+        _proxy_config_from_env,
+        _proxy_config_payload,
+    )
+
+    payload = _proxy_config_payload(ProxyConfig(port=39099))
+    payload["_rollout_snapshot"]["snapshot_digest"] = "sha256:tampered"  # type: ignore[index]
+    monkeypatch.setenv(_MULTI_WORKER_CONFIG_ENV, json.dumps(payload))
+    monkeypatch.setenv("HEADROOM_PORT", "39100")
+
+    restored = _proxy_config_from_env()
+
+    assert restored.port == 39100
+    assert restored.rollout is not None
+
+
+@pytest.mark.parametrize("raw_config", ["null", "[]", '"not-an-object"'])
+def test_non_object_proxy_json_falls_back_without_crashing(monkeypatch, raw_config: str) -> None:
+    from headroom.proxy.server import _MULTI_WORKER_CONFIG_ENV, _proxy_config_from_env
+
+    monkeypatch.setenv(_MULTI_WORKER_CONFIG_ENV, raw_config)
+    monkeypatch.setenv("HEADROOM_PORT", "39100")
+
+    restored = _proxy_config_from_env()
+
+    assert restored.port == 39100
+    assert restored.rollout is not None
+
+
+@pytest.mark.parametrize(
+    ("mutation", "message"),
+    [
+        ({"schema_version": 999}, "schema version"),
+        ({"policy_version": "999"}, "policy version"),
+        ({"unsafe_allow_unstable": "yes"}, "unsafe override"),
+        ({"explicit_requested": "proxy_output_shaper"}, "explicit_requested"),
+        ({"registry_digest": "sha256:tampered"}, "registry digest"),
+        ({"snapshot_digest": "sha256:tampered"}, "snapshot digest"),
+    ],
+)
+def test_worker_rollout_handoff_rejects_invalid_or_tampered_state(
+    mutation: dict[str, object], message: str
+) -> None:
+    payload = resolve_rollout({}).to_internal_dict()
+    payload.update(mutation)
+
+    with pytest.raises(RolloutConfigurationError, match=message):
+        RolloutSnapshot.from_internal_dict(payload)
+
+
+def test_worker_rollout_handoff_rejects_non_object_state() -> None:
+    with pytest.raises(RolloutConfigurationError, match="invalid rollout worker snapshot"):
+        RolloutSnapshot.from_internal_dict([])  # type: ignore[arg-type]
+
+
+def test_snapshot_query_and_compatibility_helpers() -> None:
+    snapshot = current_rollout(
+        {
+            "HEADROOM_ROLLOUT_CHANNEL": "canary",
+            "HEADROOM_FEATURES": "tool_result_interceptors",
+            "HEADROOM_DISABLE_FEATURES": "read_maturation",
+        }
+    )
+
+    assert snapshot.is_available("tool-result-interceptors") is True
+    assert snapshot.enabled == frozenset({"tool_result_interceptors"})
+    assert snapshot.disabled == frozenset({"read_maturation"})
+    assert feature_enabled(
+        "tool_result_interceptors",
+        explicit=True,
+        environ={"HEADROOM_ROLLOUT_CHANNEL": "canary"},
+    )
+    assert not feature_enabled("tool_result_interceptors", environ={})
+    with pytest.raises(KeyError, match="missing"):
+        snapshot.decision("missing")
+
+
+def test_registry_and_snapshot_digests_are_deterministic_and_policy_sensitive() -> None:
+    first = resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "canary"})
+    second = resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "canary"})
+    equivalent = dict(reversed(list(FEATURES.items())))
+    changed = dict(FEATURES)
+    changed["tool_result_interceptors"] = FeatureSpec(
+        "tool_result_interceptors", RolloutChannel.BETA
+    )
+
+    assert first.registry_digest == second.registry_digest == registry_digest(equivalent)
+    assert first.snapshot_digest == second.snapshot_digest
+    assert registry_digest(changed) != first.registry_digest
+    assert json.dumps(first.to_dict(), sort_keys=True) == json.dumps(
+        second.to_dict(), sort_keys=True
+    )
+
+
+def test_pipeline_uses_config_snapshot_after_environment_mutation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("HEADROOM_ROLLOUT_CHANNEL", raising=False)
+    monkeypatch.delenv("HEADROOM_FEATURES", raising=False)
+    config = HeadroomConfig()
+    original_digest = config.rollout.snapshot_digest if config.rollout else None
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "canary")
+    monkeypatch.setenv("HEADROOM_FEATURES", "tool_result_interceptors")
+
+    pipeline = TransformPipeline(config)
+
+    assert config.rollout is not None
+    assert config.rollout.snapshot_digest == original_digest
+    assert all(
+        type(transform).__name__ != "ToolResultInterceptorTransform"
+        for transform in pipeline.transforms
+    )
+
+
+def test_cli_json_status_and_strict_error() -> None:
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "rollout",
+            "status",
+            "--channel",
+            "canary",
+            "--features",
+            "tool_result_interceptors",
+            "--json",
+        ],
+    )
+    invalid = runner.invoke(main, ["rollout", "status", "--features", "typo", "--json"])
+
+    assert result.exit_code == 0
+    payload = json.loads(result.output)
+    assert payload["channel"] == "canary"
+    assert payload["features"][2]["name"] == "tool_result_interceptors"
+    assert invalid.exit_code != 0
+    assert "unknown rollout feature" in invalid.output
+
+
+def test_cli_human_status_exercises_disable_and_unsafe_options() -> None:
+    result = CliRunner().invoke(
+        main,
+        [
+            "rollout",
+            "status",
+            "--channel",
+            "stable",
+            "--features",
+            "tool_result_interceptors",
+            "--disable-features",
+            "read_maturation",
+            "--unsafe-allow-unstable-features",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert "Rollout channel: stable" in result.output
+    assert "Qualification eligible: false" in result.output
+    assert "tool_result_interceptors: enabled=true decision=unsafe_override" in result.output
+    assert "read_maturation: enabled=false decision=disabled" in result.output
+
+
+@pytest.mark.parametrize(
+    ("option", "message", "required_channel"),
+    [
+        ("--read-maturation", "--read-maturation is not available", "beta"),
+        (
+            "--intercept-tool-results",
+            "--intercept-tool-results is not available",
+            "canary",
+        ),
+    ],
+)
+def test_proxy_cli_fails_loudly_when_explicit_feature_is_channel_blocked(
+    option: str, message: str, required_channel: str
+) -> None:
+    result = CliRunner().invoke(
+        main,
+        ["proxy", option],
+        env={"HEADROOM_ROLLOUT_CHANNEL": "stable"},
+    )
+
+    assert result.exit_code == 1
+    assert message in result.output
+    assert f"HEADROOM_ROLLOUT_CHANNEL={required_channel}" in result.output
+
+
+def test_shared_python_rust_policy_vectors() -> None:
+    vectors = json.loads(
+        (Path(__file__).parent / "fixtures" / "rollout_policy_vectors.json").read_text()
+    )
+    for vector in vectors:
+        env = {"HEADROOM_ROLLOUT_CHANNEL": vector["channel"]}
+        if vector["requested"]:
+            env["HEADROOM_FEATURES"] = "tool_result_interceptors"
+        if vector["disabled"]:
+            env["HEADROOM_DISABLE_FEATURES"] = "tool_result_interceptors"
+        if vector["unsafe"]:
+            env["HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES"] = "1"
+        decision = resolve_rollout(env).decision("tool_result_interceptors")
+        assert decision.enabled is vector["enabled"]
+        assert decision.reason.value == vector["decision"]
diff --git a/tests/test_route_advice.py b/tests/test_route_advice.py
new file mode 100644
index 000000000..9e84bee9c
--- /dev/null
+++ b/tests/test_route_advice.py
@@ -0,0 +1,289 @@
+"""Per-request backend selection published by an extension.
+
+The property under test throughout is the one that makes this safe to merge:
+with nothing published, every path is exactly what it was before.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from headroom.proxy.route_advice import (
+    BackendResolver,
+    RouteAdvice,
+    advice_from,
+)
+
+
+class _Req:
+    def __init__(self, **state):
+        self.state = SimpleNamespace(**state)
+
+
+DEFAULT = object()  # stands in for the configured backend
+
+
+# --- reading what an extension published ------------------------------------
+
+
+def test_no_extension_means_no_advice():
+    assert advice_from(_Req()) is None
+    assert advice_from(object()) is None  # no .state at all
+    assert advice_from(None) is None
+
+
+def test_advice_is_duck_typed_so_extensions_need_not_import_us():
+    a = advice_from(
+        _Req(
+            headroom_route=SimpleNamespace(
+                model="moonshot/kimi-k2", provider="moonshot", reason="cheaper"
+            )
+        )
+    )
+    assert a == RouteAdvice("moonshot/kimi-k2", "moonshot", "cheaper")
+
+
+def test_an_extension_may_omit_everything_but_the_model():
+    a = advice_from(_Req(headroom_route=SimpleNamespace(model="gpt-5-mini")))
+    assert a.model == "gpt-5-mini" and a.provider == ""
+
+
+def test_malformed_advice_is_ignored_rather_than_raised():
+    for bad in (
+        SimpleNamespace(),
+        SimpleNamespace(model=""),
+        SimpleNamespace(model=123),
+        "not an object",
+    ):
+        assert advice_from(_Req(headroom_route=bad)) is None
+
+
+def test_advice_needs_a_model():
+    with pytest.raises(ValueError):
+        RouteAdvice("")
+
+
+# --- absent means unchanged, which is the whole safety argument -------------
+
+
+def test_no_advice_returns_the_configured_backend():
+    r = BackendResolver(DEFAULT)
+    assert r.for_request(_Req()) is DEFAULT
+
+
+def test_no_advice_and_no_configured_backend_stays_none():
+    """None is not "no backend", it is the direct-API path. It must survive."""
+    assert BackendResolver(None).for_request(_Req()) is None
+
+
+def test_a_native_provider_does_not_switch_backends():
+    """Anthropic is the shape the proxy already holds, so a model rewrite is
+    enough and the extension has already done it."""
+    r = BackendResolver(DEFAULT)
+    req = _Req(headroom_route=SimpleNamespace(model="claude-haiku-4-5", provider="anthropic"))
+    assert r.for_request(req) is DEFAULT
+
+
+def test_a_bare_anthropic_model_resolves_its_provider_and_stays_put():
+    r = BackendResolver(DEFAULT)
+    req = _Req(headroom_route=SimpleNamespace(model="claude-haiku-4-5"))
+    assert r.for_request(req) is DEFAULT
+
+
+# --- switching, and refusing to switch --------------------------------------
+
+
+def test_a_foreign_provider_gets_its_own_backend(monkeypatch):
+    built = []
+
+    class FakeBackend:
+        def __init__(self, provider):
+            built.append(provider)
+            self.provider = provider
+
+    monkeypatch.setattr(BackendResolver, "_build", lambda self, p: FakeBackend(p))
+    r = BackendResolver(DEFAULT)
+    body = {"model": "claude-opus-5"}
+    req = _Req(headroom_route=SimpleNamespace(model="moonshot/kimi-k2", provider="moonshot"))
+    got = r.for_request(req, body=body)
+    assert isinstance(got, FakeBackend) and got.provider == "moonshot"
+    # The extension could not safely write a foreign model id; we do it.
+    assert body["model"] == "moonshot/kimi-k2"
+
+
+def test_backends_are_built_once_per_provider(monkeypatch):
+    built = []
+    monkeypatch.setattr(BackendResolver, "_build", lambda self, p: built.append(p) or object())
+    r = BackendResolver(DEFAULT)
+    req = _Req(headroom_route=SimpleNamespace(model="x", provider="moonshot"))
+    for _ in range(5):
+        r.for_request(req)
+    assert built == ["moonshot"], "construction is expensive; cache it"
+
+
+def test_a_backend_that_will_not_build_falls_back_and_stops_retrying(monkeypatch):
+    calls = []
+    monkeypatch.setattr(BackendResolver, "_build", lambda self, p: calls.append(p) or None)
+    r = BackendResolver(DEFAULT)
+    req = _Req(headroom_route=SimpleNamespace(model="x", provider="nope"))
+    for _ in range(5):
+        assert r.for_request(req) is DEFAULT
+    assert calls == ["nope"], "a broken provider must not be retried per request"
+
+
+def test_a_routing_preference_can_never_take_traffic_down(monkeypatch):
+    """Missing credentials, missing optional dependency -- whatever the reason,
+    the request still has to be served."""
+
+    def boom(self, provider):
+        raise RuntimeError("no credentials")
+
+    monkeypatch.setattr(BackendResolver, "_build", boom)
+    r = BackendResolver(DEFAULT)
+    req = _Req(headroom_route=SimpleNamespace(model="x", provider="moonshot"))
+    assert r.for_request(req) is DEFAULT
+
+
+def test_an_unknown_provider_is_rejected_at_resolve_time():
+    """LiteLLMBackend accepts ANY provider string -- the registry falls through
+    to a generic pass-through -- so a typo silently builds a backend that only
+    fails later, at request time, with an error pointing nowhere near the typo.
+    Validate the name up front instead."""
+    r = BackendResolver(DEFAULT)
+    assert r._build("definitely-not-a-provider-name") is None
+    req = _Req(headroom_route=SimpleNamespace(model="x", provider="definitely-not-a-provider-name"))
+    assert r.for_request(req) is DEFAULT
+
+
+def test_a_real_provider_name_is_accepted():
+    assert BackendResolver(DEFAULT)._build("moonshot") is not None
+
+
+# --- streaming, which is the path agents actually take ----------------------
+
+
+class _Backend:
+    """Records that it, and not some other backend, served the request."""
+
+    def __init__(self, name):
+        self.name = name
+        self.served = False
+
+    async def stream_message(self, body, headers):
+        self.served = True
+        return
+        yield  # pragma: no cover -- makes this an async generator
+
+    async def stream_openai_message(self, body, headers):
+        self.served = True
+        return
+        yield  # pragma: no cover
+
+
+async def _drive(handler, **kw):
+    from headroom.proxy.handlers.streaming import StreamingMixin
+
+    resp = await StreamingMixin._stream_response_bedrock(
+        handler,
+        {"messages": []},
+        {},
+        "anthropic",
+        "m",
+        "rid",
+        0,
+        0,
+        0,
+        [],
+        {},
+        0.0,
+        **kw,
+    )
+    async for _ in resp.body_iterator:
+        pass
+
+
+class _Config:
+    """Every proxy flag off. Named individually the list would rot; the test
+    is about which backend served the request, not about config."""
+
+    def __getattr__(self, name):
+        return False
+
+
+def _handler(default):
+    return SimpleNamespace(
+        anthropic_backend=default,
+        config=_Config(),
+        _record_request_outcome=lambda outcome: _noop(),
+    )
+
+
+async def _noop():
+    return None
+
+
+def test_streaming_honours_the_routed_backend():
+    """The non-streaming branch was the easy half. body["model"] has already
+    been rewritten to a foreign id by the time we get here, so streaming to
+    the configured backend would send e.g. moonshot/kimi-k2 to Anthropic."""
+    configured, routed = _Backend("anthropic"), _Backend("moonshot")
+    asyncio.run(_drive(_handler(configured), backend=routed))
+    assert routed.served and not configured.served
+
+
+def test_streaming_without_a_route_uses_the_configured_backend():
+    configured = _Backend("anthropic")
+    asyncio.run(_drive(_handler(configured)))
+    assert configured.served
+
+
+async def _drive_openai(handler, **kw):
+    from headroom.proxy.handlers.streaming import StreamingMixin
+
+    resp = await StreamingMixin._stream_openai_via_backend(
+        handler,
+        {"messages": []},
+        {},
+        "m",
+        "rid",
+        0.0,
+        0,
+        0,
+        0,
+        [],
+        {},
+        0.0,
+        **kw,
+    )
+    async for _ in resp.body_iterator:
+        pass
+
+
+def test_openai_streaming_honours_the_routed_backend():
+    """opencode and pi can speak either protocol, so the OpenAI chat path
+    needs the same treatment as the Anthropic one."""
+    configured, routed = _Backend("openai"), _Backend("moonshot")
+    asyncio.run(_drive_openai(_handler(configured), backend=routed))
+    assert routed.served and not configured.served
+
+
+def test_openai_streaming_without_a_route_uses_the_configured_backend():
+    configured = _Backend("openai")
+    asyncio.run(_drive_openai(_handler(configured)))
+    assert configured.served
+
+
+def test_the_resolver_follows_a_reassigned_default():
+    class H:
+        anthropic_backend = None
+
+    h = H()
+    from headroom.proxy.route_advice import BackendResolver as BR
+
+    first = BR(h.anthropic_backend)
+    assert first.default is None
+    h.anthropic_backend = DEFAULT
+    assert BR(h.anthropic_backend).default is DEFAULT
diff --git a/tests/test_runtime_env.py b/tests/test_runtime_env.py
index 401d2ad50..7887190b0 100644
--- a/tests/test_runtime_env.py
+++ b/tests/test_runtime_env.py
@@ -14,6 +14,7 @@ pytest.importorskip("httpx")
 from fastapi.testclient import TestClient  # noqa: E402
 
 from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+from headroom.rollout import resolve_rollout  # noqa: E402
 
 
 @pytest.fixture(autouse=True)
@@ -155,11 +156,78 @@ def test_admin_runtime_env_applies_and_reflects_in_health(loopback_client):
     assert health["HEADROOM_VERBOSITY_LEVEL"] == "3"
 
 
+@pytest.mark.parametrize(
+    ("rollout", "expected_enabled", "expected_reason"),
+    [
+        (resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "beta"}), True, "legacy_alias"),
+        (resolve_rollout({}), False, "blocked_by_channel"),
+        (
+            resolve_rollout(
+                {
+                    "HEADROOM_ROLLOUT_CHANNEL": "beta",
+                    "HEADROOM_DISABLE_FEATURES": "proxy_output_shaper",
+                }
+            ),
+            False,
+            "disabled",
+        ),
+    ],
+)
+def test_admin_runtime_env_reresolves_running_rollout_without_weakening_policy(
+    rollout, expected_enabled, expected_reason
+):
+    app = create_app(
+        ProxyConfig(
+            rollout=rollout,
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            cost_tracking_enabled=False,
+        )
+    )
+    with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client:
+        before = client.get("/stats?cached=1").json()["rollout"]
+        response = client.post("/admin/runtime-env", json={"HEADROOM_OUTPUT_SHAPER": "1"})
+        after = client.get("/stats?cached=1").json()["rollout"]
+
+    decision = next(item for item in after["features"] if item["name"] == "proxy_output_shaper")
+    assert response.status_code == 200
+    assert response.json()["rollout"] == after
+    assert decision["enabled"] is expected_enabled
+    assert decision["decision"] == expected_reason
+    assert after["snapshot_digest"] != before["snapshot_digest"]
+
+
 def test_admin_runtime_env_rejects_non_object(loopback_client):
     resp = loopback_client.post("/admin/runtime-env", json=["not", "a", "dict"])
     assert resp.status_code == 400
 
 
+def test_admin_runtime_env_rejects_process_local_update_with_multiple_workers(monkeypatch):
+    monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")
+    rollout = resolve_rollout({"HEADROOM_ROLLOUT_CHANNEL": "beta"})
+    config = ProxyConfig(
+        worker_processes=2,
+        rollout=rollout,
+        optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+    )
+    app = create_app(config)
+    before_digest = rollout.snapshot_digest
+
+    with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client:
+        response = client.post("/admin/runtime-env", json={"HEADROOM_OUTPUT_SHAPER": "1"})
+        after = client.get("/stats").json()["rollout"]
+
+    assert response.status_code == 409
+    assert response.json()["worker_processes"] == 2
+    assert "restart" in response.json()["error"]
+    assert rt.getenv("HEADROOM_OUTPUT_SHAPER") is None
+    assert after["snapshot_digest"] == before_digest
+
+
 def test_admin_runtime_env_is_loopback_only():
     config = ProxyConfig(
         optimize=False,
diff --git a/tests/test_savings_ledger_before_forwarded.py b/tests/test_savings_ledger_before_forwarded.py
index 52a10a133..c50f6b938 100644
--- a/tests/test_savings_ledger_before_forwarded.py
+++ b/tests/test_savings_ledger_before_forwarded.py
@@ -21,8 +21,11 @@ class _FakeSavingsTracker:
 
 
 class _FakeOtelMetrics:
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+
     def record_proxy_request(self, **kwargs: Any) -> None:
-        pass
+        self.calls.append(kwargs)
 
 
 @pytest.mark.asyncio
@@ -63,3 +66,92 @@ async def test_record_savings_event_uses_original_input_as_before(
             "source": "proxy",
         }
     ]
+
+
+@pytest.mark.asyncio
+async def test_record_request_forwards_tool_savings_to_otel() -> None:
+    otel = _FakeOtelMetrics()
+    metrics = prometheus_metrics.PrometheusMetrics(
+        savings_tracker=_FakeSavingsTracker(),
+        otel_metrics=otel,
+    )
+
+    await metrics.record_request(
+        provider="anthropic",
+        model="claude-opus-4-6",
+        input_tokens=600,
+        output_tokens=25,
+        tokens_saved=400,
+        tool_search_saved=13182,
+        latency_ms=10.0,
+    )
+
+    assert len(otel.calls) == 1
+    assert otel.calls[0]["tokens_saved"] == 400
+    assert otel.calls[0]["tool_search_saved"] == 13182
+
+
+def _capture_ledger(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Any]]:
+    calls: list[dict[str, Any]] = []
+    monkeypatch.setattr(
+        prometheus_metrics.savings_ledger,
+        "record_savings_event",
+        lambda **kwargs: calls.append(kwargs),
+    )
+    return calls
+
+
+@pytest.mark.asyncio
+async def test_record_savings_event_includes_tool_search_deferral(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """tool_search_deferral savings must ride into the ledger delta so
+    `headroom savings` does not undercount tool-search sessions ~7-10x (#2795)."""
+    calls = _capture_ledger(monkeypatch)
+    metrics = prometheus_metrics.PrometheusMetrics(
+        savings_tracker=_FakeSavingsTracker(),
+        otel_metrics=_FakeOtelMetrics(),
+    )
+    await metrics.record_request(
+        provider="anthropic",
+        model="claude-opus-4-6",
+        input_tokens=109844,  # forwarded (post-compression) message count
+        output_tokens=25,
+        tokens_saved=1896,
+        tool_search_saved=13182,  # deferred tool schemas never sent
+        latency_ms=10.0,
+        client="claude-code",
+    )
+
+    assert len(calls) == 1
+    # saved = tokens_saved + tool_search_saved; before = forwarded + saved.
+    assert calls[0]["tokens_after"] == 109844
+    assert calls[0]["tokens_before"] == 109844 + 1896 + 13182  # == 124922
+
+
+@pytest.mark.asyncio
+async def test_record_savings_event_written_for_deferral_only_turn(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A tool-heavy turn can defer thousands of tool-schema tokens while
+    tokens_saved is 0 (deferral does not move the message-level count). It must
+    still be recorded, not dropped from the ledger (#2795)."""
+    calls = _capture_ledger(monkeypatch)
+    metrics = prometheus_metrics.PrometheusMetrics(
+        savings_tracker=_FakeSavingsTracker(),
+        otel_metrics=_FakeOtelMetrics(),
+    )
+    await metrics.record_request(
+        provider="anthropic",
+        model="claude-opus-4-6",
+        input_tokens=50000,
+        output_tokens=25,
+        tokens_saved=0,
+        tool_search_saved=13182,
+        latency_ms=10.0,
+        client="claude-code",
+    )
+
+    assert len(calls) == 1
+    assert calls[0]["tokens_before"] == 50000 + 13182
+    assert calls[0]["tokens_after"] == 50000
diff --git a/tests/test_savings_tracker_litellm_resolution_cache.py b/tests/test_savings_tracker_litellm_resolution_cache.py
new file mode 100644
index 000000000..04300bf12
--- /dev/null
+++ b/tests/test_savings_tracker_litellm_resolution_cache.py
@@ -0,0 +1,88 @@
+"""Regression: `_resolve_litellm_model`'s cache must be bounded (PR #2860 review).
+
+A plain unbounded dict cache keyed by a client-controlled model string is a
+memory-retention path on a request-facing proxy: a caller can grow it without
+limit by sending a new model name on every request. The fix uses a bounded
+`functools.lru_cache`. These tests pin the three properties that actually
+matter, independent of the litellm pricing behavior covered elsewhere:
+
+- repeated resolution of the same unresolvable model only probes litellm once
+- the cache never grows past its bound, no matter how many distinct model
+  names get resolved
+- an evicted name is transparently re-probed (never silently wrong or stuck)
+  rather than growing the cache further
+"""
+
+from __future__ import annotations
+
+import types
+
+from headroom.proxy import savings_tracker as st
+
+
+def _fake_litellm_always_unresolvable(probe_calls: dict[str, int]) -> types.SimpleNamespace:
+    """A fake litellm where every model is unpriced and unresolvable.
+
+    `cost_per_token` always raises — exactly what a real custom/local model
+    litellm has never heard of does — which is the call this cache exists to
+    memoize (see the comment above `_resolve_litellm_model` in
+    savings_tracker.py: that raise is also where real litellm prints its
+    noisy "Provider List" banner, #2851).
+    """
+
+    def cost_per_token(*, model, prompt_tokens, completion_tokens):
+        probe_calls[model] = probe_calls.get(model, 0) + 1
+        raise RuntimeError("unknown model")
+
+    return types.SimpleNamespace(model_cost={}, cost_per_token=cost_per_token)
+
+
+def test_resolve_litellm_model_probes_unknown_model_once(monkeypatch):
+    probe_calls: dict[str, int] = {}
+    monkeypatch.setattr(
+        st, "_get_litellm_module", lambda: _fake_litellm_always_unresolvable(probe_calls)
+    )
+
+    for _ in range(5):
+        resolved = st._resolve_litellm_model("widget-local-model")
+        assert resolved == "widget-local-model"
+
+    assert probe_calls == {"widget-local-model": 1}
+
+
+def test_resolve_litellm_model_cache_is_bounded(monkeypatch):
+    probe_calls: dict[str, int] = {}
+    monkeypatch.setattr(
+        st, "_get_litellm_module", lambda: _fake_litellm_always_unresolvable(probe_calls)
+    )
+
+    extra_beyond_bound = 50
+    for i in range(st._MODEL_RESOLUTION_CACHE_MAXSIZE + extra_beyond_bound):
+        st._resolve_litellm_model(f"widget-local-model-{i}")
+
+    info = st._resolve_litellm_model.cache_info()
+    assert info.maxsize == st._MODEL_RESOLUTION_CACHE_MAXSIZE
+    # However many distinct names were resolved, the cache itself never
+    # grows past its bound -- this is the actual memory-retention fix.
+    assert info.currsize == st._MODEL_RESOLUTION_CACHE_MAXSIZE
+
+
+def test_resolve_litellm_model_evicted_name_reprobes(monkeypatch):
+    probe_calls: dict[str, int] = {}
+    monkeypatch.setattr(
+        st, "_get_litellm_module", lambda: _fake_litellm_always_unresolvable(probe_calls)
+    )
+
+    st._resolve_litellm_model("seed-model")
+    assert probe_calls["seed-model"] == 1
+
+    # Push exactly `maxsize` new distinct names through without ever touching
+    # "seed-model" again -- LRU eviction must push it out to make room.
+    for i in range(st._MODEL_RESOLUTION_CACHE_MAXSIZE):
+        st._resolve_litellm_model(f"filler-model-{i}")
+
+    # A resolvable name being evicted is not a correctness bug (it just
+    # re-probes) -- the assertion that matters is that it *does* re-probe
+    # rather than silently reusing a slot it no longer legitimately owns.
+    st._resolve_litellm_model("seed-model")
+    assert probe_calls["seed-model"] == 2
diff --git a/tests/test_ssl_context.py b/tests/test_ssl_context.py
index dda61f854..9b78ae874 100644
--- a/tests/test_ssl_context.py
+++ b/tests/test_ssl_context.py
@@ -49,6 +49,7 @@ Tfx2hBGZ0UogmREaXFi099rmaueZ0HIBn51b3kYqc7of5TI0fHwSHF4GdXXs2OZi
 kF9agIt8Q8t/2kviMn2roInGTwTyPYOEQV0m
 -----END CERTIFICATE-----
 """
+_TEST_CA_COUNT = 1
 
 
 @pytest.fixture()
@@ -70,6 +71,10 @@ def _clean_env(monkeypatch):
         monkeypatch.delenv(var, raising=False)
 
 
+def _default_x509_ca_count() -> int:
+    return ssl.create_default_context().cert_store_stats()["x509_ca"]
+
+
 class FakeSSLContext:
     def __init__(self, verify_flags: int = 0) -> None:
         self.verify_flags = verify_flags
@@ -136,9 +141,10 @@ class TestFindCaBundleWithValidPem:
         ctx = find_ca_bundle()
         assert isinstance(ctx, ssl.SSLContext)
         stats = ctx.cert_store_stats()
-        # The default trust store has dozens of CAs; if only the test cert
-        # were loaded (replacement), x509_ca would be 1.
-        assert stats["x509_ca"] > 1
+        # Additive loading preserves whatever the runner's default trust store
+        # contains. Some minimal CI images have a tiny or empty default store, so
+        # compare against the local baseline instead of assuming "dozens" of CAs.
+        assert stats["x509_ca"] >= _default_x509_ca_count() + _TEST_CA_COUNT
 
 
 class TestFindCaBundlePriority:
@@ -265,8 +271,9 @@ class TestBuildHttpxVerify:
             assert ctx.verify_flags & strict_flag == 0
         # Still a real verifying context — NOT verify=False.
         assert ctx.verify_mode == ssl.CERT_REQUIRED
-        # Default trust store retained (additive, not a 1-cert replacement).
-        assert ctx.cert_store_stats()["x509_ca"] > 1
+        # Default trust store retained for this runner, not replaced by a custom
+        # one-cert bundle.
+        assert ctx.cert_store_stats()["x509_ca"] == _default_x509_ca_count()
 
     def test_custom_ca_takes_precedence_over_toggle(self, monkeypatch, ca_pem_file):
         """A configured CA bundle wins; the result is that bundle's context."""
diff --git a/tests/test_subscription_session_tracking.py b/tests/test_subscription_session_tracking.py
index 058846ced..9074c7f58 100644
--- a/tests/test_subscription_session_tracking.py
+++ b/tests/test_subscription_session_tracking.py
@@ -87,3 +87,44 @@ def test_read_transcript_lines_preserves_small_transcript(
         '{"marker":"first"}',
         '{"marker":"second"}',
     ]
+
+
+def test_compute_window_tokens_dedups_usage_by_message_id(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """A single response stored across multiple transcript lines (one per content
+    block, same message.usage) must be counted once, not per line (#2340)."""
+    timestamp = "2026-01-01T00:00:00Z"
+    dup = {
+        "timestamp": timestamp,
+        "message": {
+            "id": "msg_dup",
+            "model": "claude-opus-4-1",
+            "usage": {"input_tokens": 100, "output_tokens": 10},
+        },
+    }
+    other = {
+        "timestamp": timestamp,
+        "message": {
+            "id": "msg_other",
+            "model": "claude-opus-4-1",
+            "usage": {"input_tokens": 5, "output_tokens": 2},
+        },
+    }
+    noid = {
+        "timestamp": timestamp,
+        "message": {"model": "claude-opus-4-1", "usage": {"input_tokens": 1, "output_tokens": 1}},
+    }
+    lines = [dup, dup, dup, other, noid]
+    transcript = tmp_path / "session.jsonl"
+    transcript.write_text("\n".join(json.dumps(e) for e in lines) + "\n", encoding="utf-8")
+    monkeypatch.setattr(session_tracking, "find_transcript_files", lambda: [transcript])
+
+    entry_ts = datetime.fromisoformat(timestamp.replace("Z", "+00:00")).timestamp()
+    tokens = session_tracking.compute_window_tokens(entry_ts - 1, entry_ts + 1)
+
+    # msg_dup counted once (100), msg_other (5), id-less line (1) -> 106, NOT 306.
+    assert tokens.input == 106
+    assert tokens.output == 13
+    assert tokens.by_model["claude-opus-4-1"]["input"] == 106
diff --git a/tests/test_toin_retention.py b/tests/test_toin_retention.py
new file mode 100644
index 000000000..c43f95c05
--- /dev/null
+++ b/tests/test_toin_retention.py
@@ -0,0 +1,100 @@
+"""Regression tests for TOIN privacy and bounded retention."""
+
+from __future__ import annotations
+
+import json
+
+from headroom.telemetry.backends.filesystem import FileSystemTOINBackend
+from headroom.telemetry.models import ToolSignature
+from headroom.telemetry.toin import TOINConfig, ToolIntelligenceNetwork
+
+
+def _signature(index: int) -> ToolSignature:
+    return ToolSignature.from_items([{f"field_{index}": "x"}])
+
+
+def test_free_form_queries_are_not_persisted() -> None:
+    toin = ToolIntelligenceNetwork(TOINConfig(storage_path=""))
+
+    assert toin._anonymize_query_pattern("show me the contents of /private/secret.txt") is None
+    assert toin._anonymize_query_pattern("status:error AND user:john") == "status:* user:*"
+
+    toin.record_retrieval(
+        "signature",
+        retrieval_type="search",
+        query="show me the contents of /private/secret.txt",
+    )
+    pattern = toin.get_pattern("signature")
+    assert pattern is not None
+    assert pattern.query_pattern_frequency == {}
+
+
+def test_query_pattern_length_is_bounded() -> None:
+    toin = ToolIntelligenceNetwork(TOINConfig(storage_path=""))
+
+    assert toin._anonymize_query_pattern("field:" + "x" * 1000) == "field:*"
+    assert toin._anonymize_query_pattern(" ".join(f"field{i}:x" for i in range(200))) is None
+
+
+def test_pattern_table_evicts_old_low_sample_patterns() -> None:
+    config = TOINConfig(storage_path="", max_patterns=2)
+    toin = ToolIntelligenceNetwork(config)
+
+    for index in range(3):
+        toin.record_compression(
+            tool_signature=_signature(index),
+            original_count=10,
+            compressed_count=5,
+            original_tokens=100,
+            compressed_tokens=50,
+            strategy="test",
+        )
+
+    assert len(toin._patterns) == 2
+    assert _signature(0).structure_hash not in {
+        pattern.tool_signature_hash for pattern in toin._patterns.values()
+    }
+
+
+def test_legacy_raw_query_keys_are_removed_on_load(tmp_path) -> None:
+    path = tmp_path / "toin.json"
+    payload = {
+        "version": "2.0",
+        "patterns": {
+            "unknown|unknown|abc": {
+                "tool_signature_hash": "abc",
+                "query_pattern_frequency": {
+                    "raw prompt containing secret source code": 4,
+                    "status:* user:*": 2,
+                },
+                "common_query_patterns": [
+                    "raw prompt containing secret source code",
+                    "status:* user:*",
+                ],
+            }
+        },
+    }
+    path.write_text(json.dumps(payload), encoding="utf-8")
+
+    toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path)))
+    pattern = next(iter(toin._patterns.values()))
+
+    assert pattern.query_pattern_frequency == {"status:* user:*": 2}
+    assert pattern.common_query_patterns == ["status:* user:*"]
+
+
+def test_filesystem_backend_writes_compact_json(tmp_path) -> None:
+    path = tmp_path / "toin.json"
+    FileSystemTOINBackend(str(path)).save({"patterns": {"a": {"value": 1}}})
+
+    assert "\n" not in path.read_text(encoding="utf-8")
+    assert "  " not in path.read_text(encoding="utf-8")
+
+
+def test_filesystem_backend_skips_oversized_store(tmp_path) -> None:
+    path = tmp_path / "toin.json"
+    path.write_text("x" * 100, encoding="utf-8")
+
+    backend = FileSystemTOINBackend(str(path), max_load_bytes=10)
+    assert backend.load() == {}
+    assert path.exists()
diff --git a/tests/test_token_count_cache.py b/tests/test_token_count_cache.py
new file mode 100644
index 000000000..c90427870
--- /dev/null
+++ b/tests/test_token_count_cache.py
@@ -0,0 +1,108 @@
+"""The token-count memo must be invisible: same integers, or it is a bug.
+
+These counts feed context_pressure -> min_ratio -> which blocks get compressed,
+so "the cache returned a different number" is a compression regression, not a
+cache miss. Every test here is an equality test for that reason.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from headroom.providers.anthropic import AnthropicProvider
+from headroom.tokenizers.base import TokenCountCache
+from headroom.tokenizers.estimator import EstimatingTokenCounter
+from headroom.tokenizers.tiktoken_counter import TiktokenCounter
+
+BODIES = [
+    "word " * 500,
+    json.dumps([{"id": i, "name": f"item-{i}", "ok": i % 2 == 0} for i in range(300)]),
+    "def f(x):\n    return x + 1\n" * 200,
+    "2026-08-06 13:00:00 INFO worker did a thing\n" * 400,
+    "日本語のテキストをここに置きます。" * 200,
+    "<|endoftext|> literal special token marker " * 100,  # forces the ValueError path
+    "x" * 300,
+]
+
+
+def _counters():
+    return [
+        ("anthropic", AnthropicProvider().get_token_counter("claude-sonnet-5")),
+        ("tiktoken", TiktokenCounter(model="gpt-4o")),
+        ("estimator-auto", EstimatingTokenCounter()),
+        ("estimator-fixed", EstimatingTokenCounter(chars_per_token=3.5)),
+    ]
+
+
+@pytest.mark.filterwarnings("ignore::UserWarning")
+@pytest.mark.parametrize("body", BODIES)
+def test_cached_count_equals_uncached(body: str) -> None:
+    for name, counter in _counters():
+        counter._count_cache.clear()
+        first = counter.count_text(body)  # miss, populates
+        second = counter.count_text(body)  # hit
+        counter._count_cache.clear()
+        third = counter.count_text(body)  # miss again
+        assert first == second == third, f"{name}: {first} != {second} != {third}"
+
+
+@pytest.mark.filterwarnings("ignore::UserWarning")
+def test_empty_and_tiny_text_still_correct() -> None:
+    for _name, counter in _counters():
+        assert counter.count_text("") == 0
+        assert counter.count_text("hi") == counter.count_text("hi")
+
+
+def test_cache_clears_when_full_rather_than_growing() -> None:
+    cache = TokenCountCache(min_chars=1, max_entries=4, max_chars=10**9)
+    for i in range(10):
+        cache.put(f"text-number-{i}", i)
+    assert len(cache._counts) <= 4
+
+
+def test_cache_respects_the_character_budget() -> None:
+    cache = TokenCountCache(min_chars=1, max_entries=10**6, max_chars=1000)
+    for i in range(50):
+        cache.put("x" * 100 + str(i), i)
+    assert cache._chars <= 1000 + 200  # one entry may straddle the cap
+
+
+def test_small_strings_are_not_cached() -> None:
+    """They encode in microseconds; caching them would evict the entries that matter."""
+    cache = TokenCountCache(min_chars=256)
+    cache.put("short", 1)
+    assert cache.get("short") is None
+
+
+def test_distinct_texts_do_not_collide() -> None:
+    cache = TokenCountCache(min_chars=1)
+    cache.put("alpha", 1)
+    cache.put("beta", 2)
+    assert (cache.get("alpha"), cache.get("beta"), cache.get("gamma")) == (1, 2, None)
+
+
+@pytest.mark.filterwarnings("ignore::UserWarning")
+def test_counters_do_not_share_a_cache_across_encodings() -> None:
+    """cl100k and o200k are both live in one process; a shared memo would mix them."""
+    a = TiktokenCounter(encoding="cl100k_base")
+    b = TiktokenCounter(encoding="o200k_base")
+    body = "tokenization differs between these two encodings. " * 100
+    assert a.count_text(body) == a.count_text(body)
+    assert b.count_text(body) == b.count_text(body)
+    assert a._count_cache is not b._count_cache
+
+
+@pytest.mark.filterwarnings("ignore::UserWarning")
+def test_concurrent_counting_is_consistent() -> None:
+    """The pipeline runs on a thread pool and shares one counter."""
+    from concurrent.futures import ThreadPoolExecutor
+
+    counter = AnthropicProvider().get_token_counter("claude-sonnet-5")
+    bodies = [f"{b}\n{i}" for i, b in enumerate(BODIES * 3)]
+    expected = {b: counter.count_text(b) for b in bodies}
+    counter._count_cache.clear()
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        got = list(pool.map(counter.count_text, bodies))
+    assert got == [expected[b] for b in bodies]
diff --git a/tests/test_tokenizer_count_offload.py b/tests/test_tokenizer_count_offload.py
index e4d77e4bc..e59b001a4 100644
--- a/tests/test_tokenizer_count_offload.py
+++ b/tests/test_tokenizer_count_offload.py
@@ -176,8 +176,12 @@ async def test_count_tokens_offloaded_fails_open_on_executor_quarantine() -> Non
 
     proxy = _make_proxy()
     # Record a concurrent compression as timed out so the real executor guard
-    # quarantines the next call — no mock of the helper itself.
+    # quarantines the next call — no mock of the helper itself. Since the
+    # quarantine became time-capped (#2412), standing debt alone no longer
+    # quarantines: the deadline armed by the fresh timeout must still be in
+    # the future, so arm it the way a real timeout would.
     proxy._compression_timed_out_in_flight = 1
+    proxy._compression_quarantine_deadline = time.monotonic() + 60.0
 
     tokenizer, tokens = await proxy._count_tokens_offloaded(
         "qwen2.5-coder", [{"role": "user", "content": "hello world"}]
@@ -193,7 +197,10 @@ async def test_count_tokens_offloaded_returns_count_text_capable_tokenizer() ->
     that need per-fragment accounting."""
     proxy = _make_proxy()
     # Quarantine forces the fail-open branch (an EstimatingTokenCounter).
+    # Post-#2412 the quarantine is time-capped, so the deadline must be armed
+    # alongside the standing debt.
     proxy._compression_timed_out_in_flight = 1
+    proxy._compression_quarantine_deadline = time.monotonic() + 60.0
 
     # The empty-messages count is intentionally discarded by that handler
     # (it sums text parts itself), so only the tokenizer matters here.
diff --git a/tests/test_tool_result_interceptors.py b/tests/test_tool_result_interceptors.py
index 421c82344..432c2c51b 100644
--- a/tests/test_tool_result_interceptors.py
+++ b/tests/test_tool_result_interceptors.py
@@ -704,8 +704,9 @@ def test_transform_adapter_tokens_before_is_baseline_not_reconstruction(tokenize
 
 
 def test_proxy_pipeline_includes_interceptor_when_env_enabled(monkeypatch):
-    """When HEADROOM_INTERCEPT_ENABLED=1, ToolResultInterceptorTransform is at index 0 in both pipelines."""
+    """An eligible legacy request installs the interceptor in both pipelines."""
     monkeypatch.setenv("HEADROOM_INTERCEPT_ENABLED", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "canary")
     from headroom.proxy.interceptors import ToolResultInterceptorTransform
     from headroom.proxy.models import ProxyConfig
     from headroom.proxy.server import HeadroomProxy
@@ -717,6 +718,19 @@ def test_proxy_pipeline_includes_interceptor_when_env_enabled(monkeypatch):
         assert isinstance(transforms[0], ToolResultInterceptorTransform)
 
 
+def test_proxy_pipeline_blocks_interceptor_below_rollout_channel(monkeypatch):
+    """A legacy request cannot bypass the stable rollout-channel boundary."""
+    monkeypatch.setenv("HEADROOM_INTERCEPT_ENABLED", "1")
+    monkeypatch.setenv("HEADROOM_ROLLOUT_CHANNEL", "stable")
+    from headroom.proxy.interceptors import ToolResultInterceptorTransform
+    from headroom.proxy.models import ProxyConfig
+    from headroom.proxy.server import HeadroomProxy
+
+    proxy = HeadroomProxy(ProxyConfig())
+    for pipeline in (proxy.anthropic_pipeline, proxy.openai_pipeline):
+        assert not any(isinstance(t, ToolResultInterceptorTransform) for t in pipeline.transforms)
+
+
 def test_proxy_pipeline_excludes_interceptor_when_env_not_set(monkeypatch):
     """When HEADROOM_INTERCEPT_ENABLED is unset, no interceptor in either pipeline."""
     monkeypatch.delenv("HEADROOM_INTERCEPT_ENABLED", raising=False)
diff --git a/tests/test_transforms/test_content_router.py b/tests/test_transforms/test_content_router.py
index 52f9bfa5b..916bd62ab 100644
--- a/tests/test_transforms/test_content_router.py
+++ b/tests/test_transforms/test_content_router.py
@@ -1699,3 +1699,70 @@ class TestCompressBlockContent:
         assert any("router:tool_result" in t for t in transforms_applied), (
             f"Expected router:tool_result:* in transforms, got: {transforms_applied}"
         )
+
+
+# =============================================================================
+# Mixed content: custom-tag protection (system-reminder mangling regression)
+# =============================================================================
+
+
+class TestMixedContentTagProtection:
+    """_compress_mixed must protect custom-tag blocks BEFORE section split.
+
+    Splitting first lands the open/close tags of a
+    ``<system-reminder>...</system-reminder>`` pair in different sections;
+    per-section protection then sees only unmatched tags (which protect
+    nothing) and the block's content — Claude Code ships CLAUDE.md this way —
+    is lossy-compressed and arrives word-dropped.
+    """
+
+    REMINDER = (
+        "<system-reminder>\n"
+        "Instruction prose that must survive byte-exact.\n\n"
+        "```bash\nrtk gain\n```\n\n"
+        "More instructions after the fence, also byte-exact.\n"
+        "</system-reminder>"
+    )
+
+    @staticmethod
+    def _mangling_router() -> ContentRouter:
+        """Router whose per-section compressor visibly mangles everything."""
+        router = ContentRouter(ContentRouterConfig(min_section_tokens=1))
+
+        def mangle(content, strategy, context, language=None, question=None, bias=1.0):
+            return "MANGLED", 1, None
+
+        router._apply_strategy_to_content = mangle  # type: ignore[method-assign]
+        return router
+
+    def test_reminder_block_survives_mixed_compression_verbatim(self):
+        router = self._mangling_router()
+        content = (
+            "Prose before the reminder that may compress.\n\n"
+            + self.REMINDER
+            + "\n\nProse after the reminder that may compress."
+        )
+
+        result = router._compress_mixed(content, context="")
+
+        # The tag block (fence and all) is byte-exact in the output...
+        assert self.REMINDER in result.compressed
+        # ...while content outside it still went through the compressor.
+        assert "MANGLED" in result.compressed
+
+    def test_reminder_only_content_passes_through(self):
+        router = self._mangling_router()
+
+        result = router._compress_mixed(self.REMINDER, context="")
+
+        assert self.REMINDER in result.compressed
+        assert "MANGLED" not in result.compressed
+
+    def test_untagged_mixed_content_still_compresses(self):
+        router = self._mangling_router()
+        content = "Plain prose section.\n\n```python\nprint('hi')\n```\n\nMore prose."
+
+        result = router._compress_mixed(content, context="")
+
+        assert "MANGLED" in result.compressed
+        assert result.strategy_used == CompressionStrategy.MIXED
diff --git a/tests/test_transforms/test_detect_fallback_1123.py b/tests/test_transforms/test_detect_fallback_1123.py
index d9d0623eb..22ad4f72a 100644
--- a/tests/test_transforms/test_detect_fallback_1123.py
+++ b/tests/test_transforms/test_detect_fallback_1123.py
@@ -5,6 +5,9 @@ from __future__ import annotations
 
 import asyncio
 
+import pytest
+
+import headroom._ort as ort_runtime
 from headroom.transforms import content_router as cr
 
 # Patch the native detector via its string target ("headroom._core.detect_content_type")
@@ -15,6 +18,13 @@ from headroom.transforms import content_router as cr
 # the control-flow tests would silently run the real detector and never see the exception.
 
 
+@pytest.fixture(autouse=True)
+def _compatible_mock_native_runtime(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Keep mocked native calls reachable regardless of prior test state."""
+    monkeypatch.setattr(ort_runtime, "rust_ort_runtime_compatible", lambda: True)
+    monkeypatch.setattr(cr, "_detect_native_unhealthy", False)
+
+
 def test_falls_back_on_rust_exception(monkeypatch):
     """An ordinary exception from the native detector degrades to regex."""
 
@@ -58,8 +68,6 @@ def test_control_flow_exceptions_propagate(monkeypatch):
     monkeypatch.setattr("headroom._core.detect_content_type", _interrupt)
     monkeypatch.setattr(cr, "_detect_panic_warned", False, raising=False)
 
-    import pytest
-
     with pytest.raises(KeyboardInterrupt):
         cr._detect_content("content")
 
@@ -74,7 +82,5 @@ def test_cancelled_error_propagates(monkeypatch):
     monkeypatch.setattr("headroom._core.detect_content_type", _cancel)
     monkeypatch.setattr(cr, "_detect_panic_warned", False, raising=False)
 
-    import pytest
-
     with pytest.raises(asyncio.CancelledError):
         cr._detect_content("content")
diff --git a/tests/test_transforms/test_ort_dylib.py b/tests/test_transforms/test_ort_dylib.py
index a10cdd2c6..405db1df2 100644
--- a/tests/test_transforms/test_ort_dylib.py
+++ b/tests/test_transforms/test_ort_dylib.py
@@ -22,6 +22,8 @@ import headroom._ort as _ort
 def _fresh_resolver(monkeypatch):
     """Reset the module-level cache and scrub the env before every test."""
     monkeypatch.setattr(_ort, "_pinned", _ort._UNSET)
+    monkeypatch.setattr(_ort, "_pinned_from_override", False)
+    monkeypatch.setattr(_ort, "_installed_ort_version", lambda: (1, 24))
     monkeypatch.delenv("ORT_DYLIB_PATH", raising=False)
 
 
@@ -70,6 +72,34 @@ def test_respects_existing_env(monkeypatch):
     monkeypatch.setenv("ORT_DYLIB_PATH", r"C:\custom\onnxruntime.dll")
     assert _ort.ensure_ort_dylib_pinned() == r"C:\custom\onnxruntime.dll"
     assert _ort.os.environ["ORT_DYLIB_PATH"] == r"C:\custom\onnxruntime.dll"
+    assert _ort.rust_ort_runtime_compatible()
+
+
+def test_incompatible_package_is_not_pinned(monkeypatch, tmp_path, caplog):
+    monkeypatch.setattr(_ort, "_installed_ort_version", lambda: (1, 23))
+    pkg = tmp_path / "onnxruntime"
+    capi = pkg / "capi"
+    capi.mkdir(parents=True)
+    (capi / "libonnxruntime.so.1.23.2").write_bytes(b"old")
+    _fake_spec_for(monkeypatch, pkg)
+
+    assert _ort.ensure_ort_dylib_pinned() is None
+    assert not _ort.rust_ort_runtime_compatible()
+    assert "older C API" in caplog.text
+
+
+def test_content_router_bypasses_native_detector_for_incompatible_ort(monkeypatch, caplog):
+    import headroom.transforms.content_router as router
+
+    monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "rust")
+    monkeypatch.setattr(_ort, "rust_ort_runtime_compatible", lambda: False)
+    monkeypatch.setattr(router, "_detect_native_unhealthy", False)
+
+    result = router._detect_content('{"safe": true}')
+
+    assert result.content_type.value.startswith("json")
+    assert router._detect_native_unhealthy is True
+    assert "requires ONNX Runtime 1.24+" in caplog.text
 
 
 def test_pins_to_package_capi_dll(monkeypatch, tmp_path):
diff --git a/tests/test_transforms/test_smart_crusher_bugs.py b/tests/test_transforms/test_smart_crusher_bugs.py
index 616806d99..0981f2cba 100644
--- a/tests/test_transforms/test_smart_crusher_bugs.py
+++ b/tests/test_transforms/test_smart_crusher_bugs.py
@@ -163,6 +163,26 @@ class TestLosslessOnlyMode:
         assert json.loads(out.compressed) == rows
 
 
+def test_extract_context_survives_null_function_tool_call() -> None:
+    # A tool_call with an explicit {"function": null} must not crash context
+    # extraction: `dict.get("function", {})` returns None for a present-but-null
+    # key, and `.get` on None raises AttributeError inside apply().
+    crusher = _make_crusher()
+    messages = [
+        {
+            "role": "assistant",
+            "tool_calls": [
+                {"id": "1", "type": "function", "function": None},
+                {"id": "2", "type": "function", "function": {"arguments": "keep-me"}},
+            ],
+        },
+    ]
+
+    ctx = crusher._extract_context_from_messages(messages)
+
+    assert "keep-me" in ctx
+
+
 # Stage 3c.1 lockstep bug-fix tests previously lived here; they probed
 # Python helpers (`_percentile_linear`, `_detect_sequential_pattern`,
 # `_detect_rare_status_values`, `_compute_k_split`) that were removed
diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.py
index 89f18daa2..4f76c6386 100644
--- a/tests/test_transforms_content_router.py
+++ b/tests/test_transforms_content_router.py
@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import json
+import threading
 from types import SimpleNamespace
 
 import pytest
 
+import headroom._ort as ort_runtime
 import headroom.transforms.content_router as content_router_module
 from headroom.transforms.content_detector import ContentType, DetectionResult
 from headroom.transforms.content_router import (
@@ -35,6 +37,11 @@ def _reset_detect_module_state(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(content_router_module, "_detect_native_unhealthy", False)
     monkeypatch.setattr(content_router_module, "_detect_backend_warned", False)
     monkeypatch.setattr(content_router_module, "_detect_panic_warned", False)
+    # Router unit tests replace ``headroom._core.detect_content_type`` with
+    # deterministic fakes. Keep the separate ORT API-compatibility preflight
+    # open so those fakes reach the watchdog/circuit-breaker behavior under
+    # test; incompatibility itself is covered in test_ort_dylib.py (#2960).
+    monkeypatch.setattr(ort_runtime, "rust_ort_runtime_compatible", lambda: True)
 
 
 def test_compression_cache_handles_hits_skips_evictions_and_clear(
@@ -154,6 +161,29 @@ def test_content_signature_and_detection_helpers(monkeypatch: pytest.MonkeyPatch
     assert result.metadata == {}
 
 
+def test_native_detection_remains_bounded_after_success(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A successful native call must not disable the watchdog for later calls."""
+    import headroom._core as _core
+
+    monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "rust")
+    monkeypatch.setattr(content_router_module, "_detect_timeout_secs", lambda: 0.01)
+    calls = 0
+
+    def _succeeds_then_hangs(_content: str) -> SimpleNamespace:
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            return SimpleNamespace(content_type="plain_text")
+        threading.Event().wait()
+        raise AssertionError("unreachable")
+
+    monkeypatch.setattr(_core, "detect_content_type", _succeeds_then_hangs)
+
+    assert _detect_content("first").content_type is ContentType.PLAIN_TEXT
+    assert _detect_content("second").content_type is ContentType.PLAIN_TEXT
+    assert content_router_module._detect_native_unhealthy is True
+
+
 def test_mixed_content_section_splitting_and_json_extraction() -> None:
     content = "\n".join(
         [
diff --git a/tests/test_turn_hook_usage.py b/tests/test_turn_hook_usage.py
new file mode 100644
index 000000000..cbf5a185e
--- /dev/null
+++ b/tests/test_turn_hook_usage.py
@@ -0,0 +1,405 @@
+"""A turn hook's re-drives are billed calls and must reach token accounting.
+
+A hook that resolves an injected tool call re-drives the model. Both OpenAI
+handlers read usage from exactly ONE response — the original, or whichever the
+hook returned in its place, because the handler swaps `response` for it. Every
+other upstream call on that turn is spend nothing else records.
+
+Getting that wrong is not a rounding error for a token-saving feature: it lets
+the feature hide its own overhead behind the saving it claims. The first version
+of this recorded only the re-drives and added them unconditionally, so a single
+re-drive billed `B + B` and dropped the original `A` entirely. The handler tests
+at the bottom are what catch that class of mistake; the unit tests above them
+cannot, because the bug lives in how the accumulator composes with the response
+swap rather than in the accumulator itself.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+import respx
+
+from headroom.proxy.handlers.anthropic import _AnthropicTurnHookUsage
+from headroom.proxy.handlers.openai import (
+    CHAT_USAGE_KEYS,
+    RESPONSES_USAGE_KEYS,
+    TurnHookUsage,
+)
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient  # noqa: E402
+
+from headroom.proxy.loopback_guard import require_loopback  # noqa: E402
+from headroom.proxy.server import ProxyConfig, create_app  # noqa: E402
+from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook  # noqa: E402
+
+# --- unit: the accumulator -----------------------------------------------
+
+
+def _chat(prompt: int, completion: int, cached: int = 0) -> dict[str, Any]:
+    return {
+        "usage": {
+            "prompt_tokens": prompt,
+            "completion_tokens": completion,
+            "prompt_tokens_details": {"cached_tokens": cached},
+        }
+    }
+
+
+def test_no_redrive_adds_nothing() -> None:
+    """The common path: one upstream call, which the usage block reads itself."""
+    u = TurnHookUsage()
+    original = _chat(100, 10)
+    u.record(original, **CHAT_USAGE_KEYS)
+    u.settle(original)
+    assert u.extra_calls == 0
+    assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (0, 0, 0)
+
+
+def test_one_redrive_leaves_the_original_to_add() -> None:
+    """A + B billed; the block will read B; so A is the delta."""
+    u = TurnHookUsage()
+    a, b = _chat(100, 10, 60), _chat(150, 20, 90)
+    u.record(a, **CHAT_USAGE_KEYS)
+    u.record(b, **CHAT_USAGE_KEYS)
+    u.settle(b)
+    assert u.extra_calls == 1
+    assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (100, 10, 60)
+
+
+def test_two_redrives_leave_the_original_and_the_middle() -> None:
+    u = TurnHookUsage()
+    a, b, c = _chat(100, 10), _chat(150, 20), _chat(200, 30)
+    for r in (a, b, c):
+        u.record(r, **CHAT_USAGE_KEYS)
+    u.settle(c)
+    assert u.extra_calls == 2
+    assert (u.input_tokens, u.output_tokens) == (250, 30)
+
+
+def test_hook_that_keeps_the_original_still_pays_for_the_redrive() -> None:
+    """Re-drove, then returned the original anyway. B was still billed."""
+    u = TurnHookUsage()
+    a, b = _chat(100, 10), _chat(150, 20)
+    u.record(a, **CHAT_USAGE_KEYS)
+    u.record(b, **CHAT_USAGE_KEYS)
+    u.settle(a)
+    assert u.extra_calls == 1
+    assert (u.input_tokens, u.output_tokens) == (150, 20)
+
+
+def test_synthesised_response_matches_nothing_and_over_counts() -> None:
+    """Nothing is subtracted when the hook invents a response. Over-counting is
+    the safe direction for a bill; under-counting is the bug this file exists
+    for."""
+    u = TurnHookUsage()
+    a, b = _chat(100, 10), _chat(150, 20)
+    u.record(a, **CHAT_USAGE_KEYS)
+    u.record(b, **CHAT_USAGE_KEYS)
+    u.settle({"usage": {"prompt_tokens": 999}})
+    assert u.extra_calls == 2
+    assert u.input_tokens == 250
+
+
+def test_responses_shape_uses_its_own_key_names() -> None:
+    u = TurnHookUsage()
+    a = {
+        "usage": {
+            "input_tokens": 400,
+            "output_tokens": 40,
+            "input_tokens_details": {"cached_tokens": 300},
+        }
+    }
+    b = {"usage": {"input_tokens": 500, "output_tokens": 50}}
+    u.record(a, **RESPONSES_USAGE_KEYS)
+    u.record(b, **RESPONSES_USAGE_KEYS)
+    u.settle(b)
+    assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (400, 40, 300)
+
+    # Chat keys must not read a Responses payload: a silent 0 looks exactly like
+    # "the hook cost nothing".
+    v = TurnHookUsage()
+    v.record(a, **CHAT_USAGE_KEYS)
+    v.record(b, **CHAT_USAGE_KEYS)
+    v.settle(b)
+    assert v.input_tokens == 0
+    assert v.extra_calls == 1, "the call still happened even if its shape was unreadable"
+
+
+def test_never_raises_on_a_shape_it_does_not_recognise() -> None:
+    """A hook must not be able to 500 a request by returning something odd."""
+    u = TurnHookUsage()
+    for payload in (
+        None,
+        {},
+        [],
+        "not a dict",
+        {"usage": None},
+        {"usage": "nope"},
+        {"usage": {"prompt_tokens": None, "completion_tokens": "x"}},
+        {"usage": {"prompt_tokens": -5, "prompt_tokens_details": "nope"}},
+    ):
+        u.record(payload, **CHAT_USAGE_KEYS)
+    u.settle(object())
+    assert u.extra_calls == 8
+    assert (u.input_tokens, u.output_tokens, u.cache_read_tokens) == (0, 0, 0)
+
+
+def test_anthropic_accumulator_includes_disjoint_cache_buckets() -> None:
+    usage = _AnthropicTurnHookUsage()
+    first = {
+        "usage": {
+            "input_tokens": 100,
+            "output_tokens": 10,
+            "cache_read_input_tokens": 50,
+            "cache_creation_input_tokens": 25,
+            "cache_creation": {
+                "ephemeral_5m_input_tokens": 20,
+                "ephemeral_1h_input_tokens": 5,
+            },
+        }
+    }
+    final = {
+        "usage": {
+            "input_tokens": 150,
+            "output_tokens": 20,
+            "cache_read_input_tokens": 70,
+            "cache_creation_input_tokens": 30,
+        }
+    }
+    usage.record(first)
+    usage.record(final)
+    usage.settle(final)
+    assert usage.input_tokens == 175
+    assert usage.output_tokens == 10
+    assert usage.cache_read_tokens == 50
+    assert usage.cache_write_tokens == 25
+    assert usage.cache_write_5m_tokens == 20
+    assert usage.cache_write_1h_tokens == 5
+
+
+# --- handler level: what the unit tests above structurally cannot see -----
+
+
+class _RedriveOnce:
+    """Minimal hook: re-drive the model exactly once, return the new response."""
+
+    name = "test_redrive"
+    stream_safe = False
+
+    def __init__(self) -> None:
+        self.calls = 0
+
+    def on_request(self, ctx: Any) -> None:  # pragma: no cover - nothing to do
+        return None
+
+    async def on_response(self, ctx: Any, response: Any, call_model: Any) -> Any:
+        if self.calls:
+            return None
+        self.calls += 1
+        return await call_model(ctx.messages)
+
+
+@pytest.fixture
+def _no_hooks():
+    clear_turn_hooks()
+    yield
+    clear_turn_hooks()
+
+
+def _app_and_outcomes(monkeypatch):
+    """App with a spy on the outcome record, which is where the billed token
+    counts land (`provider_input_tokens` / `output_tokens`)."""
+    app = create_app(
+        ProxyConfig(
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            cost_tracking_enabled=False,
+            log_requests=False,
+        )
+    )
+    app.dependency_overrides[require_loopback] = lambda: None
+    outcomes: list[Any] = []
+    proxy = app.state.proxy
+
+    # Patched on the type, so the bound-call self arrives as the first argument.
+    async def _spy(_self, outcome, *a, **kw):
+        outcomes.append(outcome)
+
+    monkeypatch.setattr(type(proxy), "_record_request_outcome", _spy, raising=True)
+    return app, outcomes
+
+
+@respx.mock
+def test_chat_bills_the_original_plus_the_redrive(monkeypatch, _no_hooks) -> None:
+    """A=100/10, B=150/20 -> 250 in / 30 out.
+
+    The bug this pins reported 300/40 (B twice, A dropped).
+    """
+    register_turn_hook(_RedriveOnce())
+    app, outcomes = _app_and_outcomes(monkeypatch)
+
+    bodies = [
+        {
+            "id": "a",
+            "choices": [
+                {"message": {"role": "assistant", "content": "A"}, "finish_reason": "stop"}
+            ],
+            "usage": {"prompt_tokens": 100, "completion_tokens": 10},
+        },
+        {
+            "id": "b",
+            "choices": [
+                {"message": {"role": "assistant", "content": "B"}, "finish_reason": "stop"}
+            ],
+            "usage": {"prompt_tokens": 150, "completion_tokens": 20},
+        },
+    ]
+    sent = iter(bodies)
+    respx.post("https://api.openai.com/v1/chat/completions").mock(
+        side_effect=lambda request: httpx.Response(200, json=next(sent))
+    )
+
+    with TestClient(app) as client:
+        r = client.post(
+            "/v1/chat/completions",
+            json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},
+            headers={"authorization": "Bearer sk-test"},
+        )
+    assert r.status_code == 200
+    assert json.loads(r.content)["id"] == "b", "the hook's response is what the client gets"
+    assert outcomes, "an outcome must be recorded"
+    o = outcomes[-1]
+    assert o.provider_input_tokens == 250, f"want A+B=250, got {o.provider_input_tokens}"
+    assert o.output_tokens == 30, f"want A+B=30, got {o.output_tokens}"
+
+
+@respx.mock
+def test_responses_bills_the_original_plus_the_redrive(monkeypatch, _no_hooks) -> None:
+    """Same arithmetic on /v1/responses, whose usage keys differ."""
+    register_turn_hook(_RedriveOnce())
+    app, outcomes = _app_and_outcomes(monkeypatch)
+
+    bodies = [
+        {
+            "id": "a",
+            "output": [{"type": "message", "role": "assistant", "content": []}],
+            "usage": {"input_tokens": 400, "output_tokens": 40},
+        },
+        {
+            "id": "b",
+            "output": [{"type": "message", "role": "assistant", "content": []}],
+            "usage": {"input_tokens": 500, "output_tokens": 50},
+        },
+    ]
+    sent = iter(bodies)
+    respx.post("https://api.openai.com/v1/responses").mock(
+        side_effect=lambda request: httpx.Response(200, json=next(sent))
+    )
+
+    with TestClient(app) as client:
+        r = client.post(
+            "/v1/responses",
+            json={
+                "model": "gpt-4o",
+                "input": [{"type": "message", "role": "user", "content": []}],
+                "stream": False,
+            },
+            headers={"authorization": "Bearer sk-test"},
+        )
+    assert r.status_code == 200
+    assert outcomes, "an outcome must be recorded"
+    o = outcomes[-1]
+    assert o.provider_input_tokens == 900, f"want A+B=900, got {o.provider_input_tokens}"
+    assert o.output_tokens == 90, f"want A+B=90, got {o.output_tokens}"
+
+
+@respx.mock
+def test_no_hook_registered_bills_exactly_the_one_call(monkeypatch, _no_hooks) -> None:
+    """The regression guard in the other direction: with no hook, accounting must
+    be untouched — this whole mechanism has to be inert on a stock proxy."""
+    app, outcomes = _app_and_outcomes(monkeypatch)
+    respx.post("https://api.openai.com/v1/chat/completions").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "id": "a",
+                "choices": [
+                    {"message": {"role": "assistant", "content": "A"}, "finish_reason": "stop"}
+                ],
+                "usage": {"prompt_tokens": 100, "completion_tokens": 10},
+            },
+        )
+    )
+
+    with TestClient(app) as client:
+        r = client.post(
+            "/v1/chat/completions",
+            json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},
+            headers={"authorization": "Bearer sk-test"},
+        )
+    assert r.status_code == 200
+    o = outcomes[-1]
+    assert o.provider_input_tokens == 100
+    assert o.output_tokens == 10
+
+
+@respx.mock
+def test_anthropic_bills_original_plus_hook_redrive(monkeypatch, _no_hooks) -> None:
+    """Anthropic A=175 total input, B=250 -> 425; outputs 10+20."""
+    register_turn_hook(_RedriveOnce())
+    app, outcomes = _app_and_outcomes(monkeypatch)
+
+    def response(ident: str, input_tokens: int, output_tokens: int, read: int, write: int):
+        return {
+            "id": ident,
+            "type": "message",
+            "role": "assistant",
+            "model": "claude-sonnet-4-5",
+            "content": [{"type": "text", "text": ident}],
+            "stop_reason": "end_turn",
+            "usage": {
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "cache_read_input_tokens": read,
+                "cache_creation_input_tokens": write,
+            },
+        }
+
+    sent = iter(
+        [
+            response("a", 100, 10, 50, 25),
+            response("b", 150, 20, 70, 30),
+        ]
+    )
+    respx.post("https://api.anthropic.com/v1/messages").mock(
+        side_effect=lambda request: httpx.Response(200, json=next(sent))
+    )
+
+    with TestClient(app) as client:
+        result = client.post(
+            "/v1/messages",
+            json={
+                "model": "claude-sonnet-4-5",
+                "max_tokens": 64,
+                "messages": [{"role": "user", "content": "hi"}],
+            },
+            headers={
+                "x-api-key": "sk-ant-test",
+                "anthropic-version": "2023-06-01",
+            },
+        )
+
+    assert result.status_code == 200
+    outcome = outcomes[-1]
+    assert outcome.provider_input_tokens == 425
+    assert outcome.output_tokens == 30
+    assert outcome.cache_read_tokens == 120
+    assert outcome.cache_write_tokens == 55
+    assert outcome.uncached_input_tokens == 250
diff --git a/tests/test_turn_hooks.py b/tests/test_turn_hooks.py
index 788ae01ba..1bf2da3bc 100644
--- a/tests/test_turn_hooks.py
+++ b/tests/test_turn_hooks.py
@@ -102,6 +102,41 @@ def test_on_request_may_mutate_ctx():
     assert ctx.tools == [{"name": "keep"}]
 
 
+def test_request_runner_attributes_savings_with_handler_counters():
+    class Shrink:
+        name = "internal-hook-name"
+        savings_source = "tool_search"
+
+        def on_request(self, ctx: TurnContext) -> None:
+            ctx.tools = (ctx.tools or [])[:1]
+            ctx.messages[0]["content"] = "short"
+
+    register_turn_hook(Shrink())
+    tags = {}
+    ctx = _ctx(
+        messages=[{"role": "user", "content": "a much longer value"}],
+        tools=[{"name": "keep"}, {"name": "drop"}],
+        tags=tags,
+        count_messages=lambda messages: len(messages[0]["content"]),
+        count_tools=lambda tools: len(tools or []),
+    )
+
+    run_request_hooks(ctx)
+
+    from headroom.proxy.savings_attribution import from_tags
+
+    assert from_tags(tags) == [
+        {
+            "source": "tool_search",
+            "realized": True,
+            "estimated": False,
+            "tokens": 15,
+            "usd": 0.0,
+            "details": {"message_tokens_saved": 14, "tool_tokens_saved": 1},
+        }
+    ]
+
+
 # --- on_response replacement + re-drive loop ---------------------------------
 
 
diff --git a/tests/test_update_helpers.py b/tests/test_update_helpers.py
index bb313b2d1..b037bb99c 100644
--- a/tests/test_update_helpers.py
+++ b/tests/test_update_helpers.py
@@ -267,6 +267,64 @@ def test_update_externally_managed_refuses_via_command(monkeypatch):
     assert "PEP 668" in res.output
 
 
+def test_venv_inside_bare_dockerenv_still_self_updates(monkeypatch):
+    """A venv/pip install inside a container (bare /.dockerenv, no explicit
+    HEADROOM_IN_DOCKER) must self-update, not be refused with image guidance (#2816).
+    """
+    monkeypatch.setattr(up, "_is_source_checkout", lambda: False)
+    monkeypatch.setattr(up, "_is_editable_install", lambda: False)
+    monkeypatch.delenv("HEADROOM_IN_DOCKER", raising=False)
+    # Deterministic, pipx/uv-free venv layout (mirrors the issue's environment).
+    monkeypatch.setenv("PIPX_HOME", "")
+    monkeypatch.setenv("UV_TOOL_DIR", "")
+    monkeypatch.setattr(up.sys, "executable", "/config/.headroom-venv/bin/python")
+    monkeypatch.setattr(up.sys, "prefix", "/config/.headroom-venv")
+    monkeypatch.setattr(
+        up, "_package_location", lambda: "/config/.headroom-venv/lib/python3.12/headroom"
+    )
+    # The container is real (/.dockerenv), but a venv owns the install.
+    monkeypatch.setattr(up, "_in_docker", lambda: True)
+    monkeypatch.setattr(up, "_in_virtualenv", lambda: True)
+
+    method = up.detect_install_method()
+    assert method.kind == "pip"
+    assert method.can_self_update is True
+    assert method.argv[:4] == [up.sys.executable, "-m", "pip", "install"]
+
+
+def test_explicit_headroom_in_docker_still_refuses_over_venv(monkeypatch):
+    """The official image's explicit HEADROOM_IN_DOCKER opt-out wins up front,
+    even when a venv owns the install."""
+    monkeypatch.setattr(up, "_is_source_checkout", lambda: False)
+    monkeypatch.setattr(up, "_is_editable_install", lambda: False)
+    monkeypatch.setenv("HEADROOM_IN_DOCKER", "1")
+    monkeypatch.setattr(up, "_in_virtualenv", lambda: True)
+
+    method = up.detect_install_method()
+    assert method.kind == "docker"
+    assert method.can_self_update is False
+
+
+def test_bare_dockerenv_without_owner_refuses(monkeypatch):
+    """A container whose system interpreter owns the install (bare /.dockerenv, no
+    venv/pipx/uv/user-site) still refuses with the pull-a-new-image guidance."""
+    monkeypatch.setattr(up, "_is_source_checkout", lambda: False)
+    monkeypatch.setattr(up, "_is_editable_install", lambda: False)
+    monkeypatch.delenv("HEADROOM_IN_DOCKER", raising=False)
+    monkeypatch.setenv("PIPX_HOME", "")
+    monkeypatch.setenv("UV_TOOL_DIR", "")
+    monkeypatch.setattr(up.sys, "executable", "/usr/bin/python3")
+    monkeypatch.setattr(up.sys, "prefix", "/usr")
+    monkeypatch.setattr(up, "_package_location", lambda: "/usr/lib/python3.12/headroom")
+    monkeypatch.setattr(up, "_in_docker", lambda: True)
+    monkeypatch.setattr(up, "_in_virtualenv", lambda: False)
+    monkeypatch.setattr(up, "_is_user_site_install", lambda loc: False)
+
+    method = up.detect_install_method()
+    assert method.kind == "docker"
+    assert method.can_self_update is False
+
+
 # --------------------------------------------------------------------------- #
 # update_check helpers / branches
 # --------------------------------------------------------------------------- #
diff --git a/uv.lock b/uv.lock
index c70b4098d..edd0b3646 100644
--- a/uv.lock
+++ b/uv.lock
@@ -280,12 +280,12 @@ name = "any-llm-sdk"
 version = "1.12.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "httpx", marker = "python_full_version >= '3.11'" },
-    { name = "openai", marker = "python_full_version >= '3.11'" },
-    { name = "openresponses-types", marker = "python_full_version >= '3.11'" },
-    { name = "pydantic", marker = "python_full_version >= '3.11'" },
-    { name = "rich", marker = "python_full_version >= '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version >= '3.11'" },
+    { name = "httpx" },
+    { name = "openai" },
+    { name = "openresponses-types" },
+    { name = "pydantic" },
+    { name = "rich" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/21/d5/21ef27d031b72f0054ba0015a66cc1f10cda9410e4a3acb6e795d848ad0d/any_llm_sdk-1.12.1.tar.gz", hash = "sha256:76e043fcaa56fccfb375a908511869dc7dbf393dd97a82d06bb764d8201724e8", size = 152078, upload-time = "2026-03-18T13:13:01.735Z" }
 wheels = [
@@ -756,8 +756,8 @@ dependencies = [
     { name = "mmh3" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "opentelemetry-api" },
     { name = "opentelemetry-exporter-otlp-proto-grpc" },
     { name = "opentelemetry-sdk" },
@@ -811,7 +811,7 @@ name = "coloredlogs"
 version = "15.0.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "humanfriendly", marker = "python_full_version < '3.14'" },
+    { name = "humanfriendly" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/cc/c7/eed8f27100517e8c0e6b923d5f0845d0cb99763da6fdee00478f91db7325/coloredlogs-15.0.1.tar.gz", hash = "sha256:7c991aa71a4577af2f82600d8f8f3a89f936baeaf9b50a9c197da014e5bf16b0", size = 278520, upload-time = "2021-06-11T10:22:45.202Z" }
 wheels = [
@@ -823,7 +823,7 @@ name = "colorlog"
 version = "6.10.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "colorama", marker = "python_full_version >= '3.13' and sys_platform == 'win32'" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/a2/61/f083b5ac52e505dfc1c624eafbf8c7589a0d7f32daa398d2e7590efa5fda/colorlog-6.10.1.tar.gz", hash = "sha256:eb4ae5cb65fe7fec7773c2306061a8e63e02efc2c72eba9d27b0fa23c94f1321", size = 17162, upload-time = "2025-10-16T16:14:11.978Z" }
 wheels = [
@@ -1045,7 +1045,7 @@ name = "cuda-bindings"
 version = "13.3.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "cuda-pathfinder", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "cuda-pathfinder" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/a9/21/8464d133752951c154feafb3b65c297e7d80f301183d220bec4c830f1441/cuda_bindings-13.3.1-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:120fcc53d57903df529c3486962c56528cba5b7d6c57c99537320ed9922c8b86", size = 6073403, upload-time = "2026-05-29T23:11:36.22Z" },
@@ -1080,43 +1080,43 @@ wheels = [
 
 [package.optional-dependencies]
 cublas = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
-    { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cublas", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
+    { name = "nvidia-cuda-nvrtc", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 cudart = [
-    { name = "nvidia-cuda-runtime", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cuda-runtime", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 cufft = [
-    { name = "nvidia-cufft", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cufft", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
+    { name = "nvidia-nvjitlink", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 cufile = [
-    { name = "nvidia-cufile", marker = "(platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cufile", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 cupti = [
-    { name = "nvidia-cuda-cupti", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cuda-cupti", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 curand = [
-    { name = "nvidia-curand", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-curand", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 cusolver = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
-    { name = "nvidia-cusolver", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
-    { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cublas", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
+    { name = "nvidia-cusolver", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
+    { name = "nvidia-cusparse", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
+    { name = "nvidia-nvjitlink", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 cusparse = [
-    { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cusparse", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
+    { name = "nvidia-nvjitlink", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 nvjitlink = [
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-nvjitlink", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 nvrtc = [
-    { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-cuda-nvrtc", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 nvtx = [
-    { name = "nvidia-nvtx", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" },
+    { name = "nvidia-nvtx", marker = "platform_machine == 'aarch64' or platform_machine == 'x86_64'" },
 ]
 
 [[package]]
@@ -1220,7 +1220,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -1253,8 +1253,8 @@ dependencies = [
     { name = "mmh3" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "pillow" },
     { name = "py-rust-stemmers" },
     { name = "requests" },
@@ -1495,14 +1495,14 @@ wheels = [
 
 [[package]]
 name = "gitpython"
-version = "3.1.50"
+version = "3.1.54"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
     { name = "gitdb" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/33/f6/354ae6491228b5eb40e10d89c4d13c651fe1cf7556e35ebdded50cff57ce/gitpython-3.1.50.tar.gz", hash = "sha256:80da2d12504d52e1f998772dc5baf6e553f8d2fcfe1fcc226c9d9a2ee3372dcc", size = 219798, upload-time = "2026-05-06T04:01:26.571Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5e/d5/3da0b92033887033f4c27f2dd109a303c4ca62813c7b3bb2511edb4777de/gitpython-3.1.54.tar.gz", hash = "sha256:53f2085e24a2cda300eed7c3fc5f1559ae289634b725e98acaf4791940247aa0", size = 225076, upload-time = "2026-07-22T04:08:51.403Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/20/7a/1c6e3562dfd8950adbb11ffbc65d21e7c89d01a6e4f137fa981056de25c5/gitpython-3.1.50-py3-none-any.whl", hash = "sha256:d352abe2908d07355014abdd21ddf798c2a961469239afec4962e9da884858f9", size = 212507, upload-time = "2026-05-06T04:01:23.799Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/b9/876f442a28df5c068ca69b0122d5c35e65fd2d2fa9992ea5cb5944ea00a6/gitpython-3.1.54-py3-none-any.whl", hash = "sha256:b90d7b3d9bc0238681d24369130826f0dcdb0ceaa45db67cf1d4ffa4c302dedf", size = 216575, upload-time = "2026-07-22T04:08:50.05Z" },
 ]
 
 [[package]]
@@ -1526,18 +1526,14 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0c/bc/e30e1e3d5e8860b0e0ce4d2b16b2681b77fd13542fc0d72f7e3c22d16eff/greenlet-3.4.0-cp310-cp310-macosx_11_0_universal2.whl", hash = "sha256:d18eae9a7fb0f499efcd146b8c9750a2e1f6e0e93b5a382b3481875354a430e6", size = 284315, upload-time = "2026-04-08T17:02:52.322Z" },
     { url = "https://files.pythonhosted.org/packages/5b/cc/e023ae1967d2a26737387cac083e99e47f65f58868bd155c4c80c01ec4e0/greenlet-3.4.0-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:636d2f95c309e35f650e421c23297d5011716be15d966e6328b367c9fc513a82", size = 601916, upload-time = "2026-04-08T16:24:35.533Z" },
     { url = "https://files.pythonhosted.org/packages/67/32/5be1677954b6d8810b33abe94e3eb88726311c58fa777dc97e390f7caf5a/greenlet-3.4.0-cp310-cp310-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:234582c20af9742583c3b2ddfbdbb58a756cfff803763ffaae1ac7990a9fac31", size = 616399, upload-time = "2026-04-08T16:30:54.536Z" },
-    { url = "https://files.pythonhosted.org/packages/82/0a/3a4af092b09ea02bcda30f33fd7db397619132fe52c6ece24b9363130d34/greenlet-3.4.0-cp310-cp310-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ac6a5f618be581e1e0713aecec8e54093c235e5fa17d6d8eb7ffc487e2300508", size = 621077, upload-time = "2026-04-08T16:40:34.946Z" },
     { url = "https://files.pythonhosted.org/packages/74/bf/2d58d5ea515704f83e34699128c9072a34bea27d2b6a556e102105fe62a5/greenlet-3.4.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:523677e69cd4711b5a014e37bc1fb3a29947c3e3a5bb6a527e1cc50312e5a398", size = 611978, upload-time = "2026-04-08T15:56:31.335Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/39/3786520a7d5e33ee87b3da2531f589a3882abf686a42a3773183a41ef010/greenlet-3.4.0-cp310-cp310-manylinux_2_39_riscv64.whl", hash = "sha256:d336d46878e486de7d9458653c722875547ac8d36a1cff9ffaf4a74a3c1f62eb", size = 416893, upload-time = "2026-04-08T16:43:02.392Z" },
     { url = "https://files.pythonhosted.org/packages/bd/69/6525049b6c179d8a923256304d8387b8bdd4acab1acf0407852463c6d514/greenlet-3.4.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:b45e45fe47a19051a396abb22e19e7836a59ee6c5a90f3be427343c37908d65b", size = 1571957, upload-time = "2026-04-08T16:26:17.041Z" },
     { url = "https://files.pythonhosted.org/packages/4e/6c/bbfb798b05fec736a0d24dc23e81b45bcee87f45a83cfb39db031853bddc/greenlet-3.4.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:5434271357be07f3ad0936c312645853b7e689e679e29310e2de09a9ea6c3adf", size = 1637223, upload-time = "2026-04-08T15:57:27.556Z" },
     { url = "https://files.pythonhosted.org/packages/b7/7d/981fe0e7c07bd9d5e7eb18decb8590a11e3955878291f7a7de2e9c668eb7/greenlet-3.4.0-cp310-cp310-win_amd64.whl", hash = "sha256:a19093fbad824ed7c0f355b5ff4214bffda5f1a7f35f29b31fcaa240cc0135ab", size = 237902, upload-time = "2026-04-08T17:03:14.16Z" },
     { url = "https://files.pythonhosted.org/packages/fb/c6/dba32cab7e3a625b011aa5647486e2d28423a48845a2998c126dd69c85e1/greenlet-3.4.0-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:805bebb4945094acbab757d34d6e1098be6de8966009ab9ca54f06ff492def58", size = 285504, upload-time = "2026-04-08T15:52:14.071Z" },
     { url = "https://files.pythonhosted.org/packages/54/f4/7cb5c2b1feb9a1f50e038be79980dfa969aa91979e5e3a18fdbcfad2c517/greenlet-3.4.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:439fc2f12b9b512d9dfa681c5afe5f6b3232c708d13e6f02c845e0d9f4c2d8c6", size = 605476, upload-time = "2026-04-08T16:24:37.064Z" },
     { url = "https://files.pythonhosted.org/packages/d6/af/b66ab0b2f9a4c5a867c136bf66d9599f34f21a1bcca26a2884a29c450bd9/greenlet-3.4.0-cp311-cp311-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a70ed1cb0295bee1df57b63bf7f46b4e56a5c93709eea769c1fec1bb23a95875", size = 618336, upload-time = "2026-04-08T16:30:56.59Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/31/56c43d2b5de476f77d36ceeec436328533bff960a4cba9a07616e93063ab/greenlet-3.4.0-cp311-cp311-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8c5696c42e6bb5cfb7c6ff4453789081c66b9b91f061e5e9367fa15792644e76", size = 625045, upload-time = "2026-04-08T16:40:37.111Z" },
     { url = "https://files.pythonhosted.org/packages/e5/5c/8c5633ece6ba611d64bf2770219a98dd439921d6424e4e8cf16b0ac74ea5/greenlet-3.4.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c660bce1940a1acae5f51f0a064f1bc785d07ea16efcb4bc708090afc4d69e83", size = 613515, upload-time = "2026-04-08T15:56:32.478Z" },
-    { url = "https://files.pythonhosted.org/packages/80/ca/704d4e2c90acb8bdf7ae593f5cbc95f58e82de95cc540fb75631c1054533/greenlet-3.4.0-cp311-cp311-manylinux_2_39_riscv64.whl", hash = "sha256:89995ce5ddcd2896d89615116dd39b9703bfa0c07b583b85b89bf1b5d6eddf81", size = 419745, upload-time = "2026-04-08T16:43:04.022Z" },
     { url = "https://files.pythonhosted.org/packages/a9/df/950d15bca0d90a0e7395eb777903060504cdb509b7b705631e8fb69ff415/greenlet-3.4.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ee407d4d1ca9dc632265aee1c8732c4a2d60adff848057cdebfe5fe94eb2c8a2", size = 1574623, upload-time = "2026-04-08T16:26:18.596Z" },
     { url = "https://files.pythonhosted.org/packages/1a/e7/0839afab829fcb7333c9ff6d80c040949510055d2d4d63251f0d1c7c804e/greenlet-3.4.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:956215d5e355fffa7c021d168728321fd4d31fd730ac609b1653b450f6a4bc71", size = 1639579, upload-time = "2026-04-08T15:57:29.231Z" },
     { url = "https://files.pythonhosted.org/packages/d9/2b/b4482401e9bcaf9f5c97f67ead38db89c19520ff6d0d6699979c6efcc200/greenlet-3.4.0-cp311-cp311-win_amd64.whl", hash = "sha256:5cb614ace7c27571270354e9c9f696554d073f8aa9319079dcba466bbdead711", size = 238233, upload-time = "2026-04-08T17:02:54.286Z" },
@@ -1545,9 +1541,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/65/8b/3669ad3b3f247a791b2b4aceb3aa5a31f5f6817bf547e4e1ff712338145a/greenlet-3.4.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:1a54a921561dd9518d31d2d3db4d7f80e589083063ab4d3e2e950756ef809e1a", size = 286902, upload-time = "2026-04-08T15:52:12.138Z" },
     { url = "https://files.pythonhosted.org/packages/38/3e/3c0e19b82900873e2d8469b590a6c4b3dfd2b316d0591f1c26b38a4879a5/greenlet-3.4.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:16dec271460a9a2b154e3b1c2fa1050ce6280878430320e85e08c166772e3f97", size = 606099, upload-time = "2026-04-08T16:24:38.408Z" },
     { url = "https://files.pythonhosted.org/packages/b5/33/99fef65e7754fc76a4ed14794074c38c9ed3394a5bd129d7f61b705f3168/greenlet-3.4.0-cp312-cp312-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:90036ce224ed6fe75508c1907a77e4540176dcf0744473627785dd519c6f9996", size = 618837, upload-time = "2026-04-08T16:30:58.298Z" },
-    { url = "https://files.pythonhosted.org/packages/44/57/eae2cac10421feae6c0987e3dc106c6d86262b1cb379e171b017aba893a6/greenlet-3.4.0-cp312-cp312-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:6f0def07ec9a71d72315cf26c061aceee53b306c36ed38c35caba952ea1b319d", size = 624901, upload-time = "2026-04-08T16:40:38.981Z" },
     { url = "https://files.pythonhosted.org/packages/36/f7/229f3aed6948faa20e0616a0b8568da22e365ede6a54d7d369058b128afd/greenlet-3.4.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a1c4f6b453006efb8310affb2d132832e9bbb4fc01ce6df6b70d810d38f1f6dc", size = 615062, upload-time = "2026-04-08T15:56:33.766Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/8a/0e73c9b94f31d1cc257fe79a0eff621674141cdae7d6d00f40de378a1e42/greenlet-3.4.0-cp312-cp312-manylinux_2_39_riscv64.whl", hash = "sha256:0e1254cf0cbaa17b04320c3a78575f29f3c161ef38f59c977108f19ffddaf077", size = 423927, upload-time = "2026-04-08T16:43:05.293Z" },
     { url = "https://files.pythonhosted.org/packages/08/97/d988180011aa40135c46cd0d0cf01dd97f7162bae14139b4a3ef54889ba5/greenlet-3.4.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:9b2d9a138ffa0e306d0e2b72976d2fb10b97e690d40ab36a472acaab0838e2de", size = 1573511, upload-time = "2026-04-08T16:26:20.058Z" },
     { url = "https://files.pythonhosted.org/packages/d4/0f/a5a26fe152fb3d12e6a474181f6e9848283504d0afd095f353d85726374b/greenlet-3.4.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:8424683caf46eb0eb6f626cb95e008e8cc30d0cb675bdfa48200925c79b38a08", size = 1640396, upload-time = "2026-04-08T15:57:30.88Z" },
     { url = "https://files.pythonhosted.org/packages/42/cf/bb2c32d9a100e36ee9f6e38fad6b1e082b8184010cb06259b49e1266ca01/greenlet-3.4.0-cp312-cp312-win_amd64.whl", hash = "sha256:a0a53fb071531d003b075c444014ff8f8b1a9898d36bb88abd9ac7b3524648a2", size = 238892, upload-time = "2026-04-08T17:03:10.094Z" },
@@ -1555,9 +1549,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7a/75/7e9cd1126a1e1f0cd67b0eda02e5221b28488d352684704a78ed505bd719/greenlet-3.4.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:43748988b097f9c6f09364f260741aa73c80747f63389824435c7a50bfdfd5c1", size = 285856, upload-time = "2026-04-08T15:52:45.82Z" },
     { url = "https://files.pythonhosted.org/packages/9d/c4/3e2df392e5cb199527c4d9dbcaa75c14edcc394b45040f0189f649631e3c/greenlet-3.4.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5566e4e2cd7a880e8c27618e3eab20f3494452d12fd5129edef7b2f7aa9a36d1", size = 610208, upload-time = "2026-04-08T16:24:39.674Z" },
     { url = "https://files.pythonhosted.org/packages/da/af/750cdfda1d1bd30a6c28080245be8d0346e669a98fdbae7f4102aa95fff3/greenlet-3.4.0-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1054c5a3c78e2ab599d452f23f7adafef55062a783a8e241d24f3b633ba6ff82", size = 621269, upload-time = "2026-04-08T16:30:59.767Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/93/c8c508d68ba93232784bbc1b5474d92371f2897dfc6bc281b419f2e0d492/greenlet-3.4.0-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:98eedd1803353daf1cd9ef23eef23eda5a4d22f99b1f998d273a8b78b70dd47f", size = 628455, upload-time = "2026-04-08T16:40:40.698Z" },
     { url = "https://files.pythonhosted.org/packages/54/78/0cbc693622cd54ebe25207efbb3a0eb07c2639cb8594f6e3aaaa0bb077a8/greenlet-3.4.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f82cb6cddc27dd81c96b1506f4aa7def15070c3b2a67d4e46fd19016aacce6cf", size = 617549, upload-time = "2026-04-08T15:56:34.893Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/46/cfaaa0ade435a60550fd83d07dfd5c41f873a01da17ede5c4cade0b9bab8/greenlet-3.4.0-cp313-cp313-manylinux_2_39_riscv64.whl", hash = "sha256:b7857e2202aae67bc5725e0c1f6403c20a8ff46094ece015e7d474f5f7020b55", size = 426238, upload-time = "2026-04-08T16:43:06.865Z" },
     { url = "https://files.pythonhosted.org/packages/ba/c0/8966767de01343c1ff47e8b855dc78e7d1a8ed2b7b9c83576a57e289f81d/greenlet-3.4.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:227a46251ecba4ff46ae742bc5ce95c91d5aceb4b02f885487aff269c127a729", size = 1575310, upload-time = "2026-04-08T16:26:21.671Z" },
     { url = "https://files.pythonhosted.org/packages/b8/38/bcdc71ba05e9a5fda87f63ffc2abcd1f15693b659346df994a48c968003d/greenlet-3.4.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5b99e87be7eba788dd5b75ba1cde5639edffdec5f91fe0d734a249535ec3408c", size = 1640435, upload-time = "2026-04-08T15:57:32.572Z" },
     { url = "https://files.pythonhosted.org/packages/a1/c2/19b664b7173b9e4ef5f77e8cef9f14c20ec7fce7920dc1ccd7afd955d093/greenlet-3.4.0-cp313-cp313-win_amd64.whl", hash = "sha256:849f8bc17acd6295fcb5de8e46d55cc0e52381c56eaf50a2afd258e97bc65940", size = 238760, upload-time = "2026-04-08T17:04:03.878Z" },
@@ -1565,9 +1557,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/78/02/bde66806e8f169cf90b14d02c500c44cdbe02c8e224c9c67bafd1b8cadd1/greenlet-3.4.0-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:10a07aca6babdd18c16a3f4f8880acfffc2b88dfe431ad6aa5f5740759d7d75e", size = 286291, upload-time = "2026-04-08T17:09:34.307Z" },
     { url = "https://files.pythonhosted.org/packages/05/1f/39da1c336a87d47c58352fb8a78541ce63d63ae57c5b9dae1fe02801bbc2/greenlet-3.4.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:076e21040b3a917d3ce4ad68fb5c3c6b32f1405616c4a57aa83120979649bd3d", size = 656749, upload-time = "2026-04-08T16:24:41.721Z" },
     { url = "https://files.pythonhosted.org/packages/d3/6c/90ee29a4ee27af7aa2e2ec408799eeb69ee3fcc5abcecac6ddd07a5cd0f2/greenlet-3.4.0-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e82689eea4a237e530bb5cb41b180ef81fa2160e1f89422a67be7d90da67f615", size = 669084, upload-time = "2026-04-08T16:31:01.372Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/4a/74078d3936712cff6d3c91a930016f476ce4198d84e224fe6d81d3e02880/greenlet-3.4.0-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:06c2d3b89e0c62ba50bd7adf491b14f39da9e7e701647cb7b9ff4c99bee04b19", size = 673405, upload-time = "2026-04-08T16:40:42.527Z" },
     { url = "https://files.pythonhosted.org/packages/07/49/d4cad6e5381a50947bb973d2f6cf6592621451b09368b8c20d9b8af49c5b/greenlet-3.4.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4df3b0b2289ec686d3c821a5fee44259c05cfe824dd5e6e12c8e5f5df23085cf", size = 665621, upload-time = "2026-04-08T15:56:35.995Z" },
-    { url = "https://files.pythonhosted.org/packages/79/3e/df8a83ab894751bc31e1106fdfaa80ca9753222f106b04de93faaa55feb7/greenlet-3.4.0-cp314-cp314-manylinux_2_39_riscv64.whl", hash = "sha256:070b8bac2ff3b4d9e0ff36a0d19e42103331d9737e8504747cd1e659f76297bd", size = 471670, upload-time = "2026-04-08T16:43:08.512Z" },
     { url = "https://files.pythonhosted.org/packages/37/31/d1edd54f424761b5d47718822f506b435b6aab2f3f93b465441143ea5119/greenlet-3.4.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8bff29d586ea415688f4cec96a591fcc3bf762d046a796cdadc1fdb6e7f2d5bf", size = 1622259, upload-time = "2026-04-08T16:26:23.201Z" },
     { url = "https://files.pythonhosted.org/packages/b0/c6/6d3f9cdcb21c4e12a79cb332579f1c6aa1af78eb68059c5a957c7812d95e/greenlet-3.4.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8a569c2fb840c53c13a2b8967c63621fafbd1a0e015b9c82f408c33d626a2fda", size = 1686916, upload-time = "2026-04-08T15:57:34.282Z" },
     { url = "https://files.pythonhosted.org/packages/63/45/c1ca4a1ad975de4727e52d3ffe641ae23e1d7a8ffaa8ff7a0477e1827b92/greenlet-3.4.0-cp314-cp314-win_amd64.whl", hash = "sha256:207ba5b97ea8b0b60eb43ffcacf26969dd83726095161d676aac03ff913ee50d", size = 239821, upload-time = "2026-04-08T17:03:48.423Z" },
@@ -1575,9 +1565,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/8f/18d72b629783f5e8d045a76f5325c1e938e659a9e4da79c7dcd10169a48d/greenlet-3.4.0-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:d70012e51df2dbbccfaf63a40aaf9b40c8bed37c3e3a38751c926301ce538ece", size = 294681, upload-time = "2026-04-08T15:52:35.778Z" },
     { url = "https://files.pythonhosted.org/packages/9e/ad/5fa86ec46769c4153820d58a04062285b3b9e10ba3d461ee257b68dcbf53/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a58bec0751f43068cd40cff31bb3ca02ad6000b3a51ca81367af4eb5abc480c8", size = 658899, upload-time = "2026-04-08T16:24:43.32Z" },
     { url = "https://files.pythonhosted.org/packages/43/f0/4e8174ca0e87ae748c409f055a1ba161038c43cc0a5a6f1433a26ac2e5bf/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:05fa0803561028f4b2e3b490ee41216a842eaee11aed004cc343a996d9523aa2", size = 665284, upload-time = "2026-04-08T16:31:02.833Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/92/466b0d9afd44b8af623139a3599d651c7564fa4152f25f117e1ee5949ffb/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c4cd56a9eb7a6444edbc19062f7b6fbc8f287c663b946e3171d899693b1c19fa", size = 665872, upload-time = "2026-04-08T16:40:43.912Z" },
     { url = "https://files.pythonhosted.org/packages/19/da/991cf7cd33662e2df92a1274b7eb4d61769294d38a1bba8a45f31364845e/greenlet-3.4.0-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e60d38719cb80b3ab5e85f9f1aed4960acfde09868af6762ccb27b260d68f4ed", size = 661861, upload-time = "2026-04-08T15:56:37.269Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/14/3395a7ef3e260de0325152ddfe19dffb3e49fe10873b94654352b53ad48e/greenlet-3.4.0-cp314-cp314t-manylinux_2_39_riscv64.whl", hash = "sha256:1f85f204c4d54134ae850d401fa435c89cd667d5ce9dc567571776b45941af72", size = 489237, upload-time = "2026-04-08T16:43:09.993Z" },
     { url = "https://files.pythonhosted.org/packages/36/c5/6c2c708e14db3d9caea4b459d8464f58c32047451142fe2cfd90e7458f41/greenlet-3.4.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7f50c804733b43eded05ae694691c9aa68bca7d0a867d67d4a3f514742a2d53f", size = 1622182, upload-time = "2026-04-08T16:26:24.777Z" },
     { url = "https://files.pythonhosted.org/packages/7a/4c/50c5fed19378e11a29fabab1f6be39ea95358f4a0a07e115a51ca93385d8/greenlet-3.4.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:2d4f0635dc4aa638cda4b2f5a07ae9a2cff9280327b581a3fcb6f317b4fbc38a", size = 1685050, upload-time = "2026-04-08T15:57:36.453Z" },
     { url = "https://files.pythonhosted.org/packages/db/72/85ae954d734703ab48e622c59d4ce35d77ce840c265814af9c078cacc7aa/greenlet-3.4.0-cp314-cp314t-win_amd64.whl", hash = "sha256:1a4a48f24681300c640f143ba7c404270e1ebbbcf34331d7104a4ff40f8ea705", size = 245554, upload-time = "2026-04-08T17:03:50.044Z" },
@@ -1649,7 +1637,7 @@ name = "gunicorn"
 version = "26.0.0"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "packaging", marker = "python_full_version < '3.11' or sys_platform != 'win32'" },
+    { name = "packaging" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/6d/b7/a4a3f632f823e432ce6bc65f62961b7980c898c77f075a2f7118cb3846fe/gunicorn-26.0.0.tar.gz", hash = "sha256:ca9346f85e3a4aeeb64d491045c16b9a35647abd37ea15efe53080eb8b090baf", size = 727286, upload-time = "2026-05-05T06:38:25.529Z" }
 wheels = [
@@ -1667,20 +1655,20 @@ wheels = [
 
 [[package]]
 name = "h2"
-version = "4.3.0"
+version = "4.4.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
     { name = "hpack" },
     { name = "hyperframe" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/1d/17/afa56379f94ad0fe8defd37d6eb3f89a25404ffc71d4d848893d270325fc/h2-4.3.0.tar.gz", hash = "sha256:6c59efe4323fa18b47a632221a1888bd7fde6249819beda254aeca909f221bf1", size = 2152026, upload-time = "2025-08-23T18:12:19.778Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/85/7c366e69d84c17bb778fe41419e1fbcce3033d5b7ce29bbffff0a98b859f/h2-4.4.1.tar.gz", hash = "sha256:4e866ffb1a869ae14dd9b5e6beb5c24a13da0495ad72b65925ded182521c1516", size = 2157281, upload-time = "2026-08-03T11:45:09.509Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/b2/119f6e6dcbd96f9069ce9a2665e0146588dc9f88f29549711853645e736a/h2-4.3.0-py3-none-any.whl", hash = "sha256:c438f029a25f7945c69e0ccf0fb951dc3f73a5f6412981daee861431b70e2bdd", size = 61779, upload-time = "2025-08-23T18:12:17.779Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/22/e85faf23bd72a92d1921e37d674ca56eb298a3c8be31fdecef0ff2b3aaac/h2-4.4.1-py3-none-any.whl", hash = "sha256:0e25f1462b23c9cb82d9eb02e28bc706dac2a68cb457c6a0d74d63c8a2a5d0e6", size = 62636, upload-time = "2026-08-03T11:44:59.164Z" },
 ]
 
 [[package]]
 name = "headroom-ai"
-version = "0.34.0"
+version = "0.35.0"
 source = { editable = "." }
 dependencies = [
     { name = "ast-grep-cli" },
@@ -1711,8 +1699,8 @@ all = [
     { name = "mcp" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "openai" },
     { name = "openpyxl" },
     { name = "opentelemetry-exporter-otlp-proto-http" },
@@ -1795,8 +1783,7 @@ html = [
     { name = "trafilatura" },
 ]
 image = [
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version == '3.13.*'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.13'" },
     { name = "pillow" },
     { name = "rapidocr", marker = "python_full_version >= '3.13'" },
     { name = "rapidocr-onnxruntime", marker = "python_full_version < '3.13'" },
@@ -1835,8 +1822,8 @@ proxy = [
     { name = "httpx", extra = ["http2"] },
     { name = "magika" },
     { name = "mcp" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "openai" },
     { name = "orjson", marker = "platform_python_implementation != 'PyPy'" },
     { name = "sqlite-vec" },
@@ -1852,8 +1839,8 @@ proxy-prod = [
     { name = "httpx", extra = ["http2"] },
     { name = "magika" },
     { name = "mcp" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "openai" },
     { name = "orjson", marker = "platform_python_implementation != 'PyPy'" },
     { name = "sqlite-vec" },
@@ -1884,8 +1871,8 @@ sandbox = [
     { name = "mcp" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "openai" },
     { name = "openpyxl" },
     { name = "opentelemetry-exporter-otlp-proto-http" },
@@ -1914,16 +1901,16 @@ vector = [
     { name = "hnswlib" },
 ]
 voice = [
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "torch", marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'" },
     { name = "transformers" },
 ]
 voice-train = [
     { name = "accelerate" },
     { name = "datasets" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "torch", marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'" },
     { name = "transformers" },
 ]
@@ -1973,9 +1960,11 @@ requires-dist = [
     { name = "numpy", marker = "extra == 'evals'", specifier = ">=1.24.0" },
     { name = "numpy", marker = "extra == 'relevance'", specifier = ">=1.24.0" },
     { name = "ollama", marker = "extra == 'dev'", specifier = ">=0.4.0" },
+    { name = "onnxruntime", marker = "python_full_version >= '3.11' and extra == 'proxy'", specifier = ">=1.24.0" },
+    { name = "onnxruntime", marker = "python_full_version >= '3.11' and extra == 'voice'", specifier = ">=1.24.0" },
+    { name = "onnxruntime", marker = "python_full_version < '3.11' and extra == 'proxy'", specifier = ">=1.16.0,<1.24.0" },
+    { name = "onnxruntime", marker = "python_full_version < '3.11' and extra == 'voice'", specifier = ">=1.16.0,<1.24.0" },
     { name = "onnxruntime", marker = "python_full_version >= '3.13' and extra == 'image'", specifier = ">=1.7,<2" },
-    { name = "onnxruntime", marker = "extra == 'proxy'", specifier = ">=1.16.0" },
-    { name = "onnxruntime", marker = "extra == 'voice'", specifier = ">=1.16.0" },
     { name = "openai", marker = "extra == 'dev'", specifier = ">=1.0.0" },
     { name = "openai", marker = "extra == 'evals'", specifier = ">=1.0.0" },
     { name = "openai", marker = "extra == 'proxy'", specifier = ">=2.14.0" },
@@ -1999,7 +1988,7 @@ requires-dist = [
     { name = "rapidocr-onnxruntime", marker = "python_full_version < '3.13' and extra == 'image'", specifier = ">=1.4.0,<2" },
     { name = "respx", marker = "extra == 'dev'", specifier = ">=0.20.0" },
     { name = "rich", specifier = ">=13.0.0" },
-    { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.17" },
+    { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.22" },
     { name = "scikit-learn", marker = "extra == 'evals'", specifier = ">=1.3.0" },
     { name = "sentence-transformers", marker = "sys_platform == 'darwin' and extra == 'pytorch-mps'", specifier = ">=2.2.0" },
     { name = "sentence-transformers", marker = "(platform_machine != 'x86_64' and extra == 'evals') or (sys_platform != 'darwin' and extra == 'evals')", specifier = ">=2.2.0,<6.0" },
@@ -2078,11 +2067,11 @@ sdist = { url = "https://files.pythonhosted.org/packages/cf/7a/1a9b1405f2eb59515
 
 [[package]]
 name = "hpack"
-version = "4.1.0"
+version = "4.2.0"
 source = { registry = "https://pypi.org/simple/" }
-sdist = { url = "https://files.pythonhosted.org/packages/2c/48/71de9ed269fdae9c8057e5a4c0aa7402e8bb16f2c6e90b3aa53327b113f8/hpack-4.1.0.tar.gz", hash = "sha256:ec5eca154f7056aa06f196a557655c5b009b382873ac8d1e66e79e87535f1dca", size = 51276, upload-time = "2025-01-22T21:44:58.347Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/26/5b/fcabf6028144a8723726318b07a32c2f3314acdff6265743cf08a344b18e/hpack-4.2.0.tar.gz", hash = "sha256:0895cfa3b5531fc65fe439c05eb65144f123bf7a394fcaa56aa423548d8e45c0", size = 51300, upload-time = "2026-06-23T18:34:46.667Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/07/c6/80c95b1b2b94682a72cbdbfb85b81ae2daffa4291fbfa1b1464502ede10d/hpack-4.1.0-py3-none-any.whl", hash = "sha256:157ac792668d995c657d93111f46b4535ed114f0c9c8d672271bbec7eae1b496", size = 34357, upload-time = "2025-01-22T21:44:56.92Z" },
+    { url = "https://files.pythonhosted.org/packages/71/b4/4a9fcfb2aef6ba44d9073ecd301443aa00b3dac95de5619f2a7de7ec8a91/hpack-4.2.0-py3-none-any.whl", hash = "sha256:858ac0b02280fa582b5080d68db0899c62a80375e0e5413a74970c5e518b6986", size = 34246, upload-time = "2026-06-23T18:34:45.472Z" },
 ]
 
 [[package]]
@@ -2218,7 +2207,7 @@ name = "humanfriendly"
 version = "10.0"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "pyreadline3", marker = "python_full_version < '3.14' and sys_platform == 'win32'" },
+    { name = "pyreadline3", marker = "sys_platform == 'win32'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/cc/3f/2c29224acb2e2df4d2046e4c73ee2662023c58ff5b113c4c1adac0886c43/humanfriendly-10.0.tar.gz", hash = "sha256:6b0b831ce8f15f7300721aa49829fc4e83921a9a301cc7f606be6686a2288ddc", size = 360702, upload-time = "2021-09-17T21:40:43.31Z" }
 wheels = [
@@ -2701,18 +2690,18 @@ name = "litellm"
 version = "1.88.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "aiohttp", marker = "python_full_version < '3.14'" },
-    { name = "click", marker = "python_full_version < '3.14'" },
-    { name = "fastuuid", marker = "python_full_version < '3.14'" },
-    { name = "httpx", marker = "python_full_version < '3.14'" },
-    { name = "importlib-metadata", marker = "python_full_version < '3.14'" },
-    { name = "jinja2", marker = "python_full_version < '3.14'" },
-    { name = "jsonschema", marker = "python_full_version < '3.14'" },
-    { name = "openai", marker = "python_full_version < '3.14'" },
-    { name = "pydantic", marker = "python_full_version < '3.14'" },
-    { name = "python-dotenv", marker = "python_full_version < '3.14'" },
-    { name = "tiktoken", marker = "python_full_version < '3.14'" },
-    { name = "tokenizers", marker = "python_full_version < '3.14'" },
+    { name = "aiohttp" },
+    { name = "click" },
+    { name = "fastuuid" },
+    { name = "httpx" },
+    { name = "importlib-metadata" },
+    { name = "jinja2" },
+    { name = "jsonschema" },
+    { name = "openai" },
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "tiktoken" },
+    { name = "tokenizers" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/16/ea/f99ececb7f22703fe120f1d8be9ffb749ec9453fbbbbbebc0d6a6b4d7864/litellm-1.88.1.tar.gz", hash = "sha256:89c6b74cc7912d6365793006ff951c0450fe847625008dfe49de8a7dc4529aa5", size = 13885969, upload-time = "2026-06-09T01:06:25.192Z" }
 wheels = [
@@ -2875,8 +2864,8 @@ dependencies = [
     { name = "click" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.14'" },
-    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
     { name = "python-dotenv" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/fe/b6/8fdd991142ad3e037179a494b153f463024e5a211ef3ad948b955c26b4de/magika-0.6.2.tar.gz", hash = "sha256:37eb6ae8020f6e68f231bc06052c0a0cbe8e6fa27492db345e8dc867dbceb067", size = 3036634, upload-time = "2025-05-02T14:54:18.88Z" }
@@ -3594,7 +3583,7 @@ name = "nvidia-cublas"
 version = "13.1.1.3"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cuda-nvrtc" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/a7/a1/0bd24ee8c8d03adac032fd2909426a00c88f8c57961b1277ded97f91119f/nvidia_cublas-13.1.1.3-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:b7a210458267ac818974c53038fbec2e969d5c99f305ab15c72522fa9f001dd5", size = 542848918, upload-time = "2026-04-08T18:46:22.985Z" },
@@ -3633,7 +3622,7 @@ name = "nvidia-cudnn-cu13"
 version = "9.20.0.48"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cublas" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/56/c5/83384d846b2fd17c44bd499b36c75a45ed4f095fbbb2252294e89cea5c5c/nvidia_cudnn_cu13-9.20.0.48-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:e31454ae00094b0c55319d9d15b6fa2fc50a9e1c0f5c8c80fb75258234e731e1", size = 444574296, upload-time = "2026-03-09T19:28:27.751Z" },
@@ -3645,7 +3634,7 @@ name = "nvidia-cufft"
 version = "12.0.0.61"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-nvjitlink" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/8b/ae/f417a75c0259e85c1d2f83ca4e960289a5f814ed0cea74d18c353d3e989d/nvidia_cufft-12.0.0.61-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2708c852ef8cd89d1d2068bdbece0aa188813a0c934db3779b9b1faa8442e5f5", size = 214053554, upload-time = "2025-09-04T08:31:38.196Z" },
@@ -3675,9 +3664,9 @@ name = "nvidia-cusolver"
 version = "12.0.4.66"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
-    { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cublas" },
+    { name = "nvidia-cusparse" },
+    { name = "nvidia-nvjitlink" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/c8/c3/b30c9e935fc01e3da443ec0116ed1b2a009bb867f5324d3f2d7e533e776b/nvidia_cusolver-12.0.4.66-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:02c2457eaa9e39de20f880f4bd8820e6a1cfb9f9a34f820eb12a155aa5bc92d2", size = 223467760, upload-time = "2025-09-04T08:33:04.222Z" },
@@ -3689,7 +3678,7 @@ name = "nvidia-cusparse"
 version = "12.6.3.3"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-nvjitlink" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/f8/94/5c26f33738ae35276672f12615a64bd008ed5be6d1ebcb23579285d960a9/nvidia_cusparse-12.6.3.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:80bcc4662f23f1054ee334a15c72b8940402975e0eab63178fc7e670aa59472c", size = 162155568, upload-time = "2025-09-04T08:33:42.864Z" },
@@ -3768,8 +3757,8 @@ name = "omegaconf"
 version = "2.3.0"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "antlr4-python3-runtime", marker = "python_full_version >= '3.13'" },
-    { name = "pyyaml", marker = "python_full_version >= '3.13'" },
+    { name = "antlr4-python3-runtime" },
+    { name = "pyyaml" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/09/48/6388f1bb9da707110532cb70ec4d2822858ddfb44f1cdf1233c20a80ea4b/omegaconf-2.3.0.tar.gz", hash = "sha256:d5d4b6d29955cc50ad50c46dc269bcd92c6e00f5f90d23ab5fee7bfca4ba4cc7", size = 3298120, upload-time = "2022-12-08T20:59:22.753Z" }
 wheels = [
@@ -3781,25 +3770,15 @@ name = "onnxruntime"
 version = "1.23.2"
 source = { registry = "https://pypi.org/simple/" }
 resolution-markers = [
-    "python_full_version == '3.13.*' and sys_platform == 'win32'",
-    "python_full_version == '3.12.*' and sys_platform == 'win32'",
-    "python_full_version == '3.13.*' and sys_platform == 'emscripten'",
-    "python_full_version == '3.12.*' and sys_platform == 'emscripten'",
-    "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
-    "python_full_version == '3.12.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
-    "python_full_version == '3.11.*' and sys_platform == 'win32'",
-    "python_full_version == '3.11.*' and sys_platform == 'emscripten'",
-    "python_full_version == '3.11.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "coloredlogs", marker = "python_full_version < '3.14'" },
-    { name = "flatbuffers", marker = "python_full_version < '3.14'" },
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11' and python_full_version < '3.14'" },
-    { name = "packaging", marker = "python_full_version < '3.14'" },
-    { name = "protobuf", marker = "python_full_version < '3.14'" },
-    { name = "sympy", marker = "python_full_version < '3.14'" },
+    { name = "coloredlogs" },
+    { name = "flatbuffers" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" } },
+    { name = "packaging" },
+    { name = "protobuf" },
+    { name = "sympy" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/35/d6/311b1afea060015b56c742f3531168c1644650767f27ef40062569960587/onnxruntime-1.23.2-cp310-cp310-macosx_13_0_arm64.whl", hash = "sha256:a7730122afe186a784660f6ec5807138bf9d792fa1df76556b27307ea9ebcbe3", size = 17195934, upload-time = "2025-10-27T23:06:14.143Z" },
@@ -3834,12 +3813,21 @@ resolution-markers = [
     "python_full_version >= '3.14' and sys_platform == 'win32'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'",
+    "python_full_version == '3.13.*' and sys_platform == 'win32'",
+    "python_full_version == '3.12.*' and sys_platform == 'win32'",
+    "python_full_version == '3.13.*' and sys_platform == 'emscripten'",
+    "python_full_version == '3.12.*' and sys_platform == 'emscripten'",
+    "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
+    "python_full_version == '3.12.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
+    "python_full_version == '3.11.*' and sys_platform == 'win32'",
+    "python_full_version == '3.11.*' and sys_platform == 'emscripten'",
+    "python_full_version == '3.11.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "flatbuffers", marker = "python_full_version >= '3.14'" },
-    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.14'" },
-    { name = "packaging", marker = "python_full_version >= '3.14'" },
-    { name = "protobuf", marker = "python_full_version >= '3.14'" },
+    { name = "flatbuffers" },
+    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" } },
+    { name = "packaging" },
+    { name = "protobuf" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/81/29a9eb470994a75eb7b3ccf32be314d7c66675a00ac7b50294816cc2db27/onnxruntime-1.26.0-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:ee1109ef4ef27cad90e823399e61e03b3c6c7bfe0fb820b4baf3678c15be8b3c", size = 18005108, upload-time = "2026-05-08T19:08:11.728Z" },
@@ -3923,7 +3911,7 @@ name = "openresponses-types"
 version = "2.3.0.post1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "pydantic", marker = "python_full_version >= '3.11'" },
+    { name = "pydantic" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/d9/26/b612c3215f5599714fa94d63eb5ee59b4eb66dbdeeaf86bb4d848359484d/openresponses_types-2.3.0.post1.tar.gz", hash = "sha256:11b8896d3621d2ac2439f6ff106f34ddcb1bbd517c317a6c852a9df2e98a0753", size = 19254, upload-time = "2026-01-22T20:02:03.933Z" }
 wheels = [
@@ -4166,10 +4154,10 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
-    { name = "python-dateutil", marker = "python_full_version < '3.11'" },
-    { name = "pytz", marker = "python_full_version < '3.11'" },
-    { name = "tzdata", marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" } },
+    { name = "python-dateutil" },
+    { name = "pytz" },
+    { name = "tzdata" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/33/01/d40b85317f86cf08d853a4f495195c73815fdf205eef3993821720274518/pandas-2.3.3.tar.gz", hash = "sha256:e05e1af93b977f7eafa636d043f9f94c7ee3ac81af99c13508215942e64c993b", size = 4495223, upload-time = "2025-09-29T23:34:51.853Z" }
 wheels = [
@@ -4241,9 +4229,9 @@ resolution-markers = [
     "python_full_version == '3.11.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "python-dateutil", marker = "python_full_version >= '3.11'" },
-    { name = "tzdata", marker = "(python_full_version >= '3.11' and sys_platform == 'emscripten') or (python_full_version >= '3.11' and sys_platform == 'win32')" },
+    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" } },
+    { name = "python-dateutil" },
+    { name = "tzdata", marker = "sys_platform == 'emscripten' or sys_platform == 'win32'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/de/da/b1dc0481ab8d55d0f46e343cfe67d4551a0e14fcee52bd38ca1bd73258d8/pandas-3.0.0.tar.gz", hash = "sha256:0facf7e87d38f721f0af46fe70d97373a37701b1c09f7ed7aeeb292ade5c050f", size = 4633005, upload-time = "2026-01-21T15:52:04.726Z" }
 wheels = [
@@ -5405,17 +5393,17 @@ name = "rapidocr"
 version = "3.8.1"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "colorlog", marker = "python_full_version >= '3.13'" },
-    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.13'" },
-    { name = "omegaconf", marker = "python_full_version >= '3.13'" },
-    { name = "opencv-python", marker = "python_full_version >= '3.13'" },
-    { name = "pillow", marker = "python_full_version >= '3.13'" },
-    { name = "pyclipper", marker = "python_full_version >= '3.13'" },
-    { name = "pyyaml", marker = "python_full_version >= '3.13'" },
-    { name = "requests", marker = "python_full_version >= '3.13'" },
-    { name = "shapely", marker = "python_full_version >= '3.13'" },
-    { name = "six", marker = "python_full_version >= '3.13'" },
-    { name = "tqdm", marker = "python_full_version >= '3.13'" },
+    { name = "colorlog" },
+    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" } },
+    { name = "omegaconf" },
+    { name = "opencv-python" },
+    { name = "pillow" },
+    { name = "pyclipper" },
+    { name = "pyyaml" },
+    { name = "requests" },
+    { name = "shapely" },
+    { name = "six" },
+    { name = "tqdm" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ea/4a/fa521d947f0fc7bb304bf11bec4cb66266bd81494588b4cb48dc01001719/rapidocr-3.8.1-py3-none-any.whl", hash = "sha256:650044b1fbce9e6bae5cae462dcf8be754cde11e2f23fc51f65dcc08deae2c46", size = 15080319, upload-time = "2026-04-11T07:13:22.56Z" },
@@ -5426,16 +5414,17 @@ name = "rapidocr-onnxruntime"
 version = "1.4.4"
 source = { registry = "https://pypi.org/simple/" }
 dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.13'" },
-    { name = "opencv-python", marker = "python_full_version < '3.13'" },
-    { name = "pillow", marker = "python_full_version < '3.13'" },
-    { name = "pyclipper", marker = "python_full_version < '3.13'" },
-    { name = "pyyaml", marker = "python_full_version < '3.13'" },
-    { name = "shapely", marker = "python_full_version < '3.13'" },
-    { name = "six", marker = "python_full_version < '3.13'" },
-    { name = "tqdm", marker = "python_full_version < '3.13'" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "onnxruntime", version = "1.26.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "opencv-python" },
+    { name = "pillow" },
+    { name = "pyclipper" },
+    { name = "pyyaml" },
+    { name = "shapely" },
+    { name = "six" },
+    { name = "tqdm" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ba/12/1e5497183bdbe782dbb91bad1d0d2297dba4d2831b2652657f7517bfc6df/rapidocr_onnxruntime-1.4.4-py3-none-any.whl", hash = "sha256:971d7d5f223a7a808662229df1ef69893809d8457d834e6373d3854bc1782cbf", size = 14915192, upload-time = "2025-01-17T01:48:25.104Z" },
@@ -5765,27 +5754,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.17"
+version = "0.15.22"
 source = { registry = "https://pypi.org/simple/" }
-sdist = { url = "https://files.pythonhosted.org/packages/8c/a9/3abdf488f1bf3d24c699415e454ed554a6350d5d89ce183be1ee0a3361ac/ruff-0.15.17.tar.gz", hash = "sha256:2ec446937fd16c8c4de2674a209cc5af64d9c6f17d21fbf1151054fa0bcf5219", size = 4743346, upload-time = "2026-06-11T17:54:47.663Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/3a/06/ae069393fc66e8ff33036d4b368003833bf6e88ccf182e17e7a2f1c754fd/ruff-0.15.22.tar.gz", hash = "sha256:3f15175b1fb580126f58285a5dae6b2ea89000136d980c64499211f116b54809", size = 4785063, upload-time = "2026-07-16T15:14:13.244Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/db/4d/e11259f5da07cb6afb2d074c31bf09da9671993f7329d4f15d2fdc458301/ruff-0.15.17-py3-none-linux_armv6l.whl", hash = "sha256:d9feddb927fc68bd295f5eebc587a7e42cfaf9b65f60ca4a2386febff575da8f", size = 10856677, upload-time = "2026-06-11T17:54:49.533Z" },
-    { url = "https://files.pythonhosted.org/packages/29/3e/772d679e1a0dc058e58875bd2c0cb713a0530877b4a76fee3c7966df0d49/ruff-0.15.17-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:25805a226d741c47d274a35ad5c10a7dde175fcddfa511d7cf3da0a21eb3eab7", size = 11223443, upload-time = "2026-06-11T17:55:00.573Z" },
-    { url = "https://files.pythonhosted.org/packages/68/58/bd41f7688b2fd5623012605130ed70e60aa7f2244baa3d5066bdd61530c8/ruff-0.15.17-py3-none-macosx_11_0_arm64.whl", hash = "sha256:f6ad73b14c2d18a3bf8ad7cb6974294d7f613a7898604826058e6ac64918ef4d", size = 10566458, upload-time = "2026-06-11T17:55:07.52Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/5b/733371013fcf1ec339e477ece6ab42bfe10bdd9bba8ee88a9516aa56bfc0/ruff-0.15.17-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6ba0c1e4f95bcb3869d0d30cbd5917071ef2e28665abfec970cdab0492c713ed", size = 10914483, upload-time = "2026-06-11T17:55:05.501Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/cc/6f24251cc0252f7239391ccb85833f320efad14ebe5b443943f37ced6332/ruff-0.15.17-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:81647960f10bff57d2e51cadd0c3950fe598400c852863a038720ef5b8cca91e", size = 10647497, upload-time = "2026-06-11T17:54:57.733Z" },
-    { url = "https://files.pythonhosted.org/packages/68/dd/0d10c17ce1a1624d6fc3156309c3f834fdb5dfaad026ec90c85684f3990e/ruff-0.15.17-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0e01a84ddbc8c16c23055ba3924476850f1bbc1917cebbb9376665a63e74260d", size = 11416967, upload-time = "2026-06-11T17:54:51.461Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/91/556bfb156f6144f355e831c23db00b2fc4120f86b3ce81cc5f7fd2df51f3/ruff-0.15.17-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:84fe9f653152f8f294f9f7e03bf3a453d8b4a27f7a59c78c8666167f2b17b96c", size = 12335770, upload-time = "2026-06-11T17:54:45.793Z" },
-    { url = "https://files.pythonhosted.org/packages/88/82/8b5999aa13355e926f06d9f42a32dcca862f623bf0363785ff89d607dffd/ruff-0.15.17-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8c0fe88a7676e7a05b73174d4d4a59cb2ac21ff8263583f87a81a6018475a978", size = 11575441, upload-time = "2026-06-11T17:54:32.661Z" },
-    { url = "https://files.pythonhosted.org/packages/11/93/f10377bb04109ca0e8cbc483ff1982c54b6d418210041776f93e8cdc7fa9/ruff-0.15.17-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ecfc3c7878fff94633ab0348524e093f9ce3243080416dd7d14f8ba400174719", size = 11557614, upload-time = "2026-06-11T17:54:34.698Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/a6/eeeae7f7d5493df41649ab3db92f086b2d0a30199e4efdf8e3dd7a033f24/ruff-0.15.17-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:b8461180b22420b1bdc289909410930761629fddf2a5aaf60fae1ab26cedc4c4", size = 11544450, upload-time = "2026-06-11T17:54:39.042Z" },
-    { url = "https://files.pythonhosted.org/packages/32/88/5991ce565129a24dd4a00db1254b3b5db2e53018cbe4018ea5a89738e727/ruff-0.15.17-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:6eccbe50a038b503e7140b441aa9c7fc8c1f36edf23ebef9f4165c2f28f568b7", size = 10892524, upload-time = "2026-06-11T17:55:09.432Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/1d/0fdd248313425f55223968af04b0a42125466a8d88d21c1d99c6af0a51e8/ruff-0.15.17-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:382fc0521025f5a8ad447d8bdd523545d0d7646adb718eb1c2dac5065ec27c0f", size = 10659573, upload-time = "2026-06-11T17:54:36.824Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/0e/072e8260deb9461062ce9311ced27a8e541229a6ffd483013dd37661e43e/ruff-0.15.17-py3-none-musllinux_1_2_i686.whl", hash = "sha256:456d41fcd1b2777ad63f09a6e7121d43f7b688bbc76a800c10f7f8fb1f912c3f", size = 11127818, upload-time = "2026-06-11T17:55:03.124Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/b4/55060a34163121498014696b5f656db5b8c6963768f227dbf0d76b311073/ruff-0.15.17-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b1a04bcc94ae6194e9db05d16ad31f298a7194bfbcb08258bbe589cee1d587b8", size = 11655901, upload-time = "2026-06-11T17:54:53.562Z" },
-    { url = "https://files.pythonhosted.org/packages/49/71/9b29d6b87cef468d697f43c6a91e3fae4a80185779d7d5a4ef27d173439f/ruff-0.15.17-py3-none-win32.whl", hash = "sha256:596065960ab1ff593f744220c9fe6580eda00a95003cffa9f4048bb5b1bf0392", size = 10925574, upload-time = "2026-06-11T17:54:55.723Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/b2/8fc77f3723228836fa5d12497eb71c808f83782e10d058d2b15cfa14640b/ruff-0.15.17-py3-none-win_amd64.whl", hash = "sha256:6769e5fa1710b179b92e0bfa5a51735b35baea9013dadb06d5f44cbcf9547084", size = 12058788, upload-time = "2026-06-11T17:54:41.042Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/c7/c53e8dbff9c9dc4b7928773421ae294a5d28fcb8dcda1a089579d3a7e510/ruff-0.15.17-py3-none-win_arm64.whl", hash = "sha256:f3be1fbb34bcdfd146240d8fb92a709d4c2c8191348580a3c044ec60fa0b4456", size = 11355275, upload-time = "2026-06-11T17:54:43.635Z" },
+    { url = "https://files.pythonhosted.org/packages/23/18/ee54b7ae1e121be7a28ea6da4b67564ebb0530e183a54415ab7e3bcd2c4e/ruff-0.15.22-py3-none-linux_armv6l.whl", hash = "sha256:44423e73493737f5e7c5b41d475483898ff37afcdae38bc3da5085e29af1c2d8", size = 10781258, upload-time = "2026-07-16T15:13:19.452Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/d2/2520cb14761ddbeaf57642a76942fc36adcbdbe53b4532241995f6fc485c/ruff-0.15.22-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b82c6482946e9eda7ff2e091d25b8bad3f718684e1916d41bd56873cee05b697", size = 10999477, upload-time = "2026-07-16T15:13:23.318Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/10/74e53572aa758dfaa678c2a2646b5c5515d884b7ca56be4d2ce03ca4b560/ruff-0.15.22-py3-none-macosx_11_0_arm64.whl", hash = "sha256:11c1c715af53a09f714e011106bffc419751ec8232fcb5da42173284ea3fec6f", size = 10466716, upload-time = "2026-07-16T15:13:26.162Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/cc/44eaaf0844e028182f2d0a8f2190d0f359159aed0a9e5ab861d892f1ae2a/ruff-0.15.22-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:742a29cf29bddb7c8327895d6a10e0e6c5b38a96dd407af9b5d0857f809c0576", size = 10892644, upload-time = "2026-07-16T15:13:29.229Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/21/8edf559014d2b0f82beea19cfb713993ad802ccda16868769979c6090a84/ruff-0.15.22-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72af58b951b0ae395935ae79763dc349bc0eb706319d28f7a33ad2cfb3cfc178", size = 10576719, upload-time = "2026-07-16T15:13:32.35Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/1e/3a13abd392a3b50b62e5938a831f9ab6e588358cacad5c18545b716d2182/ruff-0.15.22-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:62d425005c1835eb24e2ee4161cb90e8db263415f4a71c8c72c33abaa6c0c224", size = 11376494, upload-time = "2026-07-16T15:13:35.958Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/3e/422d3d95bcf04dd78e1aeac22184d4f9a8fb2c01865d39d44618484a0317/ruff-0.15.22-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e8b9b3f8779a4f08c969defc3c8c35abffaa757e601ed5ae66d6d1db6519969a", size = 12208370, upload-time = "2026-07-16T15:13:39.185Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/91/5d065a0e0a02bf4813f5119ad278462eed081d2b832eb7c021ade0ec9e65/ruff-0.15.22-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1e0dd1b2e4d3d585f897a0d137cbf4eaf6223bef4e8ce34d6bb12556c5f9249e", size = 11581098, upload-time = "2026-07-16T15:13:42.132Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/f9/a0d4871d12fae702eb1f41b686caf05f1f8b124dc6db6f784f53d74918fa/ruff-0.15.22-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:365523eb91d9224e1bcb03b022fbf0facb8f9e23792a2c53d9d4b3924bdbdebb", size = 11399422, upload-time = "2026-07-16T15:13:45.2Z" },
+    { url = "https://files.pythonhosted.org/packages/18/80/c843a5176cddbceb0b7e8dd41cf9993490796c1c469348d384f5a5c13c56/ruff-0.15.22-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:fabfd168afdf29fee5be98b831efa9683c94d7c5a3b58b9ce5a2e38444589a74", size = 11381683, upload-time = "2026-07-16T15:13:48.46Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/00/8485de0ae92239438a36cfc51350db9b9e85c9ebdfaea91b18e422706662/ruff-0.15.22-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:225dbf095a87f1d9f90f5fd7924d2613ee452a75a4308c63a8f50f761787aa7c", size = 10850295, upload-time = "2026-07-16T15:13:51.655Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/91/24977ec2ec72eaf15e4394ace2959fdff2dd1e14f03e005e838023407169/ruff-0.15.22-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:1877d63b9d24ed278744f1523fd11b85540566d54641f97c566d7d9dc5ca5296", size = 10579640, upload-time = "2026-07-16T15:13:54.79Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/47/9b51216951974df1f263ac19da550d34252e0ed7218c25f10c5ef9ed7517/ruff-0.15.22-py3-none-musllinux_1_2_i686.whl", hash = "sha256:a1606c510bd7215680d32efab38965f7cdec3ef69f5170a3f4791404ffdd5262", size = 11105077, upload-time = "2026-07-16T15:13:57.915Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/47/20e9d4a3b8016778acea5fc32bb50d35d207500a17ddb529ffa6996feef8/ruff-0.15.22-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:630479b18625f5ffc373f77603a22a9f8ac0acd7ff0501178b5db28ec71e9c64", size = 11490980, upload-time = "2026-07-16T15:14:01.032Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/76/3f72d8fc38c1cb77b38c56a70da9d0c17700cc1cc50f9649c9d3c8f5ba71/ruff-0.15.22-py3-none-win32.whl", hash = "sha256:e5ba0e4a13fd14abbed2a77b517a3911290c6c6c59ef67784328d1668fab76cf", size = 10789165, upload-time = "2026-07-16T15:14:04.16Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/46/4965251734c2b6fcdca1b1b187d20bcac3af0ee5b083b89c910bb961ce3a/ruff-0.15.22-py3-none-win_amd64.whl", hash = "sha256:9be63ba1eb936acd2d1342fb8337c356353706fce233b2a15a09a97037e6acde", size = 11938297, upload-time = "2026-07-16T15:14:07.316Z" },
+    { url = "https://files.pythonhosted.org/packages/57/c9/e69b1ff4c8b69093ef08b8919ab767af0569666865b39c30a8795d88d3c6/ruff-0.15.22-py3-none-win_arm64.whl", hash = "sha256:e1168075b72158510839f250027659cdd78476f40507dd517892304c41318661", size = 11298172, upload-time = "2026-07-16T15:14:10.51Z" },
 ]
 
 [[package]]
@@ -5832,10 +5821,10 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "joblib", marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
-    { name = "threadpoolctl", marker = "python_full_version < '3.11'" },
+    { name = "joblib" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" } },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple/" } },
+    { name = "threadpoolctl" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/98/c2/a7855e41c9d285dfe86dc50b250978105dce513d6e459ea66a6aeb0e1e0c/scikit_learn-1.7.2.tar.gz", hash = "sha256:20e9e49ecd130598f1ca38a1d85090e1a600147b9c02fa6f15d69cb53d968fda", size = 7193136, upload-time = "2025-09-09T08:21:29.075Z" }
 wheels = [
@@ -5890,10 +5879,10 @@ resolution-markers = [
     "python_full_version == '3.11.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "joblib", marker = "python_full_version >= '3.11'" },
-    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "scipy", version = "1.17.0", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
-    { name = "threadpoolctl", marker = "python_full_version >= '3.11'" },
+    { name = "joblib" },
+    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" } },
+    { name = "scipy", version = "1.17.0", source = { registry = "https://pypi.org/simple/" } },
+    { name = "threadpoolctl" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0e/d4/40988bf3b8e34feec1d0e6a051446b1f66225f8529b9309becaeef62b6c4/scikit_learn-1.8.0.tar.gz", hash = "sha256:9bccbb3b40e3de10351f8f5068e105d0f4083b1a65fa07b6634fbc401a6287fd", size = 7335585, upload-time = "2025-12-10T07:08:53.618Z" }
 wheels = [
@@ -5943,7 +5932,7 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0f/37/6964b830433e654ec7485e45a00fc9a27cf868d622838f6b6d9c5ec0d532/scipy-1.15.3.tar.gz", hash = "sha256:eae3cf522bc7df64b42cad3925c876e1b0b6c35c1337c93e12c0f366f55b0eaf", size = 59419214, upload-time = "2025-05-08T16:13:05.955Z" }
 wheels = [
@@ -6013,7 +6002,7 @@ resolution-markers = [
     "python_full_version == '3.11.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
+    { name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/56/3e/9cca699f3486ce6bc12ff46dc2031f1ec8eb9ccc9a320fdaf925f1417426/scipy-1.17.0.tar.gz", hash = "sha256:2591060c8e648d8b96439e111ac41fd8342fdeff1876be2e19dea3fe8930454e", size = 30396830, upload-time = "2026-01-10T21:34:23.009Z" }
 wheels = [
diff --git a/wiki/cli.md b/wiki/cli.md
index 369936666..42a591960 100644
--- a/wiki/cli.md
+++ b/wiki/cli.md
@@ -637,7 +637,7 @@ Options:
                                   (already the default).
   --image TEXT                    Docker image to use when runtime=docker or
                                   preset=persistent-docker.  [default:
-                                  ghcr.io/chopratejas/headroom:latest]
+                                  ghcr.io/headroomlabs-ai/headroom:latest]
   -?, --help                      Show this message and exit.
 ```
 
@@ -665,7 +665,7 @@ headroom install apply --preset persistent-docker --scope user
 | `--memory` | off | Enable persistent memory in the managed runtime |
 | `--telemetry` | off | Opt in to anonymous telemetry (off by default) |
 | `--no-telemetry` | off | Force anonymous telemetry off (already the default) |
-| `--image` | `ghcr.io/chopratejas/headroom:latest` | Docker image for Docker-backed installs |
+| `--image` | `ghcr.io/headroomlabs-ai/headroom:latest` | Docker image for Docker-backed installs |
 
 `apply` stores a manifest under
 `${HEADROOM_WORKSPACE_DIR}/deploy/<profile>/manifest.json` (default
diff --git a/wiki/configuration.md b/wiki/configuration.md
index 3c594e525..58b011e04 100644
--- a/wiki/configuration.md
+++ b/wiki/configuration.md
@@ -2,6 +2,26 @@
 
 Headroom can be configured via the SDK, proxy command line, or per-request overrides.
 
+## Runtime Rollout Channels
+
+Rollout channels control behaviors in an already-installed artifact. They do
+not install or select a Headroom release/version.
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HEADROOM_ROLLOUT_CHANNEL` | `stable` | Selects `stable`, `beta`, `canary`, or `dev`. |
+| `HEADROOM_FEATURES` | unset | Comma-separated feature names to request explicitly. |
+| `HEADROOM_DISABLE_FEATURES` | unset | Comma-separated feature names to force off. Disable wins over every enable path. |
+| `HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES` | unset | Break-glass override for emergency mitigation only. |
+
+Example:
+
+```bash
+export HEADROOM_ROLLOUT_CHANNEL=canary
+export HEADROOM_FEATURES=tool_result_interceptors
+headroom proxy --intercept-tool-results
+```
+
 ## SDK Configuration
 
 ```python
diff --git a/wiki/docker-install.md b/wiki/docker-install.md
index f134eb0cb..de3956275 100644
--- a/wiki/docker-install.md
+++ b/wiki/docker-install.md
@@ -27,7 +27,7 @@ irm https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.
 ## What the installer does
 
 1. Verifies Docker is installed and available.
-2. Pulls `ghcr.io/chopratejas/headroom:latest` by default, or reuses / pulls `HEADROOM_DOCKER_IMAGE` when you set a custom image override.
+2. Pulls `ghcr.io/headroomlabs-ai/headroom:latest` by default, or reuses / pulls `HEADROOM_DOCKER_IMAGE` when you set a custom image override.
 3. Installs a `headroom` wrapper into `~/.local/bin` or `~/bin`.
 4. Updates shell startup files so the wrapper directory is on `PATH`.
 
@@ -41,7 +41,7 @@ The wrapper keeps Headroom inside Docker and mounts host state back into the con
 
 Port `8787` stays the default, so `http://localhost:8787` works the same way as a native install.
 
-Published releases also push versioned GHCR tags such as `ghcr.io/chopratejas/headroom:0.5.26`, and those images are built with the same synced package version used for the matching PyPI and npm release.
+Published releases also push versioned GHCR tags such as `ghcr.io/headroomlabs-ai/headroom:0.35.0`, and those images are built with the same synced package version used for the matching PyPI and npm release.
 
 ## How the wrapper behaves
 
@@ -63,7 +63,7 @@ docker run --rm -it \
   -p 8787:8787 \
   -v "$PWD:/workspace" \
   -w /workspace \
-  ghcr.io/chopratejas/headroom:latest \
+  ghcr.io/headroomlabs-ai/headroom:latest \
   headroom proxy --host 0.0.0.0 --port 8787
 ```
 
diff --git a/wiki/learn.md b/wiki/learn.md
index eb4eb87d6..07bb9d471 100644
--- a/wiki/learn.md
+++ b/wiki/learn.md
@@ -169,11 +169,12 @@ Options:
 
 `headroom learn --verbosity` analyzes past sessions to infer the ideal output verbosity level for your project and writes a `verbosity.json` profile.
 
-**Important**: the output shaper is **off by default**. Running `--verbosity --apply` will either:
-- Hot-enable the output shaper on a running proxy (`POST /admin/runtime-env`), OR
-- Print instructions to set `HEADROOM_OUTPUT_SHAPER=1` before `headroom wrap ...`
+**Important**: the output shaper is **off by default** and requires the `beta`
+runtime rollout channel. Running `--verbosity --apply` will either:
+- Hot-enable the output shaper on an eligible running proxy (`POST /admin/runtime-env`), OR
+- Print instructions to set `HEADROOM_ROLLOUT_CHANNEL=beta` and `HEADROOM_OUTPUT_SHAPER=1` before `headroom wrap ...`
 
-To keep the shaper on across proxy restarts, add `export HEADROOM_OUTPUT_SHAPER=1` to your shell profile before starting the proxy.
+To keep the shaper on across proxy restarts, export both variables before starting the proxy.
 
 **Flag interactions**:
 - `--all` and `--project` are mutually exclusive