@htekdev/actions-debugger 1.0.3 → 1.0.5

package/errors/concurrency-timing/job-stuck-waiting-for-runner.yml

@@ -0,0 +1,105 @@
+id: concurrency-timing-006
+title: "Job Stuck: 'Waiting for a Runner to Pick Up This Job'"
+category: concurrency-timing
+severity: error
+tags:
+  - runner
+  - runs-on
+  - self-hosted
+  - queued
+  - stuck
+  - deprecated-runner
+patterns:
+  - regex: "Waiting for a runner to pick up this job"
+    flags: "i"
+  - regex: "No runner matching the specified labels"
+    flags: "i"
+  - regex: "Could not find any online and idle runners"
+    flags: "i"
+error_messages:
+  - "Waiting for a runner to pick up this job."
+  - "No runner matching the specified labels was found: [your-label]"
+  - "Could not find any online and idle runners matching the required labels."
+root_cause: |
+  A job remains stuck in the "queued" state — showing "Waiting for a runner to pick up
+  this job" — when GitHub Actions cannot find an available runner matching the `runs-on:`
+  labels. The job will wait indefinitely until the `timeout-minutes` limit is reached.
+
+  The most common causes:
+
+  1. **Deprecated or retired runner label** — GitHub periodically retires old runner images.
+     `ubuntu-18.04` was retired in April 2023. `ubuntu-20.04` deprecation is in progress.
+     Jobs using these labels get stuck because no GitHub-hosted runners serve the label.
+
+  2. **Typo in `runs-on:` label** — `ubuntu-latets`, `ubuntu_latest`, `UBuntu-latest` all
+     fail silently. GitHub-hosted label matching is case-sensitive for custom labels.
+
+  3. **Self-hosted runner offline or de-registered** — the runner was stopped, the service
+     was not restarted after a reboot, or the runner registration token expired. GitHub queues
+     the job and waits for a registered runner with matching labels to come online.
+
+  4. **Runner group restrictions** — organization admins restrict which repositories can use
+     which runner groups. A job referencing a group the repository is not authorized for will
+     queue indefinitely without an explicit permission error.
+
+  5. **All runners busy** — all matching runners are executing other jobs. The job correctly
+     queues but appears "stuck" during peak usage. It will eventually be picked up.
+
+  There is no notification when a job has been queued for an unusually long time — the only
+  signal is the job's wall-clock age and the static "Waiting for a runner" message.
+fix: |
+  Verify the `runs-on:` label against the current list of supported GitHub-hosted runner
+  images. For self-hosted runners, check runner registration and service health.
+fix_code:
+  - language: yaml
+    label: "Use current, non-deprecated GitHub-hosted runner labels"
+    code: |
+      jobs:
+        build:
+          # Use current supported labels only
+          runs-on: ubuntu-latest     # OR ubuntu-22.04, ubuntu-24.04
+          # NOT: ubuntu-18.04 (retired), ubuntu-20.04 (deprecated)
+
+        build-windows:
+          runs-on: windows-latest   # OR windows-2022, windows-2025
+
+        build-macos:
+          runs-on: macos-latest     # OR macos-13, macos-14, macos-15
+  - language: yaml
+    label: "Self-hosted runner — verify registration and labels match exactly"
+    code: |
+      jobs:
+        deploy:
+          # Labels must exactly match what the runner was registered with
+          # Check: GitHub Settings → Actions → Runners → click runner → Labels
+          runs-on: [self-hosted, linux, production]
+
+          steps:
+            - name: Verify runner is the expected host
+              run: echo "Running on $RUNNER_NAME at $(hostname)"
+  - language: yaml
+    label: "Fallback: matrix across hosted and self-hosted runners"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              runner: [ubuntu-latest, [self-hosted, linux]]
+          runs-on: ${{ matrix.runner }}
+prevention:
+  - "Audit `runs-on:` labels in all workflows when GitHub announces runner image deprecations."
+  - "Set a job-level `timeout-minutes` so stuck jobs don't consume queue slots indefinitely."
+  - "For self-hosted runners, configure the runner service to auto-restart on reboot (e.g., `--service` install on Linux via `./svc.sh install`)."
+  - "Use GitHub's runner status page (Settings → Actions → Runners) to verify runners are Online before triggering long jobs."
+  - "Subscribe to GitHub Changelog and Actions deprecation notices to catch retiring runner labels early."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "Supported GitHub-hosted runner labels"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners"
+    label: "Adding self-hosted runners"
+  - url: "https://stackoverflow.com/questions/70959954/error-waiting-for-a-runner-to-pick-up-this-job-using-github-actions"
+    label: "Stack Overflow: Waiting for a runner to pick up this job"
+  - url: "https://github.com/actions/runner/issues/3609"
+    label: "actions/runner#3609 — Self-hosted runner stuck / deadlock"
+  - url: "https://github.com/orgs/community/discussions/147604"
+    label: "Community: Workflow stuck in queued state"

package/errors/concurrency-timing/matrix-fail-fast-sibling-cancellation.yml

