From f234cae92159d0195358f102f5280ab1368f89ba Mon Sep 17 00:00:00 2001
From: Tinson Lai <tinsonl@nvidia.com>
Date: Tue, 4 Aug 2026 08:33:07 +0000
Subject: [PATCH 1/3] fix(sandbox): remove the incomplete snapshot when
 creation fails

Writing the manifest publishes a snapshot, and it ran before the failed
directories and state files were weighed, so a failed create left a listable
and restorable capture behind. Pass --keep-failed or set
NEMOCLAW_KEEP_FAILED_SNAPSHOT=1 to keep it for diagnosis. Rebuild and
backup-all keep their partial-manifest salvage.

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
---
 docs/manage-sandboxes/backup-restore.mdx      |   6 +
 docs/reference/commands.mdx                   |  12 ++
 src/commands/sandbox/snapshot.test.ts         |  11 +
 src/commands/sandbox/snapshot/create.ts       |  14 +-
 .../snapshot-failed-create-cleanup.test.ts    | 195 ++++++++++++++++++
 src/lib/actions/sandbox/snapshot.test.ts      |  21 --
 src/lib/actions/sandbox/snapshot.ts           |  39 +++-
 src/lib/cli/public-display-defaults.ts        |   2 +-
 ...andbox-incomplete-snapshot-removal.test.ts |  68 ++++++
 src/lib/state/sandbox.ts                      |  21 ++
 test/snapshot.test.ts                         |  33 +++
 11 files changed, 397 insertions(+), 25 deletions(-)
 create mode 100644 src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts
 create mode 100644 src/lib/state/sandbox-incomplete-snapshot-removal.test.ts

diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx
index 10f2d02d2d4..af02cd75eb0 100644
--- a/docs/manage-sandboxes/backup-restore.mdx
+++ b/docs/manage-sandboxes/backup-restore.mdx
@@ -100,6 +100,12 @@ Tag a snapshot with a human-readable label:
 $$nemoclaw my-assistant snapshot create --name before-upgrade
 ```
 
+When a directory or state file cannot be captured, `snapshot create` reports the failed items, removes the incomplete snapshot, and exits nonzero.
+`snapshot list` shows no new entry, so a later restore cannot select a capture that never completed.
+
+To keep the incomplete snapshot for diagnosis, pass `--keep-failed` or set `NEMOCLAW_KEEP_FAILED_SNAPSHOT=1`.
+A kept snapshot is listed and restorable like any other, so remove it once you no longer need it.
+
 ## Restore a Snapshot
 
 Restore the latest snapshot:
diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx
index 4d71c30eac9..e3222108b1c 100644
--- a/docs/reference/commands.mdx
+++ b/docs/reference/commands.mdx
@@ -2967,6 +2967,7 @@ $$nemoclaw my-assistant snapshot create
 | Flag | Description |
 |------|-------------|
 | `--name <label>` | Attach a human-readable label to the snapshot so you can restore by name later |
+| `--keep-failed` | Keep an incomplete snapshot on disk when creation fails, instead of removing it (also enabled by `NEMOCLAW_KEEP_FAILED_SNAPSHOT=1`) |
 
 Names must be 1 to 63 characters from `[A-Za-z0-9._-]`, start with an alphanumeric character, and cannot look like a version selector (`v1`, `v2`, ...). Duplicate names per sandbox are rejected; pick a different name or delete the existing snapshot first.
 
@@ -2974,6 +2975,16 @@ Names must be 1 to 63 characters from `[A-Za-z0-9._-]`, start with an alphanumer
 $$nemoclaw my-assistant snapshot create --name before-upgrade
 ```
 
+When a directory or state file cannot be captured, the command reports the failed items, removes the incomplete snapshot, and exits nonzero.
+A removed snapshot does not appear in `snapshot list` and cannot be restored, so a later restore cannot select a capture that never completed.
+
+Pass `--keep-failed` to keep the incomplete snapshot for diagnosis.
+The kept snapshot is listed and restorable like any other, and it shifts the computed version of every snapshot created after it, so remove it once you no longer need it.
+
+```bash
+$$nemoclaw my-assistant snapshot create --keep-failed
+```
+
 ### `$$nemoclaw <name> snapshot list`
 
 List available snapshots for a sandbox as a table of version, name, timestamp, and path.
@@ -4095,6 +4106,7 @@ The following flags change defaults for commands that manage existing sandboxes.
 | `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` | Exact JSON array of sandbox names | Confirms to the installer that the exact listed set of pre-fingerprint OpenClaw or Hermes sandboxes used NemoClaw-managed images, allowing recovery onto the current managed image. The normalized names must exactly match the installer's printed array. Set it only after verifying every named sandbox. Recorded custom-image evidence remains blocked. |
 | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `$$nemoclaw <name> connect` and `$$nemoclaw <name> connect --probe-only`. Use only as a troubleshooting escape hatch. |
 | `NEMOCLAW_DISABLE_SUPERVISOR_RELAUNCH` | `1` to enable | Skips the automatic trusted container recreation during `$$nemoclaw <name> recover` when two managed scans find no supervisor while PID 1 remains stable. Use only as a troubleshooting escape hatch; recovery then falls back to the rebuild or re-onboard guidance. |
