ci: bind Unity editor gate provenance and retire superseded Unity runs

[Eli Pinkerton (wallstop)]

Summary

Binds licensed Unity work to an editor proved by a manual-only gate that runs before the repository checkout, and retires a superseded Unity run before it can reach the build lock.

Editor gate provenance (the original change, plus its fixes)

• Validate and bind the editor before the main repo checkout, so no later step can replace the validator's evidence or run against an unexpected install.
• Reject automatic editor fallback: -CiManagedOnly -RequireHealthyExisting, and a bind step that fails unless editorPath is the canonical RUNNER_TOOL_CACHE\u6-v3\<version>\Editor\Unity.exe.
• -DiagnosticsPath points at a RUNNER_TEMP directory, so ensure-editor.ps1 writes its summary outside the workspace, from its own finally block. The evidence therefore survives both a failed gate and the checkout that wipes the workspace, and the if: always() upload publishes the same file the bind step trusted.
• The upload names that directory directly rather than an env var written only on the success path.
• Applied across all five licensed jobs (unity-tests, unity-benchmarks, perf-benchmarks, release/unity-checks, release/unitypackage).

Superseded Unity runs (closes #311)

• A second push to a pull request queued a second full nine-leg matrix without retiring the first. cancel-in-progress: false is deliberate -- hard cancelling a run holding the organization build lock is what the four-layer license-return guarantee exists to prevent -- so the superseded run kept the concurrency group through every leg while the current head waited, and Unity CI Success was absent on the head that mattered.
• A new head-check job on ubuntu-latest compares the event head against the live pull-request head, before the lock is in reach, and publishes a superseded output that both licensed jobs gate on. A superseded run now costs one cheap job instead of nine self-hosted ones.
• Fails open: any event other than a pull request, and any lookup that returns no SHA, runs the full matrix.
• The per-leg Require current PR head before setup guard stays; it covers the push that lands after head-check has already passed.
• Unity CI Success reports the shape rather than going absent: it requires head-check to have succeeded and accepts skipped licensed jobs for a superseded head alongside the fork and Dependabot shapes.

Review feedback addressed

Finding	Resolution
Cursor Bugbot: empty validation upload path	The upload names ${{ runner.temp }}/dx-unity-editor-validation directly; if-no-files-found: warn keeps the previous behavior
Cursor Bugbot: gate failures drop upload evidence	ensure-editor.ps1 writes its summary to RUNNER_TEMP itself, from a finally block, so a failed gate and a provenance mismatch both upload
Prettier and yamllint red	The single-line ensure-editor.ps1 calls are wrapped again; -InstallRoot returns to one spelling, so the policy validator needs no second accepted form
Script tests red on validate:js-loc-budget	JS is net zero: five validationStep assertions folded into three, paying for the bind-step and upload-step contracts

copilot-pull-request-reviewer reports a reviewer quota limit, not a finding.

Where the contracts live

scripts/validate-unity-pr-policy.py owns the superseded gate, because its docstring is "trusted-PR Unity admission, staleness guards, and skip policy" and it already byte-pins the aggregate step's script and executes it against a truth table. Its truth table gains the superseded and failed-decision rows; a second table runs the head-freshness script itself against a stub gh for push, current head, superseded head, and failed lookup.

scripts/__tests__/ci-aggregate-workflow.test.js owns the per-job lifecycle order, which now includes the evidence upload.

Evidence

CI on 1d4563e9: 34 success, 4 skipped, 0 blocking failures. All nine Unity legs, Unity CI Success, and CI Success pass; the pull request reports mergeable_state: clean. The one red check, copilot-pull-request-reviewer, reports a reviewer quota limit rather than a finding, and is not a required status check. Cursor Bugbot on the final commit: "no new issues".

Unity head freshness runs in 5 seconds and reported superseded=false, so the new gate costs a superseded run one cheap job while the full nine-leg matrix still takes about 15 minutes end to end.

The evidence relocation is confirmed on a real runner: the upload step reports With the provided path, there will be 2 files uploaded from E:\actions-runner\_work\_temp/dx-unity-editor-validation -- the summary JSON plus the sibling .txt that Write-UnityProvisioningSummary writes next to it.

#311 observed live. The first push of this session created the exact situation the fix removes, before the fix existed. Run 30642224168 was superseded mid-flight and still scheduled five legs onto the self-hosted runner, each failing at step one on Require current PR head before setup -- five red legs and a red Unity CI Success on a stale SHA.

One leg needed a re-run, and not as a flake write-off. Unity 2021.3.45f1 playmode first failed on the shared build lock, not on tests: it acquired the lock, and 68 seconds later the release reported Lock is already free (acquired=true ... reservation=missing). The predecessor commit abaabb68 passed all nine legs with byte-identical lock code, and no other non-superseded run in the last eight has failed that step. Filed as #329 against the lock action with the full evidence, then the single job was re-run and passed.

Every guard was mutated and confirmed to fail:

Mutation	Caught by
upload path back to the env var	ci-aggregate-workflow.test.js
-InstallRoot back to the quoted form	ci-aggregate-workflow.test.js
shell: pwsh without -NoProfile -NonInteractive	ci-aggregate-workflow.test.js
export the editor path before preserving the evidence	ci-aggregate-workflow.test.js
case-sensitive canonical-path compare	ci-aggregate-workflow.test.js
evidence written back inside the workspace	ci-aggregate-workflow.test.js
bind reading an unpreserved copy	ci-aggregate-workflow.test.js
inverted superseded comparison	validate-unity-pr-policy.py
failed lookup stops failing open	validate-unity-pr-policy.py
superseded guard dropped from the licensed jobs	validate-unity-pr-policy.py
aggregate stops requiring the decision	validate-unity-pr-policy.py
decision moved onto a self-hosted runner	validate-unity-pr-policy.py
head-freshness querying a different endpoint	validate-unity-pr-policy.py
head-freshness dropping --jq .head.sha	validate-unity-pr-policy.py

Local: npm test 406/0, npm run validate:all pass, validate-js-loc-budget 17500/17500, actionlint, yamllint --strict, prettier, markdownlint and cspell clean.

No Unity MCP run: this diff touches no C#, so the local editor signal would prove nothing about it. The real signal is the nine-leg matrix on this pull request.

Docs

docs/runbooks/required-checks.md described a matrix-config job and an re-actors/alls-green aggregate for Unity CI Success. Neither exists, and validate-unity-pr-policy.py rejects the latter outright. That section now describes the three validated skip shapes and the gate as written.

Self-review, beyond what reviewers raised

• The five new validator checkouts had dropped the # v7 comment every other actions/checkout pin in the repository carries.
• Three workflows still told a reader that editor validation happens alongside credential validation and lock acquisition; the gate now runs before the repository checkout.
• A summary written by a failed gate can record no editorPath, and [IO.Path]::GetFullPath('') throws an ArgumentException rather than saying so. The binder reports (none recorded) through its own mismatch message.
• On Windows the head-freshness truth table returned a hardcoded answer instead of running the script, so its four cases asserted the helper's own logic. The table is skipped there now, matching how the aggregate result-shape table already handles the same constraint. The stub gh also accepted any invocation; it now answers only the live-head lookup.

Issues opened while working on this

• ci: a Unity leg that aborts before lock acquisition still fails Require confirmed Unity cleanup #327 -- a Unity leg that aborts before lock acquisition also fails Require confirmed Unity cleanup, because the classify step skips and the gate reads an empty classification.
• ci: the stuck-job watchdog reports success while it cannot read runner inventory #328 -- the stuck-job watchdog reports success while it cannot read runner inventory, which is why an eight-hour-stuck Performance Numbers queue on master went unreported.
• ci: a build-lock holder's reservation disappears mid-run, so the cleanup gate fails a clean leg #329 -- the build-lock reservation race above.

Follow-up to #322, which squash-merged before the provenance binder commit was ready.

Closes #311.

[Eli Pinkerton (wallstop)]

Cursor (@cursor) review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Eli Pinkerton (wallstop)]

Cursor (@cursor) review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Eli Pinkerton (wallstop)]

Cursor (@cursor) review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit abaabb6. Configure here.}

[Eli Pinkerton (wallstop)]

Cursor (@cursor) review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1d4563e. Configure here.}