@htekdev/actions-debugger 1.0.103 → 1.0.105

package/errors/caching-artifacts/cache-primary-key-prefix-matching-undocumented.yml

@@ -0,0 +1,104 @@
+id: caching-artifacts-060
+title: 'actions/cache Primary key Uses Undocumented Prefix Matching — Stale Cache Restored on Partial Hit'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - actions/cache
+  - key
+  - prefix-match
+  - stale-cache
+  - cache-hit
+  - restore-keys
+patterns:
+  - regex: 'Cache restored from key:'
+    flags: 'i'
+  - regex: 'cache-hit.*true'
+    flags: 'i'
+  - regex: 'uses:\s*actions/cache@v[34]'
+    flags: 'i'
+error_messages:
+  - "Cache restored from key: npm-cache-linux"
+  - "cache-hit: true"
+  - "Restored cache from key"
+root_cause: |
+  GitHub Actions documentation states that `actions/cache`'s primary `key:`
+  parameter requires an **exact match** to trigger a cache hit. In practice,
+  the cache service backend uses **prefix matching** for primary keys, identical
+  to how `restore-keys:` works. This undocumented behavior was confirmed by the
+  GitHub Actions team in actions/cache#1433:
+
+  > "I've checked the internal service implementation and it appears that our
+  > documentation is incorrect. `key` uses prefix-matching similar to how
+  > `restore-keys` works."
+
+  **What this means in practice:**
+  - If an existing cached entry has key `npm-cache-linux` and the current run
+    uses key `npm-cache-linux-abc123`, the primary `key` lookup returns a hit on
+    `npm-cache-linux` (the existing key is a prefix of the requested key).
+  - The cache is restored silently with `cache-hit: true`, even though the
+    actual content may be outdated or from a completely different run.
+  - Downstream jobs that check `cache-hit == 'true'` to skip install steps will
+    skip them, causing builds to use stale dependencies.
+
+  This is especially problematic when:
+  1. A broad, short key (e.g., `linux-npm`) was saved long ago and a new, more
+     specific key (e.g., `linux-npm-${{ hashFiles('package-lock.json') }}`)
+     happens to have the old key as a prefix.
+  2. CI changes add a version suffix to cache keys, but old caches from before
+     the change are still present and match as prefixes.
+fix: |
+  **Option 1 (recommended): Use unique, non-colliding key prefixes**
+  Design your cache key so that no broader key from a previous run can be a prefix
+  of your current key. Include the hash of lock files or use a version token that
+  changes with major dependency updates.
+
+  **Option 2: Rotate keys by appending a version token**
+  Prefix with a cache version that you bump whenever you want to guarantee a cold
+  start, preventing old keys from matching.
+
+  **Option 3: Use `restore-keys:` intentionally**
+  If you want prefix fallback, make it explicit with `restore-keys:` and verify
+  what you're getting. Check `cache-hit` output and run install even on partial
+  hits when correctness matters.
+
+  **Option 4: Delete stale caches via API**
+  Use `gh extension install actions/gh-actions-cache` or the REST API to delete
+  old broad-key caches that would match as prefixes, preventing unexpected hits.
+fix_code:
+  - language: yaml
+    label: 'Use versioned prefix to prevent stale prefix matches'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # v2 prefix ensures old "v1" caches never match as prefixes
+          key: v2-npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            v2-npm-${{ runner.os }}-
+  - language: yaml
+    label: 'Re-install deps on partial cache hit to avoid stale cache'
+    code: |
+      - uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: npm-${{ runner.os }}-
+
+      - name: Install dependencies
+        # Always install when not an exact hit to avoid stale partial cache
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
+prevention:
+  - 'Always include a lockfile hash in cache keys: `key: npm-${{ runner.os }}-${{ hashFiles(''**/package-lock.json'') }}`'
+  - 'Prefix cache keys with a version token (e.g., `v1-`, `v2-`) so you can easily invalidate all old caches by bumping the version.'
+  - 'Do not rely solely on `cache-hit == true` to skip install steps; consider re-running `npm install --prefer-offline` even on hits to handle partial prefix matches.'
+  - 'Periodically audit and delete stale cache entries via the GitHub REST API or `gh actions-cache` extension.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1433'
+    label: 'actions/cache#1433: Cache key uses prefix matching — documentation is incorrect'
+  - url: 'https://github.com/actions/cache/issues/1385'
+    label: 'actions/cache#1385: Unexpected cache hit from prefix match'
+  - 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/caching-artifacts/upload-artifact-v4-hidden-files-excluded-by-default.yml

