feat(onboard): bind managed create to runtime providers

ci/source-shape-test-budget.json

@@ -528,7 +528,7 @@
     },
     {
       "file": "test/runtime-provider-source-shape.test.ts",
-      "test": "keeps production activation paths disconnected from managed bootstrap",
+      "test": "keeps production activation paths disconnected from driver bootstrap adapters",
       "category": "security"
     },
     {

docs/inference/verify-inference-route.mdx

@@ -41,11 +41,15 @@ Restore the configured endpoint or proxy, run `$$nemoclaw onboard --resume` to c
 
 ## Understand Local Provider Post-Ready Checks
 
-For local Ollama and vLLM on Docker GPU sandboxes using the compatibility route, onboarding performs an additional check after the sandbox becomes ready.
+For local Ollama, local vLLM, and local NVIDIA NIM on Docker GPU sandboxes using the compatibility route, onboarding performs an additional check after the sandbox becomes ready.
+Local NIM uses the `vllm-local` route, so it receives the same reversible post-ready check as local vLLM.
 It requests `https://inference.local/v1/models` from inside the sandbox and accepts only a 2xx response.
-When this check fails, onboarding reports the endpoint and local-provider recovery steps before the first agent prompt.
+If this check fails after compatibility recreation, onboarding prints failure diagnostics and attempts to restore the pre-patch container before it exits.
+If that rollback fails, onboarding reports that the pre-patch container was not restored and prints container-cleanup guidance.
+The local-provider failure output includes the endpoint and recovery steps before the first agent prompt.
+GPU-proof diagnostics are captured before rollback and can also print cleanup guidance before the final container state is known, so inspect the sandbox and its labeled Docker containers before running a deletion command.
 
-NVIDIA NIM and other compatible endpoints receive their provider validation during onboarding but do not receive this local-provider post-ready check.
+Remote NVIDIA NIM and other compatible endpoints receive their provider validation during onboarding but do not receive this local-provider post-ready check.
 For those routes, continue to the final route check, then use the status command and a short agent request after onboarding.
 
 ## Understand Final Route Checks

docs/reference/commands.mdx

@@ -813,7 +813,10 @@ On ordinary native Linux, the compatibility path uses an available NVIDIA CDI sp
 On Docker Desktop WSL, the compatibility path skips CDI and tries Docker `--gpus all` before the NVIDIA runtime.
 On Jetson/Tegra hosts, the compatibility path uses the NVIDIA runtime and adds eligible host group IDs for the supported GPU device nodes.
 These include selected `/dev/nvmap`, `/dev/nvhost-*`, and `/dev/nvgpu/igpu0/*` nodes plus real `/dev/dri/renderD*` character devices.
-If the compatibility attempt fails, onboarding keeps its diagnostics and the failed sandbox in place and prints a manual cleanup command.
+After compatibility recreation starts, onboarding keeps the pre-patch container as a rollback backup until the replacement passes the Ready, GPU, and applicable local-inference checks.
+If a later check fails, onboarding prints failure diagnostics and attempts to restore the pre-patch container.
+If rollback fails, onboarding reports that the pre-patch container was not restored and prints container-cleanup guidance.
+GPU-proof diagnostics are captured before rollback and can print that guidance before the final container state is known, so inspect the sandbox and its labeled Docker containers before running a deletion command.
 
 Prerequisites:
 

docs/reference/troubleshooting.mdx

@@ -2506,7 +2506,7 @@ Identify the matching path before applying the recovery guidance.
 | --- | --- | --- |
 | Native `--gpu` is rejected, host runtime evidence identifies GPU injection failure, or an explicit driver proof fails and host configuration confirms no GPU attachment | Ordinary Linux native attempt | The default native-only route stops. Retry with `NEMOCLAW_DOCKER_GPU_PATCH=fallback` only if you explicitly accept one bounded compatibility retry, or use `=1` to select compatibility before creation. |
 | `Cleanup could not be proven safe` | Native-to-compatibility handoff | Run the printed sandbox deletion command, verify both the gateway row and OpenShell-managed Docker containers labeled for that sandbox are absent, then rerun onboarding. |
-| The patched container exits or the compatibility attempt fails | Compatibility recreation | Inspect the saved diagnostics, repair the NVIDIA Container Toolkit/CDI configuration, clean up the failed sandbox, and rerun onboarding. |
+| The patched container exits or the compatibility attempt fails | Compatibility recreation | Inspect the saved diagnostics and the rollback outcome, then repair the NVIDIA Container Toolkit/CDI configuration. Keep the sandbox when the pre-patch container was restored; delete it only after inspection confirms restoration failed. Then rerun onboarding. |
 | A recreated container inherits only a loopback DNS stub and no usable upstream | Compatibility DNS fallback | Repair the host's `systemd-resolved` upstream configuration, then rerun onboarding. |
 
 For bridge-networked compatibility recreation without an explicit container DNS setting, NemoClaw selects a usable IPv4 upstream from `systemd-resolved` and probes that exact `--dns` path before it stops the original container.
@@ -2552,20 +2552,26 @@ Use `NEMOCLAW_DOCKER_GPU_PATCH=0` only for troubleshooting because it bypasses t
 
 #### Common compatibility-path recovery
 
-If the compatibility attempt fails on any host, onboarding leaves the failed sandbox and diagnostic bundle in place so you can inspect the OpenShell and Docker state.
+After compatibility recreation starts, onboarding keeps the pre-patch container as a rollback backup until the replacement passes the Ready, direct GPU, and applicable local-inference checks.
+If a later check fails, onboarding prints failure diagnostics and attempts to restore the pre-patch container before it exits.
+When rollback succeeds, the pre-patch sandbox remains available.
+When rollback fails, onboarding reports that the pre-patch container was not restored and prints container-cleanup guidance.
+GPU-proof diagnostics are captured before rollback and can print that guidance before the final container state is known.
+Inspect the sandbox and its labeled Docker containers before running a deletion command.
 
 <Note>
 Starting with NemoClaw v0.0.43, the standard installer handles the `/proc/<pid>/task/<tid>/comm` permission case during this patch path.
 If an older release fails direct GPU proof with that path and `Permission denied`, upgrade NemoClaw and rerun onboarding.
 </Note>
 
-The output includes a cleanup command such as:
+When inspection confirms that the failed sandbox remains, delete it with a command such as:
 
 ```bash
 openshell sandbox delete <sandbox-name>
 ```
 
-Fix the NVIDIA Container Toolkit or CDI configuration reported in the diagnostics, clean up the failed sandbox, then rerun onboarding.
+Fix the NVIDIA Container Toolkit or CDI configuration reported in the diagnostics.
+Run the deletion command only after confirming that the pre-patch sandbox was not restored, then rerun onboarding.
 If you do not need GPU access inside the sandbox, rerun with `--no-sandbox-gpu`.
 
 If sandbox creation fails with `CDI device injection failed: unresolvable CDI devices nvidia.com/gpu=all`, the OpenShell gateway tried `docker create --device nvidia.com/gpu=all` and Docker could not resolve the CDI spec.

src/lib/adapters/openshell/sandbox-identity.ts

@@ -14,3 +14,19 @@ export function parseOpenShellSandboxId(output: string): string | null {
     ? (matches[0] as string)
     : null;
 }
+
+export function resolveOpenShellSandboxId(
+  sandboxName: string,
+  runCaptureOpenshell: (args: string[], options?: Record<string, unknown>) => string,
+): string {
+  const output = runCaptureOpenshell(["sandbox", "get", sandboxName], {
+    ignoreError: false,
+  });
+  const sandboxId = parseOpenShellSandboxId(output);
+  if (!sandboxId) {
+    throw new Error(
+      `OpenShell sandbox '${sandboxName}' did not return one exact durable sandbox ID.`,
+    );
+  }
+  return sandboxId;
+}

src/lib/onboard.ts

@@ -2708,7 +2708,7 @@ async function createSandboxWithBaseImageResolution(
   recreateRuntime.advance("creating");
   const {
     createResult,
-    dockerGpuCreatePatch,
+    runtimePatch,
     route: selectedGpuRoute,
     firstCreateOutput,
     registryImageRef,
@@ -2764,19 +2764,18 @@ async function createSandboxWithBaseImageResolution(
   }
 
   if (effectiveSandboxGpuConfig.sandboxGpuEnabled) {
-    dockerGpuLocalInference.verifyGpuSandboxLocalInferenceAfterReady(
+    await dockerGpuLocalInference.verifyGpuSandboxLocalInferenceAndCommitAfterReady(
       effectiveSandboxGpuConfig,
       provider,
       {
         sandboxName,
         dockerDriverGateway,
         selectedRoute: selectedGpuRoute,
         verifyDirectSandboxGpu,
-        verifyGpuOrExit: dockerGpuCreatePatch.verifyGpuOrExit,
-        selectedMode: dockerGpuCreatePatch.selectedMode,
         runCaptureOpenshell,
         log: console.log,
       },
+      runtimePatch,
     );
   }
 

src/lib/onboard/__test-helpers__/sandbox-gpu-create-flow.ts

@@ -64,8 +64,10 @@ export function createGpuPatchFixture() {
     maybeApplyDuringCreate: vi.fn(),
     createFailureMessage: vi.fn(() => null),
     exitOnPatchError: vi.fn(),
+    rollbackManagedStartupAfterCreateFailure: vi.fn(),
     ensureApplied: vi.fn(),
     waitForSupervisorReconnectIfNeeded: vi.fn(),
+    commitAfterReady: vi.fn(),
     selectedMode: vi.fn(() => null),
     printReadinessFailureIfEnabled: vi.fn(),
     verifyGpuOrExit: vi.fn(() => VERIFIED_GPU_PROOF),

src/lib/onboard/docker-gpu-local-inference.test.ts

@@ -11,6 +11,7 @@ import {
   shouldUseDockerGpuPatchHostNetwork,
   verifyDockerGpuSandboxLocalInference,
   verifyGpuSandboxAfterReady,
+  verifyGpuSandboxLocalInferenceAndCommitAfterReady,
 } from "./docker-gpu-local-inference";
 
 const HOST_NETWORK_ENV = {
@@ -311,10 +312,10 @@ describe("verifyGpuSandboxAfterReady", () => {
     };
   }
 
-  it("runs the GPU proof and the runtime inference gate when the patch is active", () => {
+  it("runs the GPU proof and the runtime inference gate when the patch is active", async () => {
     const log = vi.fn();
     const verifyDirectSandboxGpu = vi.fn();
-    verifyGpuSandboxAfterReady(
+    await verifyGpuSandboxAfterReady(
       GPU_CONFIG,
       "vllm-local",
       baseOptions({
@@ -327,12 +328,12 @@ describe("verifyGpuSandboxAfterReady", () => {
     expect(log).toHaveBeenCalledWith(expect.stringContaining("reached local inference"));
   });
 
-  it("captures the CUDA-usability proof onto the config for status persistence (#4231)", () => {
+  it("captures the CUDA-usability proof onto the config for status persistence (#4231)", async () => {
     const proof = { status: "verified" as const, cudaVerified: true, at: "t" };
     const config: { sandboxGpuEnabled: boolean; sandboxGpuProof?: typeof proof | null } = {
       sandboxGpuEnabled: true,
     };
-    verifyGpuSandboxAfterReady(
+    await verifyGpuSandboxAfterReady(
       config,
       "vllm-local",
       baseOptions({
@@ -343,45 +344,86 @@ describe("verifyGpuSandboxAfterReady", () => {
     expect(config.sandboxGpuProof).toEqual(proof);
   });
 
-  it("does not duplicate proof diagnostics when Docker GPU patch verifier handles them", () => {
+  it("does not duplicate proof diagnostics when Docker GPU patch verifier handles them", async () => {
     const proofError = new Error("process.exit");
     const verifyGpuOrExit = vi.fn(() => {
       throw proofError;
     });
     const logError = vi.fn();
-    expect(() =>
+    await expect(
       verifyGpuSandboxAfterReady(
         GPU_CONFIG,
         "ollama-local",
         baseOptions({ verifyGpuOrExit, logError }),
       ),
-    ).toThrow(proofError);
+    ).rejects.toBe(proofError);
     expect(logError).not.toHaveBeenCalled();
   });
 
-  it("routes failure diagnostics through the provided error sink and exits", () => {
+  it("routes failure diagnostics through the provided error sink and throws for rollback", async () => {
     const logError = vi.fn();
-    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as never);
-    try {
-      expect(() =>
-        verifyGpuSandboxAfterReady(
-          GPU_CONFIG,
-          "ollama-local",
-          baseOptions({
-            logError,
-            deps: { execInSandbox: execEmitting("HTTP_000"), sleep: vi.fn() },
-          }),
-        ),
-      ).toThrow("process.exit");
-      expect(exitSpy).toHaveBeenCalledWith(1);
-      expect(logError).toHaveBeenCalledWith(
-        expect.stringContaining("Local inference reachability check failed"),
-      );
-    } finally {
-      exitSpy.mockRestore();
-    }
+    await expect(
+      verifyGpuSandboxAfterReady(
+        GPU_CONFIG,
+        "ollama-local",
+        baseOptions({
+          logError,
+          deps: { execInSandbox: execEmitting("HTTP_000"), sleep: vi.fn() },
+        }),
+      ),
+    ).rejects.toThrow("GPU sandbox local inference reachability failed");
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("Local inference reachability check failed"),
+    );
+  });
+});
+
+describe("verifyGpuSandboxLocalInferenceAndCommitAfterReady", () => {
+  function options() {
+    return {
+      ...gpuPatchOptions(),
+      verifyDirectSandboxGpu: vi.fn(),
+      runCaptureOpenshell: vi.fn(() => ""),
+      log: vi.fn(),
+    };
+  }
+
+  it("commits only after local-inference reachability returns HTTP 2xx", async () => {
+    const runtimePatch = {
+      commitAfterReady: vi.fn(),
+      rollbackManagedStartupAfterCreateFailure: vi.fn(),
+    };
+    await verifyGpuSandboxLocalInferenceAndCommitAfterReady(
+      GPU_CONFIG,
+      "ollama-local",
+      {
+        ...options(),
+        deps: { execInSandbox: execEmitting("HTTP_200"), sleep: vi.fn() },
+      },
+      runtimePatch,
+    );
+    expect(runtimePatch.commitAfterReady).toHaveBeenCalledOnce();
+    expect(runtimePatch.rollbackManagedStartupAfterCreateFailure).not.toHaveBeenCalled();
+  });
+
+  it("rolls back before propagating an inference verification failure", async () => {
+    const runtimePatch = {
+      commitAfterReady: vi.fn(),
+      rollbackManagedStartupAfterCreateFailure: vi.fn(),
+    };
+    await expect(
+      verifyGpuSandboxLocalInferenceAndCommitAfterReady(
+        GPU_CONFIG,
+        "ollama-local",
+        {
+          ...options(),
+          deps: { execInSandbox: execEmitting("HTTP_000"), sleep: vi.fn() },
+        },
+        runtimePatch,
+      ),
+    ).rejects.toThrow("GPU sandbox local inference reachability failed");
+    expect(runtimePatch.rollbackManagedStartupAfterCreateFailure).toHaveBeenCalledOnce();
+    expect(runtimePatch.commitAfterReady).not.toHaveBeenCalled();
   });
 });