fix(onboard): reuse mirrored Windows Ollama (#9345)

<!-- markdownlint-disable MD041 -->
## Summary

Reuse Windows-host Ollama when WSL mirrored networking exposes that
daemon through `127.0.0.1`. Before this change, NemoClaw treated the
loopback response as a WSL-local daemon and could route Ollama 0.32.5
through the Linux upgrade installer even though the usable daemon was
installed on Windows.

## Related Issue

Fixes #9300

## Changes

- Classify WSL loopback as Windows-host Ollama only when `wslinfo`
reports mirrored networking, a Windows Ollama installation is present,
Docker can reach the Windows daemon, and Linux procfs shows no WSL-owned
listener on the Ollama port.
- Exclude that positively identified Windows daemon from the WSL-local
binary and daemon version-upgrade path.
- Keep fail-closed behavior for ordinary WSL loopback daemons,
dual-daemon topologies, unavailable socket identity, and unrecognized
WSL networking modes.
- Add regression coverage for mirrored-network classification, Ollama
0.32.5, local-listener identity, and ambiguous modes; document the
topology rule.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [x] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: Approved by @cv:
#9345 (review)
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit: Not applicable
- Station profile/scenario: Not applicable
- Result: Not applicable
- Supporting evidence: Not applicable

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] 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
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — `npm run test -- --run
src/lib/onboard/provider-host-state.test.ts
src/lib/onboard/ollama-install-menu.test.ts
src/lib/onboard/provider-menu.test.ts
test/install-express-wsl-ollama.test.ts
test/onboard-selection-windows-provider-rejection.test.ts
test/onboard-selection.test.ts` (133 passed)
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result: Not applicable; the change
is isolated to Ollama topology classification and its install menu.
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only) — build
succeeded with 0 errors and 2 pre-existing warnings
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

---------

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

Author: prekshivyas

docs/inference/set-up-ollama.mdx

@@ -49,6 +49,8 @@ When neither side can be read, the failure asks you to check that Ollama is inst
 Fresh installs skip this second probe because the bundled installers provide a daemon at or above the minimum.
 
 The version gate does not apply to Windows-host Ollama reached from Docker Desktop through `host.docker.internal`.
+With WSL mirrored networking, the same daemon can answer on `127.0.0.1`; NemoClaw treats it as Windows-host Ollama only when Windows installation and Docker reachability checks match and Linux procfs shows no WSL-local listener on the Ollama port.
+Ambiguous evidence or a separate WSL-local listener stays on the Linux install and upgrade path.
 The Windows-host menu entries perform their own actions on the Windows side.
 
 ## Choose a Linux Install Mode

src/lib/inference/local.ts