@@ -0,0 +1,82 @@
+id: caching-artifacts-059
+title: 'actions/upload-artifact@v4 excludes hidden files by default — dotfiles silently missing from artifacts'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - v4
+  - hidden-files
+  - dotfiles
+  - include-hidden-files
+  - silent-omission
+patterns:
+  - regex: 'uses:\s*actions/upload-artifact@v4'
+    flags: 'i'
+  - regex: 'include-hidden-files:\s*false'
+    flags: 'i'
+error_messages:
+  - 'No files were found with the provided path'
+  - 'Uploading 0 files'
+  - 'Found no files matching'
+root_cause: |
+  actions/upload-artifact@v4 introduced the include-hidden-files input, which defaults
+  to false. Any file or directory whose name begins with a dot (.) is silently excluded
+  from the artifact upload. The action completes with a success status and reports the
+  number of files uploaded — only inspecting that count reveals that dotfiles were
+  skipped.
+
+  Common files and directories affected:
+    .env, .env.production, .env.local     — environment configuration
+    .npmrc, .nvmrc, .node-version          — Node.js toolchain config
+    .htaccess                              — Apache web server config
+    .browserslistrc, .babelrc              — build tool configuration
+    .next/, .nuxt/, .svelte-kit/           — framework build output directories
+    .vitepress/, .docusaurus/              — documentation build output
+
+  Workflows migrated from v3 to v4 silently break: the artifact is created and
+  downloaded without any error, but dependent steps fail when the expected dotfiles
+  are absent. Framework deployments (Next.js, Nuxt, SvelteKit) that upload their build
+  output are most frequently affected since their output directories are hidden.
+fix: |
+  Set include-hidden-files: true on the upload step whenever dotfiles or dot-directories
+  must be preserved in the artifact:
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: build-output
+        path: ./dist
+        include-hidden-files: true
+
+  Alternatively, explicitly list only the required hidden files in the path input to
+  avoid uploading the entire directory with hidden file inclusion.
+fix_code:
+  - language: yaml
+    label: 'Add include-hidden-files: true to preserve dotfiles and dot-directories'
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./.next          # Next.js build output is a hidden directory
+          include-hidden-files: true   # required — excluded by default in v4
+  - language: yaml
+    label: 'Alternative: explicitly list hidden files instead of directory glob'
+    code: |
+      - name: Upload build artifacts including dotfiles
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: |
+            ./dist
+            ./.env.production
+            ./.nvmrc
+            ./.npmrc
+prevention:
+  - 'Set include-hidden-files: true when uploading directories known to contain dotfiles or dot-directories (.next/, .nuxt/, .svelte-kit/, etc.)'
+  - 'After migrating from upload-artifact@v3 to @v4, inspect the artifact file count in the run log — a drop indicates hidden files were excluded'
+  - 'Add a post-upload verification step: download the artifact in a subsequent job and assert the expected dotfiles exist'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/blob/main/README.md'
+    label: 'actions/upload-artifact README: include-hidden-files input'
+  - url: 'https://github.com/actions/upload-artifact/blob/main/docs/migration-v3-to-v4.md'
+    label: 'Migration guide: upload-artifact v3 to v4'

package/errors/concurrency-timing/batch-workflow-dispatch-static-concurrency-silent-cancel.yml

