@htekdev/actions-debugger 1.0.28 → 1.0.30

package/errors/caching-artifacts/hashfiles-empty-result-cache-key-collision.yml

@@ -0,0 +1,78 @@
+id: 'caching-artifacts-028'
+title: 'hashFiles() returns empty string when no files match pattern, causing cache key collision across all runs'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - hashfiles
+  - cache-key
+  - empty-string
+  - collision
+  - lock-file
+  - monorepo
+patterns:
+  - regex: 'hashFiles\('
+    flags: 'i'
+error_messages:
+  - 'Cache hit for key:'
+  - 'hashFiles result is empty string'
+root_cause: |
+  When hashFiles('**/package-lock.json') finds no matching files, it returns an empty
+  string instead of failing. A cache key like:
+    ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+  evaluates to:
+    Linux-node-
+  (no hash suffix). All workflow runs — regardless of their actual dependency state —
+  then share this single cache key. The first run to complete saves its node_modules
+  under this key; every subsequent run gets a stale cache hit with potentially outdated
+  or wrong dependencies.
+
+  The cache-hit output shows 'true' and the step succeeds with no warning. Developers
+  see unexpectedly fast runs (cache always hits) but may encounter subtle dependency
+  staleness bugs.
+
+  Behavior varies across versions: actions/toolkit prior to 1.9.0 threw an exception
+  on empty results; later versions silently return empty string, making the collapsing
+  key the default behavior for repositories without the expected lock file.
+fix: |
+  Guard hashFiles() with a fallback value so the cache key is never incomplete when
+  no matching files exist. Using || github.sha or || github.run_id ensures each run
+  gets a unique key when no lock file is present, preventing stale cache collisions.
+fix_code:
+  - language: yaml
+    label: 'Add fallback to hashFiles to prevent empty cache key'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # Fallback to github.sha when no lock file exists — prevents key collision
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: 'Verify cache is populated before relying on it'
+    code: |
+      - uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || github.sha }}
+
+      - name: Confirm cache restored correctly
+        if: steps.npm-cache.outputs.cache-hit == 'true'
+        run: |
+          if [ ! -d ~/.npm ]; then
+            echo "Cache hit claimed but directory missing — likely empty-key collision"
+            exit 1
+          fi
+prevention:
+  - 'Always add || github.sha fallback after hashFiles() in cache keys'
+  - 'Use actions built-in caching (setup-node cache: npm) which handles missing lock files safely'
+  - 'In monorepos without a root-level lock file, construct keys from per-package hash patterns'
+  - 'Test cache behavior in branches or forks where lock files might not yet exist'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#hashfiles'
+    label: 'GitHub Docs: hashFiles() function'
+  - url: 'https://github.com/actions/cache/issues/1175'
+    label: 'actions/cache#1175: hashFiles empty result causes key collision'
+  - url: 'https://github.com/actions/toolkit/blob/main/packages/glob/README.md'
+    label: 'actions/toolkit: glob — hashFiles behavior on no match'

package/errors/caching-artifacts/restore-keys-cross-arch-cache-mismatch.yml