@@ -0,0 +1,113 @@
+id: concurrency-timing-007
+title: "Matrix Sibling Jobs Silently Cancelled by fail-fast Default"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - matrix
+  - fail-fast
+  - cancellation
+  - silent-failure
+  - strategy
+  - job-cancelled
+patterns:
+  - regex: "Some jobs were not run because a sibling job failed"
+    flags: "i"
+  - regex: "Canceling since a higher priority waiting run was found"
+    flags: "i"
+  - regex: "The workflow run was canceled\\."
+    flags: "i"
+error_messages:
+  - "Some jobs were not run because a sibling job failed. To allow them to run anyway, add 'continue-on-error: true' to the matrix job."
+  - "Job was cancelled"
+root_cause: |
+  GitHub Actions matrix strategy defaults to `fail-fast: true`. When ANY matrix leg fails,
+  GitHub immediately cancels all other in-progress and pending legs in the same matrix.
+
+  This default is rarely what developers want during debugging or CI investigation, and
+  produces a confusing failure pattern:
+
+  1. **Cancelled legs appear as "Cancelled" not "Failed"** — matrix siblings killed by
+     `fail-fast` show as CANCELLED in the UI (grey icon) rather than red failures. Developers
+     scanning the run summary see one red failure and many grey cancellations, and may not
+     realize those sibling legs had reached significant progress (e.g., partway through a
+     test suite on a different OS or Node version) before being killed.
+
+  2. **Root cause is obscured** — the only failing leg that matters for diagnosis is the one
+     that triggered `fail-fast`, but with multiple cancellations in the UI, it can be hard to
+     identify which leg failed first.
+
+  3. **`fail-fast` is inherited silently** — there is no warning annotation that says
+     "fail-fast is enabled and cancelled 5 sibling legs." The default is documented but
+     easy to forget when adding a new matrix.
+
+  4. **Re-running failed jobs doesn't re-run cancelled siblings** — "Re-run failed jobs"
+     only re-runs the legs that explicitly FAILED, not the ones that were cancelled by
+     fail-fast. Developers re-running failed jobs think they'll see results from all legs,
+     but cancelled siblings stay cancelled. Only "Re-run all jobs" restarts everything.
+
+  Example: a 3-OS matrix (ubuntu, windows, macos) where ubuntu fails. With fail-fast,
+  windows and macos are immediately cancelled. The developer sees one failure and two
+  cancellations, re-runs the failed ubuntu job, and never discovers that windows also
+  had an independent failing test.
+fix: |
+  Set `fail-fast: false` explicitly on any matrix where you need full signal from all
+  legs — especially for cross-platform or multi-version compatibility matrices. Use
+  `fail-fast: true` intentionally only when running the full matrix after one failure is
+  wasteful (e.g., expensive build matrices during pre-merge CI).
+fix_code:
+  - language: yaml
+    label: "Disable fail-fast to see all matrix leg results"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false  # All legs run regardless of siblings failing
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: [18, 20, 22]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+            - run: npm ci
+            - run: npm test
+  - language: yaml
+    label: "Use fail-fast: true only for expensive pre-merge CI"
+    code: |
+      jobs:
+        # Pre-merge: fail fast to conserve minutes — just need to know if it passes
+        lint-and-typecheck:
+          strategy:
+            fail-fast: true  # OK: fast, cheap, fail early
+            matrix:
+              node: [20, 22]
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm run lint && npm run typecheck
+
+        # Post-merge: always see all platform results
+        full-test-suite:
+          if: github.event_name == 'push'
+          strategy:
+            fail-fast: false  # Need full signal on all platforms
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - run: npm test
+prevention:
+  - "Always set `fail-fast: false` explicitly on cross-platform or multi-version matrices where you need full compatibility signal."
+  - "After a matrix failure, use 'Re-run all jobs' (not 'Re-run failed jobs') to get results from previously-cancelled siblings."
+  - "Add a workflow summary step with `if: always()` to collect and consolidate test results across all matrix legs even when some are cancelled."
+  - "Be aware that cancelled legs (grey) are NOT the same as passed legs (green) — visually scan for both red and grey when investigating failures."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast"
+    label: "Workflow syntax: jobs.<job_id>.strategy.fail-fast"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix"
+    label: "Workflow syntax: jobs.<job_id>.strategy.matrix"
+  - url: "https://github.com/orgs/community/discussions/26822"
+    label: "Community: fail-fast cancels matrix siblings unexpectedly"
+  - url: "https://stackoverflow.com/questions/57850553/github-actions-check-steps-status"
+    label: "Stack Overflow: Matrix job cancellation behavior with fail-fast"

package/errors/concurrency-timing/runner-group-not-found-race.yml

