@htekdev/actions-debugger 1.0.118 → 1.0.119

package/errors/caching-artifacts/caching-artifacts-070.yml

@@ -0,0 +1,94 @@
+id: caching-artifacts-070
+title: "setup-python Post step fails — pip cache directory doesn't exist on disk"
+category: caching-artifacts
+severity: error
+tags:
+  - setup-python
+  - pip
+  - cache
+  - post-step
+  - cache-miss
+  - no-dependencies
+  - python-version-bump
+patterns:
+  - regex: 'Cache folder path is retrieved for pip but doesn.t exist on disk'
+    flags: 'i'
+  - regex: 'likely indicates that there are no dependencies to cache'
+    flags: 'i'
+  - regex: 'Post Setup Python.*fail|Post.*setup-python.*error'
+    flags: 'i'
+error_messages:
+  - "Cache folder path is retrieved for pip but doesn't exist on disk: /home/runner/.cache/pip. This likely indicates that there are no dependencies to cache. Consider removing the cache step if it is not needed."
+root_cause: |
+  When actions/setup-python is configured with cache: 'pip', the action records the expected
+  pip cache directory path at setup time (/home/runner/.cache/pip on Linux, equivalent on
+  macOS/Windows). The Post Setup Python step runs at job end and attempts to save the cache
+  to that path. If the directory does not exist on disk at save time, the Post step fails
+  with this error.
+
+  Two common causes:
+
+  1. No pip install ran in the job: The job uses cache: 'pip' but only runs linting or other
+     pre-installed tools without installing any Python packages. Pip never creates its cache
+     directory, so there is nothing to save. The job's actual steps appear green while the
+     Post step fails and turns the overall workflow run red.
+
+  2. Python version bump causes cache key miss: When the Python patch version changes (e.g.,
+     from 3.13.5 to 3.13.6), the setup-python cache key changes and the first run after the
+     bump experiences a full cache miss. If pip install runs but writes packages to a virtual
+     environment rather than the global pip cache (/home/runner/.cache/pip), the expected
+     directory remains empty and the Post step fails. Subsequent runs after the new cache is
+     warmed succeed.
+
+  The failure is deceptive because it surfaces in the Post Setup Python cleanup step — well
+  after the test or build steps have already succeeded — making it easy to overlook the root
+  cause.
+fix: |
+  - Remove cache: 'pip' from any setup-python step in jobs that do not call pip install.
+    Linting-only jobs, type-check-only jobs, and jobs that rely entirely on pre-installed
+    system Python do not benefit from pip caching.
+  - If pip install does run, ensure it runs against the global pip (not a virtualenv that
+    bypasses /home/runner/.cache/pip) so the post step can find and save the cache.
+  - Upgrade to actions/setup-python@v5 or later: newer versions emit a warning annotation
+    instead of failing the step when the cache directory is missing.
+  - After a Python version bump, the first run is expected to cache-miss; monitor for Post
+    step failures on that first run and confirm subsequent runs succeed.
+fix_code:
+  - language: yaml
+    label: 'Fix: Remove cache when no pip install runs'
+    code: |
+      # WRONG: cache: pip set but job only lints — no pip install → Post step fails
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          cache: 'pip'            # ← REMOVE when no pip install follows
+      - name: Lint
+        run: flake8 .             # no pip install; /home/runner/.cache/pip never created
+
+      # CORRECT: omit cache when the job does not install packages
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          # no cache key — Post step skips cache save attempt entirely
+      - name: Lint
+        run: flake8 .
+  - language: yaml
+    label: 'Fix: Upgrade to setup-python@v5 for graceful handling'
+    code: |
+      # CORRECT: v5+ emits a warning annotation instead of failing when cache path missing
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+prevention:
+  - 'Only set cache: pip on jobs that actually run pip install — linting-only jobs should omit it.'
+  - 'Use actions/setup-python@v5 or later; it handles missing cache directories with a warning instead of a failure.'
+  - 'After bumping the Python patch version in python-version:, expect one cache-miss run and watch for Post step failures on that run only.'
+  - 'When using virtual environments (venv/pipenv/poetry), ensure pip still writes to the global cache or configure cache-dependency-path appropriately.'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1169'
+    label: 'setup-python#1169: Cache folder path doesn''t exist on disk (Aug 2025)'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python: Caching packages documentation'

