fix(e2e): paginate stale dispatch receipt rechecks

[apurvvkumaria]

Summary

Follow up on #7594 so an old dispatch-not-observed receipt can be rechecked after more than one page of matching workflow runs. The recheck now reads a complete, bounded inventory without hiding late children or permitting a duplicate dispatch.

Related Issue

Follow-up to #7594 for #7593.
Part of #7140.

Changes

• Paginate stale-receipt workflow inventories through GitHub's documented 1,000-result filtered-search limit under one shared timeout.
• Require a stable total count, complete intermediate pages, exact final count, and globally unique run IDs before replacement can proceed.
• Preserve fail-closed behavior for changing, duplicate, short, oversized, timed-out, or otherwise incomplete inventories.
• Share the request-ID validator and reconciliation-window limit between receipt production and validation.
• Centralize the exact pre-dispatch titles consumed by the producer and fail-closed validator.

The direct time-window cap suggested during review was not used because it could hide a genuinely late child. Tests cover a clean 101-run inventory, a correlated child appearing only on page two, and every incomplete-inventory rejection boundary.

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 control-plane reliability follow-up; the operational guidance added by fix(e2e): reconcile uncertain workflow dispatches #7594 remains accurate.
• 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 Codex security and code reviews passed at 0693c168d; pagination remains bounded, complete, and fail-closed before any replacement dispatch.
• 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: fix(e2e): reconcile uncertain workflow dispatches #7594's test/e2e/README.md and .agents/skills/nemoclaw-maintainer-day/MERGE-GATE.md guidance remains accurate; no user-facing docs/ behavior changes.
• Agent: Codex Desktop

DGX Station Hardware Evidence

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

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 — npx vitest run --project integration test/github-api.test.ts test/pr-e2e*.test.ts: 19 files, 311 tests passed
• Applicable broad gate passed — CLI type-check and npx prek run --from-ref origin/main --to-ref HEAD 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 dispatch reconciliation when workflow runs appear late or across multiple inventory pages.
  • Added safeguards for incomplete, duplicated, inconsistent, or oversized workflow-run listings.
  • Improved handling of stale and zero-match dispatch receipts, including replacement checks.
  • Standardized validation of GitHub request identifiers.
  • Improved consistency of PR gate status titles during evaluation, authorization, and retry flows.

• Tests

  • Expanded end-to-end coverage for paginated inventory and delayed workflow-run scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

Dispatch reconciliation now supports paginated workflow-run inventory validation and expanded stale-receipt tests. GitHub request ID validation and reconciliation limits are shared across modules, while PR-gate expected titles are centralized into constants and helpers.

Changes

Dispatch reconciliation

Layer / File(s)	Summary
Receipt validation and reconciliation limits tools/advisors/github.mts, tools/e2e/pr-e2e-retry-receipt.mts, tools/e2e/pr-e2e-dispatch-reconciliation.mts	GitHub request ID validation is centralized, the reconciliation window cap is exported, and receipt validation uses the shared type guard.
Paginated workflow inventory rechecks tools/e2e/pr-e2e-dispatch-reconciliation.mts	Workflow-run inventory reads aggregate validated pages, reject unstable or duplicate listings, enforce limits, and support stale-dispatch replacement checks.
Reconciliation scenario coverage test/pr-e2e-dispatch-reconciliation.test.ts	Tests cover old zero-match receipts, pagination, late correlations, inconsistent listings, duplicate runs, and filtered-result caps.

PR-gate title consistency

Layer / File(s)	Summary
Expected gate title construction tools/e2e/pr-e2e-gate.mts	Pre-dispatch validation, runner-loss retries, and authorized execution use centralized expected-title constants and a title-construction helper.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant assertDispatchStillNotObserved
  participant readPaginatedInventory
  participant GitHubWorkflowRunsAPI
  assertDispatchStillNotObserved->>readPaginatedInventory: recheck stale receipt
  readPaginatedInventory->>GitHubWorkflowRunsAPI: request workflow-run inventory page
  GitHubWorkflowRunsAPI-->>readPaginatedInventory: return paginated workflow runs
  readPaginatedInventory-->>assertDispatchStillNotObserved: return validated inventory

Loading

Possibly related issues

