fix(onboard): reuse a Windows-host Ollama that WSL mirrored networking exposes on loopback

[harjothkhara]

Summary

Mirrored WSL networking shares the loopback interface with Windows, so the Windows host's Ollama daemon answers on 127.0.0.1 instead of host.docker.internal. Onboarding recognized a Windows-host daemon only by that hostname, so it read the Windows daemon's version as a local Linux one, found it below 0.32.9, and drove two Linux paths that cannot apply to a Windows install: the install menu routed onboarding into the sudo-bound Linux installer, and the reuse handler applied the Linux loopback systemd override. A non-interactive run stopped before creating the sandbox. NemoClaw now reuses that daemon and takes neither Linux path.

Related Issue

Refs: #9300

Changes

detectInferenceProviderHostState already answers this exact question when it suppresses the duplicate-daemon warning: WSL, a daemon on 127.0.0.1, a reachable Windows daemon, and wslinfo --networking-mode reporting mirrored mean one daemon, not two. That result was computed and thrown away. This makes it a state field so every consumer of the decision reads it.

• src/lib/onboard/provider-host-state.ts: extract isWindowsDaemonOnWslLoopback from maybeWarnAboutDuplicateOllamaDaemons, compute it once, and expose it as windowsDaemonOnWslLoopback on the provider host state.
• src/lib/onboard/ollama-install-menu.ts: add the optional windowsDaemonOnWslLoopback input. When set, hold off both the daemon version gate and the binary version gate.
• src/lib/onboard/setup-nim-flow.ts: pass the fact to the reuse handler's Windows-host argument, which is what decides whether Linux systemd management runs. isWindowsHostOllama itself is deliberately not widened — provider-selection.ts:152 uses it to fail sandbox recovery with wsl-recorded-ollama-windows-host, and that behavior should not change here.
• src/lib/onboard/provider-host-state.ts + src/lib/inference/local.ts: the Windows reachability probe now requires the Ollama wire format ({"models":[...]}) instead of any non-empty body, reusing the exported isValidOllamaTagsResponseBody. The repository already applies this reasoning to the loopback probe ([All Platforms][CLI&UX] nemoclaw status reports Local Ollama backend and auth proxy as "healthy" after backend is stopped (stale health for Scenario A) #4275); it matters more now that this result decides whether a version gate runs.
• src/lib/onboard/local-inference-topology.ts + machine/handlers/provider-inference.ts: resume re-detects the topology and skips Linux service repair for the same daemon (advisor finding PRA-1). onboard.ts stays pure wiring so the onboarding entry composition boundary keeps its recorded provider-decision count; the handler composes the option.
• docs/inference/set-up-ollama.mdx: name the exception to the "Upgrade Ollama entry appears when either side is below 0.32.9" rule, scoped to the topology the code actually confirms.

No new configuration, fallback, or compatibility layer. The menu input is one optional boolean with a single production caller, derived from a predicate the repository already trusts, protected by the tests below.

Judgment calls a reviewer should check

1. The binary gate is held off with the daemon gate. The ollama on the WSL PATH in this topology is the Windows client reached through interop, so the Linux installer cannot replace it either. Even where a genuine WSL-local binary coexists, the Windows daemon owns :11434 under mirrored networking, so installing over it would start a service that cannot bind. The code does not separately prove CLI origin, only daemon origin.
2. The predicate proves "one daemon across loopback", not literally "the Windows daemon". Under mirrored networking the two probes cannot reach different listeners on :11434, which is why the existing duplicate-daemon warning already draws this conclusion. A systemctl is-active ollama probe would give positive origin evidence; that seemed like more mechanism than this defect earns, but it is the maintainers' call.
3. Scope is bounded to Docker Desktop WSL integration — see the limits section.
4. The field is optional rather than required. Production detection always sets a boolean, but making it required forces a line into test/onboard-selection.test.ts, which Test file size budget then rejects at 4179 lines against a 4178 legacy budget. OllamaInstallMenuResult.binaryNeedsUpgrade?: boolean uses the same shape.

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:
• 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:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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: see below
• 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)

Advisor finding PRA-1

