@htekdev/actions-debugger 1.0.21 → 1.0.23

package/errors/known-unsolved/homebrew-transitive-dependency-not-guaranteed.yml

@@ -0,0 +1,133 @@
+id: known-unsolved-020
+title: "Homebrew Transitive Dependency Silently Removed — Only Documented Formulas Are Guaranteed"
+category: known-unsolved
+severity: limitation
+tags:
+  - macos
+  - homebrew
+  - transitive-dependency
+  - runner-image
+  - brew
+  - silent-removal
+  - limitation
+patterns:
+  - regex: "No such file or directory.*homebrew.*opt.*\\b(libevent|libiconv|libffi|gettext)\\b"
+    flags: "i"
+  - regex: "Library not loaded.*homebrew.*opt.*\\.dylib.*image not found"
+    flags: "i"
+  - regex: "brew.*error.*([a-z0-9_-]+): No available formula"
+    flags: "i"
+  - regex: "dyld.*Library not loaded.*/opt/homebrew/opt/[a-z0-9_-]+/lib"
+    flags: "i"
+error_messages:
+  - "Error: No such file or directory - /opt/homebrew/opt/libevent/lib/libevent.dylib"
+  - "dyld[80]: Library not loaded: /opt/homebrew/opt/libevent/lib/libevent.dylib"
+  - "pkg-config: Package 'libevent', required by 'virtual:world', not found"
+  - "CMake Error: Could not find a package configuration file provided by 'libevent'"
+root_cause: |
+  GitHub-hosted macOS runner images include a curated list of Homebrew formulae that are
+  **officially documented and guaranteed** (listed in the image README, e.g.
+  `images/macos/macos-15-Readme.md`). Any Homebrew package that is present on the image
+  only as a **transitive dependency** of another formula — not explicitly documented — can
+  silently disappear between image updates when the parent formula's dependency chain changes.
+
+  **What happens:**
+  When a documented formula is upgraded (e.g., `tmux`, `openssl@3`, `ffmpeg`), its new
+  version may no longer depend on the same set of transitive packages as the previous
+  version. The transitive dependency is removed from the image automatically in the next
+  image release, with no announcement, no deprecation notice, and no entry in the image
+  changelog.
+
+  **Real example:** `libevent` was present on `macos-15` images as a transitive dependency
+  of another documented formula. When that formula's dependency chain changed in the
+  `20260525.0142.1` image, `libevent` was removed. Workflows depending on `libevent`
+  (for building tmux from source, libevent-based C++ servers, etc.) began failing with
+  "No such file or directory" errors without any changes to the workflow itself.
+
+  GitHub's response (confirmed in runner-images#14170):
+  > "libevent has never been part of the documented Homebrew Formulae list. It was only
+  > present incidentally as a transitive dependency of another formula, and that
+  > dependency chain has changed in the newer image. Since libevent is not an officially
+  > preinstalled tool on the image, its presence is not guaranteed across image versions
+  > and we don't plan to pin it."
+
+  **This is by design and will not be fixed.** The GitHub runner-images team will not
+  guarantee transitive dependencies — only the explicitly documented formula list is stable.
+
+  Source: actions/runner-images#14170 (closed as `wontfix / not_planned`, May 2026).
+fix: |
+  The only reliable fix is to **explicitly install every library your workflow needs**,
+  regardless of whether it "happens to be there" on the current image.
+
+  **Immediate fix:** Add `brew install <missing-package>` as a workflow step before
+  any step that requires the package:
+
+  **Long-term fix:** Audit ALL your workflow's Homebrew dependencies and cross-reference
+  each one against the official runner image README. Any package NOT listed there must be
+  explicitly installed in your workflow.
+
+  **Finding the image README:**
+  - macOS 15: https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md
+  - macOS 26: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-Readme.md
+  If your package isn't in the "Homebrew Packages" section of the README, install it
+  explicitly — it's not guaranteed.
+fix_code:
+  - language: yaml
+    label: "Explicitly install transitive dependencies before use"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Explicitly install ALL required libraries — even ones that "used to be there"
+            - name: Install dependencies
+              run: |
+                brew install libevent libffi gettext
+                # Do NOT rely on transitive deps from other formulae
+
+            - name: Build
+              run: make
+  - language: yaml
+    label: "Audit step — verify dependencies are explicitly documented"
+    code: |
+      # Check if your dependency is in the official image README:
+      # curl -s https://raw.githubusercontent.com/actions/runner-images/main/images/macos/macos-15-Readme.md \
+      #   | grep -i "libevent"
+      # If no output → the package is NOT guaranteed → add brew install
+
+      - name: Ensure all dependencies are installed
+        run: |
+          # Install everything your build actually needs
+          brew install libevent tmux pkg-config
+  - language: yaml
+    label: "Cache explicit brew installs to reduce per-job overhead"
+    code: |
+      - name: Cache Homebrew packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/Library/Caches/Homebrew
+            /opt/homebrew/Cellar
+          key: ${{ runner.os }}-brew-${{ hashFiles('Brewfile') }}
+          restore-keys: |
+            ${{ runner.os }}-brew-
+
+      - name: Install dependencies from Brewfile
+        run: brew bundle
+prevention:
+  - "Never rely on a Homebrew package being preinstalled unless it is explicitly listed in the runner image's official README (linked below)."
+  - "Maintain a `Brewfile` in your repository and use `brew bundle` to install all macOS dependencies explicitly — this documents and enforces your true dependency set."
+  - "When a workflow starts failing on macOS runners after an image update, check the runner-images release notes for formula removals and cross-reference against the image README."
+  - "Subscribe to runner-images releases (GitHub → Watch → Releases) to get notified when the image README changes and transitive deps may be affected."
+  - "Run `brew deps --tree <your-installed-formula>` locally to identify which transitive deps your workflow relies on, then add explicit `brew install` calls for each."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14170"
+    label: "runner-images#14170: macos-15 libevent removed as transitive dep (closed wontfix)"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md"
+    label: "macOS 15 runner image README — official guaranteed software list"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-Readme.md"
+    label: "macOS 26 runner image README — official guaranteed software list"
+  - url: "https://docs.brew.sh/Manpage#bundle-subcommand"
+    label: "Homebrew Bundle subcommand — manage dependencies via Brewfile"

