chore(actions)(deps): bump docker/setup-buildx-action

Bumps [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) from 3.12.0 to 4.1.0.
- [Release notes](https://github.com/docker/setup-buildx-action/releases)
- [Commits](8d2750c68a...d7f5e7f509)

---
updated-dependencies:
- dependency-name: docker/setup-buildx-action
  dependency-version: 4.1.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/actions/detect-changes/action.yml

@@ -0,0 +1,62 @@
+name: Detect affected areas
+description: >-
+  Classify a PR's changed files into CI work lanes (python, frontend, site,
+  scan, deps, mcp_catalog) so the orchestrator can conditionally call only
+  the sub-workflows a PR can affect. Outputs are always "true" on push/dispatch
+  events and fail open (everything "true") when the diff cannot be computed.
+
+outputs:
+  python:
+    description: Run Python tests / ruff / ty / windows-footguns.
+    value: ${{ steps.classify.outputs.python }}
+  frontend:
+    description: Run the TypeScript typecheck matrix + desktop build.
+    value: ${{ steps.classify.outputs.frontend }}
+  docker_meta:
+    description: Docker setup and meta files have changed.
+    value: ${{ steps.classify.outputs.docker_meta }}
+  site:
+    description: Build the Docusaurus docs site.
+    value: ${{ steps.classify.outputs.site }}
+  scan:
+    description: Run the supply-chain critical-pattern scanner.
+    value: ${{ steps.classify.outputs.scan }}
+  deps:
+    description: Check pyproject.toml dependency upper bounds.
+    value: ${{ steps.classify.outputs.deps }}
+  mcp_catalog:
+    description: Require MCP catalog security review label.
+    value: ${{ steps.classify.outputs.mcp_catalog }}
+
+runs:
+  using: composite
+  steps:
+    - name: Classify changed files
+      id: classify
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO: ${{ github.repository }}
+        EVENT_NAME: ${{ github.event_name }}
+        BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      run: |
+        set -euo pipefail
+
+        # Only pull_request events are gated. Other events (push, release,
+        # dispatch) leave CHANGED empty, so the classifier fails open and every
+        # lane runs. Post-merge / on-demand validation is never weakened.
+        if [ "$EVENT_NAME" = "pull_request" ]; then
+          # Use the compare endpoint with the pinned base/head SHAs from the
+          # event payload instead of the "current PR files" endpoint. The SHAs
+          # are frozen at trigger time, so the file list is deterministic even
+          # if the PR receives a new push between trigger and detect.
+          CHANGED="$(gh api \
+            --paginate \
+            "repos/${REPO}/compare/${BASE_SHA}...${HEAD_SHA}" \
+            --jq '.files[].filename' || true)"
+        fi
+
+        echo "Changed files:"
+        printf '%s\n' "${CHANGED:-(none)}"
+        printf '%s\n' "${CHANGED:-}" | python3 scripts/ci/classify_changes.py

.github/actions/retry/action.yml

@@ -0,0 +1,50 @@
+name: Retry a flaky command
+description: >-
+  Run a shell command, retrying on non-zero exit. For dependency installs
+  (npm ci, uv sync) whose only failures are transient network/toolchain
+  flakes — a node-gyp header fetch, a registry blip — so CI self-heals
+  instead of needing a manual re-run.
+
+inputs:
+  command:
+    description: Shell command to run (and retry).
+    required: true
+  attempts:
+    description: Max attempts before giving up.
+    default: "3"
+  delay:
+    description: Seconds to wait between attempts.
+    default: "10"
+  working-directory:
+    description: Directory to run in.
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      # command goes through env, never interpolated into the script body, so
+      # a command with quotes/specials can't break or inject into the runner.
+      env:
+        _CMD: ${{ inputs.command }}
+        _ATTEMPTS: ${{ inputs.attempts }}
+        _DELAY: ${{ inputs.delay }}
+      run: |
+        set -uo pipefail
+        n=0
+        while :; do
+          n=$((n + 1))
+          echo "::group::attempt $n/$_ATTEMPTS: $_CMD"
+          if bash -c "$_CMD"; then
+            echo "::endgroup::"
+            exit 0
+          fi
+          echo "::endgroup::"
+          if [ "$n" -ge "$_ATTEMPTS" ]; then
+            echo "::error::failed after $n attempts: $_CMD"
+            exit 1
+          fi
+          echo "::warning::attempt $n failed; retrying in ${_DELAY}s: $_CMD"
+          sleep "$_DELAY"
+        done

.github/workflows/build-windows-installer.yml

