@htekdev/actions-debugger 1.0.104 → 1.0.106

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/cache-save-restore-path-mismatch-silent-miss.yml

@@ -0,0 +1,93 @@
+id: caching-artifacts-062
+title: "actions/cache save and restore Separate Actions Silently Miss When Paths Differ"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cache-save
+  - cache-restore
+  - path-mismatch
+  - cache-miss
+  - silent
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: i
+error_messages:
+  - "Cache not found for input keys: my-cache-key"
+root_cause: |
+  When using actions/cache/save and actions/cache/restore as separate actions (split across
+  different jobs), the cache archive is indexed by BOTH the cache key AND the path provided
+  to the save action. The restore action must specify the EXACT same path as the save action
+  or no cache will be found, even when the key matches perfectly.
+
+  This is undocumented behaviour: the path is part of the cache version hash used to locate
+  the archive, not just the key. Using a relative vs absolute path, a trailing slash, or any
+  variation in path formatting between save and restore results in "Cache not found for input
+  keys" with no hint that path mismatch is the cause.
+
+  This differs from using the combined actions/cache action in a single job, where the path
+  is always consistent between save and restore. Reported in actions/cache#1444.
+fix: |
+  Ensure the path: value in actions/cache/restore exactly matches the path: value used in
+  actions/cache/save — including the same relative-vs-absolute format and no trailing slash
+  differences.
+
+  Best practice: extract the path into a shared env variable or workflow-level output, or
+  document the exact path string in both jobs.
+fix_code:
+  - language: yaml
+    label: "Wrong: different paths between save and restore jobs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Create files
+              run: mkdir my-files && echo "data" > my-files/data.txt
+            - uses: actions/cache/save@v4
+              with:
+                path: my-files           # saved with relative path
+                key: my-cache-${{ github.run_id }}
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache/restore@v4
+              with:
+                path: ./my-files         # WRONG: './my-files' != 'my-files' -- cache not found
+                key: my-cache-${{ github.run_id }}
+  - language: yaml
+    label: "Correct: identical path strings in save and restore"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Create files
+              run: mkdir my-files && echo "data" > my-files/data.txt
+            - uses: actions/cache/save@v4
+              with:
+                path: my-files           # use identical path
+                key: my-cache-${{ github.run_id }}
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache/restore@v4
+              with:
+                path: my-files           # exact match — cache found
+                key: my-cache-${{ github.run_id }}
+prevention:
+  - "Copy the exact path: string from your save step into your restore step — do not retype it"
+  - "Avoid mixing relative (my-dir) and absolute (${{ github.workspace }}/my-dir) paths across jobs"
+  - "If in doubt, use the combined actions/cache@v4 action in a single job instead of split save/restore"
+  - "Print the cache key and path in both jobs to make debugging easier"
+docs:
+  - url: "https://github.com/actions/cache/issues/1444"
+    label: "actions/cache#1444 — Restore reports cache not found when path differs from save path"
+  - url: "https://github.com/actions/cache/tree/main/save"
+    label: "actions/cache/save — Split save/restore documentation"
+  - url: "https://github.com/actions/cache/tree/main/restore"
+    label: "actions/cache/restore — Split save/restore documentation"

package/errors/caching-artifacts/setup-java-gradle-windows-lock-files-device-busy.yml

