refactor(onboard): separate compute driver from gateway launcher

[ericksoa]

Summary

Introduce an explicit OpenShell compute plan that separates compute-driver identity from gateway-launch ownership. Existing Docker and Kubernetes selection remains unchanged, while sandbox registry metadata now records the resolved driver directly. This is stack PR 1 for #7744.

Related Issue

Related to #7744

Changes

• Add OpenShellComputePlan with separate driverName and gatewayLauncher fields.
• Route the existing platform decision through the compute plan without enabling Podman selection.
• Record the resolved OpenShell driver in sandbox registry metadata instead of inferring it from Docker gateway ownership.
• Add platform-regression and future-driver contract tests. A direct platform check is insufficient because native Podman and MXC can use a NemoClaw-launched gateway without becoming Docker drivers.
• Give the existing planner-report integration case its own 30-second budget after it repeatedly exceeded Vitest’s unrelated 5-second default on both pre-change and exact-head CI.

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 PR does not add a CLI option, change driver selection, or claim Podman support.
• 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: Maintainer-directed behavior-preserving groundwork under [Epic] Support native Podman with buildless managed onboarding #7744; focused tests prove existing selection and registry behavior.
• 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: At 3eccbec3e, the diff changes only internal compute-plan metadata plumbing and an E2E-support test timeout; no command, prompt, default, configuration, support claim, or documentation route changed.
• 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 — command/result or justification: npx vitest run --project cli src/lib/onboard/compute/plan.test.ts src/lib/onboard/docker-driver-platform.test.ts src/lib/onboard/sandbox-registry-metadata.test.ts — 2 files and 16 tests passed; npx vitest run --project integration test/shellquote-sandbox.test.ts — 1 file and 4 tests passed; npm run typecheck:cli passed; npx vitest run --project e2e-support test/e2e/support/e2e-report-to-pr-workflow-boundary.test.ts -t "carries the generated planner matrix" passed in 6.5 seconds under its explicit 30-second budget.
• 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: Aaron Erickson aerickson@nvidia.com

Summary by CodeRabbit

• New Features

  • Added compute-plan detection to select the appropriate driver and gateway based on the device platform.
  • Sandbox runtime metadata now reports the resolved compute driver directly, improving Docker and Kubernetes identification.

• Bug Fixes

  • Improved driver and gateway selection across Linux, macOS, and Windows systems.
  • Prevented incorrect driver reporting during sandbox reuse and metadata updates.

• Tests

  • Added coverage for platform-specific compute plans, gateway ownership, and runtime driver metadata.

[Copilot]

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