package/errors/concurrency-timing/concurrency-timing-056.yml

@@ -0,0 +1,127 @@
+id: concurrency-timing-056
+title: 'Workflow-level and job-level concurrency share same group key — deadlock cancellation fires immediately'
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - deadlock
+  - workflow-level
+  - job-level
+  - reusable-workflow
+  - workflow-call
+  - github-workflow-context
+patterns:
+  - regex: 'Canceling since a deadlock for concurrency group .* was detected between'
+    flags: 'i'
+  - regex: 'deadlock.*concurrency group|concurrency group.*deadlock'
+    flags: 'i'
+error_messages:
+  - "Canceling since a deadlock for concurrency group 'ci-refs/heads/main' was detected between 'top level workflow' and 'deploy'"
+  - "Canceling since a deadlock for concurrency group 'release-refs/heads/main' was detected between 'top level workflow' and 'api'"
+root_cause: |
+  GitHub Actions fires a deadlock error and immediately cancels the offending job when the
+  same concurrency group name is held simultaneously by two levels within a single workflow
+  execution. Two distinct scenarios trigger this:
+
+  Scenario 1 — Same-workflow self-deadlock: A workflow file defines concurrency: at the
+  workflow level AND one of its jobs also defines jobs.<id>.concurrency: using an expression
+  that evaluates to the same string:
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}   # workflow-level slot
+
+    jobs:
+      deploy:
+        concurrency:
+          group: ${{ github.workflow }}-${{ github.ref }}  # same string → deadlock
+        runs-on: ubuntu-latest
+
+  Scenario 2 — Reusable callee inherits caller context: A calling workflow has workflow-level
+  concurrency using ${{ github.workflow }}-${{ github.ref }}. The called reusable workflow
+  also defines workflow-level concurrency with the same expression. Because github.workflow
+  inside a reusable workflow inherits the CALLER's workflow name (not the callee's filename),
+  both evaluate to the identical group key and GitHub detects a deadlock.
+
+  github.workflow_ref also inherits from the top-level caller and does NOT produce a unique
+  value in the callee context; it cannot be used to distinguish caller from callee.
+fix: |
+  Scenario 1 — Remove the duplicate concurrency block. Keep either the workflow-level OR
+  the job-level declaration, not both with the same key. If per-job isolation is needed,
+  append ${{ github.job }} to the job-level group name:
+
+    jobs:
+      deploy:
+        concurrency:
+          group: ${{ github.workflow }}-${{ github.ref }}-${{ github.job }}
+
+  Scenario 2 — Remove the concurrency: block entirely from the reusable workflow. The
+  caller's workflow-level concurrency already governs the entire execution. If the callee
+  needs standalone concurrency when triggered via workflow_dispatch, use a hardcoded unique
+  prefix instead of ${{ github.workflow }}:
+
+    concurrency:
+      group: deploy-${{ github.ref }}   # hardcoded prefix avoids collision with any caller
+      cancel-in-progress: true
+fix_code:
+  - language: yaml
+    label: 'Scenario 1 fix: remove duplicate job-level concurrency'
+    code: |
+      # WRONG — identical group at workflow level and job level → deadlock
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}  # ← DELETE THIS
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo deploying
+
+      # CORRECT — concurrency only at workflow level
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo deploying
+  - language: yaml
+    label: 'Scenario 2 fix: remove concurrency from reusable workflow'
+    code: |
+      # deploy.yml (reusable) — WRONG: workflow-level concurrency collides with caller
+      # because github.workflow returns the CALLER's name in reusable context
+      on:
+        workflow_call:
+        workflow_dispatch:
+      # concurrency:               ← DELETE this entire block from the reusable workflow
+      #   group: ${{ github.workflow }}-${{ github.ref }}
+      #   cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo deploying
+
+      # If standalone concurrency is needed for workflow_dispatch calls, use hardcoded prefix:
+      # concurrency:
+      #   group: deploy-${{ github.ref }}   # hardcoded "deploy-" avoids collision
+      #   cancel-in-progress: true
+prevention:
+  - 'Before adding concurrency: to a reusable workflow, check if it will be called via workflow_call — if so, remove it or use a hardcoded prefix.'
+  - 'Never use the same concurrency group expression at both the workflow level and job level in the same file.'
+  - 'Note that ${{ github.workflow }} and ${{ github.workflow_ref }} both return the top-level caller''s values inside a reusable workflow; neither provides the callee''s filename.'
+  - 'Use actionlint to statically detect identical concurrency groups — issue actionlint#538 tracks adding this check.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Controlling the concurrency of workflows and jobs'
+  - url: 'https://stackoverflow.com/questions/78101326/github-actions-concurrency-deadlock'
+    label: 'SO: GitHub Actions concurrency deadlock (Score 6, 1.7K views)'
+  - url: 'https://stackoverflow.com/questions/79511940/using-workflow-filename-in-concurrency-group-for-workflows-started-by-workflow-c'
+    label: 'SO: Using workflow filename in concurrency group for workflow_call (Score 3)'
+  - url: 'https://github.com/github/vscode-github-actions/issues/135'
+    label: 'vscode-github-actions#135: Identical concurrency groups cause silent never-run (14 reactions)'

