Skip to content

fix(uninstall): remove openshell helper binaries#3483

Merged
cv merged 3 commits into
mainfrom
issue-3455-uninstall-openshell-helper-binaries
May 13, 2026
Merged

fix(uninstall): remove openshell helper binaries#3483
cv merged 3 commits into
mainfrom
issue-3455-uninstall-openshell-helper-binaries

Conversation

@jyaunches

@jyaunches jyaunches commented May 13, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Remove all installer-managed OpenShell binaries during nemoclaw uninstall, not just the openshell wrapper
  • Cover openshell-gateway, openshell-sandbox, and openshell-driver-vm in uninstall path planning and runtime cleanup tests
  • Update --keep-openshell wording to refer to OpenShell binaries

Testing

  • npm test -- src/lib/domain/uninstall/paths.test.ts src/lib/domain/uninstall/plan.test.ts src/lib/actions/uninstall/run-plan.test.ts
  • npm run build:cli

Fixes #3455

Summary by CodeRabbit

  • Documentation

    • Clarified uninstall option and command reference wording to indicate management of multiple OpenShell binaries.
  • Improvements

    • Updated uninstall messaging to more clearly state when OpenShell binaries are being kept.
  • Tests

    • Added and expanded unit and end-to-end tests covering OpenShell uninstall behavior, including version-pin scenarios.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 13, 2026

Copy link
Copy Markdown
Contributor

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: 0809fb1e-03f0-423b-b1c4-1593d9274df4

📥 Commits

Reviewing files that changed from the base of the PR and between 63f3a68 and 99940b9.

📒 Files selected for processing (2)
  • test/e2e/docs/parity-inventory.generated.json
  • test/e2e/docs/parity-map.yaml
✅ Files skipped from review due to trivial changes (1)
  • test/e2e/docs/parity-inventory.generated.json

📝 Walkthrough

Walkthrough

This PR fixes issue #3455 where nemoclaw uninstall removed only the openshell CLI binary but left behind helper binaries (openshell-gateway, openshell-sandbox). The fix introduces a managed binaries constant, dynamic path generation, updated action types, and comprehensive tests to handle removal of all managed OpenShell binaries.

Changes

OpenShell multi-binary uninstall fix

Layer / File(s) Summary
Managed binaries definition and path generation
src/lib/domain/uninstall/paths.ts, src/lib/domain/uninstall/paths.test.ts
OPENSHELL_MANAGED_BINARIES constant defines which OpenShell binaries require managed uninstall handling (openshell, openshell-gateway, openshell-sandbox). Helper function openshellInstallPathsForBinDirs() dynamically generates install paths by combining managed binary names with candidate bin directories. defaultUninstallPaths now computes openshellInstallPaths instead of hardcoding values.
Uninstall action types and plan building
src/lib/domain/uninstall/plan.ts, src/lib/domain/uninstall/plan.test.ts
UninstallPlanAction type replaced preserve-openshell-binary and delete-openshell-binary with preserve-openshell-install-paths and delete-openshell-install-path variants. buildUninstallPlan updated to emit preserve-openshell-install-paths with all computed paths when keepOpenShell is true, or individual delete-openshell-install-path actions for each path when false. Tests validate expected actions for both preserve and delete branches.
Action execution and removal testing
src/lib/actions/uninstall/run-plan.ts, src/lib/actions/uninstall/run-plan.test.ts
Log message updated from singular "openshell binary" to plural "OpenShell binaries". New test verifies runUninstallPlan with keepOpenShell disabled removes all managed helper binaries from ~/.local/bin by simulating presence, stubbing file system calls, and asserting rmSync calls and removal log messages.
User documentation updates
README.md, docs/manage-sandboxes/lifecycle.md, docs/reference/commands.md
Updated --keep-openshell flag descriptions across all documentation to reference "OpenShell binaries" (plural) instead of "openshell binary" (singular).
E2E inventory
test/e2e/docs/parity-inventory.generated.json
Added test-openshell-version-pin.sh entry and updated totals metadata for scripts/assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

