feat(onboard): add transactional Docker bootstrap adapter

src/lib/actions/sandbox/snapshot-auto-create-failure.test.ts

@@ -28,13 +28,22 @@ const streamSandboxCreateMock = vi.fn<SnapshotStreamSandboxCreateMock>(async ()
   forcedReady: false,
 }));
 
-vi.mock("../../adapters/docker", () => ({ dockerCapture: vi.fn(() => "") }));
+vi.mock("../../adapters/docker", () => ({
+  dockerCapture: vi.fn(() => ""),
+  dockerForceRm: vi.fn(),
+  dockerRunDetached: vi.fn(),
+}));
 vi.mock("../../adapters/openshell/runtime", () => ({
   captureOpenshell: captureOpenshellMock,
   getOpenshellBinary: vi.fn(() => "openshell"),
   runOpenshell: vi.fn(() => ({ status: 0, output: "" })),
 }));
-vi.mock("../../credentials/store", () => ({ prompt: vi.fn() }));
+vi.mock("../../credentials/store", () => ({
+  deleteCredential: vi.fn(),
+  getCredential: vi.fn(() => null),
+  prompt: vi.fn(),
+  saveCredential: vi.fn(),
+}));
 vi.mock("../../domain/sandbox/destroy", () => ({
   getSandboxDeleteOutcome: vi.fn(() => ({ alreadyGone: false, gatewayUnreachable: false })),
 }));
@@ -50,6 +59,11 @@ vi.mock("../../inference/nim", () => ({
   stopNimContainerByName: vi.fn(),
 }));
 vi.mock("../../messaging/channels", () => ({
+  BUILT_IN_CHANNEL_MANIFESTS: [],
+  getMessagingConfigEnvAliases: vi.fn(() => ({})),
+  getMessagingCredentialEnvKeysByChannel: vi.fn(() => ({})),
+  getMessagingProviderSuffixesByChannel: vi.fn(() => ({})),
+  listBuiltInMessagingChannelManifests: vi.fn(() => []),
   listMessagingProviderSuffixes: vi.fn(() => []),
   listMessagingCredentialMetadata: vi.fn(() => []),
 }));

src/lib/actions/sandbox/snapshot-restore-test-fixture.ts

