test(onboard): close managed state lifecycle gaps

Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

Author: ericksoa

src/lib/onboard.ts

@@ -1899,13 +1899,7 @@ async function createSandboxWithBaseImageResolution(
     extraProviders: resolvedCreateIntent.extraProviders,
     staleExtraProviders: resolvedCreateIntent.staleExtraProviders ?? [],
   });
-  const dockerDriverGateway = isLinuxDockerDriverGatewayEnabled();
-  const hermesStateVolumeLifecycle = managedWorkloadOnboard.createManagedHermesStateVolumeOnboardLifecycle({
-    agentName: requestedAgentName,
-    runtimeProvider: managedWorkloadRuntime.runtimeProvider,
-    sandboxName,
-    workloadKind: preparedSandboxWorkload.source.kind,
-  });
+  const dockerDriverGateway = isLinuxDockerDriverGatewayEnabled(), hermesStateVolumeLifecycle = managedWorkloadOnboard.createManagedHermesStateVolumeOnboardLifecycle({ agentName: requestedAgentName, runtimeProvider: managedWorkloadRuntime.runtimeProvider, sandboxName, workloadKind: preparedSandboxWorkload.source.kind });
   const { initialSandboxPolicy, policyTier: resolvedCreatePolicyTier, messagingProviders, gpuRoutePlan, compatibilityPolicyPath, initialGpuRoute, sandboxReadyTimeoutSecs, buildId, dashboardRemoteBindPrepared, legacyBuildContext, launch: { createArgv, effectiveDashboardPort, intendedSandboxStartupCommand, managedBootstrapIdentity, managedStartupRootApplyRequest, prebuild, sandboxEnv, sandboxStartupCommand } } = await managedWorkloadOnboard.prepareOnboardSandboxWorkloadLaunch({
     runtime: managedWorkloadRuntime, workload: preparedSandboxWorkload,
     legacy: { preparedBuildContext, agent, fromDockerfile, createAgentSandbox: (selectedAgent) => baseImageResolutionFlow.createAgentSandboxWithResolution(baseImageResolutionContext, selectedAgent, agentOnboard.createAgentSandbox), resolvePatchInput: () => ({ preparedBuildContext, agent, fromDockerfile, model, chatUiUrl, provider, endpointUrl: createIntent?.endpointUrl ?? null, compatibleEndpointReasoning: createIntent?.compatibleEndpointReasoning, preferredInferenceApi, webSearchConfig, toolDisclosure: effectiveToolDisclosure, rebuildPreservedEnv: createIntent?.rebuildPreservedEnv, ...(isManagedDcodeAgent ? { dcodeAutoApprovalMode: dcodeAutoApprovalPlan.mode } : {}), hermesToolGateways, sandboxGpuConfig: effectiveSandboxGpuConfig, ...baseImageResolutionFlow.getBaseImageResolutionPatchOptions(baseImageResolutionContext), gatewayPort: GATEWAY_PORT }) },
@@ -2074,8 +2068,7 @@ async function createSandboxWithBaseImageResolution(
         }),
     },
   );
-  hermesStateVolumeLifecycle.commit();
-  if ("complete" in recreateRuntime) recreateRuntime.complete();
+  hermesStateVolumeLifecycle.commit(); if ("complete" in recreateRuntime) recreateRuntime.complete();
   restoreDefaultAfterRecreate(registry.setDefault, sandboxName, sandboxWasLiveDefault); // #4614: default deferred to finalization
 
   // DNS proxy — run a forwarder in the sandbox pod so the isolated

src/lib/onboard/host-mount/path-overlap.test.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import { containerPathsOverlap } from "./path-overlap";
+
+describe("containerPathsOverlap", () => {
+  it.each([
+    ["/sandbox/.hermes", "/sandbox/.hermes/"],
+    ["/sandbox/.hermes/", "/sandbox/.hermes/session"],
+    ["/var/lib/nemoclaw", "/var/lib/nemoclaw/managed-startup/"],
+    ["/", "/sandbox"],
+  ])("normalizes trailing slashes before detecting overlap", (left, right) => {
+    expect(containerPathsOverlap(left, right)).toBe(true);
+    expect(containerPathsOverlap(right, left)).toBe(true);
+  });
+
+  it("keeps sibling paths distinct", () => {
+    expect(containerPathsOverlap("/sandbox/.hermes", "/sandbox/.hermes-cache")).toBe(false);
+  });
+});

