diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index adf834aa..5ae7217d 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -18,13 +18,34 @@ updates:
     directory: /
     schedule:
       interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
     commit-message:
       prefix: "ci"
+    # Wait 3 days after a release before bumping. Avoids immediately broken
+    # tags (e.g. floating-major tag missing for cosign-installer v4 right
+    # after publish, fixed only with the .x.y point release).
+    cooldown:
+      default-days: 3
+      semver-major-days: 7
     groups:
       actions-minor-patch:
         update-types:
           - "minor"
           - "patch"
+      # Group docker/* actions together (login/metadata/buildx/bake) so
+      # major bumps land in one PR — they're tested together anyway.
+      docker-actions:
+        patterns:
+          - "docker/*"
+        update-types:
+          - "major"
+      # Group actions/* core actions for major bumps.
+      core-actions:
+        patterns:
+          - "actions/*"
+        update-types:
+          - "major"
 
   # Python dependency updates (pip)
   - package-ecosystem: pip
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 71776cef..a2d8d383 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,15 +16,15 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Cache pip packages
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
@@ -102,18 +102,18 @@ jobs:
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.11'
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v6
         with:
-          file: ./coverage.xml
+          files: ./coverage.xml
           fail_ci_if_error: false
 
   test-extras:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -162,10 +162,10 @@ jobs:
   test-agno:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -181,10 +181,10 @@ jobs:
   docker-native-e2e:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -231,10 +231,10 @@ jobs:
   windows-native-wrapper:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -250,10 +250,10 @@ jobs:
   macos-native-wrapper:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -272,10 +272,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
 
