@htekdev/actions-debugger 1.0.113 → 1.0.114

package/errors/runner-environment/cache-restore-windows-runner-silent-crash.yml

@@ -0,0 +1,130 @@
+id: runner-environment-196
+title: 'actions/cache restore silently crashes Windows runner — job jumps to Post cleanup with no error'
+category: runner-environment
+severity: silent-failure
+tags:
+  - cache
+  - windows
+  - crash
+  - silent-failure
+  - cargo
+  - large-cache
+  - post-cleanup
+patterns:
+  - regex: 'Cache hit for:.*\n(?:.*\n){0,3}Post job cleanup'
+    flags: 'i'
+  - regex: 'Cache hit for:[\s\S]{0,200}Post job cleanup'
+    flags: 'i'
+  - regex: 'Cache up-to-date\.\s*\(node:\d+\) \[DEP0040\] DeprecationWarning.*punycode'
+    flags: 'i'
+error_messages:
+  - 'Cache hit for: [key]'
+  - 'Post job cleanup.'
+  - 'Cache up-to-date.'
+root_cause: |
+  On Windows GitHub-hosted runners, actions/cache@v5 can silently crash the Node.js
+  runner process during cache restore when extracting very large cache archives (multi-GB
+  caches, e.g. Rust/Cargo registry + cache, large Maven/Gradle dependency trees).
+
+  The failure manifests as the job jumping directly from "Cache hit for: [key]" to
+  "Post job cleanup." with no intervening restore log lines and no error message.
+  The step exits with code 0 (success), but the cache was never extracted. Subsequent
+  build steps fail with missing dependency errors (e.g. "error: no such file or directory:
+  ~/.cargo/registry") rather than a cache-related error, making the root cause opaque.
+
+  The log sequence for affected runs:
+  1. "Cache hit for: [cache-key]"  (restore begins)
+  2. [no tar extraction log lines]
+  3. "Post job cleanup."            (job finishes or runner crashes)
+  4. "Cache up-to-date."
+  5. "(node:XXXX) [DEP0040] DeprecationWarning: The `punycode` module is deprecated"
+  6. "Post job cleanup."
+
+  Root cause analysis: The Windows runner process (Runner.Worker.exe) terminates
+  abnormally during tar/zstd decompression of the cache archive. This appears to be a
+  memory-related crash (similar to the Windows heap corruption pattern in upload-artifact,
+  tracked in toolkit#2406) triggered by the high memory pressure of decompressing large
+  archives within the Node.js 20 heap on Windows runners as of May 2026.
+
+  The crash is non-deterministic (intermittent) — the same cache key may restore
+  successfully on retry. Affected cache sizes are typically 1 GB+ uncompressed.
+  Rust Cargo caches (registry/index + registry/cache + git/db) are the most commonly
+  reported trigger.
+
+  Source: actions/cache#1754 (May 2026, Windows runner, Cargo cache).
+fix: |
+  Short-term workaround: Add `continue-on-error: true` to the cache restore step.
+  The job will proceed to the build step which will then reinstall dependencies from
+  scratch. The build takes longer but completes reliably.
+
+  Preferred workaround: Split the cache into smaller chunks. Rust/Cargo caches can be
+  split by caching registry/index, registry/cache, and git/db in separate cache steps
+  with different keys, keeping each archive under ~500 MB.
+
+  Alternative: Use sccache or a remote cache (e.g. Cloudflare R2 + sccache) instead of
+  actions/cache for Rust builds on Windows — this avoids large local archives entirely.
+
+  Long-term: Track actions/cache#1754 for an upstream fix. Adding
+  `ACTIONS_STEP_DEBUG: true` as a repository secret may reveal the crash signal in
+  verbose runner logs.
+fix_code:
+  - language: yaml
+    label: 'Short-term: continue-on-error to prevent job failure on crash'
+    code: |
+      - name: Restore Cargo cache
+        uses: actions/cache@v5
+        continue-on-error: true   # Job proceeds even if cache restore crashes
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+  - language: yaml
+    label: 'Split large Cargo cache into smaller chunks to avoid crash threshold'
+    code: |
+      - name: Restore Cargo registry index (small, fast)
+        uses: actions/cache@v5
+        with:
+          path: ~/.cargo/registry/index/
+          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-index-
+
+      - name: Restore Cargo registry cache (large packages)
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: ~/.cargo/registry/cache/
+          key: ${{ runner.os }}-cargo-cache-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-cache-
+
+      - name: Restore Cargo git sources
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-git-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Restore build target dir
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: target/
+          key: ${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.lock') }}
+
+prevention:
+  - 'Keep individual cache archives under ~500 MB by splitting large dependency trees (Cargo, Maven, Gradle) into multiple cache steps'
+  - 'Add continue-on-error: true to cache restore steps on Windows runners as a safety net for intermittent crashes'
+  - 'Monitor workflow durations — a sudden increase in Windows build time (cache miss equivalent) with no cache-related error in logs is a symptom of this crash'
+  - 'For Rust/Cargo on Windows runners, consider sccache with a remote backend to avoid large local cache archives entirely'
+  - 'Enable ACTIONS_STEP_DEBUG=true (as repository secret) to capture runner-level crash signals when this failure is suspected'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1754'
+    label: 'actions/cache#1754 — Windows runner randomly dies during cache restore (May 2026)'
+  - url: 'https://github.com/actions/cache#tips-for-using-cache'
+    label: 'actions/cache — usage tips and cache size guidance'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'Caching dependencies — limits and best practices'

package/errors/runner-environment/git-248-fetch-tags-shallow-clone-regression.yml

@@ -0,0 +1,100 @@
+id: runner-environment-190
+title: 'Git 2.48.0 silently stops fetching tags with fetch-tags: true on non-depth-1 shallow clones'
+category: runner-environment
+severity: silent-failure
+tags:
+  - git-version
+  - fetch-tags
+  - shallow-clone
+  - fetch-depth
+  - ubuntu-24.04
+  - regression
+  - checkout
+patterns:
+  - regex: 'git version 2\.48\.'
+    flags: 'i'
+  - regex: 'fetch-tags.*fetch-depth|fetch-depth.*fetch-tags'
+    flags: 'i'
+error_messages:
+  - "# No error — tags are silently absent after checkout with fetch-tags: true and fetch-depth: N on git 2.48.0"
+  - "fatal: No names found, cannot describe anything."
+  - "fatal: not a tag 'HEAD'"
+root_cause: |
+  Git 2.48.0 introduced a change in how `git fetch --depth=N` handles tag following for
+  direct refspec fetches. In git ≤ 2.47.x, when actions/checkout ran:
+
+    git fetch --depth=N origin +<sha>:refs/remotes/origin/<branch>
+
+  git would automatically follow tags reachable within the depth window — any tag pointing
+  to a commit within the fetched depth was included. This is known as automatic tag following.
+
+  Starting with git 2.48.0, automatic tag following is suppressed for direct refspec fetches
+  with `--depth`. Only the explicitly requested ref is fetched; no tags are included even if
+  they point to commits within the shallow clone window. The fetch log shows only the branch
+  ref fetched — no tag lines appear.
+
+  Result: `fetch-tags: true` combined with `fetch-depth: N` (where N > 1, such as 100, 383, 500)
+  silently returns no tags on runner images shipping git 2.48.0. The workflow log shows no error
+  and no warning — `git tag -l` returns empty. Downstream steps using git describe, semantic-release,
+  helm chart versioning, or any tool that reads git tags break with "no names found" or
+  "not a tag 'HEAD'" errors.
+
+  This regression first appeared when ubuntu-24.04 runner image updated from 20250105.1.0 to
+  20250113.1.0 (which shipped git 2.48.0). The issue was resolved in runner image 20250117.1.0+
+  when git was updated to 2.48.1 which patched the regression. Self-hosted runners running
+  git 2.48.0 remain affected.
+
+  Note: This is distinct from the existing known silent failure where fetch-depth: 1 silently
+  fetches no tags regardless of git version. That is expected shallow-clone behavior. This
+  regression affects fetch-depth: N > 1 scenarios that previously worked.
+fix: |
+  Use `fetch-depth: 0` when git tags are required. A full clone fetches all history and all
+  tags regardless of git version. This is the most reliable fix.
+
+  For large repositories where a full clone is too slow, add a separate fetch --tags step
+  immediately after checkout to explicitly fetch all tag objects:
+
+    git fetch --tags --force
+
+  Self-hosted runners on git 2.48.0 should upgrade to git 2.48.1 or later which patches
+  the tag following regression.
+fix_code:
+  - language: yaml
+    label: 'Use fetch-depth: 0 for reliable tag fetching (recommended)'
+    code: |
+      - name: Checkout with full history and all tags
+        uses: actions/checkout@v4
+        with:
+          # fetch-depth: 0 always fetches all commits and tags regardless of git version
+          fetch-depth: 0
+  - language: yaml
+    label: 'Add explicit git fetch --tags step after shallow checkout'
+    code: |
+      - name: Checkout (shallow)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 100
+          # fetch-tags: true is unreliable on git 2.48.0 — use explicit fetch instead
+
+      - name: Fetch tags explicitly (git-version-safe)
+        run: git fetch --tags --force
+  - language: yaml
+    label: 'Check git version in CI for debugging'
+    code: |
+      - name: Debug git version and tags
+        run: |
+          git --version
+          git tag -l | head -20
+          git describe --tags --always || echo "No reachable tags"
+prevention:
+  - 'Always use fetch-depth: 0 when git tags are required by downstream steps like git describe or semantic-release'
+  - 'Add a git tag -l debug step after checkout to verify tags are present before release tooling runs'
+  - 'For self-hosted runners, prefer git 2.48.1+ over 2.48.0 — the regression was patched in 2.48.1'
+  - 'Pin to fetch-depth: 0 in release workflows — the performance cost of a full clone is worth the reliability'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2041'
+    label: 'actions/checkout#2041: Tags no longer fetch with Git v2.48.0'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout — fetch-depth and fetch-tags input documentation'
+  - url: 'https://git-scm.com/docs/git-fetch#_description'
+    label: 'git fetch documentation — tag following with --depth'

package/errors/runner-environment/javascript-actions-alpine-arm64-not-supported.yml

@@ -0,0 +1,121 @@
+id: runner-environment-195
+title: 'JavaScript Actions in Alpine containers not supported on ARM64 runners'
+category: runner-environment
+severity: error
+tags:
+  - alpine
+  - arm64
+  - javascript-action
+  - container
+  - ubuntu-24.04-arm
+  - musl
+patterns:
+  - regex: 'JavaScript Actions in Alpine containers are only supported on x64 Linux runners'
+    flags: 'i'
+  - regex: 'Detected Linux Arm64'
+    flags: 'i'
+  - regex: 'JavaScript Actions in Alpine containers.*Detected Linux'
+    flags: 'i'
+error_messages:
+  - 'Error: JavaScript Actions in Alpine containers are only supported on x64 Linux runners. Detected Linux Arm64'
+root_cause: |
+  The Actions runner's container hook for JavaScript-based actions (actions that use
+  `using: node20` or `using: node24` in their action.yml) includes a hard platform check
+  when the container image is detected as Alpine Linux.
+
+  Alpine Linux uses musl libc instead of glibc. The Node.js binaries bundled inside
+  GitHub-hosted Actions runners are compiled against glibc and cannot run inside Alpine
+  containers without compatibility shims. The runner guards against this by rejecting
+  JavaScript action execution in Alpine containers that are not on x64 Linux, where a
+  limited musl-compatibility workaround exists.
+
+  On ARM64 runners (ubuntu-24.04-arm, ubuntu-22.04-arm), the runner explicitly rejects
+  JavaScript actions run inside Alpine containers with this error. The check evaluates the
+  container image's /etc/os-release ID field: when ID=alpine is found AND the runner
+  architecture is not x64, the error is thrown.
+
+  Common trigger patterns:
+  - Workflow uses `container: alpine` or a custom image FROM alpine
+  - One or more steps use JavaScript-based actions (e.g. actions/upload-artifact,
+    actions/checkout, actions/setup-node)
+  - Workflow or matrix includes ubuntu-24.04-arm or ubuntu-22.04-arm runners
+
+  Upgrading to a larger ubuntu-based base image resolves the issue because glibc is
+  present. There is no planned fix to add ARM64 Alpine support to the runner.
+fix: |
+  Option 1 (recommended): Replace the Alpine container with a Debian/Ubuntu-based image.
+  Alpine is often chosen for image size, but if JavaScript actions must be used inside the
+  container, a glibc-based image is required on ARM64 runners.
+
+  Option 2: Run JavaScript actions as host-level steps (outside the container) and
+  restrict container use to run: shell steps that do not invoke JS actions.
+
+  Option 3: Restrict ARM64 runners to non-Alpine container images in your matrix.
+
+  Option 4: If the Alpine container is only for the build environment, restructure the
+  workflow so JavaScript actions (checkout, upload-artifact, etc.) run before the
+  container is started rather than inside it.
+fix_code:
+  - language: yaml
+    label: 'Replace Alpine with Debian-slim (smallest glibc image)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm
+          container:
+            # Replace: image: alpine:latest
+            image: debian:bookworm-slim   # glibc-based, JS actions work on ARM64
+          steps:
+            - uses: actions/checkout@v6
+            - run: apt-get update && apt-get install -y curl
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output
+                path: dist/
+
+  - language: yaml
+    label: 'Run JS actions on host, only use Alpine container for build steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm
+          steps:
+            # Checkout on host (no container) — JS action works fine
+            - uses: actions/checkout@v6
+            # Run build inside Alpine via docker run (shell step, not JS action)
+            - name: Build in Alpine
+              run: |
+                docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work \
+                  alpine:latest sh -c "apk add --no-cache build-base && make"
+            # Upload on host — JS action works fine
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output
+                path: dist/
+
+  - language: yaml
+    label: 'Matrix: restrict Alpine container to x64 runners only'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ matrix.runner }}
+          container:
+            image: ${{ matrix.runner == 'ubuntu-24.04-arm' && 'debian:bookworm-slim' || 'alpine:latest' }}
+          strategy:
+            matrix:
+              runner: [ubuntu-24.04, ubuntu-24.04-arm]
+          steps:
+            - uses: actions/checkout@v6
+
+prevention:
+  - 'Never use Alpine-based container images on ARM64 GitHub-hosted runners if any workflow step calls a JavaScript action'
+  - 'Use debian:bookworm-slim or ubuntu:24.04 as a lightweight glibc alternative to Alpine when JS actions must run in-container on ARM64'
+  - 'When migrating workflows to ARM64 runners, audit all container: image values for Alpine derivation (FROM alpine, alpine:latest, alpine:3.x)'
+  - 'Run JavaScript actions (checkout, upload-artifact, setup-*) as host-level steps before or after the Alpine container block when possible'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/issues/739'
+    label: 'actions/upload-artifact#739 — JS Actions in Alpine containers not supported on ARM64 (Feb 2026)'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources'
+    label: 'GitHub-hosted runners — ARM64 runner support'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container'
+    label: 'Running jobs in a container'

