fix(cli): preserve healthy Docker authority (#8823)

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

NemoClaw now preserves a reachable Docker CLI default, including a
custom `DOCKER_CONFIG`, when `DOCKER_HOST` is unset instead of replacing
it with the first existing socket.
If the default is unreachable, the CLI probes only its bounded
local-socket candidates and selects a fallback only when server-version
evidence identifies one runtime.

## Related Issue

Fixes #8816

## Changes

- Preserve an explicit `DOCKER_HOST` without probing or replacing its
authority.
- Probe the Docker CLI default before local fallbacks so a reachable
Docker Engine remains selected when Docker and Podman sockets coexist.
- Validate each allowlisted fallback for reachability and Docker or
Podman identity. Mixed or unknown fallback identities produce no
automatic override.
- Reuse the existing Docker-compatible server-version classifier from
host preflight instead of creating a second runtime identity rule.
- Preserve a reachable configured `DOCKER_CONTEXT` and its
`DOCKER_CONFIG` directory for Docker commands, and clear the context
only when a verified socket fallback must take precedence.
- Add regression coverage for explicit endpoints, coexistence,
Podman-only hosts, stale sockets, mixed runtimes, unknown engines, and
probe environment filtering.
- Update the system-readiness reference with the default and fallback
authority order.

## 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] Docs updated for user-facing behavior changes
- [ ] Docs 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: Maintainer review
covered endpoint validation, credential filtering, failure handling, and
runtime authority. The read-only default probe and Docker runner
preserve `DOCKER_CONTEXT` and its `DOCKER_CONFIG` path; fallback probes
and host overrides omit both; selecting a verified fallback clears the
conflicting context; and non-Docker commands receive neither value.
Regression coverage confirms `NVIDIA_INFERENCE_API_KEY` remains filtered
at both boundaries. The maintainer explicitly approved this Docker-only
configuration boundary.
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Documentation Writer Review

- [x] Documentation writer subagent reviewed the completed changes
- Result: `docs-updated`
- Evidence: `docs/reference/system-readiness.mdx` documents Docker
default-authority selection with `DOCKER_CONTEXT` and `DOCKER_CONFIG`,
verified local socket fallback, and conflicting context removal.
- Agent: Codex Desktop
<!-- docs-review-head-sha: 982a17d -->
<!-- docs-review-agents-blob-sha: c4923a3 -->

## DGX Station Hardware Evidence

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

## 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 — command/result or justification: 10
focused regression and security files passed 308 tests on the refreshed
head; CLI and plugin builds and type checks passed; the full pre-commit,
commit-message, and pre-push sequence passed against `upstream/main`.
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result: Not required for this
focused CLI change.
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [x] `npm run docs` builds without warnings (doc changes only) —
result: the build passed; Fern reported two baseline warnings that it
suppresses unless run with `--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>


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

* **Enhancements**
* Improved Docker runtime detection using configured hosts, Docker CLI
defaults, and eligible local sockets.
* Verifies runtime identity before selecting an endpoint, distinguishing
Docker from Podman and rejecting unknown or conflicting results.
* Improved readiness and profile selection when multiple container
runtimes are available.
* Applies Docker context settings appropriately, clearing them for
selected socket fallbacks while preserving explicit configurations.

* **Documentation**
* Updated system readiness guidance to explain Docker fallback detection
and runtime compatibility behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Co-authored-by: Senthil Ravichandran <senthilr@nvidia.com>

Author: prekshivyas

docs/reference/system-readiness.mdx

@@ -97,10 +97,14 @@ Do not use `observedAt` as build identity.
 
 ## Interpret Docker storage
 
-The report rejects an unsupported `DOCKER_HOST` before it uses Docker daemon evidence.
+The report rejects an unsupported explicit `DOCKER_HOST` before it uses Docker daemon evidence.
 `host.docker.host_invalid` records whether the configured endpoint is invalid, `host.docker.endpoint_supported` is absent when a configured endpoint is not an absolute local `unix://` socket, and the blocking `host.docker.host_invalid` finding identifies that condition.
 TCP, SSH, relative Unix socket, and unsafe path values do not fall back to the default Docker socket.
-Unset `DOCKER_HOST` continues to use Docker's default local socket.
+When `DOCKER_HOST` is unset, NemoClaw first probes the Docker CLI's selected authority, including `DOCKER_CONTEXT` and its `DOCKER_CONFIG` directory when set, without a host override.
+If that authority is unreachable, NemoClaw probes a bounded set of local Unix sockets and accepts only an endpoint with valid server-version evidence.
+When it selects a fallback socket, NemoClaw clears the unreachable `DOCKER_CONTEXT` so later Docker commands use the selected `DOCKER_HOST`.
+A mixed set of reachable Docker and Podman fallbacks, or a fallback with an unknown server identity, produces no automatic `DOCKER_HOST` override.
+A reachable Podman endpoint remains classified as Podman and does not satisfy the standard Docker runtime requirement.
 
 The Docker storage capabilities separate the current host configuration from NemoClaw's supported remediation path.
 

src/lib/onboard/preflight.ts

@@ -19,6 +19,7 @@ import { ADVISORY_CHECKS } from "../advisories/registry";
 import { runAdvisories } from "../advisories/runner";
 import { DASHBOARD_PORT } from "../core/ports";
 import { isDockerDaemonReachable, isSupportedGatewayDockerHost } from "../domain/docker-host";
+import { classifyDockerVersionIdentity } from "../platform";
 import { resolveOpenshell } from "../readiness/openshell-resolver";
 import {
   MIN_RECOMMENDED_DOCKER_CPUS,
@@ -241,59 +242,6 @@ function inferContainerRuntime(info = ""): ContainerRuntime {
   return "unknown";
 }
 
-type DockerVersionIdentity = "docker" | "podman" | "unknown";
-
-/**
- * Classify the engine identity from the explicit
- * `docker version --format '{{json .}}'` banner.
- *
- * Podman's docker-compat `/info` endpoint mimics Docker so closely that
- * `docker info` carries no "podman" marker (observed on Apple Silicon macOS:
- * `ServerVersion: "5.6.2"`, `OperatingSystem: "fedora"`, no "podman"
- * substring), so `inferContainerRuntime` misclassifies it as plain Docker.
- * The docker-compat `/version` payload still names the engine: a
- * `Server.Components[].Name` of "Podman Engine" and a `Server.Platform.Name`
- * like "linux/arm64/fedora-42". Real Docker reports
- * `Server.Platform.Name: "Docker Engine - Community"` and components
- * `Engine`/`containerd`/`runc`, which provide positive Docker identity on
- * Docker Engine, Docker Desktop, and Colima (#7320).
- */
-function classifyDockerVersionIdentity(versionOutput = ""): DockerVersionIdentity {
-  const text = String(versionOutput || "").trim();
-  if (!text) return "unknown";
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    // Plain-text `docker version` still prints the "Podman Engine" server banner.
-    if (/podman/i.test(text)) return "podman";
-    return /docker engine/i.test(text) ? "docker" : "unknown";
-  }
-  const server = (parsed as Record<string, unknown> | null)?.Server;
-  if (!server || typeof server !== "object") return "unknown";
-  const s = server as Record<string, unknown>;
-  const platformName = (s.Platform as Record<string, unknown> | undefined)?.Name;
-  if (typeof platformName === "string" && /podman/i.test(platformName)) return "podman";
-  const components = s.Components;
-  const componentNames = Array.isArray(components)
-    ? components.flatMap((component) => {
-        const name =
-          component && typeof component === "object"
-            ? (component as Record<string, unknown>).Name
-            : undefined;
-        return typeof name === "string" ? [name] : [];
-      })
-    : [];
-  if (componentNames.some((name) => /podman/i.test(name))) return "podman";
-  if (
-    (typeof platformName === "string" && /^docker (?:engine|desktop)\b/i.test(platformName)) ||
-    componentNames.some((name) => name.trim().toLowerCase() === "engine")
-  ) {
-    return "docker";
-  }
-  return "unknown";
-}
-
 /**
  * Use `ProductLicense: "Apache-2.0"` as a Podman backstop only when the
  * authoritative `docker version` probe is unavailable. Podman's docker-compat

src/lib/platform.ts

@@ -5,6 +5,8 @@ import { existsSync as defaultExistsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { dockerSpawnSync } from "./adapters/docker/exec";
+
 export type ContainerRuntime = "podman" | "colima" | "docker-desktop" | "docker" | "unknown";
 
 export interface PlatformLookupOptions {
@@ -24,6 +26,7 @@ export interface WslDetectionOptions {
 export interface DockerHostDetectionOptions extends PlatformLookupOptions, WslDetectionOptions {
   env?: NodeJS.ProcessEnv;
   existsSync?: (filePath: string) => boolean;
+  probeDockerHost?: DockerHostProbe;
 }
 
 export interface DockerHostDetection {
@@ -32,6 +35,19 @@ export interface DockerHostDetection {
   socketPath: string | null;
 }
 
+export type DockerVersionIdentity = "docker" | "podman" | "unknown";
+
+export interface DockerHostProbeResult {
+  reachable: boolean;
+  identity: DockerVersionIdentity;
+}
+
+export type DockerHostProbe = (dockerHost: string | undefined) => DockerHostProbeResult;
+
+const DOCKER_PROBE_TIMEOUT_MS = 3_000;
+const DOCKER_PROBE_MAX_BUFFER_BYTES = 1024 * 1024;
+const DOCKER_PROBE_ENV_NAMES = ["HOME", "USER", "LOGNAME", "PATH"] as const;
+
 function isWsl(opts: WslDetectionOptions = {}): boolean {
   // Explicit override — lets tests pin behavior regardless of the host kernel.
   // Useful because the WSL detection below consults `os.release()`, which
@@ -65,6 +81,85 @@ function inferContainerRuntime(info = ""): ContainerRuntime {
   return "unknown";
 }
 
+/**
+ * Classify the engine identity from the explicit
+ * `docker version --format '{{json .}}'` banner.
+ *
+ * Podman's Docker-compatible `/info` endpoint does not always name Podman.
+ * The `/version` payload retains a `Podman Engine` component. Docker Engine,
+ * Docker Desktop, and Colima retain a Docker platform or engine component.
+ */
+function classifyDockerVersionIdentity(versionOutput = ""): DockerVersionIdentity {
+  const text = String(versionOutput || "").trim();
+  if (!text) return "unknown";
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    if (/podman/i.test(text)) return "podman";
+    return /docker engine/i.test(text) ? "docker" : "unknown";
+  }
+  const server = (parsed as Record<string, unknown> | null)?.Server;
+  if (!server || typeof server !== "object") return "unknown";
+  const serverRecord = server as Record<string, unknown>;
+  const platformName = (serverRecord.Platform as Record<string, unknown> | undefined)?.Name;
+  if (typeof platformName === "string" && /podman/i.test(platformName)) return "podman";
+  const components = serverRecord.Components;
+  const componentNames = Array.isArray(components)
+    ? components.flatMap((component) => {
+        const name =
+          component && typeof component === "object"
+            ? (component as Record<string, unknown>).Name
+            : undefined;
+        return typeof name === "string" ? [name] : [];
+      })
+    : [];
+  if (componentNames.some((name) => /podman/i.test(name))) return "podman";
+  if (
+    (typeof platformName === "string" && /^docker (?:engine|desktop)\b/i.test(platformName)) ||
+    componentNames.some((name) => name.trim().toLowerCase() === "engine")
+  ) {
+    return "docker";
+  }
+  return "unknown";
+}
+
+function buildDockerProbeEnv(
+  source: NodeJS.ProcessEnv,
+  dockerHost: string | undefined,
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const name of DOCKER_PROBE_ENV_NAMES) {
+    const value = source[name];
+    if (value !== undefined) env[name] = value;
+  }
+  if (dockerHost === undefined) {
+    if (source.DOCKER_CONFIG !== undefined) env.DOCKER_CONFIG = source.DOCKER_CONFIG;
+    if (source.DOCKER_CONTEXT !== undefined) env.DOCKER_CONTEXT = source.DOCKER_CONTEXT;
+  }
+  if (dockerHost) {
+    env.DOCKER_HOST = dockerHost;
+  }
+  return env;
+}
+
+function probeDockerHost(
+  dockerHost: string | undefined,
+  source: NodeJS.ProcessEnv,
+): DockerHostProbeResult {
+  const result = dockerSpawnSync(["version", "--format", "{{json .}}"], {
+    encoding: "utf-8",
+    env: buildDockerProbeEnv(source, dockerHost),
+    timeout: DOCKER_PROBE_TIMEOUT_MS,
+    maxBuffer: DOCKER_PROBE_MAX_BUFFER_BYTES,
+  });
+  if (!result || result.status !== 0) return { reachable: false, identity: "unknown" };
+  return {
+    reachable: true,
+    identity: classifyDockerVersionIdentity(String(result.stdout ?? "")),
+  };
+}
+
 function containerCanReachHostLoopback(
   runtime: ContainerRuntime,
   opts: WslDetectionOptions = {},
@@ -165,21 +260,29 @@ function detectDockerHost(opts: DockerHostDetectionOptions = {}): DockerHostDete
     };
   }
 