• ci(e2e): reconcile ambiguous workflow-dispatch failures without duplicate runs #7593 — Covers dispatch-failure reconciliation with paginated inventory checks and fail-closed stale-correlation handling.

Possibly related PRs

• NVIDIA/NemoClaw#7342 — Modifies the PR-gate authorization title handling path.
• NVIDIA/NemoClaw#7594 — Provides closely related dispatch reconciliation implementation and test changes.

Suggested labels: area: ci, area: e2e

Suggested reviewers: cv, prekshivyas

🚥 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 clearly summarizes the main change: paginating stale dispatch receipt rechecks.
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/7593-stale-receipt-pagination

---

_{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 0693c16 in the codex/7593-stale-rec... branch remains at 96%, unchanged from commit f7d2531 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 0693c16 in the codex/7593-stale-rec... branch remains at 80%, unchanged from commit f7d2531 in the main branch.

Show a code coverage summary of the most impacted files.

File	main f7d2531	codex/7593-stale-rec... 0693c16	+/-
src/lib/onboard...box-prebuild.ts	92%	73%	-19%
src/lib/actions...ocker-health.ts	82%	65%	-17%
src/lib/actions...confirmation.ts	79%	69%	-10%
src/lib/onboard...box-gpu-mode.ts	97%	92%	-5%
src/lib/actions...light-guards.ts	90%	86%	-4%
src/lib/onboard/preflight.ts	80%	80%	0%
src/lib/actions...eway-restart.ts	94%	95%	+1%
src/lib/onboard...host-anchors.ts	90%	94%	+4%
src/lib/shields/index.ts	67%	72%	+5%
src/lib/onboard/docker-cdi.ts	70%	80%	+10%

---

_{Updated July 26, 2026 20:51 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

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

E2E guidance

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

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

Workflow run details

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

[coderabbitai]

🧹 Nitpick comments (1)

test/pr-e2e-dispatch-reconciliation.test.ts (1)

415-486: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add a success test at the pagination cap boundary.

Coverage proves the cap rejects total_count = 1_001 (one over the limit) but nothing proves a total_count exactly at MAX_WORKFLOW_RUNS * MAX_WORKFLOW_RUN_PAGES (10 full pages) still succeeds. That's the case most exposed to an off-by-one regression in the loop's page <= MAX_WORKFLOW_RUN_PAGES bound.

✅ Suggested boundary test

it("succeeds when a stale receipt inventory exactly fills the page cap", async () => {
  const runs = Array.from({ length: 1_000 }, (_value, index) => unrelatedWorkflowRun(index + 100));
  const api = paginatedInventoryApi(runs);

  await expect(
    assertDispatchStillNotObserved(oldReceiptOptions(), {
      api,
      now: () => SENT_AT_MS + WINDOW_MS + 2_000,
      clockSkewMs: 10,
    }),
  ).resolves.toBeUndefined();
  expect(api).toHaveBeenCalledTimes(10);
});

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/pr-e2e-dispatch-reconciliation.test.ts` around lines 415 - 486, Add a
success test alongside the existing pagination tests covering exactly 1,000
inventory runs, representing MAX_WORKFLOW_RUNS * MAX_WORKFLOW_PAGES. Use
paginatedInventoryApi with assertDispatchStillNotObserved and verify it resolves
successfully after exactly 10 API calls, preserving coverage of the inclusive
pagination cap boundary.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/pr-e2e-dispatch-reconciliation.test.ts`:
- Around line 415-486: Add a success test alongside the existing pagination
tests covering exactly 1,000 inventory runs, representing MAX_WORKFLOW_RUNS *
MAX_WORKFLOW_PAGES. Use paginatedInventoryApi with
assertDispatchStillNotObserved and verify it resolves successfully after exactly
10 API calls, preserving coverage of the inclusive pagination cap boundary.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: df6687e0-2f9b-46ac-b34e-e329f88f6af5

📥 Commits

Reviewing files that changed from the base of the PR and between f7d2531 and 0693c16.

📒 Files selected for processing (5)

• test/pr-e2e-dispatch-reconciliation.test.ts
• tools/advisors/github.mts
• tools/e2e/pr-e2e-dispatch-reconciliation.mts
• tools/e2e/pr-e2e-gate.mts
• tools/e2e/pr-e2e-retry-receipt.mts