@@ -292,7 +292,7 @@ jobs:
           twine check dist/*
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -301,17 +301,17 @@ jobs:
     if: github.event_name != 'push' || !startsWith(github.event.head_commit.message, 'Merge pull request ')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - uses: wagoid/commitlint-github-action@v5
+      - uses: wagoid/commitlint-github-action@v6
         with:
           configFile: .commitlintrc.json
 
   workflow-validation:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install actionlint
         run: |
diff --git a/.github/workflows/devcontainers.yml b/.github/workflows/devcontainers.yml
index 1f9bb4e1..dab8d426 100644
--- a/.github/workflows/devcontainers.yml
+++ b/.github/workflows/devcontainers.yml
@@ -30,15 +30,15 @@ jobs:
             config: .devcontainer/memory-stack/devcontainer.json
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Install Dev Container CLI
         run: npm install -g @devcontainers/cli@0.85.0
@@ -59,18 +59,18 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Create linked worktree
         run: git worktree add "$RUNNER_TEMP/headroom-worktree" HEAD
 
       - name: Set up Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Install Dev Container CLI
         run: npm install -g @devcontainers/cli@0.85.0
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 069f91a7..51914841 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -1,220 +1,357 @@
-name: Docker
-
-on:
-  workflow_call:
-    inputs:
-      version:
-        description: "Version to stamp into the image contents and exact image tag"
-        required: false
-        type: string
-      enable_ref_tags:
-        description: "Whether to emit branch/PR ref tags"
-        required: false
-        default: true
-        type: boolean
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Version to stamp into the image contents and exact image tag"
-        required: false
-  release:
-    types: [published]
-
-env:
-  REGISTRY: ghcr.io
-
-permissions:
-  contents: read
-  packages: write
-  id-token: write # For cosign keyless signing via Sigstore OIDC
-
-jobs:
-  docker-variant-tags:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - variant: ""
-            bake_target: runtime
-          - variant: nonroot
-            bake_target: runtime-nonroot
-          - variant: code
-            bake_target: runtime-code
-          - variant: code-nonroot
-            bake_target: runtime-code-nonroot
-          - variant: slim
-            bake_target: runtime-slim
-          - variant: slim-nonroot
-            bake_target: runtime-slim-nonroot
-          - variant: code-slim
-            bake_target: runtime-code-slim
-          - variant: code-slim-nonroot
-            bake_target: runtime-code-slim-nonroot
-
-    steps:
-      - uses: actions/checkout@v6
-
-      - 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 Python
-        if: steps.version.outputs.version != ''
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Sync versioned files for image build
-        if: steps.version.outputs.version != ''
-        run: |
-          python scripts/version-sync.py --version ${{ steps.version.outputs.version }}
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
-
-      - 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: Compute short SHA
-        id: short-sha
-        run: printf 'sha=%s\n' "${GITHUB_SHA:0:7}" >> "$GITHUB_OUTPUT"
-
-      - name: Extract metadata (variant)
-        id: meta
-        uses: docker/metadata-action@v6
-        with:
-          images: ${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}
-          tags: |
-            type=ref,event=branch,enable=${{ inputs.enable_ref_tags != 'false' && github.event_name != 'release' }},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
-            type=ref,event=pr,enable=${{ inputs.enable_ref_tags != 'false' && github.event_name != 'release' }},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
-            type=raw,value=${{ steps.version.outputs.version }},enable=${{ steps.version.outputs.version != '' }},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
-            type=raw,value=${{ steps.version.outputs.version }}-${{ steps.short-sha.outputs.sha }},enable=${{ steps.version.outputs.version != '' && matrix.variant == '' }}
-            type=raw,value=${{ steps.version.outputs.version }}-${{ matrix.variant }}-${{ steps.short-sha.outputs.sha }},enable=${{ steps.version.outputs.version != '' && matrix.variant != '' }}
-            type=semver,pattern={{version}},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
-            type=semver,pattern={{major}}.{{minor}},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
-            type=semver,pattern={{major}},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
-            type=sha,format=short,prefix=${{ matrix.variant != '' && format('{0}-', matrix.variant) || 'sha-' }}
-            type=raw,value=${{ matrix.variant }},enable=${{ matrix.variant != '' }}
-
-      - name: Build and push variant (bake)
-        id: bake
-        uses: docker/bake-action@v7
-        with:
-          files: |
-            ./docker-bake.hcl
-            cwd://${{ steps.meta.outputs.bake-file-tags }}
-            cwd://${{ steps.meta.outputs.bake-file-labels }}
-          targets: ${{ matrix.bake_target }}
-          push: true
-          set: |
-            *.cache-from=type=gha
-            *.cache-to=type=gha,mode=max
-
-      - name: Install cosign
-        uses: sigstore/cosign-installer@v3
-
-      - name: Sign images with cosign (keyless via Sigstore OIDC)
-        env:
-          # Route signatures to a sibling GHCR package so the main image's
-          # package version list stays clean. GHCR does not implement the OCI 1.1
-          # referrers API yet (community discussion #163029, June 2025), so
-          # cosign's OCI 1.1 mode falls back to writing referrer tags into the
-          # *image's* repo. Using legacy signature mode here lets COSIGN_REPOSITORY
-          # actually relocate the artifacts. Verifiers must export the same
-          # COSIGN_REPOSITORY value when running 'cosign verify'.
-          COSIGN_REPOSITORY: ${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}-signatures
-        run: |
-          # Write bake metadata to a file rather than pass it through
-          # the `env:` block. The `code-nonroot` and `runtime-code-nonroot`
-          # bake targets emit metadata blobs large enough that combined
-          # argv+env at bash spawn exceeds Linux ARG_MAX (~128 KiB on
-          # ubuntu-latest), failing with `E2BIG: Argument list too long`
-          # before the script can run. The heredoc puts the JSON in the
-          # script body (which is read from a temp file by bash, no
-          # ARG_MAX limit) and we read it back via `jq -f`-style file
-          # input. Sentinel chosen long enough that no JSON payload is
-          # plausibly going to collide with it.
-          cat > "${RUNNER_TEMP}/bake_meta.json" <<'__HEADROOM_BAKE_META_EOF__'
-          ${{ steps.bake.outputs.metadata }}
-          __HEADROOM_BAKE_META_EOF__
-
-          jq -r 'to_entries[].value."containerimage.digest" // empty' \
-              "${RUNNER_TEMP}/bake_meta.json" | while read -r digest; do
-            image="${{ env.REGISTRY }}/${{ steps.image-name.outputs.image_name }}@${digest}"
-            echo "Signing ${image} (signatures -> ${COSIGN_REPOSITORY})"
-            cosign sign --yes "${image}"
-          done
-
-  promote-latest:
-    # Re-push the :latest tag pointing at the root variant *after* every
-    # variant matrix 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-variant-tags
-    runs-on: ubuntu-latest
-    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 != ''
-        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).
-          promoted_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-          docker buildx imagetools create \
-            --annotation "index:io.headroom.promoted-at=${promoted_at}" \
-            --tag "${IMAGE}:latest" \
-            "${IMAGE}:${VERSION}"
+name: Docker
+
+# ─── Optimized release CI ──────────────────────────────────────────────────────
+# Strategy:
+#   1. Native amd64 + arm64 runners (no QEMU emulation).
+#   2. Single bake invocation per platform builds all 8 variants → builder
+#      stage shared in-memory across all targets within one buildx run.
+#   3. Cross-run caching via type=registry (persists across releases, unlike
+#      type=gha which is scoped to a single workflow run).
+#   4. Per-platform builds push by digest; merge job creates multi-arch
+#      manifest lists with all tags (no rebuild — pure manifest plumbing).
+#   5. Cosign signing limited to root + slim variants (the public-facing
+#      tags) to drop ~30s of aggregate cosign overhead.
+#
+# Security note: all dynamic values referenced inside `run:` blocks are
+# routed via `env:` to prevent shell injection through `${{ ... }}`
+# template expansion of untrusted inputs (release tags, workflow_dispatch
+# inputs, action outputs).
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: "Version to stamp into the image contents and exact image tag"
+        required: false
+        type: string
+      enable_ref_tags:
+        description: "Whether to emit branch/PR ref tags"
+        required: false
+        default: true
+        type: boolean
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to stamp into the image contents and exact image tag"
+        required: false
+  release:
+    types: [published]
+
+env:
+  REGISTRY: ghcr.io
+
+permissions:
+  contents: read
+  packages: write
+  id-token: write # cosign keyless signing via Sigstore OIDC
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      image_name: ${{ steps.image.outputs.image_name }}
+      version: ${{ steps.version.outputs.version }}
+      short_sha: ${{ steps.sha.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Normalize image name
+        id: image
+        env:
+          GH_REPO: ${{ github.repository }}
+        run: |
+          image_name="$(printf '%s' "${GH_REPO}" | 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: Compute short SHA
+        id: sha
+        env:
+          GH_SHA: ${{ github.sha }}
+        run: printf 'sha=%s\n' "${GH_SHA:0:7}" >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: setup
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            arch: amd64
+            runs_on: ubuntu-latest
+          - platform: linux/arm64
+            arch: arm64
+            runs_on: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runs_on }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Sync versioned files for image build
+        # version-sync.py uses stdlib only; runner's pre-installed python3
+        # avoids an 8s setup-python download per build job.
+        if: needs.setup.outputs.version != ''
+        env:
+          VERSION: ${{ needs.setup.outputs.version }}
+        run: |
+          python3 scripts/version-sync.py --version "${VERSION}"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          # Default max-parallelism is 4 * NumCPU. ubuntu-latest is 4 vCPU =
+          # default 16; arm runner same. Pin explicitly to keep parallel
+          # vertex execution saturated for 8-target single bake.
+          buildkitd-config-inline: |
+            [worker.oci]
+              max-parallelism = 16
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push by digest (all variants, single bake)
+        id: bake
+        uses: docker/bake-action@v7
+        with:
+          files: ./docker-bake.hcl
+          targets: |
+            runtime
+            runtime-nonroot
+            runtime-code
+            runtime-code-nonroot
+            runtime-slim
+            runtime-slim-nonroot
+            runtime-code-slim
+            runtime-code-slim-nonroot
+          push: true
+          # Bake `--set` uses singular `platform` (not `platforms` like the
+          # HCL field). All other keys (tags/output/cache-from/cache-to)
+          # match between HCL and `--set`.
+          set: |
+            *.platform=${{ matrix.platform }}
+            *.tags=${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}
+            *.output=type=image,push-by-digest=true,name-canonical=true,push=true
+            *.cache-from=type=registry,ref=${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}-buildcache:${{ matrix.arch }}
+            *.cache-to=type=registry,mode=max,ref=${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}-buildcache:${{ matrix.arch }}
+
+      - name: Export per-target digests
+        run: |
+          # Bake metadata blob can exceed argv/env (ARG_MAX) — write it via
+          # quoted heredoc into a file so no shell expansion happens, then
+          # read with jq from disk.
+          mkdir -p /tmp/digests
+          cat > "${RUNNER_TEMP}/bake_meta.json" <<'__HEADROOM_BAKE_META_EOF__'
+          ${{ steps.bake.outputs.metadata }}
+          __HEADROOM_BAKE_META_EOF__
+          jq -r 'to_entries[] | "\(.key) \(.value."containerimage.digest")"' \
+            "${RUNNER_TEMP}/bake_meta.json" | while read -r target digest; do
+              [ -z "$digest" ] && continue
+              printf '%s\n' "$digest" > "/tmp/digests/${target}"
+            done
+          ls -la /tmp/digests/
+
+      - name: Upload digests
+        uses: actions/upload-artifact@v7
+        with:
+          name: digests-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    needs: [setup, build]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - variant: ""
+            target: runtime
+          - variant: nonroot
+            target: runtime-nonroot
+          - variant: code
+            target: runtime-code
+          - variant: code-nonroot
+            target: runtime-code-nonroot
+          - variant: slim
+            target: runtime-slim
+          - variant: slim-nonroot
+            target: runtime-slim-nonroot
+          - variant: code-slim
+            target: runtime-code-slim
+          - variant: code-slim-nonroot
+            target: runtime-code-slim-nonroot
+    steps:
+      - 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: Download amd64 digests
+        uses: actions/download-artifact@v8
+        with:
+          name: digests-amd64
+          path: /tmp/digests/amd64
+
+      - name: Download arm64 digests
+        uses: actions/download-artifact@v8
+        with:
+          name: digests-arm64
+          path: /tmp/digests/arm64
+
+      - name: Compute tags for variant
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}
+          flavor: |
+            latest=false
+          tags: |
+            type=ref,event=branch,enable=${{ inputs.enable_ref_tags != 'false' && github.event_name != 'release' }},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
+            type=ref,event=pr,enable=${{ inputs.enable_ref_tags != 'false' && github.event_name != 'release' }},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
+            type=raw,value=${{ needs.setup.outputs.version }},enable=${{ needs.setup.outputs.version != '' }},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
+            type=raw,value=${{ needs.setup.outputs.version }}-${{ needs.setup.outputs.short_sha }},enable=${{ needs.setup.outputs.version != '' && matrix.variant == '' }}
+            type=raw,value=${{ needs.setup.outputs.version }}-${{ matrix.variant }}-${{ needs.setup.outputs.short_sha }},enable=${{ needs.setup.outputs.version != '' && matrix.variant != '' }}
+            type=semver,pattern={{version}},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
+            type=semver,pattern={{major}}.{{minor}},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
+            type=semver,pattern={{major}},suffix=${{ matrix.variant != '' && format('-{0}', matrix.variant) || '' }}
+            type=sha,format=short,prefix=${{ matrix.variant != '' && format('{0}-', matrix.variant) || 'sha-' }}
+            type=raw,value=${{ matrix.variant }},enable=${{ matrix.variant != '' }}
+
+      - name: Create multi-arch manifest list
+        env:
+          IMAGE: ${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}
+          TARGET: ${{ matrix.target }}
+          TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          AMD_DIGEST="$(cat "/tmp/digests/amd64/${TARGET}")"
+          ARM_DIGEST="$(cat "/tmp/digests/arm64/${TARGET}")"
+          if [ -z "$AMD_DIGEST" ] || [ -z "$ARM_DIGEST" ]; then
+            echo "::error::missing digest for target=${TARGET} amd=${AMD_DIGEST} arm=${ARM_DIGEST}"
+            exit 1
+          fi
+
+          # Build -t args from $TAGS (newline-separated). Reading via env
+          # avoids inline GitHub-expression interpolation in the script body.
+          TAG_ARGS=()
+          while IFS= read -r tag; do
+            [ -z "$tag" ] && continue
+            TAG_ARGS+=("-t" "$tag")
+          done <<< "${TAGS}"
+
+          if [ "${#TAG_ARGS[@]}" -eq 0 ]; then
+            echo "::error::no tags computed for variant target=${TARGET}"
+            exit 1
+          fi
+
+          docker buildx imagetools create "${TAG_ARGS[@]}" \
+            "${IMAGE}@${AMD_DIGEST}" \
+            "${IMAGE}@${ARM_DIGEST}"
+
+  sign:
+    # Sign only public-facing variants: root (runtime) and slim (distroless).
+    # Other 6 variants share builder/runtime layers and are
+    # cryptographically equivalent — re-signing each is overhead, not safety.
+    needs: [setup, merge]
+    if: needs.setup.outputs.version != ''
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - variant: ""
+          - variant: slim
+    steps:
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install cosign
+        # cosign-installer does not publish a floating `v4` tag; pin minor.
+        uses: sigstore/cosign-installer@v4.1.1
+
+      - name: Sign manifest with cosign
+        env:
+          # Route signatures to a sibling GHCR package so the main image's
+          # package version listing stays clean. Verifiers must export the same
+          # COSIGN_REPOSITORY when running `cosign verify`.
+          COSIGN_REPOSITORY: ${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}-signatures
+          IMAGE: ${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}
+          VERSION: ${{ needs.setup.outputs.version }}
+          VARIANT: ${{ matrix.variant }}
+        run: |
+          if [ -n "$VARIANT" ]; then
+            TAG="${VERSION}-${VARIANT}"
+          else
+            TAG="${VERSION}"
+          fi
+          # Cosign sometimes fails with transient HTTP/2 stream resets when
+          # talking to GHCR's signature repository. Retry up to 3 times
+          # with exponential backoff before giving up. --recursive signs
+          # each per-arch image referenced by the manifest list.
+          attempt=1
+          max=3
+          delay=5
+          until cosign sign --yes --recursive "${IMAGE}:${TAG}"; do
+            if [ "$attempt" -ge "$max" ]; then
+              echo "::error::cosign sign failed after $max attempts"
+              exit 1
+            fi
+            echo "::warning::cosign sign attempt $attempt failed, retrying in ${delay}s..."
+            sleep "$delay"
+            attempt=$((attempt + 1))
+            delay=$((delay * 2))
+          done
+
+  promote-latest:
+    # Re-tag :latest at root variant so GHCR's package version listing shows
+    # the canonical root image at the top with a fresh timestamp.
+    needs: [setup, merge]
+    if: needs.setup.outputs.version != ''
+    runs-on: ubuntu-latest
+    steps:
+      - 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
+        env:
+          IMAGE: ${{ env.REGISTRY }}/${{ needs.setup.outputs.image_name }}
+          VERSION: ${{ needs.setup.outputs.version }}
+        run: |
+          # Add unique annotation so manifest index gets a new digest;
+          # GHCR records a fresh package version with the current timestamp
+          # rather than reusing the existing root manifest entry.
+          promoted_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          docker buildx imagetools create \
+            --annotation "index:io.headroom.promoted-at=${promoted_at}" \
+            --tag "${IMAGE}:latest" \
+            "${IMAGE}:${VERSION}"
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 60285947..6b5150c6 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -17,12 +17,12 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
diff --git a/.github/workflows/eval.yml b/.github/workflows/eval.yml
index 554564f9..635a0594 100644
--- a/.github/workflows/eval.yml
+++ b/.github/workflows/eval.yml
@@ -16,8 +16,8 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - name: Install dependencies
@@ -73,8 +73,8 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - name: Install dependencies
@@ -86,7 +86,7 @@ jobs:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       - name: Upload results
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: eval-results-${{ github.run_number }}
           path: eval_results/
diff --git a/.github/workflows/init-e2e.yml b/.github/workflows/init-e2e.yml
index 607cbb33..30e38bdf 100644
--- a/.github/workflows/init-e2e.yml
+++ b/.github/workflows/init-e2e.yml
@@ -13,7 +13,7 @@ jobs:
     timeout-minutes: 45
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Build init e2e image
         run: docker build -f e2e/init/Dockerfile -t headroom-init-e2e .
diff --git a/.github/workflows/init-native-e2e.yml b/.github/workflows/init-native-e2e.yml
index cc9a4cdc..f90b1aff 100644
--- a/.github/workflows/init-native-e2e.yml
+++ b/.github/workflows/init-native-e2e.yml
@@ -48,7 +48,7 @@ jobs:
           - target: openclaw
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup (shim=${{ matrix.target }})
         uses: ./.github/actions/headroom-e2e-setup
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 3e0f7192..b4225ffa 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -15,10 +15,10 @@ jobs:
       contents: write # For uploading release assets
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -38,7 +38,7 @@ jobs:
             --outfile dist/headroom-sbom.cdx.json
 
       - name: Upload SBOM to release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           files: dist/headroom-sbom.cdx.json
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index da1bec0d..2fcce016 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -62,7 +62,7 @@ jobs:
       bump: ${{ steps.ver.outputs.bump }}
       previous_tag: ${{ steps.ver.outputs.previous_tag }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -77,17 +77,17 @@ jobs:
     needs: [detect-version]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
 
@@ -126,7 +126,7 @@ jobs:
         shell: bash
 
       - name: Upload changelog via action
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: changelog
           path: /tmp/changelog-backup.md
@@ -154,13 +154,13 @@ jobs:
           npm pack --pack-destination ../../release-assets
 
       - name: Upload dist artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
 
       - name: Upload release assets artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: release-assets
           path: release-assets/
@@ -174,7 +174,7 @@ jobs:
       id-token: write  # Required for OIDC trusted publishing
     steps:
       - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -194,18 +194,18 @@ jobs:
     if: github.event.inputs.dry_run != 'true' && vars.NPM_SKIP != 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
           registry-url: ${{ env.NPM_REGISTRY_URL }}
 
       - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -247,7 +247,7 @@ jobs:
       contents: read
       packages: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -258,13 +258,13 @@ jobs:
           printf 'scope=%s\n' "$scope" >> "$GITHUB_OUTPUT"
 
       - name: Set up Node.js for GitHub Package Registry
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
           registry-url: ${{ env.GITHUB_PACKAGES_REGISTRY_URL }}
 
       - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -369,18 +369,18 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Download changelog artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: changelog
           path: /tmp
 
       - name: Download release assets artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: release-assets
           path: release-assets
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index ea8c67af..697c67c6 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -40,7 +40,7 @@ jobs:
     name: test (ubuntu)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install stable toolchain
         # Pin action code to @stable (latest fixes), toolchain version
         # via input. The @1.95.0 ref shipped action code that errors on
@@ -82,8 +82,8 @@ jobs:
         # locally (the toolchain works; only prebuilt distribution skips
         # this target).
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
       - name: Build wheel
@@ -97,7 +97,7 @@ jobs:
           args: --release -m crates/headroom-py/Cargo.toml --out dist
           target: ${{ matrix.maturin-target }}
       - name: Upload wheel artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: wheels-${{ matrix.target }}
           path: dist/*.whl
@@ -106,7 +106,7 @@ jobs:
     name: audit
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
         with:
           toolchain: 1.95.0
@@ -128,11 +128,11 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
         with:
           toolchain: 1.95.0
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
       - uses: Swatinem/rust-cache@v2
diff --git a/.github/workflows/wrap-e2e.yml b/.github/workflows/wrap-e2e.yml
index dce63656..1acc1f66 100644
--- a/.github/workflows/wrap-e2e.yml
+++ b/.github/workflows/wrap-e2e.yml
@@ -13,7 +13,7 @@ jobs:
     timeout-minutes: 45
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Build wrap e2e image
         run: docker build -f e2e/wrap/Dockerfile -t headroom-wrap-e2e .
diff --git a/Dockerfile b/Dockerfile
index 757209db..edcc2b35 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -126,8 +126,8 @@ RUN apt-get update && \
     apt-get install -y --no-install-recommends curl && \
     rm -rf /var/lib/apt/lists/*
 
-COPY --from=builder ${PYTHON_SITE_PACKAGES} ${PYTHON_SITE_PACKAGES}
-COPY --from=builder /usr/local/bin/headroom /usr/local/bin/headroom
+COPY --link --from=builder ${PYTHON_SITE_PACKAGES} ${PYTHON_SITE_PACKAGES}
+COPY --link --from=builder /usr/local/bin/headroom /usr/local/bin/headroom
 
 RUN mkdir -p /home/nonroot /data && \
     if [ "$RUNTIME_USER" = "nonroot" ]; then \
@@ -159,7 +159,7 @@ FROM ${DISTROLESS_IMAGE}@${DISTROLESS_DIGEST} AS runtime-slim
 ARG RUNTIME_USER=nonroot
 ARG PYTHON_SITE_PACKAGES
 
-COPY --from=builder ${PYTHON_SITE_PACKAGES} ${PYTHON_SITE_PACKAGES}
+COPY --link --from=builder ${PYTHON_SITE_PACKAGES} ${PYTHON_SITE_PACKAGES}
 
 USER ${RUNTIME_USER}
 WORKDIR /app
diff --git a/docs/superpowers/specs/2026-05-03-pii-filter-design.md b/docs/superpowers/specs/2026-05-03-pii-filter-design.md
new file mode 100644
index 00000000..06cbc753
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-03-pii-filter-design.md
@@ -0,0 +1,673 @@
+# PII / Secret Filter for Headroom Proxy — Design
+
+**Date:** 2026-05-03
+**Status:** Draft v2 (security-review pass applied; awaiting user approval)
+**Owner:** TBD
+**Related:** `headroom/proxy/handlers/{anthropic,openai,gemini}.py`, `headroom/proxy/server.py`, `headroom/config.py`
+
+---
+
+## 1. Goal
+
+Detect and mask personally identifiable information (PII) and credentials/secrets in user-supplied request bodies **before** they are forwarded to upstream LLM providers (Anthropic, OpenAI, etc).
+
+The filter is opt-in via three independent mechanisms:
+
+1. **Environment variable** — `HEADROOM_PII_ENABLED=true` (default off).
+2. **Per-request header** — `X-Headroom-PII: on` (escalate only — see §6.1).
+3. **Dedicated mirrored route** — `POST /openai/pii/v1/chat/completions`, `POST /anthropic/pii/v1/messages`, `POST /openai/pii/v1/responses` — same request/response shape as the regular routes; filter is forced on; **forced routes fail-closed** (§8.1).
+
+Confidence threshold for ML-based detection is configurable globally and per-label.
+
+## 2. Non-goals
+
+- Reverse-substitution / round-tripping the original PII back into the upstream response.
+- Scanning assistant responses, tool results, system prompts, image/audio bytes, or tool-call argument JSON.
+- Compliance certification (HIPAA / GDPR DPA). The filter is a defence-in-depth control, not a guarantee.
+- Streaming-response inspection.
+- Built-in pseudonymization / format-preserving fake-data generation.
+- Hard wall-clock timeouts on detector execution (Python cannot kill threads). Soft budget only in v1; subprocess-based hard timeout deferred to v2.
+
+## 3. Locked design decisions
+
+| Axis | Decision |
+|---|---|
+| Detection backend | Hybrid: Microsoft **Presidio** + custom **regex** detector + **detect-secrets** |
+| Masking strategy | **Tag redact** — replace with `[<LABEL>]` (e.g., `[PERSON]`, `[EMAIL]`, `[AWS_ACCESS_KEY]`) |
+| Default behavior | **Off**; opt-in via env / header (escalate-only) / mirrored route |
+| Scan scope | **User messages only** (`role == "user"` text blocks). System / assistant / tool_result / tool_use untouched. Documented limitation: PII echoed in tool results is not caught. |
+| Failure mode | **Two-tier:** env/header opt-in → **fail-open**; forced `/pii/...` route → **fail-closed** (HTTP 503). Configurable via `failure_mode_default` and `failure_mode_forced`. |
+| Confidence | Global default `min_score=0.85`; per-label override map; per-request header overrides gated behind `HEADROOM_PII_ALLOW_HEADER_OVERRIDES=false` (default off). |
+| Integration point | **Pre-pipeline stage** invoked by handler immediately after JSON parse, **before** cache lookup, optimize gate, license gate, hooks, and `TransformPipeline`. PII redactor is **not** a `Transform` subclass. |
+| Response path | Untouched (one-way mask) |
+| Oversized text | **Chunk-scan** (256KB windows, 256-char overlap). No per-message skip. If chunk-scan itself fails on a forced route → fail-closed; on env/header path → fail-open with WARN. |
+
+## 4. Architecture
+
+```
+                ┌─────────────────────────────────┐
+client ────►    │  FastAPI route                  │
+                │   /v1/messages                  │
+                │   /v1/chat/completions          │
+                │   /v1/responses                 │
+                │   /openai/pii/v1/chat/...   ──► force_pii=True
+                │   /anthropic/pii/v1/messages──► force_pii=True
+                │   /openai/pii/v1/responses  ──► force_pii=True
+                └──────────────┬──────────────────┘
+                               │ raw bytes
+                               ▼
+                ┌─────────────────────────────────────────┐
+                │  Handler entry (anthropic/openai/...)   │
+                │   1. read body bytes                    │
+                │   2. parse JSON                         │
+                │   3. resolve_pii_decision(req,cfg)  ◄── escalate-only header
+                │   4. await PIIRedactor.run(body, mode)  │ ◄── PRE-PIPELINE
+                │      ├─ on success → continue           │
+                │      ├─ on failure + forced → 503       │
+                │      └─ on failure + opt-in → forward   │
+                │   5. cache lookup (uses redacted body)  │
+                │   6. optimize gate / license gate       │
+                │   7. TransformPipeline.apply(...)       │
+                │   8. forward to upstream                │
+                └─────────────────────────────────────────┘
+                               │
+                               ▼
+                       upstream LLM
+```
+
+**Key invariants**
+
+- PII redactor runs **before** every other gate. Cache hits, `optimize=False`, `_bypass=True`, `_license_ok=False`, and `pre_compress` hooks all see the **already-redacted** body.
+- Redactor is a no-op only if `PIIDecision.run == False` (env off, header absent, route not forced).
+- Forced routes (`/{provider}/pii/...`) propagate `failure_mode="closed"` — any unrecoverable error returns HTTP 503 to the client. Env/header opt-in propagates `failure_mode="open"` — errors log WARN and forward unmasked.
+- Only `role == "user"` text blocks are mutated.
+
+## 5. Components
+
+### 5.1 New module tree
+
+```
+headroom/pii/
+├── __init__.py
+├── redactor.py        # PIIRedactor — pre-pipeline entry; NOT a Transform
+├── decision.py        # resolve_pii_decision(request, config) -> PIIDecision
+├── walker.py          # body-shape walkers: anthropic / openai_chat / openai_responses
+├── chunker.py         # 256KB windows w/ 256-char overlap; merge spans across chunks
+├── async_runner.py    # bounded ThreadPoolExecutor + asyncio.wait_for harness
+├── detectors/
+│   ├── __init__.py
+│   ├── base.py        # Detector ABC + Span dataclass
+│   ├── presidio.py    # PresidioDetector — wraps presidio-analyzer
+│   ├── regex.py       # RegexDetector — email/phone/SSN/IBAN/card/IP/MRN/...
+│   └── secrets.py     # SecretDetector — wraps detect-secrets plugins
+├── masker.py          # tag_redact(spans, text) -> str
+└── span.py            # @dataclass Span(start, end, label, score, source)
+```
+
+Lives at `headroom/pii/` (top-level), **not** under `headroom/transforms/`, to make it clear PII is not part of the transform pipeline.
+
+### 5.2 Surgical edits to existing files
+
+| File | Change |
+|---|---|
+| `headroom/config.py` | Add `PIIConfig` dataclass; embed as `HeadroomConfig.pii: PIIConfig`. (Existing top-level config class is `HeadroomConfig`.) |
+| `headroom/proxy/server.py` | `_pii_config_from_env()` helper; register mirrored `/openai/pii/...` and `/anthropic/pii/...` routes that set `request.state.force_pii = True` and delegate to the regular handler. |
+| `headroom/proxy/handlers/anthropic.py` | At top of `handle_anthropic_messages` (after JSON parse, before cache lookup at ~line 596) call `await self._maybe_redact_pii(request, body)`. |
+| `headroom/proxy/handlers/openai.py` | Same pattern in `handle_openai_chat_completions` (before cache return at ~line 314) and in `handle_openai_responses` (after `body` is parsed at ~line 1084). |
+| `headroom/proxy/handlers/gemini.py` | Same pattern; route group registered when Gemini handler used. |
+| `pyproject.toml` | New optional dependency group `[pii]`. |
+
+The redactor is invoked from a small mixin method on each handler:
+
+```python
+async def _maybe_redact_pii(self, request: Request, body: dict) -> None:
+    decision = resolve_pii_decision(request, self.config.pii)
+    if not decision.run:
+        return
+    try:
+        await self._pii_redactor.run(body, decision)
+    except PIIBlocked as exc:        # forced + chunk-scan failed
+        raise HTTPException(503, detail=exc.reason) from exc
+    except Exception:
+        if decision.failure_mode == "closed":
+            log.exception("pii: forced route failed; refusing")
+            raise HTTPException(503, detail="pii redaction failed")
+        log.warning("pii: detector pipeline failed; forwarding unmasked", exc_info=True)
+        self._pii_total_failure_counter.inc()
+```
+
+### 5.3 Detector contract
+
+Detectors are **synchronous** by design (Presidio's `AnalyzerEngine.analyze`, regex, detect-secrets are all sync). The redactor wraps them in `asyncio.to_thread` + bounded `ThreadPoolExecutor` for the async interface.
+
+```python
+@dataclass(frozen=True)
+class Span:
+    start: int          # char offset (NFC-normalized) in source text
+    end: int            # exclusive
+    label: str          # PERSON | EMAIL | AWS_ACCESS_KEY | ...
+    score: float        # 0.0–1.0; regex/secrets fixed at 1.0
+    source: str         # "presidio" | "regex" | "secrets"
+
+class Detector(Protocol):
+    name: str
+    def detect(self, text: str, lang: str = "en") -> list[Span]: ...
+```
+
+### 5.4 Async runner (`async_runner.py`)
+
+```python
+class DetectorRunner:
+    """Bounded thread pool harness for sync detectors.
+
+    asyncio.wait_for cancels the *await*, but the underlying thread
+    keeps running until detect() returns naturally. The bounded pool
+    bounds pileup; per-detector concurrency is capped.
+    """
+    def __init__(self, max_workers: int = 4):
+        self._pool = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="pii")
+
+    async def run(self, det: Detector, text: str, lang: str, timeout_s: float) -> list[Span]:
+        loop = asyncio.get_running_loop()
+        fut = loop.run_in_executor(self._pool, det.detect, text, lang)
+        try:
+            return await asyncio.wait_for(fut, timeout=timeout_s)
+        except asyncio.TimeoutError:
+            # Future is still running in the pool. Caller proceeds without
+            # this detector's spans. The pool's max_workers prevents pileup.
+            return []
+```
+
+Documented caveat (in code + spec §10): a runaway sync detector occupies a worker until it returns; once `max_workers` is saturated, subsequent requests skip the affected detector immediately.
+
+### 5.5 Composition order inside `PIIRedactor.run(body, decision)`
+
+1. Pick body walker based on route shape (`anthropic_messages` / `openai_chat` / `openai_responses`).
+2. For each user-text segment found by walker:
+   - If `len(text.encode("utf-8")) > chunk_size`: split into 256KB chunks with 256-char overlap; each chunk processed independently.
+   - For each chunk, run detectors in parallel:
+     a. `RegexDetector.detect()` (sync, ~µs; bypasses runner).
+     b. `SecretDetector.detect()` (sync, ~µs; bypasses runner).
+     c. `PresidioDetector.detect()` via `DetectorRunner` (timeout `presidio_timeout_ms`).
+   - Drop spans below threshold (`min_score`, with per-label overrides).
+   - Resolve overlaps (longest span wins; ties: `secrets > regex > presidio`).
+   - For chunked text, translate chunk-local offsets to global, drop spans wholly inside the overlap region of the **next** chunk (deduped by exact `(start, end, label)`).
+3. `masker.tag_redact()` walks merged spans right-to-left, substituting `[<LABEL>]`.
+4. Mutate the original body in place via the walker's setter.
+
+### 5.6 Lazy loading
+
+- `PresidioDetector` constructed lazily on first request (cold start ~1.5s for spaCy `en_core_web_sm`).
+- `RegexDetector` and `SecretDetector` eager (cheap).
+- `DetectorRunner` thread pool created at app startup.
+
+## 6. Data flow
+
+### 6.1 Opt-in resolution (escalate-only header)
+
+```python
+def resolve_pii_decision(request: Request, cfg: PIIConfig) -> PIIDecision:
+    forced = bool(getattr(request.state, "force_pii", False))
+    hdr_on = _header_truthy(request.headers, cfg.header_name)  # only True/False/None
+    env_on = cfg.enabled
+
+    # ESCALATE ONLY: header `off` is ignored. Header `on` enables when env off.
+    run = forced or env_on or hdr_on
+
+    failure_mode = (
+        cfg.failure_mode_forced if forced
+        else cfg.failure_mode_default
+    )
+
+    # Per-request overrides only when ops trusts headers.
+    min_score = cfg.min_score
+    labels = cfg.enabled_labels
+    if cfg.allow_header_overrides:
+        ms_hdr = _header_float(request.headers, f"{cfg.header_name}-Min-Score")
+        if ms_hdr is not None:
+            min_score = max(0.0, min(1.0, ms_hdr))
+        lbl_hdr = _header_csv(request.headers, f"{cfg.header_name}-Labels")
+        if lbl_hdr is not None:
+            labels = set(lbl_hdr)
+
+    return PIIDecision(run=run, forced=forced, failure_mode=failure_mode,
+                       min_score=min_score, enabled_labels=labels)
+```
+
+**Precedence** (higher = stronger):
+- Forced route always wins (forces `run=True`, `failure_mode="closed"`).
+- Env-on always wins over header-off (header-off has **no effect**).
+- Header-on enables when env is off.
+
+This closes the auth-bypass: an untrusted client cannot disable filtering that ops has enabled by env.
+
+### 6.2 Anthropic body shape (`POST /v1/messages`) — `walker.anthropic_messages`
+
+```jsonc
+{
+  "model": "...",
+  "system": "...",                          // SKIPPED
+  "messages": [
+    { "role": "user",     "content": "string OR [blocks]" },   // ← scan
+    { "role": "assistant","content": "..." },                  // skip
+    { "role": "user",     "content": [
+        { "type": "text", "text": "scan THIS" },               // ← scan
+        { "type": "image", "source": {...} },                  // skip
+        { "type": "tool_result", "content": [...] }            // skip (per locked scope)
+    ]}
+  ]
+}
+```
+
+### 6.3 OpenAI Chat Completions (`POST /v1/chat/completions`) — `walker.openai_chat`
+
+```jsonc
+{
+  "model": "...",
+  "messages": [
+    { "role": "system",    "content": "..." },                 // skip
+    { "role": "user",      "content": "string OR [parts]" },   // ← scan
+    { "role": "assistant", "content": "..." },                 // skip
+    { "role": "tool",      "content": "..." }                  // skip
+  ]
+}
+```
+
+User parts array: scan `{"type": "text", "text": ...}` only; skip `image_url` / `input_audio`.
+
+### 6.4 OpenAI Responses API (`POST /v1/responses`) — `walker.openai_responses`
+
+The Responses API uses `input` and `instructions` instead of `messages`. Walker handles three sub-shapes (matches existing `responses_items_to_messages` helper at `openai.py:1099`):
+
+```jsonc
+{
+  "model": "...",
+  "instructions": "...",                    // SKIPPED (system per scope)
+  "input": "string"                         // ← scan (treated as user text)
+}
+
+// OR
+
+{
+  "input": [
+    { "role": "user",      "content": "string OR [parts]" },           // ← scan
+    { "role": "assistant", "content": "..." },                         // skip
+    { "type": "input_text", "text": "scan THIS" },                     // ← scan (Responses item form)
+    { "type": "input_image", "image_url": "..." },                     // skip
+    { "type": "function_call_output", "output": "..." }                // skip (per scope)
+  ]
+}
+```
+
+Walker rules:
+- `input` is `str` → scan as one user text segment.
+- `input` is `list` → for each item:
+  - `dict` with `role == "user"` → scan its `content` (str or parts list, same as Chat Completions).
+  - `dict` with `type == "input_text"` and `text` is `str` → scan `text`.
+  - All other items skipped.
+
+### 6.5 Walk algorithm (defensive, with type guards)
+
+```python
+def walk_chat_messages(body: dict) -> Iterator[TextRef]:
+    """Yield mutable refs to user-text segments."""
+    msgs = body.get("messages")
+    if not isinstance(msgs, list):
+        return
+    for msg in msgs:
+        if not isinstance(msg, dict) or msg.get("role") != "user":
+            continue
+        content = msg.get("content")
+        if isinstance(content, str):
+            yield TextRef(get=lambda m=msg: m["content"],
+                          set=lambda v, m=msg: m.__setitem__("content", v))
+        elif isinstance(content, list):
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") != "text":
+                    continue
+                text = block.get("text")
+                if not isinstance(text, str):
+                    continue
+                yield TextRef(get=lambda b=block: b["text"],
+                              set=lambda v, b=block: b.__setitem__("text", v))
+```
+
+`TextRef` is a tiny `(get, set)` pair so the redactor can mutate values in place after redaction. All walker callers use `.get()` + `isinstance()` — no key-error or attribute-error path.
+
+### 6.6 Per-segment redaction (with chunking)
+
+```python
+async def redact_segment(self, text: str, decision: PIIDecision) -> str:
+    text = unicodedata.normalize("NFC", text)
+    if not text or not text.strip():
+        return text
+
+    chunks = list(chunker.split(text, size=self.cfg.chunk_size_bytes,
+                                overlap=self.cfg.chunk_overlap_chars))
+    all_spans: list[Span] = []
+    for chunk in chunks:
+        spans = await self._detect_chunk(chunk.text, decision)
+        for s in spans:
+            all_spans.append(Span(s.start + chunk.offset, s.end + chunk.offset,
+                                  s.label, s.score, s.source))
+
+    all_spans = self._dedupe_overlap_region(all_spans, chunks)
+    all_spans = self._drop_below_threshold(all_spans, decision)
+    all_spans = self._resolve_overlaps(all_spans)
+    masked = self._mask_right_to_left(text, all_spans)
+    self._record_telemetry(all_spans)
+    return masked
+```
+
+**Single-detector errors are absorbed inside `_detect_chunk`** — each detector call is wrapped in try/except (timeout returns `[]` from `DetectorRunner`; raises are caught and counted via `pii_detector_errors_total`). `_detect_chunk` only re-raises (as `PIIBlocked`) when **every** enabled detector for that chunk failed (raised or returned no spans due to error, not zero-find). On `decision.failure_mode == "closed"`: `PIIBlocked` propagates → handler returns HTTP 503. On `failure_mode == "open"`: caller logs WARN, returns original text, increments `pii_total_failure_total`.
+
+### 6.7 Response path
+
+Untouched. Tag-redact is one-way; no reverse substitution. Upstream response returned to client unmodified.
+
+### 6.8 Telemetry
+
+- Counter: `headroom_pii_redactions_total{label, source, route}`
+- Counter: `headroom_pii_detector_errors_total{detector}`
+- Counter: `headroom_pii_detector_timeouts_total{detector}`
+- Counter: `headroom_pii_total_failure_total{forced}` — split forced-vs-opt-in
+- Counter: `headroom_pii_blocked_total{route}` — forced route 503s
+- Histogram: `headroom_pii_latency_ms{stage}` (regex / secrets / presidio / total)
+- Gauge: `headroom_pii_pool_active{}` — DetectorRunner busy workers
+- INFO log per request: `pii: redacted=N labels=[...] dur=Xms forced=bool` (counts only)
+
+**Hard rule:** original PII values are never written to logs, never returned to the client, never persisted.
+
+## 7. Config surface
+
+### 7.1 `PIIConfig` dataclass
+
+```python
+@dataclass
+class PIIConfig:
+    # Master env switch (env-on == default-on for all non-/pii routes)
+    enabled: bool = False
+
+    # Detectors (independently toggleable)
+    regex_enabled: bool = True
+    secrets_enabled: bool = True
+    presidio_enabled: bool = True            # auto-disabled if dep missing
+
+    # Confidence
+    min_score: float = 0.85
+    label_scores: dict[str, float] = field(default_factory=dict)
+
+    # Label allow/deny
+    enabled_labels: set[str] = field(default_factory=set)   # empty = all
+    disabled_labels: set[str] = field(default_factory=set)
+
+    # Mask format
+    mask_format: str = "[{label}]"
+
+    # Async runner
+    presidio_timeout_ms: int = 200
+    detector_pool_workers: int = 4
+
+    # Language
+    language: str = "en"
+
+    # Header opt-in
+    header_name: str = "X-Headroom-PII"
+    allow_header_overrides: bool = False     # min_score / labels via header — TRUSTED ENVS ONLY
+
+    # Failure modes
+    failure_mode_default: Literal["open", "closed"] = "open"   # env/header opt-in
+    failure_mode_forced: Literal["open", "closed"] = "closed"  # /pii/* routes
+
+    # Chunking
+    chunk_size_bytes: int = 262_144          # 256 KB per chunk
+    chunk_overlap_chars: int = 256           # boundary overlap
+
+    # Optional noisy detectors
+    high_entropy_secrets: bool = False
+```
+
+### 7.2 Environment variables
+
+| Env var | Default | Notes |
+|---|---|---|
+| `HEADROOM_PII_ENABLED` | `false` | Master switch |
+| `HEADROOM_PII_REGEX_ENABLED` | `true` | |
+| `HEADROOM_PII_SECRETS_ENABLED` | `true` | |
+| `HEADROOM_PII_PRESIDIO_ENABLED` | `true` | No-op if package missing |
+| `HEADROOM_PII_MIN_SCORE` | `0.85` | Float 0–1 |
+| `HEADROOM_PII_LABEL_SCORES` | `{}` | JSON, e.g. `{"PERSON":0.9}` |
+| `HEADROOM_PII_ENABLED_LABELS` | `""` | CSV; empty = all |
+| `HEADROOM_PII_DISABLED_LABELS` | `""` | CSV |
+| `HEADROOM_PII_MASK_FORMAT` | `[{label}]` | Python format template |
+| `HEADROOM_PII_PRESIDIO_TIMEOUT_MS` | `200` | Soft async deadline |
+| `HEADROOM_PII_DETECTOR_POOL_WORKERS` | `4` | ThreadPoolExecutor cap |
+| `HEADROOM_PII_LANGUAGE` | `en` | Presidio nlp lang |
+| `HEADROOM_PII_HEADER_NAME` | `X-Headroom-PII` | Override if proxy strips |
+| `HEADROOM_PII_ALLOW_HEADER_OVERRIDES` | `false` | Trust client `-Min-Score` / `-Labels` headers |
+| `HEADROOM_PII_FAILURE_MODE_DEFAULT` | `open` | env/header opt-in failure mode |
+| `HEADROOM_PII_FAILURE_MODE_FORCED` | `closed` | `/pii/*` route failure mode |
+| `HEADROOM_PII_CHUNK_SIZE_BYTES` | `262144` | 256 KB |
+| `HEADROOM_PII_CHUNK_OVERLAP_CHARS` | `256` | |
+| `HEADROOM_PII_HIGH_ENTROPY` | `false` | Generic high-entropy detector |
+
+### 7.3 Per-request headers
+
+| Header | Values | Effect | Trust |
+|---|---|---|---|
+| `X-Headroom-PII` | `on` / `1` / `true` | **Escalate** — enable when env off | Always honored |
+| `X-Headroom-PII` | `off` / `0` / `false` | **Ignored** — cannot disable env-on filtering | Never honored |
+| `X-Headroom-PII-Min-Score` | float `0`–`1` | Override `min_score` for this request | Only when `allow_header_overrides=true` |
+| `X-Headroom-PII-Labels` | CSV | Restrict scan to these labels | Only when `allow_header_overrides=true` |
+
+**Security note:** `allow_header_overrides` defaults to `false` because client-controlled threshold/label restrictions are an attack vector — an untrusted client could send `X-Headroom-PII-Min-Score: 1.0` and effectively disable detection. Operators must explicitly opt in for trusted clients (e.g., internal services behind authenticated edge).
+
+### 7.4 Mirrored routes (filter forced on, fail-closed)
+
+| Method | Path | Forwards to |
+|---|---|---|
+| POST | `/anthropic/pii/v1/messages` | `/v1/messages` |
+| POST | `/openai/pii/v1/chat/completions` | `/v1/chat/completions` |
+| POST | `/openai/pii/v1/responses` | `/v1/responses` (Responses API walker) |
+
+(Gemini route added when Gemini handler is in active use; same prefix pattern: `/gemini/pii/...`.)
+
+**Implementation:** mirrored routes are registered as additional FastAPI routes whose handler functions set `request.state.force_pii = True` and then delegate to the same handler function as the regular route. No internal path rewrite or HTTP redirect — the same code path runs with one extra flag set. Forced routes pin `failure_mode="closed"` regardless of `failure_mode_default`.
+
+### 7.5 Optional dependency group
+
+```toml
+# pyproject.toml
+[project.optional-dependencies]
+pii = [
+    "presidio-analyzer>=2.2.0",
+    "presidio-anonymizer>=2.2.0",
+    "spacy>=3.7.0",
+    "detect-secrets>=1.5.0",
+]
+```
+
+Install: `pip install headroom-ai[pii]`. spaCy model `en_core_web_sm` must be downloaded separately (`python -m spacy download en_core_web_sm`); install hint logged at startup if presidio is enabled but the model is missing.
+
+### 7.6 Default label sets
+
+| Source | Labels |
+|---|---|
+| Regex | `EMAIL`, `PHONE_NUMBER`, `US_SSN`, `CREDIT_CARD`, `IBAN_CODE`, `IP_ADDRESS`, `URL`, `MAC_ADDRESS`, `MEDICAL_RECORD_NUMBER` |
+| Secrets | `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, `GITHUB_TOKEN`, `SLACK_TOKEN`, `STRIPE_KEY`, `JWT`, `PRIVATE_KEY`, `HIGH_ENTROPY_STRING` (opt-in) |
+| Presidio | `PERSON`, `LOCATION`, `ORGANIZATION`, `DATE_TIME`, `NRP` |
+
+## 8. Error handling + edge cases
+
+### 8.1 Failure matrix
+
+`forced` column = request hit a `/{provider}/pii/...` route. `Response` reflects `failure_mode_default=open` and `failure_mode_forced=closed` defaults; both configurable.
+
+| Failure | Forced? | Behavior | Telemetry |
+|---|---|---|---|
+| `presidio-analyzer` not installed | — | WARN once at startup; `presidio_enabled=False` | startup log |
+| spaCy model `en_core_web_sm` missing | — | WARN once; `presidio_enabled=False` | startup log |
+| `PresidioDetector.detect()` raises | no | drop Presidio spans; keep regex+secrets; continue | `pii_detector_errors_total{detector="presidio"}` |
+| `PresidioDetector.detect()` raises | yes | as above (single detector failure does not abort if other detectors succeed) | counter |
+| `PresidioDetector.detect()` exceeds `presidio_timeout_ms` | — | `asyncio.wait_for` cancels the wait; thread keeps running until detect() returns; drop Presidio spans; continue | `pii_detector_timeouts_total` |
+| `RegexDetector` raises | — | drop regex spans; continue | counter |
+| `SecretDetector` raises | — | drop secrets spans; continue | counter |
+| **All** detectors fail on a chunk | no | log WARN; forward original chunk text + increment counter | `pii_total_failure_total{forced="false"}` |
+| **All** detectors fail on a chunk | yes | raise `PIIBlocked` → HTTP 503 | `pii_total_failure_total{forced="true"}` + `pii_blocked_total{route}` |
+| Walker raises (malformed body shape) | — | log WARN; no-op for unknown segments; downstream returns its own validation error | none |
+| `messages` / `input` field missing or wrong type | — | walker yields nothing; redactor is a no-op | none |
+| `min_score` env un-parseable | — | use default; WARN at startup | startup log |
+| ThreadPoolExecutor saturated | — | new requests skip the saturated detector immediately (its `wait_for` returns `[]` after timeout, but with all workers busy the `asyncio.wait_for` clock starts only once a worker frees) — to bound this, `detector_pool_workers` should be ≥ expected concurrent request count for ML detector | gauge `pii_pool_active` |
+
+### 8.2 Edge cases
+
+- **Overlapping spans.** Resolver picks longest; ties → `secrets > regex > presidio`. E.g., `john@acme.com` masked as `[EMAIL]`, not `[PERSON]@acme.com`.
+- **Adjacent spans, same label.** Presidio model already aggregates BIO tags; no merge step needed.
+- **Unicode / multi-byte.** Normalize to NFC at entry; offsets are Python str indices (code points); right-to-left substitution preserves earlier offsets. Chunker splits on code-point boundaries (never mid-grapheme).
+- **Empty / whitespace-only text.** Skip detector calls.
+- **Oversized message — chunk-scan, no skip.** Default 256KB chunk, 256-char overlap. Span entirely inside the overlap region of the *next* chunk is deduped. Spans straddling a chunk boundary land in both chunks; dedupe by `(start_global, end_global, label)`. Worst case: a span longer than `chunk_overlap_chars` may be split — for v1, masker still tags both halves (e.g., two adjacent `[PERSON]` runs) which is acceptable degradation. Document increasing `chunk_overlap_chars` for workloads with very long entities.
+- **Streaming requests.** Filter runs on full request body before upstream call; chat-completion/responses request bodies are non-streaming. No streaming concern.
+- **Loopback.** `proxy/loopback_guard.py` runs after filter; unaffected.
+- **Cache aligner / dedup.** Filter runs before all caching (semantic_cache lookup, cache_aligner, prefix freeze). Cache hits store and read **redacted** content; no leak via cache.
+- **Tool args containing user PII.** Per scope (user msgs only), tool_use args **not** scanned. Documented limitation.
+- **False positives mangling code.** A user asking about a literal AWS key gets it masked. Workaround: `disabled_labels=AWS_ACCESS_KEY` in env (per-request label restriction is gated behind `allow_header_overrides`).
+- **High-entropy detector.** Off by default. When enabled: `entropy >= 4.5` AND `length >= 20` AND not part of recognized URL/UUID/SHA.
+- **Health / metrics endpoints.** Filter only runs inside provider handlers; `/health`, `/metrics`, `/docs` unaffected.
+- **Mirrored route + opt-out header.** `/openai/pii/v1/...` with `X-Headroom-PII: off` → route flag wins (forced on, header `off` is always ignored). Documented behavior.
+- **Cache-hit replay attack defence.** Cache key is computed over redacted body; an attacker cannot prime cache with PII-bearing input and then read it back, because the stored key is the masked form.
+- **Pipeline bypass paths covered.** Because PII runs before `if self.config.optimize and messages and not _bypass and _license_ok:`, all of: `optimize=False`, `_bypass=True`, `_license_ok=False`, cache-mode skip, `pre_compress` hook bypass, and early 4xx returns still see redacted bodies.
+
+## 9. Testing
+
+### 9.1 Test layout
+
+```
+tests/pii/
+├── test_redactor.py
+├── test_decision.py                 # opt-in resolution; escalate-only header
+├── test_walker_anthropic.py
+├── test_walker_openai_chat.py
+├── test_walker_openai_responses.py
+├── test_chunker.py                  # boundary + overlap + dedupe
+├── test_async_runner.py             # timeout, pool saturation
+├── test_regex_detector.py
+├── test_secrets_detector.py
+├── test_presidio_detector.py        # @pytest.mark.optional_dep("presidio")
+├── test_masker.py
+├── test_span_resolver.py
+└── fixtures/
+    ├── anthropic_messages.json
+    ├── openai_chat.json
+    ├── openai_responses.json
+    └── pii_corpus.txt
+tests/proxy/
+├── test_pii_routes.py               # mirrored /{provider}/pii/* routes
+├── test_pii_header_opt_in.py        # escalate-only behavior
+├── test_pii_failure_modes.py        # forced=closed, opt-in=open
+└── test_pii_pre_pipeline_ordering.py # cache hit / optimize=False / bypass / license=False all see redacted body
+```
+
+### 9.2 Coverage matrix
+
+| Layer | What | How |
+|---|---|---|
+| Span | offsets, equality, ordering | unit |
+| Decision | escalate-only header (`off` ignored when env on); forced wins over env-off; `allow_header_overrides=false` rejects `-Min-Score` / `-Labels`; `=true` accepts and clamps | unit, table-driven |
+| Walker (Anthropic) | string content; blocks list; non-dict block; missing `text` key; non-string `text` value; non-list `messages` | unit |
+| Walker (OpenAI Chat) | string content; parts list; non-text parts skipped; non-dict parts skipped | unit |
+| Walker (Responses) | `input` as str; `input` as list with role=user; `input` as list with `type=input_text`; `instructions` skipped | unit |
+| Chunker | segment <chunk_size: one chunk; ≥chunk_size: N chunks with overlap; spans dedupe across overlap; spans crossing boundary appear in both chunks | unit, hypothesis |
+| AsyncRunner | timeout returns `[]`, thread keeps running but is reaped on completion; pool saturation falls through to `[]`; `max_workers` honored | unit |
+| RegexDetector | each label hits its pattern; no FP on near-misses; Luhn on cards; IBAN checksum; AWS prefix | unit, table-driven |
+| SecretDetector | each plugin (AWS / GH / Slack / JWT / private key); high-entropy gate; off-by-default | unit |
+| PresidioDetector | mocked analyzer returns spans; timeout via `monkeypatch`; missing-dep import-skip | unit |
+| Span resolver | overlap-longest-wins; tie-break by source priority; adjacent same-label | unit, hypothesis |
+| Masker | right-to-left substitution; `mask_format` template; unicode NFC | unit |
+| PIIRedactor | walks all 3 body shapes; only role=user; only text blocks; no-op when decision.run=False | integration |
+| Pre-pipeline ordering | cache-hit path: redacted body is what cache stores/reads; `optimize=False`: still redacted; `_bypass=True`: still redacted; `_license_ok=False`: still redacted | integration (monkey-patch each gate) |
+| Routes | `/{provider}/pii/...` forces filter on even when env off; regular routes untouched when env off; Responses route walks `input` not `messages` | route-level (httpx AsyncClient) |
+| Headers (escalate-only) | `on` enables when env off; `off` is ignored when env on; `off` is no-op when env off | route-level |
+| Header overrides gate | `allow_header_overrides=false` ignores `-Min-Score`; `=true` honors and clamps to [0,1] | route-level |
+| Failure modes | env-on, all detectors patched to raise → 200 + unmasked + counter; forced route, all detectors patched to raise → 503 + counter | route-level |
+| Padding-attack regression | request with 5 MB body containing AWS key at offset 4_500_000 → key is masked (chunker covers it); no skip | route-level |
+| Telemetry | counters increment per label/source/forced; histogram observed; `pii_blocked_total` increments on forced-route 503; **no PII values in log records** | unit (caplog) |
+| Loopback | masked body passes loopback_guard | integration |
+| Optional dep absent | install without `[pii]` → routes still register; `presidio_enabled=False`; regex+secrets work | tox env |
+| Mass-leakage golden | 50 known-PII strings; assert ≥95% redacted with default config | golden test |
+
+### 9.3 Eval / benchmark
+
+`benchmarks/pii_benchmark.py` measures p50/p95/p99 added latency on a 1000-message corpus; per-detector breakdown; comparison of regex-only vs regex+secrets vs full hybrid; chunk-scan overhead at 256KB / 1MB / 5MB segment sizes.
+
+### 9.4 CI gate
+
+- `pii` extra installed in one CI matrix cell (full coverage).
+- Other cells run regex+secrets only (no Presidio).
+- `pytest -k pii` part of default suite.
+- New job: `pytest tests/proxy/test_pii_pre_pipeline_ordering.py` — gates merging by verifying redaction precedes every pipeline-bypass path.
+
+### 9.5 Manual smoke
+
+```bash
+# Forced route, fail-closed
+curl -sX POST http://localhost:8000/openai/pii/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gpt-4","messages":[{"role":"user",
+       "content":"My SSN is 123-45-6789 and key AKIAIOSFODNN7EXAMPLE"}]}'
+# expect upstream sees: [US_SSN] and [AWS_ACCESS_KEY]
+
+# Responses API forced route
+curl -sX POST http://localhost:8000/openai/pii/v1/responses \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gpt-4.1","input":"Email me at jane@acme.com"}'
+# expect upstream sees: input="Email me at [EMAIL]"
+
+# Padding attack regression
+python - <<'PY'
+import json, requests
+pad = "x" * 5_000_000
+body = {"model":"gpt-4","messages":[{"role":"user",
+        "content": pad + " AKIAIOSFODNN7EXAMPLE"}]}
+r = requests.post("http://localhost:8000/openai/pii/v1/chat/completions",
+                  json=body)
+print(r.status_code, r.text[:200])
+PY
+# AWS key MUST be masked in upstream view
+```
+
+## 10. Open questions / follow-ups (out of scope for v1)
+
+- Tool-result scanning (would require expanding scope decision).
+- Reverse-substitution / round-trip preservation.
+- Streaming response inspection.
+- Per-tenant / per-API-key configuration overrides.
+- Custom regex pattern injection via env / config file.
+- Alternative ML backend (OpenMed, Nemotron) behind same `Detector` protocol.
+- **Hard wall-clock detector timeouts** via `multiprocessing.Process` (currently soft only; thread keeps running until detector returns).
+- Sub-second authenticated rate-limit on forced `/pii/*` routes (NER is expensive — rate-limit per API key to deter abuse).
+
+## 11. Migration / rollout
+
+- Default `enabled=False` and `failure_mode_default="open"` → no behavior change for existing users.
+- Add `[pii]` extra to release notes; document install command.
+- New env vars and headers documented in `README.md` proxy section.
+- Mirrored routes documented with curl example **and explicit fail-closed warning**.
+- Telemetry counters (including `pii_blocked_total`) documented in metrics section.
+- Operators enabling env-default redaction must size `detector_pool_workers` to expected concurrent ML-detection load (default 4 is fine for ≤4 concurrent requests; bump for higher).
+
+## 12. Security review trail (v1 → v2)
+
+This v2 spec applies fixes for the following findings raised during security review:
+
+| ID | Finding | Resolution |
+|---|---|---|
+| C1 | PII as first pipeline transform skipped on cache-hit / `optimize=False` / `_bypass` / `_license_ok=False` | Moved out of `TransformPipeline`. PII now runs in handler entry, before all gates. (§4, §5.2) |
+| C2 | Client header `off` could disable env-enabled filtering = auth bypass | Header is **escalate-only**. Header `off` is always ignored. Score/label header overrides gated behind `allow_header_overrides=false` (default). (§6.1, §7.3) |
+| C3 | Per-message size cap allowed padding attack to skip filter on >1MB messages | Cap removed. Replaced with chunk-scan (256KB windows, 256-char overlap). On forced route + chunk-scan failure → fail-closed. (§5.5, §6.6, §7.1) |
+| C4 | `/openai/pii/v1/responses` listed but walker only handled `messages` | Added `walker.openai_responses` covering `input` (str / list, including Responses API item shapes) and `instructions` (skipped per scope). (§5.1, §6.4) |
+| W5 | Sync detector + `asyncio.wait_for` doesn't actually cancel sync work | New `DetectorRunner` with bounded `ThreadPoolExecutor`. `wait_for` cancels the await; thread runs to completion. Saturation bounded by `max_workers`. Documented caveat; hard timeout deferred. (§5.4, §10) |
+| W6 | `block["text"]` had no key / type guard | Walker uses `.get()` + `isinstance()` for every level. (§6.5) |
+| W7 | Forced `/pii/*` routes still fail open on total detector failure | Forced routes default to `failure_mode_forced="closed"` → HTTP 503. Configurable. (§7.1, §8.1) |
+| I8 | Spec referenced non-existent `Transform.run(text)`, `RequestContext.flags`, `ProxyConfig` | Aligned to actual `Transform.apply(messages, tokenizer, **kwargs) -> TransformResult` and `HeadroomConfig`. PII is no longer a `Transform` subclass at all. (§3, §5.2) |