@@ -0,0 +1,97 @@
+id: "concurrency-timing-008"
+title: "Intermittent 'Required runner group not found' when ephemeral runner registers after job dispatch"
+category: "concurrency-timing"
+severity: "error"
+tags:
+  - "runner-group"
+  - "self-hosted"
+  - "ephemeral"
+  - "race-condition"
+  - "dispatch"
+  - "organization"
+patterns:
+  - regex: "Required runner group '.*' not found"
+    flags: "i"
+  - regex: "runner_group_id.*null"
+    flags: "i"
+error_messages:
+  - "Required runner group 'x' not found"
+root_cause: |
+  In autoscaling self-hosted runner setups (EC2, GKE ephemeral runners, ARC), the runner
+  must register with GitHub BEFORE the job dispatcher resolves runner group membership.
+
+  The race condition occurs when:
+  1. A workflow is triggered and GitHub's broker immediately tries to assign the job
+  2. The ephemeral runner is still initializing (EC2 bootstrap, container pull, ~2:30 min)
+  3. The broker resolves runner group membership before the new runner completes registration
+  4. The broker reports "Required runner group 'X' not found" and fails the job
+
+  This is intermittent: matrix jobs expose it clearly because some cells get
+  already-running (pre-registered) runners while others need a fresh runner, triggering
+  the race. Inspecting the failed job via the Jobs API shows `runner_group_id: null`
+  and `runner_name: null` throughout the queue duration even though the runner group
+  exists and has the correct repository access.
+
+  A separate but related pattern occurs with org-level runner group repository access
+  grants not propagating to the broker V2 protocol in time, causing identical symptoms
+  regardless of runner initialization speed.
+
+  Reported upstream: https://github.com/actions/runner/issues/4252
+  Related: https://github.com/actions/runner/issues/4429
+fix: |
+  For ephemeral autoscaling runners:
+  Implement a registration wait loop that polls the GitHub Runners API before signaling
+  the runner as available. The runner should only become eligible for jobs after the
+  broker has acknowledged its registration.
+
+  For org-level runner group access issues:
+  Verify that the target repository is in the runner group's allowed repositories list
+  via API. If misconfigured, re-registering the runner at repository level instead of
+  org level is a reliable workaround.
+
+  General mitigation: Add timeout-minutes to all jobs on self-hosted runners so stuck
+  queued jobs fail fast rather than waiting until the 6-hour workflow timeout.
+fix_code:
+  - language: yaml
+    label: "Add timeout-minutes to detect stuck queued jobs quickly"
+    code: |
+      jobs:
+        build:
+          runs-on:
+            group: my-runner-group
+            labels: [self-hosted, linux]
+          timeout-minutes: 10  # Fail fast if runner never picks up the job
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner assigned successfully"
+  - language: yaml
+    label: "Verify runner group repository access via API"
+    code: |
+      jobs:
+        debug-runner-group:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check runner group repository access
+              env:
+                GH_TOKEN: ${{ secrets.ORG_RUNNER_READ_TOKEN }}
+              run: |
+                echo "Runner groups and their visibility:"
+                gh api /orgs/${{ github.repository_owner }}/actions/runner-groups \
+                  --jq '.runner_groups[] | "\(.name) (id: \(.id)) — visibility: \(.visibility)"'
+
+                echo "Repositories allowed for runner group ID 1:"
+                gh api /orgs/${{ github.repository_owner }}/actions/runner-groups/1/repositories \
+                  --jq '.repositories[].full_name'
+prevention:
+  - "Add timeout-minutes to all jobs using self-hosted runners so stuck-queued jobs fail fast instead of waiting for the 6h workflow limit"
+  - "For ephemeral runners (EC2/ARC), implement a registration health check that polls the Runners API before the runner accepts jobs"
+  - "For org-level runners, verify group repository access via API after any runner group configuration change"
+  - "For matrix jobs with ephemeral runners, keep N idle pre-registered runners to avoid cold-start races"
+  - "Monitor runner_group_id via the Jobs API to detect dispatch failures early in autoscaling pipelines"
+docs:
+  - url: "https://github.com/actions/runner/issues/4252"
+    label: "actions/runner #4252 — Intermittent runner group not found"
+  - url: "https://github.com/actions/runner/issues/4429"
+    label: "actions/runner #4429 — Org-level runner never dispatched"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups"
+    label: "GitHub Docs — Managing runner group access"

package/errors/concurrency-timing/timeout-minutes-job-killed.yml