+| `NEMOCLAW_KEEP_FAILED_SNAPSHOT` | Exactly `1` to opt in (`true`, `yes`, `0` are not accepted) | Keeps the incomplete snapshot on disk when `$$nemoclaw <name> snapshot create` fails, instead of removing it. Equivalent to passing `--keep-failed`. A kept snapshot is listed and restorable even though its capture did not complete, and it shifts the computed version of every snapshot created after it. |
 | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. |
 | `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0` to `10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `$$nemoclaw <name> shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. |
 | `NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP` | Exactly `1` to opt in (`true`, `yes`, `0` are not accepted) | Applies to standalone `$$nemoclaw backup-all` runs. Skips running sandboxes whose in-sandbox SSH endpoint does not answer. It does not relax the installer's strict pre-upgrade backup, which still aborts if any registered sandbox is skipped or fails. Any uncommitted state since the last successful backup is not included in the skipped backup. |
diff --git a/src/commands/sandbox/snapshot.test.ts b/src/commands/sandbox/snapshot.test.ts
index e93d1d24a03..c56ce024846 100644
--- a/src/commands/sandbox/snapshot.test.ts
+++ b/src/commands/sandbox/snapshot.test.ts
@@ -69,6 +69,17 @@ describe("snapshot oclif commands", () => {
     expect(runSandboxSnapshot).toHaveBeenCalledWith("alpha", {
       kind: "create",
       name: "before-upgrade",
+      keepFailed: false,
+    });
+  });
+
+  it("runs snapshot create asking to keep an incomplete snapshot", async () => {
+    await SnapshotCreateCommand.run(["alpha", "--keep-failed"], rootDir);
+
+    expect(runSandboxSnapshot).toHaveBeenCalledWith("alpha", {
+      kind: "create",
+      name: undefined,
+      keepFailed: true,
     });
   });
 });