@@ -1,100 +0,0 @@
-name: Build Windows Installer
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  # Gate: workflow_dispatch is already restricted to users with write access,
-  # but we want ADMIN-only. Explicitly check the triggering actor's repo
-  # permission via the API and fail fast for anyone below admin.
-  authorize:
-    name: Authorize (admins only)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Check actor is a repo admin
-        env:
-          GH_TOKEN: ${{ github.token }}
-          ACTOR: ${{ github.actor }}
-        run: |
-          set -euo pipefail
-          perm=$(gh api \
-            "repos/${{ github.repository }}/collaborators/${ACTOR}/permission" \
-            --jq '.permission')
-          echo "Actor '${ACTOR}' has permission: ${perm}"
-          if [ "${perm}" != "admin" ]; then
-            echo "::error::'${ACTOR}' is not a repo admin (permission=${perm}). Refusing to build/sign."
-            exit 1
-          fi
-          echo "Authorized: '${ACTOR}' is an admin."
-
-  build:
-    name: Hermes-Setup.exe
-    needs: authorize
-    runs-on: windows-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-      # Required for OIDC auth to Azure (azure/login federated credentials).
-      id-token: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
-        with:
-          node-version: 22
-          cache: npm
-
-      - name: Install npm dependencies
-        run: npm ci
-
-      - name: Setup Rust
-        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8  # stable
-
-      - name: Cache Rust targets
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32  # v2
-        with:
-          workspaces: apps/bootstrap-installer/src-tauri
-
-      - name: Build installer
-        run: npm run tauri:build
-        working-directory: apps/bootstrap-installer
-
-      - name: Azure login (OIDC)
-        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5  # v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-
-      - name: Sign Hermes-Setup.exe with Azure Artifact Signing
-        uses: azure/artifact-signing-action@c7ab2a863ab5f9a846ddb8265964877ef296ee82  # v2
-        with:
-          endpoint: ${{ vars.AZURE_SIGNING_ENDPOINT }}
-          signing-account-name: ${{ vars.AZURE_SIGNING_ACCOUNT_NAME }}
-          certificate-profile-name: ${{ vars.AZURE_SIGNING_CERTIFICATE_PROFILE }}
-          # Sign both the raw exe and the bundled NSIS installer.
-          files-folder: ${{ github.workspace }}\apps\bootstrap-installer\src-tauri\target\release
-          files-folder-filter: exe
-          files-folder-recurse: true
-          file-digest: SHA256
-          timestamp-rfc3161: http://timestamp.acs.microsoft.com
-          timestamp-digest: SHA256
-
-      - name: Upload NSIS installer
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: Hermes-Setup-installer
-          path: apps/bootstrap-installer/src-tauri/target/release/bundle/nsis/*.exe
-
-      - name: Upload raw exe
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: Hermes-Setup-exe
-          path: apps/bootstrap-installer/src-tauri/target/release/Hermes-Setup.exe

.github/workflows/ci.yml

@@ -0,0 +1,146 @@
+name: CI
+
+# Orchestrator workflow. Runs ``detect-changes`` once, then conditionally
+# calls the sub-workflows that a PR can actually affect. A final
+# ``all-checks-pass`` gate job aggregates results so branch protection only
+# needs to require a single check.
+#
+# Sub-workflows are triggered via ``workflow_call`` and keep their own job
+# definitions, matrices, and concurrency settings. They no longer have
+# ``push:`` / ``pull_request:`` triggers of their own — everything flows
+# through this file.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write  # needed by lint (PR comment) + supply-chain (PR comment)
+  actions: read          # needed by osv-scanner (SARIF upload)
+  security-events: write # needed by osv-scanner (SARIF upload)
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────
+  # detect: run the classifier once. Every downstream job reads its outputs
+  # to decide whether to run. On push/dispatch the classifier fails open
+  # (all lanes true) so post-merge validation is never weakened.
+  # ─────────────────────────────────────────────────────────────────────
+  detect:
+    runs-on: ubuntu-latest
+    outputs:
+      python: ${{ steps.classify.outputs.python }}
+      frontend: ${{ steps.classify.outputs.frontend }}
+      site: ${{ steps.classify.outputs.site }}
+      scan: ${{ steps.classify.outputs.scan }}
+      deps: ${{ steps.classify.outputs.deps }}
+      docker_meta: ${{ steps.classify.outputs.docker_meta }}
+      mcp_catalog: ${{ steps.classify.outputs.mcp_catalog }}
+      event_name: ${{ github.event_name }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Detect affected areas
+        id: classify
+        uses: ./.github/actions/detect-changes
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Lane-gated sub-workflows. Each runs in parallel after detect finishes.
+  # Skipped workflows (if condition is false) don't spin up runners.
+  # ─────────────────────────────────────────────────────────────────────
+  tests:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/tests.yml
+
+  lint:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/lint.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+
+  typecheck:
+    needs: detect
+    if: needs.detect.outputs.frontend == 'true'
+    uses: ./.github/workflows/typecheck.yml
+
+  docs-site:
+    needs: detect
+    if: needs.detect.outputs.site == 'true'
+    uses: ./.github/workflows/docs-site-checks.yml
+
+  history-check:
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request'
+    uses: ./.github/workflows/history-check.yml
+
+  contributor-check:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/contributor-check.yml
+
+  uv-lockfile:
+    needs: detect
+    uses: ./.github/workflows/uv-lockfile-check.yml
+
+  docker-lint:
+    needs: detect
+    if: needs.detect.outputs.docker_meta == 'true'
+    uses: ./.github/workflows/docker-lint.yml
+
+  supply-chain:
+    needs: detect
+    if: needs.detect.outputs.scan == 'true' || needs.detect.outputs.deps == 'true' || needs.detect.outputs.mcp_catalog == 'true'
+    uses: ./.github/workflows/supply-chain-audit.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+      scan: ${{ needs.detect.outputs.scan == 'true' }}
+      deps: ${{ needs.detect.outputs.deps == 'true' }}
+      mcp_catalog: ${{ needs.detect.outputs.mcp_catalog == 'true' }}
+
+  osv-scanner:
+    needs: detect
+    uses: ./.github/workflows/osv-scanner.yml
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Gate: runs after everything. ``if: always()`` ensures it reports a
+  # status even when some deps were skipped. Only actual ``failure``
+  # results cause it to fail; ``skipped`` is treated as success.
+  #
+  # Branch protection should require ONLY this check.
+  # ─────────────────────────────────────────────────────────────────────
+  all-checks-pass:
+    name: All required checks pass
+    needs:
+      - tests
+      - lint
+      - typecheck
+      - docs-site
+      - history-check
+      - contributor-check
+      - uv-lockfile
+      - docker-lint
+      - supply-chain
+      - osv-scanner
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate job results
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: |
+          echo "$RESULTS" | python3 -c "
+          import json, sys
+          results = json.load(sys.stdin)
+          failed = [r for r in results if r == 'failure']
+          if failed:
+              print(f'::error::{len(failed)} job(s) failed')
+              sys.exit(1)
+          print('All checks passed (or were skipped)')
+          "

.github/workflows/contributor-check.yml

@@ -1,11 +1,8 @@
 name: Contributor Attribution Check
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
+
 permissions:
   contents: read
 
@@ -17,21 +14,7 @@ jobs:
         with:
           fetch-depth: 0  # Full history needed for git log
 
-      - name: Check if relevant files changed
-        id: filter
-        run: |
-          BASE="${{ github.event.pull_request.base.sha }}"
-          HEAD="${{ github.event.pull_request.head.sha }}"
-          CHANGED=$(git diff --name-only "$BASE"..."$HEAD" -- '*.py' '**/*.py' '.github/workflows/contributor-check.yml' || true)
-          if [ -n "$CHANGED" ]; then
-            echo "run=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "run=false" >> "$GITHUB_OUTPUT"
-            echo "No Python files changed, skipping attribution check."
-          fi
-
       - name: Check for unmapped contributor emails