@@ -0,0 +1,107 @@
+id: concurrency-timing-005
+title: "Job Silently Cancelled When timeout-minutes Is Exceeded"
+category: concurrency-timing
+severity: error
+tags:
+  - timeout
+  - timeout-minutes
+  - job-cancelled
+  - timing
+  - runner
+patterns:
+  - regex: "##\\[error\\]The operation was cancelled\\."
+    flags: "i"
+  - regex: "The job '.*' was cancelled because it exceeded the maximum execution time"
+    flags: "i"
+  - regex: "Error: The operation was canceled"
+    flags: "i"
+  - regex: "cancel is received"
+    flags: "i"
+error_messages:
+  - "##[error]The operation was cancelled."
+  - "Error: The operation was canceled"
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+root_cause: |
+  When a job (or step) exceeds its configured `timeout-minutes`, GitHub Actions sends a
+  cancellation signal to the runner. The runner has 5 minutes to complete graceful shutdown,
+  after which it is forcibly terminated.
+
+  The failure mode has two layers of confusion:
+
+  1. **Status shows "Cancelled" not "Failed"** — a timed-out job is marked CANCELLED in the
+     UI. It does not appear as a red failure. Developers scanning the Actions tab may miss it
+     entirely, especially if another run succeeded after it.
+
+  2. **No step-level attribution** — the job log shows "The operation was cancelled" but does
+     not identify which specific step was still running or how far it had progressed. Long
+     builds, network-heavy steps, and interactive prompts are common culprits.
+
+  3. **Default timeout is 360 minutes (6 hours)** — if `timeout-minutes` is not explicitly
+     set, GitHub uses the platform default of 6 hours for GitHub-hosted runners. A job that
+     accidentally blocks (waiting for user input, infinite loop, hung network call) will silently
+     consume 6 hours of runner minutes before being cancelled with no diagnostic output.
+
+  4. **Step-level timeouts are independent** — `timeout-minutes` on a `steps[*]` entry cancels
+     only that step; the job continues. `timeout-minutes` on `jobs[*]` cancels the entire job.
+     Mixing both is valid but must be understood deliberately.
+fix: |
+  Always set explicit `timeout-minutes` at the job level to bound worst-case runner cost.
+  Tune based on your typical build time (e.g., 2-3× the median duration). Add step-level
+  timeouts on known slow steps (network downloads, test suites) to get better attribution.
+
+  To diagnose which step was running at cancellation: add a step near the end that dumps
+  elapsed time, or use `if: cancelled()` post-steps to capture diagnostics on timeout.
+fix_code:
+  - language: yaml
+    label: "Explicit job-level timeout with diagnostic post-step"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30  # Set explicitly — don't rely on 6h default
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            - name: Tests
+              timeout-minutes: 15  # Step-level timeout for attribution
+              run: make test
+
+            # Always runs — captures which step caused the timeout
+            - name: Dump elapsed time on cancellation
+              if: cancelled()
+              run: echo "Job was cancelled at $(date -u). Check step durations above."
+  - language: yaml
+    label: "Identify which step timed out with job summary annotation"
+    code: |
+      steps:
+        - name: Long network operation
+          timeout-minutes: 10
+          run: |
+            # Use --max-time with curl to avoid relying solely on timeout-minutes
+            curl --max-time 300 https://example.com/large-asset -o output.bin
+
+        - name: Report timeout if cancelled
+          if: cancelled()
+          run: |
+            echo "## ⏱️ Job Timed Out" >> $GITHUB_STEP_SUMMARY
+            echo "The job was cancelled. Review step durations in the log." >> $GITHUB_STEP_SUMMARY
+prevention:
+  - "Always set `timeout-minutes` at the job level — never rely on the 6-hour GitHub default."
+  - "Add step-level `timeout-minutes` on network-heavy or test steps so cancellation is attributed to a specific step."
+  - "Use `if: cancelled()` post-steps to write a job summary annotation explaining the timeout."
+  - "Run commands with their own timeout flags (e.g., `curl --max-time`, `pytest --timeout`) in addition to runner timeouts."
+  - "Monitor job duration trends — a job approaching its timeout limit is a signal to investigate performance."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes"
+    label: "Workflow syntax: jobs.<job_id>.timeout-minutes"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes"
+    label: "Workflow syntax: jobs.<job_id>.steps[*].timeout-minutes"
+  - url: "https://github.com/actions/runner/issues/1326"
+    label: "actions/runner#1326 — Steps hanging until timeout with no log output"
+  - url: "https://github.com/orgs/community/discussions/38004"
+    label: "Community: Job stops producing output and is later cancelled"
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "Usage limits: maximum job execution time"

package/errors/known-unsolved/github-step-summary-size-limit.yml