@@ -0,0 +1,80 @@
+id: 'caching-artifacts-027'
+title: 'restore-keys fallback matches cross-OS or cross-architecture cache, restoring incompatible binaries'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - restore-keys
+  - cross-platform
+  - architecture
+  - arm64
+  - runner-os
+patterns:
+  - regex: 'restore-keys:'
+    flags: 'i'
+error_messages:
+  - 'Cache restored from key'
+  - 'Exec format error'
+  - 'cannot execute binary file: Exec format error'
+root_cause: |
+  restore-keys performs prefix matching against ALL cached entries in the repository,
+  regardless of operating system or CPU architecture. When a restore-keys prefix is
+  shorter than the primary cache key and omits runner.os or runner.arch, a cache
+  saved on one platform can be silently restored on a different one.
+
+  Example: primary key Linux-x64-node-abc123, restore-keys Linux-node- will match
+  a Linux ARM64 cache saved as Linux-arm64-node-xyz789. The ARM64 node_modules
+  contains native addon binaries (esbuild, sqlite3, etc.) compiled for ARM64; when
+  restored on an x64 runner, they fail at runtime with "Exec format error."
+
+  This became a widespread issue after GitHub introduced macOS ARM64 (M1/M2) runners
+  in 2023 and Linux ARM64 runners in 2024. Teams adding new runner architectures
+  to existing matrix builds often expose this silently.
+
+  The cache-hit output evaluates to 'true' even for cross-architecture restores,
+  providing no indication that the restored content may be incompatible.
+fix: |
+  Always include runner.os AND runner.arch in every level of restore-keys, mirroring
+  whatever isolation is present in the primary cache key. No restore-keys prefix should
+  ever be shorter than the architecture scope of the primary key.
+fix_code:
+  - language: yaml
+    label: 'Include runner.os and runner.arch in all restore-keys levels'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # Primary key includes full OS and architecture isolation
+          key: ${{ runner.os }}-${{ runner.arch }}-node-${{ hashFiles('**/package-lock.json') }}
+          # Every fallback level maintains OS plus architecture isolation
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-node-
+            ${{ runner.os }}-${{ runner.arch }}-
+  - language: yaml
+    label: 'Matrix build with per-arch cache keys'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest, windows-latest]
+          arch: [x64, arm64]
+      steps:
+        - uses: actions/cache@v4
+          with:
+            path: |
+              ~/.cargo/registry
+              target/
+            key: ${{ matrix.os }}-${{ matrix.arch }}-rust-${{ hashFiles('**/Cargo.lock') }}
+            restore-keys: |
+              ${{ matrix.os }}-${{ matrix.arch }}-rust-
+prevention:
+  - 'Always include runner.os AND runner.arch in every level of restore-keys'
+  - 'Audit cache configurations when adding new runner OS or arch combinations to matrix builds'
+  - 'Add a verification step after cache restore to confirm a native binary executes correctly'
+  - 'When migrating from x64-only to multi-arch, update all restore-keys at the same time'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#matching-a-cache-key'
+    label: 'GitHub Docs: Matching a cache key'
+  - url: 'https://github.com/actions/cache#inputs'
+    label: 'actions/cache README: restore-keys input'
+  - url: 'https://github.com/actions/cache/issues/1660'
+    label: 'actions/cache#1660: restore-keys cross-architecture match'

package/errors/concurrency-timing/cleanup-job-if-cancelled-skipped-by-concurrency.yml

@@ -0,0 +1,86 @@
+id: 'concurrency-timing-023'
+title: 'Cleanup jobs with if: cancelled() do not run when workflow is canceled by concurrency group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancelled
+  - cleanup
+  - cancel-in-progress
+  - if-condition
+patterns:
+  - regex: 'cancel-in-progress:\s*true'
+    flags: 'i'
+  - regex: 'if:\s*cancelled\(\)'
+    flags: 'i'
+error_messages:
+  - 'This run has been cancelled.'
+  - 'Job cancelled by a newer workflow run'
+root_cause: |
+  When cancel-in-progress: true cancels a workflow run because a new run was queued in the same
+  concurrency group, GitHub cancels the entire workflow run at the infrastructure level before
+  individual job-level if: conditions are evaluated. As a result, jobs with if: cancelled() or
+  if: always() defined to run after a canceled parent job are themselves canceled before they
+  can be dispatched to a runner.
+
+  This is distinct from a job failing or being manually canceled: concurrency-group cancellation
+  is an external platform signal. In practice, cleanup jobs that rely on if: cancelled() may
+  start briefly but are killed mid-execution if they happen to be in-flight when the cancel
+  propagates.
+fix: |
+  Use a separate workflow triggered by workflow_run with types: [completed] as the cleanup
+  trigger rather than relying on in-workflow if: cancelled() jobs. The workflow_run approach
+  fires reliably regardless of how the parent workflow ended.
+
+  If the in-workflow approach is required, use if: always() rather than if: cancelled() and
+  ensure the cleanup job starts quickly (lightweight first step) to reduce the window during
+  which the cancellation signal can reach it.
+fix_code:
+  - language: yaml
+    label: 'Reliable cleanup via separate workflow_run trigger'
+    code: |
+      # .github/workflows/cleanup.yml
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          if: >-
+            ${{ github.event.workflow_run.conclusion == 'cancelled' ||
+                github.event.workflow_run.conclusion == 'failure' }}
+          steps:
+            - name: Run cleanup
+              run: echo "Cleaning up after ${{ github.event.workflow_run.conclusion }}"
+  - language: yaml
+    label: 'Best-effort if:always() with fast first step'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./run-tests.sh
+
+        cleanup:
+          needs: build
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Signal start immediately
+              run: echo "Cleanup starting"
+            - name: Do cleanup
+              run: ./cleanup.sh
+prevention:
+  - 'Do not rely solely on if: cancelled() for critical cleanup when cancel-in-progress: true is active'
+  - 'Use a separate workflow_run: completed trigger for guaranteed post-run cleanup logic'
+  - 'Use if: always() instead of if: cancelled() for broader coverage'
+  - 'Keep cleanup steps inside the main job where possible — step-level if: always() is more reliable than job-level when concurrency cancels the run'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run event'
+  - url: 'https://github.com/orgs/community/discussions/13655'
+    label: 'GitHub Community: cleanup jobs not running after concurrency cancellation'

