fix(uninstall): preserve user data by default (#4229)

## Summary
`nemoclaw uninstall` used to `rm -rf ~/.nemoclaw/`, deleting every
host-side snapshot and workspace backup. Switch to a selective wipe that
keeps `rebuild-backups/`, `backups/`, and `sandboxes.json` by default.
Full purge still available via interactive `y` prompt or
`NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1`.

## Related Issue
Fixes #4226.

## Changes
- `src/lib/actions/uninstall/run-plan.ts`: new
`PRESERVED_USER_DATA_ENTRIES`, `removePathExcept` (selective wipe with
lstat guard against symlinked state dirs), and `resolvePreserveSet` (env
var + interactive `y/N` prompt).
- `src/lib/actions/uninstall/run-plan.test.ts`: new tests covering
preserve-by-default, env-var purge, interactive `y`/`N`,
`NEMOCLAW_NON_INTERACTIVE=1` on a TTY, symlinked state dir,
no-preservable-on-disk skip, and non-ENOENT lstat failure exiting
non-zero.
- `docs/reference/commands.mdx`: new "User-data preservation under
`~/.nemoclaw/`" subsection with the decision matrix.
- `docs/manage-sandboxes/lifecycle.mdx`: `<Note>` summary above the
uninstall flags table.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [X] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Verification
- [X] `npx prek run --all-files` passes
- [X] `npm test` passes
- [X] Tests added or updated for new or changed behavior
- [X] No secrets, API keys, or credentials committed
- [X] Docs updated for user-facing behavior changes
- [ ] `npm run docs` builds without warnings (doc changes only)
- [ ] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Uninstall now preserves user data in ~/.nemoclaw by default
(rebuild-backups/, backups/, sandboxes.json); other entries are removed.

* **Behavior**
* Interactive runs prompt before also removing preserved items (default:
keep). Non-interactive/--yes preserves by default unless
NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 forces full purge. Symlinks to
the state path are not followed.

* **Tests**
* Expanded uninstall tests covering preservation, destructive purge,
interactive/non-interactive prompts, symlink handling, and error paths.

* **Documentation**
  * Added notes describing preserved items and prompt/flag behavior.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/4229?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

Author: laitingsheng

docs/manage-sandboxes/lifecycle.mdx

@@ -257,6 +257,14 @@ nemoclaw uninstall
 | `--keep-openshell` | Leave OpenShell binaries installed.                  |
 | `--delete-models`  | Also remove NemoClaw-pulled Ollama models.           |
 
+<Note>
+`nemoclaw uninstall` preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots that `nemoclaw <name> snapshot create` and `nemoclaw backup-all` write), `~/.nemoclaw/backups/` (workspace backups that `scripts/backup-workspace.sh` writes), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default.
+Uninstall removes every other entry under `~/.nemoclaw/`.
+Interactive runs prompt before they remove the preserved entries; the default answer keeps them.
+For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well.
+See [`nemoclaw uninstall`](/reference/commands#nemoclaw-uninstall) for the full preservation contract.
+</Note>
+
 `nemoclaw uninstall` runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time.
 
 If the `nemoclaw` CLI is missing or broken, fall back to the hosted script:

docs/reference/commands.mdx

@@ -1244,6 +1244,30 @@ On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-dri
 $ nemoclaw uninstall [--yes] [--keep-openshell] [--delete-models] [--gateway <name>]
 ```
 
+##### User-data preservation under `~/.nemoclaw/`
+
+To avoid uninstall destroying host-side user data, uninstall preserves the following entries under `~/.nemoclaw/` by default:
+
+| Entry | What it holds |
+|---|---|
+| `rebuild-backups/` | Host-side snapshots that `nemoclaw <name> snapshot create` and `nemoclaw backup-all` write. `nemoclaw <name> snapshot restore` reads them back after you reinstall. |
+| `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes (see [Backup and Restore](/manage-sandboxes/backup-restore)). |
+| `sandboxes.json` | Host-side sandbox registry. NemoClaw uses it to map sandbox names back to their persistence directories when you reinstall. |
+
+Uninstall removes every other entry under `~/.nemoclaw/` (gateway source, runtime state, the Ollama auth proxy PID file, etc.).
+
+Decision matrix:
+
+| Context | Behaviour |
+|---|---|
+| Interactive TTY, preserved entries present, no env override | Prompts `Also remove them? [y/N]`. Default `N` keeps the entries. |
+| Interactive TTY, user answers `y` | Removes everything under `~/.nemoclaw/` (the previous full-removal behaviour). |
+| Non-interactive (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or non-TTY shell) | Preserves the entries and prints a one-line notice. |
+| Any context with `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` | Skips the prompt and removes everything under `~/.nemoclaw/`. |
+
+The preserved entries survive uninstall as inert files on disk.
+Reinstall NemoClaw and re-onboard the sandbox before `nemoclaw <name> snapshot restore` can use them.
+
 #### `nemoclaw uninstall` vs. the hosted `uninstall.sh`
 
 Both forms execute the same `uninstall.sh` with the same flags, but differ in where the script comes from and how much they trust the network.

src/lib/actions/uninstall/run-plan.test.ts

@@ -618,6 +618,285 @@ describe("uninstall run plan", () => {
     );
   });
 
