fix(inference): report a probe image-pull failure as its own diagnostic (#9311)

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

When the container reachability probe image was absent from the local
Docker cache and Docker could not pull it, onboarding reported the
failure as a provider networking problem: "the Docker container
reachability check failed for http://host.openshell.internal:11434" with
the lumped diagnostic "Docker command failed (image pull error or
runtime failure)". On WSL2 reached over a remote Windows OpenSSH
session, Docker Desktop's `desktop.exe` credential helper has no logon
session, blocks the pull of the public probe image, and hits exactly
this path. After this change that case is reported as a Docker
image-pull failure with the reporter-verified recovery, and networking
is not blamed for a check that never ran.

## Related Issue

Closes #9308

## Changes

- `src/lib/inference/local.ts`: when all reachability retries and both
diagnostic re-probes produce empty output, classify before reporting.
`classifyContainerRunFailure` uses data the existing stdout-only capture
seam already provides: `docker version` answers (daemon is up) while
`docker image inspect` finds no local copy of `curlimages/curl:8.10.1`
(the probe image was never available). In that case:
- The message states the check could not run and names the failure
class: "This is a Docker image-pull failure, not an Ollama networking
failure." (vLLM wording for `vllm-local`.)
- The diagnostic names the credential-helper cause (`credsStore` in
`~/.docker/config.json` failing in a remote login session) and prints
the recovery the reporter verified: `DOCKER_CONFIG=$(mktemp -d) docker
pull curlimages/curl:8.10.1` followed by `nemoclaw onboard --resume`.
- Every other failure keeps the existing messages: daemon not answering,
probe image present, partial diagnostic output, and the invalid-command
guard all report exactly as before.
- `src/lib/inference/local.test.ts`: three cases — image-pull
classification for `ollama-local` and `vllm-local` (message,
remediation, and absence of the networking misreport), and a
present-image case pinning the unchanged runtime-failure report.

## Design notes for reviewers

- **Classification never parses Docker error text.** Docker writes pull
progress to stderr on success and its error wording varies across
versions and platforms, so matching stderr signatures is fragile — the
daemon-answers + image-absent probe is stable across Docker Desktop,
rootless, and remote contexts, and it reuses the same injected
`RunCaptureFn` seam as every other probe in this file. No new
dependency-injection parameter, no stderr capture, and
`src/lib/inference/local.ts` gains no new imports (its fan-out is pinned
at exactly 21 in `ci/source-architecture-budget.json`).
- **The two extra `docker` invocations run only on the already-failed
path**, after three failed probe attempts and two empty diagnostic
re-probes. The success path is untouched.
- **The hard stop is retained deliberately.** The same broken credential
helper would block later sandbox image pulls, so warn-and-continue would
only defer the failure to a worse place. The printed pre-pull repairs
both. If maintainers prefer the warn-and-continue carveout that
`vllm-local.ts` and the auth-proxy path already use for host-responding
cases, that is a small follow-up.
- **Out of scope:** a pre-pull or image-presence gate before the probe
runs (an onboarding flow change), and capturing stderr in the retry loop
(any non-empty output would false-positive the health acceptor).

## Type of Change

- [x] Code change (feature, bug fix, or refactor)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [x] Docs not applicable — justification: no documentation quotes the
previous message or diagnostic (verified by repo-wide grep); the changed
text is a CLI error surface only.
- [x] 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:

Validation on `7d4f96ae63`:

- `npx vitest run src/lib/inference/local.test.ts` — 86 passed (3 new).
- `npx vitest run src/lib/actions/inference-set.test.ts
src/lib/onboard/inference-providers` — 46 passed (consumers of
`validateLocalProvider`).
- `npm run typecheck:cli` — clean.
- `npx oxlint` on both changed files — clean.
- `npm run test-size:check` — passed (`local.test.ts` is 1429 lines
against the 1500 budget).
- `npm run source-shape:check` — `source_shape_cases=0`.
- Changed-test-file `if` count unchanged (21 at head, 21 at base) — new
mocks dispatch on command content with ternaries.

| Case | Asserts |
|---|---|
| Daemon up, probe image absent (`ollama-local`) | image-pull message,
no networking misreport, `DOCKER_CONFIG` pre-pull + `onboard --resume`
remediation |
| Daemon up, probe image absent (`vllm-local`) | image-pull message with
vLLM wording |
| Daemon up, probe image present | unchanged "reachability check failed"
+ runtime-failure diagnostic |
| All probes empty, daemon not answering | covered by the existing
tests, unchanged |

## Documentation Writer Review

- [ ] Documentation writer subagent reviewed the completed changes
- Result: `no-docs-needed`
- Evidence: repo-wide grep shows no documentation references the changed
message or diagnostic text; `docs/inference/set-up-ollama.mdx` and the
WSL pages describe onboarding behavior at a level this change does not
alter.
- Agent: Claude Code

Signed-off-by: Dongni Yang <dongniy@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Improved local provider diagnostics when Docker probe images are
unavailable.
* Added clear image-pull guidance for missing Ollama and vLLM probe
images.
* Preserved existing container-runtime error details when the required
image is available but the runtime cannot be reached.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Dongni Yang <dongniy@nvidia.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Dongni-Yang

