fix(install): defer Windows WSL provider selection until Node.js reads Docker config

[laitingsheng]

Summary

Express setup chose the Windows WSL inference provider before the installer had installed Node.js, so a readable Docker configuration that it could not parse resolved as non-local and pinned install-ollama. Onboarding then detected the Windows-host Ollama, withheld that provider, and stopped before sandbox creation. Express selection now waits for the Node.js runtime and applies the same Docker Desktop check, and an installed Windows-host Ollama that the container runtime cannot reach no longer withholds the WSL-local install entry.

Related Issue

Fixes #8199

Changes

• Add express_wsl_docker_context_needs_node in scripts/install.sh, true only when a readable Docker configuration decides the context and no Node.js can parse it yet.
• Add select_express_wsl_ollama_provider, which selects Windows-host Ollama when the topology proves it, defers when only the missing runtime blocks the decision, and otherwise selects WSL-local Ollama.
• Add resolve_pending_express_wsl_provider, called after install_nodejs and ensure_supported_runtime, which repeats the check with the exact configuration parse and reports the selected provider.
• State the deferral in the express prompt instead of naming a provider the installer cannot determine yet.
• Suppress the install-ollama menu entry only when the sandbox can reach the detected Windows-host Ollama, and pass that reachability from detectInferenceProviderHostState.
• Record the deferred selection and the reachability rule in the Windows preparation page.
• Isolate the upstream Shields deadline snapshot-reuse regression at its intended policy-composition seam so unrelated CI runs do not depend on full coordinator mocks.
• Give the full failed-and-resumed Station onboarding coverage journey an environment-aware timeout after it exceeded Vitest's default budget in repeated CI runs.

The deferral keeps every existing fail-closed outcome: DOCKER_HOST, an overriding DOCKER_CONTEXT, a persisted non-default context, an unreadable configuration, and a malformed configuration all still select WSL-local Ollama. Its current consumer is the Windows WSL express path in main, and test/install-express-wsl-ollama.test.ts protects both the deferral and each fail-closed outcome.

windowsHostOllamaSupported is optional on OllamaInstallMenuInput because the value is read only when hasWindowsOllama is set. Its current consumer is detectInferenceProviderHostState, which always passes the resolved requirement, and src/lib/onboard/provider-host-state.test.ts protects that wiring.

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:
• 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: maintainer nine-category security review refreshed for commit 6bca27be8; the current-main merge and removal of a redundant cache-sensitive assertion did not change production behavior. No blocking findings were identified across secrets, input validation, authorization, dependencies, logging, cryptography, configuration, or privilege boundaries.
• 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: docs-updated
• Evidence: docs/get-started/windows-preparation.mdx documents deferred Windows WSL provider selection and the WSL-local Ollama fallback. The independent documentation-writer review covered commit 6bca27be8, passed the docs build with 0 errors, and verified the OpenClaw, Hermes, and Deep Agents variants. The tunnel refactor preserves existing best-effort model unloading; the final test-only commit removes a redundant cache-sensitive assertion. The complete tunnel test file passed 38/38, git diff --check passed, and signed commit plus push hooks passed, including CLI type checking.
• 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 — command/result or justification: focused installer/provider/menu/tunnel suites passed 86/86; the Shields suite passed 34/34; the focused Station resume case passed 1/1 and its complete file passed 22/22; npm run typecheck:cli passed; npm run docs passed with route check OK; normal merge and prior-head pre-push hooks passed.
• 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) — passed with 0 errors and 2 warnings
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• New Features

  • Improved Windows and WSL Ollama setup to detect whether Windows-host Ollama is reachable.
  • Keeps WSL-local Ollama installation available when Windows-host Ollama cannot be accessed.
  • Selects the appropriate provider after required runtime and Docker details are available.
  • Ensures Ollama models are unloaded when stopping all services.

• Documentation

  • Expanded Windows setup guidance for runtime detection and Ollama fallback behavior.

• Bug Fixes

  • Improved handling of unavailable or unreachable Windows-host Ollama configurations.

