fix(sandbox): re-establish gateway pairing after cross-sandbox snapshot restore

docs/manage-sandboxes/backup-restore.mdx

@@ -129,8 +129,11 @@ During rebuild or restore, NemoClaw merges those settings with the freshly gener
 If the restored config cannot be parsed or applied safely, NemoClaw stops the restore instead of replacing the generated config with an unsafe fallback.
 
 OpenClaw's device identity keys and paired-device tokens are intentionally excluded from snapshots because backup sanitization scrubs them beyond use.
-Restore never touches the sandbox's current gateway pairing state, even when an older snapshot still contains those files.
-OpenClaw regenerates its device identity on demand, and NemoClaw auto-pair re-pairs CLI clients on connect.
+Snapshot state replacement does not overwrite the destination sandbox's gateway pairing files, even when an older snapshot still contains them.
+After a cross-sandbox restore creates the destination, NemoClaw establishes gateway pairing and verifies it with an authenticated agent run.
+If verification fails, the restored state remains in the destination and the command exits nonzero.
+Run `$$nemoclaw <destination> connect` to retry pairing before you run an agent.
+OpenClaw regenerates its device identity on demand.
 </AgentOnly>
 <AgentOnly variant="hermes">
 Credential-bearing Hermes files such as `auth.json` are intentionally excluded from snapshots.

src/lib/actions/sandbox/restore-gateway-pairing.test.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  establishRestoredSandboxGatewayPairing,
+  RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT,
+  RESTORE_GATEWAY_PAIRING_VERIFY_TIMEOUT_MS,
+} from "./restore-gateway-pairing";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("establishRestoredSandboxGatewayPairing", () => {
+  it("provokes the scope upgrade before approving it", () => {
+    const order: string[] = [];
+    const warmupScopeUpgrade = vi.fn(() => order.push("warmup"));
+    const autoPairScopeApproval = vi.fn(() => order.push("approve"));
+    const verifyGatewayPairing = vi.fn(() => {
+      order.push("verify");
+      return true;
+    });
+
+    establishRestoredSandboxGatewayPairing("beta", {
+      warmupScopeUpgrade,
+      autoPairScopeApproval,
+      verifyGatewayPairing,
+    });
+
+    expect(warmupScopeUpgrade).toHaveBeenCalledWith("beta");
+    expect(autoPairScopeApproval).toHaveBeenCalledWith("beta");
+    expect(verifyGatewayPairing).toHaveBeenCalledWith("beta");
+    expect(order).toEqual(["warmup", "approve", "verify"]);
+  });
+
+  it("fails when the pairing warm-up does not complete", () => {
+    const warmupScopeUpgrade = vi.fn(() => {
+      throw new Error("gateway not up");
+    });
+    const autoPairScopeApproval = vi.fn();
+    const verifyGatewayPairing = vi.fn(() => true);
+
+    expect(() =>
+      establishRestoredSandboxGatewayPairing("beta", {
+        warmupScopeUpgrade,
+        autoPairScopeApproval,
+        verifyGatewayPairing,
+      }),
+    ).toThrow("gateway not up");
+    expect(autoPairScopeApproval).not.toHaveBeenCalled();
+    expect(verifyGatewayPairing).not.toHaveBeenCalled();
+  });
+
+  it("fails when the authenticated verification run cannot use the restored gateway", () => {
+    expect(() =>
+      establishRestoredSandboxGatewayPairing("beta", {
+        warmupScopeUpgrade: vi.fn(),
+        autoPairScopeApproval: vi.fn(),
+        verifyGatewayPairing: vi.fn(() => false),
+      }),
+    ).toThrow("authenticated gateway verification run did not succeed");
+  });
+
+  it("verifies the gateway without forcing a new pairing request", () => {
+    expect(RESTORE_GATEWAY_PAIRING_VERIFY_TIMEOUT_MS).toBe(30_000);
+    expect(RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT).toContain("openclaw agent --agent main --json");
+    expect(RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT).toContain("scope upgrade pending approval");
+    expect(RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT).toContain("transport");
+    expect(RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT).not.toContain(
+      "NEMOCLAW_OPENCLAW_FORCE_DEVICE_PAIRING",
+    );
+  });
+});

