@htekdev/actions-debugger 1.0.23 → 1.0.25

package/errors/runner-environment/macos-latest-label-switches-to-macos26.yml

@@ -0,0 +1,127 @@
+id: runner-environment-064
+title: "macos-latest Label Switching to macOS 26 — Toolchain and Brew Package Changes"
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - macos-latest
+  - macos-26
+  - runner-label
+  - homebrew
+  - toolchain
+  - migration
+patterns:
+  - regex: "macos.*26.*not supported"
+    flags: "i"
+  - regex: "No such file or directory.*clang|clang.*not found"
+    flags: "i"
+  - regex: "dyld.*Library not loaded"
+    flags: "i"
+  - regex: "Error: Cannot install in Homebrew on macOS.*without Command Line Tools"
+    flags: "i"
+  - regex: "macos-latest.*macos-26"
+    flags: "i"
+error_messages:
+  - "clang: error: no such file or directory"
+  - "dyld[12345]: Library not loaded: /usr/local/lib/libssl.1.1.dylib"
+  - "Error: Your CLT does not support macOS 26."
+  - "xcrun: error: SDK 'iphoneos' cannot be located"
+root_cause: |
+  Starting June 15, 2026, the `macos-latest` runner label is being migrated
+  from macOS 15 (Sequoia) to macOS 26 (runner-images#14167). The rollout
+  runs through July 15, 2026. Workflows pinned to `macos-latest` without
+  testing on macOS 26 may encounter failures from toolchain and package
+  differences between the two OS versions.
+
+  Key differences in macOS 26 runner images compared to macOS 15:
+
+  1. **Homebrew LLVM version bump**: LLVM jumped from 18 to 20 on macOS 26.
+     Hardcoded paths like `/opt/homebrew/opt/llvm@18/bin/clang` or env vars
+     referencing `llvm@18` binaries fail. POCO and other libraries built
+     against LLVM 18 ABI may link incorrectly.
+
+  2. **macOS SDK changes**: macOS 26 uses a newer Xcode and SDK toolchain.
+     Libraries and headers that existed in macOS 15 SDK may have moved,
+     been renamed, or removed under the macOS 26 (Tahoe) SDK.
+
+  3. **Homebrew formula versions**: Many Homebrew packages have newer
+     versions on macOS 26 images than on macOS 15. Formulas with no macOS 26
+     bottle may be built from source, increasing job time significantly.
+
+  4. **System library locations**: Dynamic library paths (e.g., for OpenSSL,
+     libpq, or other system libs installed via Homebrew) may differ between
+     macOS 15 and macOS 26 as Homebrew evolves its prefix structure.
+
+  5. **Xcode simulator SDK policy**: Only the 3 latest Xcode versions retain
+     platform tools/SDKs. Workflows using older Xcode/simulator versions
+     that worked on macOS 15 may not find the expected SDK on macOS 26.
+
+  Workflows that do not pin `macos-latest` and have never tested on macOS 26
+  may start failing after the migration completes.
+fix: |
+  1. **Pin to macOS 15 temporarily**: Replace `macos-latest` with `macos-15`
+     to preserve the current behavior while you test and migrate.
+
+  2. **Test on macOS 26 before migration**: Add a matrix job with
+     `macos-26` to identify failures before `macos-latest` switches.
+
+  3. **Fix hardcoded LLVM/Clang paths**: Update any hardcoded paths like
+     `/opt/homebrew/opt/llvm@18` to use `$(brew --prefix llvm)` or install
+     the specific version you need via `brew install llvm@18`.
+
+  4. **Update Homebrew formula pins**: Check for `@version`-pinned Homebrew
+     formulas that may no longer have macOS 26 bottles and either upgrade
+     or build from source explicitly.
+
+  5. **Audit system library dependencies**: For native extensions that link
+     against system or Homebrew libraries, verify library paths with
+     `brew --prefix <lib>` at runtime rather than hardcoding them.
+fix_code:
+  - language: yaml
+    label: "Pin to macos-15 while testing macOS 26 compatibility"
+    code: |
+      jobs:
+        build:
+          # Temporarily pin to macos-15 while migration is in progress
+          # macos-latest will point to macos-26 starting June 15, 2026
+          runs-on: macos-15
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "Matrix to test both macOS 15 and 26 before migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [macos-15, macos-26]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "Use brew --prefix to resolve dynamic LLVM/library paths"
+    code: |
+      - name: Set up LLVM paths dynamically
+        run: |
+          # Instead of hardcoded /opt/homebrew/opt/llvm@18/bin/clang:
+          LLVM_PREFIX=$(brew --prefix llvm)
+          echo "CC=${LLVM_PREFIX}/bin/clang" >> $GITHUB_ENV
+          echo "CXX=${LLVM_PREFIX}/bin/clang++" >> $GITHUB_ENV
+          echo "${LLVM_PREFIX}/bin" >> $GITHUB_PATH
+prevention:
+  - "Never use macos-latest without testing the next macOS version first — GitHub announces label migrations weeks in advance in runner-images issues."
+  - "Pin to a specific macOS version (e.g., macos-15) for production workflows; use macos-latest only in exploratory or dependency-update workflows."
+  - "Avoid hardcoding Homebrew formula paths — always use `$(brew --prefix <formula>)` to resolve paths dynamically."
+  - "Run a matrix job spanning current and next macOS versions as part of your CI to catch breakage before a label migration lands."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images #14167: macos-latest will use macos-26 starting June 15, 2026"
+  - url: "https://github.blog/changelog/2026-05-14-github-actions-upcoming-image-migrations/"
+    label: "GitHub Changelog: Upcoming image migrations (May 2026)"
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images announcement: macOS 14 deprecation starting July 6, 2026"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "GitHub Docs: Standard GitHub-hosted runners — available runner labels"

package/errors/runner-environment/maven-gradle-403-cache-backend-outage.yml

@@ -0,0 +1,116 @@
+id: runner-environment-075
+title: "Maven/Gradle 403 Forbidden when GitHub Actions cache backend is degraded"
+category: runner-environment
+severity: error
+tags:
+  - maven
+  - gradle
+  - 403
+  - cache-backend
+  - outage
+  - rate-limit
+  - sonatype
+  - dependency-download
+
+patterns:
+  - regex: "Received status code 403 from server"
+    flags: "i"
+  - regex: "Could not transfer artifact .+ from .+ Forbidden"
+    flags: "i"
+  - regex: "Our services aren't available right now"
+    flags: "i"
+  - regex: "Received HTTP 403 from Maven Repository"
+    flags: "i"
+
+error_messages:
+  - "Could not transfer artifact org.springframework:spring-core:jar:6.1.0 from/to central (https://repo.maven.apache.org/maven2): Received status code 403 from server: Forbidden"
+  - "Received status code 403 from server: Forbidden"
+  - "Our services aren't available right now\nWe're working to restore all services as soon as possible. Please check back soon."
+  - "Exception in thread \"main\" org.gradle.api.UncheckedIOException: com.amazonaws.SdkClientException: Unable to execute HTTP request: The target server failed to respond"
+
+root_cause: |
+  GitHub Actions cache backend (actions/cache) is an eventually-consistent distributed storage
+  system. During degradation incidents, cache restore operations fail with the message
+  "Our services aren't available right now" and exit 0 (the job continues). Maven and Gradle
+  builds that normally cache artifacts under .m2/repository or .gradle/caches fall through
+  to downloading all dependencies directly from Maven Central (repo.maven.apache.org).
+
+  GitHub-hosted runners share IP address ranges across thousands of concurrent workflow runs.
+  During a cache backend outage, every affected build simultaneously requests artifacts
+  from Maven Central. Sonatype (which operates Maven Central) rate-limits abusive traffic
+  patterns from shared IP ranges, returning HTTP 403 Forbidden. This creates a cascading
+  failure: one cache service incident causes all Java/Kotlin/Scala CI pipelines to fail
+  until the cache backend recovers.
+
+  The failure is misleading because the error comes from Maven Central, not GitHub, so
+  developers often suspect repository permissions, network configuration, or Sonatype policy
+  changes rather than GitHub infrastructure.
+
+fix: |
+  Short-term: Check GitHub Status (githubstatus.com) for cache service incidents before
+  debugging Maven/Gradle configuration. Retry the workflow after the incident resolves.
+
+  Medium-term: Add Maven retry configuration to pom.xml or build.gradle to tolerate
+  transient 403/429 responses. Configure a secondary mirror as a fallback to reduce
+  direct Maven Central dependency.
+
+  Long-term: Host a private artifact cache (Nexus, Artifactory, or AWS CodeArtifact)
+  that proxies Maven Central. This prevents GitHub runner IP ranges from hitting Maven
+  Central directly and provides a stable fallback during GitHub cache outages.
+
+fix_code:
+  - language: yaml
+    label: "Workflow: Add retry wrapper step for Maven builds during cache degradation"
+    code: |
+      steps:
+        - uses: actions/cache@v4
+          id: maven-cache
+          with:
+            path: ~/.m2/repository
+            key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+            restore-keys: |
+              ${{ runner.os }}-maven-
+
+        - name: Check cache status and set retry flag
+          if: steps.maven-cache.outputs.cache-hit != 'true'
+          run: echo "MAVEN_OPTS=-Dmaven.artifact.threads=5" >> $GITHUB_ENV
+
+        - name: Build with Maven
+          run: mvn --batch-mode --no-transfer-progress -T 1C verify
+
+  - language: yaml
+    label: "Maven settings.xml: Add mirror fallback to reduce direct Maven Central load"
+    code: |
+      # .github/maven-settings.xml — add to repository root
+      # Reference in workflow: mvn -s .github/maven-settings.xml ...
+      #
+      # <settings>
+      #   <mirrors>
+      #     <mirror>
+      #       <id>central-mirror</id>
+      #       <mirrorOf>central</mirrorOf>
+      #       <url>https://repo1.maven.org/maven2/</url>
+      #     </mirror>
+      #   </mirrors>
+      # </settings>
+      #
+      # Then in workflow:
+      - name: Build with Maven (mirror fallback)
+        run: mvn -s .github/maven-settings.xml --batch-mode verify
+
+prevention:
+  - "Monitor githubstatus.com/history for GitHub Actions cache incidents before assuming build failures are configuration errors."
+  - "Add --no-transfer-progress to Maven commands to reduce output noise; add -Dmaven.artifact.threads=3 to reduce concurrent Central requests."
+  - "Configure restore-keys fallback in actions/cache so partial cache hits reduce Maven Central traffic."
+  - "Consider self-hosted Nexus or AWS CodeArtifact as a Maven Central proxy for production CI pipelines."
+  - "Add 'if: always()' or cache-miss detection to skip cache restore wait during known outages."
+
+docs:
+  - url: "https://github.com/actions/runner/issues/4180"
+    label: "actions/runner#4180: CI Runners Failing with 403 Forbidden for Maven/Gradle (75 reactions)"
+  - url: "https://www.githubstatus.com/"
+    label: "GitHub Status — check for Actions cache service incidents"
+  - url: "https://central.sonatype.org/faq/rate-limiting/"
+    label: "Sonatype Maven Central: Rate limiting and fair use policy"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs: Caching dependencies to speed up workflows"

package/errors/runner-environment/node20-removed-toolcache-default-node22.yml

@@ -0,0 +1,104 @@
+id: runner-environment-062
+title: "Node.js 20 Removed from Toolcache — Default Node.js Changed to 22"
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node20
+  - node22
+  - toolcache
+  - eol
+  - setup-node
+  - runner-images
+patterns:
+  - regex: "node: not found"
+    flags: "i"
+  - regex: "node: No such file or directory"
+    flags: "i"
+  - regex: "Downloading Node\\.js (20\\.[0-9]+\\.[0-9]+)"
+    flags: "i"
+  - regex: "engines.*node.*>=\\s*20"
+    flags: "i"
+  - regex: "error node_modules.*requires node.*20"
+    flags: "i"
+error_messages:
+  - "node: not found"
+  - "Downloading Node.js 20.x.x (not pre-installed, downloading on demand)"
+  - "error: The engine 'node' is incompatible with this module. Expected version '^20.0.0'. Got '22.x.x'"
+  - "The engine 'node' is incompatible with this module. Expected version '>=20 <21'. Got '22.14.0'"
+root_cause: |
+  Node.js 20 reached end-of-life on April 30, 2026. Starting with runner image
+  updates rolled out May 19–26, 2026, Node.js 20 was removed from the toolcache
+  on ALL GitHub-hosted runner images (ubuntu-22.04, ubuntu-24.04, ubuntu-26.04,
+  macos-14, macos-15, macos-26, windows-2022, windows-2025, and ARM variants).
+
+  Two distinct impacts:
+
+  1. **Default Node.js version changed**: On runners where Node.js 20 was
+     previously the default (e.g., ubuntu-22.04, ubuntu-24.04, windows-2022,
+     macos-14), the default is now Node.js 22 (Maintenance LTS). Workflows
+     that call `node` or `npm` without an explicit `actions/setup-node` step
+     will now run on Node.js 22, potentially breaking packages with strict
+     engines constraints like `"node": "^20.0.0"`.
+
+  2. **setup-node now downloads Node.js 20**: If a workflow pins
+     `node-version: '20'` via `actions/setup-node`, it will no longer find
+     Node.js 20 in the toolcache and must download it on demand. This adds
+     download time and may fail if the registry is rate-limited or the runner
+     has no internet access (self-hosted runners with air-gapped environments).
+
+  Only Node.js 22 and Node.js 24 remain pre-installed in the toolcache on all
+  runner images after this change.
+fix: |
+  Option 1 — Upgrade to Node.js 22 or 24 (recommended):
+    Update your project to support Node.js 22 (current Maintenance LTS) or
+    Node.js 24 (Active LTS). Update package.json engines field, run tests on
+    the new version, and remove the explicit node-version pin (or update it).
+
+  Option 2 — Pin to Node.js 20 via setup-node (temporary):
+    If you cannot migrate yet, explicitly install Node.js 20 on every job
+    using `actions/setup-node`. Node.js 20 is still downloadable on demand —
+    it just won't be pre-cached. This will slow down your workflow.
+
+  Option 3 — Test with FORCE_JAVASCRIPT_ACTIONS_TO_NODE24:
+    Set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` as a workflow env to test
+    how your action runtime behaves on Node.js 24 before fully migrating.
+fix_code:
+  - language: yaml
+    label: "Upgrade to Node.js 22 (recommended)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'    # Node.js 22 is Maintenance LTS through 2026
+          cache: 'npm'
+  - language: yaml
+    label: "Pin Node.js 20 temporarily (still downloadable on demand)"
+    code: |
+      - name: Set up Node.js 20 (no longer pre-cached — will download)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'    # EOL 2026-04-30; plan your migration to v22
+          cache: 'npm'
+  - language: yaml
+    label: "Use .nvmrc / .node-version to pin version in project root"
+    code: |
+      - name: Set up Node.js from .nvmrc
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'    # Update .nvmrc to 22 or 24
+          cache: 'npm'
+prevention:
+  - "Always specify an explicit node-version in actions/setup-node — never rely on the runner's ambient Node.js version."
+  - "Set `node-version-file: '.nvmrc'` and commit a .nvmrc file so all environments (local, CI, containers) use the same version."
+  - "Watch the runner-images Announcements tab for future EOL removals — set up GitHub notifications for the actions/runner-images repo."
+  - "Use `engines` in package.json with a range like `>=22 <25` to catch version incompatibilities in CI early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14029"
+    label: "runner-images #14029: Node.js 20 removed, default changed to 22"
+  - 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://github.com/nodejs/release#readme"
+    label: "Node.js Release Schedule (EOL dates)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-installed-software#nodejs-versions"
+    label: "GitHub Docs: Using pre-installed software — Node.js versions"

package/errors/runner-environment/powershell-74-76-threadjob-module-rename.yml

@@ -0,0 +1,124 @@
+id: runner-environment-063
+title: "PowerShell 7.4 → 7.6 LTS Upgrade Breaks ThreadJob Module Name and .NET Runtime"
+category: runner-environment
+severity: warning
+tags:
+  - powershell
+  - powershell-76
+  - threadjob
+  - dotnet10
+  - runner-images
+  - breaking-change
+  - module
+patterns:
+  - regex: "The term 'ThreadJob\\\\Start-ThreadJob' is not recognized"
+    flags: "i"
+  - regex: "CommandNotFoundException.*ThreadJob"
+    flags: "i"
+  - regex: "Cannot find module.*ThreadJob"
+    flags: "i"
+  - regex: "Join-Path.*cannot process argument transformation on parameter 'ChildPath'"
+    flags: "i"
+  - regex: "PowerShell.*7\\.4.*not found"
+    flags: "i"
+error_messages:
+  - "The term 'ThreadJob\\Start-ThreadJob' is not recognized as a name of a cmdlet, function, script file, or executable program."
+  - "Cannot find module ThreadJob"
+  - "Join-Path: Cannot process argument transformation on parameter 'ChildPath'."
+  - "Get-Module: The specified module 'ThreadJob' was not found"
+root_cause: |
+  GitHub Actions runner images are being updated from PowerShell 7.4.x to 7.6.x
+  (the latest LTS release, based on .NET 10) across all runner images between
+  June 8–15, 2026 (runner-images#14150). PowerShell 7.6 is a major.minor
+  version upgrade from 7.4 and contains several breaking changes:
+
+  1. **ThreadJob module renamed**: The `ThreadJob` module has been replaced by
+     `Microsoft.PowerShell.ThreadJob`. The `Start-ThreadJob` cmdlet itself is
+     unchanged, but any script using the module-qualified name
+     `ThreadJob\Start-ThreadJob` will throw a CommandNotFoundException because
+     the old module name no longer exists. Scripts that call `Start-ThreadJob`
+     without the module prefix continue to work.
+
+  2. **Join-Path -ChildPath is now string[]**: The `-ChildPath` parameter type
+     changed from `string` to `string[]`. In most cases this is backward-
+     compatible, but scripts with unusual argument binding patterns or that
+     pass a typed `[string]` variable explicitly may encounter parameter
+     transformation errors.
+
+  3. **.NET 10 runtime**: PowerShell 7.6 ships on .NET 10 (7.4 was on .NET 8).
+     Scripts that load .NET assemblies, use P/Invoke, or invoke .NET API
+     members that changed between .NET 8 and .NET 10 may break silently
+     or throw runtime exceptions.
+
+  4. **WildcardPattern.Escape behavior change**: `WildcardPattern.Escape` now
+     correctly escapes lone backticks. Scripts that relied on the old (incorrect)
+     no-escape behavior may produce different wildcard pattern results.
+
+  5. **Trailing space removed from event source name**: Scripts that match
+     exact event source names (e.g., for Windows Event Log) may fail to find
+     the source if they include a trailing space.
+fix: |
+  1. Replace module-qualified ThreadJob references:
+     Find all occurrences of `ThreadJob\Start-ThreadJob` in your scripts and
+     update them to `Microsoft.PowerShell.ThreadJob\Start-ThreadJob` or simply
+     use the unqualified `Start-ThreadJob`.
+
+  2. Review Join-Path usage:
+     Scripts using `Join-Path` with `-ChildPath` should continue to work in
+     most cases. If you see parameter binding errors, check that you are not
+     passing a typed `[string]` variable in a context that is now ambiguous.
+
+  3. Test .NET assembly loading:
+     If your scripts load .NET assemblies via `Add-Type -Path` or
+     `[System.Reflection.Assembly]::LoadFrom()`, test them against .NET 10
+     to catch any API compatibility issues before the upgrade rolls out.
+
+  4. Pin PowerShell version (temporary workaround):
+     Until migration is complete, you can install a specific PowerShell version
+     via the MSI/package manager in a workflow step. This is a temporary
+     workaround and should not be the long-term solution.
+fix_code:
+  - language: yaml
+    label: "Fix module-qualified ThreadJob reference"
+    code: |
+      # Before (PowerShell 7.4 — breaks on 7.6):
+      # $job = ThreadJob\Start-ThreadJob -ScriptBlock { ... }
+      #
+      # After (works on both 7.4 and 7.6):
+      - name: Run threaded job
+        shell: pwsh
+        run: |
+          # Option A: unqualified (works on all versions)
+          $job = Start-ThreadJob -ScriptBlock { Get-Process }
+          
+          # Option B: fully qualified with new module name (7.6+)
+          $job = Microsoft.PowerShell.ThreadJob\Start-ThreadJob -ScriptBlock { Get-Process }
+          
+          $result = $job | Wait-Job | Receive-Job
+          Write-Output $result
+  - language: yaml
+    label: "Verify PowerShell version in workflow to detect future upgrades early"
+    code: |
+      - name: Check PowerShell version
+        shell: pwsh
+        run: |
+          $version = $PSVersionTable.PSVersion
+          Write-Output "PowerShell version: $version"
+          if ($version.Major -lt 7 -or ($version.Major -eq 7 -and $version.Minor -lt 6)) {
+            Write-Warning "PowerShell < 7.6 detected — ensure ThreadJob references use unqualified names"
+          }
+prevention:
+  - "Use unqualified cmdlet names (Start-ThreadJob, not ThreadJob\\Start-ThreadJob) to avoid module-name dependencies."
+  - "Add a PowerShell version check step at the start of complex pwsh workflows to detect unexpected upgrades early."
+  - "Test workflows against the next PowerShell LTS version in a matrix before the runner image upgrade lands."
+  - "Subscribe to GitHub notifications on actions/runner-images to receive Announcement issues for upcoming breaking changes."
+  - "Avoid loading .NET assemblies by absolute path in runner workflows — prefer NuGet package installation to ensure .NET runtime compatibility."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14150"
+    label: "runner-images #14150: PowerShell will be updated from 7.4 to 7.6 LTS (Jun 8-15 2026)"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-76"
+    label: "PowerShell 7.6 Release Notes — breaking changes"
+  - url: "https://github.com/PowerShell/PowerShell/releases/tag/v7.6.0"
+    label: "PowerShell v7.6.0 GitHub release"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle"
+    label: "PowerShell support lifecycle"

package/errors/runner-environment/self-hosted-runner-not-found.yml

@@ -0,0 +1,134 @@
+id: runner-environment-067
+title: "Self-Hosted Runner 'An error occurred: Runner not found'"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - runner
+  - runner-not-found
+  - jit
+  - registration
+  - ephemeral
+patterns:
+  - regex: "An error occurred: Runner not found"
+    flags: "i"
+  - regex: "Runner not found"
+    flags: "i"
+  - regex: "No runner matching the specified criteria was found"
+    flags: "i"
+  - regex: "Could not find any runner that matches the selector"
+    flags: "i"
+error_messages:
+  - "An error occurred: Runner not found"
+  - "Error: An error occurred: Runner not found"
+  - "No runner matching the specified criteria was found"
+root_cause: |
+  "An error occurred: Runner not found" is a vague error emitted by the
+  GitHub Actions broker when it cannot match or allocate a self-hosted runner
+  for a queued job. It has multiple distinct root causes:
+
+  1. **JIT (Just-in-Time) token expiry** (most common with ARC/Kubernetes runners):
+     Ephemeral runners provisioned via Just-in-Time tokens have a short registration
+     window. If the runner process does not connect within the token validity period
+     (~60 seconds), the broker discards the registration and emits "Runner not found"
+     when the job is dispatched. This particularly affects actions-runner-controller
+     (ARC) on Kubernetes when pod startup time exceeds the JIT window.
+
+  2. **Runner de-registered before job starts**:
+     Autoscaling controllers (ARC, custom scripts) that aggressively recycle idle
+     runners may de-register the runner in the brief window between job queue and
+     job dispatch. The broker finds no runner for the job's labels.
+
+  3. **Label mismatch**:
+     The workflow specifies `runs-on: [self-hosted, linux, x64]` but the registered
+     runner has different labels (e.g., just `[self-hosted, linux]`). The broker
+     treats this as "no matching runner found" and emits the same vague error.
+
+  4. **Runner registered at wrong scope**:
+     A runner registered at the organization level is not visible to a repository
+     not in that runner's group, or vice versa. Org runner group access policy
+     may restrict which repos can use the runner.
+
+  5. **Concurrent job stealing**:
+     In autoscaling pools where multiple runners share the same label set, a
+     job token issued to one runner is occasionally "stolen" by another — the
+     original runner's job token is invalid when it tries to start. Less common
+     but documented in high-concurrency pools (actions/runner#3857, 116 reactions).
+
+  The error is intentionally vague because it covers multiple broker-side failures
+  that are indistinguishable from the runner's perspective.
+fix: |
+  Diagnose by checking the runner registration logs first:
+
+  1. **For JIT token expiry (ARC/Kubernetes)**:
+     Reduce pod startup time — use pre-pulled images, smaller base images, or
+     warm pools. Alternatively, switch to Long-Running runners (PAT/App-registered)
+     which don't have JIT token windows. Check actions-runner-controller v0.9+
+     which extended the JIT window.
+
+  2. **For de-registered runner race condition**:
+     Add a grace period to your autoscaler before de-registering idle runners —
+     at least 60 seconds after a job completes. Use `--once` flag on ephemeral
+     runners so they only exit after completing one job, not before.
+
+  3. **For label mismatch**:
+     Run `gh api repos/{owner}/{repo}/actions/runners --jq '.[].labels'` to inspect
+     registered runner labels. Compare against the `runs-on:` in your workflow.
+     Labels are case-sensitive and must be an exact subset match.
+
+  4. **For wrong scope (org vs repo)**:
+     Check Settings → Actions → Runners in both the repo and org. Confirm the
+     runner appears under the correct scope and the runner group allows access
+     to the repository.
+
+  5. **General debugging**:
+     Enable runner diagnostic logs by setting `ACTIONS_RUNNER_DEBUG: true` and
+     `ACTIONS_STEP_DEBUG: true` as repository secrets. This enables verbose
+     broker negotiation logs in the Actions runner output.
+fix_code:
+  - language: yaml
+    label: "Enable runner diagnostic logs to capture broker negotiation details"
+    code: |
+      # Add these as repository secrets (Settings → Secrets → Actions):
+      # ACTIONS_RUNNER_DEBUG = true
+      # ACTIONS_STEP_DEBUG = true
+
+      # Then re-run the failing job. The runner logs will include:
+      # "Checking runner for labels: [self-hosted, linux, x64]"
+      # "Connected to GitHub Actions service"
+      # "Received job assignment: ..."
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner labels verified"
+  - language: yaml
+    label: "Verify registered runner labels via GitHub API"
+    code: |
+      # Check what labels your self-hosted runners actually have:
+      # gh api repos/{owner}/{repo}/actions/runners --jq '.runners[] | {name: .name, labels: [.labels[].name]}'
+      # Example output:
+      # {"name": "my-runner", "labels": ["self-hosted", "Linux", "X64"]}
+      # Note: Labels are case-sensitive — "Linux" != "linux"
+
+      # Workflow label must match runner label exactly:
+      jobs:
+        build:
+          # Use exact case matching the runner's registered labels:
+          runs-on: [self-hosted, Linux, X64]
+prevention:
+  - "Use explicit, versioned runner labels instead of generic `self-hosted` to make label mismatches immediately visible in the runner registration."
+  - "For ephemeral/JIT runners on Kubernetes, use pre-pulled base images and resource requests that ensure fast pod startup to avoid JIT token expiry."
+  - "Add ACTIONS_RUNNER_DEBUG=true as a repository secret during initial setup to capture detailed registration logs before the runner goes into production."
+  - "Implement health monitoring on your self-hosted runner pool — alert when the runner count drops below the minimum needed for your queue depth."
+  - "Prefer Long-Running runners over JIT ephemeral runners for workflows with unpredictable startup patterns — JIT token windows are unforgiving on slow infrastructure."
+docs:
+  - url: "https://github.com/actions/runner/issues/3857"
+    label: "actions/runner #3857: 'An error occurred: Runner not found' (116 reactions)"
+  - 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/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners"
+    label: "GitHub Docs: Using labels with self-hosted runners"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners"
+    label: "GitHub Docs: Security hardening for self-hosted runners"