fix(onboard): fall back to default CDI spec dirs when docker info reports none

[andrewwhitecdw]

Summary

The native-Linux sandbox GPU preflight now checks Docker's built-in CDI
directories when docker info reports no CDISpecDirs. This prevents a false
failure when an NVIDIA CDI specification is present in a default directory,
while preserving the existing failure when no readable NVIDIA specification
exists.

Related Issue

Closes #7330

Product Scope

Product-scope verdict: PASS. This fixes existing native-Linux onboarding
behavior and does not add an integration, configuration surface, solution
workflow, custom image, or third-party stack.

Changes

• Fall back to /etc/cdi and /var/run/cdi only when Docker reports no CDI
  specification directories. Docker-reported directories retain precedence.
• Cover successful default-directory detection and the failure path when the
  default directories contain no NVIDIA specification.
• Assert the successful fallback through the public preflight result with an
  exact default-directory fake, which addresses the automated test-quality
  finding without changing product behavior.

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 repairs internal CDI detection.
  Existing command and troubleshooting documentation already covers native
  Linux CDI prerequisites, remediation, and default CDI directories.
• 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: A Codex Desktop nine-category security
  review at PR SHA 619dc1aec found no findings. Independent human
  sensitive-path review remains required.
• 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: The change repairs existing native-Linux CDI detection without
  adding commands, configuration, output contracts, or product surfaces.
  Existing command, troubleshooting, and changelog documentation covers CDI
  prerequisites, remediation, and default directories. The changed comment and
  test titles follow WRITING.md. No docs build applies because no
  documentation 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:
  ./node_modules/.bin/vitest run --project cli src/lib/onboard/sandbox-gpu-preflight-routing.test.ts src/lib/onboard/docker-cdi.test.ts src/lib/onboard/preflight-cdi.test.ts —
  3 files and 44 tests passed after the upstream/main merge.
• 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: Andrew White andrewh@cdw.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

The Docker CDI GPU preflight now falls back to /etc/cdi and /var/run/cdi when Docker reports no CDI specification directories. Tests cover successful fallback lookup and failure reporting when no NVIDIA CDI specification exists.

Changes

Docker CDI preflight

Layer / File(s)	Summary
CDI directory fallback src/lib/onboard/sandbox-gpu-preflight.ts	Defines Docker’s default CDI directories and uses them when the reported CDI directory list is empty.
Fallback routing validation src/lib/onboard/sandbox-gpu-preflight-routing.test.ts	Verifies fallback NVIDIA specification lookup and the error path when no specification is found.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The code implements the requested CDI fallback and regression tests for the false-negative onboarding case in #7330.
Out of Scope Changes check	✅ Passed	The changes are limited to the CDI fallback fix and its regression tests, with no unrelated scope added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: falling back to default CDI spec directories when Docker reports none.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/sandbox-gpu-preflight-routing.test.ts (1)

95-113: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert the public preflight outcome instead of a helper call.

toHaveBeenCalledWith(...) couples this regression test to the internal collaborator call. Make the fake return a spec only for the expected fallback directories and inject an exitProcess stub, so incorrect routing fails through validateSandboxGpuPreflight’s observable behavior.

As per path instructions, tests should prioritize behavioral confidence over private mock-call assertions.

Proposed test adjustment

-    const findReadableNvidiaCdiSpecFiles = vi.fn((dirs: string[]) =>
-      dirs.includes("/etc/cdi") ? ["/etc/cdi/nvidia.yaml"] : [],
-    );
+    const findReadableNvidiaCdiSpecFiles = (dirs: string[]) =>
+      dirs.length === 2 &&
+      dirs[0] === "/etc/cdi" &&
+      dirs[1] === "/var/run/cdi"
+        ? ["/etc/cdi/nvidia.yaml"]
+        : [];
+    const exitProcess = (code: number): never => {
+      throw new Error(`exit:${code}`);
+    };

     expect(() =>
       validateSandboxGpuPreflight(sandboxGpuConfig(), {
         // ...
         findReadableNvidiaCdiSpecFiles,
-      }),
+      }, exitProcess),
     ).not.toThrow();
-    expect(findReadableNvidiaCdiSpecFiles).toHaveBeenCalledWith(["/etc/cdi", "/var/run/cdi"]);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/sandbox-gpu-preflight-routing.test.ts` around lines 95 - 113,
Update the regression test around validateSandboxGpuPreflight to assert its
observable preflight outcome rather than the internal
findReadableNvidiaCdiSpecFiles invocation. Configure the fake to return a spec
only when passed ["/etc/cdi", "/var/run/cdi"], inject an exitProcess stub, and
assert the resulting validation behavior so incorrect fallback routing causes
the test to fail.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/onboard/sandbox-gpu-preflight-routing.test.ts`:
- Around line 95-113: Update the regression test around
validateSandboxGpuPreflight to assert its observable preflight outcome rather
than the internal findReadableNvidiaCdiSpecFiles invocation. Configure the fake
to return a spec only when passed ["/etc/cdi", "/var/run/cdi"], inject an
exitProcess stub, and assert the resulting validation behavior so incorrect
fallback routing causes the test to fail.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2d18bac8-d1c0-4c5f-8a7b-16877a0ceb5f

📥 Commits

Reviewing files that changed from the base of the PR and between 7be3ef7 and 3f84360.

📒 Files selected for processing (2)

• src/lib/onboard/sandbox-gpu-preflight-routing.test.ts
• src/lib/onboard/sandbox-gpu-preflight.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 3 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 3 more warnings, 1 more suggestion.

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.

[wscurran]

✨ Thanks for the fix. This addresses the false CDI detection failure during onboarding. Maintainers will review the fallback logic for Docker CDI spec directories.

---

Related open issues:

• #7330 False "Docker CDI GPU support was not detected" on native Linux although CDI GPU passthrough works

[senthilr-nv]

@cv Please:

1. Approve the approve-credentialed-e2e-skip-for-fork-pr environment for PR fix(onboard): fall back to default CDI spec dirs when docker info reports none #7347 in E2E Gate run 30120003754.
2. Independently review PR fix(onboard): fall back to default CDI spec dirs when docker info reports none #7347 and, if satisfied, submit a GitHub PR approval.

Exact pair:

• Head: ea35cb7de2be13b77528bef47c2c78cb147b5945
• Base/live main: b9c82f11ad9c93d28fea7e87fffb7c6dc3c07a02

Required CI passed for this pair. The environment approval records the policy-required skip for credential-bearing fork jobs onboard-repair and onboard-resume; no fork code received repository secrets. It does not replace independent code review, and neither action authorizes merging.

[senthilr-nv]

Reviewed and approve the file changes at exact head ea35cb7 against base b9c82f1.
This is an existing CDI preflight bug fix, not a new supported product surface. Required CI, focused tests, CodeQL, security checks, documentation receipt, and automated reviews pass for this head. All displayed commits are Verified.
This approval covers only the reviewed code at this exact head. The protected fork E2E-skip approval and final merge decision remain separate.