fix(onboard): accurate preflight message when nvidia-smi works but GPU passthrough disabled

[kagura-chen]

Issue

Closes #3174

Type of change

• Bug fix

What does this PR do?

The preflight GPU hint in onboard had two problems:

1. Showed when user used --no-gpu: The hint "NVIDIA GPU hardware detected but nvidia-smi is not available" appeared even when the user explicitly opted out of GPU passthrough. This is noise — they chose --no-gpu, so telling them about missing GPU support is unhelpful.

2. Never verified nvidia-smi availability: The hint assumed that if gpuPassthrough was false and lspci detected NVIDIA hardware, then drivers must be missing. But the actual issue could be that nvidia-smi works fine (drivers installed) while nvidia-container-toolkit is missing (Docker can't use the GPU). The message sent users to debug drivers instead of the container toolkit.

Changes

• Add !opts.noGpu guard so the hint is skipped when --no-gpu was used
• Extract GPU driver hint logic into src/lib/onboard/gpu-hint.ts to satisfy the onboard-entrypoint-budget CI check (onboard.ts is net -5 lines)
• Actually run nvidia-smi before claiming it is unavailable
• When nvidia-smi works but GPU passthrough was not enabled, print an actionable message about nvidia-container-toolkit installation instead of the misleading driver message
• Add unit tests for the extracted helper in src/lib/onboard/gpu-hint.test.ts

How did you verify your code works?

• npx tsc -p tsconfig.src.json --noEmit — clean compilation
• npx vitest run src/lib/onboard/gpu-hint.test.ts — 5/5 tests pass
• Code review of the logic flow:
  • --no-gpu → opts.noGpu = true → hint block is skipped entirely ✅
  • No --no-gpu, nvidia-smi unavailable → original message preserved ✅
  • No --no-gpu, nvidia-smi works but container toolkit missing → new actionable message ✅

Checklist

• Signed off (DCO)
• Minimal diff — only the hint block changed
• Tests added for new behavior
• onboard-entrypoint-budget satisfied (onboard.ts net -5 lines)

Signed-off-by: kagura-agent kagura.agent.ai@gmail.com

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

📝 Walkthrough

Walkthrough

This PR refines the Linux GPU hardware detection logic during onboarding preflight checks. When a user has not opted out of GPU passthrough (--no-gpu), the code now verifies that nvidia-smi actually works before reporting "drivers missing", distinguishing between missing NVIDIA drivers versus missing container toolkit components.

Changes

GPU Detection Hint Refinement

Layer / File(s)	Summary
GPU Hardware Detection Logic src/lib/onboard.ts	Linux GPU detection now runs lspci and verifies nvidia-smi --query-gpu availability before emitting hardware-present hints. Conditional messages distinguish "nvidia-smi unavailable" from "drivers available but passthrough not enabled" based on actual nvidia-smi exit status and output.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A cunning check for GPUs found,
With lspci scanning all around,
We ask nvidia-smi true,
Does the toolkit work for you?
Now the message fits the clue! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding logic to detect when nvidia-smi works but GPU passthrough is disabled, and showing a better preflight message.
Linked Issues check	✅ Passed	The PR fully addresses issue #3174 by adding nvidia-smi verification, skipping hints when --no-gpu is used, and providing actionable messages for missing nvidia-container-toolkit.
Out of Scope Changes check	✅ Passed	All changes in src/lib/onboard.ts are scoped to fixing the GPU detection hint logic as specified in issue #3174; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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.}

[wscurran]

✨ Thanks for submitting this PR that fixes the inaccurate preflight message when nvidia-smi works but GPU passthrough is disabled. This change involves adding a guard to skip the hint when --no-gpu is used and actually running nvidia-smi before claiming it is unavailable.

---

Related open issues:

• #3174 [Ubuntu 24.04][Onboard] preflight reports "nvidia-smi is not available" when nvidia-smi works but nvidia-container-toolkit is missing

[wscurran]

✨ Thanks for submitting this PR that fixes the inaccurate preflight message when nvidia-smi works but GPU passthrough is disabled. This change involves adding a guard to skip the hint when --no-gpu is used and actually running nvidia-smi before claiming it is unavailable.

---

Related open issues:

• #3174 [Ubuntu 24.04][Onboard] preflight reports "nvidia-smi is not available" when nvidia-smi works but nvidia-container-toolkit is missing

[kagura-chen]

Hi @wscurran 👋 friendly ping — any additional changes needed here? Let me know if there's anything I should adjust.

[cv]

@kagura-agent there are a few failing checks. Mind taking a look?

[kagura-chen]

Rebased onto current main and fixed all CI failures:

Changes in this push:

1. DCO check — Added Signed-off-by trailer to PR body and commit message (git commit --signoff)
2. TypeScript compilation (checks + cli-parity) — The merge commit introduced a scope error: optedOutGpuPassthrough was referenced but not defined at that point in onboard(). Fixed by using opts.noGpu directly, which is the opts parameter already in scope
3. onboard-entrypoint-budget — Extracted GPU driver hint logic into src/lib/onboard/gpu-hint.ts so onboard.ts is net -5 lines (budget requires net-neutral or smaller). The new module lives under src/lib/onboard/ which the budget check explicitly allows to grow
4. Tests — Added src/lib/onboard/gpu-hint.test.ts with 5 tests covering: lspci failure, no NVIDIA hardware, nvidia-smi failure (driver hint), nvidia-smi success (container toolkit hint), and lspci exception
5. Removed the merge commit — clean single commit on top of main