@@ -0,0 +1,81 @@
+id: caching-artifacts-061
+title: "setup-java cache: 'gradle' Silently Corrupts Cache on Windows — Gradle Lock Files Device or Resource Busy"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - setup-java
+  - gradle
+  - windows
+  - cache
+  - lock-files
+  - device-busy
+patterns:
+  - regex: '\.lock.*Read error.*Device or resource busy'
+    flags: i
+  - regex: 'fileContent\.lock.*Device or resource busy'
+    flags: i
+  - regex: '\.gradle/caches.*Read error.*byte 0'
+    flags: i
+error_messages:
+  - "/usr/bin/tar: C\\:/Users/runneradmin/.gradle/caches/8.7/fileContent/fileContent.lock: Read error at byte 0, while reading 38 bytes: Device or resource busy"
+  - "/usr/bin/tar: Exiting with failure status due to previous errors"
+  - "Warning: Failed to save: ... failed with exit code 2"
+root_cause: |
+  On Windows runners, actions/setup-java with cache: 'gradle' triggers a cache save in its
+  post-job step. At that point, the Gradle daemon process started during the build step may
+  still be running and holding open file locks on these cache directories:
+    - .gradle/caches/*/fileContent.lock
+    - .gradle/caches/*/fileHashes.lock
+    - .gradle/caches/*/generated-gradle-jars.lock
+    - .gradle/caches/*/javaCompile.lock
+    - .gradle/caches/journal-1/journal-1.lock
+    - .gradle/caches/modules-*/modules-*.lock
+
+  The GNU tar bundled with Git for Windows (used by the GitHub Actions runner) cannot read
+  Windows-locked files and exits with code 2. Despite this failure, setup-java logs
+  "Cache saved with the key: ..." because the cache service accepted a partial archive.
+
+  The silent failure: subsequent runs restore the partial cache, missing the locked files.
+  Gradle then redownloads dependencies on every run, and the cache save repeats the same
+  error. Cache size appears normal in the UI but the archive contents are incomplete.
+  Reported in actions/setup-java#633.
+fix: |
+  Stop the Gradle daemon explicitly before the post-job step fires. The setup-java
+  post-step runs after all workflow steps complete, so stopping the daemon in the last
+  step ensures no lock files are held when the post-step archives the cache:
+fix_code:
+  - language: yaml
+    label: "Fix: stop Gradle daemon before post-step cache save"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-java@v4
+              with:
+                java-version: '21'
+                distribution: 'temurin'
+                cache: 'gradle'
+            - name: Build with Gradle
+              run: ./gradlew build
+            - name: Stop Gradle daemon before cache save
+              if: always()
+              run: ./gradlew --stop
+  - language: yaml
+    label: "Alternative: build with --no-daemon (no daemon started, no lock files)"
+    code: |
+      - name: Build with Gradle (no daemon)
+        run: ./gradlew build --no-daemon
+prevention:
+  - "Always add a './gradlew --stop' step (with if: always()) after your build step on Windows runners"
+  - "Use --no-daemon for Gradle builds in CI to avoid daemon lock file issues entirely"
+  - "Verify cache usefulness by checking whether Gradle redownloads dependencies on runs after cache save"
+  - "Consider using the official gradle/actions/setup-gradle action which handles daemon lifecycle better"
+docs:
+  - url: "https://github.com/actions/setup-java/issues/633"
+    label: "actions/setup-java#633 — Gradle caching post-task fails on Windows with 'device or resource busy'"
+  - url: "https://docs.gradle.org/current/userguide/gradle_daemon.html"
+    label: "Gradle Daemon documentation — stopping and disabling"
+  - url: "https://github.com/gradle/actions/blob/main/docs/setup-gradle.md"
+    label: "gradle/actions — recommended Gradle CI caching action"

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/runner-environment/checkout-lfs-double-authorization-header-non-github-host.yml

@@ -0,0 +1,70 @@
+id: runner-environment-175
+title: "checkout@v4 LFS with Non-GitHub Host Sends Double Authorization Header -- 400 Bad Request"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - lfs
+  - git-lfs
+  - non-github-host
+  - authorization-header
+  - submodule
+patterns:
+  - regex: 'Authorization.*Authorization'
+    flags: i
+  - regex: 'HTTP.*400.*lfs'
+    flags: i
+error_messages:
+  - "trace git-lfs: HTTP: 400"
+  - "batch request failed with status 400"
+root_cause: |
+  When actions/checkout is used with lfs: true and the repository contains submodules
+  pointing to a non-GitHub host (Gitea, Bitbucket, self-hosted GitLab, etc.), the checkout
+  action writes an HTTP Authorization header into .git/config via http.<url>.extraheader.
+  For GitHub.com remotes this works correctly. However, for submodule remotes on other hosts,
+  the git-lfs client then sends BOTH this injected header AND its own credential-helper-derived
+  Authorization header in the same LFS batch request.
+
+  Most non-GitHub servers reject duplicate Authorization headers with HTTP 400 Bad Request,
+  as the HTTP spec treats repeated Authorization headers as ambiguous. GitHub.com silently
+  deduplicates them, hiding the problem. Only non-GitHub hosts expose this bug.
+
+  Diagnosed by enabling GIT_CURL_VERBOSE: 1 and GIT_TRACE: 1 in the workflow environment,
+  which reveals two Authorization: Basic lines in the same LFS request headers.
+  Reported in actions/checkout#1830 (15 reactions).
+fix: |
+  Use SSH key authentication for the non-GitHub submodule remote — no HTTP Authorization
+  header is injected for SSH remotes, eliminating the conflict:
+fix_code:
+  - language: yaml
+    label: "Recommended: use ssh-key for non-GitHub submodule host"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          lfs: true
+          ssh-key: ${{ secrets.SUBMODULE_SSH_KEY }}
+  - language: yaml
+    label: "Alternative: disable lfs on checkout and pull LFS per-host manually"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            submodules: recursive
+            lfs: false   # prevents checkout from injecting LFS auth header
+        - name: Clear injected extraheader and pull LFS for non-GitHub host
+          env:
+            GIT_CURL_VERBOSE: "1"
+          run: |
+            cd path/to/non-github-submodule
+            git config --unset http.https://your-host.example.com/.extraheader || true
+            git lfs pull
+prevention:
+  - "Use SSH keys for non-GitHub submodule remotes to avoid HTTP credential injection conflicts"
+  - "Enable GIT_CURL_VERBOSE=1 to diagnose duplicate Authorization headers in LFS requests"
+  - "Test LFS workflows after upgrading checkout to a new major version"
+docs:
+  - url: "https://github.com/actions/checkout/issues/1830"
+    label: "actions/checkout#1830 -- LFS fails with double auth header on non-GitHub host"
+  - url: "https://github.com/actions/checkout#readme"
+    label: "actions/checkout -- lfs and submodules input documentation"

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.104",
+  "version": "1.0.106",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",