package/errors/concurrency-timing/timeout-minutes-queue-wait-not-included.yml

@@ -0,0 +1,72 @@
+id: 'concurrency-timing-024'
+title: 'timeout-minutes applies to job execution only, not queue wait time — jobs can wait indefinitely'
+category: concurrency-timing
+severity: warning
+tags:
+  - timeout
+  - queue
+  - self-hosted
+  - runner
+  - wait-time
+patterns:
+  - regex: 'timeout-minutes:\s*\d+'
+    flags: 'i'
+error_messages:
+  - 'The job running on runner has exceeded the maximum execution time of'
+  - 'The operation was canceled.'
+root_cause: |
+  timeout-minutes only counts elapsed time from when a job actually begins executing on
+  a runner — not from when it enters the queue. A job waiting for an available runner
+  slot (including jobs waiting in a concurrency group queue) can sit pending for hours
+  or indefinitely without any timeout being applied.
+
+  This is particularly impactful with:
+  - Self-hosted runners under heavy load with limited runner capacity
+  - Concurrency groups with cancel-in-progress: false that accumulate queued jobs
+  - Repository-level runner quotas on GitHub-hosted runners during peak usage
+
+  Developers are often surprised that a job with timeout-minutes: 30 waited 4+ hours
+  before starting, then proceeded to run for its full 30-minute budget.
+fix: |
+  There is no native queue-timeout setting in GitHub Actions. Recommended workarounds:
+
+  1. Set cancel-in-progress: true in concurrency groups to drop stale queued jobs
+     when newer commits arrive, preventing queue accumulation.
+  2. Monitor queue depth using the GitHub REST API /repos/{owner}/{repo}/actions/runs
+     and set up external alerting for runs stuck in 'queued' status too long.
+  3. Ensure adequate self-hosted runner pool capacity relative to expected parallelism.
+  4. Use github-hosted runners for time-sensitive jobs to avoid self-hosted queue depth issues.
+fix_code:
+  - language: yaml
+    label: 'Prevent queue accumulation with cancel-in-progress'
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          timeout-minutes: 30  # Only counts execution time, NOT queue wait time
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}
+            cancel-in-progress: true  # Drop stale queued jobs on new push
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+  - language: yaml
+    label: 'External queue monitoring via API'
+    code: |
+      # Monitor for stuck queued runs via GitHub API
+      # GET /repos/{owner}/{repo}/actions/runs?status=queued
+      # Alert if any run has been queued for more than N minutes
+      # (implement in a separate monitoring workflow or external system)
+prevention:
+  - 'Do not assume timeout-minutes prevents jobs from waiting indefinitely in the runner queue'
+  - 'Use cancel-in-progress: true for CI workflows to prevent queue accumulation'
+  - 'Size self-hosted runner pools to handle expected peak concurrency'
+  - 'Monitor workflow run queue depth separately via the GitHub REST API'
+  - 'Document queue wait behavior in team CI runbooks so on-call engineers know what to expect'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Docs: timeout-minutes'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/rest/actions/workflow-runs'
+    label: 'GitHub REST API: Workflow runs'