OpenShell, fix

Suggested reviewers

  • cv

Poem

🐰 A rabbit hops through OpenShell's domain,
Where sandbox and gateway binaries remain—
No more leaving stragglers upon uninstall,
Now all managed friends answer the call!
The claws retract cleanly, every bit gone,
A fresh slate awaits as you reinstall anon. 🌙

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% 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 Title clearly and specifically summarizes the main change: removing openshell helper binaries during uninstall, matching the primary objective from issue #3455.
Linked Issues check ✅ Passed All code changes comprehensively address issue #3455 requirements: manages multiple OpenShell binaries via OPENSHELL_MANAGED_BINARIES constant, generates install paths for all helper binaries, updates uninstall plan logic and tests, and ensures runtime cleanup includes openshell-gateway, openshell-sandbox, and openshell-driver-vm.
Out of Scope Changes check ✅ Passed All changes are directly scoped to issue #3455 objectives: binary management refactoring, uninstall path planning, runtime cleanup logic, and documentation/test updates align with fixing the uninstall bug; no extraneous changes detected.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-3455-uninstall-openshell-helper-binaries

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.


Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented May 13, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: deployment-services-e2e
Optional E2E: gpu-e2e, credential-migration-e2e

Dispatch hint: deployment-services-e2e

Workflow run

Full advisor summary

Pi Semantic E2E Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • deployment-services-e2e: TC-DEPLOY-03 in test/e2e/test-deployment-services.sh exercises nemoclaw uninstall --keep-openshell --yes end-to-end and verifies the openshell binary remains on PATH while the nemoclaw CLI is removed. This is the most direct coverage of the flag whose semantics this PR redefines (now preserving all four OpenShell helper binaries instead of just openshell).

Optional E2E

  • gpu-e2e (high): test/e2e/test-gpu-e2e.sh runs a full uninstall.sh --yes --delete-models and asserts $HOME/.nemoclaw is removed afterward, exercising the non-keep-openshell branch where the new code now removes openshell, openshell-gateway, openshell-sandbox, and openshell-driver-vm. Useful confidence check that real installed helper binaries are cleaned up, but expensive (self-hosted GPU runner) and behavior change is small.
  • credential-migration-e2e (medium): Indirectly touches the uninstall/reinstall lifecycle and verifies post-uninstall state on disk; not directly testing the binary list change but a low-cost confidence check that nothing in the surrounding cleanup path regressed.

New E2E recommendations

  • uninstall-lifecycle (medium): Existing E2E coverage (TC-DEPLOY-03) only checks that openshell itself is preserved when --keep-openshell is passed and that the nemoclaw CLI is removed. No existing E2E asserts that, after a full nemoclaw uninstall (without --keep-openshell), the new managed helper binaries openshell-gateway, openshell-sandbox, and openshell-driver-vm are actually removed from both /usr/local/bin and the writable user bin (e.g. ~/.local/bin). Likewise, the --keep-openshell preservation guarantee for these three additional binaries is not covered.
    • Suggested test: Add a deployment-services-style E2E assertion (or new test-uninstall-openshell-binaries.sh) that, on a host where openshell, openshell-gateway, openshell-sandbox, and openshell-driver-vm are all installed: (a) nemoclaw uninstall --keep-openshell --yes leaves all four binaries on PATH, and (b) nemoclaw uninstall --yes (no --keep-openshell) removes all four from both /usr/local/bin and ~/.local/bin. Wire it into nightly-e2e.yaml alongside deployment-services-e2e.

Dispatch hint

  • Workflow: nightly-e2e.yaml
  • jobs input: deployment-services-e2e

@github-actions

Copy link
Copy Markdown
Contributor

Selective E2E Results — ✅ All requested jobs passed

