feat(snapshot): prepare immutable managed clone handoff

src/lib/actions/sandbox/snapshot-managed-clone-handoff-dormancy.test.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { createHash } from "node:crypto";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { managedStartupE2eProfile } from "../../../../scripts/checks/generate-managed-startup-profile-fixture.mts";
+import { MANAGED_IMAGE_REPOSITORIES } from "../../onboard/managed-image/contract";
+import { encodeManagedStartupProfile } from "../../onboard/managed-startup/profile";
+import * as fixture from "./snapshot-restore-test-fixture";
+
+beforeEach(() => fixture.resetSnapshotRestoreMocks());
+afterEach(() => fixture.cleanupSnapshotRestoreMocks());
+
+describe("managed snapshot clone activation boundary", () => {
+  it("rejects managed cross-sandbox restore before destination effects (#7744)", async () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const encodedProfile = encodeManagedStartupProfile(managedStartupE2eProfile("openclaw"));
+    fixture.getLatestBackupMock.mockReturnValue({
+      snapshotVersion: 4,
+      timestamp: "2026-07-30T00:00:00.000Z",
+      backupPath: "/tmp/backup-alpha",
+      agentType: "openclaw",
+      workload: {
+        schemaVersion: 1,
+        kind: "managed-image",
+        reference: `${MANAGED_IMAGE_REPOSITORIES.openclaw}@sha256:${"a".repeat(64)}`,
+        platform: "linux/amd64",
+        release: "v0.0.100",
+        sourceRevision: "b".repeat(40),
+        sourceCohort: "ghrun-123-1",
+        capabilityContractVersion: 1,
+        startupProfileContractVersion: 1,
+        encodedProfile,
+        startupProfileSha256: createHash("sha256").update(encodedProfile, "utf8").digest("hex"),
+        credentialProxyReplayRequired: false,
+        shared: true,
+      },
+      runtimeSnapshot: {
+        schemaVersion: 1,
+        providerId: "docker",
+        providerHandle: "snapshot-provider-handle",
+        lifecycleState: "running",
+        lifecycleGeneration: "snapshot-generation",
+        runtime: {
+          schemaVersion: 1,
+          providerId: "docker",
+          runtime: { kind: "docker-container", handle: "container-id" },
+          acceleration: { kind: "none" },
+        },
+      },
+    });
+    fixture.getSandboxMock.mockImplementation((name) =>
+      name === "alpha" ? { name: "alpha", agent: "openclaw", openshellDriver: "docker" } : null,
+    );
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await expect(
+      runSandboxSnapshot("alpha", { kind: "restore", to: "beta", force: true, yes: true }),
+    ).rejects.toMatchObject({ exitCode: 1 });
+
+    expect(consoleError.mock.calls.flat().join("\n")).toContain(
+      "requires managed-profile clone rebind",
+    );
+    expect(fixture.lifecycleMock.events).not.toContain("delete");
+    expect(fixture.streamSandboxCreateMock).not.toHaveBeenCalled();
+    expect(fixture.restoreSandboxStateMock).not.toHaveBeenCalled();
+  });
+});

src/lib/messaging/clone-rebind.ts