package/errors/known-unsolved/reusable-secrets-inherit-not-deep-forwarded.yml

@@ -0,0 +1,113 @@
+id: known-unsolved-021
+title: "secrets: inherit Does Not Cascade to Second-Level Nested Reusable Workflows"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - secrets
+  - secrets-inherit
+  - nesting
+  - silent-failure
+
+patterns:
+  - regex: "secret .+ is required, but not provided"
+    flags: "i"
+  - regex: "secrets\\.\\w+ is not a valid secret key"
+    flags: "i"
+
+error_messages:
+  - "Secret GIT_PAT is required, but not provided"
+  - "Required secret 'MY_SECRET' was not provided by the caller"
+
+root_cause: |
+  `secrets: inherit` in a caller workflow passes ALL repository and organization
+  secrets to the directly-called (first-level) reusable workflow. However, if that
+  reusable workflow then calls ANOTHER reusable workflow (second level), those
+  inherited secrets are NOT automatically forwarded to the second level.
+
+  Each `workflow_call` boundary is a discrete secrets scope. `secrets: inherit`
+  only covers one hop. If you have:
+
+    root.yml  →  (secrets: inherit)  →  level1.yml  →  level2.yml
+
+  then `level2.yml` receives an empty secrets context unless `level1.yml`
+  explicitly passes them via its own `secrets:` block.
+
+  This is a platform design decision, not a bug. GitHub has confirmed that
+  `secrets: inherit` does not cascade through multiple `workflow_call` layers.
+  There is no current mechanism for automatic multi-level secret propagation.
+
+  Community reports: actions/runner#2709 (open, labeled bug, 8 👍, 2023–2025),
+  community/discussions/23107.
+
+fix: |
+  Explicitly declare and pass secrets at EVERY reusable workflow boundary.
+
+  For level1.yml to forward secrets to level2.yml, level1.yml must:
+    1. Declare secrets in its on.workflow_call.secrets block.
+    2. Pass those secrets explicitly in the jobs.*.secrets block when calling level2.yml.
+
+  Alternatively, use `secrets: inherit` at EACH level — but the calling workflow
+  (level1.yml) itself must also explicitly declare the secrets it expects so
+  they are available in its scope to pass down.
+
+fix_code:
+  - language: yaml
+    label: "root.yml — caller uses secrets: inherit for first hop"
+    code: |
+      jobs:
+        call-level1:
+          uses: ./.github/workflows/level1.yml
+          secrets: inherit   # passes ALL secrets to level1.yml only
+
+  - language: yaml
+    label: "level1.yml — must declare AND re-forward secrets to level2.yml"
+    code: |
+      on:
+        workflow_call:
+          secrets:
+            MY_SECRET:
+              required: true
+            DEPLOY_TOKEN:
+              required: false
+
+      jobs:
+        call-level2:
+          uses: ./.github/workflows/level2.yml
+          secrets:
+            MY_SECRET: ${{ secrets.MY_SECRET }}       # explicit re-forward
+            DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} # explicit re-forward
+
+  - language: yaml
+    label: "level2.yml — must declare secrets it expects"
+    code: |
+      on:
+        workflow_call:
+          secrets:
+            MY_SECRET:
+              required: true
+            DEPLOY_TOKEN:
+              required: false
+
+      jobs:
+        use-secrets:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use secret
+              run: echo "token length = ${#MY_SECRET}"
+              env:
+                MY_SECRET: ${{ secrets.MY_SECRET }}
+
+prevention:
+  - "Audit every workflow_call boundary in nested reusable workflows — each hop must explicitly forward secrets."
+  - "Document required secrets at every level in workflow comments to avoid silent empty-string failures."
+  - "Use composite actions instead of nested reusable workflows when secrets do not need to cross job boundaries — composite actions share the parent job's secrets context automatically."
+  - "Test nested workflows by echoing a non-sensitive derived value (e.g., secret length) at each level to confirm propagation."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/reusing-workflows#passing-secrets-to-nested-workflows"
+    label: "GitHub Docs — Passing secrets to nested workflows"
+  - url: "https://github.com/actions/runner/issues/2709"
+    label: "actions/runner#2709 — Passing secrets to reusable workflow does not work (open, 2023)"
+  - url: "https://github.com/orgs/community/discussions/23107"
+    label: "community/discussions#23107 — Inheriting secrets in reusable workflows"

