@htekdev/actions-debugger 1.0.115 → 1.0.117

package/errors/caching-artifacts/cache-key-windows-path-separator-never-matches.yml

@@ -0,0 +1,107 @@
+id: caching-artifacts-068
+title: '`actions/cache` key containing Windows backslash path separators never matches on restore — cache miss every run'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - windows
+  - path-separator
+  - backslash
+  - cache-miss
+  - cross-platform
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: 'i'
+  - regex: 'cache.*miss.*windows|windows.*cache.*miss'
+    flags: 'i'
+error_messages:
+  - 'Cache not found for input keys:'
+  - 'cache hit for key: false'
+root_cause: |
+  GitHub Actions cache keys are plain strings matched byte-for-byte. On Windows
+  runners, several common patterns produce cache keys containing backslashes (`\`):
+
+    1. Embedding ${{ runner.temp }} or ${{ github.workspace }} directly in the key:
+         key: ${{ runner.os }}-${{ runner.temp }}-${{ hashFiles('**/package-lock.json') }}
+       On Windows, runner.temp resolves to `D:\a\_temp` producing a key with `\`.
+
+    2. Using hashFiles() with backslash glob patterns:
+         key: ${{ hashFiles('**\node_modules\**') }}
+       hashFiles() on Windows sometimes receives backslash-escaped paths in its
+       argument, encoding them into the resulting hash string.
+
+    3. String concatenation with Windows path variables set in earlier steps:
+         TOOL_PATH: C:\hostedtoolcache\node\18\x64
+       When $TOOL_PATH is embedded in the cache key, the `\` chars are literal.
+
+  The cache service stores and retrieves keys as exact string matches. A cache
+  saved with key `npm-D:\a\_temp-abc123` is never found by a lookup for
+  `npm-D:/a/_temp-abc123` or by a lookup on a different run where the runner.temp
+  path differs.
+
+  On Linux/macOS runners, paths always use `/` so this issue is Windows-specific.
+  Cross-platform matrix workflows are especially affected: the Linux cache is found
+  on restore; the Windows cache is always missed.
+fix: |
+  Normalize all path separators to forward slashes before including in cache keys.
+
+  Option 1 — Avoid runner.temp and github.workspace in cache keys entirely.
+  Use runner.os and a fixed path pattern instead:
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+  Option 2 — If you must embed a path, normalize in a prior step:
+    - name: Set normalized cache path
+      shell: bash
+      run: echo "CACHE_PATH=$(echo '${{ runner.temp }}' | tr '\\' '/')" >> $GITHUB_ENV
+    Then:
+    key: ${{ runner.os }}-${{ env.CACHE_PATH }}-${{ hashFiles(...) }}
+
+  Option 3 — Always use forward-slash glob patterns in hashFiles():
+    key: ${{ hashFiles('**/package-lock.json') }}    # correct
+    # NOT: ${{ hashFiles('**\package-lock.json') }}  # Windows-style — avoid
+
+  Option 4 — Use a bash shell step to compute the key and store in GITHUB_ENV,
+  ensuring all path manipulation happens in a POSIX shell that normalizes separators.
+fix_code:
+  - language: yaml
+    label: 'Bad: runner.temp in cache key produces backslashes on Windows'
+    code: |
+      # ❌ runner.temp on Windows = "D:\a\_temp" — backslashes in key → never matches
+      - uses: actions/cache@v4
+        with:
+          path: ${{ runner.temp }}/cache
+          key: ${{ runner.os }}-${{ runner.temp }}-${{ hashFiles('**/lock.json') }}
+  - language: yaml
+    label: 'Good: use runner.os and a fixed path — no path variables in key'
+    code: |
+      # ✅ No Windows path separators in key
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+  - language: yaml
+    label: 'Good: normalize path separators with bash tr before embedding in key'
+    code: |
+      - name: Normalize cache path
+        shell: bash
+        run: |
+          NORM_PATH=$(echo '${{ runner.tool_cache }}' | tr '\\' '/')
+          echo "NORM_TOOL_CACHE=$NORM_PATH" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ runner.tool_cache }}
+          key: ${{ runner.os }}-tools-${{ env.NORM_TOOL_CACHE }}-${{ hashFiles('**/tool-versions') }}
+prevention:
+  - 'Never include runner.temp, runner.tool_cache, or github.workspace in cache keys — these resolve to OS-specific paths with backslashes on Windows'
+  - 'Always use runner.os (e.g., "Windows") as the OS discriminator in cross-platform cache keys, not path-based variables'
+  - 'Use forward-slash glob patterns in hashFiles() expressions on all platforms'
+  - 'When path variables must appear in a cache key, normalize separators to forward slashes in a bash step first and use the env variable'
+  - 'Test cache hit rate explicitly in CI by checking the cache-hit output of the restore step on Windows runners'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows'
+  - url: 'https://github.com/actions/cache/issues/671'
+    label: 'actions/cache#671: Cache key with Windows path separators causes cache miss'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables'
+    label: 'GitHub Docs: Default environment variables (runner.temp, etc.)'

package/errors/concurrency-timing/rerun-failed-jobs-bypasses-concurrency-group.yml

@@ -0,0 +1,89 @@
+id: concurrency-timing-054
+title: '"Re-run failed jobs" bypasses concurrency group — runs in parallel with a newly triggered run for the same group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - rerun
+  - re-run-failed-jobs
+  - parallel
+  - cancel-in-progress
+patterns:
+  - regex: 'Re-run failed jobs'
+    flags: 'i'
+  - regex: 'This run was automatically cancelled'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+root_cause: |
+  When a developer clicks "Re-run failed jobs" (as opposed to "Re-run all jobs"),
+  GitHub Actions does not evaluate the workflow's concurrency group before starting
+  the rerun. The rerun begins immediately and runs in parallel with any currently
+  in-progress or newly triggered run that occupies the same concurrency group.
+
+  This is distinct from "Re-run all jobs", which DOES re-trigger the concurrency
+  check and will cancel the currently in-progress run if cancel-in-progress is true,
+  or queue behind it if cancel-in-progress is false.
+
+  Common scenario:
+    1. A push triggers run A, which starts and partially fails.
+    2. A second push triggers run B for the same branch (same concurrency group).
+       Run B is queued or cancels run A depending on cancel-in-progress setting.
+    3. Developer hits "Re-run failed jobs" on run A.
+    4. Run A's rerun starts immediately — now run A (rerun) and run B are both
+       executing concurrently, violating the intent of the concurrency group.
+
+  Side effects:
+    - Two deploys to the same environment can run simultaneously.
+    - A self-hosted runner with a single slot gets double-booked.
+    - Race conditions between two concurrent jobs writing to the same artifact.
+
+  Root cause: GitHub's "Re-run failed jobs" path was implemented as a targeted job
+  restart that bypasses workflow-level orchestration including concurrency evaluation.
+  This behavior is tracked in actions/runner#2294 (open).
+fix: |
+  Option 1 — Use "Re-run all jobs" instead of "Re-run failed jobs" when the workflow
+  has a concurrency group. "Re-run all jobs" triggers a fresh run that participates
+  in concurrency evaluation normally.
+
+  Option 2 — Include github.run_attempt in the concurrency group key so each attempt
+  gets its own group slot, preventing cancellation loops during reruns while still
+  serializing independent triggers:
+    group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_attempt }}
+    cancel-in-progress: false
+
+  Option 3 — For deployment workflows, use environment protection rules as the
+  serialization mechanism instead of (or in addition to) concurrency groups. A
+  pending environment review gate serializes deployments even when concurrency is
+  bypassed.
+
+  Option 4 — Accept the behavior: if the failed jobs don't interact with shared
+  resources, concurrent partial reruns may be safe. Restrict "Re-run failed jobs" to
+  jobs that are idempotent and isolated.
+fix_code:
+  - language: yaml
+    label: 'Option A: include run_attempt in group key — each attempt gets its own slot'
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_attempt }}
+        cancel-in-progress: false
+  - language: yaml
+    label: 'Option B: environment protection to serialize deployments independent of concurrency'
+    code: |
+      jobs:
+        deploy:
+          environment: production   # Requires reviewer approval; serializes even without concurrency
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - 'Prefer "Re-run all jobs" over "Re-run failed jobs" when your workflow uses a concurrency group to prevent duplicate concurrent runs'
+  - 'Include ${{ github.run_attempt }} in the concurrency group key to give each attempt its own slot and avoid silent bypass'
+  - 'For deployment workflows with shared infrastructure, combine concurrency groups with environment protection rules for defense-in-depth serialization'
+  - 'Document in your workflow YAML that "Re-run failed jobs" bypasses concurrency to alert future maintainers'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://github.com/actions/runner/issues/2294'
+    label: 'actions/runner#2294: Re-run failed jobs bypasses concurrency group (open)'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs'
+    label: 'GitHub Docs: Re-running workflows and jobs'

package/errors/known-unsolved/empty-matrix-fromjson-workflow-failure-no-conditional-skip.yml

@@ -0,0 +1,108 @@
+id: known-unsolved-064
+title: 'No conditional matrix skip — an empty matrix from `fromJSON([])` always fails the workflow with a validation error'
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - dynamic-matrix
+  - fromJSON
+  - conditional
+  - strategy
+  - limitation
+patterns:
+  - regex: 'The strategy/matrix must contain at least one'
+    flags: 'i'
+  - regex: 'matrix must define at least one vector'
+    flags: 'i'
+  - regex: 'Error when evaluating .strategy. for job.*matrix.*empty'
+    flags: 'i'
+error_messages:
+  - 'The strategy/matrix must contain at least one vector'
+  - 'matrix must define at least one vector'
+  - 'Error when evaluating ''strategy'' for job'
+root_cause: |
+  GitHub Actions validates that a matrix strategy always produces at least one job.
+  When a prior step outputs an empty JSON array and the matrix job uses
+  `fromJSON(steps.generate.outputs.matrix)`, the workflow fails at plan time with
+  a validation error before any jobs run.
+
+  There is NO supported way to:
+    - Provide an `if:` condition on the matrix strategy to skip it entirely
+    - Use `strategy: if: ${{ condition }}` syntax (does not exist)
+    - Have a job run zero times when its matrix is empty
+
+  This is a fundamental platform limitation: matrix jobs must always expand to at
+  least one job instance. The validation runs before job execution, so even an `if:`
+  on the job itself does not help — the matrix must be non-empty regardless.
+
+  Common scenarios:
+    - CI that builds only changed packages: if no packages changed, the matrix
+      is empty and the entire workflow fails.
+    - Release workflows that conditionally matrix over artifacts: if nothing was
+      built, the matrix is empty.
+    - PR labeler workflows that matrix over affected services: a trivial change
+      affects no services, producing an empty list.
+
+  Note: yaml-syntax-008 covers the technical "fromJSON parse error" message. This
+  entry covers the LIMITATION: there is no native mechanism to conditionally skip
+  matrix jobs or provide a zero-matrix strategy.
+fix: |
+  Workaround 1 — Always include at least one sentinel/dummy entry and guard with if:
+    In the matrix-generating step, append a sentinel entry when the list is empty:
+      matrix=$(echo "$matrix" | jq 'if length == 0 then [{"skip":true}] else map(. + {"skip":false}) end')
+    Then in the job:
+      if: ${{ !matrix.skip }}
+
+  Workaround 2 — Use a separate check job with needs: to gate the matrix job:
+    Add an upstream job that outputs a boolean "has_work". The matrix job then uses
+    `needs: check` and reads `needs.check.outputs.has_work` in an `if:` condition.
+    This still requires the matrix to be non-empty (use sentinel), but the `if:`
+    prevents actual work from running.
+
+  Workaround 3 — Always include a no-op entry in the matrix output:
+    Ensure the matrix-generating script never outputs an empty array by always
+    appending a `{"target":"none"}` entry, then:
+      if: matrix.target != 'none'
+
+  None of these workarounds are elegant. This is a known limitation with no native
+  fix scheduled. Tracked in actions/runner#1502 (96+ reactions, open since 2021).
+fix_code:
+  - language: yaml
+    label: 'Workaround: inject sentinel entry when matrix is empty, skip in job if:'
+    code: |
+      jobs:
+        generate-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.set-matrix.outputs.matrix }}
+          steps:
+            - id: set-matrix
+              run: |
+                # Build your matrix list; inject sentinel when empty
+                matrix='[]'  # Replace with real generation logic
+                if [ "$(echo "$matrix" | jq 'length')" -eq 0 ]; then
+                  matrix='[{"target":"__skip__"}]'
+                fi
+                echo "matrix=$matrix" >> $GITHUB_OUTPUT
+
+        build:
+          needs: generate-matrix
+          if: ${{ fromJSON(needs.generate-matrix.outputs.matrix)[0].target != '__skip__' }}
+          strategy:
+            matrix:
+              include: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building ${{ matrix.target }}"
+prevention:
+  - 'Never pass a potentially empty array directly to fromJSON() in a matrix strategy — always guard with a sentinel entry'
+  - 'Add an upstream check job that validates matrix size before the matrix job runs'
+  - 'Document the sentinel pattern in your workflow so future maintainers understand why a dummy entry exists'
+  - 'Vote/watch actions/runner#1502 for native conditional matrix support'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow'
+    label: 'GitHub Docs: Running variations of jobs in a workflow (matrix)'
+  - url: 'https://github.com/actions/runner/issues/1502'
+    label: 'actions/runner#1502: Support for empty matrix (96+ reactions, open)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix'
+    label: 'GitHub Docs: jobs.<job_id>.strategy.matrix'

package/errors/runner-environment/arc-ephemeral-runner-oom-kill-session-conflict.yml

@@ -0,0 +1,129 @@
+id: runner-environment-203
+title: 'ARC EphemeralRunner Stuck in Running State After OOM Kill — Scale Set Blocked'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - actions-runner-controller
+  - ephemeral-runner
+  - oomkill
+  - kubernetes
+  - scale-set
+  - session-conflict
+  - stuck
+  - self-hosted
+patterns:
+  - regex: 'RunnerScaleSetSessionConflictException'
+    flags: 'i'
+  - regex: 'TaskAgentSessionConflictException'
+    flags: 'i'
+  - regex: 'A session for this runner already exists'
+    flags: 'i'
+  - regex: 'Runner connect error: Error: Conflict\. Retrying until reconnected'
+    flags: 'i'
+error_messages:
+  - 'RunnerScaleSetSessionConflictException: there is already an active session'
+  - 'TaskAgentSessionConflictException: Error: Conflict'
+  - 'A session for this runner already exists.'
+  - '2026-XX-XX HH:MM:SSZ: Runner connect error: Error: Conflict. Retrying until reconnected.'
+root_cause: |
+  When an ARC (Actions Runner Controller) ephemeral runner pod is OOM-killed by the
+  Kubernetes kubelet (memory limit exceeded), the pod terminates abruptly without going
+  through the runner's graceful shutdown path. The runner never sends a "job completed" or
+  "runner offline" signal to the GitHub broker.
+
+  As a result:
+  1. The EphemeralRunner custom resource stays in phase `Running` indefinitely.
+  2. The ARC scale-set controller still counts the dead runner as "in use", so it does not
+     spin up a replacement pod to service the next queued job.
+  3. New jobs remain stuck at "Waiting for a runner to pick up this job..." until the
+     stale EphemeralRunner CR is manually deleted.
+
+  When ARC tries to restart the runner (either via a controller health check or manually),
+  the new runner pod connects to the GitHub broker using the same JIT token/session, and
+  the broker responds HTTP 409 Conflict because the old session is still registered:
+
+    TaskAgentSessionConflictException: Error: Conflict
+    A session for this runner already exists.
+    Runner connect error: Error: Conflict. Retrying until reconnected.
+
+  The runner retries every 30 seconds. After the broker's session lease expires (~2-3 min
+  in most cases), the conflict resolves and the runner connects — but the session timeout
+  window varies and can leave the scale set blocked for longer periods.
+
+  Versions affected:
+  - Reproducible across ARC v0.9.x - v0.12.x; partial mitigation added in ARC v0.12.0
+    (stale EphemeralRunner detection), but OOM kills on active runners can still bypass it.
+  - Frequently triggered by Vitest --coverage, Jest with large test suites, or any
+    memory-intensive build tool running without memory limits in the runner container.
+fix: |
+  Immediate recovery: delete the stuck EphemeralRunner CR to release the scale-set slot:
+
+    kubectl delete ephemeralrunner -n <namespace> <runner-name>
+
+  After deletion, ARC will spin up a new runner pod and pick up the queued job.
+
+  Root fix (prevent recurrence):
+  1. Set memory limits on runner containers that match actual job requirements with headroom.
+  2. Add workflow-level `timeout-minutes:` to ensure jobs terminate and release the runner
+     if they run too long.
+  3. Upgrade ARC to v0.12.0+ for improved stale EphemeralRunner detection.
+  4. Configure `terminationGracePeriodSeconds: 90` (or longer) on runner pods to give the
+     runner process time to deregister gracefully before the kubelet force-kills it.
+fix_code:
+  - language: yaml
+    label: 'Set memory limits and timeout on runner pods to prevent OOM kills'
+    code: |
+      # In your HelmRelease / values.yaml for actions-runner-controller
+      githubConfigUrl: "https://github.com/your-org/your-repo"
+      maxRunners: 4
+      minRunners: 0
+      template:
+        spec:
+          terminationGracePeriodSeconds: 90
+          containers:
+            - name: runner
+              image: ghcr.io/actions/actions-runner:latest
+              resources:
+                requests:
+                  memory: "2Gi"
+                  cpu: "500m"
+                limits:
+                  memory: "4Gi"   # Set appropriate limit; OOM kill occurs when exceeded
+                  cpu: "2"
+  - language: yaml
+    label: 'Add workflow timeout to guarantee runner release even on hang'
+    code: |
+      jobs:
+        test:
+          runs-on: arc-runner-set
+          timeout-minutes: 30   # Runner is released after 30 min even if job hangs
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test -- --coverage
+  - language: yaml
+    label: 'Manual recovery: delete stuck EphemeralRunner CR'
+    code: |
+      # List stuck EphemeralRunners
+      kubectl get ephemeralrunner -n arc-systems
+
+      # Delete the stuck one (ARC will create a new pod automatically)
+      kubectl delete ephemeralrunner -n arc-systems <stuck-runner-name>
+
+      # Alternatively, delete all stuck runners in a namespace
+      kubectl delete ephemeralrunner -n arc-systems --field-selector='status.phase=Running'
+prevention:
+  - 'Always set memory limits on ARC runner containers; without limits, a single job can consume all node memory and OOM-kill other runners.'
+  - 'Set timeout-minutes: at the job level for all ARC-backed workflows to guarantee the runner is eventually released.'
+  - 'Upgrade ARC to v0.12.0+ for automatic stale EphemeralRunner cleanup.'
+  - 'Monitor EphemeralRunner phase distribution; a growing count of Running CRs with no corresponding pods is a leading indicator of this issue.'
+  - 'Add terminationGracePeriodSeconds: 90+ to runner pod templates so gradual shutdown signals have time to deregister the runner.'
+docs:
+  - url: 'https://github.com/actions/actions-runner-controller/issues/4155'
+    label: 'EphemeralRunner and its pods left stuck Running after runner OOMKILL (15 reactions)'
+  - url: 'https://github.com/actions/actions-runner-controller/issues/3922'
+    label: 'Scaleset controllers stuck with RunnerScaleSetSessionConflictException (12 reactions)'
+  - url: 'https://github.com/actions/runner/issues/4312'
+    label: 'Self-hosted runner gets stuck in active state, blocking queued jobs across multiple repositories'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller'
+    label: 'Managing self-hosted runners with Actions Runner Controller'

package/errors/runner-environment/checkout-v603-hash-algorithm-api-rate-limiting.yml

@@ -0,0 +1,100 @@
+id: runner-environment-206
+title: 'actions/checkout v6.0.3 regression — new /hash-algorithm API call on every checkout exhausts rate limits in high-volume orgs'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - rate-limit
+  - api-rate-limit
+  - v6
+  - PAT
+  - regression
+  - hash-algorithm
+patterns:
+  - regex: 'API rate limit exceeded'
+    flags: 'i'
+  - regex: 'You have exceeded a secondary rate limit'
+    flags: 'i'
+  - regex: 'HttpError.*API rate limit exceeded'
+    flags: 'i'
+  - regex: 'Rate limit.*exceeded.*403'
+    flags: 'i'
+error_messages:
+  - 'Error: HttpError: API rate limit exceeded for user ID'
+  - 'You have exceeded a secondary rate limit and have been temporarily blocked from content creation'
+  - 'remote: Repository not found.'
+  - 'fatal: repository ''https://github.com/owner/repo/'' not found'
+root_cause: |
+  actions/checkout v6.0.3 (released June 2, 2026, commit 1cce339) introduced a new
+  REST API call to GET /repos/{owner}/{repo}/hash-algorithm on every checkout operation
+  to determine the repository's object hashing algorithm.
+
+  In organizations with high-concurrency workflows, this additional API call multiplies
+  rate-limit consumption significantly. A matrix build with 30 parallel jobs each running
+  checkout makes 30 additional API calls per push event. At the per-user rate limit of
+  5,000 requests/hour, large orgs using PATs (Personal Access Tokens) for cross-repo
+  checkout quickly exhaust their quota across many concurrent pipelines.
+
+  When the /hash-algorithm endpoint returns HTTP 403 (rate limited), the checkout action
+  may interpret the 403 as a resource-not-found condition, producing misleading errors
+  such as "remote: Repository not found" that mask the true rate-limit cause.
+
+  GITHUB_TOKEN is not affected in the same way because it carries per-repository rate
+  limits (15,000 requests/hour for Actions) rather than per-user limits.
+  Source: actions/checkout#2450.
+fix: |
+  Immediate fix — pin to actions/checkout@v6.0.2 until the upstream regression is
+  addressed:
+    uses: actions/checkout@v6.0.2
+
+  Use GITHUB_TOKEN instead of PAT where possible:
+  GITHUB_TOKEN rate limits (15,000 req/hr for GitHub Actions) are scoped per
+  repository and do not aggregate across your organization's other workflows.
+  Reserve PATs for cross-repo or cross-org checkouts only.
+
+  Reduce parallel checkout volume:
+  Add fetch-depth: 1 and/or sparse-checkout to minimize the API surface area
+  per checkout call, reducing the number of API requests triggered per job.
+
+  Monitor actions/checkout#2450 for the upstream fix (caching the hash-algorithm
+  result within a workflow run, or making the call conditional).
+fix_code:
+  - language: yaml
+    label: 'Pin to v6.0.2 to avoid the regression until upstream fix is released'
+    code: |
+      - uses: actions/checkout@v6.0.2
+        with:
+          # Prefer GITHUB_TOKEN over a PAT to use per-repo rate limits
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 1         # Shallow fetch reduces ancillary API calls
+  - language: yaml
+    label: 'Cross-repo checkout — use dedicated PAT only where necessary, pin version'
+    code: |
+      - uses: actions/checkout@v6.0.2
+        with:
+          repository: org/other-repo
+          token: ${{ secrets.CROSS_REPO_PAT }}   # PAT required here; rate-limited per user
+          fetch-depth: 1
+  - language: yaml
+    label: 'Monitor rate limit headers in a preflight step (diagnostic aid)'
+    code: |
+      - name: Check remaining GitHub API rate limit
+        run: |
+          remaining=$(curl -s -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+            https://api.github.com/rate_limit | jq '.rate.remaining')
+          echo "Remaining API calls: $remaining"
+          if (( remaining < 500 )); then
+            echo "::warning::Low API rate limit — $remaining calls remaining"
+          fi
+prevention:
+  - 'Pin actions/checkout to a specific patch version (e.g., @v6.0.2) in high-volume orgs — patch updates can introduce API regressions like this one'
+  - 'Prefer GITHUB_TOKEN over org-wide PATs for checkout; GITHUB_TOKEN rate limits are per-repository and isolated from other workflows'
+  - 'Monitor your org REST API usage under Settings > Insights > API Requests to detect unexpected call spikes from action updates before they hit production'
+  - 'Add a rate-limit check step to long-running or high-parallelism pipelines to catch exhaustion before it causes misleading errors'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2450'
+    label: 'actions/checkout#2450: New /hash-algorithm API call causing rate limiting failures in v6.0.3'
+  - url: 'https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api'
+    label: 'GitHub Docs: Rate limits for the REST API'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Docs: GITHUB_TOKEN permissions and rate limits'

package/errors/runner-environment/macos-26-homebrew-python313-removed-stdlib-modules.yml

@@ -0,0 +1,113 @@
+id: runner-environment-201
+title: 'macOS 26 Homebrew python@3 ships Python 3.13 — removed stdlib modules (cgi, imghdr, aifc, telnetlib) cause ModuleNotFoundError'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-26
+  - python
+  - homebrew
+  - stdlib
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: 'ModuleNotFoundError: No module named ''(cgi|imghdr|aifc|chunk|nntplib|telnetlib|uu|xdrlib|sndhdr|sunau|mailcap|msilib|pipes|crypt|spwd|ossaudiodev)'''
+    flags: 'i'
+  - regex: 'ImportError.*No module named.*cgi|No module named.*imghdr|No module named.*telnetlib'
+    flags: 'i'
+  - regex: 'python.*3\.13.*deprecated.*module|removed.*python.*3\.13'
+    flags: 'i'
+error_messages:
+  - 'ModuleNotFoundError: No module named ''cgi'''
+  - 'ModuleNotFoundError: No module named ''imghdr'''
+  - 'ModuleNotFoundError: No module named ''aifc'''
+  - 'ModuleNotFoundError: No module named ''telnetlib'''
+  - 'ModuleNotFoundError: No module named ''chunk'''
+  - 'ModuleNotFoundError: No module named ''nntplib'''
+root_cause: |
+  macOS 26 runner images ship Homebrew python@3 pointing to Python 3.13.x. Python
+  3.13 removed the following stdlib modules that were deprecated since Python 3.11:
+
+    cgi, cgitb, aifc, chunk, crypt, imghdr, mailcap, msilib (Windows only),
+    nntplib, ossaudiodev, pipes, sndhdr, spwd, sunau, telnetlib, uu, xdrlib
+
+  Workflows that call bare python3 (resolved to Homebrew Python 3.13 on macOS 26)
+  and import any of these modules fail with ModuleNotFoundError at runtime.
+
+  This affects:
+  - Scripts using cgi or cgitb for HTTP form parsing
+  - Image-type detection using imghdr (commonly used with Pillow-based workflows)
+  - Legacy FTP/NNTP clients using nntplib or telnetlib
+  - Audio file handling using aifc, sunau, or sndhdr
+
+  Workflows that previously ran on macos-14 or macos-15 (Homebrew Python 3.11/3.12)
+  are affected when the job label is macos-26 or when macos-latest migrates to
+  macOS 26. The failure is not immediately obvious because the error occurs at
+  import time inside Python, not at the runner level, and the runner step exits
+  with a non-zero code that may be mistaken for a test failure rather than an
+  environment regression.
+
+  Note: actions/setup-python@v5+ with an explicit python-version is unaffected —
+  this issue only affects scripts that rely on the system/Homebrew python3 binary.
+fix: |
+  Option 1 (recommended) — Pin Python with actions/setup-python:
+    Always use actions/setup-python with an explicit version to get the exact
+    Python version your code requires. This bypasses the Homebrew python@3 symlink.
+
+  Option 2 — Replace removed modules with modern equivalents:
+    - cgi        → urllib.parse + email.parser (or the 3rd-party 'cgi' backport)
+    - imghdr     → imghdr is available as the 3rd-party 'imghdr' backport on PyPI,
+                   or use python-magic / filetype for image detection
+    - telnetlib  → use telnetlib3 (PyPI) or asyncio-based Telnet
+    - aifc/sunau → use soundfile or wave for audio I/O
+
+  Option 3 — Pin Homebrew Python to 3.12 on macos-26 (temporary):
+    brew install python@3.12
+    brew link python@3.12 --force
+    echo "/usr/local/opt/python@3.12/bin" >> $GITHUB_PATH
+fix_code:
+  - language: yaml
+    label: 'Fix: pin Python version with actions/setup-python to avoid Homebrew python@3'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'   # pins to 3.12; immune to Homebrew python@3 upgrade
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run script
+        run: python script.py   # uses setup-python's 3.12, not Homebrew 3.13
+  - language: yaml
+    label: 'Fix: install removed modules from PyPI backports'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install backported removed modules
+        run: |
+          pip install imghdr       # PyPI backport of imghdr for Python 3.13+
+          # pip install telnetlib3 # if using Telnet
+      - name: Run script
+        run: python script.py
+  - language: yaml
+    label: 'Temporary: install and use python@3.12 from Homebrew on macos-26'
+    code: |
+      - name: Pin Homebrew Python to 3.12
+        run: |
+          brew install python@3.12
+          echo "/usr/local/opt/python@3.12/libexec/bin" >> $GITHUB_PATH
+      - name: Verify Python version
+        run: python3 --version   # should print Python 3.12.x
+prevention:
+  - 'Always use actions/setup-python with an explicit version — never rely on bare python3 pointing to Homebrew python@3'
+  - 'Audit scripts for imports of modules removed in Python 3.13: cgi, imghdr, aifc, telnetlib, nntplib, chunk, uu'
+  - 'Run pyupgrade --py313-plus locally before the macos-26 migration to catch deprecated imports'
+  - 'Add python --version to diagnostic steps to catch unexpected Python version changes early'
+docs:
+  - url: 'https://docs.python.org/3/whatsnew/3.13.html#removed-modules'
+    label: 'Python 3.13: Removed modules (official docs)'
+  - url: 'https://peps.python.org/pep-0594/'
+    label: 'PEP 594: Removing dead batteries from the standard library'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python: Pin a specific Python version'

package/errors/runner-environment/macos-26-openssl3-legacy-cipher-p12-import-failure.yml

@@ -0,0 +1,102 @@
+id: runner-environment-200
+title: 'macOS 26 OpenSSL 3.x rejects legacy RC2 ciphers — p12 certificate import fails with inner_evp_generic_fetch unsupported'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-26
+  - openssl
+  - code-signing
+  - certificate
+  - ios
+  - legacy-cipher
+patterns:
+  - regex: 'inner_evp_generic_fetch:unsupported'
+    flags: 'i'
+  - regex: 'Algorithm \(RC2-\d+-CBC.*\)'
+    flags: 'i'
+  - regex: 'Could not find certificate from.*stdin|Could not parse.*certificate'
+    flags: 'i'
+  - regex: 'openssl.*failed with return code:\s*1'
+    flags: 'i'
+error_messages:
+  - '40CBBC50F87F0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:crypto/evp/evp_fetch.c:355:Global default library context, Algorithm (RC2-40-CBC : 0), Properties ()'
+  - 'Could not find certificate from <stdin>'
+  - '##[error]Error: /usr/local/bin/openssl failed with return code: 1'
+  - '##[warning]Error parsing certificate. This might be caused by an unsupported algorithm. If you''re using old certificate with a new OpenSSL version try to set -legacy flag in opensslPkcsArgs input.'
+root_cause: |
+  macOS 26 runner images ship OpenSSL 3.x (OpenSSL 3.6.x as of runner-images macOS 26
+  release notes). OpenSSL 3.x removed RC2-40-CBC, RC2-64-CBC, and RC2-128-CBC from
+  the default provider. These legacy ciphers were commonly used to encrypt PKCS#12
+  certificate bundles generated by macOS Keychain Access, Fastlane cert, older CI
+  pipelines, or Keychain import/export tools shipped before 2020.
+
+  When a workflow installs a p12 certificate using openssl pkcs12 (directly or via
+  apple-actions/import-codesign-certs@v1/v2), OpenSSL 3.x cannot decrypt the legacy
+  bundle and emits:
+
+    error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:
+    ...Algorithm (RC2-40-CBC : 0), Properties ()
+
+  followed by "Could not find certificate from <stdin>" and openssl exit code 1.
+
+  The code-signing step silently skips certificate import, causing downstream
+  codesign, xcodebuild archive, or notarytool steps to fail with "no identity found"
+  or "identity not in keychain" errors.
+
+  Workflows that ran successfully on macos-14 (OpenSSL 1.1.x) or macos-15
+  (OpenSSL 3.3.x with legacy provider enabled) may start failing when the job
+  label is macos-26 or when macos-latest migrates to macOS 26.
+fix: |
+  Option 1 (quickest) — Pass opensslPkcsArgs: -legacy to apple-actions/import-codesign-certs:
+    The -legacy flag activates OpenSSL's legacy provider which re-enables RC2 and
+    other deprecated algorithms. Supported in apple-actions/import-codesign-certs v2+.
+
+  Option 2 (permanent) — Re-encode the p12 with a modern cipher on your local machine
+  before uploading to GitHub Secrets:
+    openssl pkcs12 -in legacy.p12 -out certs.pem -nodes -passin pass:OLDPASSWORD
+    openssl pkcs12 -export -in certs.pem -out modern.p12 -passout pass:NEWPASSWORD \
+      -keypbe aes-256-cbc -certpbe aes-256-cbc -macalg sha256
+    base64 -w 0 modern.p12 > modern_b64.txt
+    # Upload content of modern_b64.txt as the new GitHub secret value
+
+  Option 3 — Regenerate certificates with modern tooling:
+    Use Fastlane match (>= 3.x) or Xcode 26 certificate export; both default to
+    AES-256-CBC which OpenSSL 3.x supports without -legacy.
+fix_code:
+  - language: yaml
+    label: 'Fix: pass opensslPkcsArgs: -legacy (apple-actions/import-codesign-certs)'
+    code: |
+      - uses: apple-actions/import-codesign-certs@v3
+        with:
+          p12-file-base64: ${{ secrets.IOS_DISTRIBUTION_P12 }}
+          p12-password: ${{ secrets.IOS_DISTRIBUTION_P12_PASSWORD }}
+          opensslPkcsArgs: -legacy   # required on macOS 26 / OpenSSL 3.x for RC2-encrypted p12
+  - language: yaml
+    label: 'Long-term fix: re-encode p12 with AES-256-CBC before updating the secret'
+    code: |
+      # Run these commands locally (not in CI) to produce a modern p12:
+      #
+      # openssl pkcs12 -in legacy.p12 -out certs.pem -nodes -passin pass:$OLD_PASS \
+      #   -legacy                          # may need -legacy on your local OpenSSL 3.x too
+      # openssl pkcs12 -export \
+      #   -in certs.pem -out modern.p12 \
+      #   -passout pass:$NEW_PASS \
+      #   -keypbe aes-256-cbc \
+      #   -certpbe aes-256-cbc \
+      #   -macalg sha256
+      # base64 -w 0 modern.p12 | pbcopy   # paste into GitHub Secrets
+      #
+      # After updating the secret, remove the opensslPkcsArgs: -legacy workaround.
+prevention:
+  - 'Re-encode all p12 certificate bundles with AES-256-CBC before migrating to macos-26'
+  - 'Audit p12 cipher with: openssl pkcs12 -in cert.p12 -info -noout -passin pass:X 2>&1 | grep -i cipher'
+  - 'Pin macos-15 temporarily as a fallback while re-encoding certificates'
+  - 'Test certificate import on macos-26 runners before macos-latest label migration completes'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/10934'
+    label: 'GitHub runner-images #10934: Intermittent SSL issue loading iOS certificates on macOS 26'
+  - url: 'https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html'
+    label: 'OpenSSL 3.x legacy provider documentation'
+  - url: 'https://github.com/apple-actions/import-codesign-certs'
+    label: 'apple-actions/import-codesign-certs: opensslPkcsArgs input'

package/errors/runner-environment/macos-self-hosted-listener-aad-ghost-busy-stall.yml

@@ -0,0 +1,126 @@
+id: runner-environment-205
+title: 'macOS self-hosted Runner.Listener silently stalls after AAD credential-refresh — ghost-busy state blocks queue'
+category: runner-environment
+severity: silent-failure
+tags:
+  - self-hosted
+  - macos
+  - apple-silicon
+  - listener
+  - aad
+  - ghost-busy
+  - broker-reconnect
+  - credential-refresh
+patterns:
+  - regex: 'AAD Correlation ID for this token request:\s*Unknown'
+    flags: 'i'
+  - regex: 'RSAFileKeyManager.*Loading RSA key parameters from file.*credentials_rsaparams'
+    flags: 'i'
+  - regex: 'GitHubActionsService.*AAD Correlation ID.*Unknown'
+    flags: 'i'
+error_messages:
+  - '[INFO RSAFileKeyManager] Loading RSA key parameters from file .../.credentials_rsaparams'
+  - '[INFO GitHubActionsService] AAD Correlation ID for this token request: Unknown'
+root_cause: |
+  On long-lived self-hosted macOS runners (v2.334.0+, Apple Silicon), the
+  Runner.Listener process can permanently stall after an AAD (Azure Active Directory)
+  credential-refresh event coincides with a broker session disconnect.
+
+  Normal broker long-poll timeouts produce "SocketException (89): Operation canceled"
+  entries and the listener successfully reconnects. However, when a broker disconnect
+  occurs at the same time as an AAD credential refresh, the listener logs its final
+  diagnostic sequence and then goes permanently silent:
+    [INFO RSAFileKeyManager] Loading RSA key parameters from file .../.credentials_rsaparams
+    [INFO GitHubActionsService] AAD Correlation ID for this token request: Unknown
+
+  After these lines, the main thread parks in pthread_cond_wait with no further diag
+  log output and no TCP ESTABLISHED connection to the broker. The OS process stays alive
+  (visible in ps/Activity Monitor/launchctl list), so launchd does not restart it. The
+  broker-side agent state continues to show the runner as "busy" from its last completed
+  job, stalling all subsequent queued jobs behind the phantom runner until an external
+  restart clears the state.
+
+  The trigger requires: runner lifetime longer than several hours (so a credential
+  refresh occurs), plus a broker disconnect at or immediately after the refresh boundary.
+  Observed simultaneously affecting all 4 of 4 macOS ARM64 runners on a single host
+  within a 32-minute window, causing a 4-hour queue stall. Source: actions/runner#4446.
+fix: |
+  No platform-side fix available as of June 2026 (open issue).
+
+  Workaround — implement an out-of-band watchdog script/cron that:
+  1. Confirms the Runner.Listener PID has an ESTABLISHED TCP socket to the broker
+     (check with `lsof -p <pid> -i TCP | grep ESTABLISHED`)
+  2. Confirms the most recent entry in _diag/Runner_*.log is less than N minutes old
+     (e.g., 10 minutes)
+  3. If both checks fail, restarts the runner service:
+     - macOS (launchd):
+         launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/actions.runner.<owner-repo>.<name>.plist
+         sleep 5
+         launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/actions.runner.<owner-repo>.<name>.plist
+     - Linux (systemd):
+         systemctl --user restart actions.runner.<owner-repo>.<name>.service
+  4. Optionally clear the broker-side ghost-busy state via REST API:
+         curl -X DELETE \
+           -H "Authorization: Bearer $GH_TOKEN" \
+           "https://api.github.com/repos/<owner>/<repo>/actions/runners/<runner_id>"
+     This forces re-registration and clears the stale busy state immediately.
+
+  Long-term: run macOS runners as ephemeral (--once) with a process supervisor
+  that restarts after each completed job, eliminating the multi-hour lifetime
+  that triggers the credential-refresh race.
+fix_code:
+  - language: yaml
+    label: 'Watchdog workflow on separate runner — detect and restart stalled listeners'
+    code: |
+      # Separate monitoring workflow on a non-affected runner
+      # Runs every 15 minutes via cron
+      on:
+        schedule:
+          - cron: '*/15 * * * *'
+      jobs:
+        watchdog:
+          runs-on: ubuntu-latest   # Use a separate hosted runner for the watchdog
+          steps:
+            - name: Check and restart stalled macOS listeners
+              env:
+                GH_TOKEN: ${{ secrets.RUNNER_MGMT_PAT }}
+              run: |
+                # List all self-hosted runners and check for stuck-busy ones
+                gh api /repos/${{ github.repository }}/actions/runners \
+                  --jq '.runners[] | select(.status=="online" and .busy==true) | .id' \
+                  | while read runner_id; do
+                    echo "Runner $runner_id showing busy — may need investigation"
+                    # Add custom liveness check here (SSH to host, check log freshness)
+                  done
+  - language: bash
+    label: 'Shell watchdog — check listener log freshness and restart via launchctl'
+    code: |
+      #!/bin/bash
+      # Run on the macOS runner host via cron every 10 minutes
+      RUNNER_LABEL="owner-repo-runner-name"
+      PLIST="$HOME/Library/LaunchAgents/actions.runner.${RUNNER_LABEL}.plist"
+      DIAG_DIR="$HOME/actions-runner/_diag"
+      STALE_MINUTES=10
+
+      latest_log=$(ls -t "${DIAG_DIR}/Runner_"*.log 2>/dev/null | head -1)
+      if [[ -z "$latest_log" ]]; then exit 0; fi
+
+      age_minutes=$(( ($(date +%s) - $(stat -f %m "$latest_log")) / 60 ))
+      if (( age_minutes > STALE_MINUTES )); then
+        echo "Runner diag log stale for ${age_minutes}min — restarting..."
+        launchctl bootout "gui/$(id -u)" "$PLIST" 2>/dev/null
+        sleep 5
+        launchctl bootstrap "gui/$(id -u)" "$PLIST"
+      fi
+prevention:
+  - 'Run macOS self-hosted runners as ephemeral (--once) with a process supervisor — this eliminates the multi-hour lifetime needed to trigger the credential-refresh race condition'
+  - 'Implement a log-freshness watchdog that monitors _diag/Runner_*.log modification time and restarts the launchd service if no new entries appear for > 10 minutes'
+  - 'Monitor GET /repos/{owner}/{repo}/actions/runners and alert on runners with busy=true for longer than your longest expected job duration'
+  - 'Limit runner lifetime with a cron-triggered scheduled restart between jobs (e.g., nightly) to reduce the window where credential refresh coincides with a broker disconnect'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4446'
+    label: 'actions/runner#4446: Listener silently exits broker-reconnect loop after AAD credential-refresh (ghost-busy)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners'
+    label: 'GitHub Docs: Monitoring and troubleshooting self-hosted runners'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners'
+    label: 'GitHub REST API: Self-hosted runners'

package/errors/runner-environment/runner-v2334-action-download-repeated-case-sensitivity.yml

@@ -0,0 +1,100 @@
+id: runner-environment-202
+title: 'Runner v2.334.0 "Download action repository" repeats for same action when references use different letter casing'
+category: runner-environment
+severity: warning
+tags:
+  - runner
+  - action-resolution
+  - performance
+  - v2.334
+  - composite-actions
+  - case-sensitivity
+patterns:
+  - regex: 'Download action repository.*already been downloaded'
+    flags: 'i'
+  - regex: 'Download action repository.*\d+\.\d+s.*Download action repository'
+    flags: 'i'
+  - regex: 'Resolving action.*batching.*dedup.*failed|action.*resolution.*duplicate.*case'
+    flags: 'i'
+error_messages:
+  - 'Download action repository ''actions/checkout@v4'' (SHA:abc123...) 18.35s'
+  - 'Download action repository ''Actions/Checkout@v4'' (SHA:abc123...) 19.12s'
+  - 'Download action repository ''ACTIONS/CHECKOUT@v4'' (SHA:abc123...) 17.88s'
+root_cause: |
+  Runner v2.334.0 introduced "batch and deduplicate action resolution across composite
+  depths" to speed up jobs with many actions. The deduplication logic uses a
+  case-sensitive equality check on the action reference string (owner/repo@ref). When
+  the same action is referenced with different capitalizations — for example,
+  actions/checkout@v4 in one workflow step and Actions/Checkout@v4 inside a composite
+  action — the deduplication logic treats them as distinct actions and downloads both.
+
+  This regression is tracked in actions/runner#3731. Each duplicate download takes
+  15-20 seconds, which multiplies across all case-variant references in a job. In
+  workflows with many composite actions or large action dependency trees, this can add
+  several minutes of silent overhead.
+
+  The issue does not cause a build failure — the downloads resolve to the same SHA
+  and the action runs once. The cost is purely in duplicate network traffic, API
+  calls, and elapsed time. Repeated downloads also count against GitHub API rate
+  limits for private runners or GHES installations.
+
+  Most commonly observed when:
+  - Composite actions use uppercase or title-case owners in their uses: fields
+  - Third-party actions internally call actions/core or actions/toolcache with
+    inconsistent casing
+  - Workflows mix community-contributed composite actions with differing conventions
+fix: |
+  Canonicalize all action references to lowercase owner/repo throughout your
+  workflow files and composite action.yml files. GitHub API lookups are
+  case-insensitive, so actions/checkout and Actions/Checkout resolve identically,
+  but the v2.334.0 deduplication cache is case-sensitive.
+
+  After fixing, run the job again to confirm "Download action repository" appears
+  only once per unique action in the logs.
+
+  A fix for the runner-side deduplication (case-insensitive cache key) is tracked
+  in actions/runner#3731 and may be included in a future runner release.
+fix_code:
+  - language: yaml
+    label: 'Bug: mixed-case action references cause repeated downloads'
+    code: |
+      # workflow.yml — uses lowercase
+      steps:
+        - uses: actions/checkout@v4
+
+      # internal/composite/action.yml — uses title-case (different casing)
+      runs:
+        using: composite
+        steps:
+          - uses: Actions/Checkout@v4   # triggers a second download in v2.334.0
+  - language: yaml
+    label: 'Fix: canonicalize to lowercase owner/repo in all workflow and composite action files'
+    code: |
+      # workflow.yml
+      steps:
+        - uses: actions/checkout@v4   # lowercase
+
+      # internal/composite/action.yml
+      runs:
+        using: composite
+        steps:
+          - uses: actions/checkout@v4   # lowercase matches — deduplicated correctly
+  - language: yaml
+    label: 'Diagnostic: detect duplicate downloads by searching job logs'
+    code: |
+      # In the Actions UI, open the job log and search for "Download action repository"
+      # If the same action appears more than once (even with different casing), you
+      # have duplicate downloads.
+      #
+      # CLI equivalent (with gh):
+      # gh run view <run-id> --log | grep "Download action repository" | sort | uniq -c
+prevention:
+  - 'Use consistent lowercase owner/repo for all action references across workflow files and composite actions'
+  - 'Add an actionlint check to CI; it flags inconsistent action reference casing'
+  - 'Audit composite action.yml files for uppercase uses: references, as they are the most common source'
+  - 'Pin runner version to v2.333.0 as a temporary workaround while waiting for runner#3731 fix'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3731'
+    label: 'GitHub runner#3731: Download action repository called repeatedly for same action (case-sensitivity)'
+  - url: 'https://github.com/actions/runner/releases/tag/v2.334.0'
+    label: 'Runner v2.334.0 release notes: batch and deduplicate action resolution'

package/errors/runner-environment/setup-node-ebaddevengines-devengines-packagemanager.yml

@@ -0,0 +1,103 @@
+id: runner-environment-204
+title: 'setup-node fails with EBADDEVENGINES when devEngines.packageManager requires a newer npm than Node ships'
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - npm
+  - devEngines
+  - EBADDEVENGINES
+  - package-manager
+  - node-22
+  - package-json
+patterns:
+  - regex: 'npm error code EBADDEVENGINES'
+    flags: 'i'
+  - regex: 'EBADDEVENGINES.*Invalid devEngines\.packageManager'
+    flags: 'i'
+  - regex: 'Invalid semver version.*does not match.*for "packageManager"'
+    flags: 'i'
+  - regex: 'npm config get cache.*EBADDEVENGINES'
+    flags: 'si'
+error_messages:
+  - 'npm error code EBADDEVENGINES'
+  - 'npm error EBADDEVENGINES The developer of this package has specified the following through devEngines'
+  - 'npm error EBADDEVENGINES Invalid devEngines.packageManager'
+  - 'npm error EBADDEVENGINES Invalid semver version "^11.10.0" does not match "10.9.7" for "packageManager"'
+  - '/opt/hostedtoolcache/node/22.22.2/x64/bin/npm config get cache'
+root_cause: |
+  actions/setup-node detects the package manager by running `npm config get cache`
+  early in its initialization — before any user-specified npm upgrade step can run.
+  When package.json contains a `devEngines.packageManager` field specifying a minimum
+  npm version higher than the version bundled with the selected Node.js release, npm
+  enforces the devEngines constraint and exits with EBADDEVENGINES during that preflight
+  `npm config get cache` call, causing setup-node to fail immediately.
+
+  Example: Node.js v22 ships with npm v10. If package.json requires:
+    "devEngines": { "packageManager": { "name": "npm", "version": "^11.10.0" } }
+  then npm v10 raises EBADDEVENGINES, aborting setup-node before the user can run
+  `npm install --global npm@latest` in a subsequent step.
+
+  The `devEngines` field (npm RFC) was introduced in Node.js 22's era and allows
+  packages to declare their required toolchain. npm 10.x enforces it strictly by
+  default. Source: actions/setup-node#1553.
+fix: |
+  Option 1 — Use the npm-version input on setup-node (recommended):
+  If setup-node applies the npm-version upgrade before its package manager detection,
+  the correct npm version will already be present when devEngines is checked.
+  Test this first; behaviour may depend on setup-node version.
+
+  Option 2 — Set devEngines.packageManager.onFail to "warn" in package.json:
+  npm 10.9+ supports an `onFail` sub-field that downgrades the constraint violation
+  from fatal error to warning. This allows CI to proceed and install the required
+  npm in a subsequent step.
+
+  Option 3 — Use explicit node-version instead of node-version-file:
+  When node-version-file is used, setup-node reads package.json to determine the
+  Node version, which may trigger the devEngines check. Using an explicit
+  node-version string avoids reading package.json entirely for version resolution.
+
+  Option 4 — Remove or relax devEngines.packageManager for CI use:
+  Consider whether the devEngines constraint is necessary for CI vs local dev.
+  A `.npmrc` with `engine-strict=false` in the repo will disable enforcement
+  for all npm operations in that directory, but this also affects local installs.
+fix_code:
+  - language: yaml
+    label: 'Option 1 — use npm-version input to pre-install required npm'
+    code: |
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json   # Reads engines.node
+          npm-version: '11'                 # Pre-installs npm 11 before devEngines check
+  - language: yaml
+    label: 'Option 3 — use explicit node-version to skip package.json parsing'
+    code: |
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'                # Explicit version; does not read package.json
+      # Install required npm explicitly in a later step
+      - run: npm install --global npm@^11.10.0
+  - language: json
+    label: 'Option 2 — set onFail: warn in package.json to prevent fatal error'
+    code: |
+      {
+        "devEngines": {
+          "packageManager": {
+            "name": "npm",
+            "version": "^11.10.0",
+            "onFail": "warn"
+          }
+        }
+      }
+prevention:
+  - 'When adopting devEngines.packageManager in package.json, test the CI setup-node step immediately — it may fail before your npm upgrade step can run'
+  - 'Set devEngines.packageManager.onFail: "warn" in any repo where CI installs the required npm version dynamically rather than having it pre-installed'
+  - 'Use the npm-version input on setup-node when your package.json requires a specific npm version via devEngines'
+  - 'Avoid relying on node-version-file if your package.json contains strict devEngines constraints and you need to upgrade the package manager in CI'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1553'
+    label: 'actions/setup-node#1553: npm config get cache fails with EBADDEVENGINES'
+  - url: 'https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines'
+    label: 'npm docs: devEngines field in package.json'
+  - url: 'https://github.com/nodejs/package-maintenance/issues/539'
+    label: 'Node.js RFC: devEngines field specification'

package/errors/silent-failures/paths-filter-before-field-missing-workflow-run.yml

@@ -0,0 +1,105 @@
+id: silent-failures-107
+title: "dorny/paths-filter Reports All Files Changed When 'before' Field Missing on workflow_run"
+category: silent-failures
+severity: silent-failure
+tags:
+  - paths-filter
+  - workflow_run
+  - before-field
+  - silent-failure
+  - fork-pr
+  - changed-files
+  - wrong-output
+patterns:
+  - regex: '''before'' field is missing in event payload'
+    flags: 'i'
+  - regex: 'changes will be detected from last commit'
+    flags: 'i'
+  - regex: 'paths-filter.*workflow.run'
+    flags: 'i'
+error_messages:
+  - "Warning: 'before' field is missing in event payload - changes will be detected from last commit"
+root_cause: |
+  `dorny/paths-filter` (v3 and earlier) contains an internal code path that requires a
+  `before` SHA field from the GitHub event payload to compute the diff base. When used in
+  a `workflow_run`-triggered workflow, the event payload does not contain a `before` field
+  (it only has `head_sha`, `head_branch`, etc.) — so the action falls into a fallback path
+  that calls `getChangesInLastCommit()` instead of performing a proper merge-base diff.
+
+  The result: **every file in the repository is reported as "changed"**, defeating any
+  attempt to use paths-filter as a change detection gate in `workflow_run` workflows.
+
+  Root cause in source code (paths-filter v3):
+  The action's `getChangedFilesFromGit()` logic normalizes both `base` and `head` to short
+  branch names. On `workflow_run`, `github.context.ref` resolves to the same ref as the
+  user-supplied `base:` (e.g. both become "main"). The `isBaseSameAsHead` check triggers
+  the fallback: if `base === head` AND `beforeSha` is null, the action emits the warning
+  and returns only the last commit's changes — which in a merge-queue or PR workflow is
+  completely wrong.
+
+  The same bug occurs when:
+  - Using paths-filter in a `workflow_run` workflow without explicitly passing `ref:` as a SHA.
+  - Running from a forked PR where the `before` field is absent from the push payload.
+  - Any workflow_run where `github.context.ref` resolves to the same branch name as the
+    `base:` input after short-name normalization.
+fix: |
+  Pass `ref:` explicitly as the HEAD SHA of the triggering workflow run. Using a full SHA
+  prevents the `isBaseSameAsHead` short-circuit because a SHA never equals a branch name
+  after normalization:
+
+    - uses: dorny/paths-filter@v3
+      with:
+        base: 'main'
+        ref: ${{ github.event.workflow_run.head_sha }}
+        filters: |
+          backend:
+            - 'src/**'
+
+  Also ensure the prior `actions/checkout` step uses `fetch-depth: 0` so the action has
+  both `base` and `ref` locally available for `getChangesSinceMergeBase`.
+
+  For fork PRs: use `ref: ${{ github.event.workflow_run.head_sha }}` and
+  `base: ${{ github.event.workflow_run.base_branch }}`.
+
+  Alternative: upgrade to dorny/paths-filter v4.0.1+ which adds native `merge_group`
+  support and has improved ref handling (check release notes for workflow_run fixes).
+fix_code:
+  - language: yaml
+    label: 'Pass ref as SHA to avoid isBaseSameAsHead false-positive on workflow_run'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        check-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            backend: ${{ steps.filter.outputs.backend }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+                fetch-depth: 0
+
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                base: ${{ github.event.workflow_run.base_branch }}
+                # REQUIRED: pass ref as SHA, not branch name
+                # Without this, base == head after normalization → all files reported as changed
+                ref: ${{ github.event.workflow_run.head_sha }}
+                filters: |
+                  backend:
+                    - 'src/**'
+prevention:
+  - 'Always pass ref: ${{ github.event.workflow_run.head_sha }} when using paths-filter in workflow_run contexts.'
+  - 'Never rely on implicit ref resolution in workflow_run workflows — the context.ref is the default branch, not the PR head.'
+  - 'After fixing, add a smoke-test PR that changes only an unmonitored path and verify paths-filter returns false for the guarded path.'
+  - 'Consider tj-actions/changed-files as an alternative; check its workflow_run documentation before switching.'
+docs:
+  - url: 'https://github.com/dorny/paths-filter/issues/261'
+    label: "Bug: 'before' field is missing when it should not even be used (11 reactions, open)"
+  - url: 'https://github.com/dorny/paths-filter'
+    label: 'dorny/paths-filter — conditionally run actions based on modified files'

package/errors/silent-failures/windows-11-arm-bash-shell-intermittent-zero-output.yml

@@ -0,0 +1,99 @@
+id: silent-failures-106
+title: 'windows-11-arm shell: bash Steps Intermittently Produce Zero Output and Exit 0'
+category: silent-failures
+severity: silent-failure
+tags:
+  - windows-11-arm
+  - bash
+  - composite-action
+  - arm64
+  - wow64
+  - silent-failure
+  - intermittent
+patterns:
+  - regex: 'error: no such command: `[a-z]'
+    flags: 'i'
+  - regex: 'error: no such subcommand: `[a-z]'
+    flags: 'i'
+  - regex: 'error\[E0463\]: can''t find crate for `[a-z]'
+    flags: 'i'
+error_messages:
+  - 'error: no such command: `make`'
+  - 'error: no such command: `expand`'
+  - 'error: no such subcommand: `make`'
+root_cause: |
+  On `windows-11-arm` runners, `shell: bash` resolves to `C:\Program Files\Git\bin\bash.EXE`,
+  which is an x86_64 binary running under WoW64 (Windows-on-Windows 64-bit) ARM64
+  emulation. The `actions/runner` binary on this platform is a **native ARM64** process.
+  When the native ARM64 runner spawns the x86_64 bash.EXE as a child process, an
+  intermittent failure in the WoW64 cross-architecture process launch causes the bash
+  process to start but never execute its script body. The step logs the command invocation
+  and environment dump, then exits 0 with zero script output — the script never ran.
+
+  Key characteristics:
+  - Failure is transient per-process-invocation: two consecutive bash steps in the same
+    job can have one succeed and one fail, ruling out image or runner misconfiguration.
+  - Zero-output steps take 0-3 seconds; successful steps take 2-7 seconds.
+  - Only occurs on `windows-11-arm`; `windows-latest` (amd64) is unaffected.
+  - The downstream step then fails with "no such command" or "not installed" errors because
+    the tool that was supposed to be installed by the bash step is missing.
+  - Reported across multiple independent Microsoft repositories
+    (microsoft/Windows-rust-driver-samples, microsoft/windows-drivers-rs), confirming
+    this is a platform-level runner bug, not a workflow configuration issue.
+
+  Root cause: intermittent x86_64 process execution failure under ARM64 WoW64 emulation
+  when launched from a native ARM64 parent process. No fix from the platform side as of
+  April 2026; actions/runner issue is open in partner-runner-images.
+fix: |
+  Option 1 (recommended): invoke bash from PowerShell as a workaround. Wrapping the bash
+  call in a pwsh step bypasses the native-arm64 → x86_64 WoW64 launch that triggers the
+  bug, because PowerShell on windows-11-arm is itself x86_64, so spawning x86_64 bash
+  from x86_64 pwsh does not cross the ARM64/x86_64 boundary:
+
+    - name: Run script via pwsh workaround
+      shell: pwsh
+      run: |
+        $result = & 'C:\Program Files\Git\bin\bash.EXE' -c "./your-script.sh"
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+  Option 2: use `shell: pwsh` for the entire step and rewrite the logic in PowerShell.
+
+  Option 3: add a retry wrapper that re-runs the composite action step if the output
+  is unexpectedly empty (e.g. check for absence of the installed binary before proceeding
+  and re-invoke if missing).
+
+  Option 4: avoid `windows-11-arm` in the runner matrix until the platform bug is fixed
+  upstream, or pin to `windows-latest` (amd64) for bash-heavy composite actions.
+fix_code:
+  - language: yaml
+    label: 'Invoke bash from pwsh to avoid the WoW64 ARM64 launch bug'
+    code: |
+      - name: Install tool (windows-11-arm workaround)
+        shell: pwsh
+        run: |
+          # Call x86_64 bash from x86_64 pwsh — avoids native-arm64 → x86_64 WoW64 issue
+          & 'C:\Program Files\Git\bin\bash.EXE' --noprofile --norc `
+            "${env:GITHUB_ACTION_PATH}/main.sh"
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+  - language: yaml
+    label: 'Exclude windows-11-arm from bash-heavy matrix jobs'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [windows-latest, ubuntu-latest, macos-latest]
+              # windows-11-arm excluded: shell: bash intermittent zero-output bug
+              # See: https://github.com/actions/partner-runner-images/issues/169
+prevention:
+  - 'Test composite actions on windows-11-arm at scale before relying on them in production CI.'
+  - 'Add post-step verification that checks for the installed binary; fail explicitly rather than silently continuing.'
+  - 'Monitor taiki-e/install-action release notes for the official workaround (pwsh retry wrapper) if using that action.'
+  - 'Prefer shell: pwsh over shell: bash for setup/install scripts in composite actions targeting windows-11-arm.'
+docs:
+  - url: 'https://github.com/actions/partner-runner-images/issues/169'
+    label: '[windows-11-arm] Composite action bash steps intermittently produce zero output and exit 0'
+  - url: 'https://github.com/taiki-e/install-action/issues/1562'
+    label: 'On windows-11-arm, sometimes does nothing, but succeeds'
+  - url: 'https://github.com/taiki-e/install-action/pull/1647'
+    label: 'Call main.sh from pwsh on Windows to work around windows-11-arm runner bug'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.115",
+  "version": "1.0.117",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",