ci: enforce python -m pip workflows + add pip-policy guard

.github/actions/setup-python-safe/action.yml

@@ -20,6 +20,15 @@ inputs:
 runs:
   using: "composite"
   steps:
+    - name: Prepare writable tool cache
+      shell: bash
+      run: |
+        set -euo pipefail
+        TOOL_CACHE="${RUNNER_TEMP:-/tmp}/hostedtoolcache"
+        mkdir -p "${TOOL_CACHE}"
+        echo "AGENT_TOOLSDIRECTORY=${TOOL_CACHE}" >> "${GITHUB_ENV}"
+        echo "RUNNER_TOOL_CACHE=${TOOL_CACHE}" >> "${GITHUB_ENV}"
+
     - name: Set up Python ${{ inputs.python-version }}
       id: setup-python
       uses: actions/setup-python@v5
@@ -33,13 +42,57 @@ runs:
       if: steps.setup-python.outcome == 'failure'
       shell: bash
       run: |
+        set -euo pipefail
         echo "::warning::actions/setup-python failed — falling back to system Python"
+        PY_BIN=""
         for cmd in python${{ inputs.python-version }} python3 python; do
           if command -v "$cmd" &>/dev/null; then
             echo "Found $cmd: $("$cmd" --version)"
-            sudo ln -sf "$(command -v "$cmd")" /usr/local/bin/python
-            sudo ln -sf "$(command -v "$cmd")" /usr/local/bin/python3
+            PY_BIN="$(command -v "$cmd")"
             break
           fi
         done
-        python --version || { echo "::error::No Python interpreter found"; exit 1; }
+
+        # actions/setup-python may download and unpack a requested interpreter
+        # before failing to install into the hosted tool cache. Reuse that
+        # unpacked binary when available.
+        if [[ -z "${PY_BIN}" && -n "${RUNNER_TEMP:-}" ]]; then
+          DISCOVERED_PY="$(find "${RUNNER_TEMP}" -type f -name "python${{ inputs.python-version }}" -perm -u+x 2>/dev/null | head -n 1 || true)"
+          if [[ -n "${DISCOVERED_PY}" ]]; then
+            PY_BIN="${DISCOVERED_PY}"
+            echo "Found unpacked interpreter in RUNNER_TEMP: ${PY_BIN}"
+            "${PY_BIN}" --version || true
+          fi
+        fi
+
+        if [[ -z "${PY_BIN}" ]]; then
+          echo "::error::No Python interpreter found"
+          exit 1
+        fi
+
+        LOCAL_BIN="${RUNNER_TEMP:-$HOME}/setup-python-safe-bin"
+        mkdir -p "${LOCAL_BIN}"
+        cat > "${LOCAL_BIN}/python" <<EOF
+        #!/usr/bin/env bash
+        exec "${PY_BIN}" "\$@"
+        EOF
+        chmod +x "${LOCAL_BIN}/python"
+        ln -sf "${LOCAL_BIN}/python" "${LOCAL_BIN}/python3"
+
+        # Make pip reliably available on self-hosted runners even when
+        # actions/setup-python fails and no pip shim is on PATH.
+        "${LOCAL_BIN}/python" -m ensurepip --upgrade || true
+        "${LOCAL_BIN}/python" -m pip --version
+
+        cat > "${LOCAL_BIN}/pip" <<EOF
+        #!/usr/bin/env bash
+        exec "${PY_BIN}" -m pip "\$@"
+        EOF
+        chmod +x "${LOCAL_BIN}/pip"
+        ln -sf "${LOCAL_BIN}/pip" "${LOCAL_BIN}/pip3"
+
+        echo "${LOCAL_BIN}" >> "${GITHUB_PATH}"
+        export PATH="${LOCAL_BIN}:${PATH}"
+
+        "${LOCAL_BIN}/python" --version
+        "${LOCAL_BIN}/python" -m pip --version

.github/workflows/aragora-review-gate.yml

@@ -132,7 +132,7 @@ jobs:
       - name: Install Aragora
         run: |
           python -m pip install --upgrade pip
-          pip install -e . 2>/dev/null || pip install -r requirements.txt
+          python -m pip install -e . 2>/dev/null || python -m pip install -r requirements.txt
 
       - name: Run Aragora Review
         id: review

