fix(onboard): offer Ollama upgrade when host version too old

docs/inference/use-local-inference.mdx

@@ -31,6 +31,12 @@ The onboard wizard detects Ollama automatically when it is installed or running
 
 If Ollama is installed but not running, NemoClaw starts it for you.
 On macOS and Linux, the wizard can also offer to install Ollama when it is not present.
+When the host Ollama is below the minimum version NemoClaw expects for its starter models (currently `0.7.0`), the wizard surfaces an explicit **Upgrade Ollama** entry in the provider menu instead of silently reusing the older daemon, and the express setup path resolves to that entry.
+The wizard inspects both the CLI binary (`ollama --version`) and the locally running daemon (`/api/version` on `:11434`) so the upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon.
+The gate skips Windows-host Ollama reached from WSL via `host.docker.internal`; the separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side.
+The wizard then runs the platform's install/upgrade path: `brew upgrade ollama` on macOS, the official `https://ollama.com/install.sh` on Linux.
+Upgrades on Linux always take the sudo-driven system path because the sudo-free user-local fallback would leave the existing system daemon on `:11434` serving the stale binary; if sudo is not available in a non-interactive run, NemoClaw refuses to silently downgrade the path and asks you to rerun interactively or upgrade Ollama manually.
+After an upgrade finishes, NemoClaw re-probes the running daemon's `/api/version` and fails the run if the daemon still reports below the minimum. Fresh installs skip this re-probe because the bundled installers ship a daemon at or above the minimum.
 On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop.
 
 #### Linux Install Modes

docs/reference/commands.mdx

