refactor(ci): bootstrap maintainer approval helper

[cv]

Summary

Add the trusted, directly tested approval helper required before PR #8168 can remove its large inline program from the write-capable workflow. This first stage is dormant: the current workflow does not load the helper, so repository behavior does not change.

Related Issue

Prerequisite for #8168. Related to #7744.

Changes

• Move PR fix(ci): retry transient maintainer workflow approvals #8168's bounded retry, request timeout, exact-run reconciliation, and mutable-authority validation behavior into tools/ci/approve-maintainer-pr-workflow-runs.mts.
• Add 28 direct behavioral tests for transient and terminal API errors, hung requests, script-budget exhaustion, exact PR and run identity, permission changes, head movement, external repositories, and ambiguous approval responses.
• Preserve Aaron Erickson's transferred contribution with a Co-authored-by trailer using the source commit identity.
• Leave the consumer workflow unchanged until this helper exists on a trusted main revision.

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 adds a dormant internal CI helper and direct tests. No workflow consumes it, and no public or contributor-facing behavior changes.
• 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: Pi completed the nine-category review at 0d25e53b2 with no findings. The helper validates exact PR, repository, author permission, head SHA, workflow-run identity, pagination, retry, timeout, and reconciliation state. It has no workflow consumer, permissions, checkout, secret access, dependency, or network path beyond the injected GitHub API client. Direct adversarial tests cover each fail-closed boundary.
• 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: Independent Pi CLI review confirmed that only the direct test imports the dormant helper. The existing workflow is unchanged, so no API, CLI, configuration, UI, workflow, supported behavior, or agent variant changes.
• Agent: Pi CLI

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 validate:pr passed after refreshing origin/main 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/maintainer-pr-workflow-approval-helper.test.ts passed 28 tests after the current-main refresh. npm run typecheck:cli, Biome format/lint, repository checks, diff checks, and NUL-byte checks passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• New Features

  • Added automated approval handling for eligible pull-request workflow runs, with validation of commit, repository, author, and permissions.
  • Added safeguards that stop approvals when pull-request details or authorization change.

• Reliability Improvements

  • Added bounded polling, timeouts, transient retries, and final status verification for more dependable workflow approvals.
  • Added comprehensive coverage for approval, timeout, retry, and invalid-response scenarios.

[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: bff12b53-d4b3-4e99-84cf-24cd3745df9d

📥 Commits

Reviewing files that changed from the base of the PR and between b148bc1 and 0d25e53.

📒 Files selected for processing (2)

• test/maintainer-pr-workflow-approval-helper.test.ts
• tools/ci/approve-maintainer-pr-workflow-runs.mts

---

📝 Walkthrough

Walkthrough

The PR adds an injectable maintainer workflow-run approval helper. It validates live pull-request state, repository identity, commit identity, and permissions before approval. It adds bounded retries, timeouts, polling, reconciliation, and comprehensive Vitest coverage.

Changes

Maintainer approval workflow

Layer / File(s)	Summary
Runtime contracts and request controls tools/ci/approve-maintainer-pr-workflow-runs.mts, test/maintainer-pr-workflow-approval-helper.test.ts	Defines the runtime contract, GitHub API shapes, request budgets, timeout signals, transient-error retries, and configurable test harness.
Pull-request validation and authorization tools/ci/approve-maintainer-pr-workflow-runs.mts, test/maintainer-pr-workflow-approval-helper.test.ts	Validates event data, live pull-request state, exact commits, repository heads, author identity, and write or admin permissions.
Workflow-run discovery and identity checks tools/ci/approve-maintainer-pr-workflow-runs.mts, test/maintainer-pr-workflow-approval-helper.test.ts	Finds paginated action_required runs for the exact head SHA and verifies run identity, event, repository, pull-request association, status, and conclusion.
Approval reconciliation and end-to-end execution tools/ci/approve-maintainer-pr-workflow-runs.mts, test/maintainer-pr-workflow-approval-helper.test.ts	Revalidates state before approval, handles transient and ambiguous responses, confirms post-approval state, and stops when authorization or the pull-request head changes.

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

Suggested labels: area: ci, area: security, chore

Suggested reviewers: brandonpelfrey, apurvvkumaria

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowEvent
  participant ApprovalHelper
  participant GitHubAPI
  participant WorkflowRun
  WorkflowEvent->>ApprovalHelper: provide pull-request event
  ApprovalHelper->>GitHubAPI: validate live PR and permissions
  GitHubAPI-->>ApprovalHelper: return current PR state
  ApprovalHelper->>GitHubAPI: list exact-head action_required runs
  GitHubAPI-->>ApprovalHelper: return matching runs
  ApprovalHelper->>GitHubAPI: revalidate state and permissions
  ApprovalHelper->>WorkflowRun: submit approval
  WorkflowRun-->>ApprovalHelper: return approval response
  ApprovalHelper->>GitHubAPI: reconcile workflow-run state
  GitHubAPI-->>ApprovalHelper: return updated run state

Loading

🚥 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 identifies the main change: adding the maintainer approval helper in CI.
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 fix/bootstrap-maintainer-approval-helper

---

_{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 0d25e53 in the fix/bootstrap-mainta... branch remains at 96%, unchanged from commit b148bc1 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 0d25e53 in the fix/bootstrap-mainta... branch remains at 82%, unchanged from commit b148bc1 in the main branch.

Show a code coverage summary of the most impacted files.

File	main b148bc1	fix/bootstrap-mainta... 0d25e53	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/tunnel/services.ts	80%	80%	0%

---

_{Updated August 05, 2026 21:08 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): Failed after a partial review · low confidence · 0 blockers · 1 warning · 0 suggestions

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — exact-head at tools/ci/approve-maintainer-pr-workflow-runs.mts:422: Keep `exact-head` for workflow runs that must match the selected pull request head SHA.
• define — ambiguous approval response at tools/ci/approve-maintainer-pr-workflow-runs.mts:106: Keep the term with the adjacent status-code and reconciliation definition.
• established — workflow-run at tools/ci/approve-maintainer-pr-workflow-runs.mts:313: Use `workflow run` as the noun and `workflow-run` only as a compound modifier.

E2E guidance

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

Recommended E2E: None

Workflow run details

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