@@ -0,0 +1,137 @@
+id: concurrency-timing-049
+title: 'Batch workflow_dispatch Runs Silently Cancel Each Other via Static Concurrency Group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow-dispatch
+  - batch
+  - cancel
+  - static-group
+  - lost-run
+  - dispatch-api
+patterns:
+  - regex: 'This run was cancelled'
+    flags: 'i'
+  - regex: 'concurrency:\s*\n\s*group:\s*[''"]?\$\{\{\s*github\.workflow\s*\}\}'
+    flags: 'im'
+  - regex: 'workflow_dispatch.*concurrency|concurrency.*workflow_dispatch'
+    flags: 'ims'
+error_messages:
+  - "This run was cancelled."
+  - "Run has been cancelled because it is in a concurrency group with a newer run."
+  - "Canceling since a more recent run was started"
+root_cause: |
+  When a workflow uses a **static concurrency group** — one that does not
+  incorporate any per-run unique value like `github.run_id` or a user-supplied
+  input — and multiple `workflow_dispatch` runs are triggered in rapid succession
+  (e.g., from a batch API script, a label webhook fan-out, or automation), GitHub
+  Actions cancels all but the last run.
+
+  GitHub Actions enforces a limit of **1 running + 1 pending** run per concurrency
+  group. Each new dispatch replaces the existing pending run:
+
+  1. Run A starts → becomes "running"
+  2. Run B dispatched → becomes "pending" (waits for A)
+  3. Run C dispatched → **cancels Run B** (B was pending), C becomes "pending"
+  4. Run D dispatched → **cancels Run C**, D becomes "pending"
+  5. Only Run D eventually runs after Run A finishes.
+
+  This produces silent data loss when each dispatch carries different `inputs:`
+  (e.g., different artifact IDs, tenant IDs, or tags to process). All runs except
+  the last are silently discarded with "This run was cancelled."
+
+  Commonly triggered by:
+  - A webhook handler that dispatches one workflow run per event, with bursts of
+    events arriving simultaneously.
+  - Automation scripts that loop over a list and call `gh workflow run` for each item.
+  - A cron job that fans out to per-repo dispatches sharing the same workflow name.
+
+  Note: this is distinct from `concurrency-timing-040` (push + workflow_dispatch
+  sharing a group) — this issue occurs with ONLY workflow_dispatch runs sharing a
+  static group with no event-name differentiation.
+fix: |
+  **Option 1 (recommended): Include a unique input value in the concurrency group**
+  If each dispatch has a unique identifier as an input (e.g., a tenant ID, artifact
+  ID, or item key), include it in the concurrency group so different dispatches
+  get independent groups.
+
+  **Option 2: Include github.run_id in the concurrency group**
+  Using `github.run_id` makes every run its own concurrency group — effectively
+  disabling concurrency entirely. Use only if all runs are important and must
+  complete.
+
+  **Option 3: Use cancel-in-progress: false (no-queue mode)**
+  With `cancel-in-progress: false`, new pending runs do not cancel existing pending
+  ones. The 1-running + 1-pending limit still applies, but the *last* queued run
+  (not the most recent dispatch) survives. This still means high-burst dispatches
+  lose most runs.
+
+  **Option 4: Use a queue-based architecture**
+  For high-volume fan-out, avoid workflow_dispatch entirely. Instead, push items to
+  a queue (SQS, GitHub Issues, database) and have a single polling workflow process
+  items from the queue sequentially or in bounded parallel batches.
+fix_code:
+  - language: yaml
+    label: 'Include unique input in concurrency group to isolate per-dispatch runs'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            item_id:
+              description: 'Unique identifier for this dispatch'
+              required: true
+              type: string
+
+      concurrency:
+        # Each unique item_id gets its own concurrency slot — no cross-dispatch cancellation
+        group: ${{ github.workflow }}-${{ inputs.item_id }}
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Use github.run_id to guarantee all dispatches run independently'
+    code: |
+      on:
+        workflow_dispatch:
+
+      concurrency:
+        # Every run is its own group — effectively disables concurrency queueing
+        group: ${{ github.workflow }}-${{ github.run_id }}
+        cancel-in-progress: false
+  - language: yaml
+    label: 'Fan-out batch dispatch via matrix instead of separate workflow runs'
+    code: |
+      # Instead of dispatching N separate workflow runs (which cancel each other),
+      # dispatch ONE run with a matrix input to process all items in parallel.
+      on:
+        workflow_dispatch:
+          inputs:
+            item_ids:
+              description: 'JSON array of item IDs to process'
+              required: true
+              type: string
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: false
+
+      jobs:
+        process-items:
+          strategy:
+            matrix:
+              item_id: ${{ fromJSON(inputs.item_ids) }}
+          runs-on: ubuntu-latest
+          steps:
+            - name: Process item
+              run: echo "Processing ${{ matrix.item_id }}"
+prevention:
+  - 'Never use a static concurrency group (e.g., `group: ${{ github.workflow }}`) for workflows dispatched in batch — include a unique per-dispatch key.'
+  - 'When dispatching multiple runs from a script, add a unique ID as an input and include it in the concurrency group.'
+  - 'For high-volume fan-out workloads, use a single matrix job instead of N separate workflow_dispatch runs.'
+  - 'Monitor workflow cancellation counts in the Actions UI — unexpected "This run was cancelled" on dispatch events signals a concurrency group collision.'
+docs:
+  - url: 'https://github.com/github/gh-aw/issues/19467'
+    label: 'github/gh-aw#19467: Batch workflow_dispatch runs cancel each other via static concurrency group'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency — 1 running + 1 pending limit per group'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow'
+    label: 'GitHub Docs: Manually running a workflow'