src/lib/inference/local-vllm-auth.test.ts

@@ -373,7 +373,9 @@ describe("managed vLLM authentication", () => {
       .filter((argv) => argv[0] === "docker");
 
     expect(result.ok).toBe(false);
-    expect(dockerCommands).toHaveLength(5);
+    // 3 reachability probes, 2 diagnostic re-probes, and the daemon probe of
+    // the image-pull classifier (#9308) — every one context-pinned.
+    expect(dockerCommands).toHaveLength(6);
     expect(
       dockerCommands.every((argv) => argv.slice(0, 3).join(" ") === "docker --context default"),
     ).toBe(true);

src/lib/inference/local.test.ts

@@ -299,6 +299,60 @@ describe("local inference helpers", () => {
     expect(result.diagnostic).toMatch(/Docker command failed/);
   });
 
+  it("reports an image-pull failure instead of an Ollama networking failure when Docker cannot provide the probe image (#9308)", () => {
+    const mockCapture = (cmd: readonly string[]) =>
+      cmd.includes("version")
+        ? "29.6.2"
+        : cmd.includes("inspect")
+          ? ""
+          : cmd.includes("run")
+            ? ""
+            : '{"models":[]}';
+    const noopSleep = () => {};
+    const result = validateLocalProvider("ollama-local", mockCapture, noopSleep);
+    expect(result.ok).toBe(false);
+    expect(result.message).toMatch(/Docker image-pull failure/);
+    expect(result.message).toMatch(/not an Ollama networking failure/);
+    expect(result.message).not.toMatch(/Docker container reachability check failed/);
+    expect(result.message).not.toMatch(/sandbox uses a different network path/);
+    expect(result.diagnostic).toMatch(/DOCKER_CONFIG=\$\(mktemp -d\) docker pull curlimages\/curl/);
+    expect(result.diagnostic).toMatch(/credential helper/);
+    expect(result.diagnostic).toMatch(/onboard --resume/);
+  });
+
+  it("reports an image-pull failure instead of a vLLM networking failure when Docker cannot provide the probe image (#9308)", () => {
+    const mockCapture = (cmd: readonly string[]) =>
+      cmd.includes("version")
+        ? "29.6.2"
+        : cmd.includes("inspect")
+          ? ""
+          : cmd.includes("run")
+            ? ""
+            : '{"data":[]}';
+    const noopSleep = () => {};
+    const result = validateLocalProvider("vllm-local", mockCapture, noopSleep);
+    expect(result.ok).toBe(false);
+    expect(result.message).toMatch(/Docker image-pull failure/);
+    expect(result.message).toMatch(/not a vLLM networking failure/);
+    expect(result.diagnostic).toMatch(/docker pull curlimages\/curl/);
+  });
+
+  it("keeps the runtime-failure report when the probe image is present locally (#9308)", () => {
+    const mockCapture = (cmd: readonly string[]) =>
+      cmd.includes("version")
+        ? "29.6.2"
+        : cmd.includes("inspect")
+          ? "sha256:0d9b7ef1"
+          : cmd.includes("run")
+            ? ""
+            : '{"models":[]}';
+    const noopSleep = () => {};
+    const result = validateLocalProvider("ollama-local", mockCapture, noopSleep);
+    expect(result.ok).toBe(false);
+    expect(result.message).toMatch(/Docker container reachability check failed/);
+    expect(result.diagnostic).toMatch(/image pull error or runtime failure/);
+  });
+
   it("succeeds after container check retry", () => {
     let callCount = 0;
     const mockCapture = () => {

src/lib/inference/local.ts

@@ -1165,28 +1165,51 @@ export function validateLocalProvider(
   // All retries exhausted — collect diagnostics
   const diagnostic = collectContainerDiagnostic(containerCommand, capture);
 
+  if (diagnostic.probeImageUnavailable) {
+    return probeImageUnavailableResult(provider, diagnostic.text);
+  }
+
   switch (provider) {
     case "vllm-local":
       return {
         ok: false,
         message: `Local vLLM is responding on the host, but the Docker container reachability check failed for ${getContainerCheckUrl(provider)}. This may be a Docker networking issue — the sandbox uses a different network path and may still work.`,
-        diagnostic,
+        diagnostic: diagnostic.text,
       };
     case "ollama-local":
       return {
         ok: false,
         message: `Local Ollama is responding on ${getResolvedOllamaHost()}, but the Docker container reachability check failed for http://host.openshell.internal:${getOllamaContainerPort()}. This may be a Docker networking issue — the sandbox uses a different network path and may still work.`,
-        diagnostic,
+        diagnostic: diagnostic.text,
       };
     default:
       return {
         ok: false,
         message: "The selected local inference provider is unavailable from containers.",
-        diagnostic,
+        diagnostic: diagnostic.text,
       };
   }
 }
 
+/**
+ * Report a reachability check that never ran because Docker could not
+ * provide the probe image (#9308). Blaming the provider's network path here
+ * is a misreport: the reporter's environment had a working path once the
+ * image existed.
+ */
+function probeImageUnavailableResult(provider: string, diagnostic: string): ValidationResult {
+  const responding =
+    provider === "vllm-local"
+      ? "Local vLLM is responding on the host"
+      : `Local Ollama is responding on ${getResolvedOllamaHost()}`;
+  const providerLabel = provider === "vllm-local" ? "a vLLM" : "an Ollama";
+  return {
+    ok: false,
+    message: `${responding}, but the container reachability check could not run because Docker could not provide its probe image. This is a Docker image-pull failure, not ${providerLabel} networking failure.`,
+    diagnostic,
+  };
+}
+
 function getContainerCheckUrl(provider: string): string | null {
   switch (provider) {
     case "vllm-local": {
@@ -1204,13 +1227,62 @@ function getContainerCheckUrl(provider: string): string | null {
   }
 }
 
-function collectContainerDiagnostic(containerCommand: string[], capture: RunCaptureFn): string {
+type ContainerDiagnostic = { text: string; probeImageUnavailable: boolean };
+
+function containerRuntimeFailureDiagnostic(text: string): ContainerDiagnostic {
+  return { text, probeImageUnavailable: false };
+}
+
+/**
+ * Distinguish "Docker could not provide the probe image" from a general
+ * runtime failure using the stdout-only capture seam: the daemon answers
+ * `docker version` while `docker image inspect` finds no local copy of the
+ * probe image. Credential-helper failures land here (#9308) — a remote login
+ * session can lose access to Docker Desktop's credential store, so the pull
+ * fails and every probe run produces empty stdout.
+ *
+ * Image-absent-after-run-attempts proves the pull failed: `docker run` pulls
+ * an absent image before it creates the container, and `--add-host`, policy,
+ * and seccomp failures all happen after that pull. Five runs precede this
+ * check (three probes, two diagnostics), so a pullable image would be in the
+ * cache by now and a run that failed for any post-pull reason keeps the
+ * generic runtime diagnostic.
+ */
+function classifyContainerRunFailure(
+  dockerCommand: string[],
+  capture: RunCaptureFn,
+): ContainerDiagnostic {
+  const runtimeFailure = containerRuntimeFailureDiagnostic(
+    `Docker command failed (image pull error or runtime failure). Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times.`,
+  );
+  const daemonVersion = capture(
+    [...dockerCommand, "version", "--format", "{{.Server.Version}}"],
+    { ignoreError: true },
+  );
+  if (!daemonVersion) return runtimeFailure;
+  const probeImageId = capture(
+    [...dockerCommand, "image", "inspect", "--format", "{{.Id}}", CONTAINER_REACHABILITY_IMAGE],
+    { ignoreError: true },
+  );
+  if (probeImageId) return runtimeFailure;
+  return {
+    text: `The probe image ${CONTAINER_REACHABILITY_IMAGE} is not in the local Docker image cache, and Docker could not pull it. The image is public and needs no credentials, but a Docker credential helper (credsStore in ~/.docker/config.json) can fail in a remote login session and block every pull. Pre-pull the image with an isolated Docker config, then resume: DOCKER_CONFIG=$(mktemp -d) docker pull ${CONTAINER_REACHABILITY_IMAGE} && nemoclaw onboard --resume`,
+    probeImageUnavailable: true,
+  };
+}
+
+function collectContainerDiagnostic(
+  containerCommand: string[],
+  capture: RunCaptureFn,
+): ContainerDiagnostic {
   const url = containerCommand.at(-1);
   const dockerRunIndex = containerCommand.indexOf("run");
   const addHostIndex = containerCommand.indexOf("--add-host");
   const hostAlias = containerCommand[addHostIndex + 1];
   if (!url || dockerRunIndex < 1 || addHostIndex < 0 || !hostAlias) {
-    return `Docker command failed (invalid reachability command). Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times.`;
+    return containerRuntimeFailureDiagnostic(
+      `Docker command failed (invalid reachability command). Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times.`,
+    );
   }
   const dockerCommand = containerCommand.slice(0, dockerRunIndex);
   try {
@@ -1253,7 +1325,7 @@ function collectContainerDiagnostic(containerCommand: string[], capture: RunCapt
     );
 
     if (!httpStatus && !hostsOutput) {
-      return `Docker command failed (image pull error or runtime failure). Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times.`;
+      return classifyContainerRunFailure(dockerCommand, capture);
     }
 
     const parts: string[] = [];
@@ -1271,9 +1343,11 @@ function collectContainerDiagnostic(containerCommand: string[], capture: RunCapt
     parts.push(
       `Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times over ~${(CONTAINER_CHECK_MAX_ATTEMPTS - 1) * CONTAINER_CHECK_RETRY_DELAY_SECS}s`,
     );
-    return parts.join(". ") + ".";
+    return containerRuntimeFailureDiagnostic(parts.join(". ") + ".");
   } catch {
-    return `Docker command failed (image pull error or runtime failure). Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times.`;
+    return containerRuntimeFailureDiagnostic(
+      `Docker command failed (image pull error or runtime failure). Retried ${CONTAINER_CHECK_MAX_ATTEMPTS} times.`,
+    );
   }
 }