-        if: steps.filter.outputs.run == 'true'
         run: |
           # Get the merge base between this PR and main
           MERGE_BASE=$(git merge-base origin/main HEAD)

.github/workflows/docker-lint.yml

@@ -11,19 +11,7 @@ name: Docker / shell lint
 # activate script doesn't exist at lint time.
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - Dockerfile
-      - docker/**
-      - .hadolint.yaml
-      - .github/workflows/docker-lint.yml
-
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read

.github/workflows/docker-publish.yml

@@ -56,13 +56,21 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
+      # The image build + smoke test + integration tests run ONLY on
+      # push-to-main and release — never on PRs. They are the heaviest jobs
+      # in CI (~15-45 min) and a broken build surfaces on the main push (and
+      # is gated pre-merge by docker-lint + uv-lockfile-check). Every step
+      # below is skipped on PRs, so the job still reports green and the
+      # required check never hangs.
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+        if: github.event_name != 'pull_request'
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
 
       # Build once, load into the local daemon for smoke testing.  Cached
       # to gha with a per-arch scope; the push step below reuses every
       # layer from this build.
       - name: Build image (amd64, smoke test)
+        if: github.event_name != 'pull_request'
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
         with:
           context: .
@@ -76,6 +84,7 @@ jobs:
           cache-to: type=gha,mode=max,scope=docker-amd64
 
       - name: Smoke test image
+        if: github.event_name != 'pull_request'
         uses: ./.github/actions/hermes-smoke-test
         with:
           image: ${{ env.IMAGE_NAME }}:test
@@ -102,12 +111,15 @@ jobs:
       # cheapest path to coverage on every PR that touches docker code.
       # ---------------------------------------------------------------------
       - name: Install uv (for docker tests)
+        if: github.event_name != 'pull_request'
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
 
       - name: Set up Python 3.11 (for docker tests)
+        if: github.event_name != 'pull_request'
         run: uv python install 3.11
 
       - name: Install Python dependencies (for docker tests)
+        if: github.event_name != 'pull_request'
         run: |
           uv venv .venv --python 3.11
           source .venv/bin/activate
@@ -118,6 +130,7 @@ jobs:
           uv pip install -e ".[dev]"
 
       - name: Run docker integration tests
+        if: github.event_name != 'pull_request'
         env:
           # Skip rebuild; use the image already loaded by the build step.
           HERMES_TEST_IMAGE: ${{ env.IMAGE_NAME }}:test
@@ -190,8 +203,10 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
+      # arm64 build runs only on push-to-main and release (see build-amd64).
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+        if: github.event_name != 'pull_request'
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
 
       # Log in to ghcr.io so the registry-backed build cache below can be
       # read (cache-from) on every event and written (cache-to) on
@@ -201,41 +216,21 @@ jobs:
       # crashed the build before the smoke test (the reason the gha cache
       # was removed from arm64 PRs in the first place).
       - name: Log in to ghcr.io (build cache)
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121  # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      # Build once, load into the local daemon for smoke testing.
-      #
-      # PR builds use the registry-backed cache READ-ONLY (cache-from only):
-      # they pull warm layers pushed by the most recent main build but never
-      # write, so rapid PR pushes don't race on cache writes or pollute the
-      # cache ref.  This restores warm-cache speed to arm64 PR builds (which
-      # were running fully uncached and were ~45% slower than amd64, making
-      # them the job most often cancelled on supersede).
+      # Build once, load into the local daemon for smoke testing, then push
+      # by digest below. Reads AND writes the registry-backed cache so the
+      # push reuses layers from this build and the next build starts warm.
       #
       # Registry cache (type=registry on ghcr.io) is used instead of the gha
       # cache that previously broke here: its credential is the job-lifetime
       # GITHUB_TOKEN, not a short-lived SAS token, so the cold-build-outlives-
       # token failure mode cannot recur.
-      - name: Build image (arm64, smoke test, cache read-only PR)
-        if: github.event_name == 'pull_request'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
-        with:
-          context: .
-          file: Dockerfile
-          load: true
-          platforms: linux/arm64
-          tags: ${{ env.IMAGE_NAME }}:test
-          build-args: |
-            HERMES_GIT_SHA=${{ github.sha }}
-          cache-from: type=registry,ref=ghcr.io/nousresearch/hermes-agent:buildcache-arm64
-
-      # Main/release builds read AND write the registry cache so the digest
-      # push below reuses layers from this smoke-test build, and so the next
-      # PR/main build starts warm.
       - name: Build image (arm64, smoke test, cached publish)
         if: github.event_name != 'pull_request'
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
@@ -251,6 +246,7 @@ jobs:
           cache-to: type=registry,ref=ghcr.io/nousresearch/hermes-agent:buildcache-arm64,mode=max
 
       - name: Smoke test image
+        if: github.event_name != 'pull_request'
         uses: ./.github/actions/hermes-smoke-test
         with:
           image: ${{ env.IMAGE_NAME }}:test
@@ -316,7 +312,7 @@ jobs:
           merge-multiple: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
 
       - name: Log in to Docker Hub
         uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121  # v4.1.0

.github/workflows/docs-site-checks.yml

@@ -1,13 +1,7 @@
 name: Docs Site Checks
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
-
-  workflow_dispatch:
+  workflow_call:
 
 permissions:
   contents: read
@@ -25,15 +19,19 @@ jobs:
           cache-dependency-path: website/package-lock.json
 
       - name: Install website dependencies
-        run: npm ci
-        working-directory: website
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci
+          working-directory: website
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
 
       - name: Install ascii-guard
-        run: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
+        uses: ./.github/actions/retry
+        with:
+          command: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
 
       - name: Extract skill metadata for dashboard
         run: python3 website/scripts/extract-skills.py

.github/workflows/history-check.yml

@@ -14,11 +14,7 @@ name: History Check
 # the PR head and main to be non-empty.
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read

.github/workflows/lint.yml

@@ -9,18 +9,12 @@ name: Lint (ruff + ty)
 #      enforcement fails.
 
 on:
-  push:
-    branches: [main]
-    paths-ignore:
-      - "**/*.md"
-      - "docs/**"
-      - "website/**"
-
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
+    inputs:
+      event_name:
+        description: The event name from the calling orchestrator (pull_request or push).
+        type: string
+        required: true
 
 permissions:
   contents: read