package/errors/concurrency-timing/concurrency-timing-057.yml

@@ -0,0 +1,115 @@
+id: concurrency-timing-057
+title: "Fork PRs with Identical Branch Names Share Concurrency Group and Cancel Each Other"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - fork
+  - pull_request
+  - head_ref
+  - cancel-in-progress
+  - silent-cancel
+patterns:
+  - regex: 'group.*github\.head_ref'
+    flags: 'i'
+  - regex: 'This run was cancelled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled."
+  - "Run was cancelled."
+root_cause: |
+  When a workflow uses 'github.head_ref' as the sole identifier in a
+  concurrency group key (a common pattern to cancel stale runs on the same
+  branch), all pull requests that share a branch name across different forks
+  map to the SAME concurrency group. With 'cancel-in-progress: true', the
+  latest queued run cancels all earlier runs in that group — including runs
+  from completely unrelated PRs in OTHER contributor forks.
+
+  Example scenario:
+  - Fork A (alice/myrepo) opens PR from branch 'fix/auth-bug'.
+  - Fork B (bob/myrepo) opens a PR from a branch also named 'fix/auth-bug'.
+  - Both PRs target the same upstream repo (org/myrepo).
+  - Concurrency group: 'ci-fix/auth-bug' (from github.head_ref).
+  - When Fork B's PR triggers a run, it cancels Fork A's in-progress run.
+
+  The cancellation appears as "This run was cancelled" with no explanation
+  that a different fork's PR caused it. Maintainers and contributors see
+  flaky-looking CI with no obvious cause.
+
+  This is especially common in:
+  - Large open-source projects where many contributors use the same
+    conventional branch names (fix/typo, docs/readme, feature/x).
+  - Dependabot/Renovate PRs across forks — all use the same structured
+    branch name pattern (dependabot/npm_and_yarn/lodash-4.0.0).
+fix: |
+  Include 'github.event.pull_request.number' in the concurrency group key.
+  PR numbers are unique per repository, so two PRs from different forks
+  always have different numbers even if their branch names collide.
+
+  Alternative: use 'github.run_id' for maximum uniqueness (no cancellation
+  across runs at all), but this defeats the purpose of cancel-in-progress
+  for the same PR.
+
+  The recommended pattern from GitHub documentation:
+  group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+
+  The '|| github.ref' fallback handles non-PR events (push, schedule)
+  where 'github.event.pull_request.number' is empty.
+fix_code:
+  - language: yaml
+    label: "Broken — github.head_ref alone causes cross-fork cancellation"
+    code: |
+      concurrency:
+        group: ci-${{ github.head_ref }}   # ❌ Collides across forks with same branch name
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Fixed — include PR number to ensure per-PR uniqueness"
+    code: |
+      concurrency:
+        # PR number is unique per repo — different forks never collide
+        group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Alternative — include repo owner to scope per fork"
+    code: |
+      concurrency:
+        # Include head repo full_name to distinguish forks explicitly
+        group: >-
+          ${{ github.workflow }}-
+          ${{ github.event.pull_request.head.repo.full_name || github.repository }}-
+          ${{ github.event.pull_request.number || github.ref }}
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Recommended pattern from GitHub docs — workflow + PR number or ref"
+    code: |
+      name: CI
+      on:
+        pull_request:
+        push:
+          branches: [main]
+
+      concurrency:
+        group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./run-tests.sh
+
+prevention:
+  - "Never use github.head_ref alone as a concurrency group key for pull_request workflows."
+  - "Always pair github.head_ref with github.event.pull_request.number to scope to the specific PR."
+  - "Use the GitHub-recommended pattern: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'."
+  - "Test concurrency behavior by opening two PRs from different forks with the same branch name before merging concurrency configuration."
+  - "On public repos with many external contributors, audit all concurrency group keys for cross-fork collision risk."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "GitHub Docs — Using concurrency (recommended group key pattern)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Docs — Workflow syntax: concurrency"

