fix(uninstall): keep shared shims when sibling ports remain

Scoped --destroy-user-data must not drop ~/.local/bin managed shims when
otherGatewayPorts proves a real sibling still shares them. Limit removal to
the unidentified scoped path and cover the confirmed-sibling retention case.

Signed-off-by: Rui Luo <ruluo@nvidia.com>

Author: rluo8

docs/manage-sandboxes/uninstall-nemoclaw.mdx

@@ -25,7 +25,7 @@ It preserves resources from a separate OpenClaw installation while continuing to
 | `--yes` | Skip the confirmation prompt. |
 | `--keep-openshell` | Leave OpenShell binaries, NemoClaw-managed gateway service files, and local gateway state in place, and do not stop the host gateway process. |
 | `--delete-models` | Delete every model reported by the host's local Ollama inventory and all non-credential data in the current user's shared `~/.cache/huggingface/` cache after managed model runtimes stop. Hugging Face authentication files remain. |
-| `--destroy-user-data` | Also remove preserved user data in `rebuild-backups/`, `backups/`, and `sandboxes.json`, and remove installer-managed user-local CLI shims under `~/.local/bin/`. When sibling gateways remain, the shared npm CLI package stays. |
+| `--destroy-user-data` | Also remove preserved user data in `rebuild-backups/`, `backups/`, and `sandboxes.json`. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. |
 | `--all-gateway-ports` | Uninstall every gateway port on the host instead of only the selected one. |
 | `--gateway <name>` | Optional consistency check; must match the name derived from `NEMOCLAW_GATEWAY_PORT`. |
 
@@ -230,7 +230,7 @@ If validation, runtime cleanup, or temporary-claim retirement fails, uninstall e
 Resolve the reported SSH, Docker, peer-host, or claim error before you retry.
 Runtime cleanup can partially complete before an error, so inspect every cluster node before retrying.
 When sibling gateways remain, it removes only the selected gateway's resources and port-scoped state and preserves those shared host resources.
-With `--destroy-user-data`, that scoped path still removes installer-managed user-local CLI shims under `~/.local/bin/` while it keeps the shared npm CLI package and the other shared host resources for remaining gateways.
+With `--destroy-user-data`, that scoped path removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified (for example odd `~/.nemoclaw/gateways/` entries or an unreadable gateway list). When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package and the other shared host resources.
 A recorded sandbox that OpenShell reports as already removed leaves nothing to delete, so the scoped path reports it, finishes the remaining gateway cleanup, and exits `0`.
 A sandbox that OpenShell cannot reach or refuses to delete still leaves state behind.
 Uninstall exits nonzero and preserves the selected gateway registration, port-scoped state, and selected sandbox registry entry for a retry.

docs/reference/commands.mdx

@@ -4346,7 +4346,7 @@ Uninstall does not otherwise target the declared external directory.
 | `--yes` | Skip the confirmation prompt |
 | `--keep-openshell` | Leave OpenShell binaries, NemoClaw-managed gateway service files, and local gateway state in place, and do not stop the host gateway process |
 | `--delete-models` | Outside portable cleanup, delete every model reported by the host's local Ollama inventory and all non-credential data in the current user's shared `~/.cache/huggingface/` cache after managed model runtimes stop. Hugging Face authentication files remain. Portable cleanup preserves both model stores and every Podman image. |
-| `--destroy-user-data` | Also remove preserved user data (`rebuild-backups/`, `backups/`, `sandboxes.json`) and installer-managed user-local CLI shims under `~/.local/bin/`. When sibling gateways remain, the shared npm CLI package stays. Portable cleanup still retains its recovery record until later completed onboarding durably supersedes it. |
+| `--destroy-user-data` | Also remove preserved user data (`rebuild-backups/`, `backups/`, `sandboxes.json`). Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. Portable cleanup still retains its recovery record until later completed onboarding durably supersedes it. |
 | `--all-gateway-ports` | Uninstall every gateway port on the host, not only the port `NEMOCLAW_GATEWAY_PORT` selects |
 | `--gateway <name>` | Optional consistency check; must match the name derived from `NEMOCLAW_GATEWAY_PORT` |
 
