@htekdev/actions-debugger 1.0.117 → 1.0.119

package/errors/runner-environment/ubuntu-26-04-missing-preinstalled-tools.yml

@@ -0,0 +1,178 @@
+id: runner-environment-212
+title: 'ubuntu-26.04 Runner Image Removes Many Pre-installed Tools — grunt, gulp, tsc, webpack, lerna, fastlane, Pulumi, Julia, Miniconda Absent'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-26.04
+  - runner-image
+  - pre-installed-tools
+  - migration
+  - breaking-change
+  - nodejs-tools
+  - toolset
+patterns:
+  - regex: 'grunt: command not found|grunt.*not found.*ubuntu'
+    flags: 'i'
+  - regex: 'gulp: command not found|gulp.*not found.*ubuntu'
+    flags: 'i'
+  - regex: '(tsc|webpack|webpack-cli|lerna|newman|parcel): command not found'
+    flags: 'i'
+  - regex: 'fastlane: command not found|fastlane.*not found.*ubuntu'
+    flags: 'i'
+  - regex: 'pulumi: command not found|julia: command not found|conda: command not found'
+    flags: 'i'
+error_messages:
+  - '/usr/bin/env: grunt: No such file or directory'
+  - 'grunt: command not found'
+  - 'webpack: command not found'
+  - 'tsc: command not found'
+  - 'gulp: command not found'
+  - 'lerna: command not found'
+  - 'newman: command not found'
+  - 'parcel: command not found'
+  - 'fastlane: command not found'
+  - 'pulumi: command not found'
+  - 'julia: command not found'
+  - 'conda: command not found'
+root_cause: |
+  The ubuntu-26.04 GitHub Actions hosted runner image deliberately removes many
+  tools that were pre-installed on ubuntu-22.04 and ubuntu-24.04. The toolset
+  was slimmed as part of the ubuntu-26.04 image build (runner-images commit
+  9e3319d, `[ubuntu-26] Adjust installed software`, May 2026).
+
+  **Removed global Node.js CLI tools** (previously installed via npm globally):
+  - `grunt` / `grunt-cli`
+  - `gulp` / `gulp-cli`
+  - `tsc` (TypeScript compiler, was pre-installed globally)
+  - `webpack` and `webpack-cli`
+  - `lerna` (monorepo manager)
+  - `newman` (Postman CLI runner)
+  - `parcel` (zero-config bundler)
+
+  **Removed Ruby gems:**
+  - `fastlane` (iOS/Android CI automation)
+
+  **Removed language runtimes / tools:**
+  - `julia` (Julia language, x86_64 only — was in ubuntu-24.04 x64)
+  - `miniconda` / `conda` (x86_64 only — was in ubuntu-24.04 x64)
+  - `pulumi` (IaC CLI, both x86_64 and ARM64)
+
+  **Removed system utilities:**
+  - `mercurial` (hg version control)
+  - `haveged` (entropy daemon)
+  - `mediainfo` (media analysis tool)
+  - `sphinxsearch` (full-text search server)
+
+  **Other significant changes on ubuntu-26.04 vs ubuntu-24.04:**
+  - **Helm**: updated from 3.x → 4.x (get-helm-4 installer)
+  - **Docker Compose**: updated from 2.40.3 → 5.1.3 (major version bump)
+  - **Java default**: changed from Java 21 → Java 25
+  - `Fastlane` removed from rubygems pre-install
+
+  Workflows that rely on these tools being pre-installed without an explicit
+  installation step will fail immediately on ubuntu-26.04 with "command not
+  found" errors.
+fix: |
+  Explicitly install any removed tools in your workflow steps before use.
+
+  For global Node.js tools, add an installation step at the start of your job:
+
+  ```yaml
+  - name: Install build tools
+    run: npm install -g grunt-cli gulp-cli typescript webpack webpack-cli lerna newman parcel
+  ```
+
+  For fastlane:
+  ```yaml
+  - name: Install fastlane
+    run: gem install fastlane
+  ```
+
+  For Pulumi:
+  ```yaml
+  - uses: pulumi/actions@v6
+  # or
+  - name: Install Pulumi CLI
+    run: curl -fsSL https://get.pulumi.com | sh
+  ```
+
+  For Julia:
+  ```yaml
+  - uses: julia-actions/setup-julia@v2
+    with:
+      version: '1'
+  ```
+
+  For Conda / Miniconda:
+  ```yaml
+  - uses: conda-incubator/setup-miniconda@v3
+    with:
+      auto-activate-base: true
+  ```
+
+  For Java 21 (if Java 25 default breaks your build):
+  ```yaml
+  - uses: actions/setup-java@v4
+    with:
+      java-version: '21'
+      distribution: 'temurin'
+  ```
+fix_code:
+  - language: yaml
+    label: 'Explicitly install removed Node.js tools and pin Java version on ubuntu-26.04'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-26.04   # or ubuntu-latest when it aliases ubuntu-26.04
+          steps:
+            - uses: actions/checkout@v6
+
+            # Install tools removed from ubuntu-26.04 pre-installed toolset
+            - name: Install missing build tools
+              run: |
+                npm install -g grunt-cli typescript webpack webpack-cli lerna
+                gem install fastlane
+
+            # Pin Java version explicitly — ubuntu-26.04 defaults to Java 25
+            - uses: actions/setup-java@v4
+              with:
+                java-version: '21'
+                distribution: 'temurin'
+
+            - name: Build
+              run: |
+                tsc --version   # now available
+                grunt build     # now available
+  - language: yaml
+    label: 'Guard workflow with image-conditional tool install'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ matrix.os }}
+          strategy:
+            matrix:
+              os: [ubuntu-24.04, ubuntu-26.04]
+          steps:
+            - uses: actions/checkout@v6
+
+            # Install tools only when running on ubuntu-26.04
+            # where they are not pre-installed
+            - name: Install tools absent on ubuntu-26.04
+              if: startsWith(matrix.os, 'ubuntu-26')
+              run: npm install -g grunt-cli gulp-cli typescript webpack webpack-cli lerna newman
+
+            - name: Build
+              run: grunt build
+prevention:
+  - 'Do not rely on pre-installed tools being available across Ubuntu runner generations — explicitly install all tools your workflow depends on.'
+  - 'Pin Java version with actions/setup-java rather than relying on the image default Java version, which changed from 21 to 25 on ubuntu-26.04.'
+  - 'Use actions/setup-node + local project devDependencies instead of globally pre-installed Node.js tools (grunt, webpack, tsc, etc.).'
+  - 'Review the ubuntu-26.04 software manifest before migrating workflows from ubuntu-24.04 or ubuntu-latest.'
+  - 'When ubuntu-latest eventually aliases ubuntu-26.04, workflows that assume pre-installed tools from ubuntu-24.04 will break silently or with "command not found" errors.'
+docs:
+  - url: 'https://github.com/actions/runner-images/commit/9e3319d6b4acc306925295853d0ff41ddd5c40f0'
+    label: 'runner-images commit 9e3319d — [ubuntu-26] Adjust installed software (May 2026)'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Readme.md'
+    label: 'ubuntu-26.04 installed software manifest'
+  - url: 'https://github.com/actions/runner-images/issues/14150'
+    label: 'runner-images #14150 — PowerShell 7.4→7.6 announcement (lists ubuntu-26.04 as supported image)'