@@ -33,6 +27,7 @@ concurrency:
 jobs:
   lint-diff:
     name: ruff + ty diff
+    if: inputs.event_name == 'pull_request'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -45,16 +40,16 @@ jobs:
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
 
       - name: Install ruff + ty
-        run: |
-          uv tool install ruff
-          uv tool install ty
+        uses: ./.github/actions/retry
+        with:
+          command: uv tool install ruff && uv tool install ty
 
       - name: Determine base ref
         id: base
         run: |
           # For PRs, diff against the merge base with the target branch.
           # For pushes to main, diff against the previous commit on main.
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
+          if [ "${{ inputs.event_name }}" = "pull_request" ]; then
             BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
             BASE_REF="origin/${{ github.base_ref }}"
           else
@@ -110,7 +105,7 @@ jobs:
             --base-ty   .lint-reports/base/ty.json \
             --head-ty   .lint-reports/head/ty.json \
             --base-ref  "${{ steps.base.outputs.ref }}" \
-            --head-ref  "${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}" \
+            --head-ref  "${{ inputs.event_name == 'pull_request' && github.head_ref || github.ref_name }}" \
             --output    .lint-reports/summary.md
           cat .lint-reports/summary.md >> "$GITHUB_STEP_SUMMARY"
 
@@ -122,7 +117,7 @@ jobs:
           retention-days: 14
 
       - name: Post / update PR comment
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        if: inputs.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
         continue-on-error: true
         uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
         with:
@@ -172,7 +167,9 @@ jobs:
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
 
       - name: Install ruff
-        run: uv tool install ruff
+        uses: ./.github/actions/retry
+        with:
+          command: uv tool install ruff
 
       - name: ruff check .
         # No --exit-zero, no || true. Exit code propagates to the job,

.github/workflows/osv-scanner.yml

@@ -1,8 +1,8 @@
 name: OSV-Scanner
 
 # Scans lockfiles (uv.lock, package-lock.json) against the OSV vulnerability
-# database. Runs on every PR that touches a lockfile and on a weekly schedule
-# against main.
+# database. Runs on every PR/push (via the ci.yml orchestrator's workflow_call)
+# and on a weekly schedule against main.
 #
 # This is detection-only — OSV-Scanner does NOT open PRs or modify pins.
 # It reports known CVEs in currently-pinned dependency versions so we can