package/errors/concurrency-timing/github-run-id-concurrency-group-disables-cancel-in-progress.yml

@@ -0,0 +1,90 @@
+id: concurrency-timing-048
+title: 'github.run_id in concurrency group key disables cancel-in-progress — every run is unique, unlimited parallelism'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - github-run-id
+  - unique-key
+  - parallelism
+  - anti-pattern
+patterns:
+  - regex: 'group:.*\$\{\{\s*github\.run_id\s*\}\}'
+    flags: 'i'
+  - regex: 'group:.*github\.run_id'
+    flags: 'i'
+error_messages:
+  - 'Old workflow runs are not being cancelled despite cancel-in-progress: true'
+  - 'Multiple concurrent runs executing simultaneously'
+root_cause: |
+  github.run_id is always unique per workflow run — it is the numeric identifier
+  assigned at run creation time. When used in the concurrency group key, every run
+  evaluates to a different group name. No two runs ever share the same group, so
+  cancel-in-progress: true has nothing to cancel. All runs proceed simultaneously.
+
+  This anti-pattern typically originates from developers who experienced unwanted
+  concurrency cancellations and "fixed" the problem by adding a unique value to the
+  group key. The immediate cancellation symptom disappears but a more serious problem
+  is introduced: on high-velocity branches, dozens of in-progress CI runs pile up
+  simultaneously, exhausting the available runner pool and increasing costs.
+
+  Related: github.sha in the group key has the same effect (concurrency-timing-030),
+  but github.run_id is more severe. github.sha can repeat when a commit is re-run;
+  github.run_id is unconditionally unique per run and per re-run attempt, so
+  cancel-in-progress is permanently disabled with no exceptions.
+fix: |
+  Remove github.run_id from the concurrency group key. Use github.ref (for branch-scoped
+  deduplication) or github.head_ref (for PR-scoped deduplication). If the original
+  goal was to prevent manual dispatch runs from being cancelled, scope the unique key
+  to workflow_dispatch events only using a conditional expression:
+
+    group: >-
+      ${{ github.workflow }}-
+      ${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.run_id makes every run unique — cancel-in-progress is dead code'
+    code: |
+      # WRONG: every run gets its own unique group — cancel-in-progress never fires
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_id }}
+        cancel-in-progress: true  # never cancels anything
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: 'Correct: branch-scoped group key enables cancel-in-progress'
+    code: |
+      # CORRECT: all pushes to same branch share one group
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: 'Advanced: isolate manual dispatch runs while deduplicating automated runs'
+    code: |
+      # Manual dispatch runs are never cancelled; push/PR runs cancel old runs on same branch
+      concurrency:
+        group: >-
+          ${{ github.workflow }}-
+          ${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
+        cancel-in-progress: true
+prevention:
+  - 'Never add github.run_id to a concurrency group key when the goal is to cancel old runs — it defeats cancel-in-progress entirely'
+  - 'Verify cancel-in-progress by triggering two rapid pushes and confirming the first run is cancelled in the Actions UI'
+  - 'If cancellation of specific trigger types is unwanted, use event_name-conditional keys instead of unique values'
+  - 'Monitor runner utilization — unbounded parallel runs will exhaust available runners and increase billing'
+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-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github context — run_id'

package/errors/concurrency-timing/pull-request-target-base-ref-concurrency-serializes-all-prs.yml

@@ -0,0 +1,78 @@
+id: concurrency-timing-046
+title: 'pull_request_target github.ref resolves to base branch — all PRs targeting same branch share one concurrency slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - pull_request_target
+  - github-ref
+  - base-branch
+  - serialization
+patterns:
+  - regex: 'on:\s*\n\s+pull_request_target:'
+    flags: 'ms'
+  - regex: 'group:.*github\.ref'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically queued'
+  - 'Waiting for a pending job to complete'
+root_cause: |
+  On pull_request events, github.ref is the head branch ref (e.g., refs/heads/my-feature).
+  On pull_request_target events, however, github.ref is the BASE branch ref (e.g.,
+  refs/heads/main) — the branch the PR targets. This is a security design choice that
+  prevents untrusted fork code from influencing the event ref.
+
+  When a concurrency group key uses github.ref in a pull_request_target workflow, all
+  open PRs targeting the same base branch (main, develop, etc.) evaluate to the identical
+  group key. Only one PR's CI can run at a time; all others queue behind it. On repos
+  with many open PRs, this effectively serializes all PR workflows into a single lane
+  with potentially multi-hour wait times.
+
+  The correct per-PR identifier in pull_request_target workflows is
+  github.event.pull_request.number — unique per PR regardless of base branch.
+fix: |
+  Replace github.ref with github.event.pull_request.number in concurrency group keys
+  for pull_request_target workflows. PR numbers are unique per repository and stable
+  across new commits to the same PR:
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.ref = base branch on pull_request_target — all PRs share one slot'
+    code: |
+      # WRONG: github.ref = refs/heads/main for ALL PRs targeting main
+      on:
+        pull_request_target:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}  # same for every PR!
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Correct: use github.event.pull_request.number for per-PR isolation'
+    code: |
+      # CORRECT: PR number is unique per PR, stable across pushes to same PR
+      on:
+        pull_request_target:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+prevention:
+  - 'In pull_request_target workflows, never use github.ref as the sole differentiator in concurrency groups — it is the base branch ref'
+  - 'Use github.event.pull_request.number to scope concurrency to individual PRs'
+  - 'Audit concurrency groups when migrating workflows from pull_request to pull_request_target'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target'
+    label: 'GitHub Docs: pull_request_target event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'