@@ -4452,7 +4452,7 @@ The default gateway uses `~/.nemoclaw/`; a non-default gateway uses `~/.nemoclaw
 
 Outside portable cleanup, when uninstall confirms that no sibling gateways remain, it also removes shared host resources such as the gateway source clone, runtime state, and the Ollama auth proxy PID file.
 When sibling gateways remain, it removes only the selected gateway's resources and port-scoped state while preserving those shared host resources.
-With `--destroy-user-data`, that scoped path still removes installer-managed user-local CLI shims under `~/.local/bin/` while it keeps the shared npm CLI package and the other shared host resources for remaining gateways.
+With `--destroy-user-data`, that scoped path removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified (for example odd `~/.nemoclaw/gateways/` entries or an unreadable gateway list). When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package and the other shared host resources.
 If the OpenShell command is unavailable or its gateway list cannot be read, uninstall cannot confirm that the selected gateway is the last one, so it uses the same scoped path and preserves the shared resources.
 When the command itself is unavailable, uninstall exits nonzero before OpenShell cleanup so you can restore the command and retry.
 
@@ -4468,8 +4468,8 @@ Decision matrix:
 | 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 the preserved entries in the selected gateway's state root; outside portable cleanup, a single-gateway uninstall also removes the remaining shared state. Portable cleanup preserves shared OpenShell resources and its retirement record. |
 | Non-interactive (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or non-TTY shell) | Preserves the entries and prints a one-line notice. |
-| `--destroy-user-data` | Skips the secondary user-data prompt, removes the preserved entries in the selected gateway's state root, and removes installer-managed user-local CLI shims under `~/.local/bin/`. When sibling gateways remain, the shared npm CLI package stays. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |
-| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` | Skips the secondary user-data prompt, removes the preserved entries, and removes installer-managed user-local CLI shims under `~/.local/bin/`. When sibling gateways remain, the shared npm CLI package stays. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |
+| `--destroy-user-data` | Skips the secondary user-data prompt and removes the preserved entries in the selected gateway's state root. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |
+| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` | Skips the secondary user-data prompt and removes the preserved entries. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |
 
 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.
@@ -5145,7 +5145,7 @@ The following flags change defaults for commands that manage existing sandboxes.
 | `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. |
 | `NEMOCLAW_UNINSTALL_ALL_GATEWAY_PORTS` | `1` to opt in | Makes `$$nemoclaw uninstall` remove every gateway port on the host instead of only the port `NEMOCLAW_GATEWAY_PORT` selects. Equivalent to passing the `--all-gateway-ports` flag; the whole-host `Proceed?` confirmation still applies unless `--yes` is also passed. Each port runs as its own uninstall, and the variable is dropped from those runs so the sweep cannot re-enter itself. |
-| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA` | `1` to opt in | Acknowledges data loss during `$$nemoclaw uninstall`, removes the otherwise-preserved entries (`rebuild-backups/`, `backups/`, `sandboxes.json`) under `~/.nemoclaw/`, and removes installer-managed user-local CLI shims under `~/.local/bin/`. When sibling gateways remain, the shared npm CLI package stays. Equivalent to passing the `--destroy-user-data` flag; the global `Proceed?` confirmation still applies unless `--yes` is also passed. |
+| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA` | `1` to opt in | Acknowledges data loss during `$$nemoclaw uninstall` and removes the otherwise-preserved entries (`rebuild-backups/`, `backups/`, `sandboxes.json`) under `~/.nemoclaw/`. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. Equivalent to passing the `--destroy-user-data` flag; the global `Proceed?` confirmation still applies unless `--yes` is also passed. |
 
 <AgentOnly variant="openclaw">
 ### Deprecated Brev Deployment

src/lib/actions/root-help.ts

@@ -85,7 +85,7 @@ export function help(): void {
     `    --delete-models${" ".repeat(19)}Remove all Ollama models and non-credential Hugging Face cache data (authentication files remain)`,
   );
   lines.push(
-    `    --destroy-user-data${" ".repeat(15)}Remove preserved ~/.nemoclaw/ user data and managed ~/.local/bin CLI shims`,
+    `    --destroy-user-data${" ".repeat(15)}Remove preserved ~/.nemoclaw/ user data; managed CLI shims unless a confirmed sibling remains`,
   );
   lines.push(
     `    --all-gateway-ports${" ".repeat(15)}Uninstall every gateway port on this host, not only NEMOCLAW_GATEWAY_PORT`,

src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts

@@ -55,6 +55,12 @@ function okWithKnownGatewayList(command: string, args: readonly string[]): RunRe
     : ok();
 }
 