package/errors/runner-environment/runner-environment-188.yml

@@ -0,0 +1,96 @@
+id: runner-environment-188
+title: "macOS Self-Hosted Runner Concurrent Checkout Hangs — git-credential-osxkeychain Deadlock"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - self-hosted
+  - checkout
+  - concurrent
+  - osxkeychain
+  - credential
+  - hang
+patterns:
+  - regex: 'git-credential-osxkeychain store'
+    flags: i
+  - regex: 'run_command.*git-credential-osxkeychain'
+    flags: i
+error_messages:
+  - "trace: run_command: 'git credential-osxkeychain store'"
+  - "trace: exec: git-credential-osxkeychain store"
+  - "trace: start_command: /opt/homebrew/opt/git/libexec/git-core/git-credential-osxkeychain store"
+root_cause: |
+  When two or more concurrent jobs on the same macOS self-hosted runner both execute
+  `actions/checkout`, each job's git process attempts to acquire the macOS Keychain to store
+  the authentication token via `git-credential-osxkeychain`. Because the macOS Keychain
+  serializes write access, a second concurrent credential store call waits indefinitely for
+  the first to release the keychain lock — creating a deadlock that never resolves on its own.
+
+  The job hangs silently. The last visible log line is always the `git-credential-osxkeychain
+  store` trace, followed by no output until the 6-hour GitHub Actions job timeout cancels
+  the run. There is no error message — the step simply never completes.
+
+  Runner v2.331.0 (which moved the base macOS image to 26 / Tahoe) and checkout@v6 together
+  worsened the race condition frequency. The issue also affects earlier runner/checkout
+  version combinations when multiple jobs share the same macOS self-hosted runner workspace.
+fix: |
+  Two workarounds exist. The most reliable is a pre-checkout workspace cleanup step that
+  removes leftover lock files from prior concurrent runs. The second is disabling credential
+  persistence so git never calls the macOS Keychain at all.
+
+  Option A (most reliable — workspace cleanup before every checkout):
+    Add a step before `actions/checkout` that removes all workspace contents. This eliminates
+    stale `.git/index.lock`, `.git/gc.pid` and credential lock files that cause the hang.
+
+  Option B (simpler — disable credential persistence):
+    Set `persist-credentials: false` on the checkout step. This prevents git from calling
+    `git-credential-osxkeychain store` entirely since no token is persisted. Note: this
+    means subsequent git operations in the same job cannot use the persisted token, so you
+    must pass the token explicitly in each git call that needs it.
+
+  If the workspace directory itself is the issue (leftover `.git/index.lock`), add an explicit
+  pre-step that deletes `.git/index.lock` and `.git/gc.pid` if they exist.
+fix_code:
+  - language: yaml
+    label: "Option A — pre-checkout workspace cleanup (most reliable)"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            - name: Clean workspace before checkout
+              run: |
+                find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
+                  || echo "::warning::Workspace cleanup failed due to concurrent writes. Not fatal."
+            - uses: actions/checkout@v6
+  - language: yaml
+    label: "Option B — disable credential persistence to skip keychain"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            - uses: actions/checkout@v6
+              with:
+                persist-credentials: false
+  - language: yaml
+    label: "Delete stale git lock files before checkout"
+    code: |
+      - name: Remove stale git lock files
+        run: |
+          rm -f "$GITHUB_WORKSPACE/.git/index.lock"
+          rm -f "$GITHUB_WORKSPACE/.git/gc.pid"
+      - uses: actions/checkout@v6
+prevention:
+  - "Use ephemeral self-hosted macOS runners (each job gets a fresh runner) to eliminate workspace state sharing between concurrent jobs"
+  - "Limit concurrency on the macOS runner's job queue to 1 using a concurrency group if ephemeral runners are not available"
+  - "Add a pre-checkout workspace cleanup step as a defensive measure on all macOS self-hosted runner jobs"
+  - "Set `persist-credentials: false` if downstream git operations do not require the persisted token"
+  - "Upgrade to the latest actions/checkout — version tags and runner versions interact; newer releases may reduce the deadlock window"
+docs:
+  - url: "https://stackoverflow.com/questions/79881327/github-actions-self-hosted-runner-on-macos-tries-to-checkout-repository-forever"
+    label: "Stack Overflow — macOS self-hosted runner checkout hangs forever (Feb 2026)"
+  - url: "https://github.com/actions/checkout/issues/550"
+    label: "actions/checkout#550 — Checkout gets stuck forever randomly on self-hosted runners"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "GitHub Docs: About self-hosted runners"