[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: 2ab5dd74-1897-4865-a0b4-69d4e9f31045

📥 Commits

Reviewing files that changed from the base of the PR and between 31223a8 and 6bca27b.

📒 Files selected for processing (1)

• src/lib/tunnel/services.test.ts

💤 Files with no reviewable changes (1)

• src/lib/tunnel/services.test.ts

---

📝 Walkthrough

Walkthrough

The WSL installer defers Ollama provider selection until Node.js can resolve Docker configuration. Onboarding checks Windows-host Ollama reachability and retains WSL-local installation when the host service is inaccessible. Tests cover provider resolution, cleanup injection, policy handling, and integration timing.

Changes

WSL Ollama provider handling

Layer / File(s)	Summary
Ollama menu reachability src/lib/onboard/ollama-install-menu.ts, src/lib/onboard/ollama-install-menu.test.ts, src/lib/onboard/provider-host-state.ts, src/lib/onboard/provider-host-state.test.ts	The installation menu accepts windowsHostOllamaSupported. Provider state passes Windows-host reachability to menu resolution. WSL-local installation remains available when Windows-host Ollama is unusable.
Deferred Express provider selection scripts/install.sh, test/install-express-wsl-ollama.test.ts, docs/get-started/windows-preparation.mdx	WSL Express selection waits for Node.js when Docker configuration cannot be parsed. The installer then selects Windows-host or WSL-local Ollama. Tests and documentation cover deferred, immediate, remote, and unreachable-host paths.

Test seam updates

Layer / File(s)	Summary
Injectable Ollama cleanup src/lib/tunnel/services.ts, src/lib/tunnel/services.test.ts	stopAll accepts an optional Ollama unload callback. Tests inject the callback and verify that unloading occurs before the final stopped-status message.
Focused integration test execution src/lib/shields/index.test.ts, src/lib/state/onboard-session-station-express.test.ts	The Shields test directly validates unchanged policy snapshots without temporary storage. The Station Express resume test uses a 15-second timeout.

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

Possibly related PRs

• NVIDIA/NemoClaw#8277: Updates the related Shields no-managed-MCP test.
• NVIDIA/NemoClaw#8278: Modifies the same Shields snapshot-reuse test.
• NVIDIA/NemoClaw#8293: Modifies overlapping service shutdown and Ollama cleanup tests.

Suggested labels: area: onboarding

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes unrelated shield-policy, Station Express timeout, and tunnel cleanup changes not required by issue #8199.	Move unrelated shield-policy, Station Express timeout, and tunnel cleanup changes into separate pull requests.
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 (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary fix: defer Windows WSL provider selection until Node.js can read Docker configuration.
Linked Issues check	✅ Passed	The changes address issue #8199 by deferring provider selection, resolving Docker topology after Node.js installation, and preserving an available Ollama provider.

✨ 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 fix/express-wsl-provider-selection

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 6bca27b in the fix/express-wsl-prov... branch remains at 96%, unchanged from commit 962f1c3 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 6bca27b in the fix/express-wsl-prov... branch remains at 81%, unchanged from commit 962f1c3 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 962f1c3	fix/express-wsl-prov... 6bca27b	+/-
src/lib/onboard...e-patch-flow.ts	76%	71%	-5%
src/lib/policy/...ne-exclusion.ts	96%	92%	-4%
src/lib/private-networks.ts	93%	90%	-3%
src/lib/inferen...vider-models.ts	69%	68%	-1%
src/lib/onboard...install-menu.ts	88%	88%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/credentials/store.ts	55%	56%	+1%
src/lib/inferen...er-discovery.ts	87%	88%	+1%
src/lib/tunnel/services.ts	76%	80%	+4%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated August 05, 2026 05:24 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8209.docs.buildwithfern.com/nemoclaw

[coderabbitai]

Actionable comments posted: 1

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

Inline comments:
In `@src/lib/onboard/provider-host-state.ts`:
- Line 223: Update the value assigned to windowsHostOllamaSupported in the
provider-host state construction to require both
windowsHostOllamaDockerRequirement.supported and windowsOllamaReachable, so it
represents usable Windows-host Ollama reachability rather than Docker topology
alone. Add a regression test covering Docker Desktop with an installed but
unreachable Windows-host daemon and verify install-ollama remains available.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b6109db5-74c2-4f08-84a3-3fed27b56c6b

📥 Commits

Reviewing files that changed from the base of the PR and between 00c6111 and 1c36c73.

📒 Files selected for processing (7)

• docs/get-started/windows-preparation.mdx
• scripts/install.sh
• src/lib/onboard/ollama-install-menu.test.ts
• src/lib/onboard/ollama-install-menu.ts
• src/lib/onboard/provider-host-state.test.ts
• src/lib/onboard/provider-host-state.ts
• test/install-express-wsl-ollama.test.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: Partial review preserved 0 canonical finding(s) and 3 terminology decision(s) before the advisor stopped.

Model lanes

• GPT-5.6 Terra (primary): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

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

• established — Windows-host Ollama at docs/get-started/windows-preparation.mdx:176: Keep `Windows-host Ollama`; repository documentation, installer comments, and tests use this term consistently.
• established — WSL-local Ollama at scripts/install.sh:4207: Keep `WSL-local Ollama`; it consistently identifies the fallback provider path.
• justified — effective Docker context at docs/get-started/windows-preparation.mdx:173: Keep `effective Docker context`; the modifier explains why the installer must account for both overrides and persisted configuration.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, managed-image-multiarch-startup, onboard-repair, onboard-resume

Workflow run details

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

[cv]

The current wiring does not implement the documented reachability rule. detectInferenceProviderHostState passes only windowsHostOllamaDockerRequirement.supported as windowsHostOllamaSupported, even though windowsOllamaReachable is computed immediately above. On Docker Desktop with an installed but unreachable Windows-host daemon, usableWindowsOllama remains true and suppresses the WSL-local install-ollama entry. Pass actual usability (topology support and daemon reachability) and add a regression test where Docker Desktop is supported but the host probe fails.

Security review: no hardcoded secret, unsafe parser, authorization bypass, dependency, cryptography, header, or privilege regression was found in the current diff. The installer/onboarding correctness defect above blocks approval because it can leave the user without the fallback provider that this PR promises. The branch is also behind main; refresh it and obtain current required E2E evidence after the fix. Complete the documentation-writer review receipt for the changed Windows page on the final head.

[cv]

Reviewed commit 9828f6c16. The only change after the prior review is the main merge, so the reachability defect remains: windowsHostOllamaSupported receives topology support without windowsOllamaReachable. An installed but unreachable Windows daemon can still suppress the WSL-local install entry. Pass actual usability and add the Docker Desktop/unreachable-daemon regression test requested in the prior review.

The shared aiohttp main-CI failure is tracked by #8213 and does not replace this code correction. After the fix, rerun required CI/E2E and the documentation-writer review for the resulting commit.

[jyaunches]

Reviewed exact head f54c3a6. This is the right solution for #8199: it keeps the authoritative JSON parser, defers WSL provider selection only until Node.js is available, preserves fail-closed remote Docker handling, and requires Windows-host Ollama reachability before suppressing the WSL-local fallback. All actionable CodeRabbit and published PR Review Advisor feedback is addressed; the primary advisor reports merge_as_is with zero findings. Required CI and the selected cloud-onboard, onboard-repair, and onboard-resume E2E scenarios pass. Security review found no issues across the nine required categories.

Dismissed as stale on current head f28b5a8: the requested Windows-host reachability wiring and unreachable-daemon regression were implemented in e31949e and remain present after the latest main merge. Superseded by later exact-head review.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[cv]

CI for #8278 has now timed out twice in the unchanged stopAll test. Commits f54c3a62238d7c058bf85737ec48d3515693e3a2 and ee3bd723715c4421271642a4cd368cc65ac13c4f contain the reviewed fix and apply cleanly to current main.

To preserve Julie Yaunches's authorship when those commits are transferred to a focused CI repair, repository policy requires Julie's own DCO declaration in this PR description. Julie, please add this line to the description yourself:

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>

Maintainers cannot add or copy that declaration on a contributor's behalf. No code change is requested.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/tunnel/services.test.ts (1)

454-456: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Cover the default Ollama cleanup path.

stopAllForTest always injects unloadOllamaModels, so the changed tests exercise only the injected branch. Add or retain one test that calls stopAll without this option, mocks ../inference/ollama/proxy, and verifies that the fallback cleanup runs.

As per path instructions, tests must verify behavior through the public boundary and mock external dependencies instead of calling a real NVIDIA API.

🤖 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/tunnel/services.test.ts` around lines 454 - 456, Update the tests
around stopAllForTest and the public stopAll API to cover the default cleanup
path without injecting unloadOllamaModels. Mock ../inference/ollama/proxy, call
stopAll without the option, and verify the fallback Ollama cleanup executes
without contacting a real NVIDIA API; retain the injected-branch coverage
separately.

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/tunnel/services.test.ts`:
- Around line 454-456: Update the tests around stopAllForTest and the public
stopAll API to cover the default cleanup path without injecting
unloadOllamaModels. Mock ../inference/ollama/proxy, call stopAll without the
option, and verify the fallback Ollama cleanup executes without contacting a
real NVIDIA API; retain the injected-branch coverage separately.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0c825694-aaa7-48c8-b4cb-f3134042d293

📥 Commits

Reviewing files that changed from the base of the PR and between 2b18817 and b99632e.

📒 Files selected for processing (11)

• docs/get-started/windows-preparation.mdx
• scripts/install.sh
• src/lib/onboard/ollama-install-menu.test.ts
• src/lib/onboard/ollama-install-menu.ts
• src/lib/onboard/provider-host-state.test.ts
• src/lib/onboard/provider-host-state.ts
• src/lib/shields/index.test.ts
• src/lib/state/onboard-session-station-express.test.ts
• src/lib/tunnel/services.test.ts
• src/lib/tunnel/services.ts
• test/install-express-wsl-ollama.test.ts

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

• src/lib/onboard/provider-host-state.ts
• test/install-express-wsl-ollama.test.ts
• src/lib/onboard/ollama-install-menu.test.ts
• src/lib/onboard/ollama-install-menu.ts
• src/lib/onboard/provider-host-state.test.ts
• docs/get-started/windows-preparation.mdx
• scripts/install.sh

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