Walkthrough

Adds an allowlist and selective-deletion logic for ~/.nemoclaw during uninstall, computes a preserve set (interactive prompt or env-var override), uses removePathExcept() in the uninstall plan, adds tests for multiple scenarios, and updates reference and lifecycle docs to describe the preservation contract.

Changes

User-data preservation during uninstall

sequenceDiagram
  participant detectPreservableEntries
  participant resolvePreserveSet
  participant executePlan
  participant removePathExcept
  detectPreservableEntries->>resolvePreserveSet: find present allowlisted entries
  resolvePreserveSet->>executePlan: computed preserveUnderStateDir (preserve or purge)
  executePlan->>removePathExcept: removePathExcept(paths.nemoclawStateDir, preserveSet)
  removePathExcept->>removePathExcept: remove non-preserved children or remove symlink

Estimated code review effort:
🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers:

• ericksoa
• cv

"🐰
I tend the backups in the den,
I ask, I note, I spare the men.
If TTY says yes, I clear the shelf;
else whisper: 'Keeping user data' myself.
Flip the flag and let it go — or keep it on the shelf!"

❌ Failed checks (2 warnings)

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: medium

Required E2E

• snapshot-commands-e2e (medium (~30 min timeout, cloud onboarding)): Validates the snapshot create/list/restore lifecycle and the ~/.nemoclaw/rebuild-backups/ plus sandbox registry state that this uninstall change now preserves by default.
• state-backup-restore-e2e (medium (~60 min timeout, cloud onboarding)): Validates scripts/backup-workspace.sh backup/restore and the ~/.nemoclaw/backups/ tree that uninstall now selectively preserves instead of deleting.

Optional E2E

• docs-validation-e2e (low-medium (~15 min timeout)): Useful because the PR changes user-facing command/lifecycle docs; this checks installed CLI/docs validation, but it is adjacent rather than direct coverage for uninstall preservation.
• cloud-e2e (medium (~45 min script runner default)): General install/onboard/inference/destroy smoke coverage for the source branch; useful confidence that lifecycle changes did not regress the common sandbox path, though it does not directly exercise nemoclaw uninstall.

New E2E recommendations

• uninstall / user-data preservation (high): No existing E2E appears to directly run nemoclaw uninstall after creating rebuild-backups/, backups/, and sandboxes.json, then assert default non-interactive preservation versus NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 full purge. Current unit tests cover the plan logic, but an E2E should validate the packaged CLI/uninstall path on a real host.
  • Suggested test: uninstall-user-data-preservation-e2e
• reinstall recovery after uninstall (medium): The new contract says preserved files are inert but usable after reinstall/re-onboard. Add an E2E that creates a snapshot, uninstalls with default preservation, reinstalls, re-onboards, and restores the snapshot to prove the documented recovery path works.
  • Suggested test: uninstall-reinstall-snapshot-restore-e2e

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: snapshot-commands-e2e,state-backup-restore-e2e

🛠️ Needs attention

• [Ubuntu 24.04][Install] nemoclaw uninstall destroys all user data — workspace files (USER.md, SOUL.md) and snapshots not preserved #4226 byte-for-byte preservation remains unproven (src/lib/actions/uninstall/run-plan.test.ts:639): The linked issue's primary expected result requires the documented preservation paths to remain on the host with SHA256 content unchanged. The added tests prove selected paths still exist after uninstall, but they do not record pre-uninstall bytes or hashes and compare them after uninstall. The restore-shaped snapshot fixture also does not include the issue's representative USER.md and SOUL.md workspace content.
  • Recommendation: Extend the regression to create representative rebuild-backups/, backups/, and sandboxes.json payloads, including USER.md and SOUL.md where applicable. Record pre-uninstall bytes or SHA256 values, run uninstall --yes, then assert exact byte-for-byte equality afterward.
  • Evidence: Issue [Ubuntu 24.04][Install] nemoclaw uninstall destroys all user data — workspace files (USER.md, SOUL.md) and snapshots not preserved #4226 expected result: "The documented preservation paths still exist on the host after uninstall, with their SHA256 content unchanged from before uninstall." The new preservation test starts at run-plan.test.ts:639 and asserts fs.existsSync for rebuild-backups, backups, and sandboxes.json. Repository grep found no sha256/createHash/readFileSync equality checks and no SOUL.md fixture in the new preservation tests.