diff --git a/src/commands/sandbox/snapshot/create.ts b/src/commands/sandbox/snapshot/create.ts
index 65ddcff5c58..00d1ece3320 100644
--- a/src/commands/sandbox/snapshot/create.ts
+++ b/src/commands/sandbox/snapshot/create.ts
@@ -15,22 +15,32 @@ export default class SnapshotCreateCommand extends NemoClawCommand {
   static strict = true;
   static summary = "Create a snapshot of sandbox state";
   static description = "Create an auto-versioned snapshot of sandbox workspace state.";
-  static usage = ["<name> [--name <label>]"];
+  static usage = ["<name> [--name <label>] [--keep-failed]"];
   static examples = [
     "<%= config.bin %> sandbox snapshot create alpha",
     "<%= config.bin %> sandbox snapshot create alpha --name before-upgrade",
+    "<%= config.bin %> sandbox snapshot create alpha --keep-failed",
   ];
   static args = {
     sandboxName: sandboxNameArg,
   };
   static flags = {
     name: Flags.string({ description: "Optional snapshot label" }),
+    "keep-failed": Flags.boolean({
+      description:
+        "Keep an incomplete snapshot on disk when creation fails, instead of removing it",
+      default: false,
+    }),
   };
 
   public async run(): Promise<void> {
     const { args, flags } = await this.parse(SnapshotCreateCommand);
     try {
-      await runSandboxSnapshot(args.sandboxName, { kind: "create", name: flags.name });
+      await runSandboxSnapshot(args.sandboxName, {
+        kind: "create",
+        name: flags.name,
+        keepFailed: flags["keep-failed"],
+      });
     } catch (error) {
       const snapshotError = snapshotCommandError(error);
       if (snapshotError) {
diff --git a/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts b/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts
new file mode 100644
index 00000000000..94527ccd63f
--- /dev/null
+++ b/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts
@@ -0,0 +1,195 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  backupSandboxState: vi.fn(),
+  captureOpenshell: vi.fn(() => ({ status: 0, output: "alpha Ready\n" })),
+  findBackup: vi.fn(() => ({ match: null })),
+  removeIncompleteSnapshot: vi.fn(
+    () =>
+      ({ removed: true }) as {
+        removed: boolean;
+        error?: string;
+      },
+  ),
+}));
+
+vi.mock("../../adapters/openshell/runtime", () => ({
+  captureOpenshell: mocks.captureOpenshell,
+  getOpenshellBinary: vi.fn(() => "openshell"),
+  runOpenshell: vi.fn(),
+}));
+
+vi.mock("../../runtime-recovery", () => ({
+  parseLiveSandboxNames: vi.fn(() => new Set(["alpha"])),
+}));
+
+vi.mock("../../shields", () => ({
+  isShieldsDown: vi.fn(() => true),
+}));
+
+vi.mock("../../shields/timer-bound-lock", () => ({
+  withTimerBoundShieldsMutationLock: vi.fn(
+    (_sandboxName: string, _command: string, operation: () => unknown) => operation(),
+  ),
+}));
+
+vi.mock("../../state/registry", () => ({
+  getBaselineExclusions: vi.fn(() => []),
+  getSandbox: vi.fn(() => ({ name: "alpha", agent: "openclaw" })),
+}));
+
+vi.mock("../../state/sandbox", () => ({
+  backupSandboxState: mocks.backupSandboxState,
+  findBackup: mocks.findBackup,
+  removeIncompleteSnapshot: mocks.removeIncompleteSnapshot,
+}));
+
+vi.mock("./sandbox-gateway-routing", () => ({
+  probeGatewayRunning: vi.fn(() => true),
+  selectSandboxGatewayIfRegistered: vi.fn(() => true),
+  usesGatewayMetadataProbe: vi.fn(() => false),
+}));
+
+const INCOMPLETE_PATH = "/home/user/.nemoclaw/rebuild-backups/alpha/2026-08-04T06-53-38-310Z";
+
+function failedCaptureWithPublishedSnapshot(overrides: Record<string, unknown> = {}) {
+  return {
+    success: false,
+    manifest: { backupPath: INCOMPLETE_PATH },
+    backedUpDirs: ["workspace"],
+    failedDirs: [],
+    backedUpFiles: [],
+    failedFiles: ["openclaw.json"],
+    ...overrides,
+  };
+}
+
+describe("snapshot create cleanup after a failed capture", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.removeIncompleteSnapshot.mockReturnValue({ removed: true });
+    mocks.findBackup.mockReturnValue({ match: null });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  async function createSnapshot(request: Record<string, unknown> = {}): Promise<string> {
+    const { runSandboxSnapshot } = await import("./snapshot");
+    await expect(runSandboxSnapshot("alpha", { kind: "create", ...request })).rejects.toMatchObject(
+      { exitCode: 1 },
+    );
+    return vi.mocked(console.error).mock.calls.flat().join("\n");
+  }
+
+  it("reports the failed directories and files", async () => {
+    mocks.backupSandboxState.mockReturnValue(
+      failedCaptureWithPublishedSnapshot({
+        failedDirs: ["workspace", "skills"],
+        failedDirReasons: { workspace: "permission denied" },
+      }),
+    );
+
+    const errors = await createSnapshot();
+
+    expect(errors).toContain("Snapshot failed.");
+    expect(errors).toContain("Failed directories: workspace (permission denied), skills");
+    expect(errors).toContain("Failed files: openclaw.json");
+  });
+
+  it("removes the snapshot so a later restore cannot select an incomplete capture (#8201)", async () => {
+    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
+
+    const errors = await createSnapshot();
+
+    expect(mocks.removeIncompleteSnapshot).toHaveBeenCalledWith(INCOMPLETE_PATH);
+    expect(errors).toContain("Removed the incomplete snapshot.");
+  });
+
+  it("keeps the snapshot when --keep-failed is passed", async () => {
+    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
+
+    const errors = await createSnapshot({ keepFailed: true });
+
+    expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
+    expect(errors).toContain(`Kept the incomplete snapshot at ${INCOMPLETE_PATH}.`);
+    expect(errors).toContain("can be restored even though its capture did not complete");
+  });
+
+  it("keeps the snapshot when NEMOCLAW_KEEP_FAILED_SNAPSHOT is exactly 1", async () => {
+    vi.stubEnv("NEMOCLAW_KEEP_FAILED_SNAPSHOT", "1");
+    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
+
+    await createSnapshot();
+
+    expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "true",
+    "yes",
+    "0",
+    "",
+  ])("removes the snapshot when NEMOCLAW_KEEP_FAILED_SNAPSHOT is %j", async (value) => {
+    vi.stubEnv("NEMOCLAW_KEEP_FAILED_SNAPSHOT", value);
+    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
+
+    await createSnapshot();
+
+    expect(mocks.removeIncompleteSnapshot).toHaveBeenCalledWith(INCOMPLETE_PATH);
+  });
+
+  it("names the snapshot that is still listed when removal fails", async () => {
+    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
+    mocks.removeIncompleteSnapshot.mockReturnValue({
+      removed: false,
+      error: "EACCES: permission denied",
+    });
+
+    const errors = await createSnapshot();
+
+    expect(errors).toContain(
+      `The incomplete snapshot at '${INCOMPLETE_PATH}' could not be removed: EACCES: permission denied`,
+    );
+    expect(errors).toContain("Remove it before the next restore.");
+  });
+
+  it("does not attempt removal when the capture failed before publishing a snapshot", async () => {
+    mocks.backupSandboxState.mockReturnValue({
+      success: false,
+      backedUpDirs: [],
+      failedDirs: [],
+      backedUpFiles: [],
+      failedFiles: [],
+      error: "Snapshot name 'dup' already exists.",
+    });
+
+    const errors = await createSnapshot();
+
+    expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
+    expect(errors).toContain("Snapshot name 'dup' already exists.");
+  });
+
+  it("does not touch a snapshot whose capture succeeded", async () => {
+    mocks.backupSandboxState.mockReturnValue({
+      success: true,
+      manifest: { backupPath: INCOMPLETE_PATH, timestamp: "2026-08-04T06-53-38-310Z" },
+      backedUpDirs: ["workspace"],
+      failedDirs: [],
+      backedUpFiles: ["openclaw.json"],
+      failedFiles: [],
+    });
+    const { runSandboxSnapshot } = await import("./snapshot");
+
+    await runSandboxSnapshot("alpha", { kind: "create", keepFailed: true });
+
+    expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/lib/actions/sandbox/snapshot.test.ts b/src/lib/actions/sandbox/snapshot.test.ts
index 19cf6428de0..4d402f1d9f0 100644
--- a/src/lib/actions/sandbox/snapshot.test.ts
+++ b/src/lib/actions/sandbox/snapshot.test.ts
@@ -1476,25 +1476,4 @@ describe("runSandboxSnapshot", () => {
       "Warning: could not reconcile custom policy(ies): old-custom (remove failed)",
     );
   });
-
-  it("prints failed dirs and files when snapshot creation fails without an error", async () => {
-    backupSandboxStateMock.mockReturnValue({
-      success: false,
-      failedDirs: ["workspace", "skills"],
-      failedDirReasons: { workspace: "permission denied" },
-      failedFiles: ["openclaw.json"],
-    });
-    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.spyOn(console, "log").mockImplementation(() => {});
-    const { runSandboxSnapshot } = await import("./snapshot");
-
-    await expect(runSandboxSnapshot("alpha", { kind: "create" })).rejects.toMatchObject({
-      exitCode: 1,
-    });
-
-    const errors = consoleError.mock.calls.flat().join("\n");
-    expect(errors).toContain("Snapshot failed.");
-    expect(errors).toContain("Failed directories: workspace (permission denied), skills");
-    expect(errors).toContain("Failed files: openclaw.json");
-  });
 });
diff --git a/src/lib/actions/sandbox/snapshot.ts b/src/lib/actions/sandbox/snapshot.ts
index 2a1f1562a80..d9574de7bb1 100644
--- a/src/lib/actions/sandbox/snapshot.ts
+++ b/src/lib/actions/sandbox/snapshot.ts
@@ -102,7 +102,7 @@ const R = useColor ? "\x1b[0m" : "";
 
 export type SnapshotRequest =
   | { kind: "help" }
-  | { kind: "create"; name?: string }
+  | { kind: "create"; name?: string; keepFailed?: boolean }
   | { kind: "list" }
   | {
       kind: "restore";
@@ -659,6 +659,39 @@ function isSnapshotCreationAllowedByDcodeActivity(sandboxName: string): boolean
   return false;
 }
 
+const KEEP_FAILED_SNAPSHOT_ENV = "NEMOCLAW_KEEP_FAILED_SNAPSHOT";
+
+function keepFailedSnapshotRequested(
+  request: Extract<SnapshotRequest, { kind: "create" }>,
+): boolean {
+  return request.keepFailed === true || process.env[KEEP_FAILED_SNAPSHOT_ENV] === "1";
+}
+
+function reportIncompleteSnapshot(
+  sandboxName: string,
+  backupPath: string,
+  keepFailed: boolean,
+): void {
+  if (keepFailed) {
+    console.error(`  Kept the incomplete snapshot at ${backupPath}.`);
+    console.error(
+      `  It is listed by \`${CLI_NAME} ${sandboxName} snapshot list\` and can be restored even though its capture did not complete.`,
+    );
+    return;
+  }
+  const removal = sandboxState.removeIncompleteSnapshot(backupPath);
+  if (removal.removed) {
+    console.error("  Removed the incomplete snapshot.");
+    return;
+  }
+  console.error(
+    `  The incomplete snapshot at '${backupPath}' could not be removed: ${removal.error}`,
+  );
+  console.error(
+    `  It is listed by \`${CLI_NAME} ${sandboxName} snapshot list\`. Remove it before the next restore.`,
+  );
+}
+
 function runSnapshotCreate(
   sandboxName: string,
   request: Extract<SnapshotRequest, { kind: "create" }>,
@@ -722,6 +755,10 @@ function runSnapshotCreate(
         console.error(`  Failed files: ${result.failedFiles.join(", ")}`);
       }
     }
+    const incompletePath = result.manifest?.backupPath;
+    if (incompletePath) {
+      reportIncompleteSnapshot(sandboxName, incompletePath, keepFailedSnapshotRequested(request));
+    }
     snapshotExit(1);
   });
 }
