fix(e2e): carry managed image revision to Jetson

[sandl99]

Summary

Jetson dispatch used the candidate commit for managed-image lookup even when the publication gate selected an earlier first-parent commit, causing a GHCR manifest 404. Carry the selected publication commit through a versioned dispatcher request and keep candidate identity separate in the live test.

This PR is draft until the operator-owned backend accepts contract 2.0.0 and the live Jetson target passes.

Related Issue

Related to #8142. Fixes the Jetson regression exposed after #10031.

Changes

• Expose the selected managed-image publication commit from the publication gate and send it with Jetson dispatch.
• Add immutable contract 2.0.0 compatibility vectors with a required managedImageRevision; retain contract 1.0.0 parsing for the coordinated backend rollout.
• Bind both commit identities into the v2 job ID and reject missing, noncanonical, or extra request data.
• Use the candidate commit for checkout and identity checks while using the publication commit for managed-image lookup.
• Document the two commit identities and add controller, workflow-boundary, and compatibility-vector regression tests.

The versioned compatibility path is required because the operator-owned receiver may still return contract 1.0.0 jobs during rollout. Editing v1 directly would break its immutable cross-repository boundary; the v1 and v2 static-vector tests protect both contracts.

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:
• 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: OIDC permissions, audience, token transport, and authorization remain unchanged. The new noncredential field is a validated lowercase commit SHA, and the v2 job ID binds it to the candidate and workflow-run identity.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 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 e2e-support test/e2e/support/jetson-dispatch-client.test.ts test/e2e/support/jetson-workflow-boundary.test.ts test/e2e/support/base-image-publication-workflow-boundary.test.ts (95 passed); npm run test:e2e-phases:check; npm run typecheck:cli; npm run checks:repository
• Applicable broad gate passed — Not applicable; this is a focused Jetson dispatcher boundary change, not a broad runtime or test-harness change.
• 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) — Not applicable; the owning E2E operator guide changed with code and passed Markdown lint.
• Doc pages follow the style guide (doc changes only) — Not applicable
• New doc pages include SPDX header and frontmatter (new pages only) — Not applicable

---

Signed-off-by: San Dang sdang@nvidia.com

Summary by CodeRabbit

• New Features

  • Added Jetson dispatch contract version 2.0.0.
  • Dispatch requests now include a required managed-image revision.
  • Job tracking and status handling now account for the managed-image revision.
  • Base-image publication exposes the revision used by Jetson runs.

• Documentation

  • Updated Jetson dispatch contract, compatibility, and live-target documentation.