.github/workflows/autopilot-worktree-e2e.yml

@@ -114,8 +114,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,test]"
-          pip install pytest-timeout
+          python -m pip install -e ".[dev,test]"
+          python -m pip install pytest-timeout
 
       - name: Run autopilot API end-to-end test
         env:

.github/workflows/backup-verification.yml

@@ -68,7 +68,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          python -m pip install -e ".[dev]"
 
       - name: Run backup manager tests
         run: |
@@ -128,7 +128,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          python -m pip install -e ".[dev]"
 
       - name: Run DR drill tests
         run: |
@@ -182,7 +182,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          python -m pip install -e ".[dev]"
 
       - name: Run backup handler tests
         run: |

.github/workflows/benchmark.yml

@@ -76,7 +76,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           bash scripts/ci_install_project.sh --extras test
-          pip install pytest-benchmark
+          python -m pip install pytest-benchmark
 
       - name: Run benchmark tests
         run: |
@@ -235,7 +235,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           bash scripts/ci_install_project.sh --extras test
-          pip install pytest-benchmark
+          python -m pip install pytest-benchmark
 
       - name: Run PR benchmarks
         run: |

.github/workflows/benchmarks.yml

@@ -130,9 +130,9 @@ jobs:
         run: |
           python -m venv /tmp/main-venv
           source /tmp/main-venv/bin/activate
-          pip install --upgrade pip
-          pip install -e "main-branch/[test]"
-          pip install pytest-benchmark
+          python -m pip install --upgrade pip
+          python -m pip install -e "main-branch/[test]"
+          python -m pip install pytest-benchmark
           cd main-branch
           pytest tests/benchmarks/test_performance.py \
             --benchmark-only \

.github/workflows/capability-gap.yml

@@ -68,7 +68,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          python -m pip install -e .
 
       - name: Generate report (markdown)
         run: |

.github/workflows/contract-drift-governance.yml

@@ -62,7 +62,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          python -m pip install -e .
 
       - name: Generate drift summary and planning artifacts
         run: |

.github/workflows/coverage.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,test]"
+          python -m pip install -e ".[dev,test]"
 
       - name: Run tests with coverage
         run: |
@@ -260,7 +260,7 @@ jobs:
         if: steps.changed.outputs.files != ''
         run: |
           echo "Changed files: ${{ steps.changed.outputs.files }}"
-          pip install -e ".[dev,test]"
+          python -m pip install -e ".[dev,test]"
 
           # Run coverage on changed files only
           python -m pytest tests/ \

.github/workflows/deploy-canary.yml

@@ -233,7 +233,7 @@ jobs:
               "sudo -u ec2-user git checkout main || sudo -u ec2-user git checkout -b main origin/main",
               "sudo -u ec2-user git reset --hard origin/main",
               "source venv/bin/activate",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"",
               "sudo mkdir -p /etc/systemd/system/aragora.service.d/",
               "echo \"[Service]\" | sudo tee /etc/systemd/system/aragora.service.d/secrets.conf",
@@ -512,7 +512,7 @@ jobs:
                 "sudo -u ec2-user git checkout main || sudo -u ec2-user git checkout -b main origin/main",
                 "sudo -u ec2-user git reset --hard origin/main",
                 "source venv/bin/activate",
-                "pip install -e . --quiet --no-cache-dir",
+                "python -m pip install -e . --quiet --no-cache-dir",
                 "sudo mkdir -p /etc/systemd/system/aragora.service.d/",
                 "echo \"[Service]\" | sudo tee /etc/systemd/system/aragora.service.d/secrets.conf",
                 "echo \"Environment=ARAGORA_USE_SECRETS_MANAGER=true\" | sudo tee -a /etc/systemd/system/aragora.service.d/secrets.conf",
@@ -624,7 +624,7 @@ jobs:
               "if [ -f /tmp/aragora_canary_state ]; then source /tmp/aragora_canary_state; fi",
               "if [ -n \"$PREVIOUS_COMMIT\" ]; then sudo -u ec2-user git checkout $PREVIOUS_COMMIT; fi",
               "source venv/bin/activate",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "sudo systemctl restart aragora",
               "rm -f /tmp/aragora_canary_state",
               "echo \"Canary rollback complete\""