package/errors/known-unsolved/input-unset-vs-empty-string.yml

@@ -0,0 +1,78 @@
+id: 'known-unsolved-030'
+title: 'core.getInput cannot distinguish unset input from explicitly-empty input'
+category: known-unsolved
+severity: limitation
+tags:
+  - toolkit
+  - core-getInput
+  - composite-action
+  - empty-string
+  - null-input
+  - fork-secrets
+patterns:
+  - regex: 'core\.getInput\('
+    flags: 'i'
+error_messages:
+  - 'No way to detect if input was provided vs set to empty string'
+root_cause: |
+  The `core.getInput(name)` function in `@actions/core` always returns an empty string ('')
+  when an input is either not provided by the caller or explicitly set to the empty string.
+  There is no `core.hasInput(name)` API or other mechanism to distinguish these two cases.
+
+  This creates several practical problems for action authors:
+  - A required input set to '' passes the required: true check in getInput but is semantically absent
+  - Fork pull requests inject secrets as empty strings (secrets are unavailable); an action cannot tell
+    if a secret input was omitted vs provided-as-empty-because-fork
+  - Composite action callers cannot express "I intentionally leave this blank" vs "I don't provide this at all"
+  - YAML null or ~ values (e.g., with: my_val: ~) are coerced to '' by the runner before the action sees them
+
+  Upstream GitHub toolkit issue #940 has been open since 2022 with 22 upvotes and no fix planned.
+fix: |
+  No direct fix exists — there is no core.hasInput() API. Workarounds depend on the use case:
+  - For sentinel detection: document a convention like 'none' or '__unset__' as the explicit absent value
+    and check getInput('x') === 'none'
+  - For fork secret detection: check github.event.pull_request.head.repo.fork == true and gate on that
+    rather than on whether the secret is empty
+  - For optional inputs: provide a well-documented default value in action.yml so callers always get a
+    predictable non-empty string when they omit the input
+  - For composite actions: use ${{ inputs.my_input != '' }} in if: conditions, documenting that
+    callers must pass a non-empty string to opt in
+fix_code:
+  - language: yaml
+    label: 'Use sentinel value convention to detect absent input'
+    code: |
+      # action.yml — declare sentinel default
+      inputs:
+        deploy_env:
+          description: 'Target environment (leave blank to skip deployment)'
+          required: false
+          default: '__unset__'
+
+      # In composite action steps
+      steps:
+        - name: Deploy
+          if: ${{ inputs.deploy_env != '__unset__' && inputs.deploy_env != '' }}
+          run: echo "Deploying to ${{ inputs.deploy_env }}"
+  - language: yaml
+    label: 'Detect fork PR to guard secret-gated steps instead of empty-check'
+    code: |
+      steps:
+        - name: Publish (skip on fork PRs)
+          if: >-
+            ${{ github.event_name != 'pull_request' ||
+                github.event.pull_request.head.repo.full_name == github.repository }}
+          run: echo "$NPM_TOKEN" | npm login --registry https://registry.npmjs.org
+          env:
+            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+prevention:
+  - 'Document in action.yml that empty string and absent are treated identically by core.getInput'
+  - 'Use a non-empty sentinel default value (e.g. __unset__) instead of relying on empty-check logic'
+  - 'Never gate fork-secret logic on secret emptiness — use fork-detection via event context instead'
+  - 'For required inputs that must be non-empty, add an explicit validation step that fails with a helpful message'
+docs:
+  - url: 'https://github.com/actions/toolkit/issues/940'
+    label: 'actions/toolkit#940: Impossible to detect unset inputs from inputs set as empty string'
+  - url: 'https://github.com/actions/toolkit/tree/main/packages/core'
+    label: 'actions/toolkit core package — getInput API'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#inputs'
+    label: 'GitHub Docs: Action metadata — inputs'