package/errors/runner-environment/force-node24-env-persistent-node20-annotation.yml

@@ -0,0 +1,127 @@
+id: runner-environment-057
+title: "FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 Still Emits Node 20 Deprecation Annotation"
+category: runner-environment
+severity: warning
+tags:
+  - node20
+  - node24
+  - deprecation
+  - annotation
+  - force-node24
+  - javascript-actions
+patterns:
+  - regex: "Node\\.js 20 is deprecated.*following actions target Node\\.js 20 but are being forced to run on Node\\.js 24"
+    flags: "i"
+  - regex: "The following actions target Node\\.?20 but are being forced to run on Node\\.?24"
+    flags: "i"
+  - regex: "following actions are running on Node\\.js 20 and may not work as expected"
+    flags: "i"
+error_messages:
+  - "Node.js 20 is deprecated. The following actions target Node.js 20 but are being forced to run on Node.js 24: some-action@v1"
+  - "The following actions are running on Node.js 20 and may not work as expected: actions/cache@v3, custom-org/deploy@v2"
+  - "Node.js 20 actions are deprecated. The following actions are running on Node.js 20"
+root_cause: |
+  Setting `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"` in a workflow's `env:` section
+  successfully redirects JavaScript actions that declare `using: node20` to execute on
+  Node.js 24 at runtime. However, the runner still emits a deprecation annotation at
+  the end of every job listing those actions.
+
+  **Two distinct annotation messages depending on runner version:**
+
+  - **Pre-runner v2.326 (before PR#4303):** Inaccurate message — "The following actions
+    are **running on** Node.js 20 and may not work as expected" — even though they are
+    actually executing on Node 24. This is a bug in the runner's deprecation tracking
+    which recorded actions before the `FORCE_` env var was resolved.
+
+  - **Post-runner v2.326 (after PR#4303 fix):** Accurate but still present message —
+    "Node.js 20 is deprecated. The following actions **target** Node.js 20 but are
+    being forced to run on Node.js 24" — this annotation correctly describes the
+    situation but continues to appear as long as any action declares `using: node20`.
+
+  **Why this matters:** The annotation appears as a warning in GitHub's UI, turning
+  affected jobs "yellow" or showing red annotation badges, causing developer confusion
+  about whether `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` is working. CI dashboards that
+  treat any annotation as a failure (strict mode) will block PRs.
+
+  **Root cause of persistence:** The annotation fires based on the action's *declared*
+  `using` field in `action.yml` (`node20`), not the *actual runtime* used. Even with
+  the force env var, the declaration still exists until the action author updates and
+  publishes a new release with `using: node24`.
+
+  Source: actions/runner#4295 (9 reactions, April 2026), fixed partially in runner PR#4303.
+fix: |
+  The only permanent fix is to eliminate the `using: node20` declaration from every
+  action listed in the annotation.
+
+  **If you control the action:**
+  Update `action.yml` to declare `runs.using: 'node24'`, recompile with Node 24, and
+  publish a new release. Downstream consumers must update their `uses:` pin.
+
+  **If you use a third-party action:**
+  Update to a newer version of the action that already ships `using: node24`. Check the
+  action's GitHub releases or `action.yml` on the latest tag.
+
+  **Temporary suppression (not recommended for long-term):**
+  Continue using `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"` — the action *does* run
+  on Node 24 despite the annotation. The annotation is informational. If you need
+  annotation-clean builds, the only path is action upgrades.
+
+  **Audit all actions in your workflow:**
+  Run this to find actions still declaring node20 in their action.yml:
+  ```bash
+  find . -name 'action.yml' -o -name 'action.yaml' | xargs grep -l 'using.*node20'
+  ```
+fix_code:
+  - language: yaml
+    label: "Upgrade pinned actions to node24-compatible major versions"
+    code: |
+      # Before: actions declaring using: node20 → emits annotation even with FORCE_ var
+      steps:
+        - uses: actions/checkout@v3          # node20 → upgrade to @v4
+        - uses: actions/cache@v3             # node20 → upgrade to @v4
+        - uses: actions/upload-artifact@v3   # node20 → upgrade to @v4
+
+      # After: actions declaring using: node24 → no annotation
+      steps:
+        - uses: actions/checkout@v4          # node24 ✅
+        - uses: actions/cache@v4             # node24 ✅
+        - uses: actions/upload-artifact@v4   # node24 ✅
+  - language: yaml
+    label: "For your own action.yml — update to node24"
+    code: |
+      # action.yml — before
+      runs:
+        using: 'node20'
+        main: 'dist/index.js'
+
+      # action.yml — after
+      runs:
+        using: 'node24'
+        main: 'dist/index.js'
+      # Also recompile: ncc build src/index.ts --license licenses.txt
+  - language: yaml
+    label: "Temporary escape hatch — FORCE env var (annotation still appears)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            # Actions run on Node 24 but annotation still fires for node20 declarations
+            FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Pin to the latest major version of all official `actions/*` actions — they already ship `using: node24` in current releases."
+  - "Search your workflow files for `uses:` pins older than the current major version and update them in batch before Node 20 enforcement completes."
+  - "For private/internal actions, add a CI check that fails if any `action.yml` in the monorepo still declares `using: node20`."
+  - "Use `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true` only as a bridge, not a permanent solution — the annotation is a reminder that action.yml still needs updating."
+  - "Run periodic audits: `gh api /repos/ORG/REPO/contents/action.yml | jq .content | base64 -d | grep using`."
+docs:
+  - url: "https://github.com/actions/runner/issues/4295"
+    label: "actions/runner#4295: Node 20 deprecation warning fires even with FORCE_JAVASCRIPT_ACTIONS_TO_NODE24"
+  - url: "https://github.com/actions/runner/pull/4303"
+    label: "actions/runner#4303: Node 24 enforcement + Linux ARM32 deprecation support (fix)"
+  - url: "https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/"
+    label: "GitHub Changelog: Deprecation of Node 20 on GitHub Actions runners"
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
+    label: "Metadata syntax: runs.using for JavaScript actions"

package/errors/runner-environment/macos-26-homebrew-llvm-version-hardcoded.yml

@@ -0,0 +1,158 @@
+id: runner-environment-058
+title: "macOS 26 Homebrew LLVM Jumps 18 → 20 — Hardcoded llvm@18 Paths Fail"
+category: runner-environment
+severity: error
+tags:
+  - macos-26
+  - macos-latest
+  - llvm
+  - clang
+  - homebrew
+  - runner-image
+  - breaking-change
+  - cpp
+  - cmake
+patterns:
+  - regex: "no such file or directory.*homebrew.*opt.*llvm@(17|18)/bin"
+    flags: "i"
+  - regex: "clang(\\+\\+)?-(17|18).*command not found|No such file.*clang-(17|18)"
+    flags: "i"
+  - regex: "brew.*prefix.*llvm@(17|18).*Error.*no such keg"
+    flags: "i"
+  - regex: "Could not find.*LLVM (17|18).*Config\\.cmake"
+    flags: "i"
+  - regex: "llvm-config-(17|18).*not found"
+    flags: "i"
+error_messages:
+  - "zsh: no such file or directory: /opt/homebrew/opt/llvm@18/bin/clang++"
+  - "Error: clang-18: command not found"
+  - "Error: No such keg: /opt/homebrew/Cellar/llvm@18"
+  - "CMake Error at /opt/homebrew/lib/cmake/llvm/LLVMConfig.cmake: LLVM 18.1 required but 20.1 found"
+  - "llvm-config-18: not found"
+root_cause: |
+  When the `macos-latest` label migrated to macOS 26 Tahoe (beginning June 15, 2026),
+  the Homebrew-installed LLVM major version changed from **18.1.8** (on macOS 15) to
+  **20.1.8** (on macOS 26). This is a two-major-version jump that silently breaks any
+  workflow that hardcodes LLVM version numbers in paths, environment variables, or
+  CMake configuration.
+
+  **Affected patterns:**
+  - Shell scripts using `$(brew --prefix llvm@18)/bin/clang++` — the `llvm@18` keg no
+    longer exists on macOS 26; Homebrew returns "Error: No such keg"
+  - Workflows setting `CC=clang-18` or `CXX=clang++-18` — these binaries aren't
+    installed; the available binaries are `clang-20` and `clang++-20`
+  - CMake `find_package(LLVM 18 REQUIRED)` — succeeds on macOS 15 because Homebrew
+    LLVM 18 is present; fails on macOS 26 because only LLVM 20 is available
+  - `llvm-config-18 --version` in build scripts — the versioned binary doesn't exist
+  - `pkg-config --libs llvm-18` — the pkg-config file for llvm-18 is absent
+
+  **macOS 26 image ships with:**
+  - `llvm` formula → installs LLVM 20.x (unversioned `llvm` formula always tracks latest)
+  - `llvm@20` → available for explicit `brew install llvm@20`
+  - No `llvm@18` keg in the default image
+
+  Note: Workflows using the *unversioned* `llvm` or `clang` commands (e.g., `CC=clang`,
+  `$(brew --prefix llvm)/bin/clang++`) are NOT affected — they pick up the default
+  LLVM version on each image automatically.
+
+  Source: runner-images#14167 release diff table (Clang/LLVM 18.1.8 → 20.1.8);
+  community migration example: POCO C++ Libraries commit ff8174d (April 2026).
+fix: |
+  Replace all hardcoded `llvm@18` / `clang-18` references with either the unversioned
+  `llvm` formula path or the explicit `llvm@20` path on macOS 26.
+
+  **Option 1 — Use the unversioned Homebrew prefix (recommended):**
+  Replace `$(brew --prefix llvm@18)` with `$(brew --prefix llvm)` — this always resolves
+  to the current default LLVM, making the workflow future-proof.
+
+  **Option 2 — Explicit llvm@20 for reproducibility:**
+  Install `llvm@20` explicitly and reference it by version. This avoids future surprises
+  when `llvm` bumps to 21+.
+
+  **Option 3 — Pin to macos-15 temporarily:**
+  If the migration is not immediately feasible, pin to `macos-15` while updating your
+  build system to use the unversioned LLVM path.
+
+  **For CMake projects:** Remove the version constraint from `find_package(LLVM X REQUIRED)`
+  or use `find_package(LLVM REQUIRED)` and check the found version at configure time.
+fix_code:
+  - language: yaml
+    label: "Use unversioned llvm prefix — works across all macOS runner versions"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install LLVM
+              run: brew install llvm  # installs current default (llvm@20 on macOS 26)
+
+            - name: Build
+              run: |
+                # Use unversioned prefix — future-proof across LLVM major bumps
+                LLVM_PREFIX=$(brew --prefix llvm)
+                export CC="$LLVM_PREFIX/bin/clang"
+                export CXX="$LLVM_PREFIX/bin/clang++"
+                export LDFLAGS="-L$LLVM_PREFIX/lib"
+                export CPPFLAGS="-I$LLVM_PREFIX/include"
+                make -j$(sysctl -n hw.logicalcpu)
+  - language: yaml
+    label: "Explicit llvm@20 for reproducible macOS 26 builds"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest  # macOS 26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install LLVM 20
+              run: brew install llvm@20
+
+            - name: Configure and build
+              run: |
+                export CC="$(brew --prefix llvm@20)/bin/clang"
+                export CXX="$(brew --prefix llvm@20)/bin/clang++"
+                cmake -B build \
+                  -DCMAKE_C_COMPILER="$CC" \
+                  -DCMAKE_CXX_COMPILER="$CXX" \
+                  -DLLVM_DIR="$(brew --prefix llvm@20)/lib/cmake/llvm"
+                cmake --build build --parallel
+  - language: yaml
+    label: "CMake: remove version constraint from find_package(LLVM)"
+    code: |
+      # CMakeLists.txt — before
+      find_package(LLVM 18 REQUIRED CONFIG)
+
+      # CMakeLists.txt — after (accepts any version)
+      find_package(LLVM REQUIRED CONFIG)
+      message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+      # Optionally enforce a minimum version:
+      if(LLVM_VERSION_MAJOR LESS 18)
+        message(FATAL_ERROR "LLVM >= 18 required, got ${LLVM_PACKAGE_VERSION}")
+      endif()
+  - language: yaml
+    label: "Pin to macos-15 as temporary rollback while migrating"
+    code: |
+      jobs:
+        build:
+          # Temporary: macOS 15 still has llvm@18 via Homebrew
+          # TODO: migrate to unversioned llvm and switch back to macos-latest
+          runs-on: macos-15
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Never hardcode LLVM version numbers in Homebrew prefix paths. Use `$(brew --prefix llvm)` for the current default or `$(brew --prefix llvm@XX)` with an explicit install step for reproducibility."
+  - "In CMakeLists.txt, use `find_package(LLVM REQUIRED CONFIG)` without a version constraint, and validate the found version at configure time instead."
+  - "Test your macOS CI against `macos-26` (or `macos-latest` after it transitions) before the migration completes — use a matrix build to run both images in parallel."
+  - "Audit all workflow files for hardcoded `clang-XX`, `llvm@XX`, or `llvm-config-XX` strings when macOS runner images announce major tool version changes."
+  - "Subscribe to runner-images releases to monitor Homebrew LLVM version changes in the release diff tables."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images#14167: macos-latest will use macos-26 in June 2026 (diff table shows LLVM 18 → 20)"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md"
+    label: "macOS 26 arm64 image README — full software list including LLVM version"
+  - url: "https://docs.brew.sh/Versions"
+    label: "Homebrew Docs: Versioned formulae (llvm@18, llvm@20, etc.)"
+  - url: "https://cmake.org/cmake/help/latest/command/find_package.html"
+    label: "CMake find_package documentation"

package/errors/runner-environment/org-runner-group-dispatch-null.yml

@@ -0,0 +1,102 @@
+id: runner-environment-059
+title: "Org-Level Self-Hosted Runner in Group Never Dispatched — Job Queued Indefinitely"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted-runner
+  - runner-group
+  - org-runner
+  - queued
+  - dispatch
+
+patterns:
+  - regex: "no runner.*matching.*label.*self-hosted"
+    flags: "i"
+  - regex: "runner_group_id.*null"
+    flags: "i"
+
+error_messages:
+  - "Can't find any online and idle self-hosted runner in the current repository, account/organization that matches the required labels: 'self-hosted, <group-name>'"
+  - "Waiting for a runner to pick up this job..."
+
+root_cause: |
+  When a self-hosted runner is registered at the ORGANIZATION level and placed into
+  a runner group that has explicit repository access, the GitHub Actions dispatcher
+  sometimes fails to resolve the runner's group membership within the target
+  repository's scope. The job's metadata shows runner_group_id: null throughout the
+  entire wait period, meaning the internal broker never matched the org-level runner
+  to the queued job.
+
+  This affects runners using the V2 broker protocol
+  (broker.actions.githubusercontent.com) on GitHub Team and Enterprise plans.
+  The runner appears "Online" in the org settings, the runner group lists the target
+  repository as allowed, and the runs-on labels match — yet the job never starts.
+
+  Root technical cause: the dispatcher resolves runner group membership differently
+  for org-scoped runners vs. repo-scoped runners. When the runner is registered at
+  org scope, the broker does not propagate its group_id to the queued job record,
+  so no assignment occurs.
+
+fix: |
+  Short-term workaround (immediate):
+    Re-register the runner at the REPOSITORY level instead of the organization level.
+    This bypasses the group dispatch path and the job is assigned immediately.
+
+  Long-term fix:
+    1. Monitor GitHub Actions runner releases for a fix to org-level group dispatch.
+    2. Use GitHub-hosted larger runners or runner scale sets (Actions Runner Controller)
+       for org-level sharing — these use a different dispatch mechanism that is not
+       affected by this bug.
+    3. If org-level management is required, use runner groups with repo-scoped runner
+       registration and rely on group access policies to control visibility.
+
+fix_code:
+  - language: yaml
+    label: "Re-register runner at repository level (workaround)"
+    code: |
+      # 1. Remove the runner from the org-level runner list in GitHub UI:
+      #    Settings → Actions → Runners → (select runner) → Remove runner
+      #
+      # 2. Re-register the runner at the REPO level:
+      #    <repo> → Settings → Actions → Runners → New self-hosted runner
+      #    Follow setup commands shown in the UI.
+      #
+      # 3. Your workflow runs-on stays the same:
+      jobs:
+        build:
+          runs-on: [self-hosted, my-runner-label]
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: "Use Actions Runner Controller (ARC) for org-level runners"
+    code: |
+      # ARC scale sets are not affected by the org-runner group dispatch bug.
+      # Install the controller chart and create a runner scale set:
+      #
+      # helm install arc-runner-set \
+      #   --namespace arc-runners \
+      #   oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
+      #   --set githubConfigUrl=https://github.com/<org> \
+      #   --set githubConfigSecret.github_token=<token>
+      #
+      # Then reference in your workflow:
+      jobs:
+        build:
+          runs-on: arc-runner-set
+          steps:
+            - uses: actions/checkout@v4
+
+prevention:
+  - "Register self-hosted runners at repository level when possible to avoid org-level dispatch issues."
+  - "After registering a runner, trigger a test workflow immediately to confirm dispatch before relying on it in production."
+  - "Use Actions Runner Controller (ARC) scale sets for org-wide shared runners — ARC bypasses the runner group dispatch path."
+  - "Check runner_group_id via the API (`GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs`) when a job is stuck — null means dispatch failed at the broker level."
+
+docs:
+  - url: "https://github.com/actions/runner/issues/4429"
+    label: "actions/runner#4429 — Org-level runner never dispatched despite correct group access (May 2026)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs — Runner registration scopes"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow"
+    label: "GitHub Docs — Using self-hosted runners in a workflow"

package/errors/silent-failures/setup-python-pip-cache-macos26-annotation.yml

@@ -0,0 +1,110 @@
+id: silent-failures-027
+title: "actions/setup-python pip Cache on macOS 26 Emits False Error Annotation"
+category: silent-failures
+severity: warning
+tags:
+  - setup-python
+  - pip
+  - cache
+  - macos-26
+  - annotation
+  - false-positive
+  - python310
+patterns:
+  - regex: "ERROR.*WARNING.*Cache entry deserialization failed.*entry ignored"
+    flags: "i"
+  - regex: "Cache entry deserialization failed.*entry ignored"
+    flags: "i"
+  - regex: "Error: WARNING:.*cache.*deserialization"
+    flags: "i"
+error_messages:
+  - "Error: WARNING: Cache entry deserialization failed, entry ignored."
+  - "WARNING: Cache entry deserialization failed, entry ignored"
+root_cause: |
+  When using `actions/setup-python@v6` with `cache: 'pip'` and an older Python version
+  (notably Python 3.10) on `macos-26` runners, the action succeeds but emits a false
+  error annotation in the GitHub Actions UI, turning the job "yellow" or showing a red
+  annotation badge.
+
+  **What happens:**
+  1. `setup-python@v6` restores the pip cache from a previous run.
+  2. pip on the current macOS 26 runner (with a newer pip version) encounters a pip
+     wheel cache entry written by an older pip version using a different serialization
+     format or metadata schema.
+  3. pip emits: `WARNING: Cache entry deserialization failed, entry ignored` to stderr.
+  4. The GitHub Actions runner's annotation parser sees the word "Error" at the start
+     of the output (because the line is rendered as `Error: WARNING: ...` in GitHub's
+     log viewer) and creates an annotation treating it as a job error.
+  5. The job itself succeeds — the dependency install works fine — but the annotation
+     makes the job appear failed or degraded in the GitHub UI.
+
+  **Platform specificity:** This is reproducible specifically on `macos-26` (ARM), not
+  on Ubuntu, Windows, or `macos-15`. The combination of macOS 26's newer system Python
+  environment and the `macos-26` Arm64 pip wheel cache schema causes the deserialization
+  mismatch.
+
+  Source: actions/setup-python#1317 (open bug, May 20 2026 — under investigation by
+  actions/setup-python maintainers).
+fix: |
+  **Option 1 — Clear the stale pip cache (immediate fix):**
+  Purge the GitHub Actions cache for the affected key via the UI or API, forcing a cache
+  rebuild on the next run. The fresh cache will be written by the current pip version on
+  macOS 26 and will deserialize cleanly on subsequent runs.
+
+  **Option 2 — Disable pip caching for macOS 26 until resolved:**
+  Use a conditional `cache` input based on the runner OS:
+
+  **Option 3 — Pin to a Python version not affected:**
+  Python 3.12 and 3.14 have not been reported to exhibit this issue on macOS 26 — only
+  3.10 is confirmed. Test whether upgrading your target Python version resolves the annotation.
+
+  **Option 4 — Wait for the upstream fix:**
+  This is an open bug in `actions/setup-python` being investigated (issue #1317). A fix
+  in `setup-python@v6` will resolve this without workflow changes.
+fix_code:
+  - language: yaml
+    label: "Disable pip cache on macOS to avoid false error annotation"
+    code: |
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+          # Disable cache on macOS 26 until setup-python#1317 is resolved
+          cache: ${{ runner.os != 'macOS' && 'pip' || '' }}
+  - language: yaml
+    label: "Clear the stale cache via GitHub API (one-time fix)"
+    code: |
+      # Delete the stale pip cache key via gh CLI (run once)
+      gh cache list --repo owner/repo --key 'setup-python-*macos-26*'
+      gh cache delete <CACHE_ID> --repo owner/repo
+      # Or delete all pip caches for macOS 26:
+      gh cache list --repo owner/repo --json id,key --jq \
+        '.[] | select(.key | test("macos-26")) | .id' \
+        | xargs -I{} gh cache delete {} --repo owner/repo
+  - language: yaml
+    label: "Matrix build: cache only on platforms where it works cleanly"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-26]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/setup-python@v6
+              with:
+                python-version: "3.10"
+                # macOS 26 pip cache has deserialization issue (setup-python#1317)
+                cache: ${{ matrix.os != 'macos-26' && 'pip' || '' }}
+prevention:
+  - "Watch for `actions/setup-python` releases fixing issue #1317 — once resolved, re-enable caching on macOS 26."
+  - "When a new macOS runner label becomes `macos-latest`, clear pip caches from the old image version to avoid deserialization mismatches on the first run."
+  - "Test your workflows on new macOS runner labels before `macos-latest` transitions — catch cache format incompatibilities before they affect production CI."
+  - "Use GitHub's cache eviction API or `actions/cache@v4` with `fail-on-cache-miss: false` to gracefully handle deserialization failures."
+docs:
+  - url: "https://github.com/actions/setup-python/issues/1317"
+    label: "actions/setup-python#1317: Cache entry deserialization failed on macOS 26 (open bug)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#managing-caches"
+    label: "GitHub Docs: Managing GitHub Actions caches"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python — official action repository"

package/errors/triggers/workflow-run-checkout-uses-default-branch.yml

@@ -0,0 +1,114 @@
+id: triggers-019
+title: "workflow_run-Triggered Job Checks Out Default Branch, Not the Triggering PR's Branch"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - checkout
+  - default-branch
+  - silent-failure
+  - pull-request
+
+patterns:
+  - regex: "workflow_run.*head_branch"
+    flags: "i"
+  - regex: "github\\.event\\.workflow_run\\.head_branch"
+    flags: "i"
+
+error_messages:
+  - "# No error message — the job silently runs against the wrong branch (e.g., main instead of the PR's feature branch)"
+  - "HEAD is now at <main-branch-commit> — expected feature branch content not present"
+
+root_cause: |
+  When a workflow is triggered via `workflow_run`, the triggered workflow ALWAYS
+  runs in the context of the repository's DEFAULT branch, not the branch that
+  caused the original workflow to run.
+
+  This means that `actions/checkout` without an explicit `ref:` will check out
+  the default branch (e.g., `main`), even when the triggering workflow ran on a
+  feature branch or PR. The job may silently pass because it's testing old code
+  on `main` rather than the developer's new changes.
+
+  This is by design: `workflow_run` is intended for privileged workflows that
+  run in the base repository context regardless of where the triggering push came
+  from. It avoids giving fork PRs access to secrets — but it also means the
+  checkout behavior surprises developers expecting to test branch code.
+
+  The branch of the triggering workflow IS available via the event context:
+    `github.event.workflow_run.head_branch`
+    `github.event.workflow_run.head_sha`
+
+fix: |
+  Explicitly set the `ref:` in your `actions/checkout` step to the triggering
+  workflow's head commit SHA or branch name.
+
+  Use `head_sha` (not `head_branch`) for more precise pinning — branch names
+  can advance between trigger and checkout for busy repositories.
+
+fix_code:
+  - language: yaml
+    label: "Checkout the triggering workflow's exact commit"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI — Unit Tests"]
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Use head_sha for precise pinning — not head_branch
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+  - language: yaml
+    label: "Download artifacts from the triggering workflow run instead of re-checking out"
+    code: |
+      # For deployment workflows, prefer downloading the build artifact
+      # from the triggering run rather than re-building from source.
+      # This avoids the branch checkout problem entirely.
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                run-id: ${{ github.event.workflow_run.id }}
+                name: build-output
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Deploy
+              run: ./deploy.sh
+
+  - language: yaml
+    label: "Guard against running on wrong branch with a condition"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Only deploy when triggered from the main branch to avoid
+          # accidentally deploying non-main code
+          if: |
+            github.event.workflow_run.conclusion == 'success' &&
+            github.event.workflow_run.head_branch == 'main'
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+prevention:
+  - "Always specify ref: ${{ github.event.workflow_run.head_sha }} in checkout steps inside workflow_run-triggered jobs."
+  - "Prefer downloading build artifacts over re-checking-out source code in workflow_run jobs to avoid branch confusion."
+  - "Log github.event.workflow_run.head_branch and head_sha at the start of workflow_run jobs for debugging."
+  - "Use the conclusion check (if: github.event.workflow_run.conclusion == 'success') to avoid deploying failed builds."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs — workflow_run event"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#using-data-from-the-triggering-workflow"
+    label: "GitHub Docs — Using data from the triggering workflow"
+  - url: "https://stackoverflow.com/questions/76184351"
+    label: "SO#76184351 — workflow_run job runs on wrong (default) branch"

package/errors/yaml-syntax/reusable-workflow-nesting-depth-exceeded.yml

@@ -0,0 +1,113 @@
+id: yaml-syntax-024
+title: "Reusable Workflow Nesting Exceeds Maximum Depth of 4 Levels"
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflow
+  - nesting
+  - depth-limit
+  - workflow_call
+  - yaml-parse-error
+
+patterns:
+  - regex: "would exceed the limit on called workflow depth of \\d+"
+    flags: "i"
+  - regex: "calls workflow .+, but doing so would exceed the limit"
+    flags: "i"
+
+error_messages:
+  - "error parsing called workflow \"./.github/workflows/deploy.yml@\": job \"build\" calls workflow \"./.github/workflows/release.yml@\", but doing so would exceed the limit on called workflow depth of 3"
+  - "but doing so would exceed the limit on called workflow depth of 3"
+
+root_cause: |
+  GitHub Actions enforces a maximum reusable workflow call depth of 4 levels total.
+  The top-level workflow counts as level 1, so the maximum number of sequential
+  workflow_call hops is 3 (levels 2, 3, and 4).
+
+  The error message says "depth of 3" because it refers to the maximum allowed
+  zero-indexed depth of called workflows, not the total chain length.  When your
+  chain would require a 4th call (fifth total workflow), GitHub rejects the YAML
+  at parse time — before any runner picks up the job.
+
+  Example chain that fails:
+    root.yml → a.yml → b.yml → c.yml → d.yml   (depth index 4 → rejected)
+
+  Example chain that succeeds:
+    root.yml → a.yml → b.yml → c.yml            (depth index 3 → allowed)
+
+  This limit was increased from 2 to 3 in August 2022 and is currently fixed at 4
+  total levels (depth index 0–3).
+
+fix: |
+  Reduce the nesting depth so the total chain is 4 levels or fewer.
+  Strategies:
+
+  1. Flatten: merge two deeply-nested reusable workflows into one.
+  2. Convert inner reusables to composite actions — composite actions do NOT
+     count toward the reusable workflow depth limit.
+  3. Restructure so leaf workflows are composite actions, keeping reusable
+     workflows only at the top layers.
+
+fix_code:
+  - language: yaml
+    label: "Replace inner reusable workflow with a composite action"
+    code: |
+      # Instead of calling another reusable workflow at depth 4,
+      # use a composite action in .github/actions/my-task/action.yml
+      # which has no depth limit.
+
+      # .github/actions/my-task/action.yml
+      name: My Task
+      description: Previously a reusable workflow, now a composite action
+      runs:
+        using: composite
+        steps:
+          - name: Do the work
+            shell: bash
+            run: echo "doing the work"
+
+      # Called from the deeply-nested workflow:
+      - name: Run my task
+        uses: ./.github/actions/my-task  # composite, no depth counted
+
+  - language: yaml
+    label: "Flatten two reusable workflows into one to reduce depth"
+    code: |
+      # Before (depth 4 — fails):
+      # root.yml  →  build.yml  →  test.yml  →  lint.yml  →  scan.yml
+      #
+      # After (depth 3 — passes):
+      # Merge lint.yml and scan.yml into a single quality.yml
+
+      # quality.yml
+      on:
+        workflow_call:
+          inputs:
+            target:
+              required: true
+              type: string
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "linting ${{ inputs.target }}"
+        scan:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "scanning ${{ inputs.target }}"
+
+prevention:
+  - "Map your reusable workflow call chain before writing YAML — count total levels."
+  - "Prefer composite actions for leaf-level tasks; they have no depth limit."
+  - "Limit reusable workflow use to high-value shared orchestration layers, not every step."
+  - "If depth 4 is genuinely required, consider splitting the pipeline into separate triggered workflows using workflow_run instead of nested workflow_call."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/reusing-workflows#nesting-reusable-workflows"
+    label: "GitHub Docs — Nesting reusable workflows"
+  - url: "https://github.blog/changelog/2022-08-22-github-actions-improvements-to-reusable-workflows-2/"
+    label: "GitHub Changelog — Nesting increased to 4 levels (August 2022)"
+  - url: "https://github.com/actions/runner/issues/1797"
+    label: "actions/runner#1797 — Original depth-limit enhancement request"

package/package.json

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