.github/workflows/deploy-ec2.yml

@@ -146,7 +146,7 @@ jobs:
               "sudo -u ec2-user git reset --hard origin/main",
               "sudo chown -R ec2-user:ec2-user /home/ec2-user/aragora/venv || true",
               "sudo chown -R ec2-user:ec2-user /home/ec2-user/.npm /home/ec2-user/.cache || true",
-              "sudo -u ec2-user bash -c 'cd /home/ec2-user/aragora && source venv/bin/activate && pip install -e . --quiet --no-cache-dir'",
+              "sudo -u ec2-user bash -c 'cd /home/ec2-user/aragora && source venv/bin/activate && python -m pip install -e . --quiet --no-cache-dir'",
               "find /home/ec2-user/aragora/venv/lib/python3.11/site-packages -maxdepth 1 -name \"~*\" -type d -exec rm -rf {} + 2>/dev/null || true",
               "sudo -u ec2-user bash -c 'cd /home/ec2-user/aragora && source venv/bin/activate && python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"'",
               "sudo systemctl restart aragora",
@@ -295,7 +295,7 @@ jobs:
               "if [ -f /tmp/aragora_deploy_state ]; then source /tmp/aragora_deploy_state; fi",
               "if [ -n \"$PREVIOUS_COMMIT\" ]; then sudo -u ec2-user git checkout $PREVIOUS_COMMIT; fi",
               "source venv/bin/activate",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "sudo systemctl restart aragora",
               "rm -f /tmp/aragora_deploy_state",
               "echo \"Canary rollback complete\""
@@ -361,7 +361,7 @@ jobs:
               "sudo -u ec2-user git reset --hard origin/main",
               "sudo chown -R ec2-user:ec2-user /home/ec2-user/aragora/venv || true",
               "sudo chown -R ec2-user:ec2-user /home/ec2-user/.npm /home/ec2-user/.cache || true",
-              "sudo -u ec2-user bash -c 'cd /home/ec2-user/aragora && source venv/bin/activate && pip install -e . --quiet --no-cache-dir'",
+              "sudo -u ec2-user bash -c 'cd /home/ec2-user/aragora && source venv/bin/activate && python -m pip install -e . --quiet --no-cache-dir'",
               "find /home/ec2-user/aragora/venv/lib/python3.11/site-packages -maxdepth 1 -name \"~*\" -type d -exec rm -rf {} + 2>/dev/null || true",
               "sudo -u ec2-user bash -c 'cd /home/ec2-user/aragora && source venv/bin/activate && python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"'",
               "sudo systemctl restart aragora",
@@ -546,7 +546,7 @@ jobs:
               "if [ -f /tmp/aragora_deploy_state ]; then source /tmp/aragora_deploy_state; fi",
               "if [ -n \"$PREVIOUS_COMMIT\" ]; then sudo -u ec2-user git checkout $PREVIOUS_COMMIT; fi",
               "source venv/bin/activate",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "sudo systemctl restart aragora",
               "rm -f /tmp/aragora_deploy_state",
               "echo \"Worker rollback complete\""

.github/workflows/deploy-lightsail.yml

@@ -106,7 +106,7 @@ jobs:
 
             # Install
             source venv/bin/activate 2>/dev/null || source .venv/bin/activate 2>/dev/null || true
-            pip install -e . --quiet --no-cache-dir 2>/dev/null || true
+            python -m pip install -e . --quiet --no-cache-dir 2>/dev/null || true
 
             # Import check
             python -c "from aragora.server.unified_server import UnifiedServer; print('Import OK')"

.github/workflows/deploy-secure.yml

@@ -339,7 +339,7 @@ jobs:
               "source venv/bin/activate",
               "echo \"Cleaning corrupted pip distributions...\"",
               "find venv/lib/python3.11/site-packages -maxdepth 1 -name '~*' -type d -exec rm -rf {} + 2>/dev/null || true",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "find venv/lib/python3.11/site-packages -maxdepth 1 -name '~*' -type d -exec rm -rf {} + 2>/dev/null || true",
               "python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"",
               "echo \"Setting up secrets manager for systemd...\"",