• Destructive uninstall preservation policy is still embedded in the runner monolith (src/lib/actions/uninstall/run-plan.ts:121): The PR keeps the preservation allowlist, selective deletion implementation, preservable-entry detection, prompt/ack decision logic, and expanded regression coverage inside the already-large destructive uninstall runner and test file. This also leaves the selective cleanup behavior without a clear source-of-truth boundary or permanence/removal story.
  • Recommendation: Extract PRESERVED_USER_DATA_ENTRIES, preservable-entry detection, preserve-set resolution, and removePathExcept() into a focused uninstall state-preservation helper with narrow filesystem dependencies. Move the new preservation tests into a focused test file and document whether this policy is permanent or a temporary compatibility bridge.
  • Evidence: PRESERVED_USER_DATA_ENTRIES starts at run-plan.ts:121, removePathExcept() at run-plan.ts:127, detectPreservableEntries() at run-plan.ts:633, and resolvePreserveSet() at run-plan.ts:640. Trusted drift context reports run-plan.ts grew by 121 lines and run-plan.test.ts grew by 279 lines.

🔎 Worth checking

• Source-of-truth review needed: src/lib/actions/uninstall/run-plan.ts removePathExcept() selective cleanup under ~/.nemoclaw/: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: removePathExcept() starts at run-plan.ts:127 and implements selective deletion inline in the runner. It catches lstat errors at run-plan.ts:143-152 but leaves readdirSync and child rmSync unwrapped at run-plan.ts:160-163.
• Selective state-dir cleanup still lacks a controlled filesystem error policy (src/lib/actions/uninstall/run-plan.ts:160): The lstat branch now fails closed and returns a non-zero uninstall outcome, but directory enumeration and per-child deletion do not use the same policy. On unreadable, concurrently modified, or partially failing ~/.nemoclaw layouts, fs.readdirSync() or rmSync() can still throw outside the intended ok=false path, potentially skipping later cleanup of security-relevant local state/config and leaving users without a consistent warning and exit-code contract.
  • Recommendation: Wrap lstat, readdir, and each child deletion in one explicit policy: either fail closed with a clear warning and non-zero outcome, or preserve data with a clear warning. Add negative tests for readdir failure and child rmSync failure/race in addition to the existing lstat test.
  • Evidence: removePathExcept() catches fs.lstatSync(target) at run-plan.ts:143-152, but then calls const children = fs.readdirSync(target) at run-plan.ts:160 and deps.rmSync(path.join(target, entry), ...) at run-plan.ts:163 without local error handling. Tests cover lstat EACCES and symlinked ~/.nemoclaw, but not readdirSync or child rmSync failures.
• Preserve-by-default changes privacy cleanup semantics of uninstall --yes (docs/reference/commands.mdx:1201): The new default intentionally keeps host-side snapshots, workspace backups, and the sandbox registry after uninstall. That prevents accidental data loss, but it also means security-sensitive scripted users no longer get a full local-data purge from uninstall --yes unless they set NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1. The docs and runtime notice describe what is retained, but do not explicitly warn that retained backups, snapshots, or registry files may contain private workspace data, PII, message history, or secret-adjacent user content.
  • Recommendation: Keep the explicit purge path, but make the non-interactive runtime notice and uninstall docs explicit that retained backups/snapshots/registry may contain private workspace data, PII, message history, or secrets. Keep NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 prominent for users who need a full purge.
  • Evidence: PRESERVED_USER_DATA_ENTRIES includes rebuild-backups, backups, and sandboxes.json. resolvePreserveSet() preserves them by default for --yes, non-TTY, and NEMOCLAW_NON_INTERACTIVE=1. docs/reference/commands.mdx:1201-1220 says the entries survive as inert files on disk; docs/manage-sandboxes/lifecycle.mdx:261-264 names the preserved entries and purge env var but does not warn about private content.