@@ -83,6 +83,7 @@ export function resetOllamaContainerPortCache(): void {
 export const HOST_GATEWAY_URL = "http://host.openshell.internal";
 export const LOCAL_INFERENCE_SANDBOX_HOST_URL_ENV = "NEMOCLAW_LOCAL_INFERENCE_SANDBOX_HOST_URL";
 export { CONTAINER_REACHABILITY_IMAGE } from "../adapters/http/container-curl-probe";
+export { OLLAMA_PORT };
 
 // These tags are convenience aliases for callers that want to refer to a
 // specific bootstrap model by role rather than by string. The canonical

src/lib/onboard/ollama-install-menu.test.ts

@@ -200,6 +200,27 @@ describe("resolveOllamaInstallMenuEntry", () => {
     expect(result.entry).toBeNull();
   });
 
+  it("does not route mirrored Windows-host Ollama through the WSL installer (#9300)", () => {
+    const result = resolveOllamaInstallMenuEntry({
+      hasOllama: true,
+      ollamaRunning: true,
+      hasWindowsOllama: true,
+      windowsHostOllamaSupported: true,
+      isWindowsHostOllama: true,
+      ollamaHost: "127.0.0.1",
+      installedOllamaVersion: "0.32.5",
+      runningOllamaVersion: "0.32.5",
+      platform: "linux",
+      isWsl: true,
+    });
+
+    expect(result).toEqual({
+      entry: null,
+      hasUpgradableOllama: false,
+      binaryNeedsUpgrade: false,
+    });
+  });
+
   it("omits the entry when only Windows-host Ollama is present", () => {
     const result = resolveOllamaInstallMenuEntry({
       hasOllama: false,

src/lib/onboard/ollama-install-menu.ts

@@ -20,6 +20,9 @@ export interface OllamaInstallMenuInput {
    *  routing covers nothing, so the WSL-local install entry stays on offer.
    *  Only read when `hasWindowsOllama` is set; defaults to reachable. */
   windowsHostOllamaSupported?: boolean;
+  /** True when the responding daemon is known to run on Windows, including
+   *  WSL mirrored networking where it is observed through distro loopback. */
+  isWindowsHostOllama?: boolean;
   platform: NodeJS.Platform;
   isWsl: boolean;
   /** Resolved host for the running Ollama daemon. `host.docker.internal`
@@ -138,7 +141,9 @@ export function resolveOllamaInstallMenuEntry(
   // 127.0.0.1/localhost. A Windows-host daemon reached via
   // `host.docker.internal` is handled by separate menu entries
   // (`install-windows-ollama` / `start-windows-ollama`).
-  const daemonProbeApplies = input.ollamaRunning && isLocalOllamaHost(input.ollamaHost);
+  const localUpgradeApplies = input.isWindowsHostOllama !== true;
+  const daemonProbeApplies =
+    localUpgradeApplies && input.ollamaRunning && isLocalOllamaHost(input.ollamaHost);
   const runningOllamaVersion =
     input.runningOllamaVersion !== undefined
       ? input.runningOllamaVersion
@@ -150,14 +155,18 @@ export function resolveOllamaInstallMenuEntry(
   // on the old version (and vice versa). Upgrade when either source is below
   // the minimum.
   const installedBinaryMeetsMinimum =
-    input.hasOllama && isOllamaVersionAtLeast(installedOllamaVersion, MIN_OLLAMA_VERSION);
+    localUpgradeApplies &&
+    input.hasOllama &&
+    isOllamaVersionAtLeast(installedOllamaVersion, MIN_OLLAMA_VERSION);
   const daemonNeedsUpgrade =
     daemonProbeApplies && !isOllamaVersionAtLeast(runningOllamaVersion, MIN_OLLAMA_VERSION);
   // Restart-only recovery is safe only with positive evidence that the
   // installed binary meets the floor. A stale daemon without a local binary
   // still needs the installer to provide one.
   const binaryNeedsUpgrade =
-    !installedBinaryMeetsMinimum && (input.hasOllama || daemonNeedsUpgrade);
+    localUpgradeApplies &&
+    !installedBinaryMeetsMinimum &&
+    (input.hasOllama || daemonNeedsUpgrade);
   const hasUpgradableOllama = binaryNeedsUpgrade || daemonNeedsUpgrade;
   // A Windows-host install only covers the local-inference need when the
   // sandbox can route to it. Under a container runtime without that routing,

src/lib/onboard/provider-host-state.test.ts

@@ -6,6 +6,7 @@ import { MIN_OLLAMA_VERSION } from "../inference/ollama-version";
 import { getWindowsHostOllamaDockerRequirement } from "./local-inference-topology";
 import {
   type DetectInferenceProviderHostStateDeps,
+  detectLocalTcpListener,
   detectInferenceProviderHostState,
   type InferenceProviderHostGpu,
 } from "./provider-host-state";
@@ -40,6 +41,7 @@ function buildDeps(
     getWindowsHostOllamaDockerRequirement: vi.fn(() => SUPPORTED_WINDOWS_OLLAMA),
     detectVllmProfile: vi.fn(() => null),
     getLocalProviderAvailabilityEndpoint: vi.fn(() => "http://127.0.0.1:8000/v1/models"),
+    detectLocalTcpListener: vi.fn(() => null),
     ...overrides,
   };
 }
@@ -294,7 +296,7 @@ describe("detectInferenceProviderHostState", () => {
     expect(isWsl).toHaveBeenCalledWith({ platform: "linux", env });
   });
 
-  it("suppresses the duplicate-daemon warning when WSL mirrored networking makes the probes equivalent", () => {
+  it("classifies a mirrored loopback daemon as Windows-host Ollama (#9300)", () => {
     const logs: string[] = [];
     const deps = buildDeps({
       isWsl: vi.fn(() => true),
@@ -310,6 +312,7 @@ describe("detectInferenceProviderHostState", () => {
         return "";
       }),
       dockerCapture: vi.fn((command) => (command.at(-1) === WINDOWS_OLLAMA_TAGS_URL ? "{}" : "")),
+      detectLocalTcpListener: vi.fn(() => false),
     });
 
     const state = detectInferenceProviderHostState({
@@ -324,9 +327,103 @@ describe("detectInferenceProviderHostState", () => {
     });
 
     expect(state.windowsOllamaReachable).toBe(true);
+    expect(state.isWindowsHostOllama).toBe(true);
+    expect(state.ollamaInstallMenu.entry).toBeNull();
     expect(logs).toEqual([]);
   });
 
+  it("keeps a mirrored WSL-local daemon on the Linux upgrade path (#9300)", () => {
+    const logs: string[] = [];
+    const deps = buildDeps({
+      isWsl: vi.fn(() => true),
+      hostCommandExists: vi.fn((command) => command === "ollama"),
+      findReachableOllamaHost: vi.fn(() => "127.0.0.1"),
+      detectWindowsHostOllama: vi.fn(() => ({
+        installed: true,
+        installedPath: "C:\\Ollama\\ollama.exe",
+        loopbackOnly: false,
+      })),
+      runCapture: vi.fn((command) =>
+        command.join(" ").includes("wslinfo --networking-mode") ? "mirrored\n" : "",
+      ),
+      dockerCapture: vi.fn((command) => (command.at(-1) === WINDOWS_OLLAMA_TAGS_URL ? "{}" : "")),
+      detectLocalTcpListener: vi.fn(() => true),
+    });
+
+    const state = detectInferenceProviderHostState({
+      gpu: null,
+      experimental: false,
+      platform: "linux",
+      env: {},
+      log: (message = "") => logs.push(message),
+      installedOllamaVersion: "0.32.5",
+      runningOllamaVersion: "0.32.5",
+      deps,
+    });
+
+    expect(state.windowsOllamaReachable).toBe(true);
+    expect(state.isWindowsHostOllama).toBe(false);
+    expect(state.ollamaInstallMenu.entry?.key).toBe("install-ollama");
+    expect(state.ollamaInstallMenu.hasUpgradableOllama).toBe(true);
+    expect(logs.join("\n")).toContain("Ollama is running on both WSL and the Windows host");
+  });
+
+  it("fails closed when mirrored listener identity is unavailable (#9300)", () => {
+    const deps = buildDeps({
+      isWsl: vi.fn(() => true),
+      findReachableOllamaHost: vi.fn(() => "127.0.0.1"),
+      detectWindowsHostOllama: vi.fn(() => ({
+        installed: true,
+        installedPath: "C:\\Ollama\\ollama.exe",
+        loopbackOnly: false,
+      })),
+      runCapture: vi.fn((command) =>
+        command.join(" ").includes("wslinfo --networking-mode") ? "mirrored\n" : "",
+      ),
+      dockerCapture: vi.fn((command) => (command.at(-1) === WINDOWS_OLLAMA_TAGS_URL ? "{}" : "")),
+      detectLocalTcpListener: vi.fn(() => null),
+    });
+
+    const state = detectWithDeps(deps);
+
+    expect(state.isWindowsHostOllama).toBe(false);
+  });
+
+  it("keeps an unrecognized WSL networking mode on the Linux upgrade path (#9300)", () => {
+    const detectLocalTcpListener = vi.fn(() => false);
+    const deps = buildDeps({
+      isWsl: vi.fn(() => true),
+      hostCommandExists: vi.fn((command) => command === "ollama"),
+      findReachableOllamaHost: vi.fn(() => "127.0.0.1"),
+      detectWindowsHostOllama: vi.fn(() => ({
+        installed: true,
+        installedPath: "C:\\Ollama\\ollama.exe",
+        loopbackOnly: false,
+      })),
+      runCapture: vi.fn((command) =>
+        command.join(" ").includes("wslinfo --networking-mode") ? "future-mode\n" : "",
+      ),
+      dockerCapture: vi.fn((command) => (command.at(-1) === WINDOWS_OLLAMA_TAGS_URL ? "{}" : "")),
+      detectLocalTcpListener,
+    });
+
+    const state = detectInferenceProviderHostState({
+      gpu: null,
+      experimental: false,
+      platform: "linux",
+      env: {},
+      log: () => undefined,
+      installedOllamaVersion: "0.32.5",
+      runningOllamaVersion: "0.32.5",
+      deps,
+    });
+
+    expect(state.isWindowsHostOllama).toBe(false);
+    expect(state.ollamaInstallMenu.entry?.key).toBe("install-ollama");
+    expect(state.ollamaInstallMenu.hasUpgradableOllama).toBe(true);
+    expect(detectLocalTcpListener).not.toHaveBeenCalled();
+  });
+
   it("does not probe the Windows-host switch path when running Ollama already resolves to the Windows host", () => {
     const runCapture = vi.fn<DetectInferenceProviderHostStateDeps["runCapture"]>(() => "");
     const dockerCapture = vi.fn<DetectInferenceProviderHostStateDeps["dockerCapture"]>(() => "");
@@ -349,3 +446,24 @@ describe("detectInferenceProviderHostState", () => {
     expect(dockerCapture).not.toHaveBeenCalled();
   });
 });
+
+describe("detectLocalTcpListener", () => {
+  it("distinguishes Linux listeners from an empty procfs socket table (#9300)", () => {
+    const header = "  sl  local_address rem_address   st\n";
+    const listener = `${header}   0: 0100007F:2CAA 00000000:0000 0A\n`;
+
+    expect(detectLocalTcpListener(11434, () => listener)).toBe(true);
+    expect(detectLocalTcpListener(11434, () => header)).toBe(false);
+  });
+
+  it("fails closed when procfs is unavailable or malformed (#9300)", () => {
+    expect(detectLocalTcpListener(11434, () => null)).toBeNull();
+    expect(detectLocalTcpListener(11434, () => "header\nmalformed\n")).toBeNull();
+    expect(
+      detectLocalTcpListener(11434, (filePath) =>
+        filePath.endsWith("tcp") ? "  sl  local_address rem_address   st\n" : null,
+      ),
+    ).toBeNull();
+    expect(detectLocalTcpListener(0, () => "unused")).toBeNull();
+  });
+});