package/errors/known-unsolved/known-unsolved-067.yml

@@ -0,0 +1,117 @@
+id: known-unsolved-067
+title: 'ubuntu-24.04 Runner df Reports 12-15 GB Ghost Disk Usage — Invisible to du/lsof'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - ubuntu-24
+  - disk-space
+  - enospc
+  - runner-agent
+  - diagnostics
+  - phantom-disk
+  - playwright
+  - hosted-runner
+patterns:
+  - regex: 'ENOSPC:\s*no space left on device'
+    flags: 'i'
+  - regex: 'df\s+/\s+.*\d{4,5}M\s+.*\d+%'
+    flags: 'i'
+  - regex: 'No space left on device'
+    flags: 'i'
+error_messages:
+  - 'ENOSPC: no space left on device, write'
+  - 'No space left on device'
+  - 'df: cannot read table of mounted file systems: No space left on device'
+root_cause: |
+  On ubuntu-24.04 hosted runners, `df /` can report 12–15 GB of disk used
+  during heavy test runs (particularly those spawning many short-lived child
+  processes or producing large volumes of stdout, such as Playwright WebKit /
+  WPE test suites). This usage CANNOT be accounted for by:
+
+  - `du -shx /` (sum of all directories does not grow)
+  - `lsof +L1` (deleted-but-open files show only kernel /memfd:* entries)
+  - /proc/<PID>/maps (only kernel memfd entries)
+  - /proc/<PID>/io write_bytes (single-digit MB cumulative)
+
+  The ghost usage RECOVERS fully ~40 seconds after the job's main process
+  exits — gradually, over ~10 seconds — even though all child processes are
+  already reaped at recovery start. This rules out lingering processes holding
+  mmap'd files.
+
+  Best-guess root cause (unconfirmed by GitHub team as of June 2026): the
+  runner agent's diagnostic/log buffers are flushed periodically on the host
+  and the flushed bytes are counted in the container's `df` view but are not
+  visible from inside the runner's PID namespace. The ~40-second recovery delay
+  is consistent with a periodic flush cycle on the agent side.
+
+  This issue is non-deterministic and tied to the state of the underlying host
+  VM. The same workload run locally on ubuntu-24.04 does not reproduce.
+
+  Affected environments:
+  - Native `ubuntu-24.04` hosted runner
+  - Containers running on the `ubuntu-24.04` runner (which share the host's /)
+  - Does NOT reproduce on self-hosted ubuntu-24.04 VM locally
+
+  Tracked upstream: https://github.com/actions/runner/issues/4448 (open, May 2026)
+fix: |
+  There is NO user-side fix for the phantom disk usage itself — this is
+  infrastructure-level behaviour outside the workflow's control.
+
+  Mitigations to prevent ENOSPC failures:
+
+  1. Use a larger runner (8-core or 16-core) — larger runner classes have
+     more disk allocated on different host hardware.
+
+  2. Reduce stdout volume by adding --quiet / --silent flags to test runners
+     and package managers (npm ci --quiet, pytest -q, etc.).
+
+  3. Pre-clean the runner's docker layer cache and tool downloads that are
+     not needed:
+       - name: Free disk space
+         run: |
+           sudo rm -rf /usr/share/dotnet
+           sudo rm -rf /opt/ghc
+           sudo rm -rf /usr/local/lib/android
+           docker system prune -af
+
+  4. Split the job into smaller parallel matrix jobs to reduce per-job output.
+
+  5. Monitor disk in a background step to detect the ghost spike early and
+     correlate it with failures.
+fix_code:
+  - language: yaml
+    label: 'Pre-clean unused runner tools to reclaim disk headroom'
+    code: |
+      steps:
+        - name: Free runner disk space
+          run: |
+            sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android
+            sudo apt-get clean
+            docker system prune -af --volumes || true
+            df -h /   # confirm headroom before heavy tests
+
+        - name: Run Playwright tests
+          run: npx playwright test
+  - language: yaml
+    label: 'Use a larger runner with more disk allocation'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest-8-cores   # or ubuntu-24.04-x64-8-cores
+          steps:
+            - run: npx playwright test
+prevention:
+  - 'Add `df -h /` before and after heavy test steps to measure actual disk
+    consumption and detect when the ghost spike occurs.'
+  - 'Reduce test output verbosity — the agent diagnostic buffer hypothesis
+    correlates large stdout volumes with larger phantom disk readings.'
+  - 'For Playwright/WebKit CI that regularly sees ENOSPC: switch to
+    `ubuntu-24.04` larger runners or use `--reporter=dot` to minimise output.'
+  - 'Do not rely on `du -shx /` for disk capacity planning on hosted runners —
+    `df /` may show significantly more usage than du can account for during
+    heavy-output jobs.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4448'
+    label: 'runner #4448 — df reports 12-15 GB ghost disk usage on ubuntu-24.04 runner (open, May 2026)'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources'
+    label: 'GitHub Docs — Hosted runner hardware resources (disk sizes per runner class)'

package/errors/known-unsolved/known-unsolved-068.yml

@@ -0,0 +1,124 @@
+id: known-unsolved-068
+title: "Step outcome cannot distinguish timeout from failure — both report as 'failure' in steps context"
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout-minutes
+  - outcome
+  - conclusion
+  - continue-on-error
+  - steps-context
+  - retry
+  - known-limitation
+  - no-fix
+patterns:
+  - regex: 'steps\.\w+\.outcome\s*==\s*.failure.'
+    flags: 'i'
+  - regex: 'timeout-minutes.*continue-on-error|continue-on-error.*timeout-minutes'
+    flags: 'im'
+  - regex: 'The process.*timed out after \d+ minutes'
+    flags: 'i'
+error_messages:
+  - "Error: The process '/usr/bin/bash' failed with exit code 1"
+  - 'Error: Process completed with exit code 1'
+root_cause: |
+  GitHub Actions exposes two result fields for completed steps in the steps context:
+
+  - steps.<id>.outcome: the raw result before continue-on-error is applied.
+    Possible values: success, failure, cancelled, skipped.
+  - steps.<id>.conclusion: the final result after continue-on-error is applied.
+    When continue-on-error: true is set on a failed step, conclusion becomes 'success'
+    even if outcome is 'failure'.
+
+  Neither field distinguishes between a step that failed because the process exited with a
+  non-zero code and a step that failed because it hit its timeout-minutes limit. Both
+  scenarios set outcome to 'failure'. There is no 'timed_out' value, no
+  steps.<id>.timed_out boolean, and no built-in expression function to query the reason
+  for failure.
+
+  This means workflows cannot natively:
+  - Retry only on timeout while failing fast on real errors
+  - Alert with different severity for timeouts vs application failures
+  - Auto-escalate timeout-minutes only when a timeout (not a logic error) occurred
+
+  The limitation has been a known open request in the GitHub Actions community since at
+  least 2022 with no current implementation timeline from GitHub.
+fix: |
+  No native fix exists within GitHub Actions expressions. Two manual workarounds are
+  available in bash-based steps:
+
+  1. Record start time and compute elapsed duration at the next step to infer timeout:
+     Compare elapsed seconds against the timeout-minutes threshold. A step that used
+     approximately 100% of its time budget likely timed out.
+
+  2. Write a sentinel file just before the critical work; check for its absence afterward.
+     A timed-out step never reaches the sentinel-write line after the long-running command,
+     while a normally-failing step (which exits immediately on error) may or may not.
+
+  Neither workaround is exact — both have race conditions and edge cases. The most
+  reliable approach is to implement timeout detection inside the script itself using
+  shell signals or test-framework timeout flags.
+fix_code:
+  - language: yaml
+    label: 'Workaround 1: Infer timeout via elapsed time'
+    code: |
+      - name: Start timer
+        id: timer
+        run: echo "start=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Run slow tests
+        id: tests
+        timeout-minutes: 10
+        continue-on-error: true
+        run: npm test
+
+      - name: Classify failure type
+        if: steps.tests.outcome == 'failure'
+        env:
+          START: ${{ steps.timer.outputs.start }}
+        run: |
+          elapsed=$(( $(date +%s) - START ))
+          timeout_secs=600   # 10 minutes in seconds
+          threshold=$(( timeout_secs - 30 ))  # within 30s of limit → likely timeout
+          if [ "$elapsed" -ge "$threshold" ]; then
+            echo "::warning::Step likely timed out (elapsed ${elapsed}s, limit ${timeout_secs}s)"
+            # Handle timeout-specific logic here (e.g., don't fail, just warn)
+          else
+            echo "::error::Step failed (exit code, not timeout — elapsed ${elapsed}s)"
+            exit 1
+          fi
+  - language: yaml
+    label: 'Workaround 2: Sentinel file to detect timeout vs normal failure'
+    code: |
+      - name: Run tests with sentinel
+        id: tests
+        timeout-minutes: 10
+        continue-on-error: true
+        run: |
+          # The long-running command:
+          npm test
+          # Only reached on clean exit (not timeout, not error):
+          touch /tmp/test-completed
+
+      - name: Check failure reason
+        if: steps.tests.outcome == 'failure'
+        run: |
+          if [ ! -f /tmp/test-completed ]; then
+            echo "Step timed out or failed before completing"
+            # Inspect logs for timeout keyword:
+            # If the runner log shows "The process timed out after N minutes" → it was timeout
+          else
+            echo "Step completed but exited non-zero — application failure"
+            exit 1
+          fi
+prevention:
+  - 'Log test durations inside the script itself; test framework flags like --testTimeout (Jest) or --timeout (Mocha) provide per-test granularity inside logs.'
+  - 'Use separate jobs for steps with different timeout characteristics — a dedicated integration-test job with a high timeout-minutes and a unit-test job with a low one makes failures easier to categorize.'
+  - 'If the step runs a single long command, wrap it in a shell timeout with a slightly shorter duration than timeout-minutes; the shell timeout exit code (124) is detectable inside the same step.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context'
+    label: 'GitHub Docs: steps context — outcome and conclusion fields'
+  - url: 'https://stackoverflow.com/questions/78233438/github-action-cannot-get-timeout-status-from-previous-step'
+    label: 'SO: Cannot get timeout status from previous step (Mar 2024)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs: Status check functions (failure, success, cancelled, always)'