src/lib/actions/sandbox/restore-gateway-pairing.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { spawnSync } from "node:child_process";
+
+import { ROOT } from "../../state/paths";
+import { WARMUP_SESSION_ID_PREFIX } from "./warmup-session";
+
+export const RESTORE_GATEWAY_PAIRING_VERIFY_TIMEOUT_MS = 30_000;
+
+export const RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT = `
+PROXY_ENV=/tmp/nemoclaw-proxy-env.sh
+[ -r "$PROXY_ENV" ] && . "$PROXY_ENV"
+command -v openclaw >/dev/null 2>&1 || exit 1
+output="$(
+  openclaw agent --agent main --json -m "ping" \
+    --session-id "${WARMUP_SESSION_ID_PREFIX}restore-verify-$$-$(date +%s)" 2>&1
+)"
+status=$?
+[ "$status" -eq 0 ] || exit 1
+if printf '%s\n' "$output" | grep -Eiq \
+  'EMBEDDED FALLBACK|gateway connect failed|scope upgrade pending approval|device pairing required|pairing required|fallbackFrom[": ]+gateway|transport[": ]+embedded'; then
+  exit 1
+fi
+exit 0
+`;
+
+export type RestoreGatewayPairingDeps = {
+  warmupScopeUpgrade: (sandboxName: string) => void;
+  autoPairScopeApproval: (sandboxName: string) => void;
+  verifyGatewayPairing: (sandboxName: string) => boolean;
+};
+
+function defaultRestoreGatewayPairingDeps(): RestoreGatewayPairingDeps {
+  const warmup: typeof import("./auto-pair-warmup") = require("./auto-pair-warmup");
+  const connect: typeof import("./connect") = require("./connect");
+  return {
+    warmupScopeUpgrade: warmup.runSandboxScopeWarmupRun,
+    autoPairScopeApproval: connect.runConnectAutoPairApprovalPass,
+    verifyGatewayPairing: verifyRestoredSandboxGatewayPairing,
+  };
+}
+
+export function verifyRestoredSandboxGatewayPairing(targetSandbox: string): boolean {
+  const { resolveOpenshell } =
+    require("../../adapters/openshell/resolve") as typeof import("../../adapters/openshell/resolve");
+  try {
+    const openshellBinary = resolveOpenshell();
+    if (!openshellBinary) return false;
+    const result = spawnSync(
+      openshellBinary,
+      [
+        "sandbox",
+        "exec",
+        "--name",
+        targetSandbox,
+        "--",
+        "sh",
+        "-c",
+        RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT,
+      ],
+      {
+        cwd: ROOT,
+        env: process.env,
+        stdio: ["ignore", "ignore", "ignore"],
+        timeout: RESTORE_GATEWAY_PAIRING_VERIFY_TIMEOUT_MS,
+      },
+    );
+    return result.status === 0 && result.error === undefined;
+  } catch {
+    return false;
+  }
+}
+
+export function establishRestoredSandboxGatewayPairing(
+  targetSandbox: string,
+  deps: RestoreGatewayPairingDeps = defaultRestoreGatewayPairingDeps(),
+): void {
+  try {
+    deps.warmupScopeUpgrade(targetSandbox);
+    deps.autoPairScopeApproval(targetSandbox);
+    if (!deps.verifyGatewayPairing(targetSandbox)) {
+      throw new Error("the authenticated gateway verification run did not succeed");
+    }
+  } catch (err) {
+    throw new Error(
+      `could not establish gateway pairing for '${targetSandbox}': ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}

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

@@ -5,7 +5,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import * as f from "./snapshot-restore-test-fixture";
 
-beforeEach(f.resetSnapshotRestoreMocks);
+beforeEach(() => {
+  f.resetSnapshotRestoreMocks();
+});
 afterEach(f.cleanupSnapshotRestoreMocks);
 describe("runSandboxSnapshot restore: lifecycle and destination safety", () => {
   it("restores the latest snapshot into the source sandbox", async () => {
@@ -188,3 +190,106 @@ describe("runSandboxSnapshot restore: lifecycle and destination safety", () => {
     expect(f.registerSandboxMock).not.toHaveBeenCalled();
   });
 });
+
+describe("runSandboxSnapshot restore: gateway pairing on a freshly created destination", () => {
+  it("provokes and approves device pairing after a cross-sandbox restore", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    f.getSandboxMock.mockImplementation((name) =>
+      name === "alpha"
+        ? {
+            name: "alpha",
+            agent: "openclaw",
+            imageTag: "nemoclaw-alpha:test",
+            openshellDriver: "docker",
+            provider: "nvidia-nim",
+            model: "nvidia/model-a",
+          }
+        : null,
+    );
+    f.parseLiveSandboxNamesMock.mockReturnValue(new Set(["alpha"]));
+    f.captureOpenshellMock.mockImplementation((args) =>
+      f.openshellResponses(args, {
+        "sandbox exec": { status: 0, output: f.dcodeProbeOutput("no-runtime") },
+        "sandbox list": { status: 0, output: "alpha Ready\nbeta Ready\n" },
+      }),
+    );
+    f.getLatestBackupMock.mockReturnValue({ ...f.latestBackupFixture });
+    f.restoreSandboxStateMock.mockReturnValue({
+      success: true,
+      restoredDirs: ["workspace"],
+      restoredFiles: ["user.md"],
+      failedDirs: [],
+      failedFiles: [],
+    });
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await runSandboxSnapshot("alpha", { kind: "restore", to: "beta", yes: true });
+
+    expect(f.restoreSandboxStateMock).toHaveBeenCalledWith("beta", "/tmp/backup-alpha");
+    expect(f.establishRestoredSandboxGatewayPairingMock).toHaveBeenCalledWith("beta");
+  });
+
+  it("fails with repair guidance when restored gateway pairing cannot be verified", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    f.getSandboxMock.mockImplementation((name) =>
+      name === "alpha"
+        ? {
+            name: "alpha",
+            agent: "openclaw",
+            imageTag: "nemoclaw-alpha:test",
+            openshellDriver: "docker",
+            provider: "nvidia-nim",
+            model: "nvidia/model-a",
+          }
+        : null,
+    );
+    f.parseLiveSandboxNamesMock.mockReturnValue(new Set(["alpha"]));
+    f.captureOpenshellMock.mockImplementation((args) =>
+      f.openshellResponses(args, {
+        "sandbox exec": { status: 0, output: f.dcodeProbeOutput("no-runtime") },
+        "sandbox list": { status: 0, output: "alpha Ready\nbeta Ready\n" },
+      }),
+    );
+    f.getLatestBackupMock.mockReturnValue({ ...f.latestBackupFixture });
+    f.restoreSandboxStateMock.mockReturnValue({
+      success: true,
+      restoredDirs: ["workspace"],
+      restoredFiles: ["user.md"],
+      failedDirs: [],
+      failedFiles: [],
+    });
+    f.establishRestoredSandboxGatewayPairingMock.mockImplementationOnce(() => {
+      throw new Error("authenticated gateway verification failed");
+    });
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await expect(
+      runSandboxSnapshot("alpha", { kind: "restore", to: "beta", yes: true }),
+    ).rejects.toMatchObject({
+      exitCode: 1,
+      lines: [
+        "State restored into 'beta', but gateway pairing could not be verified.",
+        "Run `nemoclaw beta connect` to retry pairing before running an agent.",
+        expect.stringContaining("authenticated gateway verification failed"),
+      ],
+    });
+  });
+
+  it("leaves the working gateway credentials untouched on a self-restore", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    f.getLatestBackupMock.mockReturnValue({ ...f.latestBackupFixture });
+    f.restoreSandboxStateMock.mockReturnValue({
+      success: true,
+      restoredDirs: ["workspace"],
+      restoredFiles: ["user.md"],
+      failedDirs: [],
+      failedFiles: [],
+    });
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await runSandboxSnapshot("alpha", { kind: "restore" });
+
+    expect(f.restoreSandboxStateMock).toHaveBeenCalledWith("alpha", "/tmp/backup-alpha");
+    expect(f.establishRestoredSandboxGatewayPairingMock).not.toHaveBeenCalled();
+  });
+});

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

@@ -108,6 +108,7 @@ export const captureOpenshellMock = vi.fn<
   (args: string[], opts?: Record<string, unknown>) => OpenshellCaptureResult
 >((args) => defaultOpenshellResponses(args));
 export const dockerInspectMock = vi.fn(() => ({ status: 0, stdout: "true\n" }));
+export const establishRestoredSandboxGatewayPairingMock = vi.fn();
 export const findBackupMock = vi.fn();
 export const getAppliedPresetsMock = vi.fn(() => [] as string[]);
 export const getCustomPoliciesMock = vi.fn(
@@ -247,6 +248,10 @@ vi.mock("./destroy", () => ({
   removeSandboxRegistryEntry: vi.fn(),
 }));
 
+vi.mock("./restore-gateway-pairing", () => ({
+  establishRestoredSandboxGatewayPairing: establishRestoredSandboxGatewayPairingMock,
+}));
+
 export function resetSnapshotRestoreMocks(): void {
   vi.clearAllMocks();
   shieldsMock.setIsShieldsDownExport(shieldsMock.isShieldsDownMock);
@@ -256,6 +261,7 @@ export function resetSnapshotRestoreMocks(): void {
   lifecycleMock.readTimerMarkerMock.mockReturnValue(null);
   captureOpenshellMock.mockImplementation((args) => defaultOpenshellResponses(args));
   dockerInspectMock.mockReturnValue({ status: 0, stdout: "true\n" });
+  establishRestoredSandboxGatewayPairingMock.mockReset();
   findBackupMock.mockReturnValue({ match: null });
   getAppliedPresetsMock.mockReturnValue([]);
   getCustomPoliciesMock.mockReturnValue([]);

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

@@ -236,6 +236,10 @@ vi.mock("../../state/sandbox", () => ({
   restoreSandboxState: restoreSandboxStateMock,
 }));
 
+vi.mock("./restore-gateway-pairing", () => ({
+  establishRestoredSandboxGatewayPairing: vi.fn(),
+}));
+
 vi.mock("./destroy", () => ({
   cleanupShieldsDestroyArtifacts: lifecycleMock.cleanupShieldsDestroyArtifactsMock,
   removeSandboxRegistryEntry: vi.fn(),

src/lib/actions/sandbox/snapshot.ts

@@ -61,6 +61,7 @@ import {
   parseDcodeProbeState,
 } from "./dcode-activity-probe";
 import { cleanupShieldsDestroyArtifacts, removeSandboxRegistryEntry } from "./destroy";
+import { establishRestoredSandboxGatewayPairing } from "./restore-gateway-pairing";
 import {
   buildSandboxExecMarkedCommand,
   createSandboxExecMarker,
@@ -1099,6 +1100,18 @@ async function runSnapshotRestoreUnlocked(
     // managed observability binding from current target state.
     reconcileSnapshotPolicyPresets(targetSandbox, resolvedSnapshot);
   });
+  if (isCrossSandboxRestore) {
+    try {
+      establishRestoredSandboxGatewayPairing(targetSandbox);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new SnapshotCommandError([
+        `State restored into '${targetSandbox}', but gateway pairing could not be verified.`,
+        `Run \`${CLI_NAME} ${targetSandbox} connect\` to retry pairing before running an agent.`,
+        `Details: ${detail}`,
+      ]);
+    }
+  }
 }
 
 export async function runSandboxSnapshot(