package/errors/concurrency-timing/workflow-dispatch-schedule-shared-concurrency-kills-scheduled-run.yml

@@ -0,0 +1,87 @@
+id: concurrency-timing-047
+title: 'workflow_dispatch and schedule sharing a concurrency group — manual dispatch silently cancels queued scheduled run'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow_dispatch
+  - schedule
+  - cancel-in-progress
+  - scheduled-job
+patterns:
+  - regex: 'schedule:.*\n.*workflow_dispatch:|workflow_dispatch:.*\n.*schedule:'
+    flags: 'ms'
+  - regex: 'group:\s*.*github\.workflow'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+root_cause: |
+  When a workflow is triggered by both schedule and workflow_dispatch and uses a shared
+  concurrency group key that does not include github.event_name (e.g.,
+  group: ${{ github.workflow }}-${{ github.ref }}), all runs — regardless of trigger
+  type — map to the same concurrency slot.
+
+  When cancel-in-progress: true is set, any manual workflow_dispatch run immediately
+  cancels the scheduled run that may be actively executing. A developer who triggers
+  a manual run can silently kill a scheduled maintenance job, nightly report, or backup
+  workflow with no warning or notification.
+
+  When cancel-in-progress: false, GitHub only keeps one pending run per concurrency
+  slot. A queued scheduled run is silently displaced when the dispatch run arrives.
+  The scheduled run is discarded with no error, no notification, and no log entry.
+
+  This affects maintenance workflows, report generators, data sync jobs, and backup
+  workflows where workflow_dispatch is added for "emergency manual runs" after the
+  initial scheduled implementation.
+fix: |
+  Include github.event_name in the concurrency group key to give each trigger type
+  its own independent concurrency slot:
+
+    group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+
+  This ensures that manual dispatch runs and scheduled runs never compete for the
+  same slot and cannot cancel each other.
+fix_code:
+  - language: yaml
+    label: 'Wrong: schedule and workflow_dispatch share the same concurrency slot'
+    code: |
+      on:
+        schedule:
+          - cron: '0 3 * * *'   # nightly at 03:00 UTC
+        workflow_dispatch:
+
+      # WRONG: both trigger types evaluate to the same group key
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true  # dispatch run kills the in-progress scheduled run
+  - language: yaml
+    label: 'Correct: include github.event_name to isolate trigger types'
+    code: |
+      on:
+        schedule:
+          - cron: '0 3 * * *'
+        workflow_dispatch:
+
+      # CORRECT: schedule and workflow_dispatch get separate concurrency slots
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        nightly:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./nightly-tasks.sh
+prevention:
+  - 'Always include ${{ github.event_name }} in the concurrency group for workflows with multiple trigger event types'
+  - 'After adding workflow_dispatch to an existing scheduled workflow, verify scheduled runs are not silently displaced'
+  - 'Monitor the Actions tab run history — consecutive scheduled run gaps may indicate silent cancellations'
+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#schedule'
+    label: 'GitHub Docs: schedule event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'GitHub Docs: workflow_dispatch event'