diff --git a/src/lib/cli/public-display-defaults.ts b/src/lib/cli/public-display-defaults.ts
index 161d980ae26..80df0c469f1 100644
--- a/src/lib/cli/public-display-defaults.ts
+++ b/src/lib/cli/public-display-defaults.ts
@@ -493,7 +493,7 @@ const PUBLIC_DISPLAY_LAYOUT: Record<string, readonly PublicDisplayLayout[]> = {
     {
       group: "Sandbox Management",
       order: 7,
-      flags: "[--name <name>]",
+      flags: "[--name <name>] [--keep-failed]",
     },
   ],
   "sandbox:snapshot:list": [
diff --git a/src/lib/state/sandbox-incomplete-snapshot-removal.test.ts b/src/lib/state/sandbox-incomplete-snapshot-removal.test.ts
new file mode 100644
index 00000000000..9ea4be5d45a
--- /dev/null
+++ b/src/lib/state/sandbox-incomplete-snapshot-removal.test.ts
@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { removeIncompleteSnapshot } from "./sandbox.js";
+
+const testDirectories: string[] = [];
+
+function createSnapshot(): string {
+  const backupPath = mkdtempSync(join(tmpdir(), "nemoclaw-incomplete-snapshot-"));
+  testDirectories.push(backupPath);
+  mkdirSync(join(backupPath, "workspace"), { recursive: true });
+  writeFileSync(join(backupPath, "rebuild-manifest.json"), "{}");
+  return backupPath;
+}
+
+afterEach(() => {
+  for (const testDirectory of testDirectories.splice(0)) {
+    rmSync(testDirectory, { recursive: true, force: true });
+  }
+});
+
+describe("incomplete snapshot removal", () => {
+  it("takes the snapshot and its captured content off disk", () => {
+    const backupPath = createSnapshot();
+
+    expect(removeIncompleteSnapshot(backupPath)).toEqual({ removed: true });
+    expect(existsSync(backupPath)).toBe(false);
+  });
+
+  it("reports success for a snapshot that is already gone", () => {
+    const backupPath = createSnapshot();
+    rmSync(backupPath, { recursive: true, force: true });
+
+    expect(removeIncompleteSnapshot(backupPath)).toEqual({ removed: true });
+  });
+
+  it("reports the reason when removal throws", () => {
+    const backupPath = createSnapshot();
+
+    const result = removeIncompleteSnapshot(backupPath, {
+      removeBackup: () => {
+        throw new Error("EACCES: permission denied");
+      },
+    });
+
+    expect(result).toEqual({ removed: false, error: "EACCES: permission denied" });
+    expect(existsSync(backupPath)).toBe(true);
+  });
+
+  it("reports failure when removal reports success but the snapshot remains", () => {
+    const backupPath = createSnapshot();
+
+    const result = removeIncompleteSnapshot(backupPath, {
+      removeBackup: () => undefined,
+    });
+
+    expect(result).toEqual({
+      removed: false,
+      error: "the snapshot directory still exists after removal",
+    });
+    expect(existsSync(backupPath)).toBe(true);
+  });
+});
diff --git a/src/lib/state/sandbox.ts b/src/lib/state/sandbox.ts
index 05fed8025a5..0266b95dd86 100644
--- a/src/lib/state/sandbox.ts
+++ b/src/lib/state/sandbox.ts
@@ -731,6 +731,27 @@ export function sanitizeBackupDirectory(
   }
 }
 