• NEMOCLAW_NON_INTERACTIVE wording can imply it replaces the initial uninstall confirmation (docs/manage-sandboxes/lifecycle.mdx:264): The docs group --yes, NEMOCLAW_NON_INTERACTIVE=1, and non-TTY shells as non-interactive preservation contexts. In code, NEMOCLAW_NON_INTERACTIVE=1 only skips the second preservation prompt after the initial Proceed? confirmation has already been accepted; confirm() still skips only when options.assumeYes is true. The new test for NEMOCLAW_NON_INTERACTIVE also supplies a readLine answer of yes for the initial prompt, so it does not prove env-var-only uninstall proceeds without --yes.
  • Recommendation: Clarify that NEMOCLAW_NON_INTERACTIVE=1 controls the preservation prompt but does not by itself acknowledge the initial destructive uninstall confirmation; scripted runs should still pass --yes when they intend to proceed.
  • Evidence: confirm() returns early only for options.assumeYes at run-plan.ts:260, then reads the Proceed? prompt. resolvePreserveSet() treats runtime.env.NEMOCLAW_NON_INTERACTIVE === "1" as non-interactive at run-plan.ts:657-658. The test at run-plan.test.ts:756 uses readLine = vi.fn(() => "yes") and expects it to be called once for the earlier generic confirm prompt.

🌱 Nice ideas

• None.

Current findings:

• Source-of-truth review needed: src/lib/actions/uninstall/run-plan.ts removePathExcept() selective cleanup under ~/.nemoclaw/: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: removePathExcept() starts at run-plan.ts:127 and implements selective deletion inline in the runner. It catches lstat errors at run-plan.ts:143-152 but leaves readdirSync and child rmSync unwrapped at run-plan.ts:160-163.
• [Ubuntu 24.04][Install] nemoclaw uninstall destroys all user data — workspace files (USER.md, SOUL.md) and snapshots not preserved #4226 byte-for-byte preservation remains unproven (src/lib/actions/uninstall/run-plan.test.ts:639): The linked issue's primary expected result requires the documented preservation paths to remain on the host with SHA256 content unchanged. The added tests prove selected paths still exist after uninstall, but they do not record pre-uninstall bytes or hashes and compare them after uninstall. The restore-shaped snapshot fixture also does not include the issue's representative USER.md and SOUL.md workspace content.
  • Recommendation: Extend the regression to create representative rebuild-backups/, backups/, and sandboxes.json payloads, including USER.md and SOUL.md where applicable. Record pre-uninstall bytes or SHA256 values, run uninstall --yes, then assert exact byte-for-byte equality afterward.
  • Evidence: Issue [Ubuntu 24.04][Install] nemoclaw uninstall destroys all user data — workspace files (USER.md, SOUL.md) and snapshots not preserved #4226 expected result: "The documented preservation paths still exist on the host after uninstall, with their SHA256 content unchanged from before uninstall." The new preservation test starts at run-plan.test.ts:639 and asserts fs.existsSync for rebuild-backups, backups, and sandboxes.json. Repository grep found no sha256/createHash/readFileSync equality checks and no SOUL.md fixture in the new preservation tests.
• Destructive uninstall preservation policy is still embedded in the runner monolith (src/lib/actions/uninstall/run-plan.ts:121): The PR keeps the preservation allowlist, selective deletion implementation, preservable-entry detection, prompt/ack decision logic, and expanded regression coverage inside the already-large destructive uninstall runner and test file. This also leaves the selective cleanup behavior without a clear source-of-truth boundary or permanence/removal story.
  • Recommendation: Extract PRESERVED_USER_DATA_ENTRIES, preservable-entry detection, preserve-set resolution, and removePathExcept() into a focused uninstall state-preservation helper with narrow filesystem dependencies. Move the new preservation tests into a focused test file and document whether this policy is permanent or a temporary compatibility bridge.
  • Evidence: PRESERVED_USER_DATA_ENTRIES starts at run-plan.ts:121, removePathExcept() at run-plan.ts:127, detectPreservableEntries() at run-plan.ts:633, and resolvePreserveSet() at run-plan.ts:640. Trusted drift context reports run-plan.ts grew by 121 lines and run-plan.test.ts grew by 279 lines.