package/errors/runner-environment/sparse-checkout-persists-self-hosted-cross-run.yml

@@ -0,0 +1,99 @@
+id: runner-environment-174
+title: 'Sparse Checkout Config Persists Across Workflow Runs on Self-Hosted Runners'
+category: runner-environment
+severity: silent-failure
+tags:
+  - sparse-checkout
+  - self-hosted
+  - git-config
+  - workspace-reuse
+  - checkout
+  - non-ephemeral
+patterns:
+  - regex: 'core\.sparseCheckout\s*=\s*true'
+    flags: 'i'
+  - regex: 'sparse.checkout.*persist|persist.*sparse.checkout'
+    flags: 'i'
+  - regex: 'git sparse-checkout disable'
+    flags: 'i'
+error_messages:
+  - "Run actions/checkout@v4"
+  - "Checkout was successful but expected files are missing from working directory"
+  - "sparse-checkout: /run/git/config: sparseCheckout = true"
+root_cause: |
+  On non-ephemeral self-hosted runners, the workspace directory (e.g.
+  `/home/runner/work/my-repo/my-repo`) is reused across multiple workflow runs
+  on the same runner machine. When `actions/checkout` runs with `sparse-checkout:`
+  options, it sets `core.sparseCheckout = true` in the repository's `.git/config`
+  file.
+
+  In older versions of `actions/checkout` (before the fix in commit aadec89,
+  merged ~2025), the `disableSparseCheckout()` method reset `core.sparseCheckout`
+  only in `.git/config.worktree` (used in git worktrees), but NOT in the main
+  `.git/config`. As a result:
+
+  - **Workflow run N** uses `sparse-checkout:` → sets `core.sparseCheckout = true`
+    in `.git/config`.
+  - **Workflow run N+1** on the same runner does NOT use `sparse-checkout:`, but
+    inherits the stale `core.sparseCheckout = true` setting from the reused workspace.
+  - `actions/checkout` reports success, but the working directory contains only
+    the files that matched the previous run's sparse-checkout patterns. All other
+    files silently absent.
+
+  This is distinct from the same-job sticky cone mode issue (sf-008), which covers
+  two `actions/checkout` calls within a single job sharing sparse state. This issue
+  manifests across entirely separate workflow runs on a shared workspace.
+
+  Confirmed in actions/checkout#2249 (published Aug 2025) and actions/checkout#1992.
+fix: |
+  **Option 1 (recommended): Upgrade to actions/checkout v4.2.0+**
+  The bug was fixed in commit aadec89. Pinning to a patched release ensures
+  `disableSparseCheckout()` explicitly sets `core.sparseCheckout = false` in
+  `.git/config` when no `sparse-checkout:` input is provided.
+
+  **Option 2: Add an explicit `git sparse-checkout disable` step**
+  Add this step at the beginning of workflows that do NOT use sparse-checkout
+  on a runner that may previously have run sparse-checkout workflows:
+
+  **Option 3: Use ephemeral self-hosted runners**
+  Configure runners so each job gets a fresh workspace (e.g., ARC ephemeral mode,
+  EC2 runners with fresh AMIs). Ephemeral runners eliminate all cross-run workspace
+  contamination.
+
+  **Option 4: Configure runner to clean workspace between runs**
+  Set `ACTIONS_RUNNER_CLEAN_WORKSPACE=true` in the runner environment (where
+  supported) to force workspace cleanup between job runs.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to patched actions/checkout version'
+    code: |
+      steps:
+        - uses: actions/checkout@v4  # Use v4.2.0+ for the sparse-checkout fix
+          # No sparse-checkout options — will correctly restore full tree
+  - language: yaml
+    label: 'Explicit sparse-checkout reset before checkout on shared runners'
+    code: |
+      steps:
+        - name: Reset sparse-checkout (safety guard for shared self-hosted runners)
+          shell: bash
+          run: |
+            if git -C "${{ github.workspace }}" rev-parse --git-dir > /dev/null 2>&1; then
+              git -C "${{ github.workspace }}" sparse-checkout disable 2>/dev/null || true
+              git -C "${{ github.workspace }}" config --unset core.sparseCheckout 2>/dev/null || true
+            fi
+
+        - uses: actions/checkout@v4
+prevention:
+  - 'On self-hosted runners, always pin `actions/checkout` to v4.2.0+ which fixes the sparse-checkout persistence bug.'
+  - 'Add a `git sparse-checkout disable` guard step at the start of any workflow that runs on a non-ephemeral self-hosted runner.'
+  - 'Use ephemeral runners (fresh environment per job) to eliminate all cross-run workspace contamination.'
+  - 'Do not mix sparse-checkout and full-checkout workflows on the same non-ephemeral runner without resetting `.git/config` between runs.'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2249'
+    label: 'actions/checkout#2249: Sparse-checkout configuration persists across workflows on self-hosted runners'
+  - url: 'https://github.com/actions/checkout/issues/1992'
+    label: 'actions/checkout#1992: Sparscheckout breaks cached repository on self-hosted runners'
+  - url: 'https://github.com/actions/checkout/commit/aadec899646c8e0f34c52d9219c2faac36626b55'
+    label: 'Fix commit aadec89: Explicitly disable sparseCheckout in .git/config when not using sparse-checkout'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners (ephemeral vs self-hosted)'

