fix(uninstall): remove managed CLI shims on destroy-user-data

[rluo8]

Summary

Sibling-scoped nemoclaw uninstall kept installer-managed ~/.local/bin CLI shims even with --destroy-user-data, so a destructive uninstall could exit 0 while leaving nemoclaw on PATH. With --destroy-user-data, the scoped path now removes those managed shims and still keeps the shared npm CLI package for remaining gateways.

Related Issue

Fixes #9277

Changes

• Extract removeManagedCliShims() from removeNemoclawCli() so shim cleanup can run without uninstalling the shared global npm package; return the removed count so scoped destroy logs only when a managed shim was actually deleted.
• On sibling-scoped uninstall with --destroy-user-data, keep the shared npm package but remove managed user-local CLI shims (~/.local/bin/nemoclaw and agent-alias siblings); classification still preserves foreign files without claiming removal.
• Extend run-plan-gateway-scan-entries.test.ts for destroy-user-data shim removal under unidentified ~/.nemoclaw/gateways/ entries ([Ubuntu 22.04][Install] destructive uninstall reports success but leaves NemoClaw shim on disk #9277), foreign-shim non-removal, and managed-gateway authority helpers.
• Document the scoped --destroy-user-data shim behavior in uninstall and commands reference pages, including the flag table, decision matrix, env var, and CLI help.

Type of Change

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

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/manage-sandboxes/uninstall-nemoclaw.mdx, docs/reference/commands.mdx, src/lib/actions/root-help.ts — flag table, sibling narrative, decision matrix, env var, and CLI help now state that --destroy-user-data also removes installer-managed user-local CLI shims under ~/.local/bin/ while keeping the shared npm package when siblings remain.
• Agent:

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Brev nemoclaw-518ae1 (Ubuntu 24.04): A/B probe showed shim survivors on main (NEMOCLAW_SHIM_ABSENT_EXIT=1) and zero survivors after the fix patch (FIX_DESTROY_SHIM_LOG=yes). vitest run src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts → 10/10 passed on that host. Windows still cannot prove scoped sandbox namespace for the same vitest file.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

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

Summary by CodeRabbit

• New Features
  • Uninstalling with --destroy-user-data now removes installer-managed CLI shims from ~/.local/bin/.
  • The equivalent environment variable supports the same cleanup behavior.
• Bug Fixes
  • Shared CLI packages are preserved when confirmed sibling gateways still use them.
  • Foreign or user-managed shims remain untouched.
• Documentation
  • Updated uninstall help and reference documentation to explain scoped cleanup, sibling gateway detection, and retained shared packages.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ffab72a5-69c8-4eda-9a2a-7a50d501fb02

📥 Commits

Reviewing files that changed from the base of the PR and between 8ff35b3 and 3339df3.

📒 Files selected for processing (1)

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

🚧 Files skipped from review as they are similar to previous changes (1)

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

Included review availability: Your plan includes up to 12 reviews per rolling hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Destructive uninstall now removes installer-managed CLI shims under ~/.local/bin/ when no confirmed sibling gateway remains. It preserves shared npm packages and foreign files. Tests, CLI help, and documentation cover the updated behavior.

Changes

Uninstall shim cleanup

Layer / File(s)	Summary
Managed shim removal src/lib/actions/uninstall/run-plan.ts	The uninstall plan removes recognized NemoClaw and agent-alias shims, preserves foreign files, and reports successful removals.
Scoped destructive cleanup src/lib/actions/uninstall/run-plan.ts	Scoped cleanup passes confirmed sibling gateway ports, removes managed shims only when no confirmed sibling remains, and retains the shared CLI package.
Validation and uninstall contract src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts, src/lib/actions/root-help.ts, docs/manage-sandboxes/uninstall-nemoclaw.mdx, docs/reference/commands.mdx	Tests cover managed, foreign, and sibling-gateway cases. Help and documentation describe conditional shim removal and shared-package retention.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 3339d

This localized uninstall change removes managed user-local CLI shims during destructive sibling-scoped cleanup while preserving the shared package for remaining gateways. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.78% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the uninstall fix: removing managed CLI shims during destructive cleanup.
Linked Issues check	✅ Passed	The changes address issue #9277 by removing managed shims during destructive uninstall while preserving confirmed sibling gateway resources.
Out of Scope Changes check	✅ Passed	The code, tests, documentation, and CLI help changes directly support the linked uninstall objective and contain no unrelated scope.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/9277-uninstall-destroy-shim

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 3339df3 in the fix/9277-uninstall-d... branch remains at 96%, unchanged from commit fda9eb1 in the main branch.

---

_{Updated August 17, 2026 07:40 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-9288.docs.buildwithfern.com/nemoclaw

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 3 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 3 more warnings, the same number of suggestions.

5 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• installer-managed user-local CLI shims at docs/manage-sandboxes/uninstall-nemoclaw.mdx:28: primary classified it as justified; the second opinion classified it as define.
• sibling evidence at docs/manage-sandboxes/uninstall-nemoclaw.mdx:28: selected only by the second-opinion lane as define.
• managed CLI shims at src/lib/actions/root-help.ts:88: selected only by the second-opinion lane as replace.
• shared npm CLI package at docs/manage-sandboxes/uninstall-nemoclaw.mdx:28: selected only by the second-opinion lane as define.
• confirmed sibling gateway at docs/manage-sandboxes/uninstall-nemoclaw.mdx:28: selected only by the second-opinion lane as define.

3 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• bootstrap-install-smoke: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• onboard-repair: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• state-backup-restore: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — installer-managed user-local CLI shims at docs/manage-sandboxes/uninstall-nemoclaw.mdx:28: Keep this term. The ownership modifier distinguishes removable shims from foreign files.
• justified — sibling evidence is unidentified at docs/manage-sandboxes/uninstall-nemoclaw.mdx:233: Keep this term. It identifies the branch that permits managed-shim removal with --destroy-user-data.
• justified — confirmed sibling gateway port at src/lib/actions/uninstall/run-plan.ts:1739: Keep this term. It identifies the branch that preserves the shared npm package and user-local shims.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

1 optional E2E recommendation

• concurrent-gateway-ports

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[prekshivyas]

Reviewed commit 2610352c587e8eb1340aaebe0c31a37c47e186f8 against the full diff, #9277, current review threads, targeted uninstall tests, CI, and the sensitive-path security rubric.

Blocking lifecycle/ownership regression

When --destroy-user-data is used and any sibling gateway remains, this now removes all managed ~/.local/bin NemoClaw agent shims while intentionally retaining the shared CLI package. That is valid for the unidentified-directory false positive in #9277, but it also runs when otherGatewayPorts proves a real sibling gateway exists. The remaining environment can therefore lose its managed commands even though the shared installation is retained for it. Limit shim removal to the false-positive/unidentified-only case (or otherwise prove the shims are not shared), and add coverage with a confirmed sibling showing its shims remain.

Security review

PASS: secrets, input validation, authentication/authorization, dependencies, cryptography/data protection, and error handling. BLOCKING WARNING: system security/resource ownership—the destructive cleanup crosses the selected gateway boundary. Test coverage currently exercises the false-positive case but not a confirmed sibling.

Validation: the focused scan-entry and gateway-segregation suites passed locally (36/36). CI still had running jobs and a failing static-checks job at review time.

[rluo8]

Addressed the blocking lifecycle/ownership finding in 8ff35b3b8.

Change: scoped --destroy-user-data now removes managed ~/.local/bin shims only when otherGatewayPorts.length === 0 (unidentified / unproven sibling evidence — the #9277 false-positive path). When otherGatewayPorts proves a real sibling, the shared package and managed shims are retained (same log as the non-destroy scoped path).

Coverage: added keeps managed CLI shims with --destroy-user-data when a confirmed sibling gateway remains (#9277) (live list includes nemoclaw-9123). Docs / root-help updated to match.

Local Windows cannot prove sandbox namespace for these scoped suites (exit 1 before CLI step); please re-run the focused scan-entry + segregation suites on Linux/CI.

[prekshivyas]

Approved at 3339df3. The requested ownership fix is present: confirmed sibling gateway ports preserve the shared npm CLI package and installer-managed shims, while the destroy-user-data shim cleanup remains limited to unidentified or unproven scoped evidence. I re-reviewed the destructive cleanup boundary, documentation, and regression coverage; the two focused uninstall suites pass 37/37 locally.