fix(onboard): use Docker gpus mode on WSL

[HwangJohn]

Summary

Makes the Docker GPU patch use Docker's --gpus mode on Docker Desktop WSL instead of selecting host-visible CDI specs. This keeps the WSL path aligned with Docker Desktop GPU passthrough while preserving CDI-first behavior on native Linux CDI hosts.

Related Issue

Fixes #5512

Changes

• Skip CDI mode selection when the Docker GPU patch is running on Docker Desktop WSL.
• Thread the Docker Desktop WSL runtime context through the deferred sandbox recreate path.
• Add regression coverage for mode selection and recreate command arguments.

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)

Verification

Validated locally on Windows and on DGX Spark/Linux.

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• 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: HwangJohn angelic805@gmail.com

Summary by CodeRabbit

• Improvements
  • Enhanced GPU mode selection for Docker Desktop on WSL by prioritizing --gpus all and skipping CDI probing when applicable.
  • Standardized CDI detection by normalizing path separators for more reliable behavior across Windows/Unix-style environments.
  • Refined “GPU mode” failure messaging to distinguish Docker Desktop WSL from other Docker scenarios.
• Tests
  • Expanded Vitest coverage for WSL GPU mode selection, sandbox recreation behavior, and propagation of the dockerDesktopWsl option through the GPU patch flow.

[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.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: e3e58489-99f6-47bf-af01-132caef308fa

📥 Commits

Reviewing files that changed from the base of the PR and between d9838bd and 3a78f7b.

📒 Files selected for processing (1)

• src/lib/onboard/docker-gpu-sandbox-create.ts

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

• src/lib/onboard/docker-gpu-sandbox-create.ts

---

📝 Walkthrough

Walkthrough

Adds a dockerDesktopWsl?: boolean option to GPU patch sandbox creation, forcing --gpus all and bypassing CDI when Docker Desktop WSL is detected. Normalizes Windows path separators in two existing CDI file-path matchers. Introduces helper documentation for runtime detection and adds comprehensive test coverage for both mode selection and sandbox-create forwarding.

Changes

Docker Desktop WSL GPU Patch Fix

Layer / File(s)	Summary
Docker Desktop WSL detection and option types src/lib/onboard/docker-gpu-sandbox-create.ts	Documents isDockerDesktopWslRuntime() as a cached probe, adds documentation for the test seam loosening override return type, and introduces dockerDesktopWsl?: boolean field to DockerGpuSandboxCreatePatchOptions.
Sandbox create: accept and forward dockerDesktopWsl src/lib/onboard/docker-gpu-sandbox-create.ts	When building applyOptions, reads dockerDesktopWsl from the explicit option or falls back to isDockerDesktopWslRuntime(), then forwards downstream. Adds comprehensive JSDoc for createDockerGpuSandboxCreatePatch, hook methods (createFailureMessage, ensureApplied, selectedMode, verifyGpuOrExit), and helper functions (shouldUseDockerGpuPatchForCreate, resolveDockerGpuSandboxCreatePlan).
Supervisor reconnect failure message refactoring src/lib/onboard/docker-gpu-sandbox-create.ts	Extracts supervisor-reconnect rollback failure message logic into a dedicated supervisorReconnectFailureMessage() helper, replacing inline message construction and centralizing failure reporting during rollback failure handling.
Test coverage: path normalization and Docker Desktop WSL mode selection src/lib/onboard/docker-gpu-patch-mode-selection.test.ts, src/lib/onboard/docker-gpu-patch.test.ts, src/lib/onboard/docker-gpu-sandbox-create.test.ts	Existing CDI readFile mocks normalize Windows backslashes to forward slashes before path comparison. New test suites assert dockerDesktopWsl: true selects only gpus mode without CDI, that recreateOpenShellDockerSandboxWithGpu emits --gpus all without --device, and that createDockerGpuSandboxCreatePatch forwards dockerDesktopWsl: true into the deferred recreate call.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5198: Previously extended Docker GPU patching with Docker Desktop WSL–specific behavior using the same dockerDesktopWsl option threading pattern applied here.

Suggested labels

bug-fix, platform: wsl, area: sandbox, v0.0.65

Suggested reviewers

• cv
• ericksoa

Poem

🐇 On Windows paths with backslash woes,
The CDI probe no longer goes.
--gpus all shall light the way,
On Docker Desktop WSL today.
No orphaned containers, no more despair —
The GPU patch bunny fixed it with care! 🎮

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 78.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 accurately summarizes the main change: fixing Docker GPU patch to use the --gpus mode on Docker Desktop WSL instead of CDI syntax.
Linked Issues check	✅ Passed	The pull request fully addresses issue #5512 by implementing CDI skipping on Docker Desktop WSL, threading the dockerDesktopWsl option through the sandbox recreate path, and adding regression test coverage for mode selection and recreate arguments.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the Docker GPU patch logic and its testing; modifications align with fixing CDI mode selection and adding dockerDesktopWsl option threading throughout the relevant modules.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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