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

[Dongni-Yang]

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

• Code change (feature, bug fix, or refactor)

Quality Gates

• Tests added or updated for changed behavior
• 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.
• 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

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.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

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: 1b93d8bc-a4c5-4261-8d5c-5e359f597888

📥 Commits

Reviewing files that changed from the base of the PR and between 7d4f96a and d217363.

📒 Files selected for processing (1)

• src/lib/inference/local.ts

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

• src/lib/inference/local.ts

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

---

📝 Walkthrough

Walkthrough

Local provider validation now distinguishes unavailable Docker probe images from container runtime failures. Docker diagnostics return structured results, and regression tests cover Ollama, vLLM, and locally available probe images.

Changes

Local provider diagnostics

Layer / File(s)	Summary
Structured Docker failure classification src/lib/inference/local.ts	Docker diagnostic collection returns structured results and classifies daemon, image-cache, credential-helper, command, normal, and exceptional failures.
Provider validation and regression coverage src/lib/inference/local.ts, src/lib/inference/local.test.ts	validateLocalProvider reports unavailable probe images as image-pull failures. Tests cover Ollama, vLLM, and runtime failures when the probe image is available.

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

Merge Risk: ⚪ Minimal · up to d2173

The change provides a more accurate Docker image-pull diagnostic while preserving existing behavior for other failures; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant validateLocalProvider
  participant collectContainerDiagnostics
  participant Docker
  validateLocalProvider->>collectContainerDiagnostics: request probe diagnostics
  collectContainerDiagnostics->>Docker: check daemon and probe image
  Docker-->>collectContainerDiagnostics: image availability or runtime result
  collectContainerDiagnostics-->>validateLocalProvider: return structured diagnostic

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: reporting probe image-pull failures as a distinct diagnostic.
Linked Issues check	✅ Passed	The changes classify missing probe images correctly and provide actionable remediation for the credential-helper failure described in issue #9308.
Out of Scope Changes check	✅ Passed	The code and tests remain within the linked issue scope of Docker probe image-pull diagnostics and regression coverage.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/9308-pull-failure-classification

---

_{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 9cbe46e in the fix/9308-pull-failur... branch remains at 96%, unchanged from commit 8cdc3c4 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 9cbe46e in the fix/9308-pull-failur... branch remains at 83%, unchanged from commit 8cdc3c4 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 8cdc3c4	fix/9308-pull-failur... 9cbe46e	+/-
src/lib/onboard...nt-authority.ts	79%	75%	-4%
src/lib/onboard...ce-lifecycle.ts	93%	89%	-4%
src/lib/inference/local.ts	82%	81%	-1%
src/lib/adapter...ateway-drift.ts	60%	61%	+1%
src/lib/state/p...l-retirement.ts	84%	86%	+2%
src/lib/actions...me-preflight.ts	84%	86%	+2%
src/lib/onboard...file-builder.ts	91%	95%	+4%
src/lib/actions...aged-profile.ts	84%	88%	+4%
src/lib/actions...er-lifecycle.ts	85%	94%	+9%
src/lib/actions...ld-mcp-phase.ts	87%	98%	+11%

---

_{Updated August 17, 2026 15:44 UTC}

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

3 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• image-pull failure at src/lib/inference/local.ts:1207: primary classified it as established; the second opinion classified it as justified.
• runtime-failure at src/lib/inference/local.ts:1237: selected only by the second-opinion lane as established.
• probe image at src/lib/inference/local.ts:1195: selected only by the second-opinion lane as established.

1 additional E2E selection from the second opinion

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

• ollama-auth-proxy: 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.

4 semantic terminology decisions

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

• established — probe image at src/lib/inference/local.ts:1207: Retain `probe image` for the image used by the reachability probe.
• established — image-pull failure at src/lib/inference/local.ts:1207: Retain `Docker image-pull failure` for this diagnostic classification.
• justified — credential helper at src/lib/inference/local.ts:1268: Retain the `Docker` modifier to identify the Docker credential-store component.
• established — runtime failure at src/lib/inference/local.ts:1255: Retain `runtime failure` for the generic remaining Docker execution classification.

E2E guidance

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

Recommended E2E: inference-routing

Manual-only E2E: 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.

[Dongni-Yang]

Advisor warning PRA-1 — rebuttal, with the invariant now recorded in code (d21736325d)

The warning's scenario — a runtime, policy, or host-mapping failure receiving the image-pull diagnosis — cannot reach the classifier's positive branch, because of an ordering invariant in docker run itself:

1. docker run pulls an absent image before it creates the container. --add-host validation, network policy, and seccomp failures all happen at create or start, after the pull completes.
2. Five docker run invocations precede the docker image inspect check: three reachability probes and two diagnostic re-probes.
3. Therefore, if the image were pullable, at least the first run would have pulled it, and inspect would find it in the cache — the classifier then keeps the generic runtime diagnostic (pinned by the present-image test).
4. inspect finding no image after five run attempts proves the pull was attempted and did not complete. That is exactly what the message asserts: "Docker could not pull it."

The diagnostic also does not over-assert the cause: the credential helper is named as a possible blocker ("can fail in a remote login session"), and the printed recovery — pre-pull with an isolated Docker config — is the correct next step for any pull failure. If the pre-pull also fails, its own error output names the real cause (network, disk, registry), which is more evidence than onboarding could relay.

The suggested test ("non-pull failure with the image absent") describes a state the invariant makes unreachable, so it would pin an impossible input; the reachable neighbor — run fails post-pull, image present — is already covered by the keeps the runtime-failure report when the probe image is present locally case.

Commit d21736325d records this invariant in the classifier's doc comment so it does not need re-deriving in review.

[prekshivyas]

The diagnostic cleanly distinguishes a missing probe image from provider-network failure without parsing unstable Docker stderr. It preserves generic runtime failure behavior when the daemon is unavailable or the image exists, keeps the selected Docker context on every probe, and provides a targeted recovery. Tests cover Ollama, vLLM, the present-image fallback, and context pinning.

Cross-issue sweep: no additional candidate issues found.

Security review: secrets/credentials — PASS; input validation/sanitization — PASS; authentication/authorization — PASS; dependencies — PASS; error handling/logging — PASS; cryptography/data protection — PASS; configuration/security headers — PASS; security testing — PASS; system security — PASS.