@htekdev/actions-debugger 1.0.116 → 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/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-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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.116",
+  "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",