+export interface IncompleteSnapshotRemoval {
+  readonly removed: boolean;
+  readonly error?: string;
+}
+
+export function removeIncompleteSnapshot(
+  backupPath: string,
+  overrides: Partial<Pick<BackupSanitizationOperations, "removeBackup" | "backupExists">> = {},
+): IncompleteSnapshotRemoval {
+  const operations = { ...DEFAULT_BACKUP_SANITIZATION_OPERATIONS, ...overrides };
+  try {
+    operations.removeBackup(backupPath);
+  } catch (error) {
+    return { removed: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  if (operations.backupExists(backupPath)) {
+    return { removed: false, error: "the snapshot directory still exists after removal" };
+  }
+  return { removed: true };
+}
+
 // ── Logging ────────────────────────────────────────────────────────
 
 const _verbose = () => process.env.NEMOCLAW_REBUILD_VERBOSE === "1";
diff --git a/test/snapshot.test.ts b/test/snapshot.test.ts
index 26f7f05ee33..c53916f28bc 100644
--- a/test/snapshot.test.ts
+++ b/test/snapshot.test.ts
@@ -212,6 +212,39 @@ describe("listBackups computes virtual versions", () => {
     expect(entry.name).toBe("before-upgrade");
     expect(entry.snapshotVersion).toBe(1);
   });
+  it("stops listing a snapshot that was removed as incomplete (#8201)", () => {
+    const incomplete = writeBackup("test-sandbox", "2026-04-21T14-00-00-000Z", {
+      name: "failtest",
+    });
+    expect(sandboxState.listBackups("test-sandbox")).toHaveLength(1);
+
+    expect(sandboxState.removeIncompleteSnapshot(String(incomplete.backupPath))).toEqual({
+      removed: true,
+    });
+
+    expect(sandboxState.listBackups("test-sandbox")).toEqual([]);
+    expect(sandboxState.findBackup("test-sandbox", "failtest").match).toBeNull();
+    expect(fs.existsSync(String(incomplete.backupPath))).toBe(false);
+  });
+  it("restores the versions of surviving snapshots once an incomplete one is removed (#8201)", () => {
+    writeBackup("test-sandbox", "2026-04-21T14-01-00-000Z");
+    const incomplete = writeBackup("test-sandbox", "2026-04-21T14-05-00-000Z");
+    writeBackup("test-sandbox", "2026-04-21T14-10-00-000Z");
+    expect(sandboxState.listBackups("test-sandbox").map((b) => b.timestamp)).toEqual([
+      "2026-04-21T14-10-00-000Z",
+      "2026-04-21T14-05-00-000Z",
+      "2026-04-21T14-01-00-000Z",
+    ]);
+
+    sandboxState.removeIncompleteSnapshot(String(incomplete.backupPath));
+
+    expect(
+      sandboxState.listBackups("test-sandbox").map((b) => [b.snapshotVersion, b.timestamp]),
+    ).toEqual([
+      [2, "2026-04-21T14-10-00-000Z"],
+      [1, "2026-04-21T14-01-00-000Z"],
+    ]);
+  });
 
   it("surfaces customPolicies (name + content + sourcePath) through the manifest round-trip", () => {
     const custom = [

From 445426600c81c47b4138dd06f331ef341c4e5f93 Mon Sep 17 00:00:00 2001
From: Tinson Lai <tinsonl@nvidia.com>
Date: Wed, 5 Aug 2026 04:09:18 +0000
Subject: [PATCH 2/3] fix(sandbox): drop the incomplete-snapshot retention
 surface

Issue #8201 establishes removal of a failed snapshot as the accepted
outcome, and no accepted decision covers a supported flag and variable
that keep an incomplete snapshot listed and restorable. Cleanup is now
unconditional, and the docs describe the removal-failure path instead.

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
---
 docs/manage-sandboxes/backup-restore.mdx      |  4 +-
 docs/reference/commands.mdx                   | 10 +----
 src/commands/sandbox/snapshot.test.ts         | 11 -----
 src/commands/sandbox/snapshot/create.ts       | 14 +-----
 .../snapshot-failed-create-cleanup.test.ts    | 44 +++----------------
 src/lib/actions/sandbox/snapshot.ts           | 25 ++---------
 src/lib/cli/public-display-defaults.ts        |  2 +-
 7 files changed, 13 insertions(+), 97 deletions(-)

diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx
index 16266749866..02f74102b8c 100644
--- a/docs/manage-sandboxes/backup-restore.mdx
+++ b/docs/manage-sandboxes/backup-restore.mdx
@@ -108,9 +108,7 @@ $$nemoclaw my-assistant snapshot create --name before-upgrade
 
 When a directory or state file cannot be captured, `snapshot create` reports the failed items, removes the incomplete snapshot, and exits nonzero.
 `snapshot list` shows no new entry, so a later restore cannot select a capture that never completed.
-
-To keep the incomplete snapshot for diagnosis, pass `--keep-failed` or set `NEMOCLAW_KEEP_FAILED_SNAPSHOT=1`.
-A kept snapshot is listed and restorable like any other, so remove it once you no longer need it.
+If the removal itself fails, the command names the path that is still listed and asks you to remove it before the next restore.
 
 ## Restore a Snapshot
 
diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx
index de748c5a3aa..00ad0978d17 100644
--- a/docs/reference/commands.mdx
+++ b/docs/reference/commands.mdx
@@ -3004,7 +3004,6 @@ $$nemoclaw my-assistant snapshot create
 | Flag | Description |
 |------|-------------|
 | `--name <label>` | Attach a human-readable label to the snapshot so you can restore by name later |
-| `--keep-failed` | Keep an incomplete snapshot on disk when creation fails, instead of removing it (also enabled by `NEMOCLAW_KEEP_FAILED_SNAPSHOT=1`) |
 
 Names must be 1 to 63 characters from `[A-Za-z0-9._-]`, start with an alphanumeric character, and cannot look like a version selector (`v1`, `v2`, ...). Duplicate names per sandbox are rejected; pick a different name or delete the existing snapshot first.
 
@@ -3014,13 +3013,7 @@ $$nemoclaw my-assistant snapshot create --name before-upgrade
 
 When a directory or state file cannot be captured, the command reports the failed items, removes the incomplete snapshot, and exits nonzero.
 A removed snapshot does not appear in `snapshot list` and cannot be restored, so a later restore cannot select a capture that never completed.
-
-Pass `--keep-failed` to keep the incomplete snapshot for diagnosis.
-The kept snapshot is listed and restorable like any other, and it shifts the computed version of every snapshot created after it, so remove it once you no longer need it.
-
-```bash
-$$nemoclaw my-assistant snapshot create --keep-failed
-```
+When the removal itself fails, the command reports the path that is still listed and asks you to remove it before the next restore, and the exit code stays nonzero.
 
 ### `$$nemoclaw <name> snapshot list`
 
@@ -4148,7 +4141,6 @@ The following flags change defaults for commands that manage existing sandboxes.
 | `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` | Exact JSON array of sandbox names | Confirms to the installer that the exact listed set of pre-fingerprint OpenClaw or Hermes sandboxes used NemoClaw-managed images, allowing recovery onto the current managed image. The normalized names must exactly match the installer's printed array. Set it only after verifying every named sandbox. Recorded custom-image evidence remains blocked. |
 | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `$$nemoclaw <name> connect` and `$$nemoclaw <name> connect --probe-only`. Use only as a troubleshooting escape hatch. |
 | `NEMOCLAW_DISABLE_SUPERVISOR_RELAUNCH` | `1` to enable | Skips the automatic trusted container recreation during `$$nemoclaw <name> recover` when two managed scans find no supervisor while PID 1 remains stable. Use only as a troubleshooting escape hatch; recovery then falls back to the rebuild or re-onboard guidance. |
-| `NEMOCLAW_KEEP_FAILED_SNAPSHOT` | Exactly `1` to opt in (`true`, `yes`, `0` are not accepted) | Keeps the incomplete snapshot on disk when `$$nemoclaw <name> snapshot create` fails, instead of removing it. Equivalent to passing `--keep-failed`. A kept snapshot is listed and restorable even though its capture did not complete, and it shifts the computed version of every snapshot created after it. |
 | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. |
 | `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0` to `10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `$$nemoclaw <name> shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. |
 | `NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP` | Exactly `1` to opt in (`true`, `yes`, `0` are not accepted) | Applies to standalone `$$nemoclaw backup-all` runs. Skips running sandboxes whose in-sandbox SSH endpoint does not answer. It does not relax the installer's strict pre-upgrade backup, which still aborts if any registered sandbox is skipped or fails. Any uncommitted state since the last successful backup is not included in the skipped backup. |
diff --git a/src/commands/sandbox/snapshot.test.ts b/src/commands/sandbox/snapshot.test.ts
index c56ce024846..e93d1d24a03 100644
--- a/src/commands/sandbox/snapshot.test.ts
+++ b/src/commands/sandbox/snapshot.test.ts
@@ -69,17 +69,6 @@ describe("snapshot oclif commands", () => {
     expect(runSandboxSnapshot).toHaveBeenCalledWith("alpha", {
       kind: "create",
       name: "before-upgrade",
-      keepFailed: false,
-    });
-  });
-
-  it("runs snapshot create asking to keep an incomplete snapshot", async () => {
-    await SnapshotCreateCommand.run(["alpha", "--keep-failed"], rootDir);
-
-    expect(runSandboxSnapshot).toHaveBeenCalledWith("alpha", {
-      kind: "create",
-      name: undefined,
-      keepFailed: true,
     });
   });
 });
diff --git a/src/commands/sandbox/snapshot/create.ts b/src/commands/sandbox/snapshot/create.ts
index 00d1ece3320..65ddcff5c58 100644
--- a/src/commands/sandbox/snapshot/create.ts
+++ b/src/commands/sandbox/snapshot/create.ts
@@ -15,32 +15,22 @@ export default class SnapshotCreateCommand extends NemoClawCommand {
   static strict = true;
   static summary = "Create a snapshot of sandbox state";
   static description = "Create an auto-versioned snapshot of sandbox workspace state.";
-  static usage = ["<name> [--name <label>] [--keep-failed]"];
+  static usage = ["<name> [--name <label>]"];
   static examples = [
     "<%= config.bin %> sandbox snapshot create alpha",
     "<%= config.bin %> sandbox snapshot create alpha --name before-upgrade",
-    "<%= config.bin %> sandbox snapshot create alpha --keep-failed",
   ];
   static args = {
     sandboxName: sandboxNameArg,
   };
   static flags = {
     name: Flags.string({ description: "Optional snapshot label" }),
-    "keep-failed": Flags.boolean({
-      description:
-        "Keep an incomplete snapshot on disk when creation fails, instead of removing it",
-      default: false,
-    }),
   };
 
   public async run(): Promise<void> {
     const { args, flags } = await this.parse(SnapshotCreateCommand);
     try {
-      await runSandboxSnapshot(args.sandboxName, {
-        kind: "create",
-        name: flags.name,
-        keepFailed: flags["keep-failed"],
-      });
+      await runSandboxSnapshot(args.sandboxName, { kind: "create", name: flags.name });
     } catch (error) {
       const snapshotError = snapshotCommandError(error);
       if (snapshotError) {
diff --git a/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts b/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts
index 94527ccd63f..ea8cfffe562 100644
--- a/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts
+++ b/src/lib/actions/sandbox/snapshot-failed-create-cleanup.test.ts
@@ -78,14 +78,13 @@ describe("snapshot create cleanup after a failed capture", () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
-    vi.unstubAllEnvs();
   });
 
-  async function createSnapshot(request: Record<string, unknown> = {}): Promise<string> {
+  async function createSnapshot(): Promise<string> {
     const { runSandboxSnapshot } = await import("./snapshot");
-    await expect(runSandboxSnapshot("alpha", { kind: "create", ...request })).rejects.toMatchObject(
-      { exitCode: 1 },
-    );
+    await expect(runSandboxSnapshot("alpha", { kind: "create" })).rejects.toMatchObject({
+      exitCode: 1,
+    });
     return vi.mocked(console.error).mock.calls.flat().join("\n");
   }
 
@@ -113,39 +112,6 @@ describe("snapshot create cleanup after a failed capture", () => {
     expect(errors).toContain("Removed the incomplete snapshot.");
   });
 
-  it("keeps the snapshot when --keep-failed is passed", async () => {
-    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
-
-    const errors = await createSnapshot({ keepFailed: true });
-
-    expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
-    expect(errors).toContain(`Kept the incomplete snapshot at ${INCOMPLETE_PATH}.`);
-    expect(errors).toContain("can be restored even though its capture did not complete");
-  });
-
-  it("keeps the snapshot when NEMOCLAW_KEEP_FAILED_SNAPSHOT is exactly 1", async () => {
-    vi.stubEnv("NEMOCLAW_KEEP_FAILED_SNAPSHOT", "1");
-    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
-
-    await createSnapshot();
-
-    expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
-  });
-
-  it.each([
-    "true",
-    "yes",
-    "0",
-    "",
-  ])("removes the snapshot when NEMOCLAW_KEEP_FAILED_SNAPSHOT is %j", async (value) => {
-    vi.stubEnv("NEMOCLAW_KEEP_FAILED_SNAPSHOT", value);
-    mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
-
-    await createSnapshot();
-
-    expect(mocks.removeIncompleteSnapshot).toHaveBeenCalledWith(INCOMPLETE_PATH);
-  });
-
   it("names the snapshot that is still listed when removal fails", async () => {
     mocks.backupSandboxState.mockReturnValue(failedCaptureWithPublishedSnapshot());
     mocks.removeIncompleteSnapshot.mockReturnValue({
@@ -188,7 +154,7 @@ describe("snapshot create cleanup after a failed capture", () => {
     });
     const { runSandboxSnapshot } = await import("./snapshot");
 
-    await runSandboxSnapshot("alpha", { kind: "create", keepFailed: true });
+    await runSandboxSnapshot("alpha", { kind: "create" });
 
     expect(mocks.removeIncompleteSnapshot).not.toHaveBeenCalled();
   });
diff --git a/src/lib/actions/sandbox/snapshot.ts b/src/lib/actions/sandbox/snapshot.ts
index 09e8a9e4c10..6ec7fb850bb 100644
--- a/src/lib/actions/sandbox/snapshot.ts
+++ b/src/lib/actions/sandbox/snapshot.ts
@@ -102,7 +102,7 @@ const R = useColor ? "\x1b[0m" : "";
 
 export type SnapshotRequest =
   | { kind: "help" }
-  | { kind: "create"; name?: string; keepFailed?: boolean }
+  | { kind: "create"; name?: string }
   | { kind: "list" }
   | {
       kind: "restore";
@@ -659,26 +659,7 @@ function isSnapshotCreationAllowedByDcodeActivity(sandboxName: string): boolean
   return false;
 }
 
-const KEEP_FAILED_SNAPSHOT_ENV = "NEMOCLAW_KEEP_FAILED_SNAPSHOT";
-
-function keepFailedSnapshotRequested(
-  request: Extract<SnapshotRequest, { kind: "create" }>,
-): boolean {
-  return request.keepFailed === true || process.env[KEEP_FAILED_SNAPSHOT_ENV] === "1";
-}
-
-function reportIncompleteSnapshot(
-  sandboxName: string,
-  backupPath: string,
-  keepFailed: boolean,
-): void {
-  if (keepFailed) {
-    console.error(`  Kept the incomplete snapshot at ${backupPath}.`);
-    console.error(
-      `  It is listed by \`${CLI_NAME} ${sandboxName} snapshot list\` and can be restored even though its capture did not complete.`,
-    );
-    return;
-  }
+function removeIncompleteSnapshot(sandboxName: string, backupPath: string): void {
   const removal = sandboxState.removeIncompleteSnapshot(backupPath);
   if (removal.removed) {
     console.error("  Removed the incomplete snapshot.");
@@ -757,7 +738,7 @@ function runSnapshotCreate(
     }
     const incompletePath = result.manifest?.backupPath;
     if (incompletePath) {
-      reportIncompleteSnapshot(sandboxName, incompletePath, keepFailedSnapshotRequested(request));
+      removeIncompleteSnapshot(sandboxName, incompletePath);
     }
     snapshotExit(1);
   });
diff --git a/src/lib/cli/public-display-defaults.ts b/src/lib/cli/public-display-defaults.ts
index 80df0c469f1..161d980ae26 100644
--- a/src/lib/cli/public-display-defaults.ts
+++ b/src/lib/cli/public-display-defaults.ts
@@ -493,7 +493,7 @@ const PUBLIC_DISPLAY_LAYOUT: Record<string, readonly PublicDisplayLayout[]> = {
     {
       group: "Sandbox Management",
       order: 7,
-      flags: "[--name <name>] [--keep-failed]",
+      flags: "[--name <name>]",
     },
   ],
   "sandbox:snapshot:list": [

From e2647faa5aa32d9ce3f06cb9675d7b21bafc1344 Mon Sep 17 00:00:00 2001
From: Apurv Kumaria <akumaria@nvidia.com>
Date: Wed, 5 Aug 2026 02:04:05 -0700
Subject: [PATCH 3/3] docs(snapshot): clarify failed cleanup recovery

Signed-off-by: Apurv Kumaria <akumaria@nvidia.com>
---
 docs/manage-sandboxes/backup-restore.mdx | 3 ++-
 docs/reference/commands.mdx              | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx
index 02f74102b8c..74022a9c8db 100644
--- a/docs/manage-sandboxes/backup-restore.mdx
+++ b/docs/manage-sandboxes/backup-restore.mdx
@@ -108,7 +108,8 @@ $$nemoclaw my-assistant snapshot create --name before-upgrade
 
 When a directory or state file cannot be captured, `snapshot create` reports the failed items, removes the incomplete snapshot, and exits nonzero.
 `snapshot list` shows no new entry, so a later restore cannot select a capture that never completed.
-If the removal itself fails, the command names the path that is still listed and asks you to remove it before the next restore.
+If removal fails, the command reports the listed snapshot path.
+Remove that directory manually before you run `snapshot restore` because the incomplete capture remains selectable.
 
 ## Restore a Snapshot
 
diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx
index bcadf2ace81..511bf0d3f09 100644
--- a/docs/reference/commands.mdx
+++ b/docs/reference/commands.mdx
@@ -3021,7 +3021,8 @@ $$nemoclaw my-assistant snapshot create --name before-upgrade
 
 When a directory or state file cannot be captured, the command reports the failed items, removes the incomplete snapshot, and exits nonzero.
 A removed snapshot does not appear in `snapshot list` and cannot be restored, so a later restore cannot select a capture that never completed.
-When the removal itself fails, the command reports the path that is still listed and asks you to remove it before the next restore, and the exit code stays nonzero.
+When removal fails, the command reports the listed snapshot path and exits nonzero.
+Remove that directory manually before you run `snapshot restore` because the incomplete capture remains selectable.
 
 ### `$$nemoclaw <name> snapshot list`