Run: 25828420769
Target ref: 63f3a68869fccddcde85eca9350be0d95227376c
Workflow ref: main
Requested jobs: deployment-services-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job Result
deployment-services-e2e ✅ success

@cv cv added the v0.0.41 label May 13, 2026
@cv cv self-requested a review May 13, 2026 22:06
@cv cv merged commit de22347 into main May 13, 2026
31 checks passed
cjagwani pushed a commit that referenced this pull request May 14, 2026
Resolve the two output threads in #3456 left after the core dead-loop fix
landed via #3459 + #3434:

Sub-bug #3 — `src/lib/onboard.ts` printed
  `nemoclaw <name> destroy --yes && nemoclaw onboard --gpu`
with a literal `<name>` placeholder, and assumed at least one sandbox
was registered. When the GPU-passthrough mismatch hit on the State B
re-run path with an empty registry (the dead-loop case), the hint was
not actionable. Replace with a registry-aware helper at
`src/lib/onboard/gpu-recovery.ts` that renders the right shape:
  - empty registry → suggest `nemoclaw uninstall && nemoclaw onboard --gpu`
  - one sandbox → suggest destroy --yes --cleanup-gateway for that name
  - multiple sandboxes → list each, only the last gets --cleanup-gateway

Sub-bug #4 — `src/lib/actions/uninstall/run-plan.ts` printed
  `Destroyed gateway 'nemoclaw' skipped`
when the openshell destroy no-op'd (gateway already gone) — the
"Destroyed … skipped" wording was self-contradictory. Extend
`runOptional` with an `onSkip` option; route the gateway destroy to
emit `Gateway 'nemoclaw' already removed or unreachable` on no-op.

Tests:
- `src/lib/onboard/gpu-recovery.test.ts` (6 tests): forbid literal
  `<name>` placeholder anywhere in the output; cover empty / single /
  multi-sandbox cases; defensive filter on whitespace names so a
  `nemoclaw  destroy` rendering can never happen.
- `src/lib/actions/uninstall/run-plan.test.ts`: assert the new
  "already removed or unreachable" wording and the absence of the
  "Destroyed gateway 'nemoclaw' skipped" string.

The core dead loop itself (sub-bugs #1, #2 and State B GPU mismatch)
is already addressed by #3459 + #3434 + #3483; #3456 will close once
this lands. See the #3456 status comment for the full mapping.

Refs #3456. Mirrors (and tightens) the approach in the closed PR #3464,
which left the literal `<name>` placeholder in tests per CodeRabbit
feedback that was never addressed.

Signed-off-by: Charan Jagwani <charjags100@gmail.com>
cv pushed a commit that referenced this pull request May 14, 2026
## Summary
- Bump the docs metadata and version switcher to `0.0.41`.
- Add v0.0.41 release notes plus operator guidance for OpenShell
pinning, Docker bridge reachability, Local Ollama proxy reachability,
and Docker GPU onboarding diagnostics.
- Refresh generated `nemoclaw-user-*` skills from the updated docs.

## Source summary
- #3434 -> `docs/reference/commands.md`,
`docs/reference/troubleshooting.md`, `docs/about/release-notes.md`:
Document Linux Docker-driver GPU onboarding behavior, diagnostics,
cleanup guidance, and the `NEMOCLAW_DOCKER_GPU_PATCH` troubleshooting
escape hatch.
- #3483 -> `docs/about/release-notes.md`: Note that `nemoclaw uninstall`
removes all installer-managed OpenShell helper binaries unless
`--keep-openshell` is passed.
- #3446 -> `docs/reference/commands.md`,
`docs/reference/troubleshooting.md`, `docs/about/release-notes.md`:
Document blueprint-driven OpenShell install pin resolution and fallback
behavior.
- #3472 -> `docs/inference/use-local-inference.md`,
`docs/reference/troubleshooting.md`, `docs/about/release-notes.md`:
Document sandbox-side Local Ollama auth proxy reachability checks and
firewall remediation.
- #3459 -> `docs/reference/commands.md`,
`docs/reference/troubleshooting.md`, `docs/about/release-notes.md`:
Document Docker-driver sandbox-to-gateway reachability checks and
firewall remediation.

## Test plan
- `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix
nemoclaw-user`
- `make docs`
- `git diff --check`
- `npm run build:cli`
- `npm run typecheck:cli`
- pre-commit hooks during `git commit`

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

## Summary by CodeRabbit

* **New Features**
* Added `nemoclaw inference get` command to check current inference
settings
* Improved gateway health validation with Linux firewall remediation
guidance

* **Bug Fixes**
  * Enhanced proxy readiness validation with sandbox network path probes
  * Improved local Ollama route onboarding with rerun-safe fixes
  * Better sandbox-to-gateway connectivity detection

* **Documentation**
* Expanded troubleshooting guidance for firewall and connectivity issues
* Updated CLI reference with new command and environment variable
documentation
  * Added gateway binding and Docker-driver GPU compatibility guidance

<!-- 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/3531)