@@ -0,0 +1,112 @@
+id: known-unsolved-008
+title: "GITHUB_STEP_SUMMARY Upload Aborted When Content Exceeds 1024k"
+category: known-unsolved
+severity: error
+tags:
+  - step-summary
+  - GITHUB_STEP_SUMMARY
+  - size-limit
+  - job-summary
+  - markdown
+  - limitation
+patterns:
+  - regex: "\\$GITHUB_STEP_SUMMARY upload aborted, supports content up to a size of 1024k, got \\d+k"
+    flags: "i"
+  - regex: "upload aborted.*supports content up to a size of 1024k"
+    flags: "i"
+  - regex: "Error: GITHUB_STEP_SUMMARY.*1024"
+    flags: "i"
+error_messages:
+  - "$GITHUB_STEP_SUMMARY upload aborted, supports content up to a size of 1024k, got 1387k"
+  - "$GITHUB_STEP_SUMMARY upload aborted, supports content up to a size of 1024k, got 2048k"
+root_cause: |
+  GitHub Actions imposes a hard 1 MiB (1024 KiB) size limit on the content written to
+  `$GITHUB_STEP_SUMMARY`. When a step writes more than this limit, the runner aborts
+  the summary upload and logs an error.
+
+  This is a **platform limit with no workaround** — you cannot increase it. GitHub has not
+  announced plans to raise the limit.
+
+  Common triggers:
+  1. **Test reporters** — tools like `dorny/test-reporter`, `ctrf-io/github-actions-ctrf`,
+     or `EnricoMi/publish-unit-test-result-action` write per-test result tables. Large
+     test suites (thousands of test cases, especially with long failure messages) easily
+     exceed 1 MiB.
+  2. **Dependency review action** — `actions/dependency-review-action` writes full
+     dependency diff tables. Large projects with hundreds of transitive dependencies produce
+     summaries well above 1 MiB.
+  3. **Coverage reports** — HTML-style coverage tables written to `$GITHUB_STEP_SUMMARY`
+     with per-file rows can grow unboundedly on large monorepos.
+  4. **Log echo pipelines** — `cat large-file >> $GITHUB_STEP_SUMMARY` without size
+     checking is the most direct way to hit the limit.
+
+  The error aborts the summary upload but does **not** fail the step or job by default.
+  Depending on the action's error handling, the step may succeed (exit 0) even though the
+  summary was not written — making this a silent failure from a reporting perspective.
+fix: |
+  Truncate or paginate summary content before writing it. Most test reporters provide
+  options to limit which results are written (e.g., only failures, not all passed tests).
+  For custom summary generation, check the size before writing and truncate with a note.
+fix_code:
+  - language: yaml
+    label: "Truncate summary content with size check before writing"
+    code: |
+      - name: Generate test report
+        run: |
+          # Generate report to a temp file first
+          ./scripts/generate-report.sh > /tmp/report.md
+
+          # Check size before writing to summary
+          SIZE_KB=$(du -k /tmp/report.md | cut -f1)
+          MAX_KB=800  # Leave headroom below 1024k limit
+
+          if [ "$SIZE_KB" -gt "$MAX_KB" ]; then
+            echo "⚠️ Full report too large (${SIZE_KB}k). Showing failures only." >> "$GITHUB_STEP_SUMMARY"
+            ./scripts/generate-report.sh --failures-only >> "$GITHUB_STEP_SUMMARY"
+          else
+            cat /tmp/report.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+  - language: yaml
+    label: "dorny/test-reporter — limit to failures only for large test suites"
+    code: |
+      - name: Test Report
+        uses: dorny/test-reporter@v1
+        if: always()
+        with:
+          name: Test Results
+          path: test-results/**/*.xml
+          reporter: jest-junit
+          # Limit output to avoid 1024k summary limit on large suites
+          only-summary: true          # Write only totals, not per-test rows
+          fail-on-error: false
+  - language: yaml
+    label: "Upload full report as artifact instead of writing to summary"
+    code: |
+      - name: Generate full coverage report
+        run: ./scripts/coverage.sh > /tmp/coverage-full.md
+
+      - name: Write summary (truncated)
+        run: |
+          head -100 /tmp/coverage-full.md >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "_Full report available as workflow artifact._" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload full report as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: /tmp/coverage-full.md
+prevention:
+  - "Never pipe unbounded command output directly to `$GITHUB_STEP_SUMMARY` — always size-check or limit first."
+  - "Configure test reporter actions to write only failures (not all passing tests) when the test suite is large."
+  - "Upload large reports as workflow artifacts and link to them from a short summary, instead of embedding all content in the summary."
+  - "The undocumented historical limit of 65,535 characters cited in older docs/answers is no longer accurate — the current limit is 1024 KiB (1 MiB)."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary"
+    label: "Workflow commands: Adding a job summary"
+  - url: "https://github.com/actions/dependency-review-action/issues/786"
+    label: "dependency-review-action#786 — Job Summary Size Limitation aborts the job"
+  - url: "https://github.com/dorny/test-reporter/issues/379"
+    label: "dorny/test-reporter#379 — Is the step summary limit for 65535 characters still accurate?"
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "Usage limits — GitHub Actions"

package/errors/known-unsolved/job-maximum-execution-time.yml