@@ -1256,7 +1256,7 @@ Set them before running `nemoclaw onboard`.
 | `NEMOCLAW_REASONING` | `true` or `false` | Overrides the model's reasoning-mode flag in the built OpenClaw config. |
 | `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | duration with `s`, `m`, or `h` suffix (for example `30m`, `1h`, or `0m`) | Overrides `agents.defaults.heartbeat.every` in the built OpenClaw config. Set `0m` to disable periodic agent turns. |
 | `NEMOCLAW_OLLAMA_REQUIRE_TOOLS` | `0` to disable, anything else to keep the default | When set to `0`, skips the Ollama tool-calling capability check during local-inference onboarding. |
-| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location. `system` runs the official `https://ollama.com/install.sh` (sudo, writes to `/usr/local`, configures systemd). `user` extracts the release tarball to `${HOME}/.local` without sudo and launches the daemon manually (no systemd; manual restart after reboot). Empty/unset auto-detects: root or passwordless `sudo` selects `system`; a non-interactive run without passwordless `sudo` selects `user`; an interactive shell falls back to `system` so the official installer can prompt for the password. Any other value is rejected. |
+| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location. `system` runs the official `https://ollama.com/install.sh` (sudo, writes to `/usr/local`, configures systemd). `user` extracts the release tarball to `${HOME}/.local` without sudo and launches the daemon manually (no systemd; manual restart after reboot). Empty/unset auto-detects: root or passwordless `sudo` selects `system`; a non-interactive run without passwordless `sudo` selects `user`; an interactive shell falls back to `system` so the official installer can prompt for the password. Any other value is rejected. On the upgrade path the helper rejects `user` because a user-local install cannot replace the system daemon on `:11434`, and it also rejects `system` under `NEMOCLAW_NON_INTERACTIVE=1` when passwordless `sudo` is unavailable (the installer would hang on a hidden sudo prompt); the run exits with an actionable diagnostic instead. |
 | `NEMOCLAW_PROXY_HOST` | hostname or IP | Overrides the sandbox-side outbound HTTP proxy host. Defaults to `10.200.0.1`. |
 | `NEMOCLAW_PROXY_PORT` | integer port | Overrides the sandbox-side outbound HTTP proxy port. Defaults to `3128`. |
 | `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). |

src/lib/inference/local.ts

@@ -78,6 +78,13 @@ export const QWEN3_6_OLLAMA_MODEL = assertRegistryTag("qwen3.6:35b");
 
 export type RunCaptureFn = (cmd: string | string[], opts?: { ignoreError?: boolean }) => string;
 
+export {
+  getInstalledOllamaVersion,
+  getRunningOllamaDaemonVersion,
+  isOllamaVersionAtLeast,
+  MIN_OLLAMA_VERSION,
+} from "./ollama-version";
+
 export type RunCaptureExFn = (cmd: string[]) => CaptureResult;
 
 // Hosts that the WSL-side onboard CLI tries when probing Ollama. Native Linux

src/lib/inference/ollama-version.test.ts

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import {
+  getInstalledOllamaVersion,
+  getRunningOllamaDaemonVersion,
+  isOllamaVersionAtLeast,
+  MIN_OLLAMA_VERSION,
+} from "../../../dist/lib/inference/ollama-version";
+
+describe("Ollama version detection", () => {
+  it("parses 'ollama version is X.Y.Z' output", () => {
+    const capture = () => "ollama version is 0.6.2";
+    expect(getInstalledOllamaVersion(capture)).toBe("0.6.2");
+  });
+
+  it("returns null when ollama --version produces no output", () => {
+    const capture = () => "";
+    expect(getInstalledOllamaVersion(capture)).toBeNull();
+  });
+
+  it("returns null when ollama --version output has no version", () => {
+    const capture = () => "ollama: command not found";
+    expect(getInstalledOllamaVersion(capture)).toBeNull();
+  });
+
+  it("treats null/missing versions as below the minimum", () => {
+    expect(isOllamaVersionAtLeast(null, MIN_OLLAMA_VERSION)).toBe(false);
+  });
+
+  it("treats 0.6.2 as below the 0.7.0 floor", () => {
+    expect(isOllamaVersionAtLeast("0.6.2", "0.7.0")).toBe(false);
+  });
+
+  it("treats 0.7.0 as meeting the 0.7.0 floor", () => {
+    expect(isOllamaVersionAtLeast("0.7.0", "0.7.0")).toBe(true);
+  });
+
+  it("treats 0.24.0 as above the 0.7.0 floor", () => {
+    expect(isOllamaVersionAtLeast("0.24.0", "0.7.0")).toBe(true);
+  });
+
+  it("treats 1.0.0 as above the 0.7.0 floor", () => {
+    expect(isOllamaVersionAtLeast("1.0.0", "0.7.0")).toBe(true);
+  });
+
+  it("returns false for unparseable version components", () => {
+    expect(isOllamaVersionAtLeast("not-a-version", "0.7.0")).toBe(false);
+  });
+
+  it("reads the running daemon version from /api/version", () => {
+    const capture = () => '{"version":"0.24.0"}';
+    expect(getRunningOllamaDaemonVersion(capture)).toBe("0.24.0");
+  });
+
+  it("returns null when the daemon endpoint is unreachable", () => {
+    const capture = () => "";
+    expect(getRunningOllamaDaemonVersion(capture)).toBeNull();
+  });
+
+  it("returns null when the daemon payload is not JSON", () => {
+    const capture = () => "ollama is running";
+    expect(getRunningOllamaDaemonVersion(capture)).toBeNull();
+  });
+
+  it("returns null when the daemon payload omits a version field", () => {
+    const capture = () => '{"status":"ok"}';
+    expect(getRunningOllamaDaemonVersion(capture)).toBeNull();
+  });
+});

src/lib/inference/ollama-version.ts

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Ollama version detection helpers. Kept separate from the larger
+ * `inference/local.ts` so the version-floor logic can evolve without
+ * dragging the rest of the local-inference helpers along.
+ */
+
+const { runCapture } = require("../runner");
+import { OLLAMA_PORT } from "../core/ports";
+
+export type OllamaVersionRunCapture = (
+  cmd: readonly string[],
+  opts?: { ignoreError?: boolean },
+) => string;
+
+/**
+ * Minimum Ollama version NemoClaw expects when reusing an existing host
+ * Ollama. Older Ollama runners crash loading newer starter models because
+ * their GGUF parsers predate the model format. Bump this when starter-model
+ * recipes adopt a newer GGUF feature.
+ */
+export const MIN_OLLAMA_VERSION = "0.7.0";
+
+export function getInstalledOllamaVersion(
+  runCaptureImpl?: OllamaVersionRunCapture,
+): string | null {
+  const capture = runCaptureImpl ?? runCapture;
+  const out = capture(["ollama", "--version"], { ignoreError: true });
+  if (!out) return null;
+  const match = out.match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match[0] : null;
+}
+
+/**
+ * Probe the running Ollama daemon's version via `/api/version`. This is
+ * the version NemoClaw will actually drive for inference — the CLI binary
+ * on `PATH` may be newer than the daemon that still owns `:11434` (for
+ * example after a user-local install while the original systemd unit is
+ * still running). Returns `null` when the daemon is unreachable or the
+ * response payload is not parseable.
+ */
+export function getRunningOllamaDaemonVersion(
+  runCaptureImpl?: OllamaVersionRunCapture,
+  endpoint: string = `http://127.0.0.1:${OLLAMA_PORT}/api/version`,
+): string | null {
+  const capture = runCaptureImpl ?? runCapture;
+  const out = capture(
+    [
+      "curl",
+      "-sf",
+      "--connect-timeout",
+      "2",
+      "--max-time",
+      "5",
+      endpoint,
+    ],
+    { ignoreError: true },
+  );
+  if (!out) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(out);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const raw = (parsed as { version?: unknown }).version;
+  if (typeof raw !== "string") return null;
+  const match = raw.match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match[0] : null;
+}
+
+export function isOllamaVersionAtLeast(
+  version: string | null,
+  minimum: string,
+): boolean {
+  if (!version) return false;
+  const parts = version.split(".").map((v) => Number.parseInt(v, 10));
+  const min = minimum.split(".").map((v) => Number.parseInt(v, 10));
+  const len = Math.max(parts.length, min.length);
+  for (let i = 0; i < len; i += 1) {
+    const a = parts[i] ?? 0;
+    const b = min[i] ?? 0;
+    if (Number.isNaN(a) || Number.isNaN(b)) return false;
+    if (a > b) return true;
+    if (a < b) return false;
+  }
+  return true;
+}