The PR review advisor's primary lane flagged that resume repair still applied the Linux systemd override to a recorded route pointing at the Windows daemon. Commit c9eda3f3c fixes it: repairLocalInferenceSystemdOverrideOrExit now takes a topology detector, detectWindowsDaemonOnWslLoopback resolves the same fact from the same predicate for callers with no host snapshot, and a resume test asserts ensureOllamaLoopbackSystemdOverride is not called while model warm-up and validation still run. Verified by mutation: forcing the guard open fails that test with expected "vi.fn()" to not be called at all, but actually been called 1 times.

Two existing handler tests asserted the exact repair options object and were updated to include the new field. They encoded the old call shape, not old behavior.

Negative control

All six new tests, run against git checkout origin/main -- of the four changed source files with the new tests kept:

$ npx vitest run --project cli --no-file-parallelism \
    src/lib/onboard/provider-host-state.test.ts \
    src/lib/onboard/ollama-install-menu.test.ts \
    src/lib/onboard/setup-nim-flow-ollama-topology.test.ts

 × skips Linux service management for a mirrored Windows daemon on WSL loopback (#9300)
 × keeps a stale Windows daemon on WSL mirrored loopback out of the Linux upgrade (#9300)
 × does not treat a loopback daemon as the Windows host without Docker Desktop routing (#9300)
 × rejects a Windows-host reachability body that is not the Ollama wire format (#9300)
 × still warns about duplicate daemons under WSL NAT networking (#9300)
 × does not flag the daemon as upgradable when mirrored WSL networking answers the Windows host on loopback (#9300)

 Test Files  3 failed (3)
      Tests  6 failed | 34 passed (40)

With the change, the same command is 40 passed (40). The other 34 pass either way, so the change moves only the cases it claims to.

The routing test was also checked by mutation: reverting just args.isWindowsHostOllama || args.windowsDaemonOnWslLoopback to args.isWindowsHostOllama fails it with expected false to be true, so it is pinned to the systemd decision and not to incidental state.

Blast radius

Every file in the repository matching resolveOllamaInstallMenuEntry, OllamaInstallMenuInput, detectInferenceProviderHostState, InferenceProviderHostState, ollamaInstallMenu, windowsOllamaReachable, windowsDaemonOnWslLoopback, binaryNeedsUpgrade, or isValidOllamaTagsResponseBody, run in both lanes — integration is not covered by npm run test:changed:

$ npx vitest run --project cli --no-file-parallelism \
    src/lib/inference/local.test.ts \
    src/lib/onboard/{local-inference-topology,ollama-install-menu,provider-host-state,provider-menu,provider-selection,setup-nim-flow,setup-nim-flow-ollama-topology,setup-nim-ollama}.test.ts \
    src/lib/onboard/machine/core-flow-phases.test.ts
 Test Files  10 passed (10)
      Tests  231 passed (231)

$ npx vitest run --project integration --no-file-parallelism \
    test/onboard-ollama-upgrade-version-floor.test.ts \
    test/onboard-selection-windows-provider-rejection.test.ts test/onboard-selection.test.ts
 Test Files  3 passed (3)
      Tests  68 passed (68)

All 37 files under src/lib/onboard/machine/handlers/ also pass (486 tests). npm run typecheck:cli, npm run checks:repository, npx oxfmt --check, npx oxlint, and npm run docs all pass on origin/main at e746431d2.

No existing test needed rewriting: the mirrored topology was untested, so nothing encoded the old behavior. The three Windows-host reachability mocks in provider-host-state.test.ts changed from "{}" to '{"models":[]}' — the real /api/tags shape, and the one the issue reports.

The new tests live in src/lib/onboard/setup-nim-flow-ollama-topology.test.ts rather than setup-nim-flow.test.ts because that file is at the 1500-line budget; Test file size budget rejected the commit until the test moved to a focused file.

What this does not cover

• Not proven on WSL2 hardware. The tests drive the real detectInferenceProviderHostState, resolveOllamaInstallMenuEntry, and createSetupNim with only I/O seams injected, but the end-to-end claim in [WSL2][Onboard] local Ollama onboard aborts after requesting a privileged reinstall when no models are present #9300 — that onboarding then pulls qwen2.5:1.5b and reaches a Ready Hermes sandbox — is not something this machine can run. Hence Refs: rather than Closes:. The pull itself already exists on the reuse path (src/lib/onboard.ts under NEMOCLAW_YES=1, and src/lib/inference/ollama/proxy.ts over HTTP when no Linux CLI exists, [WSL2][Install] express install fails with "Install did not produce ollama.exe on PATH" when Ollama already installed #7472).
• Native Docker Engine, Podman, and Colima inside WSL are deliberately unchanged. The predicate requires windowsOllamaReachable, which requires Docker Desktop WSL integration. Widening it there would be wrong, not merely incomplete: local-inference-topology.ts states that native Docker-in-WSL "cannot reliably route sandbox containers to Windows-host Ollama", so reusing the Windows daemon would hand the sandbox an endpoint it cannot reach. does not treat a loopback daemon as the Windows host without Docker Desktop routing (#9300) locks that boundary. Closing it properly needs a routing answer for those runtimes, which is a separate issue.
• The reused daemon can still be below the 0.32.9 tool-call floor. That matches existing Windows-host behavior — NemoClaw does not offer to upgrade a Windows Ollama from WSL today either — but model validation may still fail against a sufficiently old daemon. Upgrading Ollama on the Windows side in this topology is not addressed here.
• The running-provider menu still labels this daemon Local Ollama (WSL:11434). resolveRunningOllamaMenuEntry (src/lib/onboard/ollama-install-menu.ts) branches on ollamaHost === "host.docker.internal", which this change does not alter. It is the same misclassification in a display path; left out to keep the fix to the two paths that actually fail, and worth a follow-up.
• A requested install-ollama provider is unaffected: resolveProviderKeyFallback already collapses it to the reuse ollama entry (src/lib/onboard/provider-key-fallback.ts), and scripts/install.sh:5093-5104 only emits install-ollama on WSL when Docker Desktop is absent — the case this predicate cannot fire in.

Two review suggestions deliberately not taken

• Widening the detection to non-Docker-Desktop WSL runtimes. That would be wrong rather than merely incomplete — see the limits above.
• Validating /api/tags bodies inside findReachableOllamaHost. Applying isValidOllamaTagsResponseBody at host discovery would harden every platform, not just this topology, and it changes which host onboarding selects everywhere. src/lib/inference/local.test.ts currently asserts a non-JSON body is accepted there, so that is a standing contract worth its own issue rather than a rider on this fix. The Windows-side probe, which this change made load-bearing for a version-gate decision, is validated.

---

Signed-off-by: harjoth harjoth.khara@gmail.com

Summary by CodeRabbit

• New Features

  • Improved Ollama setup on WSL with Docker Desktop mirrored networking.
  • Detects Windows-hosted Ollama daemons and avoids incompatible Linux installation or upgrade prompts.
  • Provides clearer handling for stale WSL-local Ollama daemons requiring an upgrade.
  • Prevents unnecessary Linux systemd repairs and duplicate-daemon warnings when using Windows-hosted Ollama.
  • Improves validation of Ollama responses during host detection.

• Documentation

  • Added guidance for upgrading Windows-hosted Ollama in mirrored WSL environments.

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

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: d88d3ca3-2f65-45d5-bb83-f7af5c518c62

📥 Commits

Reviewing files that changed from the base of the PR and between 9d73ca9 and c9eda3f.

📒 Files selected for processing (10)

• src/lib/onboard.ts
• src/lib/onboard/local-inference-topology.test.ts
• src/lib/onboard/local-inference-topology.ts
• src/lib/onboard/machine/core-flow-phases.test.ts
• src/lib/onboard/machine/handlers/provider-inference-ollama-context.test.ts
• src/lib/onboard/machine/handlers/provider-inference-route-containment.test.ts
• src/lib/onboard/machine/handlers/provider-inference.test-support.ts
• src/lib/onboard/machine/handlers/provider-inference.test.ts
• src/lib/onboard/machine/handlers/provider-inference.ts
• src/lib/onboard/provider-host-state.ts

Included review availability: Your plan includes up to 12 reviews per rolling hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

NemoClaw validates Windows-host Ollama responses, detects mirrored WSL loopback access, suppresses incompatible Linux upgrades, reuses the Windows daemon during onboarding, and skips incompatible Linux systemd repair.

Changes

Mirrored WSL Ollama handling

Layer / File(s)	Summary
Detect and validate mirrored Ollama src/lib/inference/local.ts, src/lib/onboard/provider-host-state.ts, src/lib/onboard/provider-host-state.test.ts	Windows-host probes now require valid Ollama tags output. Mirrored WSL loopback detection records the topology and suppresses duplicate-daemon warnings.
Resolve Ollama installation state src/lib/onboard/ollama-install-menu.ts, src/lib/onboard/ollama-install-menu.test.ts	The install menu skips Linux version and binary upgrade requirements for Windows-host Ollama reached through WSL loopback.
Reuse the detected daemon src/lib/onboard/setup-nim-flow.ts, src/lib/onboard/setup-nim-flow-ollama-topology.test.ts, src/lib/onboard.ts, docs/inference/set-up-ollama.mdx	Setup forwards the topology flag and reuses the running Windows daemon without installation. Documentation directs upgrades to Windows.
Skip incompatible Linux repair src/lib/onboard/local-inference-topology.ts, src/lib/onboard/machine/handlers/provider-inference.ts, related tests	Resumed local-inference repair skips Linux systemd repair when mirrored Windows-host Ollama is detected. Dependency fixtures and regression tests cover the new detector.

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

Merge Risk: 🟡 Moderate · up to c9eda

This change alters onboarding behavior for Windows-hosted Ollama reuse. Targeted tests are reported as passing, but the applicable broad validation gate is still unrecorded, so merge readiness remains pending that check or explicit acceptance.

Sequence Diagram(s)

sequenceDiagram
  participant WSL
  participant ProviderHostState
  participant OllamaInstallMenu
  participant SetupNimFlow
  participant LocalInferenceRepair
  WSL->>ProviderHostState: probe Windows-host Ollama
  ProviderHostState->>ProviderHostState: detect mirrored loopback topology
  ProviderHostState->>OllamaInstallMenu: pass windowsDaemonOnWslLoopback
  OllamaInstallMenu-->>SetupNimFlow: suppress Linux upgrade handling
  SetupNimFlow->>SetupNimFlow: reuse running Windows daemon
  SetupNimFlow->>LocalInferenceRepair: pass topology detector
  LocalInferenceRepair->>LocalInferenceRepair: skip Linux systemd repair

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% 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	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes reusing Windows-host Ollama through WSL mirrored networking on loopback, which is the primary change.

✨ Finishing Touches 💡 2

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch oss-find/nemoclaw-9300-wsl-mirrored-ollama

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{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: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

2 additional E2E selections from the second opinion

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

• hermes-e2e: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• hermes-gpu-startup: 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 — mirrored WSL networking at src/lib/onboard/local-inference-topology.ts:25: Keep this term. The modifier distinguishes the detected topology from NAT networking.
• justified — Windows daemon on WSL loopback at src/lib/onboard/local-inference-topology.test.ts:127: Keep this term. It identifies the topology that must skip Linux service management.

E2E guidance

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

Recommended E2E: managed-image-protected-runtime, inference-routing

Manual-only E2E: cloud-onboard, managed-image-multiarch-startup, onboard-repair, onboard-resume, network-policy
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

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

[cv]

Looks like this was already addressed by #9345, but feel free to reopen if there's more to do.

[harjothkhara]

@cv Thanks. #9345 covers the install menu and fresh onboarding. Three items from this PR did not land:

1. Resume still runs the Linux systemd repair. The resume shortcut calls repairLocalInferenceSystemdOverrideOrExit for every recorded ollama-local selection without rechecking the mirrored-Windows topology (src/lib/onboard/local-inference-topology.ts). With a residual ollama.service, that is the sudo-bound repair path against a daemon with no Linux service.

2. probeWindowsOllamaReachable accepts any non-empty body, and its result now feeds isWindowsHostOllama. Nothing proves the responder is Ollama. Validating the /api/tags body with isValidOllamaTagsResponseBody would match the existing health checks.

3. To confirm: in non-interactive recovery with no explicit provider, the widened flag now fails a recorded ollama-local with wsl-recorded-ollama-windows-host (provider-selection.ts:152). That rejects sessions fresh onboarding just created, since recorded state has no topology.

Also stale: the provider-selection.ts:112 comment and the (WSL:11434) menu label.

I can reopen this rebased to points 1 and 2, reusing #9345's classification, or open a fresh follow-up.