package/errors/runner-environment/runner-environment-191.yml

@@ -0,0 +1,147 @@
+id: runner-environment-191
+title: 'GHCup 0.1.x → 0.2.x Upgrade on Ubuntu Runners Breaks Direct ghcup CLI Usage'
+category: runner-environment
+severity: error
+tags:
+  - haskell
+  - ghcup
+  - ubuntu-22.04
+  - ubuntu-24.04
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: 'ghcup: command not found'
+    flags: 'i'
+  - regex: 'ghcup list.*-r[0-9]+|version.*-r[0-9].*not found'
+    flags: 'i'
+  - regex: '\$HOME/\.ghcup/bin/ghc.*no such file|\.ghcup/bin/ghc.*not a regular file'
+    flags: 'i'
+  - regex: 'ghcup.*cabal install.*unknown command|cabal install.*unrecognized.*ghcup'
+    flags: 'i'
+error_messages:
+  - 'test -f ~/.ghcup/bin/ghc returned false (ghc not installed)'
+  - 'GHC version 9.6.6-r1 was not found in the expected location'
+  - 'Error: The value 9.6.6-r1 is not a valid GHC version'
+  - 'ghcup: error: no subcommand: cabal install'
+root_cause: |
+  The ubuntu-22.04 and ubuntu-24.04 runner image update released 2026-05-26
+  (ubuntu24/20260525.161.1, ubuntu22/20260525.156.1) upgraded the pre-installed GHCup
+  from 0.1.50.2 to 0.2.5.0. GHCup 0.2.x introduced several breaking CLI and
+  filesystem changes that affect workflows calling ghcup directly.
+
+  **Breaking changes in GHCup 0.2.x:**
+
+  1. **`ghcup list` version strings now include a `-rX` revision suffix** when a
+     revision update is available (e.g., `9.6.6-r1` instead of `9.6.6`). Scripts
+     that parse `ghcup list` output for version equality checks (e.g., `grep 9.6.6`)
+     or that pipe the version into other tools fail because of the unexpected suffix.
+
+  2. **`~/.ghcup/bin/` is now entirely composed of symlinks** (except the `ghcup`
+     binary itself). Previously, some binaries (like `ghc`, `cabal`, `hls`) were
+     hardlinks or regular executable files. Workflow steps using the POSIX file-
+     existence test `-f ~/.ghcup/bin/ghc` now return false because `-f` returns
+     false for symlinks. The check must be `-e` (exists) or `-L` (is symlink).
+
+  3. **Old undocumented subcommand alias removed**: `ghcup cabal install <ver>` as
+     an alternative form is gone. The canonical form `ghcup install cabal <ver>` and
+     `ghcup install ghc <ver>` still work. Workflows that copied old forum examples
+     using the deprecated form receive an "unknown subcommand" error.
+
+  4. **`ghcup compile hls --isolate=<dir>` changed output path**: binaries are now
+     installed into `<dir>/bin/` instead of `<dir>/`. Scripts expecting the binary
+     directly at the isolate path fail with "file not found".
+
+  Note: The `--install-targets` flag bug present in GHCup 0.2.0–0.2.2 was already
+  fixed before the runner images updated (runner ships 0.2.5.0). That specific bug
+  does not affect GitHub-hosted runners.
+fix: |
+  **For `-f` file existence checks** — replace with `-e` (any file type) or
+  `-L` (is symlink):
+
+  ```bash
+  # Before (breaks on GHCup 0.2.x):
+  if [ -f "$HOME/.ghcup/bin/ghc" ]; then ...
+
+  # After:
+  if [ -e "$HOME/.ghcup/bin/ghc" ]; then ...
+  ```
+
+  **For version parsing from `ghcup list`** — strip the revision suffix:
+
+  ```bash
+  GHC_VER=$(ghcup list -t ghc --show-criteria 'recommended' -r | awk '{print $2}' \
+    | sed 's/-r[0-9]*$//')
+  ```
+
+  Or use `--show-revisions=none` to suppress the suffix entirely:
+
+  ```bash
+  ghcup list -t ghc --show-revisions=none
+  ```
+
+  **For old subcommand syntax** — use the canonical form:
+
+  ```bash
+  # Before:
+  ghcup cabal install 3.12.1.0
+
+  # After:
+  ghcup install cabal 3.12.1.0
+  ```
+
+  **Best practice** — use `haskell-actions/setup` instead of calling ghcup
+  directly. The action is maintained to handle ghcup version changes:
+
+  ```yaml
+  - uses: haskell-actions/setup@v2
+    with:
+      ghc-version: '9.6.6'
+      cabal-version: 'latest'
+  ```
+fix_code:
+  - language: yaml
+    label: 'Use haskell-actions/setup instead of raw ghcup commands'
+    code: |
+      - name: Set up GHC
+        uses: haskell-actions/setup@v2
+        with:
+          ghc-version: '9.6.6'
+          cabal-version: 'latest'
+          enable-stack: false
+
+  - language: yaml
+    label: 'Conditional GHCup binary check — fix -f to -e'
+    code: |
+      - name: Check if GHC is available
+        run: |
+          # GHCup 0.2.x: all ~/.ghcup/bin/ entries are symlinks; use -e not -f
+          if [ -e "$HOME/.ghcup/bin/ghc" ]; then
+            echo "GHC found: $(ghc --version)"
+          else
+            ghcup install ghc recommended
+          fi
+
+  - language: yaml
+    label: 'Parse GHCup list output — strip revision suffix'
+    code: |
+      - name: Get recommended GHC version
+        run: |
+          # GHCup 0.2.x: version may include -rX revision suffix
+          GHC_VER=$(ghcup list -t ghc --show-revisions=none -r \
+            | grep 'recommended' | awk '{print $2}')
+          echo "GHC version: $GHC_VER"
+          ghcup install ghc "$GHC_VER"
+prevention:
+  - 'Use haskell-actions/setup instead of calling ghcup directly — it handles ghcup API changes across versions.'
+  - 'Use `-e` or `-L` for file existence checks on `~/.ghcup/bin/` entries, never `-f`.'
+  - 'Pin to specific GHC/Cabal versions in haskell-actions/setup rather than resolving "recommended" at runtime.'
+  - 'When parsing `ghcup list` output, use `--show-revisions=none` to suppress the `-rX` suffix added in 0.2.x.'
+docs:
+  - url: 'https://github.com/haskell/ghcup-hs/releases/tag/v0.2.1.0'
+    label: 'GHCup 0.2.1.0 release notes (breaking changes section)'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'Ubuntu 24.04 runner image release 20260525.161.1 — GHCup 0.1.50.2 → 0.2.5.0'
+  - url: 'https://github.com/actions/runner-images/issues/14142'
+    label: 'runner-images #14142 — GHCup 0.2 version banner format change'
+  - url: 'https://github.com/haskell/haskell-actions/tree/main/setup'
+    label: 'haskell-actions/setup — official Haskell CI setup action'