+  describe("user-data preservation under ~/.nemoclaw/", () => {
+    function setupStateDir(): { tmpHome: string; stateDir: string } {
+      const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-uninstall-preserve-"));
+      const stateDir = path.join(tmpHome, ".nemoclaw");
+      fs.mkdirSync(path.join(stateDir, "rebuild-backups", "sb1", "20260101"), { recursive: true });
+      fs.writeFileSync(path.join(stateDir, "rebuild-backups", "sb1", "20260101", "manifest.json"), "{}");
+      fs.mkdirSync(path.join(stateDir, "backups", "20260320-120000"), { recursive: true });
+      fs.writeFileSync(path.join(stateDir, "backups", "20260320-120000", "USER.md"), "hello");
+      fs.writeFileSync(path.join(stateDir, "sandboxes.json"), "[]");
+      fs.writeFileSync(path.join(stateDir, "ollama-auth-proxy.pid"), "1234");
+      fs.mkdirSync(path.join(stateDir, "source"));
+      return { tmpHome, stateDir };
+    }
+
+    function tempScopedExistsSync(tmpHome: string): (target: string) => boolean {
+      return (target: string) => target.startsWith(tmpHome) && fs.existsSync(target);
+    }
+
+    it("preserves rebuild-backups/, backups/, and sandboxes.json by default in non-interactive runs", () => {
+      const { tmpHome, stateDir } = setupStateDir();
+      try {
+        const logs: string[] = [];
+        const result = runUninstallPlan(
+          { assumeYes: true, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+            existsSync: tempScopedExistsSync(tmpHome),
+            isTty: false,
+            log: (line) => logs.push(line),
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(path.join(stateDir, "rebuild-backups", "sb1", "20260101", "manifest.json"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "backups", "20260320-120000", "USER.md"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "sandboxes.json"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "ollama-auth-proxy.pid"))).toBe(false);
+        expect(fs.existsSync(path.join(stateDir, "source"))).toBe(false);
+        expect(logs).toContain(`Preserving rebuild-backups, backups, sandboxes.json under ${stateDir}.`);
+        expect(logs.some((line) => line.includes("preserved: rebuild-backups, backups, sandboxes.json"))).toBe(true);
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+
+    it("purges the whole state dir when NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 is set", () => {
+      const { tmpHome, stateDir } = setupStateDir();
+      try {
+        const logs: string[] = [];
+        const result = runUninstallPlan(
+          { assumeYes: true, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: {
+              HOME: tmpHome,
+              NEMOCLAW_UNINSTALL_DESTROY_USER_DATA: "1",
+            } as NodeJS.ProcessEnv,
+            existsSync: tempScopedExistsSync(tmpHome),
+            isTty: false,
+            log: (line) => logs.push(line),
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(stateDir)).toBe(false);
+        expect(logs).toContain(`Removed ${stateDir}`);
+        expect(logs).toContain("NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 set; purging user data under ~/.nemoclaw/.");
+        expect(logs.every((line) => !line.includes("preserved:"))).toBe(true);
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+
+    it("purges via interactive y/N prompt when user answers yes", () => {
+      const { tmpHome, stateDir } = setupStateDir();
+      try {
+        const logs: string[] = [];
+        const replies = ["yes", "y"];
+        const result = runUninstallPlan(
+          { assumeYes: false, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+            existsSync: tempScopedExistsSync(tmpHome),
+            isTty: true,
+            log: (line) => logs.push(line),
+            readLine: () => replies.shift() ?? null,
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(stateDir)).toBe(false);
+        expect(logs).toContain("Also remove them? [y/N]");
+        expect(logs).toContain("Acknowledged; purging user data.");
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+
+    it("keeps user data when interactive prompt is declined", () => {
+      const { tmpHome, stateDir } = setupStateDir();
+      try {
+        const logs: string[] = [];
+        const replies = ["yes", ""];
+        const result = runUninstallPlan(
+          { assumeYes: false, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+            existsSync: tempScopedExistsSync(tmpHome),
+            isTty: true,
+            log: (line) => logs.push(line),
+            readLine: () => replies.shift() ?? null,
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(path.join(stateDir, "rebuild-backups", "sb1", "20260101", "manifest.json"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "backups", "20260320-120000", "USER.md"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "sandboxes.json"))).toBe(true);
+        expect(logs).toContain("Keeping user data.");
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+
+    it("preserves entries on a TTY when NEMOCLAW_NON_INTERACTIVE=1 is set instead of --yes", () => {
+      const { tmpHome, stateDir } = setupStateDir();
+      const readLine = vi.fn(() => "yes");
+      try {
+        const logs: string[] = [];
+        const result = runUninstallPlan(
+          { assumeYes: false, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: {
+              HOME: tmpHome,
+              NEMOCLAW_NON_INTERACTIVE: "1",
+            } as NodeJS.ProcessEnv,
+            existsSync: tempScopedExistsSync(tmpHome),
+            // Simulate a TTY so we exercise the env-var-only branch (the prior
+            // tests reach the silent-preserve branch via !isTty or assumeYes).
+            isTty: true,
+            log: (line) => logs.push(line),
+            readLine,
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(path.join(stateDir, "rebuild-backups", "sb1", "20260101", "manifest.json"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "backups", "20260320-120000", "USER.md"))).toBe(true);
+        expect(fs.existsSync(path.join(stateDir, "sandboxes.json"))).toBe(true);
+        expect(logs).toContain(`Preserving rebuild-backups, backups, sandboxes.json under ${stateDir}.`);
+        // Interactive y/N prompt must not fire when NEMOCLAW_NON_INTERACTIVE is set.
+        expect(logs.every((line) => line !== "Also remove them? [y/N]")).toBe(true);
+        // The earlier generic confirm() prompt still consumes one readLine for "Proceed? [y/N]";
+        // resolvePreserveSet must not consume another.
+        expect(readLine).toHaveBeenCalledTimes(1);
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+
+    it("exits non-zero and warns when lstat on ~/.nemoclaw fails with a non-ENOENT error", () => {
+      const { tmpHome, stateDir } = setupStateDir();
+      const realLstat = fs.lstatSync;
+      const lstatSpy = vi.spyOn(fs, "lstatSync").mockImplementation((p: fs.PathLike) => {
+        if (String(p) === stateDir) {
+          const err = new Error("permission denied") as NodeJS.ErrnoException;
+          err.code = "EACCES";
+          throw err;
+        }
+        return realLstat(p);
+      });
+      try {
+        const logs: string[] = [];
+        const warnings: string[] = [];
+        const result = runUninstallPlan(
+          { assumeYes: true, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+            error: (line) => warnings.push(line),
+            existsSync: tempScopedExistsSync(tmpHome),
+            isTty: false,
+            log: (line) => logs.push(line),
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(1);
+        expect(warnings.some((line) => line.startsWith(`Failed to inspect ${stateDir}: `))).toBe(true);
+        expect(warnings).toContain(
+          "Uninstall completed with errors. Some state may remain on disk; see warnings above.",
+        );
+        expect(logs).not.toContain("Claws retracted. Until next time.");
+        expect(fs.existsSync(path.join(stateDir, "rebuild-backups", "sb1", "20260101", "manifest.json"))).toBe(true);
+      } finally {
+        lstatSpy.mockRestore();
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+
+    it("removes ~/.nemoclaw wholesale when it is a symlink rather than a real directory", () => {
+      const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-uninstall-preserve-"));
+      const realTarget = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-uninstall-preserve-target-"));
+      const stateDir = path.join(tmpHome, ".nemoclaw");
+      fs.symlinkSync(realTarget, stateDir);
+      // Symlink target intentionally non-empty so that following it would
+      // tempt the selective-wipe path; lstat must short-circuit that.
+      fs.writeFileSync(path.join(realTarget, "rebuild-backups"), "should not be followed");
+      try {
+        const logs: string[] = [];
+        const result = runUninstallPlan(
+          { assumeYes: true, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+            existsSync: (target: string) =>
+              target.startsWith(tmpHome) && fs.existsSync(target),
+            isTty: false,
+            log: (line) => logs.push(line),
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(stateDir)).toBe(false);
+        expect(fs.existsSync(realTarget)).toBe(true);
+        expect(logs).toContain(`Removed ${stateDir}`);
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+        fs.rmSync(realTarget, { recursive: true, force: true });
+      }
+    });
+
+    it("skips the preservation notice when no protected entries exist on disk", () => {
+      const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-uninstall-preserve-"));
+      const stateDir = path.join(tmpHome, ".nemoclaw");
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, "ollama-auth-proxy.pid"), "1234");
+      try {
+        const logs: string[] = [];
+        const result = runUninstallPlan(
+          { assumeYes: true, deleteModels: false, keepOpenShell: true },
+          {
+            commandExists: () => false,
+            env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+            existsSync: tempScopedExistsSync(tmpHome),
+            isTty: false,
+            log: (line) => logs.push(line),
+            run: vi.fn(() => ok()),
+            runDocker: () => ok(""),
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        expect(fs.existsSync(stateDir)).toBe(false);
+        expect(logs).toContain(`Removed ${stateDir}`);
+        expect(logs.every((line) => !line.startsWith("Preserving "))).toBe(true);
+      } finally {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      }
+    });
+  });
+
   it("kills host openshell-gateway process during uninstall (#3516)", () => {
     const logs: string[] = [];
     const killed: number[] = [];