@@ -615,7 +615,7 @@ jobs:
               "if [ -f /tmp/aragora_deploy_state ]; then source /tmp/aragora_deploy_state; fi",
               "if [ -n \"$PREVIOUS_COMMIT\" ]; then sudo -u ec2-user git checkout $PREVIOUS_COMMIT; fi",
               "source venv/bin/activate",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "sudo systemctl restart aragora",
               "rm -f /tmp/aragora_deploy_state",
               "echo \"Rollback complete\""
@@ -772,7 +772,7 @@ jobs:
               "source venv/bin/activate",
               "echo \"Cleaning corrupted pip distributions...\"",
               "find venv/lib/python3.11/site-packages -maxdepth 1 -name '~*' -type d -exec rm -rf {} + 2>/dev/null || true",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "find venv/lib/python3.11/site-packages -maxdepth 1 -name '~*' -type d -exec rm -rf {} + 2>/dev/null || true",
               "python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"",
               "echo \"Setting up secrets manager for systemd...\"",
@@ -877,7 +877,7 @@ jobs:
                 "sudo -u ec2-user git reset --hard origin/main",
                 "source venv/bin/activate",
                 "find venv/lib/python3.11/site-packages -maxdepth 1 -name ~* -type d -exec rm -rf {} + 2>/dev/null || true",
-                "pip install -e . --quiet --no-cache-dir",
+                "python -m pip install -e . --quiet --no-cache-dir",
                 "find venv/lib/python3.11/site-packages -maxdepth 1 -name ~* -type d -exec rm -rf {} + 2>/dev/null || true",
                 "python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"",
                 "echo \"Setting up secrets manager for systemd...\"",
@@ -1062,7 +1062,7 @@ jobs:
               "if [ -f /tmp/aragora_deploy_state ]; then source /tmp/aragora_deploy_state; fi",
               "if [ -n \"$PREVIOUS_COMMIT\" ]; then sudo -u ec2-user git checkout $PREVIOUS_COMMIT; fi",
               "source venv/bin/activate",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "sudo systemctl restart aragora",
               "rm -f /tmp/aragora_deploy_state",
               "echo \"Rollback complete\""
@@ -1175,7 +1175,7 @@ jobs:
               "source venv/bin/activate",
               "echo \"Cleaning corrupted pip distributions...\"",
               "find venv/lib/python3.11/site-packages -maxdepth 1 -name '~*' -type d -exec rm -rf {} + 2>/dev/null || true",
-              "pip install -e . --quiet --no-cache-dir",
+              "python -m pip install -e . --quiet --no-cache-dir",
               "find venv/lib/python3.11/site-packages -maxdepth 1 -name '~*' -type d -exec rm -rf {} + 2>/dev/null || true",
               "python -c \"from aragora.server.unified_server import UnifiedServer; print(\\\"Import OK\\\")\"",
               "echo \"Setting up secrets manager for systemd...\"",

.github/workflows/docs-build.yml

@@ -72,7 +72,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          python -m pip install -e .
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

.github/workflows/e2e.yml

@@ -75,7 +75,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,test]"
+          python -m pip install -e ".[dev,test]"
 
       - name: Start Aragora backend
         run: |
@@ -243,8 +243,8 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
-          pip install pytest pytest-asyncio pytest-timeout aiohttp
+          python -m pip install -e ".[dev]"
+          python -m pip install pytest pytest-asyncio pytest-timeout aiohttp
 
       - name: Run Python E2E tests
         run: |

.github/workflows/integration-gate.yml

@@ -61,8 +61,8 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           # Keep smoke gate dependency footprint lean to avoid CI install stalls/timeouts.
-          pip install -e ".[dev,test]"
-          pip install pytest-timeout
+          python -m pip install -e ".[dev,test]"
+          python -m pip install pytest-timeout
 
       # ---------------------------------------------------------------
       # Smoke test script (backend-focused; frontend has its own gate)
@@ -123,7 +123,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,test]"
+          python -m pip install -e ".[dev,test]"
 
       # ---------------------------------------------------------------
       # OpenAPI spec drift detection
@@ -194,7 +194,7 @@ jobs:
           python-version: "3.11"
 
       - name: Install parity test deps
-        run: pip install pytest pytest-timeout pydantic pydantic-settings
+        run: python -m pip install pytest pytest-timeout pydantic pydantic-settings
 
       - name: "BLOCKING: SDK contract parity"
         run: |