[BUG] Mutation gate fails pull requests: stale-head checkout and missing root vitest binary

[edelauna]

Problem (one or two sentences)

The mutation-diff job fails on any pull request whose head predates the mutation gate. The job dies on a missing script, not on surviving mutants.

Failing run: https://github.com/Zoo-Code-Org/Zoo-Code/actions/runs/33711419999/job/100511541034

Context (who is affected and when)

Every open pull request that branched off main before #1479 merged the gate. Each one fails Changed-code mutation testing until it rebases.

Root cause

1. PR [Chore] Require changed-code mutation tests before review #1479 merged .github/workflows/mutation-testing.yml onto main.
2. GitHub fires pull_request workflows from the merge ref. Main contains the workflow, so the gate triggers for old PR heads too.
3. The checkout step pins ref: ${{ github.event.pull_request.head.sha }}. The job checks out the PR head, not the merge result.
4. On an old head, package.json has no test:mutation-ci script and scripts/stryker-diff.mjs does not exist.
5. The job fails: ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command "test:mutation-ci" not found, exit 254.

The gate tests the bare PR head instead of the code that would land. A stale branch fails on a missing script before mutation testing even starts.

Suggested fix

Check out the merge ref instead of the head:

- name: Checkout pull request merge result
  if: github.event_name == 'pull_request'
  uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
  with:
      ref: refs/pull/${{ github.event.pull_request.number }}/merge
      fetch-depth: 0
      persist-credentials: false

Notes:

• With fetch-depth: 0 the merge commit carries both parents. --base and --head still resolve, and the diff still isolates the PR's own changed lines.
• The merge ref lives on the base repo, so the step must drop repository:. This also fixes fork PRs.
• A PR with conflicts against main has no merge ref. Checkout fails with a clear signal. That is correct, because the PR cannot merge anyway.

Rejected alternative: skip with exit 0 when the script is missing. That silently disables the gate for exactly the PRs most in need of it.

[edelauna]

Fork PR behavior with the merge-ref checkout

Where the merge ref lives:

• refs/pull/N/merge exists on the base repo. PR numbers are base-repo scoped, and GitHub creates the merge commit there for fork PRs too. This is how GitHub computes mergeability and decides to fire CI at all.
• The current workflow passes repository: ${{ github.event.pull_request.head.repo.full_name }}. That points at the fork, where refs/pull/N/merge does not exist. The fix must drop repository: so checkout defaults to github.repository (the base repo).
• Base-repo checkout from a fork-triggered pull_request run works with the read-only token. This workflow already tolerates that: permissions: contents: read, no secrets used.

What changes for fork PRs after the fix:

1. Workflow definition. Unchanged. GitHub already takes it from the base repo's merge ref for fork PRs, same as same-repo PRs.
2. Payload. Improved, same as same-repo PRs. Today a fork PR with a stale base fails on the missing script the same way as the linked run. After the fix it tests the merge result.
3. The diff. Still correct. With fetch-depth: 0 from the base repo, both pull_request.base.sha and pull_request.head.sha are ancestors of the merge commit. --base and --head resolve, and the diff still isolates the PR's own changes.
4. The separate "Fetch pull request base" step becomes redundant, because the base SHA is already in the merge commit's parent lineage. It can be deleted.

Known rough edge with merge-ref checkouts in general: immediately after a force-push, GitHub can fire the workflow a moment before the merge ref is recomputed. Checkout then fails with "ref not found". A job rerun resolves it. Rare and self-healing, and strictly better than the current behavior for the conflict case, where the merge ref never exists and no gate runs at all.

[edelauna]

Follow-up: second failure mode in the same gate

PR #1494 branched after the gate landed. The script exists and runs, but the job still fails in discoverRelatedTestFiles. This failure mode is independent of the checkout problem above.

Failing run: https://github.com/Zoo-Code-Org/Zoo-Code/actions/runs/33712025662/job/100513383670?pr=1494

Log line:

Mutation gate failed: extension related-test discovery failed:

The detail after the colon is empty.

Root cause

scripts/stryker-diff.mjs spawns vitest from a hardcoded repo root path:

spawnSync(path.join(repoRoot, "node_modules/.bin/vitest"), ["related", ...])

This repository is a pnpm workspace. vitest is not a root dependency, so the repo root has no node_modules/.bin/vitest. The binary exists only per package:

• src/node_modules/.bin/vitest
• webview-ui/node_modules/.bin/vitest

spawnSync cannot launch the missing binary. It returns status: null and null stdout and stderr. The handler checks only status !== 0 and prints stdout plus stderr. Both are null, so the message is empty. The result.error field holds ENOENT, but nothing reads it.

Blast radius

Only packages with discoverRelatedTests: true run this spawn: extension (src) and webview (webview-ui). Every PR with changed executable lines in those trees fails on a fresh CI install. The other four packages go straight to Stryker. The stryker binary itself is safe: @stryker-mutator/core is a root devDependency.

The failure is invisible on dev machines. An old install can leave a stale root bin behind. The unit tests never spawn vitest, so test:mutation-ci passes.

Suggested fix

1. Resolve the vitest binary per package. Try runRoot/node_modules/.bin/vitest, then packageRoot/node_modules/.bin/vitest, then the repo root.
2. Check result.error before the status check. Report the launch failure instead of an empty message.

The unit tests assert config flags only. They do not mock spawnSync or assert binary paths. The fix needs no test changes.

Both fixes are needed. The merge-ref checkout makes old heads run the current gate. This fix makes the current gate run at all.