+function okWithSiblingGatewayList(command: string, args: readonly string[]): RunResult {
+  return command === "openshell" && args[0] === "gateway" && args[1] === "list"
+    ? ok(JSON.stringify([{ name: "nemoclaw" }, { name: "nemoclaw-9123" }]))
+    : ok();
+}
+
 const SCOPED_RETENTION_LOG =
   "Sibling gateways remain; kept the shared NemoClaw CLI and shell shims.";
 const SCOPED_PACKAGE_RETENTION_LOG =
@@ -126,7 +132,9 @@ function writeScopedGatewayState(home: string, port = 8080): void {
 function uninstall(
   home: string,
   shims: readonly string[],
-  options: Pick<UninstallRunOptions, "destroyUserData"> = {},
+  options: Pick<UninstallRunOptions, "destroyUserData"> & {
+    run?: (command: string, args: readonly string[]) => RunResult;
+  } = {},
 ) {
   const logs: string[] = [];
   const result = runUninstallPlan(
@@ -147,7 +155,7 @@ function uninstall(
       rmSync: vi.fn((target: fs.PathLike, rmOptions?: fs.RmOptions) => {
         String(target).startsWith(home) ? fs.rmSync(target, rmOptions) : undefined;
       }),
-      run: vi.fn(okWithKnownGatewayList),
+      run: vi.fn(options.run ?? okWithKnownGatewayList),
       runDocker: () => ok(""),
     },
   );
@@ -264,4 +272,24 @@ describe("uninstall gateway-directory scan", () => {
       fs.rmSync(home, { recursive: true, force: true });
     }
   });
+
+  it("keeps managed CLI shims with --destroy-user-data when a confirmed sibling gateway remains (#9277)", () => {
+    const { home, shims } = makeHome("nemoclaw-uninstall-destroy-sibling-", []);
+    writeScopedGatewayState(home);
+
+    try {
+      const { result, logs, survivors } = uninstall(home, shims, {
+        destroyUserData: true,
+        run: okWithSiblingGatewayList,
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(logs).toContain(SCOPED_RETENTION_LOG);
+      expect(logs).not.toContain(DESTROY_SHIM_CLEANUP_LOG);
+      expect(logs).not.toContain(SCOPED_PACKAGE_RETENTION_LOG);
+      expect(survivors).toEqual(shims);
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
 });

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

@@ -2617,6 +2617,7 @@ function executePlan(
   preserveUnderStateDir: readonly string[],
   scopedToSelectedGateway: boolean,
   sharedRegistryMustBePreserved: boolean,
+  otherGatewayPorts: readonly number[],
   sandboxNames: readonly string[],
   teardownAuthority: GatewayOwner,
   portableRuntimeCleanup: boolean,
@@ -2759,12 +2760,12 @@ function executePlan(
       }
     } else if (step.name === "NemoClaw CLI") {
       if (scopedToSelectedGateway) {
-        // Sibling-scoped cleanup keeps the shared npm CLI package. With
-        // `--destroy-user-data`, also delete installer-managed user-local shims
-        // when `removePath` succeeds so a destructive uninstall does not leave
-        // them on PATH (#9277). Foreign files of those names stay; the summary
-        // log runs only when at least one managed shim was removed.
-        if (options.destroyUserData) {
+        // Confirmed sibling gateway ports share ~/.local/bin shims. Only the
+        // unidentified / unproven scoped path (#9277 false positives: odd
+        // gateways/ entries, unreadable gateway list, etc.) may drop managed
+        // shims on `--destroy-user-data` while keeping the shared npm package.
+        const confirmedSiblingPortsRemain = otherGatewayPorts.length > 0;
+        if (options.destroyUserData && !confirmedSiblingPortsRemain) {
           runtime.log("Sibling gateways remain; kept the shared NemoClaw CLI package.");
           const removedShims = removeManagedCliShims(paths, runtime);
           if (removedShims > 0) {
@@ -3082,6 +3083,7 @@ export function runUninstallPlan(
       preserveUnderStateDir,
       scopedToSelectedGateway,
       gatewayInspection.sharedRegistryMustBePreserved,
+      gatewayInspection.otherGatewayPorts,
       sandboxNames,
       teardownAuthority,
       portableRuntimeCleanup,