package/errors/runner-environment/upload-artifact-v6-proxy-headers-leak-strict-proxy-fail.yml

@@ -0,0 +1,101 @@
+id: runner-environment-208
+title: 'upload-artifact@v6 fails behind strict corporate proxy — ECONNRESET or HTTP 400 on CONNECT tunnel'
+category: runner-environment
+severity: error
+tags:
+  - upload-artifact
+  - v6
+  - proxy
+  - self-hosted
+  - ECONNRESET
+  - corporate-network
+  - azure-storage
+patterns:
+  - regex: 'Proxy connection ended before receiving CONNECT response'
+    flags: 'i'
+  - regex: 'Unable to make request: ECONNRESET'
+    flags: 'i'
+  - regex: 'upload-artifact@v[6-9]'
+    flags: 'i'
+error_messages:
+  - 'Error: Proxy connection ended before receiving CONNECT response'
+  - 'Error: Unable to make request: ECONNRESET'
+  - 'HTTP 400 Bad Request from proxy'
+root_cause: |
+  `actions/upload-artifact@v6` switched its Azure Blob Storage client from
+  `@azure/storage-blob` backed by `@azure/core-http` (used in v4/v5) to
+  `@azure/storage-blob` backed by `@azure/core-rest-pipeline` and
+  `@typespec/ts-http-runtime`.
+
+  The `proxyPolicy` in `@typespec/ts-http-runtime` contains a bug: it leaks
+  destination HTTP request headers — including `content-type`, `content-length`,
+  `x-ms-version`, and `accept` — directly into the HTTP `CONNECT` tunnel
+  request sent to the corporate proxy. RFC 9110 §9.3.6 does not expect
+  `CONNECT` requests to carry a `Content-Length`, and many strict enterprise
+  forward proxies (Squid with strict policies, Zscaler, BlueCoat, some HAProxy
+  configurations) reject `CONNECT` requests with unexpected headers.
+
+  This manifests as:
+  - `Proxy connection ended before receiving CONNECT response` — proxy drops
+    the connection before sending `200 Connection established`
+  - `ECONNRESET` — proxy resets the TCP connection
+  - HTTP 400 Bad Request — proxy rejects the malformed CONNECT
+
+  The issue does NOT reproduce with permissive proxies like default Squid
+  (which is why GitHub's own CI did not catch it). Only strict corporate proxies
+  that validate CONNECT request headers are affected.
+
+  `actions/upload-artifact@v5` uses the older `@azure/core-http` stack which
+  sends proper CONNECT tunnels without leaking headers, so workflows that pin
+  to v5 are not affected.
+
+  The fix was shipped in `actions/upload-artifact@v7.0.1` (April 12, 2026),
+  which bumps `@actions/artifact` to a version that uses the fixed
+  `@typespec/ts-http-runtime` proxyPolicy.
+fix: |
+  **Preferred fix:** Upgrade to `actions/upload-artifact@v7` (v7.0.1 or later):
+
+  ```yaml
+  - uses: actions/upload-artifact@v7
+    with:
+      name: build-artifacts
+      path: dist/
+  ```
+
+  **Temporary workaround (stay on v6):** Set the `HTTPS_PROXY` environment
+  variable AND apply a one-liner patch to strip headers from the ProxyAgent
+  call inside the cached action source:
+
+  ```yaml
+  - name: Patch upload-artifact proxy headers bug
+    run: |
+      for f in $(find "${GITHUB_WORKSPACE}/../.." -name "index.js" \
+        -path "*actions/upload-artifact*dist*" 2>/dev/null); do
+        sed -i 's/ProxyAgent(proxyUrl, { headers })/ProxyAgent(proxyUrl)/g' "$f"
+      done
+  ```
+
+  **Do NOT downgrade to v5** in new workflows; v5 relies on deprecated
+  dependencies. Upgrading to v7 is the correct long-term fix.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to upload-artifact@v7 (recommended)'
+    code: |
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: build-artifacts
+          path: dist/
+          retention-days: 7
+prevention:
+  - 'Always upgrade upload-artifact to @v7 or later on self-hosted runners that sit behind a corporate proxy'
+  - 'When adding new @v6 steps, test on a runner behind your actual proxy before deploying to all pipelines'
+  - 'If the proxy blocks the artifact upload step silently, enable RUNNER_DEBUG=1 to see the full CONNECT request/response cycle'
+  - 'Pin to upload-artifact@v7.0.1 or later — earlier v7 releases were not published, v7.0.1 is the first tagged release'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/issues/747'
+    label: 'upload-artifact#747 — V6 upload stalled behind proxy (10 reactions)'
+  - url: 'https://github.com/actions/upload-artifact/pull/792'
+    label: 'upload-artifact#792 — Fix proxy headers leak errconnect on strict proxies'
+  - url: 'https://github.com/actions/upload-artifact/releases/tag/v7.0.1'
+    label: 'upload-artifact v7.0.1 release notes — includes proxy fix'

package/errors/silent-failures/silent-failures-108.yml

@@ -0,0 +1,108 @@
+id: silent-failures-108
+title: 'Service container entrypoint: key silently clears Dockerfile CMD — Docker Compose semantics differ from Docker CLI'
+category: silent-failures
+severity: silent-failure
+tags:
+  - service-container
+  - docker
+  - entrypoint
+  - command
+  - docker-compose
+  - breaking-change
+  - april-2026
+patterns:
+  - regex: 'service.*container.*unhealthy|health.*check.*failed.*service'
+    flags: 'i'
+  - regex: 'Connection refused.*service|service.*port.*not.*reachable'
+    flags: 'i'
+  - regex: 'exec.*not.*enough.*arguments|usage:.*\[command\].*\[args\]'
+    flags: 'i'
+error_messages:
+  - 'Error: Service container failed health check after entrypoint override'
+  - 'Connection refused: service port not accepting connections'
+  - 'exec: not enough arguments — entrypoint launched without expected CMD'
+root_cause: |
+  GitHub Actions added explicit `entrypoint` and `command` keys for service containers
+  in the Early April 2026 update. These keys use **Docker Compose semantics**, which
+  differ from Docker CLI semantics in one critical way:
+
+  **Docker CLI** (`docker run --entrypoint /wrapper.sh image`):
+  - Overrides the image ENTRYPOINT
+  - **Keeps** the image CMD from the Dockerfile
+
+  **Docker Compose** / GitHub Actions `services.<name>.entrypoint` key:
+  - Overrides the image ENTRYPOINT
+  - **Clears the image CMD** — the container starts with no CMD arguments
+
+  This means that if a developer specifies only `entrypoint:` in a service container
+  (to wrap or replace the image's startup script) and does not also specify `command:`,
+  the container runs the new entrypoint with no arguments. For images that require CMD
+  arguments to function (e.g., a PostgreSQL image running `postgres`, a Redis image
+  running `redis-server`), the container may exit immediately, enter an error loop, or
+  start in a degraded mode.
+
+  The failure is silent because:
+  - The container may still pass a health check if it starts at all
+  - The job continues even if the service is in an unexpected state
+  - No GitHub Actions error is emitted for CMD mismatch
+
+  Example: migrating from `options: --entrypoint /wrapper.sh` (which preserved CMD)
+  to `entrypoint: /wrapper.sh` (which clears CMD) silently changes the container's
+  startup behaviour.
+fix: |
+  Always specify `command:` alongside `entrypoint:` in service container configuration
+  to explicitly provide the CMD arguments that the original Dockerfile would have
+  passed. Do not assume entrypoint-only overrides will inherit the Dockerfile CMD.
+
+  To preserve the original image's CMD, look up the image's Dockerfile CMD
+  (e.g., via `docker inspect <image> --format '{{.Config.Cmd}}'`) and replicate
+  it in the `command:` key.
+fix_code:
+  - language: yaml
+    label: 'Broken — entrypoint only, silently clears CMD (Docker Compose semantics)'
+    code: |
+      services:
+        db:
+          image: postgres:16
+          # WRONG: entrypoint alone clears the Dockerfile CMD ["postgres"]
+          # The container starts /wrapper.sh with no arguments — postgres never runs
+          entrypoint: /wrapper.sh
+
+  - language: yaml
+    label: 'Fixed — specify command: to preserve the intended CMD arguments'
+    code: |
+      services:
+        db:
+          image: postgres:16
+          env:
+            POSTGRES_PASSWORD: test
+          # Wrap the entrypoint AND preserve the original CMD
+          entrypoint: /wrapper.sh
+          command: ["postgres"]  # explicit CMD to preserve what Dockerfile would pass
+
+  - language: yaml
+    label: 'Alternative — use options: --entrypoint if you want to keep Dockerfile CMD'
+    code: |
+      services:
+        db:
+          image: postgres:16
+          env:
+            POSTGRES_PASSWORD: test
+          # Legacy approach: Docker CLI semantics — preserves Dockerfile CMD automatically
+          options: >-
+            --entrypoint /wrapper.sh
+            --health-cmd "pg_isready -U postgres"
+            --health-interval 5s
+
+prevention:
+  - 'When using the new entrypoint: key on a service container, always pair it with an explicit command: key — never rely on the Dockerfile CMD being inherited.'
+  - 'If migrating from options: --entrypoint to the new entrypoint: key, remember that the options: approach preserved CMD while the new key does not.'
+  - 'Test service container health immediately after adding entrypoint: overrides — a passing health check may mask CMD loss if the entrypoint script does not require CMD arguments.'
+  - 'Run docker inspect <image> --format "{{.Config.Cmd}}" locally to discover what CMD values the Dockerfile sets before overriding entrypoint in CI.'
+docs:
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/#customizing-entrypoints-for-service-containers'
+    label: 'GitHub Changelog: Customizing entrypoints for service containers (April 2026)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idservicesservice_identrypoint'
+    label: 'GitHub Docs: jobs.<id>.services.<id>.entrypoint syntax'
+  - url: 'https://docs.docker.com/compose/compose-file/05-services/#entrypoint'
+    label: 'Docker Compose docs: entrypoint key clears CMD'

package/errors/silent-failures/silent-failures-109.yml

@@ -0,0 +1,119 @@
+id: silent-failures-109
+title: 'electron-forge make Silently Exits 0 on Node.js 24.16.0+ — No .exe, No Error'
+category: silent-failures
+severity: silent-failure
+tags:
+  - electron-forge
+  - nodejs
+  - node24
+  - extract-zip
+  - toolcache
+  - regression
+  - windows
+  - packaging
+patterns:
+  - regex: 'Invalid input file path.{0,80}\.exe'
+    flags: 'i'
+  - regex: 'Finalizing package\s*$'
+    flags: 'im'
+  - regex: 'electron-forge make.{0,60}exit(?:ed)? (?:with )?(?:code )?0'
+    flags: 'i'
+  - regex: 'exec\: node\: not found'
+    flags: 'i'
+error_messages:
+  - 'Error: Invalid input file path - apps/desktop/out/<AppName>-win32-x64/<App>.exe'
+  - '❯ Finalizing package'
+  - 'exec: node: not found'
+  - '> Packaging for x64 on win32'
+root_cause: |
+  On the ubuntu-24.04 image update from 20260518.149.1 → 20260525.161.1 and
+  the Windows Server 2022/2025 image update from 20260518 → 20260525, the
+  cached Node.js toolcache version was bumped from 24.15.0 to 24.16.0. Node.js
+  24.16.0 contains an upstream regression in the readable-stream.destroy()
+  lifecycle that breaks yauzl (a ZIP reading library) and extract-zip which
+  depends on it.
+
+  `electron-forge make` uses extract-zip internally during the "Finalizing
+  package" phase to extract the Electron binary archive. When running under
+  Node.js 24.16.0 or 26.1.0+, the forge process:
+  1. Enters all packaging subtasks within ~5 ms (each spinner shows up instantly)
+  2. Exits with code 0 — no checkmarks, no error, no output
+  3. Produces no .exe in `out/<AppName>-win32-x64/`
+
+  The same regression affects other tools that use extract-zip internally:
+  - jsvu (JS engine version updater)
+  - Any npm package that has not yet migrated away from the 6-year-old
+    unmaintained extract-zip package
+
+  The affected subtasks (Copying files → Preparing native dependencies →
+  Finalizing package) complete within milliseconds instead of minutes, which
+  is the visible telltale sign — none receive a ✓ checkmark.
+
+  Upstream issues:
+  - https://github.com/nodejs/node/issues/63487 (yauzl/extract-zip partial extraction)
+  - https://github.com/nodejs/node/issues/63638 (libuv regression on Windows)
+  - https://github.com/electron/forge/issues/4277
+fix: |
+  Pin Node.js to 24.15.0 (last unaffected 24.x release) until Node.js 24.17.0
+  ships the upstream fix and it is rolled into the runner toolcache via
+  actions/node-versions:
+
+    - uses: actions/setup-node@v6
+      with:
+        node-version: '24.15.0'
+
+  Alternatively, downgrade to Node.js 22 LTS which is unaffected:
+
+    - uses: actions/setup-node@v6
+      with:
+        node-version: '22'
+
+  For jsvu users, the same pin applies. Track the upstream fix at
+  https://github.com/nodejs/node/issues/63487 and
+  https://github.com/electron/forge/issues/4277 for when to unpin.
+fix_code:
+  - language: yaml
+    label: 'Pin Node.js to 24.15.0 until extract-zip regression is fixed'
+    code: |
+      steps:
+        - uses: actions/checkout@v6
+
+        - name: Set up Node.js (pin to last unaffected 24.x)
+          uses: actions/setup-node@v6
+          with:
+            node-version: '24.15.0'   # 24.16.0+ breaks extract-zip / electron-forge
+            cache: 'npm'
+
+        - name: Install dependencies
+          run: npm ci
+
+        - name: Package (electron-forge)
+          run: npx electron-forge make --platform win32 --arch x64
+  - language: yaml
+    label: 'Fallback to Node.js 22 LTS (unaffected by regression)'
+    code: |
+      steps:
+        - uses: actions/setup-node@v6
+          with:
+            node-version: '22'   # LTS — unaffected by 24.16.0 extract-zip regression
+prevention:
+  - 'Pin exact Node.js minor versions in actions/setup-node — semver ranges like
+    "24" silently upgrade to patch/minor releases that may carry regressions.'
+  - 'Watch https://github.com/nodejs/node/issues/63487 and
+    https://github.com/electron/forge/issues/4277 for when the regression is
+    fixed in both Node.js upstream and electron-forge itself.'
+  - 'If forge make exits 0 but produces no output files, check whether the Node.js
+    version in use is >=24.16.0 or >=26.1.0 — the silent exit is the diagnostic.'
+  - 'Consider using a lock-file approach: pin node-version in setup-node AND add
+    a post-step assertion that the expected .exe exists before continuing.'
+docs:
+  - url: 'https://github.com/nodejs/node/issues/63487'
+    label: 'nodejs/node #63487 — yauzl/extract-zip hang and partial extraction (readable-stream regression)'
+  - url: 'https://github.com/nodejs/node/issues/63638'
+    label: 'nodejs/node #63638 — libuv regression in Node.js 24.16.0 on Windows'
+  - url: 'https://github.com/electron/forge/issues/4277'
+    label: 'electron/forge #4277 — make exits 0 silently on Node.js 24.16.0 / extract-zip regression'
+  - url: 'https://github.com/actions/runner-images/issues/14174'
+    label: 'runner-images #14174 — Windows 2022/2025 May 25 image: electron-forge make silent exit'
+  - url: 'https://github.com/actions/runner-images/issues/14173'
+    label: 'runner-images #14173 — Puppeteer broken in ubuntu-24.04 20260525 (same root cause)'

package/errors/silent-failures/silent-failures-110.yml

@@ -0,0 +1,91 @@
+id: silent-failures-110
+title: 'setup-node v6 cache:npm silently aborts entire Windows job when npm cache directory does not exist'
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-node
+  - windows
+  - npm
+  - cache
+  - silent-failure
+  - fresh-runner
+  - npm-cache-path
+patterns:
+  - regex: 'Found in cache.*\n(?:.*\n){0,5}Post job cleanup'
+    flags: 'im'
+  - regex: 'npm config get cache.*\n(?:.*\n){0,3}(?:Detected npm|Auto caching)'
+    flags: 'im'
+  - regex: 'setup-node.*cache.*npm.*windows.*abort'
+    flags: 'i'
+error_messages:
+  - 'Found in cache @ C:\hostedtoolcache\windows\node\22...'
+  - 'Detected npm as the package manager from package.json'
+  - 'Auto caching has been enabled for npm.'
+root_cause: |
+  actions/setup-node@v6 with `cache: 'npm'` (or auto-detected npm caching when
+  package.json has `packageManager: npm`) calls `npm config get cache` to locate the
+  npm cache directory before registering it with actions/cache.
+
+  On fresh Windows runners (hosted or self-hosted), `C:\npm\cache` does not yet exist
+  because no prior npm install has run in this workspace. The Node.js process executing
+  `npm config get cache` internally tries to initialise the npm config directory and
+  hits an EEXIST or missing-parent-directory race in npm's cache initialisation code
+  (npm/cli#7308). The runner process exits after ~24 seconds with no error message and
+  no non-zero exit code.
+
+  The result: every step AFTER setup-node is silently skipped. The job shows as
+  "Success" or the failure appears much later in a confusing step, making this
+  extremely hard to diagnose.
+
+  Affected versions: actions/setup-node@v6.4.0+; most frequently seen on
+  `windows-latest` and `windows-2025` hosted runners.
+fix: |
+  Remove `cache: 'npm'` from setup-node on Windows runners and handle npm caching
+  separately using actions/cache pointing at `~/.npm` or the correct Windows path.
+
+  Alternatively, run a no-op npm command before setup-node to force-create the cache
+  directory (not recommended as a long-term fix).
+
+  If npm caching is needed, use setup-node without `cache:` and add an explicit
+  actions/cache step after npm install has run at least once.
+fix_code:
+  - language: yaml
+    label: 'Remove cache:npm from setup-node; handle caching separately'
+    code: |
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          # Do NOT set cache: 'npm' on Windows — it silently aborts on fresh runners
+
+      - name: Get npm cache dir
+        id: npm-cache-dir
+        shell: pwsh
+        run: echo "dir=$(npm config get cache)" >> $env:GITHUB_OUTPUT
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.npm-cache-dir.outputs.dir }}
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      - run: npm ci
+  - language: yaml
+    label: 'Cross-platform: use cache:npm only on non-Windows'
+    code: |
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: ${{ runner.os != 'Windows' && 'npm' || '' }}
+prevention:
+  - 'Never set cache: npm in setup-node for Windows-targeted jobs without verifying the npm cache directory pre-exists.'
+  - 'When targeting multiple OSes with a matrix, conditionally disable cache:npm on Windows runners.'
+  - 'After setup-node on Windows, immediately run a trivial npm command (e.g., npm --version) and verify the step succeeds before continuing.'
+  - 'Pin setup-node version and watch the changelog for fixes to the Windows npm cache init race.'
+docs:
+  - url: 'https://github.com/unslothai/unsloth/pull/5474'
+    label: 'unsloth PR #5474 — drop cache:npm from setup-node (silent abort on Windows)'
+  - url: 'https://github.com/npm/cli/issues/7308'
+    label: 'npm/cli#7308 — EEXIST/missing-dir race in npm cache directory initialisation'
+  - url: 'https://github.com/actions/setup-node/issues/1556'
+    label: 'setup-node#1556 — setup-node silently falls through on download/extract failure'