@@ -0,0 +1,167 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { cloneAndDeepFreeze } from "../core/immutable";
+import { isValidName } from "../name-validation";
+import { createBuiltInChannelManifestRegistry } from "./channels/built-ins";
+import { resolveSandboxNameTemplate } from "./compiler/engines/template";
+import { hydrateDerivedSandboxMessagingPlanFields } from "./hydration";
+import type { MessagingAgentId, SandboxMessagingPlan } from "./manifest";
+import { compactSandboxMessagingPlanForPersistence } from "./persistence";
+import { parseSandboxMessagingPlan } from "./plan-validation";
+
+export interface SandboxMessagingCloneRebindInput {
+  readonly sourceSandboxName: string;
+  readonly destinationSandboxName: string;
+  readonly agent: MessagingAgentId;
+  readonly sourcePlan: unknown;
+  /**
+   * Explicit non-secret inputs used by manifest renderers. Clone rebinding
+   * never consults process.env, so an unrelated host credential cannot change
+   * the destination plan or enter its fingerprints.
+   */
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+
+export class SandboxMessagingCloneRebindError extends Error {
+  constructor(message: string) {
+    super(`Cannot rebind managed messaging plan: ${message}`);
+    this.name = "SandboxMessagingCloneRebindError";
+  }
+}
+
+function fail(message: string): never {
+  throw new SandboxMessagingCloneRebindError(message);
+}
+
+function requireSandboxName(value: string, label: string): string {
+  if (!isValidName(value)) fail(`${label} sandbox name is invalid`);
+  return value;
+}
+
+/**
+ * Recompile one secret-free managed messaging plan for a destination sandbox.
+ *
+ * Compact persistence data is the retained intent boundary. All target-bound
+ * provider names and executable derived fields are rebuilt from current
+ * built-in manifests with an explicit, credential-free environment.
+ */
+export function rebindSandboxMessagingPlanForClone(
+  input: SandboxMessagingCloneRebindInput,
+): SandboxMessagingPlan {
+  const sourceSandboxName = requireSandboxName(input.sourceSandboxName, "source");
+  const destinationSandboxName = requireSandboxName(input.destinationSandboxName, "destination");
+  if (sourceSandboxName === destinationSandboxName) {
+    fail("source and destination sandbox names must differ");
+  }
+
+  const manifestRegistry = createBuiltInChannelManifestRegistry();
+  const supportedChannelIds = manifestRegistry
+    .listAvailable({ agent: input.agent })
+    .map((manifest) => manifest.id);
+  const environment = Object.freeze({ ...(input.environment ?? {}) });
+  const sourcePlan = parseSandboxMessagingPlan(input.sourcePlan, {
+    sandboxName: sourceSandboxName,
+    agent: input.agent,
+    supportedChannelIds,
+    environment,
+  });
+  if (!sourcePlan) fail("source plan is invalid or uses a non-built-in channel");
+  const sourceChannelIds = new Set(sourcePlan.channels.map((channel) => channel.channelId));
+  if (sourcePlan.disabledChannels.some((channelId) => !sourceChannelIds.has(channelId))) {
+    fail("source plan disables a channel that is not configured");
+  }
+  for (const channel of sourcePlan.channels) {
+    const manifest = manifestRegistry.get(channel.channelId);
+    if (!manifest || !manifest.supportedAgents.includes(input.agent)) {
+      fail(`source channel ${channel.channelId} is not a supported built-in`);
+    }
+    const listedDisabled = sourcePlan.disabledChannels.includes(channel.channelId);
+    if (channel.disabled !== listedDisabled || (channel.active && !channel.configured)) {
+      fail(`source channel ${channel.channelId} has inconsistent lifecycle state`);
+    }
+    const seenInputIds = new Set<string>();
+    for (const planInput of channel.inputs) {
+      if (seenInputIds.has(planInput.inputId)) {
+        fail(`source channel ${channel.channelId} repeats input ${planInput.inputId}`);
+      }
+      seenInputIds.add(planInput.inputId);
+      const manifestInput = manifest.inputs.find((candidate) => candidate.id === planInput.inputId);
+      if (!manifestInput || manifestInput.kind !== planInput.kind) {
+        fail(
+          `source channel ${channel.channelId} input ${planInput.inputId} is not manifest-owned`,
+        );
+      }
+      if (planInput.kind === "secret" && planInput.value !== undefined) {
+        fail("source plan contains a raw secret input value");
+      }
+    }
+    if (channel.active && !channel.disabled) {
+      for (const requiredInput of manifest.inputs.filter((candidate) => candidate.required)) {
+        const retained = channel.inputs.find((candidate) => candidate.inputId === requiredInput.id);
+        const available =
+          requiredInput.kind === "secret"
+            ? retained?.credentialAvailable === true
+            : retained?.value !== undefined;
+        if (!available) {
+          fail(
+            `active source channel ${channel.channelId} is missing required input ${requiredInput.id}`,
+          );
+        }
+      }
+    }
+  }
+
+  const compact = compactSandboxMessagingPlanForPersistence(sourcePlan);
+  const credentialBindings = (compact.credentialBindings ?? []).map(
+    ({ credentialHash: _sourceCredentialHash, ...binding }) => binding,
+  );
+  const targetIntent = {
+    ...compact,
+    // A source hash describes the source gateway credential, not the explicit
+    // credential that clone provisioning will write into the destination.
+    credentialBindings,
+    sandboxName: destinationSandboxName,
+    // These fields are executable output, not retained clone intent.
+    networkPolicy: { presets: [], entries: [] },
+    agentRender: [],
+    buildSteps: [],
+    runtimeSetup: { nodePreloads: [], envAliases: [], secretScans: [] },
+    stateUpdates: [],
+    healthChecks: [],
+  } as const;
+  const normalized = parseSandboxMessagingPlan(targetIntent, {
+    sandboxName: destinationSandboxName,
+    agent: input.agent,
+    supportedChannelIds,
+    environment,
+  });
+  if (!normalized) fail("destination intent could not be normalized");
+  const hydrated = hydrateDerivedSandboxMessagingPlanFields(normalized, { environment });
+  const rebound = parseSandboxMessagingPlan(hydrated, {
+    sandboxName: destinationSandboxName,
+    agent: input.agent,
+    supportedChannelIds,
+    environment,
+  });
+  if (!rebound) fail("destination plan could not be validated after manifest hydration");
+  const secretProvenanceNeutralRebound = {
+    ...rebound,
+    credentialBindings: rebound.credentialBindings.map(
+      ({ credentialHash: _ambientCredentialHash, ...binding }) => binding,
+    ),
+  };
+  for (const binding of secretProvenanceNeutralRebound.credentialBindings) {
+    const credential = manifestRegistry
+      .get(binding.channelId)
+      ?.credentials.find((candidate) => candidate.id === binding.credentialId);
+    const expectedProviderName =
+      credential === undefined
+        ? undefined
+        : resolveSandboxNameTemplate(credential.providerName, destinationSandboxName);
+    if (!expectedProviderName || binding.providerName !== expectedProviderName) {
+      fail(`destination provider identity for ${binding.channelId} could not be proven`);
+    }
+  }
+  return cloneAndDeepFreeze(secretProvenanceNeutralRebound);
+}

src/lib/messaging/compiler/engines/credential-binding-engine.ts

@@ -1,19 +1,20 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { hashCredential } from "../../../security/credential-hash";
 import type {
   ChannelManifest,
   SandboxMessagingCredentialBindingPlan,
   SandboxMessagingInputReference,
 } from "../../manifest";
 import type { ManifestCompilerContext } from "../types";
-import { hashCredential } from "../../../security/credential-hash";
 import { resolveSandboxNameTemplate } from "./template";
 
 export function planCredentialBindings(
   manifest: ChannelManifest,
   context: ManifestCompilerContext,
   inputs: readonly SandboxMessagingInputReference[],
+  environment: Readonly<Record<string, string | undefined>> = process.env,
 ): SandboxMessagingCredentialBindingPlan[] {
   return manifest.credentials.map((credential) => {
     const sourceInput = inputs.find((input) => input.inputId === credential.sourceInput);
@@ -24,7 +25,7 @@ export function planCredentialBindings(
 
     const envKey = sourceInput?.sourceEnv ?? credential.providerEnvKey;
     const credentialHash = credentialAvailable
-      ? (hashCredential(process.env[envKey]) ?? undefined)
+      ? (hashCredential(environment[envKey]) ?? undefined)
       : undefined;
 
     return {

src/lib/messaging/compiler/engines/host-forward-engine.ts

@@ -17,10 +17,11 @@ export function planHostForward(
   inputs: readonly SandboxMessagingInputReference[],
   active: boolean,
   referenceResolver?: RenderTemplateReferenceResolver,
+  environment: Readonly<Record<string, string | undefined>> = process.env,
 ): SandboxMessagingHostForwardPlan | undefined {
   if (!active || !manifest.hostForward) return undefined;
 
-  const context = { inputs, env: process.env, referenceResolver };
+  const context = { inputs, env: environment, referenceResolver };
   if (!isTruthyRenderTemplate(manifest.hostForward.when, context)) return undefined;
 
   const portValue = resolveRenderTemplatesInValue(manifest.hostForward.port, context);

src/lib/messaging/hydration.ts

@@ -42,12 +42,19 @@ import {
   normalizePersistedInputs,
 } from "./persistence";
 
+export interface SandboxMessagingHydrationOptions {
+  /** Explicit environment seam for deterministic rehydration without ambient credentials. */
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+
 export function hydrateDerivedSandboxMessagingPlanFields(
   plan: SandboxMessagingPlan,
+  options: SandboxMessagingHydrationOptions = {},
 ): SandboxMessagingPlan {
+  const environment = options.environment ?? process.env;
   const manifestRegistry = createBuiltInChannelManifestRegistry();
   const channels = plan.channels.map((channel) =>
-    hydrateChannelFromManifest(plan, channel, manifestRegistry.get(channel.channelId)),
+    hydrateChannelFromManifest(plan, channel, manifestRegistry.get(channel.channelId), environment),
   );
   const hydratedPlan = { ...plan, channels };
   const manifests = channels.flatMap((channel) => {
@@ -63,7 +70,7 @@ export function hydrateDerivedSandboxMessagingPlanFields(
     agentRender:
       plan.agentRender.length > 0
         ? plan.agentRender
-        : agentRenderFromManifests(hydratedPlan, manifestRegistry),
+        : agentRenderFromManifests(hydratedPlan, manifestRegistry, environment),
     buildSteps:
       plan.buildSteps.length > 0
         ? plan.buildSteps
@@ -82,6 +89,7 @@ function hydrateChannelFromManifest(
   plan: SandboxMessagingPlan,
   channel: SandboxMessagingChannelPlan,
   manifest: ChannelManifest | undefined,
+  environment: Readonly<Record<string, string | undefined>>,
 ): SandboxMessagingChannelPlan {
   const { hostForward: _oldHostForward, ...channelWithoutHostForward } = channel;
   const disabled = channel.disabled || plan.disabledChannels.includes(channel.channelId);
@@ -91,7 +99,7 @@ function hydrateChannelFromManifest(
   const configured = channel.configured;
   const active = channel.active && !disabled;
   const hostForward = manifest
-    ? planHostForward(manifest, inputs, active, createBuiltInRenderTemplateResolver())
+    ? planHostForward(manifest, inputs, active, createBuiltInRenderTemplateResolver(), environment)
     : undefined;
   return {
     ...channelWithoutHostForward,
@@ -231,6 +239,7 @@ function runtimeSetupHasEntries(setup: SandboxMessagingRuntimeSetupPlan | undefi
 function agentRenderFromManifests(
   plan: SandboxMessagingPlan,
   manifestRegistry: ReturnType<typeof createBuiltInChannelManifestRegistry>,
+  environment: Readonly<Record<string, string | undefined>>,
 ): SandboxMessagingAgentRenderPlan[] {
   const render: SandboxMessagingAgentRenderPlan[] = [];
   const referenceResolver = createBuiltInRenderTemplateResolver();
@@ -239,7 +248,7 @@ function agentRenderFromManifests(
     if (!manifest) continue;
     const context = {
       inputs: channel.inputs,
-      env: process.env,
+      env: environment,
       referenceResolver,
     };
 

src/lib/messaging/index.ts

@@ -3,6 +3,7 @@
 
 export * from "./applier";
 export * from "./channels";
+export * from "./clone-rebind";
 export * from "./compiler";
 export * from "./diagnostics";
 export * from "./hooks";