<!-- review_stack_entry_end -->

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
cv added a commit that referenced this pull request May 14, 2026
…3520)

> **Draft for visibility.** Issue-autopilot Stages 4-5 of #3456. Will
mark ready once batch self-review + CI complete.

## Summary

Closes the two remaining output threads in #3456 after the core
dead-loop fix already landed on `main` (via #3459, #3434, #3483). Full
sub-bug mapping in the [#3456 status
comment](#3456 (comment)).

- **Sub-bug #3** — `nemoclaw <name> destroy --yes` recovery hint
replaced with a registry-aware helper.
- **Sub-bug #4** — `Destroyed gateway 'nemoclaw' skipped`
self-contradictory wording replaced with `Gateway 'nemoclaw' already
removed or unreachable`.

## Acceptance criteria mapping

| Sub-bug | Resolution | Evidence |
|---|---|---|
| #1 dead loop | Already fixed on main (#3459) | out of scope |
| #2 firewall diagnostic | Already fixed on main (#3459) | out of scope
|
| **#3** literal `<name>` placeholder | **This PR** |
`src/lib/onboard/gpu-recovery.ts` + `onboard.ts:10387-10405` |
| **#4** misleading "skipped" wording | **This PR** |
`src/lib/actions/uninstall/run-plan.ts:210-228, 407-414` |
| #5 uninstall residuals | Already fixed on main (#3483) | out of scope
|

## Behavior matrix

`gpuPassthroughRecoveryLines(names)`:

| Input | Suggestion |
|---|---|
| `null` / `[]` | `nemoclaw uninstall && nemoclaw onboard --gpu` |
| one sandbox | `nemoclaw <name> destroy --yes --cleanup-gateway &&
nemoclaw onboard --gpu` |
| many sandboxes | each `destroy --yes`, only the last gets
`--cleanup-gateway` |

## Test plan

```
npm run typecheck:cli
npx vitest run src/lib/onboard/gpu-recovery.test.ts src/lib/actions/uninstall/run-plan.test.ts
```

22 tests pass (6 new + 16 existing).

## Notes for reviewers

- This is the work [#3464
attempted](#3464); that PR was
closed without merging after CodeRabbit asked for the `<name>`
placeholder to be forbidden in tests via negative assertion. This PR
adopts that refinement.
- `runOptional` extension is backwards-compatible — existing callers
without `onSkip` get the original wording.

Closes #3456 once merged.

---------

Signed-off-by: Charan Jagwani <charjags100@gmail.com>
Co-authored-by: Charan Jagwani <charjags100@gmail.com>
Co-authored-by: Carlos Villela <cvillela@nvidia.com>
@wscurran wscurran added the bug-fix PR fixes a bug or regression label Jun 8, 2026
@jyaunches jyaunches deleted the issue-3455-uninstall-openshell-helper-binaries branch June 12, 2026 13:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug-fix PR fixes a bug or regression

Projects

None yet

3 participants