fix(ci): clean up canonical retry reservations

[apurvvkumaria]

Summary

Closes an interrupted runner-loss retry reservation when GitHub exposes the reserved check through its canonical self URL. Before this change, the cleanup path accepted only a missing details URL and could leave the replacement check in progress after a lost create response.

Related Issue

Part of #7146. Parent epic: #7140.

Changes

• Accept the exact https://github.com/<repository>/runs/<replacement-check-id> self URL for the immediately succeeding reserved replacement.
• Retain the existing missing-URL compatibility path and the exact source identity, history position, status, title, and summary checks.
• Cover missing URLs, matching canonical self URLs, unexpected reservation ownership, and mismatched self-link check IDs.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This is an internal E2E retry-controller compatibility fix. The internal README already documents canonical GitHub check URLs and interrupted post-reservation cleanup.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Independent focused review confirmed the replacement match remains exact and fail-closed; no actionable findings.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Exact head 010d84cc0 changes only the internal PR E2E retry-cleanup controller and its focused tests. test/e2e/README.md already documents GitHub canonical /runs/<check-id> details URLs and that interrupted post-reservation cleanup closes the reserved replacement. No user-facing command, configuration, default, API, policy, or operator procedure changes.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — 159/159 focused PR-gate controller tests passed across six files; the exact cleanup suite passed 45/45.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable to this bounded two-file cleanup guard. CLI build/typecheck, test-size, title-style, source-shape, project-membership, secret scan, and the full diff-scoped hook suite passed.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved retry handling for pull request checks when a replacement check is in progress.
  • Correctly recognizes valid GitHub check URLs during retry recovery.
  • Better handles ambiguous or incomplete retry scenarios without incorrectly abandoning the check.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a9d9ee5e-5559-459d-903d-1e2e4f273f78

📥 Commits

Reviewing files that changed from the base of the PR and between 04e6dfa and 010d84c.

📒 Files selected for processing (2)

• test/pr-e2e-gate-runner-loss-retry.test.ts
• tools/e2e/pr-e2e-gate.mts

---

📝 Walkthrough

Walkthrough

The retry-loss handling now recognizes the current GitHub check URL as a canonical replacement. End-to-end tests add shared output expectations and parameterized coverage for self-URL and ambiguous replacement scenarios.

Changes

Retry replacement handling

Layer / File(s)	Summary
Canonical replacement detection and test coverage tools/e2e/pr-e2e-gate.mts, test/pr-e2e-gate-runner-loss-retry.test.ts	abandonRunnerLossRetrySource accepts the current check’s GitHub runs URL, while tests parameterize replacement URLs, reserved output, and ambiguity cases.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the CI retry reservation cleanup and the canonical self-URL behavior added in this change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/7146-canonical-retry-cleanup

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 3c4d325 in the codex/7146-canonical... branch remains at 96%, unchanged from commit a63ac38 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 3c4d325 in the codex/7146-canonical... branch remains at 80%, unchanged from commit 5faed2c in the main branch.

Show a code coverage summary of the most impacted files.

File	main 5faed2c	codex/7146-canonical... 3c4d325	+/-
src/lib/onboard...der-metadata.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated July 24, 2026 17:30 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

Since last review: 0 prior items resolved · 0 still apply · 1 new item found

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, credential-sanitization, security-posture

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Document the GitHub self-URL recovery exception

• Location: tools/e2e/pr-e2e-gate.mts:4480
• Category: docs
• Problem: The retry cleanup now accepts a reservation whose details URL is GitHub's self check URL. The code does not record the API behavior that creates this state, why the reservation creator cannot prevent it, or when this exception can be removed.
• Impact: A future change can remove or broaden this fail-closed exception without knowing the external contract it preserves, which can misclassify a noncanonical replacement as a canonical reservation.
• Recommendation: Add a concise code comment beside the self-URL condition. Name GitHub's check-run URL behavior, the lost-create recovery state, and the condition that permits removal.
• Verification: Read the reservation creation path and the GitHub Check Runs API evidence used to establish whether GitHub can replace an absent details URL with `https://github.com/<repository>/runs/<check-id>\`.
• Test coverage: The existing parameterized test covers the accepted self URL and a wrong self URL. Retain those cases and add a contract-focused test only if the documented upstream behavior has a distinct observable API response.
• Evidence: `tools/e2e/pr-e2e-gate.mts:4480-4484` adds the self-URL alternative without an explanatory comment. `test/pr-e2e-gate-runner-loss-retry.test.ts:1055-1060` calls this case "GitHub's self check URL" but does not record the API contract or removal boundary. The retry cleanup is a recovery path for a lost create response, so the accepted representation is an external-system assumption.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[prekshivyas]

Reviewed exact head 3c4d325d7 against base 5faed2cbc. The canonical reserved replacement remains fail-closed: it accepts only the immediately succeeding in-progress check with the exact GitHub self URL, canonical identity/output, and matching check ID; mismatched self URLs remain rejected. The focused 45/45 tests, all required CI checks, selected E2E jobs, DCO, commit verification, and security scans pass. No blocking correctness or security findings.