fix(inference): find nvidia-smi on WSL

[cjagwani]

Summary

Stock WSL2 guests can now detect NVIDIA GPUs without adding /usr/lib/wsl/lib to PATH. NVIDIA probes keep the existing PATH command authoritative, then use the stock WSL driver shim only on WSL so preflight can enable GPU passthrough and managed vLLM can pass its prerequisite and compute-capability checks.

Related Issue

Fixes #8794

Changes

• Add a WSL-gated, hardcoded fallback from nvidia-smi to /usr/lib/wsl/lib/nvidia-smi in the existing GPU trust layer.
• Route GPU inventory, driver-version, mixed-GPU selection, and managed-vLLM probes through the same resolver. A local edit to preflight alone is insufficient because managed vLLM separately checks command availability and compute capability.
• Add focused resolver and end-to-end GPU detection regression coverage. The tests protect PATH precedence, WSL fallback, non-WSL behavior, and the managed-vLLM consumer.
• Ratchet the legacy nim.test.ts line budget from 2068 to its new measured value of 2067 after moving the new regression into the focused GPU-detection suite.

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 restores the existing documented WSL GPU contract and adds no command, flag, environment variable, prerequisite, or supported surface.
• 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: focused review confirms the fallback is WSL-gated, uses only the stock hardcoded driver path, preserves PATH precedence, and executes with argv transport; no user-controlled executable path is accepted.
• 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: docs/get-started/windows-preparation.mdx, docs/inference/set-up-vllm.mdx, docs/inference/set-up-nvidia-nim.mdx, and docs/reference/troubleshooting.mdx already describe the supported WSL/GPU contract without requiring nvidia-smi PATH configuration.
• 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 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 cli src/lib/inference/gpu-trust.test.ts src/lib/inference/nim.test.ts src/lib/inference/nim-igpu-compute-constrained.test.ts src/lib/inference/nim-driver-version.test.ts src/lib/inference/vllm-compute-capability.test.ts (124 passed)
• Applicable broad gate passed — npm run checks:repository, npm run typecheck:cli, and npm run test-size:check passed.
• 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: Charan Jagwani cjagwani@nvidia.com

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit df4d2a6 in the codex/8794-wsl-nvidi... branch remains at 96%, unchanged from commit 164a7be in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit df4d2a6 in the codex/8794-wsl-nvidi... branch remains at 82%, unchanged from commit f712516 in the main branch.

Show a code coverage summary of the most impacted files.

File	main f712516	codex/8794-wsl-nvidi... df4d2a6	+/-
src/lib/onboard...ixed-forward.ts	100%	77%	-23%
src/lib/actions...ocker-health.ts	78%	61%	-17%
src/lib/actions...ence-gateway.ts	91%	82%	-9%
src/lib/state/g...way-registry.ts	98%	96%	-2%
src/lib/agent/defs.ts	95%	94%	-1%
src/lib/adapter...ateway-drift.ts	60%	61%	+1%
src/lib/inferen...ollama/proxy.ts	33%	36%	+3%
src/lib/actions...aged-profile.ts	84%	88%	+4%
src/lib/actions...er-lifecycle.ts	85%	94%	+9%
src/lib/inference/gpu-trust.ts	79%	94%	+15%

---

_{Updated August 12, 2026 17:59 UTC}