src/lib/onboard/host-mount/path-overlap.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+function normalizeContainerPath(value: string): string {
+  return value.replace(/\/+$/u, "") || "/";
+}
+
+export function containerPathsOverlap(left: string, right: string): boolean {
+  const normalizedLeft = normalizeContainerPath(left);
+  const normalizedRight = normalizeContainerPath(right);
+  const contains = (parent: string, child: string): boolean =>
+    parent === "/" ? child.startsWith("/") : child.startsWith(`${parent}/`);
+  return (
+    normalizedLeft === normalizedRight ||
+    contains(normalizedLeft, normalizedRight) ||
+    contains(normalizedRight, normalizedLeft)
+  );
+}

src/lib/onboard/managed-bootstrap/podman-bootstrap-replacement.ts

@@ -10,6 +10,7 @@ import type {
   ContainerEngine,
   ContainerEngineCommandResult,
 } from "../../adapters/container-engine";
+import { containerPathsOverlap } from "../host-mount/path-overlap";
 import {
   PODMAN_BOOTSTRAP_JOURNAL_SCHEMA_VERSION,
   type PodmanBootstrapJournal,
@@ -104,8 +105,7 @@ interface PodmanBootstrapReplacementAuthority {
   readonly watcherLease: PodmanGatewayWatcherLease;
 }
 
-export interface PrepareStoppedPodmanBootstrapReplacementInput
-  extends PodmanBootstrapReplacementAuthority {
+export interface PrepareStoppedPodmanBootstrapReplacementInput extends PodmanBootstrapReplacementAuthority {
   readonly plan: PodmanBootstrapReplacementPlan;
 }
 
@@ -114,8 +114,7 @@ export interface StopExactPodmanBootstrapOriginalInput extends PodmanBootstrapRe
   readonly heldWorkload: PodmanHeldWorkloadObservation;
 }
 
-export interface RollbackPodmanBootstrapBeforeCommitInput
-  extends PodmanBootstrapReplacementAuthority {
+export interface RollbackPodmanBootstrapBeforeCommitInput extends PodmanBootstrapReplacementAuthority {
   readonly bootstrapIdentity: string;
   readonly heldWorkload: PodmanHeldWorkloadObservation;
 }
@@ -322,10 +321,6 @@ function exactAbsolutePath(value: unknown, label: string): string {
   return target;
 }
 
-function pathsOverlap(left: string, right: string): boolean {
-  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
-}
-
 function assertMountDoesNotShadowState(specification: string): void {
   const destinations = specification.split(",").flatMap((entry) => {
     const separator = entry.indexOf("=");
@@ -340,7 +335,7 @@ function assertMountDoesNotShadowState(specification: string): void {
   }
   for (const destination of destinations) {
     const normalized = exactAbsolutePath(destination, "Podman runtime mount destination");
-    if (pathsOverlap(normalized, PODMAN_BOOTSTRAP_STATE_DIRECTORY)) {
+    if (containerPathsOverlap(normalized, PODMAN_BOOTSTRAP_STATE_DIRECTORY)) {
       failure(
         `Podman replacement runtime arguments cannot shadow ${PODMAN_BOOTSTRAP_STATE_DIRECTORY}.`,
         false,

src/lib/onboard/managed-workload/onboard-orchestration.test.ts

@@ -3,9 +3,71 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { prepareOnboardSandboxWorkloadLaunch } from "./onboard-orchestration";
+import {
+  createManagedHermesStateVolumeOnboardLifecycle,
+  prepareOnboardSandboxWorkloadLaunch,
+} from "./onboard-orchestration";
 
 describe("managed workload onboard orchestration", () => {
+  it("keeps failure cleanup armed until the caller commits registration", () => {
+    let volume: { name: string; labels: Record<string, string> } | null = null;
+    let exitCleanup: (() => void) | null = null;
+    const calls: string[][] = [];
+    const runDocker = vi.fn((args: readonly string[]) => {
+      const argv = [...args];
+      calls.push(argv);
+      if (argv[0] === "inspect") {
+        return volume
+          ? {
+              status: 0,
+              stdout: `${JSON.stringify({ Name: volume.name, Labels: volume.labels })}\n`,
+            }
+          : { status: 1, stderr: "Error response from daemon: no such volume" };
+      }
+      if (argv[0] === "create") {
+        const labels: Record<string, string> = {};
+        for (let index = 1; index < argv.length - 1; index += 1) {
+          if (argv[index] !== "--label") continue;
+          const [name, ...value] = argv[index + 1]!.split("=");
+          labels[name!] = value.join("=");
+          index += 1;
+        }
+        volume = { name: argv.at(-1)!, labels };
+        return { status: 0, stdout: `${volume.name}\n` };
+      }
+      if (argv[0] === "rm") {
+        volume = null;
+        return { status: 0, stdout: `${argv[1]}\n` };
+      }
+      return { status: 1, stderr: "unexpected Docker command" };
+    });
+
+    const lifecycle = createManagedHermesStateVolumeOnboardLifecycle(
+      {
+        agentName: "hermes",
+        runtimeProvider: { identity: { id: "docker" } } as never,
+        sandboxName: "alpha",
+        workloadKind: "managed-image",
+      },
+      {
+        runDocker: runDocker as never,
+        registerExitCleanup: (cleanup) => {
+          exitCleanup = cleanup;
+          return vi.fn();
+        },
+      },
+    );
+
+    lifecycle.materializeSandboxCreatePlan({} as never, (input) => {
+      expect(input.managedStateMount).toMatchObject({ target: "/sandbox/.hermes" });
+      return {} as never;
+    });
+    exitCleanup!();
+
+    expect(volume).toBeNull();
+    expect(calls.some((args) => args[0] === "rm")).toBe(true);
+  });
+
   it("resolves final-image patch metadata after managed build-context staging", async () => {
     const resolutionMetadata = { key: "published-dcode-base" };
     let staged = false;

src/lib/onboard/managed-workload/onboard-orchestration.ts

@@ -62,6 +62,7 @@ import { resolveSandboxWorkloadRuntimeCapabilities } from "../workload/runtime";
 import {
   prepareManagedHermesStateVolume,
   type ManagedHermesStateVolumeContext,
+  type ManagedHermesStateVolumeDeps,
 } from "./hermes-state-volume";
 
 type ManagedProfileInput = Omit<
@@ -85,13 +86,17 @@ export function createManagedHermesStateVolumeOnboardLifecycle(
   input: Omit<ManagedHermesStateVolumeContext, "runtimeProviderId"> & {
     readonly runtimeProvider: RuntimeProviderBundle | null;
   },
+  deps: ManagedHermesStateVolumeDeps = {},
 ): ManagedHermesStateVolumeOnboardLifecycle {
-  const scope = prepareManagedHermesStateVolume({
-    agentName: input.agentName,
-    runtimeProviderId: input.runtimeProvider?.identity.id,
-    sandboxName: input.sandboxName,
-    workloadKind: input.workloadKind,
-  });
+  const scope = prepareManagedHermesStateVolume(
+    {
+      agentName: input.agentName,
+      runtimeProviderId: input.runtimeProvider?.identity.id,
+      sandboxName: input.sandboxName,
+      workloadKind: input.workloadKind,
+    },
+    deps,
+  );
   return {
     materializeSandboxCreatePlan(input, materialize) {
       return materialize({ ...input, managedStateMount: scope?.mount });

src/lib/onboard/sandbox-create-plan-materialization.ts

@@ -8,6 +8,7 @@ import type {
   SandboxCreateIntent,
   SandboxCreateMessagingProviderRequest,
 } from "./sandbox-create-intent-types";
+import { containerPathsOverlap } from "./host-mount/path-overlap";
 import { prepareSandboxGpuRoutePolicies } from "./sandbox-gpu-route-policy";
 
 type PrepareInitialSandboxCreatePolicy =
@@ -23,17 +24,6 @@ const DCODE_MCP_SNAPSHOT_TMPFS_MOUNT = {
   mode: 0o1777,
 } as const;
 
-function pathsOverlap(left: string, right: string): boolean {
-  const normalize = (value: string) => value.replace(/\/+$/u, "") || "/";
-  const normalizedLeft = normalize(left);
-  const normalizedRight = normalize(right);
-  return (
-    normalizedLeft === normalizedRight ||
-    normalizedLeft.startsWith(`${normalizedRight}/`) ||
-    normalizedRight.startsWith(`${normalizedLeft}/`)
-  );
-}
-
 function buildSandboxDriverConfig(
   intent: SandboxCreateIntent,
   managedStateMount: MaterializeSandboxCreatePlanInput["managedStateMount"],
@@ -43,7 +33,7 @@ function buildSandboxDriverConfig(
   );
   if (managedStateMount) {
     const conflictingHostMount = intent.hostMounts?.find(({ target }) =>
-      pathsOverlap(target, managedStateMount.target),
+      containerPathsOverlap(target, managedStateMount.target),
     );
     if (conflictingHostMount) {
       throw new Error(

test/helpers/managed-image-buildless-e2e.ts

@@ -147,6 +147,7 @@ const registerCalls = [];
 const runnerCommands = [];
 const spawnCalls = [];
 let sandboxCreated = false;
+let managedHermesVolume = null;
 
 // The protected live-E2E job intentionally runs source without build:cli.
 // Route the root CLI's generated shared-boundary import back to its canonical
@@ -402,6 +403,7 @@ replace(managedBootstrap, "createDockerManagedBootstrapAdapter", () => {
 
 const runner = require(${source("src/lib/runner.ts")});
 runner.run = (command, options = {}) => {
+  const argv = Array.isArray(command) ? command.map(String) : [];
   const normalized = normalize(command);
   runnerCommands.push(normalized);
   if (/(?:^|\s)docker(?:\s+buildx)?\s+build(?:\s|$)/u.test(normalized)) {
@@ -412,6 +414,25 @@ runner.run = (command, options = {}) => {
       ? { status: 0, stdout: "Name: " + sandboxName + "\nId: sbx-managed-fixture\n", stderr: "" }
       : { status: 1, stdout: "", stderr: "sandbox not found" };
   }
+  if (argv[0] === "docker" && argv[1] === "volume") {
+    const volumeName = argv.at(-1);
+    if (argv[2] === "inspect") {
+      return managedHermesVolume
+        ? { status: 0, stdout: JSON.stringify(managedHermesVolume) + "\n", stderr: "" }
+        : { status: 1, stdout: "", stderr: "Error response from daemon: no such volume" };
+    }
+    if (argv[2] === "create") {
+      const labels = {};
+      for (let index = 3; index < argv.length - 1; index += 1) {
+        if (argv[index] !== "--label") continue;
+        const [name, ...value] = argv[index + 1].split("=");
+        labels[name] = value.join("=");
+        index += 1;
+      }
+      managedHermesVolume = { Name: volumeName, Labels: labels };
+      return { status: 0, stdout: volumeName + "\n", stderr: "" };
+    }
+  }
   return { status: 0, stdout: "", stderr: "" };
 };
 runner.runFile = (file, args = []) => runner.run([file, ...args]);
@@ -656,6 +677,25 @@ function assertManagedLaunch(
   const fromIndex = createArgs.indexOf("--from");
   expect(createArgs[fromIndex + 1]).toBe(expectedContract.reference);
   expect(createArgs.join(" ")).not.toContain("Dockerfile");
+  if (agent === "hermes") {
+    const driverConfigIndex = createArgs.indexOf("--driver-config-json");
+    expect(driverConfigIndex).toBeGreaterThanOrEqual(0);
+    expect(JSON.parse(createArgs[driverConfigIndex + 1]!) as unknown).toMatchObject({
+      docker: {
+        mounts: [
+          {
+            type: "volume",
+            source: "nemoclaw-hermes-state-v1-managed-hermes",
+            target: "/sandbox/.hermes",
+            read_only: false,
+          },
+        ],
+      },
+    });
+    expect(
+      result.payload.runnerCommands.some((command) => command.startsWith("docker volume create ")),
+    ).toBe(true);
+  }
 
   expect(createArgs.filter((arg) => arg.startsWith("NEMOCLAW_STARTUP_PROFILE_B64="))).toEqual([]);
   const encodedProfile = bootstrapRequest?.encodedProfile;