@@ -213,7 +213,9 @@ export { lifecycleMock, shieldsMock };
 
 vi.mock("../../adapters/docker", () => ({
   dockerCapture: vi.fn(() => ""),
+  dockerForceRm: vi.fn(),
   dockerInspect: dockerInspectMock,
+  dockerRunDetached: vi.fn(),
 }));
 
 vi.mock("../../agent/defs", () => ({
@@ -227,7 +229,10 @@ vi.mock("../../adapters/openshell/runtime", () => ({
 }));
 
 vi.mock("../../credentials/store", () => ({
+  deleteCredential: vi.fn(),
+  getCredential: vi.fn(() => null),
   prompt: vi.fn(),
+  saveCredential: vi.fn(),
 }));
 
 vi.mock("../../domain/sandbox/destroy", () => ({

src/lib/actions/sandbox/snapshot.test.ts

@@ -144,19 +144,21 @@ const latestBackupFixture = {
 
 vi.mock("../../adapters/docker", () => ({
   dockerCapture: vi.fn(() => ""),
+  dockerForceRm: vi.fn(),
   dockerInspect: dockerInspectMock,
+  dockerRunDetached: vi.fn(),
 }));
-
 vi.mock("../../adapters/openshell/runtime", () => ({
   captureOpenshell: captureOpenshellMock,
   getOpenshellBinary: vi.fn(() => "openshell"),
   runOpenshell: runOpenshellMock,
 }));
-
 vi.mock("../../credentials/store", () => ({
+  deleteCredential: vi.fn(),
+  getCredential: vi.fn(() => null),
   prompt: vi.fn(),
+  saveCredential: vi.fn(),
 }));
-
 vi.mock("../../domain/sandbox/destroy", () => ({
   getSandboxDeleteOutcome: vi.fn(() => ({ alreadyGone: false, gatewayUnreachable: false })),
 }));
@@ -165,7 +167,6 @@ vi.mock("../../inference/nim", () => ({
   stopNimContainer: vi.fn(),
   stopNimContainerByName: vi.fn(),
 }));
-
 vi.mock("../../policy", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../../policy")>()),
   applyPreset: applyPresetMock,
@@ -176,7 +177,6 @@ vi.mock("../../policy", async (importOriginal) => ({
   removePreset: removePresetMock,
   resolveAgentBaselinePolicy: resolveTestAgentBaselinePolicy,
 }));
-
 vi.mock("../../runner", () => ({
   ROOT: "/repo",
   run: vi.fn(() => ({ status: 0 })),

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

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import { parseOpenShellSandboxId } from "./sandbox-identity";
+
+describe("OpenShell sandbox identity parsing", () => {
+  it("accepts one exact durable ID with optional terminal color", () => {
+    expect(parseOpenShellSandboxId("Name: alpha\nID: sandbox-alpha\n")).toBe("sandbox-alpha");
+    expect(parseOpenShellSandboxId("\u001b[32mId: sandbox.alpha_2\u001b[0m\n")).toBe(
+      "sandbox.alpha_2",
+    );
+  });
+
+  it("rejects ambiguous or non-canonical IDs", () => {
+    expect(parseOpenShellSandboxId("ID: first\nID: second\n")).toBeNull();
+    expect(parseOpenShellSandboxId("ID: sandbox/alpha\n")).toBeNull();
+    expect(parseOpenShellSandboxId("id: sandbox-alpha\n")).toBeNull();
+  });
+});

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

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+const ANSI_RE = /\x1b\[[0-9;]*m/gu;
+const SANDBOX_ID_RE = /^[A-Za-z0-9._-]+$/u;
+
+export function parseOpenShellSandboxId(output: string): string | null {
+  const matches = [
+    ...String(output)
+      .replace(ANSI_RE, "")
+      .matchAll(/^\s*(?:Id|ID):\s*(\S+)\s*$/gm),
+  ].map((match) => match[1] ?? "");
+  return matches.length === 1 && SANDBOX_ID_RE.test(matches[0] as string)
+    ? (matches[0] as string)
+    : null;
+}

src/lib/onboard/docker-gpu-patch-clone.test.ts

@@ -122,6 +122,41 @@ describe("Docker GPU clone envelope", () => {
     expect(args).not.toContain("nofile=1024:1024");
   });
 
+  it("uses exact managed-bootstrap container, entrypoint, and command overrides", () => {
+    const args = buildDockerGpuCloneRunArgs(
+      inspectFixture(),
+      buildDockerGpuMode("startup-command"),
+      {
+        containerName: "openshell-alpha-bootstrap-stage",
+        containerEntrypoint: "/usr/local/bin/nemoclaw-managed-bootstrap",
+        containerCommand: ["--request", "/run/nemoclaw/bootstrap-request.json"],
+      },
+    );
+
+    expect(args.slice(0, 2)).toEqual(["--name", "openshell-alpha-bootstrap-stage"]);
+    expect(args).toEqual(
+      expect.arrayContaining(["--entrypoint", "/usr/local/bin/nemoclaw-managed-bootstrap"]),
+    );
+    expect(args.slice(args.indexOf("openshell/sandbox:abc"))).toEqual([
+      "openshell/sandbox:abc",
+      "--request",
+      "/run/nemoclaw/bootstrap-request.json",
+    ]);
+  });
+
+  it.each([
+    "",
+    "-starts-with-dash",
+    "contains/slash",
+    "a".repeat(254),
+  ])("rejects invalid managed-bootstrap container name %j", (containerName) => {
+    expect(() =>
+      buildDockerGpuCloneRunArgs(inspectFixture(), buildDockerGpuMode("startup-command"), {
+        containerName,
+      }),
+    ).toThrow("Docker clone container name is invalid.");
+  });
+
   it("adds SYS_PTRACE to the GPU clone when the baseline container lacks it", () => {
     const inspect = inspectFixture();
     inspect.HostConfig!.CapAdd = ["SYS_ADMIN", "NET_ADMIN"];

src/lib/onboard/docker-gpu-patch-clone.ts

@@ -329,7 +329,15 @@ export function buildDockerGpuCloneRunArgs(
   const image = String(options.image || config.Image || "").trim();
   if (!image) throw new Error("Docker inspect output did not include Config.Image.");
 
-  const args: string[] = ["--name", dockerContainerName(inspect), ...mode.args];
+  const containerName = String(options.containerName ?? dockerContainerName(inspect)).trim();
+  if (
+    containerName.length === 0 ||
+    containerName.length > 253 ||
+    !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/u.test(containerName)
+  ) {
+    throw new Error("Docker clone container name is invalid.");
+  }
+  const args: string[] = ["--name", containerName, ...mode.args];
   const gpuAugment = mode.kind !== "startup-command";
 
   // Startup-command recreation must retain OpenShell's native CDI attachment.
@@ -435,8 +443,17 @@ export function buildDockerGpuCloneRunArgs(
   if (host.Init) args.push("--init");
 
   const entrypoint = stringArray(config.Entrypoint);
-  if (entrypoint.length > 0) args.push("--entrypoint", entrypoint[0]);
-  const commandArgs = sandboxCommand ? [] : [...entrypoint.slice(1), ...stringArray(config.Cmd)];
+  const replacementEntrypoint = String(options.containerEntrypoint ?? "").trim();
+  if (replacementEntrypoint) {
+    args.push("--entrypoint", replacementEntrypoint);
+  } else if (entrypoint.length > 0) {
+    args.push("--entrypoint", entrypoint[0]);
+  }
+  const commandArgs = options.containerCommand
+    ? [...options.containerCommand]
+    : sandboxCommand
+      ? []
+      : [...entrypoint.slice(1), ...stringArray(config.Cmd)];
   args.push(image, ...commandArgs);
   return args;
 }

src/lib/onboard/docker-gpu-patch-types.ts

@@ -112,6 +112,14 @@ export type DockerGpuCloneRunOptions = {
   sandboxFallbackDns?: string | null;
   openshellSandboxCommand?: readonly string[] | null;
   requiredUlimits?: readonly DockerUlimit[] | null;
+  /**
+   * Exact replacement process boundary used only by dormant managed bootstrap.
+   * Ordinary recreation leaves both fields unset.
+   */
+  containerEntrypoint?: string | null;
+  containerCommand?: readonly string[] | null;
+  /** Stopped staging name used before exact-name cutover. */
+  containerName?: string | null;
   /**
    * Extra supplementary group IDs to add to the recreated container via
    * `--group-add`. On Jetson these are the host group(s) owning the Tegra GPU
@@ -190,6 +198,14 @@ export type DockerContainerInspect = {
     Hostname?: string;
     Tty?: boolean;
     OpenStdin?: boolean;
+    StopTimeout?: number | null;
+    Volumes?: Record<string, unknown> | null;
+  } | null;
+  State?: {
+    Running?: boolean;
+    Paused?: boolean;
+    Restarting?: boolean;
+    Dead?: boolean;
   } | null;
   HostConfig?: {
     Binds?: string[] | null;
@@ -244,6 +260,7 @@ export type DockerContainerInspect = {
       DeviceIDs?: string[] | null;
     }> | null;
     ShmSize?: number;
+    ReadonlyRootfs?: boolean;
     ReadonlyPaths?: string[] | null;
     MaskedPaths?: string[] | null;
   } | null;

src/lib/onboard/managed-bootstrap/README.md

@@ -3,9 +3,9 @@
 
 # Managed bootstrap protocol
 
-This directory defines a dormant, driver-neutral transaction contract. It does
-not register a runtime provider or change sandbox creation, onboarding,
-snapshot, clone, or restore behavior.
+This directory defines a dormant, driver-neutral transaction contract and its
+first driver adapter. It does not register a runtime provider, activate managed
+bootstrap, or change the current user-visible lifecycle paths.
 
 The protocol binds one random bootstrap identity to:
 
@@ -71,6 +71,22 @@ journal and a canonical launch-spec normalizer. Each surface is independently
 validated and remains dormant: no registered runtime provider imports either
 module, and neither changes sandbox creation or lifecycle behavior.
 
+The Docker adapter creates and validates a stopped replacement under an
+identity-derived staging name while the original remains running. It stages the
+0400 envelope and returns exact cleanup authority without quiescing, renaming,
+or otherwise mutating the original. Only after the coordinator durably records
+that complete prepared authority may activation journal both full runtime IDs,
+all three names, both launch-spec hashes, image identity, profile fingerprint,
+and sandbox ID and then enter the destructive cutover. Post-cutover rollback
+publishes `rollback-authorized` before exact replacement deletion; pre-cutover
+staged cleanup removes only the exact prepared replacement without that journal
+transition. Commit publishes `shared-state-committed` before exact backup
+deletion. Cleanup is bound to full runtime IDs. Mutable OpenShell names are read
+only to detect ownership reuse, and unsafe name-only deletion returns a typed
+retention error. The dormant adapter assumes the protocol's single coordinator;
+multi-process lease/arbitration remains an explicit production-activation gate.
+Activation must also inject the selected gateway's canonical state root.
+
 ## Architectural disposition
 
 The coordinator deliberately lands as a dormant trust-boundary slice before a
@@ -86,22 +102,22 @@ This is executable, bounded groundwork rather than an untested placeholder.
 failure rollback for OpenClaw, Hermes, and LangChain Deep Agents Code through an
 MXC-named fake driver. `runtime-provider-source-shape.test.ts` separately
 inventories the protocol, provider, and image-packaging surfaces and proves that
-production activation cannot import or package the protocol yet. The later
-activation slice must add a registered-provider contract test for the same
-transaction before removing those dormancy assertions.
+production activation does not import or install the protocol into a runtime
+image yet. The later activation slice must add a registered-provider contract
+test for the same transaction before removing those dormancy assertions.
 
 The native entrypoint source is intentionally not compiled into production
-artifacts, and neither source is packaged or selected yet. No production
-TypeScript module imports this protocol. The current image definitions do not
-package `nemoclaw-managed-startup-hold` or
-`managed-startup-image-runtime.cjs`. A later
-provider integration must compile and verify the freestanding entrypoint
-natively for amd64 and arm64 in every agent image. It must add those
-prerequisites together with their image-runtime bootstrap modes, implement
-driver-specific prepare, durable-record, activate, exact cleanup, and rollback,
-and only then wire the coordinator into create. The same contract is exercised
-for OpenClaw, Hermes, and Deep Agents Code without a provider-specific central
-switch. The remaining integration and qualification work is tracked in
-[epic #7744](https://github.com/NVIDIA/NemoClaw/issues/7744) and its linked
-implementation stack. Until that complete boundary lands, every registered
-runtime provider keeps its bootstrap surface unsupported.
+artifacts, and neither image-owned source is installed or selected in a runtime
+image yet. No production activation or provider module outside this dormant
+directory imports the protocol or Docker adapter. The current image definitions
+do not package `nemoclaw-managed-startup-hold`,
+`managed-startup-image-runtime.cjs`, or the shared-state bootstrap modes consumed
+by the adapter. A later provider integration must compile and verify the
+freestanding entrypoint natively for amd64 and arm64 in every agent image. It
+must add those prerequisites together with their image-runtime bootstrap modes
+and wire the coordinator and Docker adapter into create as one boundary. The
+same contract is exercised for OpenClaw, Hermes, and Deep Agents Code without a
+provider-specific central switch. The remaining integration and qualification
+work is tracked in [epic #7744](https://github.com/NVIDIA/NemoClaw/issues/7744)
+and its linked implementation stack. Until that complete boundary lands, every
+registered runtime provider keeps its bootstrap surface unsupported.

src/lib/onboard/managed-bootstrap/adapter.test.ts

@@ -909,13 +909,16 @@ describe("managed bootstrap adapter contract", () => {
   });
 
   it.each([
+    "BASHOPTS=extdebug",
     "BASH_ENV=/sandbox/attacker",
     "ENV=/sandbox/attacker",
-    "LD_PRELOAD=/sandbox/attacker.so",
     "LD_AUDIT=/sandbox/attacker.so",
     "LD_LIBRARY_PATH=/sandbox/lib",
-    "SHELLOPTS=xtrace",
+    "LD_PRELOAD=/sandbox/attacker.so",
+    "NODE_OPTIONS=--require=/sandbox/attacker.cjs",
+    "NODE_PATH=/sandbox/attacker-modules",
     "PS4=$(touch /sandbox/bypass)",
+    "SHELLOPTS=xtrace",
     "BASH_FUNC_attacker%%=() { touch /sandbox/bypass; }",
   ])("rejects a process-control assignment before rendering the held command: %s", (assignment) => {
     const request = requestFor("hermes");

src/lib/onboard/managed-bootstrap/adapter.ts

@@ -25,6 +25,8 @@ const PROCESS_INJECTION_ENV_KEYS = new Set([
   "LD_AUDIT",
   "LD_LIBRARY_PATH",
   "LD_PRELOAD",
+  "NODE_OPTIONS",
+  "NODE_PATH",
   "PS4",
   "SHELLOPTS",
 ]);
@@ -931,7 +933,7 @@ function normalizePreparedReplacement(
   });
 }
 
-function createPreparedAuthority(
+export function createManagedBootstrapPreparedAuthority(
   transaction: ManagedBootstrapPreparedTransaction,
 ): ManagedBootstrapPreparedAuthority {
   const { handle, snapshot, prepared } = transaction;
@@ -1358,7 +1360,7 @@ export async function activateManagedBootstrapSequence(
   let durablePreparation: ManagedBootstrapDurablePreparationReceipt | null = null;
   let replacement: ManagedBootstrapReplacementHandle | null = null;
   try {
-    const authority = createPreparedAuthority(input.transaction);
+    const authority = createManagedBootstrapPreparedAuthority(input.transaction);
     durablePreparation = normalizeDurablePreparationReceipt(
       await input.authorityStore.recordPreparedAuthority(authority),
       authority,