fix(onboard): prepare Jetson images before GPU probes

[latenighthackathon]

Outcome

Jetson managed onboarding now prepares an uncached sandbox image before the 30-second GPU probe. Image downloads use the existing progress watchdog instead of consuming the probe timeout.

Reason

The image preparation path covered Docker Desktop WSL but not Jetson, which could misreport a slow image download as an NVIDIA runtime failure.

Related issues

Fixes #11677

Changes

• Reuse managed image preparation for Jetson compatibility GPU probes and disable implicit pulls during those probes.
• Preserve cached-image reuse, pull-failure handling, and other Docker hosts' existing behavior.
• Cover cold and cached Jetson images and abort before probing when image preparation times out.

Verification

• The new cold-image sequencing regression failed on v0.0.125 and current main before the fix.
• Managed-bootstrap, Jetson GPU-patch, and GPU lifecycle suites: 341 tests passed across 19 files.
• Normal commit and pre-push hooks passed, including publication validation and CLI, plugin, and JS-config type checks.
• The diff contains no secrets, API keys, or credentials.

Review notes

Self-review of NVIDIA/NemoClaw commit 215b36d4293daf4e3b07df66071a4c63d839ea13 covered the managed-bootstrap lifecycle and affected tests. This reuses the existing digest-pinned image preparation and credential-cleanup paths. GPU admission, device permissions, and runtime ownership are unchanged.

Tests ran in Linux with mocked Docker boundaries. No physical Jetson onboarding or CUDA qualification is claimed; this does not establish new platform support. Independent CI and automated review remain pending.

---

Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com

Summary by CodeRabbit

• Bug Fixes

  • Improved GPU compatibility detection for Docker Desktop on WSL and Jetson devices.
  • Required probe images are now prepared before GPU detection, helping uncached environments complete reliably.
  • Cached images can be reused without unnecessary downloads.
  • Probe operations now stop cleanly when image preparation exceeds its timeout.

• Tests

  • Added coverage for image pulling, cached-image handling, and timeout behavior across WSL and Jetson environments.

[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: 12017854-2a8b-49cd-a867-91901ced0590

📥 Commits

Reviewing files that changed from the base of the PR and between d3587e8 and 215b36d.

📒 Files selected for processing (2)

• src/lib/onboard/managed-bootstrap/docker-runtime.test.ts
• src/lib/onboard/managed-bootstrap/docker-runtime.ts

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

---

📝 Walkthrough

Walkthrough

Changes

GPU image preparation

Layer / File(s)	Summary
Pre-probe image preparation src/lib/onboard/managed-bootstrap/docker-runtime.ts	Jetson and Docker Desktop WSL compatibility GPU routes prepare the managed image before GPU mode selection. Probe pulls use pullPolicy: "never".
Platform-specific preparation coverage src/lib/onboard/managed-bootstrap/docker-runtime.test.ts	Tests cover uncached Jetson images, cached images on Jetson and WSL, and pull timeouts before GPU probing.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant createDockerLifecycle
  participant ImagePreparation
  participant Docker
  participant GPUProbe
  createDockerLifecycle->>ImagePreparation: Prepare image for Jetson or WSL
  ImagePreparation->>Docker: Pull image with 30-minute limit
  createDockerLifecycle->>GPUProbe: Select GPU mode after preparation
  GPUProbe->>Docker: Probe with pullPolicy never and 30-second timeout

Loading

Suggested reviewers: ericksoa

Merge Risk: ⚪ Minimal · up to 215b3

Jetson image preparation is moved before the bounded GPU probe, while cached images and pull-timeout behavior remain covered. No current merge-blocking risk is identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files.	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 and concisely describes the main change: preparing Jetson managed-bootstrap images before GPU probes.
Linked Issues check	✅ Passed	The change satisfies #11677. For compatibility GPU mode on Jetson, createDockerLifecycle prepares the digest-pinned managed image before mode selection. prepareDockerManagedBootstrapGpuProbeImage …
Out of Scope Changes check	✅ Passed	The changes stay within #11677. The implementation adds Jetson coverage to the existing managed image preparation path and preserves WSL behavior. The tests cover Jetson behavior and regression behavi…

• Fix all pre-merge checks with AI

✨ 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 codex/fix-jetson-gpu-probe-prepull-11677

---

_{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 215b36d in the codex/fix-jetson-gpu... branch remains at 96%, unchanged from commit 17015b5 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 215b36d in the codex/fix-jetson-gpu... branch remains at 83%, unchanged from commit 4c4de3a in the main branch.

Show a line coverage summary of the most impacted files.

File	main 4c4de3a	codex/fix-jetson-gpu... 215b36d	+/-
src/lib/security/redact-url.ts	100%	99%	-1%
src/lib/messagi...nnels/policy.ts	98%	97%	-1%
src/lib/onboard...cker-runtime.ts	84%	84%	0%
src/lib/agent/defs.ts	97%	97%	0%
src/lib/agent/s...ory-contract.ts	97%	97%	0%
src/lib/sandbox...rce-identity.ts	82%	82%	0%
src/lib/securit...ntial-filter.ts	96%	96%	0%
src/lib/onboard...uild-context.ts	74%	75%	+1%

---

_{Updated September 16, 2026 03:03 UTC}

[github-actions]

PR Review Advisor finished for commit 215b36d. Include the Advisor findings in the complete PR feedback collection. Verify and group valid findings before repair.

Request review only when Require no Advisor blockers is green.

All previous runs

[kaofelix]

Thanks for the focused fix and test coverage. We are closing this PR because the accepted Jetson GPU direction now uses OpenShell-native CDI as the single authority for device injection, mounts, supplemental groups, and hardware-derived sandbox policy.

This PR correctly prevents a cold image pull from consuming the bounded NemoClaw compatibility probe timeout. However, it changes the legacy Jetson compatibility probe and container-recreation path, which NemoClaw no longer intends to extend. PR #8910 owns NemoClaw adoption and qualification of the released OpenShell CDI contract.

Issue #11677 will remain open and track that supported path. This closure does not mean that #8910 already contains this pre-pull change or that the reported behavior is fixed.