From 142449b2e2319bc5e7cbe2ba64b1868518c4c615 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 5 Aug 2026 15:15:15 -0400
Subject: [PATCH 1/3] Make package and Docker previews opt-in (#287)

* Make package previews opt-in

* Fix Dockerfile smoke build mode

* Document contributing and preview workflows

* Harden opt-in preview publishing
---
 .github/actions/setup-docker/action.yml |   5 +
 .github/workflows/dependency-review.yml |   5 +-
 .github/workflows/package-check.yml     |  66 +++++
 .github/workflows/pr-preview.yml        | 353 ++++++++++++++++--------
 .hooks/sync_version.py                  |  36 ++-
 CONTRIBUTING.md                         |  62 +++++
 Dockerfile                              |  15 +-
 Dockerfile.preview                      |  68 +++++
 8 files changed, 495 insertions(+), 115 deletions(-)
 create mode 100644 .github/workflows/package-check.yml
 create mode 100644 CONTRIBUTING.md
 create mode 100644 Dockerfile.preview

diff --git a/.github/actions/setup-docker/action.yml b/.github/actions/setup-docker/action.yml
index 846efd4..2eea2fb 100644
--- a/.github/actions/setup-docker/action.yml
+++ b/.github/actions/setup-docker/action.yml
@@ -5,6 +5,10 @@ description: >-
   preview, and stable workflows.
 
 inputs:
+  enable-qemu:
+    description: "Set up QEMU for multi-platform builds"
+    required: false
+    default: "true"
   dockerhub-username:
     description: "Docker Hub username (pass from secrets)"
     required: true
@@ -16,6 +20,7 @@ runs:
   using: "composite"
   steps:
     - uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+      if: inputs.enable-qemu == 'true'
     - uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
     - uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
       with:
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
index 39d05b5..fba0863 100644
--- a/.github/workflows/dependency-review.yml
+++ b/.github/workflows/dependency-review.yml
@@ -571,7 +571,10 @@ jobs:
           persist-credentials: false
 
       - name: Build the Dockerfile (no push)
-        run: docker build --pull -t socket-python-cli:dependabot-smoke .
+        run: >-
+          docker build --pull
+          --build-arg USE_LOCAL_INSTALL=true
+          -t socket-python-cli:dependabot-smoke .
 
   workflow-notice:
     needs: inspect
diff --git a/.github/workflows/package-check.yml b/.github/workflows/package-check.yml
new file mode 100644
index 0000000..b2e8409
--- /dev/null
+++ b/.github/workflows/package-check.yml
@@ -0,0 +1,66 @@
+name: Package Check
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: package-check-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  package-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        uses: ./.github/actions/setup-hatch
+
+      - name: Install distribution validator
+        run: python -m pip install "twine>=4.0.0"
+
+      - name: Build distributions
+        run: hatch build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Install and inspect wheel without resolving dependencies
+        run: |
+          python -m venv "$RUNNER_TEMP/package-check"
+          "$RUNNER_TEMP/package-check/bin/pip" install --no-deps dist/*.whl
+          "$RUNNER_TEMP/package-check/bin/python" - <<'PY'
+          import compileall
+          import importlib.metadata
+          import pathlib
+          import sysconfig
+
+          distribution = importlib.metadata.distribution("socketsecurity")
+          entry_points = {entry_point.name for entry_point in distribution.entry_points}
+          assert "socketcli" in entry_points
+          package = pathlib.Path(sysconfig.get_paths()["purelib"]) / "socketsecurity"
+          assert compileall.compile_dir(package, quiet=1)
+          print("wheel metadata and bytecode smoke OK", distribution.version)
+          PY
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: socketsecurity-${{ github.sha }}
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
diff --git a/.github/workflows/pr-preview.yml b/.github/workflows/pr-preview.yml
index 113538a..473a68a 100644
--- a/.github/workflows/pr-preview.yml
+++ b/.github/workflows/pr-preview.yml
@@ -1,169 +1,306 @@
-name: PR Preview
+name: Publish PR Preview
+
 on:
   pull_request:
-    types: [opened, synchronize, ready_for_review]
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to publish
+        required: true
+        type: string
+      publish_test_pypi:
+        description: Publish the Python package to TestPyPI
+        required: true
+        default: true
+        type: boolean
+      publish_docker:
+        description: Publish socketdev/cli:pr-<number> to Docker Hub
+        required: true
+        default: false
+        type: boolean
+      sdk_preview_version:
+        description: Optional exact TestPyPI socketdev prerelease for the Docker image
+        required: false
+        type: string
 
-# Cancel an in-flight preview when the PR is pushed again -- previews are slow
-# (publish + multi-step Docker build), so superseded runs shouldn't keep going.
 concurrency:
-  group: pr-preview-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
+  group: publish-pr-preview-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: false
 
 jobs:
-  preview:
-    # Skip on:
-    #  - PRs from forks (no access to publish secrets)
-    #  - Dependabot PRs: preview-publishing a dependency bump to Test PyPI /
-    #    Docker Hub is pointless and fails (no version bump, secret access).
+  context:
     if: >-
-      github.event.pull_request.head.repo.full_name == github.repository &&
-      github.event.pull_request.user.login != 'dependabot[bot]'
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.label.name == 'publish-preview' ||
+      github.event.label.name == 'publish-docker-preview') &&
+      github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     permissions:
-      id-token: write
       contents: read
-      pull-requests: write
+      pull-requests: read
+    outputs:
+      pr_number: ${{ steps.context.outputs.pr_number }}
+      head_sha: ${{ steps.context.outputs.head_sha }}
+    steps:
+      - name: Validate pull request context
+        id: context
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+          EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+          INPUT_PR_NUMBER: ${{ inputs.pr_number }}
+          WORKFLOW_REF: ${{ github.ref }}
+        with:
+          script: |
+            const rawPrNumber = context.eventName === 'workflow_dispatch'
+              ? process.env.INPUT_PR_NUMBER
+              : process.env.EVENT_PR_NUMBER;
+            if (!/^[1-9][0-9]*$/.test(rawPrNumber || '')) {
+              core.setFailed('Pull request number must contain ASCII digits only.');
+              return;
+            }
+
+            if (context.eventName === 'workflow_dispatch') {
+              const defaultRef = `refs/heads/${process.env.DEFAULT_BRANCH}`;
+              if (process.env.WORKFLOW_REF !== defaultRef) {
+                core.setFailed(`Run manual previews from ${defaultRef}.`);
+                return;
+              }
+            }
+
+            const prNumber = Number(rawPrNumber);
+            if (!Number.isSafeInteger(prNumber)) {
+              core.setFailed('Pull request number is outside the supported range.');
+              return;
+            }
+            const {data: pullRequest} = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+            });
+            if (pullRequest.state !== 'open') {
+              core.setFailed(`Pull request #${prNumber} is not open.`);
+              return;
+            }
+            if (pullRequest.head.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}`) {
+              core.setFailed('Preview publication is limited to branches in this repository.');
+              return;
+            }
+
+            core.setOutput('pr_number', String(prNumber));
+            core.setOutput('head_sha', pullRequest.head.sha);
+
+  build:
+    needs: context
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    outputs:
+      preview_version: ${{ steps.version.outputs.preview_version }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
+          ref: ${{ needs.context.outputs.head_sha }}
           fetch-depth: 0
           persist-credentials: false
+
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          python-version: '3.13'
+          python-version: "3.12"
 
       - name: Install build tooling
         uses: ./.github/actions/setup-hatch
 
-      - name: Inject full dynamic version
-        run: python .hooks/sync_version.py --dev
+      - name: Install distribution validator
+        run: python -m pip install "twine>=4.0.0"
 
-      - name: Clean previous builds
-        run: rm -rf dist/ build/ *.egg-info
+      - name: Inject deterministic preview version
+        env:
+          PREVIEW_ID: ${{ github.run_id }}
+          RUN_ATTEMPT: ${{ github.run_attempt }}
+        run: |
+          PREVIEW_ID=$((PREVIEW_ID * 100 + RUN_ATTEMPT))
+          python .hooks/sync_version.py --dev --preview-id "$PREVIEW_ID" --skip-lock
 
-      - name: Get Hatch version
+      - name: Read preview version
         id: version
-        run: |
-          VERSION=$(hatch version | cut -d+ -f1)
-          echo "VERSION=$VERSION" >> $GITHUB_ENV
+        run: echo "preview_version=$(hatch version)" >> "$GITHUB_OUTPUT"
 
-      - name: Check if version already exists on Test PyPI
-        id: version_check
-        env:
-          VERSION: ${{ env.VERSION }}
-        run: |
-          if curl -s -f https://test.pypi.org/pypi/socketsecurity/${VERSION}/json > /dev/null; then
-            echo "exists=true" >> $GITHUB_OUTPUT
-          else
-            echo "exists=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Build package
-        if: steps.version_check.outputs.exists != 'true'
+      - name: Build and validate distributions
         run: |
           hatch build
+          python -m twine check dist/*
+
+      - name: Install and inspect wheel locally
+        run: |
+          python -m venv "$RUNNER_TEMP/preview-check"
+          "$RUNNER_TEMP/preview-check/bin/pip" install --no-deps dist/*.whl
+          "$RUNNER_TEMP/preview-check/bin/python" - <<'PY'
+          import compileall
+          import importlib.metadata
+          import pathlib
+          import sysconfig
+
+          distribution = importlib.metadata.distribution("socketsecurity")
+          entry_points = {entry_point.name for entry_point in distribution.entry_points}
+          assert "socketcli" in entry_points
+          package = pathlib.Path(sysconfig.get_paths()["purelib"]) / "socketsecurity"
+          assert compileall.compile_dir(package, quiet=1)
+          print("preview wheel smoke OK", distribution.version)
+          PY
+
+      - name: Upload preview distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: socketsecurity-preview-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
 
-      - name: Publish to Test PyPI
-        if: steps.version_check.outputs.exists != 'true'
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+  publish-package:
+    needs: [context, build]
+    if: >-
+      github.event.label.name == 'publish-preview' ||
+      (github.event_name == 'workflow_dispatch' && inputs.publish_test_pypi)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+    steps:
+      - name: Download preview distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: socketsecurity-preview-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
         with:
           repository-url: https://test.pypi.org/legacy/
           verbose: true
 
-      - name: Comment on PR
-        if: steps.version_check.outputs.exists != 'true'
+      - name: Comment on pull request
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
-          VERSION: ${{ env.VERSION }}
+          PREVIEW_VERSION: ${{ needs.build.outputs.preview_version }}
+          PR_NUMBER: ${{ needs.context.outputs.pr_number }}
         with:
           script: |
-            const version = process.env.VERSION;
-            const prNumber = context.payload.pull_request.number;
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-            // Find existing bot comments
-            const comments = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: prNumber,
-            });
-
-            const botComment = comments.data.find(comment =>
-              comment.user.type === 'Bot' &&
-              comment.body.includes('🚀 Preview package published!')
-            );
-
-            const comment = `
-            🚀 Preview package published!
+            const marker = '<!-- socketsecurity-pr-preview -->';
+            const prNumber = Number(process.env.PR_NUMBER);
+            const version = process.env.PREVIEW_VERSION;
+            const body = `${marker}
+            🚀 CLI preview published: \`socketsecurity==${version}\`
 
-            Install with:
             \`\`\`bash
             pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple socketsecurity==${version}
             \`\`\`
 
-            Docker image: \`socketdev/cli:pr-${prNumber}\`
-            `;
-
-            if (botComment) {
-              // Update existing comment
+            TestPyPI's package index can take several minutes to expose a newly uploaded version.`;
+            const {data: comments} = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+            const existing = comments.find(comment =>
+              comment.user.type === 'Bot' && comment.body.includes(marker)
+            );
+            if (existing) {
               await github.rest.issues.updateComment({
-                owner: owner,
-                repo: repo,
-                comment_id: botComment.id,
-                body: comment
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
               });
             } else {
-              // Create new comment
               await github.rest.issues.createComment({
-                owner: owner,
-                repo: repo,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
                 issue_number: prNumber,
-                body: comment
+                body,
               });
             }
 
-      - name: Verify package is available
-        if: steps.version_check.outputs.exists != 'true'
-        id: verify_package
-        env:
-          VERSION: ${{ env.VERSION }}
-        run: |
-          for i in {1..30}; do
-            if pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple socketsecurity==${VERSION}; then
-              echo "Package ${VERSION} is now available and installable on Test PyPI"
-              pip uninstall -y socketsecurity
-              echo "success=true" >> $GITHUB_OUTPUT
-              exit 0
-            fi
-            echo "Attempt $i: Package not yet installable, waiting 20s... (${i}/30)"
-            sleep 20
-          done
-          echo "success=false" >> $GITHUB_OUTPUT
-          exit 1
+  publish-docker:
+    needs: [context, build]
+    if: >-
+      github.event.label.name == 'publish-docker-preview' ||
+      (github.event_name == 'workflow_dispatch' && inputs.publish_docker)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Keep the Dockerfile and credential-handling action on trusted code.
+          # The pull request enters this job only through the built wheel.
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Download preview distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: socketsecurity-preview-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist
 
       - name: Set up Docker publishing
-        if: steps.verify_package.outputs.success == 'true'
         uses: ./.github/actions/setup-docker
         with:
+          enable-qemu: "false"
           dockerhub-username: ${{ secrets.DOCKERHUB_USERNAME }}
           dockerhub-token: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build & Push Docker Preview
-        if: steps.verify_package.outputs.success == 'true'
+      - name: Build and push Docker preview
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
-        env:
-          VERSION: ${{ env.VERSION }}
         with:
+          file: Dockerfile.preview
           push: true
-          # Preview images are for quick testing -- build amd64 only. arm64 via
-          # QEMU emulation is the slowest part of the job; release builds keep
-          # multi-arch. GHA layer cache speeds up repeated preview builds.
+          pull: true
           platforms: linux/amd64
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          tags: |
-            socketdev/cli:pr-${{ github.event.pull_request.number }}
+          tags: socketdev/cli:pr-${{ needs.context.outputs.pr_number }}
           build-args: |
-            CLI_VERSION=${{ env.VERSION }}
-            PIP_INDEX_URL=https://test.pypi.org/simple
-            PIP_EXTRA_INDEX_URL=https://pypi.org/simple
+            SDK_PREVIEW_VERSION=${{ inputs.sdk_preview_version }}
+
+      - name: Comment on pull request
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PR_NUMBER: ${{ needs.context.outputs.pr_number }}
+        with:
+          script: |
+            const marker = '<!-- socketsecurity-docker-preview -->';
+            const prNumber = Number(process.env.PR_NUMBER);
+            const body = `${marker}
+            🐳 Docker preview published: \`socketdev/cli:pr-${prNumber}\`
+
+            This mutable tag is only created when a Docker preview is explicitly requested.`;
+            const {data: comments} = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+            const existing = comments.find(comment =>
+              comment.user.type === 'Bot' && comment.body.includes(marker)
+            );
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body,
+              });
+            }
diff --git a/.hooks/sync_version.py b/.hooks/sync_version.py
index 57b29d3..51835c3 100644
--- a/.hooks/sync_version.py
+++ b/.hooks/sync_version.py
@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
-import subprocess
+import json
 import pathlib
 import re
+import subprocess
 import sys
 import urllib.request
-import json
 
 INIT_FILE = pathlib.Path("socketsecurity/__init__.py")
 PYPROJECT_FILE = pathlib.Path("pyproject.toml")
@@ -125,13 +125,45 @@ def run_uv_lock() -> bool:
     after = UV_LOCK_FILE.read_bytes() if UV_LOCK_FILE.exists() else b""
     return before != after
 
+
+def read_preview_id():
+    if "--preview-id" not in sys.argv:
+        return None
+
+    option_index = sys.argv.index("--preview-id")
+    try:
+        preview_id = sys.argv[option_index + 1]
+    except IndexError:
+        print("❌ `--preview-id` requires a numeric value.")
+        sys.exit(1)
+
+    if not preview_id.isascii() or not preview_id.isdigit():
+        print("❌ `--preview-id` must contain ASCII digits only.")
+        sys.exit(1)
+    return preview_id
+
+
 def main():
     dev_mode = "--dev" in sys.argv
+    skip_lock = "--skip-lock" in sys.argv
+    preview_id = read_preview_id()
     current_version = read_version_from_init(INIT_FILE)
     previous_version = read_version_from_git("socketsecurity/__init__.py")
 
     print(f"Current: {current_version}, Previous: {previous_version}")
 
+    if preview_id is not None:
+        if not dev_mode:
+            print("❌ `--preview-id` can only be used with `--dev`.")
+            sys.exit(1)
+        base_version = current_version.split(".dev")[0]
+        new_version = f"{base_version}.dev{preview_id}"
+        inject_version(new_version)
+        if not skip_lock:
+            run_uv_lock()
+        print(f"✅ Prepared deterministic preview version {new_version}.")
+        sys.exit(0)
+
     if current_version == previous_version:
         if dev_mode:
             base_version = current_version.split(".dev")[0] if ".dev" in current_version else current_version
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..ed9ee2b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,62 @@
+# Contributing
+
+## Development setup
+
+Use Python 3.11 or newer and install
+[`uv`](https://docs.astral.sh/uv/getting-started/installation/). From the
+repository root, create the environment and install all development
+dependencies:
+
+```bash
+uv sync --all-extras
+```
+
+Before opening a pull request, run:
+
+```bash
+make test
+uv run hatch build
+uv run python -m twine check dist/*
+```
+
+To develop against a local SDK checkout, set `SOCKET_SDK_PATH` if it is not at
+`../socketdev`, then run `make first-time-local-setup`.
+
+## Pull request validation
+
+The `Package Check` workflow runs automatically for pull requests. It builds
+and validates the distributions, smoke-tests the wheel, and uploads the
+distributions as workflow artifacts. It does not publish a package or Docker
+image.
+
+## Publishing pull request previews
+
+Preview publication is intentionally opt-in. Only request previews for code
+that is trusted to run with the repository's publishing permissions.
+
+For a pull request from this repository, apply the label for the artifact that
+needs testing:
+
+- `publish-preview` publishes a uniquely versioned `socketsecurity` prerelease
+  to TestPyPI and adds or updates a pull request comment with the exact version
+  and installation command.
+- `publish-docker-preview` publishes the mutable
+  `socketdev/cli:pr-<pull-request-number>` image to Docker Hub and adds or
+  updates a pull request comment with the image tag.
+
+Both label-triggered and manually dispatched previews are limited to open pull
+requests whose branches belong to this repository. Each label is handled as a
+separate event, so applying both labels starts two workflow runs. Use manual
+dispatch instead when both artifacts should be published in a single run.
+
+The workflow reacts when a label is added; pushing another commit while the
+label remains on the pull request does not publish a new preview. To publish the
+new pull request head or retry a failed publication, remove the relevant label
+and apply it again.
+
+Maintainers can also open **Actions > Publish PR Preview > Run workflow**, run
+it from the repository's default branch, enter the pull request number, and
+choose whether to publish to TestPyPI, Docker Hub, or both. When testing the CLI
+against an SDK preview, enter the exact TestPyPI `socketdev` prerelease in
+`sdk_preview_version`; publish the SDK preview first and allow time for
+TestPyPI to expose it before starting the CLI Docker preview.
diff --git a/Dockerfile b/Dockerfile
index 7511078..52959a3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -115,14 +115,22 @@ RUN curl -L https://raw.githubusercontent.com/pyenv/pyenv-installer/master/bin/p
 RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
         echo "Using local development install"; \
     else \
+        cli_installed=false; \
         for i in $(seq 1 10); do \
             echo "Attempt $i/10: Installing socketsecurity==$CLI_VERSION"; \
             if pip install --index-url ${PIP_INDEX_URL} --extra-index-url ${PIP_EXTRA_INDEX_URL} socketsecurity==$CLI_VERSION; then \
+                cli_installed=true; \
                 break; \
             fi; \
-            echo "Install failed, waiting 30s before retry..."; \
-            sleep 30; \
-        done && \
+            if [ "$i" -lt 10 ]; then \
+                echo "Install failed, waiting 30s before retry..."; \
+                sleep 30; \
+            fi; \
+        done; \
+        if [ "$cli_installed" != "true" ]; then \
+            echo "Failed to install socketsecurity==$CLI_VERSION after 10 attempts"; \
+            exit 1; \
+        fi; \
         if [ ! -z "$SDK_VERSION" ]; then \
             pip install --index-url ${PIP_INDEX_URL} --extra-index-url ${PIP_EXTRA_INDEX_URL} socketdev==${SDK_VERSION}; \
         fi; \
@@ -133,7 +141,6 @@ COPY . /app
 WORKDIR /app
 RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
         pip install --upgrade -e .; \
-        pip install --upgrade socketdev; \
     fi
 
 # Create workspace directory with proper permissions
diff --git a/Dockerfile.preview b/Dockerfile.preview
new file mode 100644
index 0000000..62cb3ce
--- /dev/null
+++ b/Dockerfile.preview
@@ -0,0 +1,68 @@
+# syntax=docker/dockerfile:1
+
+FROM socketdev/cli:latest
+
+ARG SDK_PREVIEW_VERSION=""
+ARG PYPI_INDEX_URL=https://pypi.org/simple/
+ARG TEST_PYPI_INDEX_URL=https://test.pypi.org/simple/
+
+COPY dist/socketsecurity-*.whl /tmp/socket-preview/
+
+RUN <<'SH'
+set -eux
+
+wheel=$(find /tmp/socket-preview -maxdepth 1 -name 'socketsecurity-*.whl' -print -quit)
+
+# Resolve every wheel dependency from production PyPI. When an exact SDK
+# preview is requested, leave socketdev out so the prerelease can intentionally
+# override a final-version floor such as socketdev>=3.4.0.
+python - "$wheel" > /tmp/socket-preview/requirements.txt <<'PY'
+import email
+import os
+import sys
+import zipfile
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+
+wheel_path = sys.argv[1]
+with zipfile.ZipFile(wheel_path) as archive:
+    metadata_path = next(
+        name for name in archive.namelist() if name.endswith(".dist-info/METADATA")
+    )
+    metadata = email.message_from_bytes(archive.read(metadata_path))
+
+sdk_preview = os.environ.get("SDK_PREVIEW_VERSION")
+for value in metadata.get_all("Requires-Dist", []):
+    if sdk_preview and canonicalize_name(Requirement(value).name) == "socketdev":
+        continue
+    print(value)
+PY
+
+python -m pip install \
+    --no-cache-dir \
+    --index-url "$PYPI_INDEX_URL" \
+    --requirement /tmp/socket-preview/requirements.txt
+
+if [ -n "$SDK_PREVIEW_VERSION" ]; then
+    mkdir /tmp/socket-preview/sdk
+    python -m pip download \
+        --no-cache-dir \
+        --no-deps \
+        --dest /tmp/socket-preview/sdk \
+        --index-url "$TEST_PYPI_INDEX_URL" \
+        "socketdev==$SDK_PREVIEW_VERSION"
+    python -m pip install \
+        --no-cache-dir \
+        --index-url "$PYPI_INDEX_URL" \
+        /tmp/socket-preview/sdk/socketdev-*.whl
+fi
+
+python -m pip install \
+    --no-cache-dir \
+    --no-deps \
+    --force-reinstall \
+    "$wheel"
+socketcli --help >/dev/null
+rm -rf /tmp/socket-preview
+SH

From 0b577a91a92d3a65ea54cd2c63949d45d557b966 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 5 Aug 2026 23:50:24 -0400
Subject: [PATCH 2/3] Harden PyPI install verification against stale cache
 (#290)

* Harden release verify step against PyPI index propagation delays

The verify loop assumed a new release appears in PyPI's simple index
within its 10-minute budget. Both socketsecurity 2.5.9 and socketdev
3.4.2 (2026-08-05) took longer than that: the upload succeeded and the
JSON API showed the release immediately, but the CDN-cached simple
index kept serving a stale version list past the loop's last attempt,
failing the release and skipping the Docker publish.

Extend the retry window to 30 minutes, add --no-cache-dir so each
attempt refetches the index rather than revalidating pip's locally
cached stale copy, and log when the JSON API already has the version
so index staleness is distinguishable from a failed publish.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Align release verify step with socket-sdk-python hardening

Use python -m pip with an explicit production Simple-index URL, quote
workflow outputs, and skip the sleep after the final attempt, matching
the socket-sdk-python release workflow so the verify step is identical
in both repos.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Trim release-specific details from verify step comment

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

---------

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 342060b..5be9e26 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -79,17 +79,31 @@ jobs:
         env:
           VERSION: ${{ env.VERSION }}
         run: |
-          for i in {1..30}; do
-            if pip install socketsecurity==${VERSION}; then
+          # The first lookup can race PyPI's Simple-index propagation, and a delayed
+          # CDN purge can leave the index stale well after a successful upload.
+          # pip caches HTTP responses by default, so without --no-cache-dir every
+          # retry can reuse that initial stale response instead of checking whether
+          # the release has appeared. Budget: 30 minutes.
+          MAX_ATTEMPTS=60
+          for i in $(seq 1 "$MAX_ATTEMPTS"); do
+            if python -m pip install \
+              --no-cache-dir \
+              --index-url https://pypi.org/simple/ \
+              "socketsecurity==${VERSION}"; then
               echo "Package ${VERSION} is now available and installable on PyPI"
-              pip uninstall -y socketsecurity
-              echo "success=true" >> $GITHUB_OUTPUT
+              python -m pip uninstall -y socketsecurity
+              echo "success=true" >> "$GITHUB_OUTPUT"
               exit 0
             fi
-            echo "Attempt $i: Package not yet installable, waiting 20s... (${i}/30)"
-            sleep 20
+            if curl -s -f "https://pypi.org/pypi/socketsecurity/${VERSION}/json" > /dev/null; then
+              echo "Release ${VERSION} exists on PyPI (JSON API) but is not in the Simple index yet - CDN propagation delay"
+            fi
+            if [ "$i" -lt "$MAX_ATTEMPTS" ]; then
+              echo "Attempt $i: Package not yet installable, waiting 30s... (${i}/${MAX_ATTEMPTS})"
+              sleep 30
+            fi
           done
-          echo "success=false" >> $GITHUB_OUTPUT
+          echo "success=false" >> "$GITHUB_OUTPUT"
           exit 1
 
       - name: Build & Push Docker

From 72bf0c21ec206e6a040da2d3fac51ea8d9066229 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Thu, 6 Aug 2026 00:19:15 -0400
Subject: [PATCH 3/3] Pin all Python dependencies (#289)

* Pin all Python dependencies

Pin every runtime dependency in pyproject.toml to an exact version,
replace the bs4 shim with a direct beautifulsoup4 dependency, pin the
socketdev SDK to 3.4.2, and install Docker image dependencies from the
committed uv.lock with pip hash verification so image builds no longer
resolve loose versions from PyPI at build time. Also pins the hatchling
build backend and the uv binary used in the Dockerfile.

Refs CE-359.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Keep locked dep install on prod PyPI; run pip check before SDK override

Pass explicit production index flags on the hash-locked dependency
install so the PIP_INDEX_URL/PIP_EXTRA_INDEX_URL build args (pointed at
TestPyPI by the preview build scripts) don't leak in via pip's env
vars, and move pip check ahead of the SDK_VERSION override so a preview
SDK that deviates from the exact socketdev pin doesn't abort the build.

Addresses PR#289 review findings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Fail the Docker build when pip check fails

Docker's shell-form RUN only propagates the last command's exit status,
so once pip check moved ahead of the SDK_VERSION block its failure was
silently discarded whenever SDK_VERSION was empty or the override
install succeeded. Gate it explicitly with || exit 1.

Addresses PR#289 review finding.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Drop ticket reference from changelog entry

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Bump version to 2.6.0

Switching to fully pinned dependencies warrants a minor bump rather
than a patch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* Pin socketdev to 3.5.0

Ingest the SDK release that bounds its own runtime dependency ranges,
so the pinned closure is hygienic end to end.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

* ci(e2e): retry reachability on empty results, upload diagnostics on failure

The e2e-reachability job intermittently fails with 'no components with
alerts in .socket.facts.json': the tier-1 reachability backend can
return empty results while the CLI reports success (ENG-5093), and the
same flake has hit unrelated PRs.

- Add a retry-probe hook to the e2e matrix: entries that define it get
  up to 3 scan attempts, retrying only when the probe says the output
  looks incomplete. Persistent failures still fail via the validate
  step. Each retry emits a warning annotation and a step-summary line
  so flake frequency stays visible.
- Add tests/e2e/reach-facts-probe.sh: exits 0 when the facts file has
  alerted components, non-zero (retry) when empty or missing.
- Upload /tmp/e2e-output.log, SARIF/GitLab outputs, and facts files as
  artifacts when any e2e job fails, so flakes are diagnosable without
  a re-run.

Also bump version to 2.6.2 (2.6.0 and 2.6.1 are being released ahead
of this PR).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(e2e): classify known empty reachability backend result

* Drop ticket references from e2e hardening and note it in the changelog

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

---------

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/e2e-test.yml     | 49 +++++++++++++++++++++++++++++-
 CHANGELOG.md                       | 24 +++++++++++++++
 Dockerfile                         | 19 ++++++++++--
 pyproject.toml                     | 26 ++++++++--------
 socketsecurity/__init__.py         |  2 +-
 tests/e2e/reach-facts-probe.sh     | 19 ++++++++++++
 tests/e2e/validate-reachability.sh | 19 ++++++++++++
 uv.lock                            | 44 ++++++++++-----------------
 8 files changed, 156 insertions(+), 46 deletions(-)
 create mode 100755 tests/e2e/reach-facts-probe.sh

diff --git a/.github/workflows/e2e-test.yml b/.github/workflows/e2e-test.yml
index 17bdc15..a1d2f29 100644
--- a/.github/workflows/e2e-test.yml
+++ b/.github/workflows/e2e-test.yml
@@ -46,6 +46,11 @@ jobs:
               --enable-debug
             validate: tests/e2e/validate-reachability.sh
             setup-node: "true"
+            # The tier-1 reachability backend intermittently returns empty
+            # results while the CLI reports success. The probe exits 0 when
+            # the facts file has alerted components; anything else is
+            # retried before validation fails the job.
+            retry-probe: bash tests/e2e/reach-facts-probe.sh tests/e2e/fixtures/simple-npm
 
           - name: gitlab
             args: >-
@@ -94,17 +99,59 @@ jobs:
         run: pip install uv
 
       - name: Run Socket CLI
+        id: run-cli
         env:
           SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_CLI_API_TOKEN }}
+          RETRY_PROBE: ${{ matrix.retry-probe }}
         run: |
           set -o pipefail
-          socketcli ${{ matrix.args }} 2>&1 | tee /tmp/e2e-output.log
+          # Entries with retry-probe get up to 3 attempts: the probe exits 0
+          # when the scan output looks complete, and a run that fails it is
+          # re-run on the assumption of a transient backend failure. A
+          # persistent incomplete result still reaches validation. Validation
+          # only treats the explicit zero-project backend signature as
+          # inconclusive; any other empty result remains a failure. Retries are
+          # surfaced as warning annotations so flake frequency stays visible.
+          max_attempts=3
+          attempt=1
+          while :; do
+            socketcli ${{ matrix.args }} 2>&1 | tee /tmp/e2e-output.log
+            [ -z "$RETRY_PROBE" ] && break
+            if bash -c "$RETRY_PROBE"; then
+              break
+            fi
+            if [ "$attempt" -ge "$max_attempts" ]; then
+              echo "::warning title=e2e-${{ matrix.name }} incomplete results::output still fails the completeness probe after ${max_attempts} attempts; letting validation classify the result"
+              echo "diagnostics=true" >> "$GITHUB_OUTPUT"
+              break
+            fi
+            echo "::warning title=e2e-${{ matrix.name }} transient retry::attempt ${attempt} failed the completeness probe (suspected backend transient); retrying"
+            echo "e2e-${{ matrix.name }}: retry after attempt ${attempt} — completeness probe failed (suspected transient)" >> "$GITHUB_STEP_SUMMARY"
+            attempt=$((attempt+1))
+            sleep 30
+          done
 
       - name: Validate results
         env:
           SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_CLI_API_TOKEN }}
         run: bash ${{ matrix.validate }}
 
+      - name: Upload diagnostics on failure
+        if: failure() || steps.run-cli.outputs.diagnostics == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-${{ matrix.name }}-diagnostics-attempt${{ github.run_attempt }}
+          path: |
+            /tmp/e2e-output.log
+            /tmp/*.sarif
+            tests/e2e/fixtures/simple-npm/.socket.facts.json
+            tests/e2e/fixtures/simple-pypi/.socket.facts.json
+            gl-*.json
+            license_output.json
+          if-no-files-found: ignore
+          include-hidden-files: true
+          retention-days: 14
+
   # Branch protection requires the e2e-* checks, but the `e2e` job above is
   # skipped on PRs that can't access repository secrets -- fork PRs and
   # Dependabot PRs. A job skipped via a job-level `if` never expands its
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b7deb2..202c6ed 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,29 @@
 # Changelog
 
+## 2.6.0
+
+### Changed: pin all Python dependencies
+
+- Pinned every runtime dependency in `pyproject.toml` to an exact version;
+  several were previously unpinned or open ranges.
+- Replaced the `bs4` shim package with a direct, pinned `beautifulsoup4`
+  dependency (the shim provided no version control over the actual library).
+- Pinned the bundled `socketdev` SDK to `3.5.0` (previously `>=3.3.0,<4.0.0`).
+- Docker images now install Python dependencies from the committed `uv.lock`
+  with pip hash verification (`--require-hashes`), so image builds no longer
+  resolve dependency versions from PyPI at build time. `pip check` validates
+  the environment after install.
+- Pinned the `hatchling` build backend and the `uv` binary used in the
+  Dockerfile.
+
+### Changed: e2e reachability jobs retry transient empty results
+
+- Reachability e2e runs that report success with no alerted components in the
+  facts file are retried up to three times as a suspected transient backend
+  failure. After retries, only the known zero-project backend signature is
+  classified as inconclusive — any other empty result still fails — and e2e
+  jobs upload their logs and reports as diagnostics on failure.
+
 ## 2.5.9
 
 ### Changed: bump pinned @coana-tech/cli to 15.10.3
diff --git a/Dockerfile b/Dockerfile
index 52959a3..06e8b0a 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -86,7 +86,7 @@ ENV PATH="/usr/local/go/bin:/usr/lib/go/bin:/root/.cargo/bin:${PATH}"
 ENV GOPATH="/go"
 
 # Install uv
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY --from=ghcr.io/astral-sh/uv:0.10.4 /uv /usr/local/bin/uv
 
 # Install pyenv
 # pyenv lets us build/install arbitrary Python versions on demand. We install
@@ -111,6 +111,18 @@ RUN curl -L https://raw.githubusercontent.com/pyenv/pyenv-installer/master/bin/p
     ln -s ~/.pyenv/bin/pyenv /bin/pyenv && \
     pyenv --version
 
+# Install Python dependencies from the lockfile with hash verification so the
+# image never resolves loose versions from PyPI at build time.
+COPY pyproject.toml uv.lock /tmp/socket-cli-lock/
+# Index flags are passed explicitly (always production PyPI) so the
+# PIP_INDEX_URL/PIP_EXTRA_INDEX_URL ARGs used to point CLI/SDK preview installs
+# at TestPyPI don't leak into the locked dependency install via pip's env vars.
+RUN uv export --directory /tmp/socket-cli-lock --frozen --no-dev --no-emit-project \
+        --format requirements-txt -o /tmp/socket-cli-lock/requirements.txt && \
+    pip install --require-hashes --no-deps \
+        --index-url https://pypi.org/simple --extra-index-url https://pypi.org/simple \
+        -r /tmp/socket-cli-lock/requirements.txt
+
 # Install CLI based on build mode
 RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
         echo "Using local development install"; \
@@ -118,7 +130,7 @@ RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
         cli_installed=false; \
         for i in $(seq 1 10); do \
             echo "Attempt $i/10: Installing socketsecurity==$CLI_VERSION"; \
-            if pip install --index-url ${PIP_INDEX_URL} --extra-index-url ${PIP_EXTRA_INDEX_URL} socketsecurity==$CLI_VERSION; then \
+            if pip install --no-deps --index-url ${PIP_INDEX_URL} --extra-index-url ${PIP_EXTRA_INDEX_URL} socketsecurity==$CLI_VERSION; then \
                 cli_installed=true; \
                 break; \
             fi; \
@@ -131,6 +143,7 @@ RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
             echo "Failed to install socketsecurity==$CLI_VERSION after 10 attempts"; \
             exit 1; \
         fi; \
+        pip check || exit 1; \
         if [ ! -z "$SDK_VERSION" ]; then \
             pip install --index-url ${PIP_INDEX_URL} --extra-index-url ${PIP_EXTRA_INDEX_URL} socketdev==${SDK_VERSION}; \
         fi; \
@@ -140,7 +153,7 @@ RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
 COPY . /app
 WORKDIR /app
 RUN if [ "$USE_LOCAL_INSTALL" = "true" ]; then \
-        pip install --upgrade -e .; \
+        pip install --no-deps -e . && pip check; \
     fi
 
 # Create workspace directory with proper permissions
diff --git a/pyproject.toml b/pyproject.toml
index 25fbd17..1b49c2c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,26 +1,26 @@
 [build-system]
 requires = [
-  "hatchling"
+  "hatchling==1.31.0"
 ]
 build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.5.9"
+version = "2.6.0"
 requires-python = ">= 3.11"
 license = {"file" = "LICENSE"}
 dependencies = [
-    'requests',
-    'mdutils',
-    'prettytable',
-    'GitPython',
-    'packaging',
-    'python-dotenv',
-    "socketdev>=3.3.0,<4.0.0",
-    "bs4>=0.0.2",
-    "markdown>=3.10",
-    "brotli>=1.0.9; platform_python_implementation == 'CPython'",
-    "brotlicffi>=1.0.9; platform_python_implementation != 'CPython'",
+    "requests==2.34.2",
+    "mdutils==1.8.1",
+    "prettytable==3.18.0",
+    "GitPython==3.1.57",
+    "packaging==26.2",
+    "python-dotenv==1.2.2",
+    "socketdev==3.5.0",
+    "beautifulsoup4==4.14.3",
+    "markdown==3.10.2",
+    "brotli==1.2.0; platform_python_implementation == 'CPython'",
+    "brotlicffi==1.2.0.1; platform_python_implementation != 'CPython'",
 ]
 readme = "README.md"
 description = "Socket Security CLI for CI/CD"
diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py
index 0189af7..2a2ecb9 100644
--- a/socketsecurity/__init__.py
+++ b/socketsecurity/__init__.py
@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.5.9'
+__version__ = '2.6.0'
 USER_AGENT = f'SocketPythonCLI/{__version__}'
diff --git a/tests/e2e/reach-facts-probe.sh b/tests/e2e/reach-facts-probe.sh
new file mode 100755
index 0000000..c1db4dd
--- /dev/null
+++ b/tests/e2e/reach-facts-probe.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Exits 0 when the reachability facts file contains components with alerts.
+#
+# Used by the e2e workflow's retry-probe hook: a --reach run against the
+# known-vulnerable fixture that reports success but yields no alerted
+# components is the signature of a transient tier-1 backend failure,
+# so the run is worth repeating before validation fails the job.
+set -euo pipefail
+
+TARGET="${1:?usage: reach-facts-probe.sh <target-path>}"
+
+uv run python - "$TARGET" <<'PY'
+import sys
+
+from socketsecurity.core.alert_selection import load_components_with_alerts
+
+components = load_components_with_alerts(sys.argv[1], ".socket.facts.json")
+sys.exit(0 if components else 1)
+PY
diff --git a/tests/e2e/validate-reachability.sh b/tests/e2e/validate-reachability.sh
index e32f004..0732616 100755
--- a/tests/e2e/validate-reachability.sh
+++ b/tests/e2e/validate-reachability.sh
@@ -34,6 +34,25 @@ if [ ! -f "$FACTS_PATH" ]; then
 fi
 echo "PASS: Reachability facts file present at $FACTS_PATH"
 
+# The tier-1 backend intermittently returns the known fixture as one orphaned
+# component with zero projects, so Coana has no vulnerability to analyze even
+# though manifest upload, facts generation, and scan finalization all succeed.
+# After the workflow's bounded retries, classify only that explicit
+# upstream signature as inconclusive. Any other empty facts result still fails,
+# including the important regression case where Coana received a vulnerability
+# but the CLI lost its alerted component.
+if ! bash tests/e2e/reach-facts-probe.sh tests/e2e/fixtures/simple-npm; then
+  if grep -q "Found 1 manifest files for reachability upload" "$LOG" && \
+     grep -q "Found 0 projects across 0 ecosystems to analyze" "$LOG" && \
+     grep -q "Filtered out 1 orphaned component" "$LOG"; then
+    echo "::warning title=e2e-reachability inconclusive backend result::tier-1 returned the known zero-project/orphaned-component signature after retries; core reachability execution and finalization passed"
+    echo "e2e-reachability: inconclusive after retries — known zero-project backend signature; diagnostics uploaded" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+    exit 0
+  fi
+  echo "FAIL: no components with alerts in .socket.facts.json and the known backend signature was not present"
+  exit 1
+fi
+
 # 3-4. Build SARIF from the facts file produced by the initial --reach run.
 # Avoid re-running reach + full scan here; duplicate API scans are slow and flaky in CI.
 uv run python -c "
diff --git a/uv.lock b/uv.lock
index ce7c38a..fb5a540 100644
--- a/uv.lock
+++ b/uv.lock
@@ -196,18 +196,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ef/6f/534205ba7590c9a8716a614f270c5c2ec419b5b7079b3f9cd31b7b5580de/brotlicffi-1.2.0.1-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:f2a5575653b0672638ba039b82fda56854934d7a6a24d4b8b5033f73ab43cbc1", size = 375108, upload-time = "2026-03-05T19:54:10.079Z" },
 ]
 
-[[package]]
-name = "bs4"
-version = "0.0.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "beautifulsoup4" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/c9/aa/4acaf814ff901145da37332e05bb510452ebed97bc9602695059dd46ef39/bs4-0.0.2.tar.gz", hash = "sha256:a48685c58f50fe127722417bae83fe6badf500d54b55f7e39ffe43b798653925", size = 698, upload-time = "2024-01-17T18:15:47.371Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/51/bb/bf7aab772a159614954d84aa832c129624ba6c32faa559dfb200a534e50b/bs4-0.0.2-py2.py3-none-any.whl", hash = "sha256:abf8742c0805ef7f662dce4b51cca104cffe52b835238afc169142ab9b3fbccc", size = 1189, upload-time = "2024-01-17T18:15:48.613Z" },
-]
-
 [[package]]
 name = "certifi"
 version = "2025.11.12"
@@ -1281,25 +1269,25 @@ wheels = [
 
 [[package]]
 name = "socketdev"
-version = "3.3.0"
+version = "3.5.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "requests" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/25/30/16155f7f27d18274f364b3bd3506ee45d17f53fc8938aaea9a618054449b/socketdev-3.3.0.tar.gz", hash = "sha256:3d60bd4ac3201e9d581b1fe02bf2e6aef1b90c13ae75d15a8664aa9ef966734e", size = 181519, upload-time = "2026-06-10T11:41:17.942Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/64/24/0c11290dc7d59e24b7075035c7e1a3ab87fa17a445cebc88cfa6ee98b22c/socketdev-3.5.0.tar.gz", hash = "sha256:a2b20f9b98f73c25f3d2e97a1ae730504509c91219c0b393f28a9230266b3531", size = 195138, upload-time = "2026-08-06T03:47:14.185Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/33/dd/25622e033182e8c744d2420bb4f056206edc096a1e5ce8e4af4b0a0c0791/socketdev-3.3.0-py3-none-any.whl", hash = "sha256:513c045ce42bdd6cc2bb66a527f5863e0c399e56dbdcb1832cd5d94a5fb1a5e4", size = 67956, upload-time = "2026-06-10T11:41:16.534Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/75/5a8506a473716740e94f2f01b697909333f966c143d8a0a566d278e6118d/socketdev-3.5.0-py3-none-any.whl", hash = "sha256:780f5841770397035ff87de6181d954b6318cd0a07f6fdd304d1376667f33f68", size = 72027, upload-time = "2026-08-06T03:47:12.773Z" },
 ]
 
 [[package]]
 name = "socketsecurity"
-version = "2.5.9"
+version = "2.6.0"
 source = { editable = "." }
 dependencies = [
+    { name = "beautifulsoup4" },
     { name = "brotli", marker = "platform_python_implementation == 'CPython'" },
     { name = "brotlicffi", marker = "platform_python_implementation != 'CPython'" },
-    { name = "bs4" },
     { name = "gitpython" },
     { name = "markdown" },
     { name = "mdutils" },
@@ -1333,25 +1321,25 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "brotli", marker = "platform_python_implementation == 'CPython'", specifier = ">=1.0.9" },
-    { name = "brotlicffi", marker = "platform_python_implementation != 'CPython'", specifier = ">=1.0.9" },
-    { name = "bs4", specifier = ">=0.0.2" },
-    { name = "gitpython" },
+    { name = "beautifulsoup4", specifier = "==4.14.3" },
+    { name = "brotli", marker = "platform_python_implementation == 'CPython'", specifier = "==1.2.0" },
+    { name = "brotlicffi", marker = "platform_python_implementation != 'CPython'", specifier = "==1.2.0.1" },
+    { name = "gitpython", specifier = "==3.1.57" },
     { name = "hatch", marker = "extra == 'dev'" },
-    { name = "markdown", specifier = ">=3.10" },
-    { name = "mdutils" },
-    { name = "packaging" },
+    { name = "markdown", specifier = "==3.10.2" },
+    { name = "mdutils", specifier = "==1.8.1" },
+    { name = "packaging", specifier = "==26.2" },
     { name = "pre-commit", marker = "extra == 'dev'" },
-    { name = "prettytable" },
+    { name = "prettytable", specifier = "==3.18.0" },
     { name = "pytest", marker = "extra == 'test'", specifier = ">=7.4.0" },
     { name = "pytest-asyncio", marker = "extra == 'test'", specifier = ">=0.23.0" },
     { name = "pytest-cov", marker = "extra == 'test'", specifier = ">=4.1.0" },
     { name = "pytest-mock", marker = "extra == 'test'", specifier = ">=3.12.0" },
     { name = "pytest-watch", marker = "extra == 'test'", specifier = ">=4.2.0" },
-    { name = "python-dotenv" },
-    { name = "requests" },
+    { name = "python-dotenv", specifier = "==1.2.2" },
+    { name = "requests", specifier = "==2.34.2" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.3.0" },
-    { name = "socketdev", specifier = ">=3.3.0,<4.0.0" },
+    { name = "socketdev", specifier = "==3.5.0" },
     { name = "twine", marker = "extra == 'dev'" },
     { name = "uv", marker = "extra == 'dev'", specifier = ">=0.1.0" },
 ]