[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: ed50972c-a5db-4ac7-a00e-d43c56b03ce0

📥 Commits

Reviewing files that changed from the base of the PR and between 3eccbec and ea819d7.

📒 Files selected for processing (1)

• src/lib/onboard.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/onboard.ts

---

📝 Walkthrough

Walkthrough

The PR adds explicit compute-plan types and resolution helpers, routes Docker gateway detection through them, and passes the resolved driver name directly into sandbox registry metadata generation. Tests cover platform mappings, gateway predicates, metadata driver propagation, and runtime getter behavior.

Changes

Compute plan and sandbox metadata

Layer / File(s)	Summary
Compute plan resolution and compatibility src/lib/onboard/compute/plan.ts, src/lib/onboard/compute/plan.test.ts, src/lib/onboard/docker-driver-platform.ts	Compute plans now resolve driver and gateway launcher values by platform and architecture, while the existing Docker gateway predicate delegates to the new helpers and is covered by tests.
Explicit sandbox metadata driver src/lib/onboard/sandbox-registry-metadata.ts, src/lib/onboard/sandbox-registry-metadata.test.ts	Sandbox metadata receives a driver-name getter, records that value directly, and tests Docker, Kubernetes, arbitrary driver names, and runtime getter resolution.
Onboarding plan integration src/lib/onboard.ts	Onboarding loads the platform module and supplies the current compute plan’s driver name when creating sandbox metadata helpers.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: chore

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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 refactor: splitting compute driver selection from gateway launcher handling.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/podman-driver-selection-groundwork

---

_{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 75bce2c in the feat/podman-driver-s... branch remains at 96%, unchanged from commit 45d7e1a in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 75bce2c in the feat/podman-driver-s... branch remains at 81%, unchanged from commit 45d7e1a in the main branch.

Show a code coverage summary of the most impacted files.

File	main 45d7e1a	feat/podman-driver-s... 75bce2c	+/-
src/lib/onboard...try-metadata.ts	90%	70%	-20%
src/lib/onboard/docker-cdi.ts	80%	70%	-10%
src/lib/onboard...host-anchors.ts	94%	90%	-4%
src/lib/onboard/preflight.ts	80%	80%	0%
src/lib/actions...light-guards.ts	86%	90%	+4%
src/lib/onboard...box-gpu-mode.ts	92%	97%	+5%
src/lib/actions...confirmation.ts	69%	79%	+10%
src/lib/actions...ocker-health.ts	65%	82%	+17%
src/lib/onboard...box-prebuild.ts	74%	92%	+18%
src/lib/onboard...compute/plan.ts	0%	100%	+100%

---

_{Updated July 30, 2026 14:35 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: onboard-repair, onboard-resume, cloud-onboard

Workflow run details

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

[Copilot]

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

[Copilot]

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

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[cjagwani]

Maintainer security review — exact head e002e30b663088b385f9894085c60ef8255818e2 against base 795de982e26b400009bf1fc0f3826845d79acc4d: PASS. No security findings. Diff fingerprint: 107627f307189a6829072cf34529a9764d10c255acc83188fb85854ea5c14b20.

1. Secrets and credentials — PASS. No credential values, hashes, stores, providers, or logging paths change.
2. Input validation and sanitization — PASS. The plan is derived only from the existing bounded Node platform/architecture values and preserves today’s exact platform mapping.
3. Authentication and authorization — PASS. No authentication, pairing, roles, permissions, or gateway access rules change.
4. Dependencies and third-party code — PASS. No dependency, lockfile, image, registry, or license changes.
5. Error handling and logging — PASS. No new failure-swallowing or sensitive logging behavior; the metadata resolver remains synchronous and deterministic.
6. Cryptography and data protection — PASS / not applicable. No cryptographic or protected-data behavior changes.
7. Configuration and infrastructure — PASS. The patch separates driver identity from gateway-launch ownership without enabling Podman/MXC or changing Docker/Kubernetes selection, network policy, capabilities, or filesystem permissions.
8. Security testing — PASS. Tests preserve the existing Linux/macOS/Windows mapping, prove future non-Docker drivers do not inherit Docker lifecycle ownership, and verify registry metadata resolves at write time. Current CI and the trusted onboard repair/resume E2E gate pass.
9. Holistic security posture — PASS. This is behavior-preserving groundwork under the accepted #7744 design; it removes an unsafe inference between gateway ownership and driver identity without expanding product scope.

[cjagwani]

Approved at exact head e002e30b663088b385f9894085c60ef8255818e2 against base 795de982e26b400009bf1fc0f3826845d79acc4d.

Final gate: accepted scope under #7744; all current checks and the trusted E2E gate pass; both advisor lanes report 0 blockers / 0 warnings / 0 suggestions; exact-head security review is PASS; docs review is no-docs-needed; all six commits are GitHub Verified; and no review threads remain unresolved. The change preserves current driver selection while making registry driver identity explicit.

[cjagwani]

Exact-head review remains approved at e002e30b663088b385f9894085c60ef8255818e2, but the PR is still based on 795de982e26b400009bf1fc0f3826845d79acc4d while current main is 376beb50b6d184675283bdbc4f2eca18d7200a86. Maintainer edits are disabled, so the merge gate needs an author refresh before current-base CI/evidence can be accepted. I will re-gate the next quiet revision. This is a plain handoff comment, not Changes Requested.

[cjagwani]

Correction to my prior handoff: conflict-free base refreshes are explicitly waived. Please do not merge main solely for base currency; preserving exact-head CI/E2E and documentation receipts is preferred unless GitHub reports a real conflict or reviewed behavior requires a change. The existing approval/review evidence remains in force, and I will continue monitoring mergeability. This is a plain coordination comment, not Changes Requested.

[cjagwani]

Re-approved exact head 75bce2c9510d05501a7956f84a812587ec855c33 after the merge-only refresh from previously reviewed head e002e30b663088b385f9894085c60ef8255818e2.

The reviewed six-file feature diff is unchanged. The existing exact-diff security PASS therefore remains applicable. All 43 current checks are green, DCO is present, all seven commits are Verified, GitHub reports MERGEABLE/CLEAN, and no unresolved major/critical findings remain. A further conflict-free base refresh is explicitly waived and not requested.