package/errors/runner-environment/arc-task-cancelled-pod-eviction.yml

@@ -0,0 +1,90 @@
+id: 'runner-environment-083'
+title: 'Actions Runner Controller pods intermittently fail with "A task was cancelled" during large matrix jobs'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - kubernetes
+  - matrix
+  - task-cancelled
+  - pod-eviction
+  - self-hosted
+  - keda
+patterns:
+  - regex: 'A task was cancell?ed\.'
+    flags: 'i'
+  - regex: 'The operation was canceled\.'
+    flags: 'i'
+error_messages:
+  - 'Error: A task was cancelled.'
+  - 'Error: The operation was canceled.'
+root_cause: |
+  When using Actions Runner Controller (ARC) to run GitHub Actions on Kubernetes, ephemeral
+  runner pods can be evicted or preempted mid-job by the Kubernetes scheduler, producing
+  a "A task was cancelled" or "The operation was canceled" error with no application-level
+  log output before the failure.
+
+  Common causes:
+  - Kubernetes resource pressure: if a node is under memory or CPU pressure, the kubelet
+    evicts lower-priority pods. ARC runner pods have no PriorityClass by default and are
+    among the first to be evicted
+  - Node autoscaling: Cluster Autoscaler draining nodes for scale-down triggers eviction of
+    runner pods that have been running longer than the scale-down grace period
+  - KEDA queue-length scaling: KEDA scaling down the runner Deployment while jobs are
+    in-flight terminates runner pods before jobs complete
+  - OOM kills: matrix jobs that each consume significant memory can saturate node memory,
+    causing the OOM killer to terminate runner pods
+
+  The issue is especially common with large matrix builds (10+ parallel jobs) because the
+  aggregate resource demand spike can trigger autoscaler or eviction behavior. Because ARC
+  runner pods are ephemeral and have no restart policy, the job is permanently failed when
+  the pod is evicted.
+fix: |
+  Assign a high PriorityClass to ARC runner pods so the Kubernetes scheduler avoids evicting
+  them during resource pressure. Also set adequate resource requests/limits and configure
+  terminationGracePeriodSeconds to at least the expected maximum job duration.
+fix_code:
+  - language: yaml
+    label: 'Create a high-priority PriorityClass for ARC runner pods'
+    code: |
+      apiVersion: scheduling.k8s.io/v1
+      kind: PriorityClass
+      metadata:
+        name: github-runner-high
+      value: 1000000
+      globalDefault: false
+      description: 'High priority for GitHub Actions runner pods to prevent eviction'
+  - language: yaml
+    label: 'Reference PriorityClass and set resource limits in ARC AutoscalingRunnerSet values'
+    code: |
+      # helm values for actions-runner-controller AutoscalingRunnerSet chart
+      template:
+        spec:
+          priorityClassName: github-runner-high
+          # Allow jobs up to 1 hour to finish before pod is force-terminated
+          terminationGracePeriodSeconds: 3600
+          containers:
+            - name: runner
+              resources:
+                requests:
+                  memory: '2Gi'
+                  cpu: '500m'
+                limits:
+                  memory: '4Gi'
+                  cpu: '2000m'
+prevention:
+  - 'Assign a PriorityClass to ARC runner pods to prevent eviction under resource pressure'
+  - 'Set terminationGracePeriodSeconds to at least the expected maximum single-job duration'
+  - 'Set explicit resource requests and limits to avoid OOM kills during large matrix builds'
+  - 'Configure KEDA scale-down stabilization windows to prevent scaling down while jobs run'
+  - 'Monitor node resource utilization and right-size cluster nodes for peak matrix concurrency'
+  - 'Enable PodDisruptionBudgets for runner workloads to reduce involuntary evictions during node drains'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3819'
+    label: 'actions/runner#3819: A lot of random "A task was cancelled" errors'
+  - url: 'https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/'
+    label: 'Kubernetes: Pod Priority and Preemption'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs: Autoscaling with self-hosted runners'
+  - url: 'https://github.com/actions/actions-runner-controller'
+    label: 'Actions Runner Controller (ARC) GitHub repository'