@@ -0,0 +1,127 @@
+id: known-unsolved-009
+title: "Job Killed After Maximum Execution Time (6h Hosted / 35-Day Workflow)"
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout
+  - execution-time
+  - job-limits
+  - platform-limit
+  - self-hosted
+  - workflow-duration
+  - limitation
+patterns:
+  - regex: "The job running has exceeded the maximum execution time"
+    flags: "i"
+  - regex: "exceeded the maximum (?:time|execution time)"
+    flags: "i"
+  - regex: "job .* exceeded .* maximum"
+    flags: "i"
+error_messages:
+  - "The job running on runner GitHub Actions X has exceeded the maximum execution time of 360 minutes."
+  - "The job running has exceeded the maximum execution time"
+root_cause: |
+  GitHub Actions enforces hard platform-level execution time limits that cannot be
+  overridden or extended by workflow configuration. These limits exist to protect
+  shared infrastructure and prevent runaway jobs from consuming unlimited resources.
+
+  **GitHub-hosted runner limits:**
+  - Maximum job execution time: **6 hours** (360 minutes)
+  - Maximum workflow run time: **35 days** (across all jobs, including queued time)
+  - Default `timeout-minutes` when not set: **360 minutes** (6 hours)
+
+  **Self-hosted runner limits:**
+  - Maximum job execution time: **5 days** (7,200 minutes) by default
+  - Maximum workflow run time: **35 days** (same as hosted)
+  - Self-hosted limits can be customized in enterprise plans via org/enterprise policies
+
+  **When limits are hit:**
+  - The runner process is sent a SIGTERM (graceful) then SIGKILL (forced) after a grace period
+  - The job is marked CANCELLED (not FAILED) in the UI
+  - The log message "The job running has exceeded the maximum execution time" appears in
+    the runner log (may be visible in the step logs depending on where the runner was killed)
+  - Any `post:` steps for active actions (e.g., cache save, artifact upload) are skipped
+  - No email notification is sent to the repo owner about the cancellation
+
+  **Why this is a limitation, not just misconfiguration:**
+  - There is no way to set `timeout-minutes` above 21600 (360 hours) to extend the GitHub-hosted 6h cap
+  - The workflow `timeout-minutes` field cannot override the platform cap on GitHub-hosted runners
+  - Jobs requiring more than 6 hours on GitHub-hosted runners have NO supported path without
+    migrating to self-hosted or restructuring the job into multiple shorter sequential jobs
+fix: |
+  There is no way to extend the GitHub-hosted runner 6-hour job cap. Options:
+
+  1. **Break the job into smaller sequential jobs** — split long-running work (e.g., build
+     artifacts first, test in separate parallel jobs, deploy last). Each job has its own
+     6-hour budget.
+
+  2. **Migrate to self-hosted runners** — self-hosted runners support up to 5-day jobs.
+     Use actions-runner-controller (ARC) or cloud auto-scaling for elastic capacity.
+
+  3. **Optimize the slow step** — profile build/test times; parallelize with matrix
+     strategy; use incremental builds or test sharding to reduce per-job duration.
+
+  4. **Use caching aggressively** — `actions/cache` reduces download/build time between
+     runs, but does not extend limits.
+fix_code:
+  - language: yaml
+    label: "Split a long job into sequential jobs to stay within 6h per job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 120  # 2h budget for build
+          outputs:
+            artifact-id: ${{ steps.upload.outputs.artifact-id }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build-release
+            - name: Upload build artifact
+              id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: release-build
+                path: dist/
+
+        # Separate job — gets its own 6h budget
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          timeout-minutes: 180  # 3h budget for tests
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                artifact-id: ${{ needs.build.outputs.artifact-id }}
+            - run: make test-full
+  - language: yaml
+    label: "Self-hosted runner for jobs requiring more than 6 hours"
+    code: |
+      jobs:
+        long-running-job:
+          # Self-hosted runners support up to 5-day job duration
+          runs-on: [self-hosted, linux, x64]
+          timeout-minutes: 2880  # 48h — only possible on self-hosted
+          steps:
+            - uses: actions/checkout@v4
+            - name: Long-running process
+              run: ./scripts/full-dataset-processing.sh
+prevention:
+  - "Set explicit `timeout-minutes` on every job — don't rely on the implicit 6h GitHub-hosted cap as your only safeguard."
+  - "Profile job duration regularly and alert when a job's P99 duration approaches 80% of its timeout budget."
+  - "Parallelize test suites using matrix strategy or `actions/github-script` dynamic matrix generation to reduce per-job time."
+  - "Use self-hosted runners for any workflow that legitimately requires more than 2-3 hours per job (e.g., large model training, full database rebuild, exhaustive integration tests)."
+  - "Be aware that post-run actions (cache save, artifact upload) will NOT execute if the parent job is killed for exceeding the time limit."
+docs:
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "Usage limits: job execution time and workflow run time"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits"
+    label: "Self-hosted runner usage limits"
+  - url: "https://github.com/orgs/community/discussions/48790"
+    label: "Community: Workflow run time limit 35 days"
+  - url: "https://github.com/orgs/community/discussions/150900"
+    label: "Community: Job cancellation after 6 hours"
+  - url: "https://stackoverflow.com/questions/70187174/github-actions-self-hosted-runner-the-job-running-has-exceeded-the-maximum-exe"
+    label: "Stack Overflow: The job running has exceeded the maximum execution time"
+  - url: "https://github.com/actions/actions-runner-controller"
+    label: "Actions Runner Controller (ARC) — Kubernetes-based self-hosted runner auto-scaling"

package/errors/runner-environment/checkout-safe-directory-container.yml

@@ -0,0 +1,84 @@
+id: "runner-environment-022"
+title: "actions/checkout set-safe-directory only runs in post step — container jobs get dubious ownership errors"
+category: "runner-environment"
+severity: "error"
+tags:
+  - "actions/checkout"
+  - "safe-directory"
+  - "container"
+  - "dubious-ownership"
+  - "CVE-2022-24765"
+  - "post-step"
+patterns:
+  - regex: "fatal: detected dubious ownership in repository"
+    flags: "i"
+  - regex: "safe\\.directory.*not.*owned"
+    flags: "i"
+error_messages:
+  - "fatal: detected dubious ownership in repository at '/github/workspace'"
+  - "hint: git config --global --add safe.directory /github/workspace"
+root_cause: |
+  The `actions/checkout` action configures `safe.directory` to allow git operations in
+  the workspace. However, this configuration only runs in the **post step** (cleanup
+  phase), not during the main execution step.
+
+  In container jobs, the workspace is mounted from the host and may be owned by a
+  different UID than the user running inside the container. Git's safe.directory
+  protection (introduced in Git 2.35.2 for CVE-2022-24765) blocks access when the
+  directory owner differs from the running user.
+
+  Because safe.directory is only written during the post step — after all workflow
+  steps have already run — any subsequent git operations in the job's main steps
+  fail with "fatal: detected dubious ownership". This includes third-party actions
+  that internally invoke git (reviewdog, gitops tools, semantic-release, etc.).
+
+  Reported upstream: https://github.com/actions/checkout/issues/2031
+fix: |
+  Add an explicit safe.directory configuration step immediately after `actions/checkout`
+  in any container job that performs git operations. This ensures the directory is
+  trusted before any subsequent steps run.
+fix_code:
+  - language: yaml
+    label: "Add safe.directory config step after checkout in container jobs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container: node:20-bookworm
+          steps:
+            - uses: actions/checkout@v4
+
+            # Workaround: post step safe.directory config doesn't help in container jobs
+            - name: Mark workspace as safe for git
+              run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+            - name: Run git-dependent steps
+              run: git log --oneline -5
+  - language: yaml
+    label: "Use wildcard to mark all directories safe in container workflows"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container: python:3.12-slim
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Configure git safe directories
+              run: |
+                git config --global --add safe.directory '*'
+
+            - name: Lint with pre-commit
+              run: pre-commit run --all-files
+prevention:
+  - "Always add a safe.directory config step after checkout when using container jobs"
+  - "Audit third-party actions in container jobs — reviewdog, semantic-release, and gitops tools invoke git internally"
+  - "Consider running without a container and using docker run explicitly if git safety is complex to manage"
+  - "Track https://github.com/actions/checkout/issues/2031 for an official fix from the actions team"
+docs:
+  - url: "https://github.com/actions/checkout/issues/2031"
+    label: "actions/checkout #2031 — safe.directory only set in post step"
+  - url: "https://github.blog/2022-04-12-git-security-vulnerability-announced/"
+    label: "Git CVE-2022-24765 — safe.directory background"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container"
+    label: "GitHub Docs — Running jobs in a container"

package/errors/runner-environment/self-hosted-runner-version-deprecated.yml

@@ -0,0 +1,99 @@
+id: "runner-environment-023"
+title: "Self-hosted runner on deprecated version stops receiving jobs"
+category: "runner-environment"
+severity: "error"
+tags:
+  - "self-hosted"
+  - "runner"
+  - "deprecated"
+  - "version"
+  - "cannot-receive-messages"
+  - "maintenance"
+patterns:
+  - regex: "Runner version v\\d+\\.\\d+\\.\\d+ is deprecated and cannot receive messages"
+    flags: "i"
+  - regex: "WRITE ERROR.*runner.*deprecated"
+    flags: "i"
+error_messages:
+  - "Runner version v2.332.0 is deprecated and cannot receive messages."
+  - "WRITE ERROR: An error occured: Runner version v2.XXX.X is deprecated and cannot receive messages."
+root_cause: |
+  GitHub periodically deprecates older self-hosted runner versions. Once a runner version
+  is past its deprecation deadline, the runner agent can no longer communicate with the
+  GitHub Actions broker service.
+
+  The runner process stays alive, appears online in the GitHub UI (Settings → Actions →
+  Runners), and is listed as "Active" — but it can no longer receive job assignments.
+  Jobs queued for a runner group containing only deprecated-version runners will either
+  stay "Queued" indefinitely or time out without a clear error in the workflow UI.
+
+  This is a silent failure mode: the runner shows as online, no workflow error is
+  surfaced, but jobs never start. The deprecation schedule is published in the GitHub
+  Changelog and actions/runner releases but teams often miss it without automated
+  update pipelines.
+
+  As of 2026, GitHub requires runners to be within approximately the last 6 months of
+  releases. Related issues: actions/runner #4305, actions/runner #4442
+fix: |
+  Update the runner binary to a currently supported version.
+
+  For manually managed runners:
+  1. SSH to the runner host
+  2. Stop the runner service: ./svc.sh stop
+  3. Download the latest runner from https://github.com/actions/runner/releases/latest
+  4. Extract to the runner directory (configuration is preserved via .runner file)
+  5. Restart: ./svc.sh start
+
+  For ARC (Actions Runner Controller) or autoscaling solutions: bump the runner image
+  version tag in your HelmRelease or Deployment manifest and redeploy.
+fix_code:
+  - language: yaml
+    label: "Scheduled workflow to alert on outdated runner versions"
+    code: |
+      name: Check self-hosted runner versions
+      on:
+        schedule:
+          - cron: '0 9 * * 1'  # Weekly Monday 9 AM
+
+      jobs:
+        check-runners:
+          runs-on: ubuntu-latest  # GitHub-hosted runner for this diagnostic
+          steps:
+            - name: List runner versions via API
+              env:
+                GH_TOKEN: ${{ secrets.RUNNER_READ_TOKEN }}
+              run: |
+                echo "=== Org runners ==="
+                gh api /orgs/${{ github.repository_owner }}/actions/runners \
+                  --jq '.runners[] | "\(.name): v\(.version) (\(.status))"'
+
+            - name: Check latest available version
+              run: |
+                LATEST=$(curl -sf https://api.github.com/repos/actions/runner/releases/latest | jq -r .tag_name)
+                echo "Latest runner version: $LATEST"
+                echo "Compare against your registered runners above"
+  - language: yaml
+    label: "ARC — bump runner version in HelmRelease"
+    code: |
+      # In your ARC HelmRelease or values.yaml
+      githubConfigUrl: "https://github.com/myorg"
+      template:
+        spec:
+          containers:
+            - name: runner
+              image: ghcr.io/actions/actions-runner:2.335.0  # Bump this regularly
+prevention:
+  - "Subscribe to the GitHub Changelog (https://github.blog/changelog/) or watch actions/runner releases for deprecation notices"
+  - "Use Actions Runner Controller (ARC) or an autoscaling solution to automate runner lifecycle management"
+  - "Schedule a weekly cron workflow that checks registered runner versions via the Runners API and alerts if any are outdated"
+  - "Pin runner version in IaC (Terraform, Ansible) and include a runner version bump in your monthly maintenance checklist"
+  - "Set up Dependabot or Renovate to auto-update runner image tags in Docker/ARC manifests"
+docs:
+  - url: "https://github.com/actions/runner/releases"
+    label: "actions/runner releases — version history and changelogs"
+  - url: "https://github.com/actions/runner/issues/4305"
+    label: "actions/runner #4305 — runner deprecated cannot receive messages"
+  - url: "https://github.com/actions/runner/issues/4442"
+    label: "actions/runner #4442 — version deprecation notice"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "GitHub Docs — About self-hosted runners"

package/errors/silent-failures/cache-hit-restore-keys-misleading.yml

@@ -0,0 +1,82 @@
+id: "silent-failures-010"
+title: "cache-hit output is 'true' on restore-keys partial match, not just exact key"
+category: "silent-failures"
+severity: "silent-failure"
+tags:
+  - "actions/cache"
+  - "cache-hit"
+  - "restore-keys"
+  - "partial-match"
+  - "output"
+  - "exact-match"
+patterns:
+  - regex: "cache-hit.*true"
+    flags: "i"
+error_messages:
+  - "cache-hit: true"
+root_cause: |
+  The `cache-hit` output of `actions/cache` is documented to return `true` for an exact
+  cache key match. In practice, `cache-hit` also returns `true` when the key matched via
+  `restore-keys` (a partial/fallback match), not only for exact key hits.
+
+  Workflows that gate post-build steps on `steps.cache.outputs.cache-hit == 'true'` to
+  skip dependency installs assume an exact match. When a restore-keys match occurs,
+  `cache-hit` is `true` even though the cache may be stale or from a different branch.
+  The correct exact-match indicator is the `exact-match` output (available in
+  actions/cache v4+) or comparing `cache-matched-key` against the computed key.
+
+  Reported upstream: https://github.com/actions/cache/issues/1675
+fix: |
+  Use the `exact-match` output (actions/cache v4+) to determine if the restore was an
+  exact key match. `cache-hit` alone does not distinguish between exact and partial
+  (restore-keys) matches.
+
+  Alternatively, compare the `cache-matched-key` output against the expected key to
+  determine if the restore was exact.
+fix_code:
+  - language: yaml
+    label: "Use exact-match output (actions/cache v4+)"
+    code: |
+      - name: Restore cache
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      # Only skip install on EXACT key match, not partial restore-keys hit
+      - name: Install dependencies
+        if: steps.cache.outputs.exact-match != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Compare cache-matched-key to verify exact hit"
+    code: |
+      - name: Restore cache
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: npm-
+
+      - name: Install or skip dependencies
+        run: |
+          EXPECTED_KEY="npm-${{ hashFiles('**/package-lock.json') }}"
+          if [ "${{ steps.cache.outputs.cache-matched-key }}" = "$EXPECTED_KEY" ]; then
+            echo "Exact cache hit — skipping npm ci"
+          else
+            echo "Partial/stale restore-keys hit — running npm ci"
+            npm ci
+          fi
+prevention:
+  - "Never rely on cache-hit == 'true' alone to skip dependency installs; it fires on partial restore-keys matches too"
+  - "Use the exact-match output (actions/cache v4+) when you need to distinguish exact vs partial cache hits"
+  - "Use cache-matched-key output to log or compare the actual key that was restored"
+  - "If using restore-keys, always validate that your skip-install condition handles partial matches correctly"
+docs:
+  - url: "https://github.com/actions/cache/issues/1675"
+    label: "actions/cache #1675 — cache-hit true on restore-keys match"
+  - url: "https://github.com/actions/cache#outputs"
+    label: "actions/cache outputs documentation"

package/package.json

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