package/errors/yaml-syntax/hashfiles-newline-delimiter-returns-empty.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-066
+title: 'hashFiles() Newline Delimiter in Single String Returns Empty — Use Multiple Arguments'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - hashfiles
+  - expression
+  - cache-key
+  - empty-string
+  - multifile
+  - glob
+  - newline-delimiter
+patterns:
+  - regex: 'hashFiles\([''"].*\\n.*[''"]'
+    flags: 'i'
+  - regex: 'hashFiles\s*\(\s*[''"][^''",]+\\n[^''",]+[''"]'
+    flags: 'i'
+error_messages:
+  - "${{ hashFiles('src/**\npackage.json') }}"
+  - "${{ hashFiles('**/*.lock\n**/*.toml') }}"
+  - "hashFiles result: ''"
+root_cause: |
+  The `@actions/glob` internal implementation documents that file patterns can be
+  separated by newline (`\n`) characters when passed as a single string. This causes
+  developers to write `hashFiles('file.ts\nfile.tsx')` expecting it to hash both
+  files.
+
+  However, inside a GitHub Actions expression (`${{ ... }}`), string literals do
+  NOT interpret escape sequences. The `\n` in `'file.ts\nfile.tsx'` is a literal
+  two-character sequence: backslash + "n". The glob function then looks for a file
+  literally named `file.ts\nfile.tsx` — which does not exist — and returns an empty
+  string `''`.
+
+  **Result:**
+  - `cache-key: ${{ hashFiles('package.json\nyarn.lock') }}` → cache key ends with
+    an empty string, causing ALL runs to collide on the same constant prefix key.
+  - `if: hashFiles('src/**\ntest/**') != ''` → always false (no hash returned), so
+    cache/condition logic silently skips.
+  - No error is raised; the expression just evaluates to `''` silently.
+
+  Confirmed in actions/runner#3467 and actions/runner#4049.
+
+  Note: `hashFiles()` DOES accept multiple comma-separated string arguments, and
+  each argument is a full glob pattern. The variadic call form works correctly.
+fix: |
+  Use multiple comma-separated arguments to `hashFiles()` instead of a
+  newline-delimited single string.
+
+  `hashFiles('pattern1', 'pattern2', ...)` correctly hashes all files matching
+  any of the provided glob patterns.
+
+  If you are building a dynamic list of patterns from a context value or step
+  output, write the patterns to a file and hash that file, or hash each pattern
+  in separate expressions and combine.
+fix_code:
+  - language: yaml
+    label: 'Use multiple arguments (correct) instead of newline-delimited string (broken)'
+    code: |
+      # BROKEN — \n is a literal backslash-n, not a newline; returns empty string
+      # key: npm-${{ hashFiles('package.json\npackage-lock.json') }}
+
+      # CORRECT — comma-separated arguments, hashes both files
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package.json', 'package-lock.json') }}
+  - language: yaml
+    label: 'Multiple lock files hashed with variadic hashFiles()'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            ~/.cache/pip
+          key: multi-${{ runner.os }}-${{ hashFiles('**/package-lock.json', '**/requirements*.txt', '**/Pipfile.lock') }}
+          restore-keys: |
+            multi-${{ runner.os }}-
+  - language: yaml
+    label: 'Conditional step using hashFiles() with multiple arguments'
+    code: |
+      # BROKEN — always evaluates to '' because \n is not a newline escape
+      # if: ${{ hashFiles('src/**\ntest/**') != '' }}
+
+      # CORRECT
+      - name: Check if source files changed
+        if: ${{ hashFiles('src/**', 'test/**') != '' }}
+        run: echo "Source files found"
+prevention:
+  - 'Never use `\n` as a pattern delimiter inside a `hashFiles()` call in a workflow expression — it is a literal backslash-n, not a newline.'
+  - 'Use multiple comma-separated arguments: `hashFiles(''pattern1'', ''pattern2'')` to hash files from multiple glob patterns.'
+  - 'When a `hashFiles()` result is used as a cache key suffix, validate it is non-empty by running the workflow once and checking the logged cache key.'
+  - 'If you suspect an empty hash, add a debug step: `run: echo "hash=${{ hashFiles(''**/*.lock'') }}"` to verify the value before using it in a key.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3467'
+    label: 'actions/runner#3467: hashFiles does not follow docs — newline delimiter in string returns empty'
+  - url: 'https://github.com/actions/runner/issues/4049'
+    label: 'actions/runner#4049: hashFiles newline pattern delimiter not interpreted in expressions'
+  - 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 — variadic arguments'

package/package.json

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