+  const probe = opts.probeDockerHost ?? ((dockerHost) => probeDockerHost(dockerHost, env));
+  if (probe(undefined).reachable) return null;
+
   const fileExists = opts.existsSync ?? defaultExistsSync;
+  let selection: DockerHostDetection | null = null;
+  let selectedIdentity: Exclude<DockerVersionIdentity, "unknown"> | null = null;
   for (const socketPath of getDockerSocketCandidates(opts)) {
-    if (fileExists(socketPath)) {
-      return {
-        dockerHost: `unix://${socketPath}`,
-        source: "socket",
-        socketPath,
-      };
-    }
+    if (!fileExists(socketPath)) continue;
+    const dockerHost = `unix://${socketPath}`;
+    const observation = probe(dockerHost);
+    if (!observation.reachable) continue;
+    if (observation.identity === "unknown") return null;
+    if (selectedIdentity && observation.identity !== selectedIdentity) return null;
+    if (selection) continue;
+    selection = { dockerHost, source: "socket", socketPath };
+    selectedIdentity = observation.identity;
   }
 
-  return null;
+  return selection;
 }
 
 export {
+  classifyDockerVersionIdentity,
   containerCanReachHostLoopback,
   detectDockerHost,
   findColimaDockerSocket,

src/lib/runner.ts

@@ -43,15 +43,31 @@ type SpawnResult = SpawnSyncReturns<string | Buffer>;
 const dockerHost = detectDockerHost();
 if (dockerHost) {
   process.env.DOCKER_HOST = dockerHost.dockerHost;
+  if (dockerHost.source === "socket") {
+    delete process.env.DOCKER_CONTEXT;
+  }
 }
 
-function buildRunnerEnv(extraEnv?: NodeJS.ProcessEnv): Record<string, string> {
+function buildRunnerEnv(extraEnv?: NodeJS.ProcessEnv, executable?: string): Record<string, string> {
   const normalizedExtra: Record<string, string> = {};
   if (extraEnv) {
     for (const [key, value] of Object.entries(extraEnv)) {
       if (value !== undefined) normalizedExtra[key] = value;
     }
   }
+  const usesDockerDefaultAuthority =
+    executable !== undefined &&
+    path.basename(executable) === "docker" &&
+    normalizedExtra.DOCKER_HOST === undefined &&
+    process.env.DOCKER_HOST === undefined;
+  if (usesDockerDefaultAuthority) {
+    if (normalizedExtra.DOCKER_CONFIG === undefined && process.env.DOCKER_CONFIG !== undefined) {
+      normalizedExtra.DOCKER_CONFIG = process.env.DOCKER_CONFIG;
+    }
+    if (normalizedExtra.DOCKER_CONTEXT === undefined && process.env.DOCKER_CONTEXT !== undefined) {
+      normalizedExtra.DOCKER_CONTEXT = process.env.DOCKER_CONTEXT;
+    }
+  }
   return buildSubprocessEnv(normalizedExtra);
 }
 
@@ -118,7 +134,7 @@ function spawnAndHandle(
     shell: false,
     stdio: effectiveStdio,
     cwd: ROOT,
-    env: buildRunnerEnv(opts.env),
+    env: buildRunnerEnv(opts.env, safeFile),
   });
   if (!opts.suppressOutput) {
     writeRedactedResult(result, effectiveStdio);
@@ -192,7 +208,7 @@ function runArrayCmd(
     shell: false,
     stdio,
     cwd: ROOT,
-    env: buildRunnerEnv(extraEnv),
+    env: buildRunnerEnv(extraEnv, exe),
   });
   if (!suppressOutput) {
     writeRedactedResult(result, stdio);
@@ -293,7 +309,7 @@ function runCapture(cmd: readonly string[], opts: CaptureOptions = {}): string {
       ...spawnOpts,
       shell: false,
       cwd: ROOT,
-      env: buildRunnerEnv(extraEnv),
+      env: buildRunnerEnv(extraEnv, exe),
       stdio: ["pipe", "pipe", "pipe"],
       encoding: "utf-8",
     });
@@ -357,7 +373,7 @@ function runCaptureEx(
       // NO_PROXY=localhost,127.0.0.1 is injected when HTTP_PROXY is set.
       // Otherwise curl probes against localhost (Ollama validation, etc.)
       // tunnel through the user's host proxy and fail with HTTP 500.
-      env: buildRunnerEnv(extraEnv),
+      env: buildRunnerEnv(extraEnv, exe),
       stdio: ["pipe", "pipe", "pipe"],
       encoding: "utf-8",
     });

src/lib/shields/index.test.ts

@@ -68,6 +68,7 @@ vi.mock("../sandbox/agent-config", () => ({
 
 vi.mock("../adapters/docker/exec", () => ({
   dockerExecFileSync: vi.fn((_argv: string[]) => ""),
+  dockerSpawnSync: vi.fn(() => ({ status: 1, stdout: "", stderr: "" })),
 }));
 
 vi.mock("./audit", () => ({