• Selective state-dir cleanup still lacks a controlled filesystem error policy (src/lib/actions/uninstall/run-plan.ts:160): The lstat branch now fails closed and returns a non-zero uninstall outcome, but directory enumeration and per-child deletion do not use the same policy. On unreadable, concurrently modified, or partially failing ~/.nemoclaw layouts, fs.readdirSync() or rmSync() can still throw outside the intended ok=false path, potentially skipping later cleanup of security-relevant local state/config and leaving users without a consistent warning and exit-code contract.
  • Recommendation: Wrap lstat, readdir, and each child deletion in one explicit policy: either fail closed with a clear warning and non-zero outcome, or preserve data with a clear warning. Add negative tests for readdir failure and child rmSync failure/race in addition to the existing lstat test.
  • Evidence: removePathExcept() catches fs.lstatSync(target) at run-plan.ts:143-152, but then calls const children = fs.readdirSync(target) at run-plan.ts:160 and deps.rmSync(path.join(target, entry), ...) at run-plan.ts:163 without local error handling. Tests cover lstat EACCES and symlinked ~/.nemoclaw, but not readdirSync or child rmSync failures.
• Preserve-by-default changes privacy cleanup semantics of uninstall --yes (docs/reference/commands.mdx:1201): The new default intentionally keeps host-side snapshots, workspace backups, and the sandbox registry after uninstall. That prevents accidental data loss, but it also means security-sensitive scripted users no longer get a full local-data purge from uninstall --yes unless they set NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1. The docs and runtime notice describe what is retained, but do not explicitly warn that retained backups, snapshots, or registry files may contain private workspace data, PII, message history, or secret-adjacent user content.
  • Recommendation: Keep the explicit purge path, but make the non-interactive runtime notice and uninstall docs explicit that retained backups/snapshots/registry may contain private workspace data, PII, message history, or secrets. Keep NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 prominent for users who need a full purge.
  • Evidence: PRESERVED_USER_DATA_ENTRIES includes rebuild-backups, backups, and sandboxes.json. resolvePreserveSet() preserves them by default for --yes, non-TTY, and NEMOCLAW_NON_INTERACTIVE=1. docs/reference/commands.mdx:1201-1220 says the entries survive as inert files on disk; docs/manage-sandboxes/lifecycle.mdx:261-264 names the preserved entries and purge env var but does not warn about private content.
• NEMOCLAW_NON_INTERACTIVE wording can imply it replaces the initial uninstall confirmation (docs/manage-sandboxes/lifecycle.mdx:264): The docs group --yes, NEMOCLAW_NON_INTERACTIVE=1, and non-TTY shells as non-interactive preservation contexts. In code, NEMOCLAW_NON_INTERACTIVE=1 only skips the second preservation prompt after the initial Proceed? confirmation has already been accepted; confirm() still skips only when options.assumeYes is true. The new test for NEMOCLAW_NON_INTERACTIVE also supplies a readLine answer of yes for the initial prompt, so it does not prove env-var-only uninstall proceeds without --yes.
  • Recommendation: Clarify that NEMOCLAW_NON_INTERACTIVE=1 controls the preservation prompt but does not by itself acknowledge the initial destructive uninstall confirmation; scripted runs should still pass --yes when they intend to proceed.
  • Evidence: confirm() returns early only for options.assumeYes at run-plan.ts:260, then reads the Proceed? prompt. resolvePreserveSet() treats runtime.env.NEMOCLAW_NON_INTERACTIVE === "1" as non-interactive at run-plan.ts:657-658. The test at run-plan.test.ts:756 uses readLine = vi.fn(() => "yes") and expects it to be called once for the earlier generic confirm prompt.

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario workflow, scenario metadata, scenario runtime, or validation-suite files changed.

Optional scenario E2E

• None.

Relevant changed files

• None.