@htekdev/actions-debugger 1.0.115 → 1.0.116

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/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/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/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.116",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",