fix(snapshot): name the python3 prerequisite when sanitization cannot run

Snapshot sanitization runs through a trusted python3 helper. When no
interpreter resolved, the helper reported that the same way it reports a
helper that ran and failed, so `snapshot create` printed "Credential
sanitization failed; removed the incomplete backup" and never named the
prerequisite.

The boundary that owns interpreter resolution now raises
SnapshotSanitizerPrerequisiteError, both sanitizers raise through it, and
the backup wrapper keeps that sentence in the message it rethrows.

Refs: #8202
Signed-off-by: harjoth <harjoth.khara@gmail.com>

Author: harjothkhara

docs/reference/troubleshooting.mdx

@@ -1631,6 +1631,22 @@ $$nemoclaw <name> snapshot create
 $$nemoclaw <name> rebuild
 ```
 
+### Snapshot creation reports that `python3` is required
+
+Commands that write a host-side snapshot stop with this message when no verified interpreter resolves:
+
+```text
+python3 is required for snapshot sanitization; install python3 and retry
+```
+
+The message covers `$$nemoclaw <name> snapshot create`, `$$nemoclaw <name> rebuild`, and the automatic backups that NemoClaw takes before maintenance and before it backs up a stopped sandbox.
+NemoClaw removes credentials from copied state with an isolated `python3` helper, and it fails closed when that helper cannot run.
+
+A host that already has `python3` can still report this message.
+NemoClaw does not resolve this credential-bearing helper through `PATH`, so an interpreter from a version manager or a virtual environment does not qualify.
+Install `python3` at one of the accepted locations in [Prerequisites](../get-started/prerequisites).
+Then run the command again.
+
 ### Sandbox shows as stopped
 
 When status reports `sandbox_container_stopped`, Docker still has a container for the sandbox, but the container is not running.

nemoclaw/src/security/snapshot-sanitizer-failure.test.ts

@@ -95,6 +95,16 @@ describe("migration snapshot sanitizer fallbacks", () => {
     expect(readFileSync(configPath, "utf-8")).toBe(original);
   });
 
+  it("names the python3 prerequisite when the migration scan finds no interpreter (#8202)", () => {
+    const root = makeRoot();
+    writeFileSync(path.join(root, "openclaw.json"), JSON.stringify({ apiKey: "sk-secret-value" }));
+    setSnapshotSanitizerPythonPathForTest(null);
+
+    expect(() => sanitizeMigrationDirectory(root)).toThrow(
+      "python3 is required for snapshot sanitization; install python3 and retry",
+    );
+  });
+
   it("fails closed when the descriptor apply helper is unavailable", () => {
     const root = { canonicalPath: makeRoot(), identity };
     setSnapshotSanitizerPythonPathForTest(null);

nemoclaw/src/security/snapshot-sanitizer.ts

@@ -13,6 +13,7 @@ import {
   type SnapshotSanitizationAction,
   type SnapshotScannedFile,
   scanDescriptorSnapshot,
+  snapshotSanitizerFailure,
 } from "../shared/snapshot-sanitizer-boundary.cjs";
 import {
   CREDENTIAL_PLACEHOLDER,
@@ -96,14 +97,14 @@ export function sanitizeMigrationDirectory(rootPath: string): void {
     }
     const scan = scanDescriptorSnapshot(root, CREDENTIAL_SENSITIVE_BASENAMES);
     if (scan === null) {
-      throw new Error(`Failed to inspect migration artifacts safely: ${rootPath}`);
+      throw snapshotSanitizerFailure(`Failed to inspect migration artifacts safely: ${rootPath}`);
     }
     const actions = scan.files
       .map((file) => actionForScannedFile(file))
       .filter((action): action is SnapshotSanitizationAction => action !== null);
     if (actions.length === 0) return;
     if (!applyDescriptorSnapshotActions(root, scan, actions)) {
-      throw new Error(`Failed to sanitize migration artifacts safely: ${rootPath}`);
+      throw snapshotSanitizerFailure(`Failed to sanitize migration artifacts safely: ${rootPath}`);
     }
   }
   throw new Error(`Migration artifacts did not reach a stable sanitized state: ${rootPath}`);

nemoclaw/src/shared/snapshot-sanitizer-boundary.cts

@@ -67,13 +67,35 @@ export function setSnapshotSanitizerPythonPathForTest(
   snapshotSanitizerPythonPathForTest = pythonPath;
 }
 
+/** Resolve the interpreter the helpers will actually run, including the test substitute. */
 function snapshotSanitizerPythonPath(): string | null {
   if (process.env.VITEST === "true" && snapshotSanitizerPythonPathForTest !== undefined) {
     return snapshotSanitizerPythonPathForTest;
   }
   return resolveTrustedSnapshotSanitizerPythonPath();
 }
 
+/** No trusted python3 interpreter resolved, so no descriptor-relative helper can run. (#8202) */
+export class SnapshotSanitizerPrerequisiteError extends Error {
+  constructor() {
+    super("python3 is required for snapshot sanitization; install python3 and retry");
+    this.name = "SnapshotSanitizerPrerequisiteError";
+  }
+}
+
+/**
+ * Return the prerequisite error when no interpreter resolved.
+ *
+ * Every helper reports an unresolved interpreter and a helper that ran and
+ * failed the same way, so this separates them before the caller reports a
+ * generic failure.
+ */
+export function snapshotSanitizerFailure(message: string): Error {
+  return snapshotSanitizerPythonPath() === null
+    ? new SnapshotSanitizerPrerequisiteError()
+    : new Error(message);
+}
+
 export interface SnapshotFileIdentity {
   readonly dev: string;
   readonly ino: string;

src/lib/security/snapshot-sanitizer.ts

@@ -11,6 +11,7 @@ import {
   type SnapshotSanitizationAction,
   type SnapshotScannedFile,
   scanDescriptorSnapshot,
+  snapshotSanitizerFailure,
 } from "../../../nemoclaw/dist/shared/snapshot-sanitizer-boundary.cjs";
 
 import {
@@ -23,6 +24,9 @@ import {
   valueLooksLikeSecret,
 } from "./credential-filter";
 
+/** Re-exported so CLI callers identify the prerequisite failure without importing the plugin boundary module. (#8202) */
+export { SnapshotSanitizerPrerequisiteError } from "../../../nemoclaw/dist/shared/snapshot-sanitizer-boundary.cjs";
+
 const MAX_SANITIZATION_PASSES = 3;
 
 const VENDORED_DEPENDENCY_DIRECTORY = "node_modules";
@@ -186,14 +190,14 @@ export function sanitizeSnapshotDirectory(rootPath: string): void {
 
     const scan = scanDescriptorSnapshot(root, CREDENTIAL_SENSITIVE_BASENAMES);
     if (scan === null) {
-      throw new Error(`Failed to inspect snapshot artifacts safely: ${rootPath}`);
+      throw snapshotSanitizerFailure(`Failed to inspect snapshot artifacts safely: ${rootPath}`);
     }
     const actions = scan.files
       .map((file) => actionForScannedFile(file))
       .filter((action): action is SnapshotSanitizationAction => action !== null);
     if (actions.length === 0) return;
     if (!applyDescriptorSnapshotActions(root, scan, actions)) {
-      throw new Error(`Failed to sanitize snapshot artifacts safely: ${rootPath}`);
+      throw snapshotSanitizerFailure(`Failed to sanitize snapshot artifacts safely: ${rootPath}`);
     }
   }
   throw new Error(`Snapshot artifacts did not reach a stable sanitized state: ${rootPath}`);

src/lib/state/sandbox-backup-sanitization.test.ts

@@ -310,6 +310,17 @@ describe("rebuild backup credential sanitization", () => {
     expect(existsSync(backupPath)).toBe(false);
   });
 
+  it("names the python3 prerequisite when the backup sanitizer finds no interpreter (#8202)", () => {
+    const backupPath = createBackup();
+    writeFileSync(join(backupPath, "state", "config.json"), '{"apiKey":"sk-secret-value"}');
+    setSnapshotSanitizerPythonPathForTest(null);
+
+    expect(() => sanitizeBackupDirectory(backupPath)).toThrow(
+      "python3 is required for snapshot sanitization; install python3 and retry",
+    );
+    expect(existsSync(backupPath)).toBe(false);
+  });
+
   it("reports when cleanup leaves an incomplete backup behind", () => {
     const backupPath = createBackup();
     const yamlPath = join(backupPath, "state", "config.yaml");

src/lib/state/sandbox.ts

@@ -50,7 +50,10 @@ import {
 } from "../domain/backup-failure.js";
 import { shellQuote } from "../runner.js";
 import { createTempSshConfig } from "../sandbox/temp-ssh-config.js";
-import { sanitizeSnapshotDirectory } from "../security/snapshot-sanitizer.js";
+import {
+  SnapshotSanitizerPrerequisiteError,
+  sanitizeSnapshotDirectory,
+} from "../security/snapshot-sanitizer.js";
 import {
   buildRestoreCleanupCommand,
   buildRestoreTarArgs,
@@ -752,19 +755,24 @@ export function sanitizeBackupDirectory(
   try {
     operations.sanitizeDirectory(dirPath);
   } catch (error) {
+    // sanitizeBackupDirectory replaces the message, so an unmet prerequisite
+    // would otherwise survive only as `cause` and never reach the operator. (#8202)
+    const prerequisite =
+      error instanceof SnapshotSanitizerPrerequisiteError ? `${error.message}. ` : "";
     try {
       operations.removeBackup(dirPath);
     } catch (cleanupError) {
-      throw new Error("Credential sanitization failed and backup cleanup failed", {
+      throw new Error(`${prerequisite}Credential sanitization failed and backup cleanup failed`, {
         cause: cleanupError,
       });
     }
     if (operations.backupExists(dirPath)) {
-      throw new Error("Credential sanitization failed and the incomplete backup remains", {
-        cause: error,
-      });
+      throw new Error(
+        `${prerequisite}Credential sanitization failed and the incomplete backup remains`,
+        { cause: error },
+      );
     }
-    throw new Error("Credential sanitization failed; removed the incomplete backup", {
+    throw new Error(`${prerequisite}Credential sanitization failed; removed the incomplete backup`, {
       cause: error,
     });
   }