@htekdev/actions-debugger 1.0.121 → 1.0.123

package/errors/caching-artifacts/caching-artifacts-072.yml

@@ -0,0 +1,137 @@
+id: caching-artifacts-072
+title: 'actions/cache@v5 Restore Rate Limit (429) Silently Treated as Cache Miss'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - rate-limit
+  - 429
+  - restore
+  - cache-miss
+  - silent-failure
+  - v5
+  - performance
+patterns:
+  - regex: 'Warning: You''ve hit a rate limit, your rate limit will reset in \d+ seconds'
+    flags: 'i'
+  - regex: 'Failed to restore:.*GetCacheEntryDownloadURL.*Rate [Ll]imited'
+    flags: 'i'
+  - regex: 'Failed request: \(429\) Too Many Requests: rate limit exceeded'
+    flags: 'i'
+error_messages:
+  - "Warning: You've hit a rate limit, your rate limit will reset in 18 seconds"
+  - "Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate Limited: Failed request: (429) Too Many Requests: rate limit exceeded"
+  - "Cache not found for input keys: goofy-b41b01ad3312fe1358359b7522c43860bfdad754166c7f1d385e51766e57b4c0"
+root_cause: |
+  When the GitHub cache service rate-limits a cache restore lookup request with HTTP
+  429 Too Many Requests, actions/cache@v5 does NOT retry the request. Instead, it
+  prints a warning and immediately treats the response as a cache miss, proceeding
+  with a full build from scratch.
+
+  The cache service includes a Retry-After header in the 429 response that tells the
+  client exactly how many seconds to wait before retrying (often ≤60 seconds). The
+  actions/cache implementation ignores this header entirely — no retry, no backoff,
+  no configurable behavior. The job simply never gets its cached dependencies.
+
+  This is a silent failure in the sense that:
+  1. The job succeeds — it just rebuilds everything from scratch.
+  2. No annotation or error is surfaced in the Actions UI. Only a Warning line in
+     the step log reveals what happened.
+  3. The resulting build artifacts are correct, but the CI run takes 2–10x longer
+     than expected, masking the real cause.
+
+  Most commonly triggered in large matrix builds (20+ parallel jobs) where many jobs
+  simultaneously query the cache service and collectively exhaust the per-repo or
+  per-org cache API rate limit. Also reported on repos with heavy cross-job cache
+  sharing patterns.
+
+  Distinct from caching-artifacts-030 (cache-service-429-upload-ebadf-crash.yml):
+  that entry covers 429 during the cache UPLOAD phase which crashes with EBADF.
+  This entry covers 429 during the cache RESTORE/lookup phase which silently misses
+  — different operation, different error message, different impact, different fix path.
+
+  Source: actions/cache#1758 (May 2026, open); also reported in
+  oxidecomputer/hubris#2535 "CI fails intermittently on Windows while restoring cache"
+  (May 2026).
+fix: |
+  There is no complete fix — this is an open upstream bug (actions/cache#1758).
+  The rate-limit retry path is not implemented in actions/cache. Workarounds:
+
+  Option 1 — Reduce cache API pressure by staggering matrix jobs:
+
+    strategy:
+      matrix: ...
+      max-parallel: 5   # Limit to 5 concurrent jobs instead of all at once
+
+  This reduces the burst of simultaneous restore calls and lowers the chance of
+  hitting the rate limit.
+
+  Option 2 — Add a retry wrapper using actions/cache's restore-keys cascade:
+
+    - uses: actions/cache@v5
+      id: cache
+      with:
+        key: ${{ runner.os }}-deps-${{ hashFiles('**/lockfile') }}
+        restore-keys: |
+          ${{ runner.os }}-deps-
+    - name: Warn on cache rate limit miss
+      if: steps.cache.outputs.cache-hit != 'true'
+      run: |
+        echo "::warning::Cache miss — may be rate limited. Check step log for 429."
+
+  Option 3 — Switch to a self-hosted cache backend to bypass GitHub's rate limits:
+
+    env:
+      ACTIONS_CACHE_URL: https://your-cache-backend.example.com/
+      ACTIONS_RUNTIME_TOKEN: ${{ secrets.CACHE_TOKEN }}
+
+  Option 4 — Accept it and add monitoring. If you frequently see the rate limit
+  warning, consider filing a support ticket to request a higher cache API rate limit
+  for your organization.
+fix_code:
+  - language: yaml
+    label: 'Reduce parallelism to lower cache restore burst pressure'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              target: [linux-x64, linux-arm64, windows-x64, macos-x64, macos-arm64]
+            max-parallel: 4   # Stagger jobs to reduce simultaneous cache restore calls
+          steps:
+            - uses: actions/cache@v5
+              with:
+                path: ~/.cargo/registry
+                key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+  - language: yaml
+    label: 'Add explicit warning step to surface rate limit cache misses clearly'
+    code: |
+      steps:
+        - uses: actions/cache@v5
+          id: cache-restore
+          with:
+            path: |
+              ~/.npm
+              node_modules
+            key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-
+
+        - name: Check for cache rate limit miss
+          if: steps.cache-restore.outputs.cache-hit != 'true'
+          run: |
+            echo "::warning::Cache miss detected — check step log for '429 Too Many Requests' to distinguish rate-limit miss from genuine cache absence."
+
+prevention:
+  - 'Set max-parallel on matrix strategies to limit simultaneous cache restore API calls and avoid triggering the per-org/per-repo cache rate limit.'
+  - 'Monitor the cache restore step logs for the warning message "You''ve hit a rate limit" to distinguish rate-limit misses from genuine cache absences when diagnosing slow CI runs.'
+  - 'Consider using restore-keys fallback chains so that even a rate-limited primary key miss may still succeed with a partial restore from a broader key.'
+  - 'Report rate limit occurrences to GitHub Support with your org name to request a higher cache API rate limit if you encounter this regularly in large workflows.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1758'
+    label: 'actions/cache#1758 — Handle rate limit (open, May 2026)'
+  - url: 'https://github.com/oxidecomputer/hubris/issues/2535'
+    label: 'oxidecomputer/hubris#2535 — CI fails intermittently on Windows while restoring cache (May 2026)'
+  - url: 'https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy'
+    label: 'GitHub Docs — Caching usage limits and eviction policy'

package/errors/runner-environment/runner-environment-221.yml

@@ -0,0 +1,145 @@
+id: runner-environment-221
+title: 'actions/checkout@v6 Hangs at git-credential-osxkeychain on macOS Self-Hosted Runners with Concurrent Jobs'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - macos
+  - osxkeychain
+  - credential-helper
+  - deadlock
+  - self-hosted
+  - concurrent
+  - v6
+  - hang
+patterns:
+  - regex: 'trace: start_command:.*git-credential-osxkeychain store'
+    flags: 'i'
+  - regex: 'trace: run_command: .?git credential-osxkeychain store.?$'
+    flags: 'im'
+  - regex: 'credential-osxkeychain store.*\n.*\n.*\n.*\n.*checkout.*hang'
+    flags: 'im'
+error_messages:
+  - "trace: run_command: 'git credential-osxkeychain store'"
+  - "trace: start_command: /bin/sh -c 'git credential-osxkeychain store' 'git credential-osxkeychain store'"
+  - "trace: exec: git-credential-osxkeychain store"
+  - "trace: start_command: /opt/homebrew/opt/git/libexec/git-core/git-credential-osxkeychain store"
+root_cause: |
+  On macOS self-hosted runners, Git uses git-credential-osxkeychain as the default
+  credential helper. When actions/checkout@v6 runs with persist-credentials: true
+  (the default), it stores the GITHUB_TOKEN in the macOS Keychain via the osxkeychain
+  credential helper.
+
+  The macOS Keychain grants exclusive write locks to one process at a time. When two or
+  more jobs run actions/checkout@v6 concurrently on the same self-hosted runner machine,
+  both jobs attempt to call `git credential-osxkeychain store` simultaneously. One process
+  acquires the Keychain lock and proceeds; the other blocks indefinitely waiting for the
+  lock to be released — which never happens because the macOS Keychain's IPC mechanism
+  can deadlock under concurrent access from multiple git processes sharing the same runner
+  session.
+
+  The hung checkout step produces no error output — the last visible log lines are the
+  `git-credential-osxkeychain store` trace entries. The job appears to be running but
+  makes no progress. Without a step-level timeout, GitHub's 6-hour job timeout eventually
+  cancels it.
+
+  Affected environment:
+  - actions/checkout@v6 (v6.0.x, the version that changed credential handling)
+  - macOS self-hosted runners, including macOS 26 Tahoe (runner 2.331.0+)
+  - Reproduced when ≥2 jobs on the same runner machine execute checkout concurrently
+  - Not specific to runner 2.331.0 — also reported on earlier macOS self-hosted setups
+    since checkout@v2, but became more frequent with v6's credential handling changes
+
+  Distinct from runner-environment-032 (persist-credentials: false breaks subsequent
+  git push auth — the opposite direction: fixing the push but needing credentials).
+fix: |
+  Two workarounds — try Option 1 first, fall back to Option 2 if the deadlock persists:
+
+  Option 1 — Disable credential persistence for checkout (avoids Keychain writes):
+
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+
+  This prevents checkout from calling `git credential-osxkeychain store` entirely,
+  eliminating the deadlock. Note: if your workflow's later steps need to push changes
+  to the repo using git directly (not via GH_TOKEN env var), you must pass the token
+  explicitly in the remote URL or use a separate authentication step.
+
+  Option 2 — Clean workspace before checkout (forces clean lock state):
+
+    - name: Clean workspace before checkout
+      run: |
+        find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
+          || echo "::warning::Workspace cleanup had warnings (non-fatal)"
+    - uses: actions/checkout@v6
+
+  This removes any pre-existing files that might be holding Git process locks
+  from a previous job, allowing checkout to complete cleanly. This is an uglier
+  workaround but more effective when persist-credentials: false alone does not help.
+
+  Option 3 — Disable the macOS credential helper globally for CI git operations:
+
+    - name: Disable osxkeychain credential helper for CI
+      run: git config --global credential.helper ''
+    - uses: actions/checkout@v6
+
+  For git push steps that use an explicit token URL, also set GIT_TERMINAL_PROMPT=0:
+
+    - name: Push changes
+      env:
+        GIT_TERMINAL_PROMPT: '0'
+      run: |
+        git -c credential.helper='' push --force \
+          "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" \
+          HEAD:gh-pages
+fix_code:
+  - language: yaml
+    label: 'Fix 1 — persist-credentials: false prevents Keychain write (preferred)'
+    code: |
+      steps:
+        - uses: actions/checkout@v6
+          with:
+            persist-credentials: false  # Avoids git-credential-osxkeychain store call
+
+  - language: yaml
+    label: 'Fix 2 — clean workspace before checkout to resolve concurrent lock conflicts'
+    code: |
+      steps:
+        - name: Clean workspace before checkout
+          run: |
+            find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
+              || echo "::warning::Cleanup warnings are non-fatal"
+
+        - uses: actions/checkout@v6
+
+  - language: yaml
+    label: 'Fix 3 — disable osxkeychain globally and use explicit token for git push'
+    code: |
+      steps:
+        - name: Disable macOS keychain credential helper for CI
+          run: git config --global credential.helper ''
+
+        - uses: actions/checkout@v6
+
+        # Later, for git push steps:
+        - name: Push to gh-pages
+          env:
+            GIT_TERMINAL_PROMPT: '0'
+          run: |
+            git -c credential.helper='' push --force \
+              "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" \
+              HEAD:gh-pages
+
+prevention:
+  - 'Always set persist-credentials: false on actions/checkout@v6 for macOS self-hosted runners if your jobs do not need subsequent git operations using the GITHUB_TOKEN credential helper.'
+  - 'Add a timeout-minutes: on checkout steps on macOS self-hosted runners to bound hang duration (e.g., timeout-minutes: 5) rather than waiting for the 6-hour job timeout.'
+  - 'Serialize concurrent jobs on the same macOS runner using a concurrency group, or ensure jobs that checkout concurrently run on different runner instances.'
+  - 'Set GIT_TERMINAL_PROMPT=0 in macOS self-hosted runner environments to prevent git from waiting for interactive input from any credential helper.'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/550'
+    label: 'actions/checkout#550 — Actions checkout gets stuck forever randomly (open, 2021–2026)'
+  - url: 'https://stackoverflow.com/questions/79881327/github-actions-self-hosted-runner-on-macos-tries-to-checkout-repository-forever'
+    label: 'SO q/79881327 — Github Actions self hosted runner on macOS tries to checkout repository forever (Feb 2026)'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout README — persist-credentials input documentation'

package/errors/runner-environment/runner-environment-222.yml

@@ -0,0 +1,140 @@
+id: runner-environment-222
+title: 'Windows Self-Hosted Runner V2 Broker Listener Stops Polling After First Job Completion'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - windows
+  - broker
+  - v2-flow
+  - listener
+  - polling
+  - idle
+  - 2.334.0
+  - BrokerMessageListener
+patterns:
+  - regex: 'BrokerMessageListener.*Get messages has been cancelled using local token source\. Continue to get messages with new status\.'
+    flags: 'i'
+  - regex: 'BrokerMessageListener.*Received job status event\. JobState: Online'
+    flags: 'i'
+error_messages:
+  - "[2026-05-21 14:48:13Z INFO BrokerMessageListener] Get messages has been cancelled using local token source. Continue to get messages with new status."
+  - "[INFO BrokerMessageListener] Received job status event. JobState: Online"
+  - "[INFO BrokerMessageListener] Session created."
+root_cause: |
+  On Windows self-hosted runners using the V2 broker protocol (useV2Flow: true,
+  serverUrlV2: broker.actions.githubusercontent.com), a race condition in the
+  BrokerMessageListener causes the runner to permanently stop polling the broker
+  after the first job completes.
+
+  The sequence that triggers the hang:
+  1. Runner starts, creates a broker session, and begins polling for messages.
+  2. First job arrives → BrokerMessageListener logs "JobState: Busy".
+  3. Job finishes → BrokerMessageListener logs "JobState: Online".
+  4. The Online state transition triggers a cancellation of the current polling
+     loop via a local token source ("Get messages has been cancelled using
+     local token source. Continue to get messages with new status.").
+  5. The listener is supposed to create a new polling loop with fresh state, but
+     due to a bug in the V2 flow state machine, the new polling loop is never
+     started. No further GET /message requests are ever issued.
+
+  The runner process stays alive. OAuth token refreshes continue on schedule (so
+  credentials are not the problem). The runner shows as "Idle" in the GitHub UI.
+  However, it will never pick up another job until the service is manually restarted.
+
+  The bug was introduced in or around v2.334.0 on Windows. It does not affect:
+  - Linux runners (different socket layer — see broker-server-socket-exception-nat-timeout-linux.yml)
+  - macOS runners (see macos-self-hosted-listener-aad-ghost-busy-stall.yml for a
+    separate macOS stall pattern)
+  - V1 flow runners (useV2Flow: false)
+  - GitHub-hosted runners (not affected by self-hosted listener bugs)
+
+  Source: actions/runner#4444 (May 2026, open). Reported on Windows Server 2022
+  x64, v2.334.0, V2 flow. Three reproducible occurrences in 22 hours on a
+  previously stable 6+ day continuous runner.
+fix: |
+  Immediate fix — Restart the runner service to recover:
+
+    Restart-Service actions.runner.*
+
+  Or via the runner management interface:
+    1. Go to repo/org Settings → Actions → Runners
+    2. Force-remove the stale runner registration
+    3. Re-register and restart
+
+  Structural workarounds:
+
+  Option 1 — Switch to ephemeral runners (recommended for most use cases):
+  Ephemeral runners register once, run one job, and exit cleanly. No stale state.
+
+    ./config.sh --url https://github.com/ORG/REPO --token TOKEN --ephemeral
+    ./run.sh
+
+  Or with Actions Runner Controller (ARC):
+    autoscaling.runnerScaleSetListener.minRunners: 1
+
+  Option 2 — Revert to V1 broker flow if ephemeral is not an option:
+  The V1 flow (long-polling, non-broker) does not exhibit this specific hang.
+  Edit the .runner config file and set useV2Flow: false, then restart the service.
+  Note: V1 is deprecated and will eventually be removed.
+
+  Option 3 — Add an automatic service recovery watchdog:
+
+    # Windows Task Scheduler: check every 5 minutes if runner has been Idle >20min
+    # and restart the service if it's stuck
+    $runner = Get-Service "actions.runner.*"
+    if ($runner.Status -eq "Running") {
+      # Check last job timestamp via API; if >20min and jobs queued, restart
+      Restart-Service "actions.runner.*"
+    }
+
+  Option 4 — Pin to a known-good runner version:
+  If v2.334.0+ reliably triggers this, pin the runner to v2.333.x by editing
+  the .runner config and disabling auto-update. Note: outdated versions
+  eventually stop being able to receive messages.
+fix_code:
+  - language: yaml
+    label: 'Use ephemeral runners to avoid stale listener state entirely'
+    code: |
+      # In your workflow:
+      jobs:
+        build:
+          runs-on: [self-hosted, windows-x64]   # Labels for your runner pool
+
+      # Register runners as ephemeral:
+      # ./config.cmd --url https://github.com/ORG/REPO --token TOKEN --ephemeral
+      # Each runner exits after completing one job; a process manager (NSSM, task
+      # scheduler, or ARC) restarts it to accept the next job.
+
+  - language: yaml
+    label: 'Add watchdog step to detect stale listener symptom (queue depth check)'
+    code: |
+      # Optional diagnostic: surface "no runners picked up job for >N minutes" via API
+      # Run this in a separate monitoring workflow:
+      jobs:
+        watchdog:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check for stuck self-hosted Windows runners
+              env:
+                GH_TOKEN: ${{ secrets.RUNNER_ADMIN_PAT }}
+              run: |
+                # List queued jobs older than 10 minutes that are assigned to self-hosted
+                gh api repos/${{ github.repository }}/actions/runs \
+                  --jq '.workflow_runs[] | select(.status=="queued") | .id' \
+                | while read run_id; do
+                    echo "Queued run: $run_id"
+                  done
+
+prevention:
+  - 'Use ephemeral self-hosted runners — they register, run one job, and exit. No stale listener state can accumulate.'
+  - 'If using long-lived runners on Windows with V2 broker flow, add monitoring to detect runners stuck in the Idle state with queued jobs.'
+  - 'Set up automatic service recovery for the runner service on Windows (e.g., via Windows Service recovery actions: restart after 1st failure).'
+  - 'Monitor actions/runner release notes for a fix to the V2 listener polling regression introduced around v2.334.0.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4444'
+    label: 'actions/runner#4444 — Listener stops polling broker after first job''s Busy→Online transition (2.334.0, Windows, V2 flow)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job'
+    label: 'GitHub Docs — Self-hosted runner configuration'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs — Autoscaling with self-hosted runners (ephemeral runner pattern)'

package/errors/runner-environment/runner-environment-223.yml

@@ -0,0 +1,149 @@
+id: runner-environment-223
+title: 'macOS-15 Arm64 brew update Fails with Stale lockf Lock When Run Twice'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - homebrew
+  - brew-update
+  - lockf
+  - arm64
+  - macos-15
+  - regression
+  - concurrent
+patterns:
+  - regex: 'lockf: 200: already locked'
+    flags: 'i'
+  - regex: 'Error: Another `brew update` process is already running\.'
+    flags: 'i'
+  - regex: 'lockf:.*already locked\s*\nError: Another.*brew update.*process is already running'
+    flags: 'im'
+error_messages:
+  - "lockf: 200: already locked"
+  - "Error: Another `brew update` process is already running."
+  - "Please wait for it to finish or terminate it to continue."
+  - "Error: Process completed with exit code 1."
+root_cause: |
+  On macOS-15 Arm64 GitHub Actions hosted runners starting with image version
+  20260422.526 (released ~April 22, 2026), running `brew update` more than once
+  within the same workflow — or across two steps that both call `brew update` —
+  fails on the second invocation with a stale lockf lock error.
+
+  Homebrew uses a lockfile at `/opt/homebrew/Library/Taps/homebrew/homebrew-core/.git/index.lock`
+  (or a similar path) to prevent concurrent updates. In the affected image versions,
+  the first `brew update` completes successfully but leaves the lock file in a
+  state that subsequent `brew update` calls cannot acquire. The `lockf` system
+  call returns errno 200 (EDEADLK on macOS), which Homebrew surfaces as
+  "Another brew update process is already running."
+
+  This is a regression — the same workflow step pattern worked correctly on image
+  version 20260415.520 and earlier.
+
+  Common trigger patterns:
+  1. Explicit double-update in a single step: `brew update && brew update`
+  2. Two separate steps that each call `brew update` before installing different tools
+  3. Parallel jobs on the same runner image that both run `brew update` (less common
+     since each hosted runner job gets a fresh VM, but affects matrix jobs in the
+     same workflow when they share a Homebrew setup step via the action cache)
+  4. A step script that calls `brew update` internally AND the user also calls it
+
+  Note: This affects macOS-15 Arm64 specifically. macOS-14, macOS-26, and x86_64
+  variants were NOT marked as affected in the original bug report (runner-images#13965).
+
+  Source: actions/runner-images#13965 (April 2026, open, under investigation by
+  GitHub runner-images team). Reported with reproducible case from the
+  mullvad/mullvadvpn-app CI pipeline.
+fix: |
+  Option 1 — Run brew update only once per job (preferred):
+
+  Consolidate all your brew installations into a single step and call brew update
+  exactly once before them:
+
+    - name: Install dependencies
+      run: |
+        brew update
+        brew install cmake ninja pkg-config
+
+  Option 2 — Use HOMEBREW_NO_AUTO_UPDATE=1 on steps that don't need fresh formulae:
+
+  If you only need brew update for specific steps, set the env var on all other
+  brew-using steps to prevent automatic update attempts:
+
+    - name: Install specific tool
+      env:
+        HOMEBREW_NO_AUTO_UPDATE: '1'
+      run: brew install your-tool   # Skips the implicit brew update
+
+  Option 3 — Guard the second brew update with a lock check:
+
+    - name: Safe brew update
+      run: |
+        flock -xn /opt/homebrew/Library/Taps/homebrew/homebrew-core/.git/index.lock \
+          brew update || echo "::warning::brew update skipped (lock already held)"
+
+  Option 4 — Use brew upgrade instead of repeated brew update:
+  If you need the latest formula versions, run brew update once and then
+  use brew upgrade to update installed packages:
+
+    - name: Update and upgrade Homebrew
+      run: |
+        brew update        # Run exactly once
+        brew upgrade       # Upgrades installed formulae to latest
+
+  Option 5 — Check for the regression in your image version and pin:
+  If you need to pin to a known-good image version while the fix is pending,
+  see GitHub's runner-images documentation for image version pinning options
+  (note: pinning is not officially supported for GitHub-hosted standard runners).
+fix_code:
+  - language: yaml
+    label: 'Broken — two brew update calls in same workflow (second fails on affected image)'
+    code: |
+      # This fails on macOS-15 Arm64 image 20260422.526+ with lockf: 200: already locked:
+      steps:
+        - name: Install build tools
+          run: |
+            brew update
+            brew install cmake ninja
+
+        - name: Install test tools
+          run: |
+            brew update        # FAILS: Another brew update process is already running
+            brew install lcov
+
+  - language: yaml
+    label: 'Fixed — single brew update before consolidated installs'
+    code: |
+      # Consolidate into one brew update call at the start:
+      steps:
+        - name: Install all Homebrew tools
+          run: |
+            brew update   # Only call once per job
+            brew install cmake ninja lcov
+
+  - language: yaml
+    label: 'Fixed — use HOMEBREW_NO_AUTO_UPDATE=1 on subsequent brew steps'
+    code: |
+      # Or prevent auto-update on steps after the first:
+      steps:
+        - name: Install build tools
+          run: |
+            brew update
+            brew install cmake ninja
+
+        - name: Install test tools (no re-update needed)
+          env:
+            HOMEBREW_NO_AUTO_UPDATE: '1'
+          run: brew install lcov   # Uses existing formula cache; no brew update call
+
+prevention:
+  - 'Call brew update at most once per job. Consolidate all Homebrew installations into a single step with one brew update at the top.'
+  - 'Set HOMEBREW_NO_AUTO_UPDATE=1 as a job-level env var and call brew update explicitly only in the one step that needs it.'
+  - 'Pin to macOS-14 (macos-14-xlarge) or use macOS-26 (which has different Homebrew behavior) if the regression is blocking critical workflows while runner-images#13965 is open.'
+  - 'Check your CI logs for the "lockf: 200: already locked" error if macOS-15 Arm64 workflows started failing around late April 2026 — this regression is the likely cause.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13965'
+    label: 'actions/runner-images#13965 — Running brew update twice in one workflow breaks (open, April 2026)'
+  - url: 'https://docs.brew.sh/Manpage#environment'
+    label: 'Homebrew docs — HOMEBREW_NO_AUTO_UPDATE environment variable'
+  - url: 'https://github.com/mullvad/mullvadvpn-app/actions/runs/24890005834'
+    label: 'mullvad/mullvadvpn-app — Example failing run (regression confirmed between image 20260415 and 20260422)'

package/errors/triggers/triggers-071.yml

@@ -0,0 +1,117 @@
+id: triggers-071
+title: 'on: branches: Filter with Only Negation Patterns Silently Never Triggers'
+category: triggers
+severity: silent-failure
+tags:
+  - branches-filter
+  - push
+  - pull_request
+  - negation
+  - glob
+  - workflow-not-triggering
+patterns:
+  - regex: 'branches:\s*\n(\s+-\s+[''"]?!)'
+    flags: 'm'
+  - regex: 'branches:\s*\[\s*[''"]?!'
+    flags: 'i'
+error_messages:
+  - "# No error message — workflow simply never appears in the Actions run queue"
+root_cause: |
+  GitHub Actions branch filters evaluate patterns sequentially against the ref name. The
+  documented rule is: "the workflow only runs if at least one pattern matches the ref name."
+
+  When a branches: (or branches-ignore's inverse: branches:) filter list contains ONLY
+  negation patterns (entries starting with !), no positive match is ever established.
+  Negation patterns can only EXCLUDE from an existing positive match set — they cannot
+  create a match on their own. The evaluation starts with zero matches, negations find
+  nothing to remove, and the result is always "no match" → workflow never fires.
+
+  This is a silent failure: no error is raised, no annotation appears, and the workflow
+  simply never shows up in the Actions tab when the target branch is pushed to. It is
+  especially confusing because the workflow file is syntactically valid and GitHub accepts it.
+
+  Common mistake patterns:
+    branches:
+      - '!main'            # ← Only a negation — zero positive matches → never triggers
+
+    branches:
+      - '!master'          # ← Same problem — always zero triggers
+      - '!release/**'
+
+  The branches-ignore filter does NOT have this problem because it operates on the
+  complement: it matches everything EXCEPT the listed patterns. Use branches-ignore when
+  you want to exclude specific branches.
+
+  Source: SO q/57699839 (144 votes) "GitHub Actions: how to target all branches EXCEPT
+  master?" — accepted answer (242 votes) documents the required positive+negative combo.
+fix: |
+  To target all branches EXCEPT specific ones, choose one of two approaches:
+
+  Option 1 — Add wildcard positive patterns before the negation (order matters):
+
+    on:
+      push:
+        branches:
+          - '*'         # matches every branch without a '/' (e.g. main, develop)
+          - '*/*'       # matches single-slash branches (e.g. feature/x)
+          - '**'        # matches all remaining branches
+          - '!main'     # now excludes main from the positive matches above
+
+  Option 2 — Use branches-ignore instead (simpler and cleaner):
+
+    on:
+      push:
+        branches-ignore:
+          - main
+          - 'release/**'
+
+  Do NOT combine branches: and branches-ignore: on the same event — GitHub rejects that
+  combination with a YAML validation error.
+fix_code:
+  - language: yaml
+    label: 'Broken — only negation in branches: filter, workflow never runs'
+    code: |
+      # This workflow NEVER triggers for any branch push — negation-only matches nothing:
+      on:
+        push:
+          branches:
+            - '!main'        # WRONG: no positive pattern to negate from
+
+  - language: yaml
+    label: 'Fixed — positive wildcard patterns before negation'
+    code: |
+      # Correct approach: include positive patterns first, then exclude specific branches:
+      on:
+        push:
+          branches:
+            - '*'            # matches branches without '/' in name
+            - '*/*'          # matches single-level slash branches
+            - '**'           # matches all remaining branches
+            - '!main'        # now excludes main from the above positive matches
+
+  - language: yaml
+    label: 'Alternative fix — use branches-ignore (simplest for exclusion only)'
+    code: |
+      # Use branches-ignore when you want to exclude specific branches entirely:
+      on:
+        push:
+          branches-ignore:
+            - main
+            - 'release/**'
+            - 'hotfix/**'
+        pull_request:
+          branches-ignore:
+            - main
+
+prevention:
+  - 'When you want to exclude branches, prefer branches-ignore: over branches: with negation — it is simpler and has no positive-pattern requirement.'
+  - 'If you must use branches: with negation, always include at least one positive glob (like ** or *) before the negation patterns.'
+  - 'Remember that pattern order matters: a positive match AFTER a negative pattern re-includes the ref; a negative match AFTER a positive match excludes it.'
+  - 'Use actionlint or act --list to verify your workflow would trigger before relying on pushes to test it.'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'GitHub Docs — on.push.branches filter syntax and negation patterns'
+  - url: 'https://stackoverflow.com/questions/57699839/github-actions-how-to-target-all-branches-except-master'
+    label: 'SO q/57699839 (144 votes) — GitHub Actions: how to target all branches EXCEPT master?'
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet'
+    label: 'GitHub Docs — Filter pattern cheat sheet (glob syntax reference)'

package/errors/yaml-syntax/yaml-syntax-074.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-074
+title: 'Workflow YAML File in Nested Subdirectory of .github/workflows/ Is Silently Ignored'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - workflow-placement
+  - subdirectory
+  - nested-folder
+  - file-location
+  - workflow-not-appearing
+  - silent-failure
+patterns:
+  - regex: '\.github/workflows/[^/\s]+/[^/\s]+\.ya?ml'
+    flags: 'i'
+error_messages:
+  - "# No error — workflow YAML in .github/workflows/subdir/name.yml is silently ignored"
+  - "# Workflow never appears in Actions tab; no annotation is created"
+root_cause: |
+  GitHub Actions only scans for workflow files in the DIRECT children of
+  `.github/workflows/` — it does NOT recurse into subdirectories. Files placed in
+  nested paths such as:
+
+    .github/workflows/ci/build.yml
+    .github/workflows/scripts/deploy.yaml
+    .github/workflows/reusable/my-caller.yml
+
+  are completely invisible to GitHub Actions. The runner does not parse them, does not
+  validate them, and emits no error or warning of any kind. The workflow simply never
+  appears in the repository's Actions tab, regardless of how correct the YAML content is.
+
+  This is a documented but easy-to-overlook constraint in the GitHub Actions architecture.
+  The scanner uses a shallow file glob equivalent to `.github/workflows/*.yml` and
+  `.github/workflows/*.yaml` — NOT `.github/workflows/**/*.yml`.
+
+  Common causes:
+  1. Developers organize workflows into subdirectories for clarity (e.g., `ci/`, `deploy/`),
+     not realizing GitHub won't pick them up.
+  2. Copy-pasting a workflow into a folder that already holds related shell scripts or
+     configuration files, creating an unintended nested path.
+  3. Renaming or restructuring the .github directory and accidentally moving workflow files
+     one level too deep.
+  4. Reusable workflow files placed in a `reusable/` or `shared/` subdirectory under
+     workflows/ — these also won't be discovered by GitHub as callable workflows.
+
+  Note: This affects ALL workflow types — regular workflows, reusable workflows
+  (workflow_call), scheduled workflows, and manually dispatched workflows alike.
+
+  Source: SO q/61989951 answer (score 9, from the 158-vote "GitHub Action workflow not
+  running" thread) and GitHub Actions documentation.
+fix: |
+  Move all workflow YAML files directly into `.github/workflows/` (one level deep).
+  Do not create subdirectories inside `.github/workflows/` for workflow YAML files.
+
+  If you want to organize workflows logically, use naming prefixes instead of folders:
+
+    .github/workflows/ci-build.yml
+    .github/workflows/ci-test.yml
+    .github/workflows/deploy-staging.yml
+    .github/workflows/deploy-production.yml
+
+  For scripts, configs, and helper files that are referenced by workflows, place them
+  in a separate directory OUTSIDE `.github/workflows/`, for example:
+    .github/scripts/
+    .github/actions/my-local-action/
+
+  Note: Local composite actions (in `.github/actions/`) CAN be in subdirectories — the
+  subdirectory restriction only applies to workflow YAML files inside `.github/workflows/`.
+fix_code:
+  - language: yaml
+    label: 'Broken — workflow file in nested subdirectory (silently ignored)'
+    code: |
+      # .github/workflows/ci/build.yml  ← WRONG LOCATION, never discovered
+      name: Build CI
+
+      on:
+        push:
+          branches: ['**']
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+  - language: yaml
+    label: 'Fixed — workflow file at root of .github/workflows/'
+    code: |
+      # .github/workflows/ci-build.yml  ← CORRECT LOCATION, discovered by GitHub
+      name: Build CI
+
+      on:
+        push:
+          branches: ['**']
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+  - language: yaml
+    label: 'Organization pattern — use prefixes instead of subdirectories'
+    code: |
+      # Use name prefixes to group related workflows at the root level:
+      # .github/workflows/ci-build.yml
+      # .github/workflows/ci-lint.yml
+      # .github/workflows/ci-test.yml
+      # .github/workflows/deploy-staging.yml
+      # .github/workflows/deploy-production.yml
+      # .github/workflows/release-tag.yml
+      #
+      # Helper scripts/configs can be in subdirectories outside workflows/:
+      # .github/scripts/deploy.sh
+      # .github/actions/my-composite-action/action.yml  ← composite actions CAN be nested
+
+prevention:
+  - 'Keep all workflow YAML files (.yml / .yaml) directly in .github/workflows/ — never in subdirectories of that folder.'
+  - 'For workflow organization, use descriptive filename prefixes (ci-, deploy-, release-) instead of subdirectories.'
+  - 'Place helper shell scripts in .github/scripts/ and composite actions in .github/actions/<name>/ — subdirectories are fine there but not for workflow files.'
+  - 'After creating a new workflow file, immediately check that it appears in the repository Actions tab before relying on it for CI.'
+  - 'Use actionlint or the GitHub Actions VS Code extension to validate placement — both tools warn about unrecognized workflow file locations.'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-workflows/about-workflows#workflow-basics'
+    label: 'GitHub Docs — About workflows: file placement requirements'
+  - url: 'https://stackoverflow.com/questions/61989951/github-action-workflow-not-running'
+    label: 'SO q/61989951 (158 votes) — GitHub Action workflow not running (answer: nested subfolder not recognized)'
+  - url: 'https://docs.github.com/en/actions/creating-actions/creating-a-composite-action'
+    label: 'GitHub Docs — Composite actions (can be in .github/actions/ subdirectories)'

package/package.json

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