@@ -10,9 +10,9 @@ name: OSV-Scanner
 # (full SHA / exact version) is preserved; only the notification signal
 # is added.
 #
-# Complements the existing supply-chain-audit.yml workflow (which scans
-# for malicious code patterns in PR diffs) by covering the orthogonal
-# "currently-pinned dep became known-vulnerable" case.
+# Complements the supply-chain-audit.yml workflow (which scans for malicious
+# code patterns in PR diffs) by covering the orthogonal "currently-pinned
+# dep became known-vulnerable" case.
 #
 # Uses Google's officially-recommended reusable workflow, pinned by SHA.
 # Findings land in the repo's Security tab (Code Scanning > OSV-Scanner).
@@ -20,19 +20,7 @@ name: OSV-Scanner
 # vulnerabilities in pinned deps that we may need to patch deliberately.
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-    paths:
-      - "uv.lock"
-      - "pyproject.toml"
-      - "package.json"
-      - "package-lock.json"
-      - "website/package-lock.json"
+  workflow_call:
   schedule:
     # Weekly scan against main — catches CVEs published after merge for
     # deps that haven't changed since.

.github/workflows/supply-chain-audit.yml

@@ -1,16 +1,5 @@
 name: Supply Chain Audit
 
-on:
-  # No paths filter — the jobs must always run so required checks
-  # report a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  pull-requests: write
-  contents: read
-
 # Narrow, high-signal scanner. Only fires on critical indicators of supply
 # chain attacks (e.g. the litellm-style payloads). Low-signal heuristics
 # (plain base64, plain exec/eval, dependency/Dockerfile/workflow edits,
@@ -19,56 +8,40 @@ permissions:
 # the scanner. Keep this file's checks ruthlessly narrow: if you find
 # yourself adding WARNING-tier patterns here again, make a separate
 # advisory-only workflow instead.
+#
+# Path-gating is handled centrally by the ``ci.yml`` orchestrator's
+# ``detect`` job. The orchestrator passes ``scan`` / ``deps`` /
+# ``mcp_catalog`` booleans as inputs; this workflow's jobs gate on those
+# inputs instead of re-computing the diff.
+
+on:
+  workflow_call:
+    inputs:
+      event_name:
+        description: The event name from the calling orchestrator.
+        type: string
+        required: true
+      scan:
+        description: Whether supply-chain-relevant files changed.
+        type: boolean
+        required: true
+      deps:
+        description: Whether pyproject.toml changed.
+        type: boolean
+        required: true
+      mcp_catalog:
+        description: Whether the MCP catalog / installer changed.
+        type: boolean
+        required: true
+
+permissions:
+  pull-requests: write
+  contents: read
 
 jobs:
-  # ── Path filter (shared by both scan and dep-bounds) ───────────────
-  changes:
-    runs-on: ubuntu-latest
-    outputs:
-      # True when any file the scanner cares about changed in this PR
-      scan: ${{ steps.filter.outputs.scan }}
-      # True when pyproject.toml changed in this PR
-      deps: ${{ steps.filter.outputs.deps }}
-      # True when the curated MCP catalog / bundled MCP manifests changed.
-      mcp_catalog: ${{ steps.filter.outputs.mcp_catalog }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-      - name: Check for relevant file changes
-        id: filter
-        run: |
-          BASE="${{ github.event.pull_request.base.sha }}"
-          HEAD="${{ github.event.pull_request.head.sha }}"
-          SCAN_FILES=$(git diff --name-only "$BASE"..."$HEAD" -- \
-            '*.py' '**/*.py' '*.pth' '**/*.pth' \
-            'setup.py' 'setup.cfg' \
-            'sitecustomize.py' 'usercustomize.py' '__init__.pth' \
-            'pyproject.toml' || true)
-          if [ -n "$SCAN_FILES" ]; then
-            echo "scan=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "scan=false" >> "$GITHUB_OUTPUT"
-          fi
-          DEPS_FILES=$(git diff --name-only "$BASE"..."$HEAD" -- 'pyproject.toml' || true)
-          if [ -n "$DEPS_FILES" ]; then
-            echo "deps=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "deps=false" >> "$GITHUB_OUTPUT"
-          fi
-          MCP_CATALOG_FILES=$(git diff --name-only "$BASE"..."$HEAD" -- \
-            'optional-mcps/**' \
-            'hermes_cli/mcp_catalog.py' || true)
-          if [ -n "$MCP_CATALOG_FILES" ]; then
-            echo "mcp_catalog=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "mcp_catalog=false" >> "$GITHUB_OUTPUT"
-          fi
-
   scan:
     name: Scan PR for critical supply chain risks
-    needs: changes
-    if: needs.changes.outputs.scan == 'true'
+    if: inputs.scan
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -111,7 +84,7 @@ jobs:
           fi
 
           # --- base64 decode + exec/eval on the same line (the litellm attack pattern) ---
-          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
+          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
           if [ -n "$B64_EXEC_HITS" ]; then
             FINDINGS="${FINDINGS}
           ### 🚨 CRITICAL: base64 decode + exec/eval combo
@@ -125,7 +98,7 @@ jobs:
           fi
 
           # --- subprocess with encoded/obfuscated command argument ---
-          PROC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
+          PROC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
           if [ -n "$PROC_HITS" ]; then
             FINDINGS="${FINDINGS}
           ### 🚨 CRITICAL: subprocess with encoded/obfuscated command
@@ -187,23 +160,9 @@ jobs:
           echo "::error::CRITICAL supply chain risk patterns detected in this PR. See the PR comment for details."
           exit 1
 
-  # Gate: reports success when scan was skipped (no relevant files changed).
-  # This ensures the required check always gets a status.
-  scan-gate:
-    name: Scan PR for critical supply chain risks
-    needs: changes
-    # always() so the gate still reports SUCCESS even if `changes` fails/is
-    # skipped — without it, a failed dependency would leave the required
-    # check unreported (i.e. "pending"), the exact failure mode this fixes.
-    if: always() && needs.changes.outputs.scan != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "No supply-chain-relevant files changed, skipping scan."
-
   dep-bounds:
     name: Check PyPI dependency upper bounds
-    needs: changes
-    if: needs.changes.outputs.deps == 'true'
+    if: inputs.deps
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -253,7 +212,7 @@ jobs:
           $(cat /tmp/unbounded.txt)
           \`\`\`
 
-          **Fix:** Add an upper bound, e.g. \`\"package>=1.2.0,<2\"\`
+          **Fix:** Add an upper bound, e.g. \`"package>=1.2.0,<2"\`
 
           ---
           *See PR #2810 and CONTRIBUTING.md for the full policy rationale.*"
@@ -266,23 +225,9 @@ jobs:
           echo "::error::PyPI dependencies without upper bounds detected. Add <next_major ceiling per CONTRIBUTING.md policy."
           exit 1
 
-  # Gate: reports success when dep-bounds was skipped (no pyproject.toml changed).
-  # This ensures the required check always gets a status.
-  dep-bounds-gate:
-    name: Check PyPI dependency upper bounds
-    needs: changes
-    # always() so the gate still reports SUCCESS even if `changes` fails/is
-    # skipped — without it, a failed dependency would leave the required
-    # check unreported (i.e. "pending"), the exact failure mode this fixes.
-    if: always() && needs.changes.outputs.deps != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "No pyproject.toml changes, skipping dependency bounds check."
-
   mcp-catalog-review:
     name: MCP catalog security review
-    needs: changes
-    if: needs.changes.outputs.mcp_catalog == 'true'
+    if: inputs.mcp_catalog
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -317,11 +262,3 @@ jobs:
           gh pr comment "$PR" --body "$BODY" || echo "::warning::Could not post PR comment (expected for fork PRs)"
           echo "::error::MCP catalog changes require the mcp-catalog-reviewed label."
           exit 1
-
-  mcp-catalog-review-gate:
-    name: MCP catalog security review
-    needs: changes
-    if: always() && needs.changes.outputs.mcp_catalog != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "No MCP catalog changes, skipping MCP catalog security review."

.github/workflows/tests.yml

@@ -1,21 +1,12 @@
 name: Tests
 
 on:
-  push:
-    branches: [main]
-    paths-ignore:
-      - "**/*.md"
-      - "docs/**"
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read
 
-# Cancel in-progress runs for the same PR/branch
+# Cancel in-progress runs for the same ref
 concurrency:
   group: tests-${{ github.ref }}
   cancel-in-progress: true
@@ -49,7 +40,7 @@ jobs:
           RG_VERSION=15.1.0
           RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
           RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
-          curl -sSfL -o "$RG_TARBALL" \
+          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
             "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
           echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
           tar -xzf "$RG_TARBALL"
@@ -78,7 +69,9 @@ jobs:
         # fails if the lock is out of sync with pyproject.toml), giving a
         # reproducible env. It also creates .venv itself, so no separate
         # `uv venv` step is needed.
-        run: uv sync --locked --python 3.11 --extra all --extra dev
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev
 
       - name: Minimize uv cache
         # Optimized for CI: prunes pre-built wheels that are cheap to
@@ -171,7 +164,7 @@ jobs:
           RG_VERSION=15.1.0
           RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
           RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
-          curl -sSfL -o "$RG_TARBALL" \
+          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
             "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
           echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
           tar -xzf "$RG_TARBALL"
@@ -200,7 +193,9 @@ jobs:
         # fails if the lock is out of sync with pyproject.toml), giving a
         # reproducible env. It also creates .venv itself, so no separate
         # `uv venv` step is needed.
-        run: uv sync --locked --python 3.11 --extra all --extra dev
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev
 
       - name: Minimize uv cache
         # Optimized for CI: prunes pre-built wheels that are cheap to

.github/workflows/typecheck.yml

@@ -2,13 +2,7 @@
 name: Typecheck
 
 on:
-  push:
-    branches: [main]
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 jobs:
   typecheck:
@@ -24,7 +18,14 @@ jobs:
         with:
           node-version: 22
           cache: npm
-      - run: npm ci
+      # --ignore-scripts: typecheck only needs the TS sources + type defs, not
+      # native builds. Skipping install scripts drops node-pty's node-gyp
+      # header fetch — the transient flake that killed this job pre-`tsc` — and
+      # is faster. retry covers the remaining registry blips.
+      - 
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci --ignore-scripts
       - run: npm run --prefix ${{ matrix.package }} typecheck
 
   # Production build of the desktop renderer. `typecheck` runs `tsc` only,
@@ -41,5 +42,10 @@ jobs:
         with:
           node-version: 22
           cache: npm
-      - run: npm ci
+      # Keep install scripts here: the production build may need node-pty's
+      # native binary. retry handles the transient install-time fetch flakes.
+      - 
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci
       - run: npm run --prefix apps/desktop build

.github/workflows/uv-lockfile-check.yml

@@ -44,25 +44,14 @@ name: uv.lock check
 # the same way.  Better to catch it here than after merge.
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - "pyproject.toml"
-      - "uv.lock"
-      - ".github/workflows/uv-lockfile-check.yml"
-
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read
 
 concurrency:
   group: uv-lockfile-check-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: true
 
 jobs:
   check:

scripts/ci/classify_changes.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Classify a PR's changed files into CI work lanes.
+
+Reads newline-separated changed paths on stdin and writes ``key=value``
+booleans (one per lane) to ``$GITHUB_OUTPUT`` and stdout. The
+``detect-changes`` composite action consumes them so steps gate on
+``if: steps.changes.outputs.<lane> == 'true'``.
+
+Lanes:
+
+* ``python``      — pytest / ruff / ty / footguns.
+* ``docker_meta`` — Dockerfiles etc.
+* ``frontend``    — TS typecheck matrix + desktop build.
+* ``site``        — Docusaurus + generated skill docs.
+* ``scan``        — supply-chain scan (Python files, .pth, setup hooks).
+* ``deps``        — pyproject.toml dependency bounds check.
+* ``mcp_catalog`` — bundled MCP catalog / installer review.
+
+Docker is not a lane — it builds on push-to-main and release only,
+never per-PR.
+
+Contract — *fail open, never closed*. We may run a lane we didn't need, but
+must never skip one a change could break:
+
+* An empty diff, or any ``.github/`` change, runs everything.
+* ``python`` is a denylist: skipped only when *every* file is provably prose
+  or a frontend-only package; an unrecognized path keeps it on.
+* ``skills/`` (incl. ``SKILL.md``) is python-relevant — the skill-doc tests
+  read that tree, so a doc-looking edit can still break Python.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_FRONTEND = ("ui-tui/", "web/", "apps/")  # TS typecheck-matrix packages
+_ROOT_NPM = {"package.json", "package-lock.json"}  # shifts every package's tree
+_DOCKER_META = ("docker/", ".hadolint.yml", "Dockerfile") # docker setup
+_SITE = ("website/", "skills/", "optional-skills/")  # docs site + skill pages
+# Prose/frontend trees that can't touch Python. skills/ is excluded on purpose.
+_PY_SKIP = ("docs/", "website/") + _FRONTEND
+
+# Supply-chain scan: files that can execute code at install/import time.
+_SCAN_EXTS = (".py", ".pth")
+_SCAN_FILES = {"setup.cfg", "pyproject.toml"}
+
+# MCP catalog files that require explicit security review.
+_MCP_CATALOG_PATHS = ("optional-mcps/",)
+_MCP_CATALOG_FILES = {"hermes_cli/mcp_catalog.py"}
+
+def _is_docs(p: str) -> bool:
+    if p.startswith(("skills/", "optional-skills/")):
+        return False
+    return p.endswith((".md", ".mdx")) or p.startswith("docs/") or p.startswith("LICENSE")
+
+
+def _py_irrelevant(p: str) -> bool:
+    return _is_docs(p) or p in _ROOT_NPM or p.startswith(_PY_SKIP) or p.startswith(_DOCKER_META)
+
+
+def _is_scan(p: str) -> bool:
+    return p.endswith(_SCAN_EXTS) or p in _SCAN_FILES
+
+
+def _is_mcp_catalog(p: str) -> bool:
+    return p.startswith(_MCP_CATALOG_PATHS) or p in _MCP_CATALOG_FILES
+
+
+def classify(files: list[str]) -> dict[str, bool]:
+    """Map changed paths to ``{lane: should_run}``."""
+    files = [f.strip() for f in files if f.strip()]
+    if not files or any(f.startswith(".github/") for f in files):
+        return dict.fromkeys(
+            ("python", "docker_meta", "frontend", "site", "scan", "deps", "mcp_catalog"), True
+        )
+    return {
+        "python": any(not _py_irrelevant(f) for f in files),
+        "docker_meta":  any(f.startswith(_DOCKER_META) for f in files),
+        "frontend": any(f.startswith(_FRONTEND) or f in _ROOT_NPM for f in files),
+        "site": any(f.startswith(_SITE) for f in files),
+        "scan": any(_is_scan(f) for f in files),
+        "deps": any(f == "pyproject.toml" for f in files),
+        "mcp_catalog": any(_is_mcp_catalog(f) for f in files),
+    }
+
+
+def main() -> int:
+    lanes = classify(sys.stdin.read().splitlines())
+    out = "\n".join(f"{k}={str(v).lower()}" for k, v in lanes.items())
+    if dest := os.environ.get("GITHUB_OUTPUT"):
+        with open(dest, "a", encoding="utf-8") as fh:
+            fh.write(out + "\n")
+    print(out)  # echo for local runs + CI step logs
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/ci/test_classify_changes.py

@@ -0,0 +1,85 @@
+"""Tests for scripts/ci/classify_changes.py.
+
+Check some common patterns of file modifications and the CI lanes they should run.
+We should always fail open. We may run a lane we didn't need, never skip one a
+change could have broken.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_PATH = Path(__file__).resolve().parents[2] / "scripts" / "ci" / "classify_changes.py"
+_spec = importlib.util.spec_from_file_location("classify_changes", _PATH)
+if _spec is None or _spec.loader is None:
+    raise ImportError("Failed to load classify_changes.py")
+_mod = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_mod)
+classify = _mod.classify
+
+ALL = {
+    "python": True,
+    "frontend": True,
+    "docker_meta": True,
+    "site": True,
+    "scan": True,
+    "deps": True,
+    "mcp_catalog": True,
+}
+
+
+def _lanes(python=False, frontend=False, site=False, scan=False, deps=False, mcp_catalog=False, docker_meta=False) -> dict[str, bool]:
+    return {
+        "python": python,
+        "frontend": frontend,
+        "docker_meta": docker_meta,
+        "site": site,
+        "scan": scan,
+        "deps": deps,
+        "mcp_catalog": mcp_catalog,
+    }
+
+
+CASES = {
+    "docs-only → nothing heavy": (["README.md", "docs/guide.md"], _lanes()),
+    "python source → python": (["run_agent.py"], _lanes(python=True, scan=True)),
+    "dep manifest → python": (["pyproject.toml"], _lanes(python=True, scan=True, deps=True)),
+    "uv.lock → python": (["uv.lock"], _lanes(python=True)),
+    "ts package → frontend": (["apps/desktop/src/app.tsx"], _lanes(frontend=True)),
+    "ui-tui → frontend": (["ui-tui/src/entry.ts"], _lanes(frontend=True)),
+    # Lockfile bump shifts every TS package's tree, but not the Python suite.
+    "root lockfile → frontend, not python": (["package-lock.json"], _lanes(frontend=True)),
+    "website → site": (["website/docs/intro.md"], _lanes(site=True)),
+    # SKILL.md reads like docs, but the skill-doc tests read skills/, so a
+    # skill edit must still run Python.
+    "skill md → python + site": (["skills/github/SKILL.md"], _lanes(python=True, site=True)),
+    "dockerfile → docker meta": (["Dockerfile"], _lanes(docker_meta=True)),
+    # Unknown top-level file keeps Python on rather than risk a silent skip.
+    "unknown toplevel → python": (["Makefile"], _lanes(python=True)),
+    "mixed docs+python → python": (["README.md", "agent/x.py"], _lanes(python=True, scan=True)),
+    "mixed docs+frontend → frontend": (["README.md", "apps/x.tsx"], _lanes(frontend=True)),
+    # Supply-chain lanes
+    ".pth file → scan": (["evil.pth"], _lanes(python=True, scan=True)),
+    "setup.py → scan": (["setup.py"], _lanes(python=True, scan=True)),
+    "mcp catalog manifest → mcp_catalog": (
+        ["optional-mcps/foo/manifest.yaml"],
+        _lanes(python=True, mcp_catalog=True),
+    ),
+    "mcp_catalog.py → mcp_catalog": (
+        ["hermes_cli/mcp_catalog.py"],
+        _lanes(python=True, scan=True, mcp_catalog=True),
+    ),
+    # Fail open: CI-config / empty / blank diffs run everything.
+    ".github change → all": ([".github/workflows/tests.yml"], ALL),
+    "action change → all": ([".github/actions/detect-changes/action.yml"], ALL),
+    "empty diff → all": ([], ALL),
+    "blank lines → all": (["", "  "], ALL),
+}
+
+
+@pytest.mark.parametrize("files,expected", CASES.values(), ids=CASES.keys())
+def test_classify(files, expected):
+    assert classify(files) == expected

website/docs/user-guide/features/computer-use.md

@@ -255,6 +255,19 @@ of screenshot context, not ~600K.
   drawing (Logic, Final Cut, some games) have sparse or empty AX trees.
   Fall back to pixel coordinates if the tree is empty — or skip the
   task entirely.
+- **Windows: elevated (admin) windows can't be driven from a normal
+  agent.** Windows UIPI (User Interface Privilege Isolation) enforces
+  integrity-level boundaries: a Medium-integrity process (the default
+  Hermes agent) cannot enumerate the UIA tree of, or inject mouse input
+  into, a window owned by a High-integrity (Administrator) process.
+  Symptom: `capture(mode='som')` returns 0 elements and `click(...)`
+  reports success while doing nothing, even though the screenshot
+  renders fine (GDI capture sits below the integrity check). Keyboard
+  events partially bypass UIPI, so Tab / Enter can still navigate an
+  elevated dialog. This is an OS constraint, not a cua-driver bug — it
+  affects every Windows automation stack. To drive elevated windows,
+  run the Hermes agent itself at High integrity (launch from an
+  elevated terminal); otherwise target non-elevated windows.
 - **Platform-specific deployment gotchas:**
   - **macOS** uses private SkyLight SPIs. Apple can change them in any
     OS update. Hermes warns when the installed cua-driver is older than