package/errors/runner-environment/bash-script-path-unquoted-spaces.yml

@@ -0,0 +1,83 @@
+id: 'runner-environment-084'
+title: 'Bash/sh script handler does not quote script path — fails when path contains spaces'
+category: runner-environment
+severity: error
+tags:
+  - bash
+  - shell
+  - path-spaces
+  - job-hooks
+  - self-hosted
+  - macos
+  - tart-vm
+patterns:
+  - regex: 'ACTIONS_RUNNER_HOOK_JOB_(?:STARTED|COMPLETED)'
+    flags: 'i'
+  - regex: 'bash.*No such file or directory'
+    flags: 'i'
+error_messages:
+  - 'bash: /Volumes/My Shared Files/hook.sh: No such file or directory'
+  - 'sh: /path with spaces/script.sh: not found'
+  - '/path/with: not found'
+root_cause: |
+  The GitHub Actions runner bash/sh script handler does not quote the script path
+  placeholder when building the shell invocation. The default bash arguments in
+  ScriptHandlerHelpers.cs are:
+    --noprofile --norc -e -o pipefail {0}
+  When {0} is replaced with a path containing spaces — e.g.,
+    /Volumes/My Shared Files/hook.sh
+  bash receives the path as two separate arguments due to word splitting:
+    bash --noprofile --norc -e -o pipefail /Volumes/My Shared Files/hook.sh
+  This causes a "No such file or directory" error for the first word-split token.
+
+  By contrast, the PowerShell and cmd handlers correctly quote the path:
+    pwsh:       -command "& '{0}'"
+    powershell: -command ". '{0}'"
+    cmd:        /D /E:ON /V:OFF /S /C "CALL "{0}""
+  Only bash and sh are affected (runner#4404, unresolved as of June 2026).
+
+  Practical impact:
+  - Job hooks (ACTIONS_RUNNER_HOOK_JOB_STARTED, ACTIONS_RUNNER_HOOK_JOB_COMPLETED) placed in
+    shared directories with spaces — common on macOS Tart VMs mounted at /Volumes/My Shared Files/
+  - Self-hosted runner workspaces on paths containing spaces (less common but possible)
+  - Any run: step using a working-directory with spaces in the resolved path
+fix: |
+  Ensure hook script paths and runner working directories never contain spaces.
+  On macOS Tart VMs, place hook scripts under a path without spaces (e.g., /Users/runner/hooks/).
+
+  Use a wrapper script at a space-free path that exec-delegates to the actual script if
+  it must reside under a shared mount with spaces in its path.
+
+  Monitor actions/runner#4404 for the upstream fix and upgrade when a patched runner ships.
+fix_code:
+  - language: yaml
+    label: 'Configure job hook at a space-free path (environment variable)'
+    code: |
+      # In the runner .env file (e.g., /home/runner/actions-runner/.env):
+      # Point hook variables to a path WITHOUT spaces
+      ACTIONS_RUNNER_HOOK_JOB_STARTED=/Users/runner/hooks/job-started.sh
+      ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/Users/runner/hooks/job-completed.sh
+      #
+      # Avoid paths like:
+      # /Volumes/My Shared Files/hooks/  ← spaces cause bash word-splitting error
+  - language: yaml
+    label: 'Wrapper script at space-free path delegates to actual hook in shared mount'
+    code: |
+      #!/bin/bash
+      # /Users/runner/hooks/job-started.sh  (space-free path — registered as the hook)
+      #
+      # Exec-delegates to the actual hook that lives under a shared volume with spaces.
+      # Using exec preserves exit codes and avoids a subprocess layer.
+      exec "/Volumes/My Shared Files/hooks/actual-job-started.sh" "$@"
+prevention:
+  - 'Never place runner hooks, workspace paths, or working-directories in paths containing spaces'
+  - 'On macOS Tart VMs, configure shared mounts to use space-free mount points (e.g., /Volumes/SharedFiles)'
+  - 'Test runner hook invocations explicitly on macOS or Windows deployments with shared mounts'
+  - 'Watch actions/runner#4404 for the upstream fix; upgrade the runner version when it ships'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4404'
+    label: 'actions/runner#4404: Bash script handler does not quote script path — breaks with spaces'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job'
+    label: 'GitHub Docs: Running scripts before or after a job (hooks)'
+  - url: 'https://github.com/actions/runner/blob/main/src/Runner.Worker/Handlers/ScriptHandlerHelpers.cs'
+    label: 'Runner source: ScriptHandlerHelpers.cs (unquoted bash path template)'

package/errors/runner-environment/self-hosted-runner-stuck-between-jobs.yml

@@ -0,0 +1,109 @@
+id: 'runner-environment-082'
+title: 'Self-hosted runner gets stuck "Waiting for a runner to pick up this job" between jobs in the same workflow'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - runner
+  - multi-job
+  - queued
+  - stuck
+  - windows
+  - auto-update
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a runner to pick up this job...'
+root_cause: |
+  After completing the first job in a multi-job workflow, a self-hosted runner sometimes
+  fails to pick up subsequent jobs in the same workflow run. The subsequent jobs remain
+  in queued status indefinitely, with no timeout and no automatic retry.
+
+  Common root causes:
+  - Runner auto-update race condition: when the runner auto-updates between jobs, the post-job
+    cleanup of the first job can leave the runner in a state where it reports idle to the
+    broker but cannot accept new job messages
+  - Windows service restart latency: on Windows hosts, if the runner was auto-updated or
+    the service restarted between jobs, the new process may not have fully re-registered
+    with the GitHub Actions broker before the second job is dispatched
+  - JIT token expiry: in ephemeral/JIT runner setups, the registration token can expire
+    between jobs if the first job runs for a long time, and the runner cannot re-register
+  - Broker disconnect: a transient network interruption between jobs severs the long-poll
+    connection; the runner reconnects but the already-dispatched job message is missed
+
+  Manually cancelling and re-running the workflow, or restarting the runner service,
+  resolves the issue immediately, confirming the runner is functional but lost broker contact.
+fix: |
+  Immediate workaround: cancel the stuck workflow run and re-trigger it, or restart the
+  runner service:
+    Windows: Restart-Service "actions.runner.*"
+    Linux:   sudo systemctl restart actions.runner.*.<name>.service
+
+  Long-term fixes:
+  - Disable runner auto-update during active workflows by setting RUNNER_ALLOW_RUNASROOT
+    environment variable and pinning a specific runner version
+  - Use ephemeral runners (--ephemeral flag) so each job dispatches a fresh runner that
+    registers anew with the broker, eliminating the between-job reconnect window
+  - Split long workflows into separate workflow files triggered via workflow_run or
+    repository_dispatch so each workflow gets an independent runner session
+  - On Windows: ensure the runner service account has the "Log on as a service" right
+    and that antivirus is not blocking runner binary updates
+fix_code:
+  - language: yaml
+    label: 'Use ephemeral runners to avoid stuck-between-jobs on self-hosted'
+    code: |
+      # When configuring the runner, use the --ephemeral flag:
+      # ./config.sh --url https://github.com/OWNER/REPO --token TOKEN --ephemeral
+      #
+      # For ARC (Actions Runner Controller), set runnerScaleSetSettings:
+      # spec:
+      #   template:
+      #     metadata:
+      #       labels:
+      #         ephemeral: 'true'
+      #
+      # Each job gets a freshly-registered runner; no between-job broker reconnect issues.
+  - language: yaml
+    label: 'Split multi-job workflow into two workflows triggered by workflow_run'
+    code: |
+      # phase1.yml
+      on:
+        push:
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+
+      # phase2.yml (fresh runner registration — no stuck-between-jobs risk)
+      on:
+        workflow_run:
+          workflows: [phase1.yml]
+          types: [completed]
+      jobs:
+        test:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: [self-hosted, linux]
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+            - run: make test
+prevention:
+  - 'Use ephemeral runners (--ephemeral) to ensure each job gets a fresh broker registration'
+  - 'Configure the runner service with Restart=on-failure to auto-recover from crashes between jobs'
+  - 'Pin runner versions and suppress auto-updates in production to prevent mid-workflow upgrades'
+  - 'Monitor for stuck runs via the GitHub Actions API and alert or auto-cancel them'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3609'
+    label: 'actions/runner#3609: Self-hosted runner stuck on "Waiting for a runner to pick up this job"'
+  - 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'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs: Autoscaling with self-hosted runners'

package/errors/triggers/workflow-run-skipped-when-trigger-workflow-filtered.yml

@@ -0,0 +1,88 @@
+id: 'triggers-026'
+title: 'workflow_run does not fire when triggering workflow is skipped by paths or branches filter'
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-run
+  - skipped
+  - paths-filter
+  - branches-filter
+  - trigger-chain
+patterns:
+  - regex: 'workflow_run'
+    flags: 'i'
+  - regex: 'types:\s*\[.*completed.*\]'
+    flags: 'i'
+error_messages:
+  - 'This run was triggered by a workflow_run event but the parent workflow was not found'
+root_cause: |
+  When a workflow is skipped because its on.push.paths or on.push.branches filter does not
+  match the pushed commit, GitHub does not create a workflow run record and therefore does
+  not emit a workflow_run completion event. A downstream workflow that listens for
+  on.workflow_run: [UpstreamWorkflow] with types: [completed] silently never fires.
+
+  This breaks fan-out CI/CD architectures where a primary workflow is gated by path/branch
+  filters, and secondary workflows (deploy, notify, publish) depend on its completion.
+  When the paths filter causes the primary workflow to be skipped entirely, the downstream
+  chain is dropped with no error message.
+
+  The issue affects both on.push.paths and on.push.branches filters. It does not affect
+  workflows that run but exit early via an if: condition on a job — only skipped runs
+  (which never appear in the GitHub Actions run list) cause the downstream gap.
+fix: |
+  Replace trigger-level on.push.paths filtering with in-workflow job-level path detection
+  using an action like dorny/paths-filter. This ensures the upstream workflow always
+  creates a run (triggering the workflow_run event), while individual jobs are skipped
+  when paths do not match.
+fix_code:
+  - language: yaml
+    label: 'Replace trigger-level paths filter with in-workflow detection'
+    code: |
+      # upstream.yml
+      # BAD: on.push.paths silently skips the run — workflow_run downstream never fires
+      # on:
+      #   push:
+      #     paths: ['src/**']
+
+      # GOOD: Always run, detect paths inside the workflow
+      on: [push]
+
+      jobs:
+        detect-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            src-changed: ${{ steps.filter.outputs.src }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+
+        build:
+          needs: detect-changes
+          if: ${{ needs.detect-changes.outputs.src-changed == 'true' }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+
+      # downstream.yml — now reliably fires on every push
+      # on:
+      #   workflow_run:
+      #     workflows: ['Upstream CI']
+      #     types: [completed]
+prevention:
+  - 'Do not combine on.push.paths/branches filters with workflow_run downstream dependencies'
+  - 'Use dorny/paths-filter or tj-actions/changed-files inside always-running workflows instead'
+  - 'Test the full trigger chain end-to-end by pushing commits that both match and do not match the filter'
+  - 'Document the skipped-runs gap in team CI docs for anyone building workflow_run chains'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run — triggering workflow must run on default branch'
+  - url: 'https://github.com/dorny/paths-filter'
+    label: 'dorny/paths-filter — job-level path filtering'
+  - url: 'https://github.com/orgs/community/discussions/23710'
+    label: 'GitHub Community: workflow_run not triggered when upstream workflow is skipped'

package/package.json

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