• Tests

  • Added coverage for contract v2 validation, serialization, compatibility, and managed-image requirements.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[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: e7cf4061-1a31-4e9b-acb7-19ed2430a927

📥 Commits

Reviewing files that changed from the base of the PR and between 5211d8b and a50023f.

📒 Files selected for processing (10)

• .github/workflows/e2e.yaml
• test/e2e/docs/jetson-dispatch.md
• test/e2e/live/jetson-nvmap-gpu.test.ts
• test/e2e/support/jetson-dispatch-client.test.ts
• test/e2e/support/jetson-workflow-boundary.test.ts
• tools/e2e/contracts/v2/jetson-dispatch.json
• tools/e2e/jetson-dispatch-client.mts
• tools/e2e/jetson-dispatch-contract.mts
• tools/e2e/operations-workflow-boundary.mts
• tools/e2e/workflow-boundary.mts

Included review availability: Your plan provides up to 12 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Jetson dispatch advances to contract 2.0.0 and requires a managed-image revision. Workflow outputs, client requests, job IDs, status validation, fixtures, tests, and documentation now distinguish candidate and managed-image revisions.

Changes

Jetson dispatch contract and workflow

Layer / File(s)	Summary
Versioned dispatch contract tools/e2e/jetson-dispatch-contract.mts, tools/e2e/contracts/v2/jetson-dispatch.json, test/e2e/support/jetson-dispatch-client.test.ts	The contract supports request and status schemas 1.0.0 and 2.0.0. V2 requires and validates managedImageRevision, includes it in job IDs, and preserves the request schema version through status and artifact parsing.
Publication revision dispatch wiring .github/workflows/e2e.yaml, tools/e2e/operations-workflow-boundary.mts, tools/e2e/workflow-boundary.mts, tools/e2e/jetson-dispatch-client.mts, test/e2e/support/jetson-dispatch-client.test.ts	The base-image publication job exposes managed_image_revision. The workflow passes it to the client, which builds a validated V2 request from the environment.
Boundary and live revision validation test/e2e/support/jetson-workflow-boundary.test.ts, test/e2e/live/jetson-nvmap-gpu.test.ts	Boundary tests require the publication output and dispatch environment. Live tests use separate candidate and managed-image revisions.
Contract and deployment documentation test/e2e/docs/jetson-dispatch.md	The documentation describes V2 requests, compatibility vectors, job identity, revision selection, service compatibility, and separate candidate and managed-image lookup.

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

Merge Risk: ⚪ Minimal · up to a5002

The PR carries the selected managed-image revision separately from the candidate revision to prevent incorrect Jetson image lookups. No actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant BaseImagePublication
  participant GitHubActionsWorkflow
  participant JetsonDispatchClient
  participant JetsonDispatchContract
  participant JetsonService
  BaseImagePublication->>GitHubActionsWorkflow: publish managed_image_revision
  GitHubActionsWorkflow->>JetsonDispatchClient: provide candidate and managed-image revisions
  JetsonDispatchClient->>JetsonDispatchContract: build and validate V2 request
  JetsonDispatchClient->>JetsonService: submit schema-version 2 request
  JetsonService-->>JetsonDispatchClient: return schema-matched status and artifact

Loading

Suggested reviewers: brandonpelfrey, apurvvkumaria

🚥 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 and concisely describes the main change: carrying the managed image revision to Jetson workflows.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
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/jetson-managed-image-handoff

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit a50023f in the fix/jetson-managed-i... branch remains at 96%, unchanged from commit 5211d8b in the main branch.

---

_{Updated August 24, 2026 08:50 UTC}

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions
Synthesis status: Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: cloud-onboard, security-posture, cloud-inference
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Blockers

PRA-1 Blocker — Record remote cancellation failures for accepted Jetson jobs

• Location: tools/e2e/jetson-dispatch-client.mts:194
• Category: security
• Problem: The controller suppresses failures from remote cancellation after it accepts a Jetson job. It writes its artifact receipt only after it receives a completed artifact. A deadline or repeated polling failure plus a rejected DELETE can therefore leave a remote job running without durable recovery evidence.
• Impact: A maintainer cannot identify the accepted remote job or determine whether cancellation reached the operator service before another dispatch. The running job can block the queued controller lane or duplicate device work.
• Fix: Write a bounded private receipt immediately after acceptance with the validated request and job ID. Update it for each cancellation attempt with a success state or bounded non-sensitive error. Include the job ID in the terminal failure message, and document that maintainers must inspect or cancel the recorded job before another dispatch.
• Verification: Read pollJetsonDispatch and the client main path. Simulate a deadline or third polling failure with a rejecting DELETE request and inspect E2E_ARTIFACT_DIR for a receipt that identifies the job and cancellation outcome.
• Test coverage: Extend test/e2e/support/jetson-dispatch-client.test.ts with deadline and repeated-poll-failure cases where DELETE rejects. Assert that the durable receipt contains the accepted job ID, validated request, cancellation attempt, and bounded failure classification.
• Evidence: tools/e2e/jetson-dispatch-client.mts:188-195 suppresses DELETE failures when the controller deadline expires. tools/e2e/jetson-dispatch-client.mts:215-222 suppresses DELETE failures after the third consecutive polling failure. tools/e2e/jetson-dispatch-client.mts:294-304 writes jetson-dispatch.json only after a completed artifact response is received. test/e2e/support/jetson-dispatch-client.test.ts:445-458 verifies a deadline DELETE request but does not cover a rejected DELETE or recovery receipt. test/e2e/docs/jetson-dispatch.md:143-150 states that uploaded Jetson evidence contains completed status data; it gives no recovery record for an accepted job whose cancellation request fails.

Workflow run details

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

[cv]

Reviewed the full Jetson dispatch contract, workflow boundary, compatibility vectors, operator guide, and tests. I fixed the reused-publication path so it sends the pinned managed-image revision instead of the candidate commit. The v2 request now keeps candidate checkout identity separate from managed-image lookup identity, validates both commits, and binds both into the job ID. Focused validation passed: 95 E2E-support tests, semantic E2E phase coverage, normal commit hooks, and the pre-push CLI type-check. No unresolved correctness, security, product-scope, documentation, or test finding remains. Current GitHub check failures are caused by the GitHub installation API rate limit (HTTP 403), not this change.