src/lib/onboard.ts

@@ -105,6 +105,9 @@ const {
 const {
   installOllamaOnLinux,
 }: typeof import("./onboard/install-ollama-linux") = require("./onboard/install-ollama-linux");
+const {
+  installOllamaOnMacOS,
+}: typeof import("./onboard/install-ollama-macos") = require("./onboard/install-ollama-macos");
 const crypto = require("node:crypto");
 const fs = require("fs");
 const os = require("os");
@@ -183,6 +186,9 @@ const {
   validateOllamaModel,
   validateLocalProvider,
 } = localInference;
+const { resolveOllamaInstallMenuEntry, assertOllamaUpgradeApplied } = require(
+  "./onboard/ollama-install-menu",
+);
 const {
   ensureOllamaAuthProxy,
   getOllamaProxyToken,
@@ -4219,7 +4225,10 @@ async function selectAndValidateOllamaModel(
       },
     );
     if (validation.retry === "selection") return { outcome: "back-to-selection" };
-    if (!validation.ok) continue;
+    if (!validation.ok) {
+      if (isNonInteractive()) process.exit(1);
+      continue;
+    }
     // Ollama's /v1/responses endpoint does not produce correctly formatted
     // tool calls — force chat completions like vLLM/NIM.
     if (validation.api !== "openai-completions") {
@@ -4375,19 +4384,15 @@ async function setupNim(
       label: "Install Ollama on Windows host (recommended)",
     });
   }
-  // Without any Ollama, offer to install one locally as a fallback (e.g. when
-  // the NVIDIA API server is down and cloud keys are unavailable).
-  if (!hasOllama && !ollamaRunning && !hasWindowsOllama) {
-    if (process.platform === "darwin") {
-      options.push({ key: "install-ollama", label: "Install Ollama (macOS)" });
-    } else if (process.platform === "linux") {
-      if (isWsl()) {
-        options.push({ key: "install-ollama", label: "Install Ollama (WSL Linux)" });
-      } else {
-        options.push({ key: "install-ollama", label: "Install Ollama (Linux)" });
-      }
-    }
-  }
+  const ollamaInstallMenu = resolveOllamaInstallMenuEntry({
+    hasOllama,
+    ollamaRunning,
+    hasWindowsOllama,
+    ollamaHost,
+    platform: process.platform,
+    isWsl: isWsl(),
+  });
+  if (ollamaInstallMenu.entry) options.push(ollamaInstallMenu.entry);
 
   // Model Router: complexity-based routing via blueprint config.
   const blueprintRouterCfg = loadBlueprintProfile("routed");
@@ -5265,26 +5270,19 @@ async function setupNim(
         break;
       } else if (selected.key === "install-ollama") {
         if (!checkOllamaPortsOrWarn()) continue selectionLoop;
-        if (process.platform === "darwin") {
-          console.log("  Installing Ollama via Homebrew...");
-          run(["brew", "install", "ollama"], { ignoreError: true });
-          // brew install doesn't auto-start a service; launch directly.
-          // Shell required: backgrounding (&), env var prefix, output redirection.
-          console.log("  Starting Ollama...");
-          runShell(`OLLAMA_HOST=127.0.0.1:${OLLAMA_PORT} ollama serve > /dev/null 2>&1 &`, {
-            ignoreError: true,
-          });
-          if (!waitForHttp(`http://127.0.0.1:${OLLAMA_PORT}/`, 10)) {
-            console.error(`  Ollama did not become ready on :${OLLAMA_PORT} within timeout.`);
-            if (isNonInteractive()) process.exit(1);
-            continue selectionLoop;
-          }
-        } else {
-          const installResult = installOllamaOnLinux({ isNonInteractive });
-          if (!installResult.ok) {
-            if (isNonInteractive()) process.exit(1);
-            continue selectionLoop;
-          }
+        const isUpgrade = ollamaInstallMenu.hasUpgradableOllama;
+        const installResult = process.platform === "darwin"
+          ? installOllamaOnMacOS({ isNonInteractive, isUpgrade })
+          : installOllamaOnLinux({ isNonInteractive, isUpgrade });
+        if (!installResult.ok) {
+          if (isNonInteractive()) process.exit(1);
+          continue selectionLoop;
+        }
+        const upgradeCheck = assertOllamaUpgradeApplied(ollamaInstallMenu);
+        if (!upgradeCheck.ok) {
+          console.error(`  ${upgradeCheck.message}`);
+          if (isNonInteractive()) process.exit(1);
+          continue selectionLoop;
         }
         if (shouldFrontOllamaWithProxy()) {
           if (!startOllamaAuthProxy()) process.exit(1);