[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: 57c3cbb2-51c3-437b-baa9-ce906251c7f4

📥 Commits

Reviewing files that changed from the base of the PR and between 8464775 and f2879f0.

📒 Files selected for processing (1)

• ci/test-file-size-budget.json

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

• ci/test-file-size-budget.json

---

📝 Walkthrough

Walkthrough

The change adds WSL-aware NVIDIA SMI discovery. NIM GPU detection and managed vLLM checks now try the PATH command first and the stock WSL driver path when required.

Changes

WSL NVIDIA SMI discovery

Layer / File(s)	Summary
Shared NVIDIA SMI discovery src/lib/inference/gpu-trust.ts, src/lib/inference/gpu-trust.test.ts	Adds shared capture and resolution helpers. WSL checks /usr/lib/wsl/lib/nvidia-smi after the PATH command. Non-WSL systems use PATH only.
NIM GPU detection integration src/lib/inference/nim.ts, src/lib/inference/nim-igpu-compute-constrained.test.ts, ci/test-file-size-budget.json	Routes NIM GPU and driver queries through the shared helper. Adds a WSL override and validates fallback detection. Updates the legacy test-file size budget.
Managed vLLM prerequisite integration src/lib/inference/vllm.ts, src/lib/inference/serving/vllm-managed-support.ts	Routes vLLM command checks and compute-capability reads through the shared helpers. Re-exports the helpers through managed-support.

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

Sequence Diagram(s)

sequenceDiagram
  participant NIM
  participant captureNvidiaSmi
  participant runCapture
  participant GPU
  NIM->>captureNvidiaSmi: request GPU or driver data
  captureNvidiaSmi->>runCapture: run PATH nvidia-smi
  runCapture->>GPU: query NVIDIA SMI
  GPU-->>runCapture: output or error
  captureNvidiaSmi->>runCapture: retry WSL driver path when needed
  runCapture->>GPU: query /usr/lib/wsl/lib/nvidia-smi
  GPU-->>runCapture: NVIDIA SMI output
  runCapture-->>NIM: first non-empty output

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8748: Broadens NVIDIA driver-version parsing in the same NIM GPU detection area.

Suggested labels: area: inference, platform: wsl, bug-fix, provider: vllm

🚥 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement WSL fallback discovery, preserve PATH and non-WSL behavior, and update GPU and vLLM probes as required by issue #8794.
Out of Scope Changes check	✅ Passed	All changes support WSL GPU detection, related integration tests, or the required legacy test-size budget update.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding WSL support to locate nvidia-smi.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/8794-wsl-nvidia-smi

---

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

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

2 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• gpu-e2e: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• vllm-docker-storage: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

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

• justified — stock WSL driver path at src/lib/inference/gpu-trust.ts:19: Keep the term. The comment states the fixed path's WSL-only fallback behavior.
• established — WSL fallback at src/lib/inference/gpu-trust.test.ts:73: Keep the established term. The test title identifies the PATH-first command-selection behavior.

E2E guidance

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

Recommended E2E: inference-routing

Manual-only E2E: network-policy
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Test the WSL fallback in the vLLM capability consumer

• Location: src/lib/inference/vllm-compute-capability.test.ts:75
• Category: tests
• Problem: The managed vLLM capability tests mock only the PATH `nvidia-smi` command. They do not prove that `readGpuComputeCapabilities` accepts capability output from the fixed WSL driver path after the PATH command returns no output.
• Impact: A regression in the vLLM capability consumer can make managed vLLM reject or misclassify a WSL GPU even though NIM detection succeeds through the fallback.
• Recommendation: Add a focused test that simulates WSL, returns no output for `nvidia-smi`, returns a valid capability for `/usr/lib/wsl/lib/nvidia-smi`, and verifies `readGpuComputeCapabilities` or its capability preflight consumes that value.
• Verification: Read `src/lib/inference/vllm-compute-capability.test.ts` and confirm a mock assertion covers the PATH probe followed by `WSL_NVIDIA_SMI_PATH` for `--query-gpu=compute_cap`.
• Test coverage: A vLLM capability test must verify that the fixed WSL driver path supplies the compute capability after the PATH command returns no output.
• Evidence: `src/lib/inference/vllm.ts:402-404` routes `readGpuComputeCapabilities` through `captureNvidiaSmi`. `src/lib/inference/vllm-compute-capability.test.ts:75-89` returns a capability only when `cmd[0] === "nvidia-smi"`. `src/lib/inference/gpu-trust.test.ts:73-101` tests the helper, but not the vLLM capability consumer.

Workflow run details

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

[cv]

Accepted issue #8794 is linked and In Progress. The complete eight-file change preserves PATH precedence, adds only the fixed WSL NVIDIA driver path, updates all relevant GPU and managed-vLLM probes, and adds focused regression coverage. All nine security categories pass: execution uses argv transport, the shell lookup receives a fixed candidate as $1, and no credential, policy, dependency, or authorization boundary changes. No competing open PR, unresolved review finding, compatibility defect, or documentation gap was found.