fix(uninstall): exit nonzero when openshell is unavailable (#7628)

[kagura-agent]

Summary

nemoclaw uninstall now exits nonzero when the openshell command is unavailable.
The check runs after confirmation and before any cleanup mutation, so the user can restore the command and retry without a partial uninstall.

Related Issue

Fixes #7628

Product Scope

Product scope is approved independently of GitHub merge state.
This PR restores the existing supported uninstall contract documented in docs/manage-sandboxes/uninstall-nemoclaw.mdx and docs/reference/commands.mdx.
It adds no integration, recipe, image, third-party stack, configuration, or product surface.

Changes

• Check for the openshell command after uninstall confirmation and before the cleanup plan mutates services, processes, or files.
• Retain the check inside removeOpenShellResources() so the plan fails if the command disappears after the first check.
• Report an actionable error that tells the user to restore openshell to PATH and run uninstall again.
• Extend the regression test to prove that the missing-command path runs no command, kill, or remove operation.
• Resolve PR Review Advisor finding PRA-1, which reported that the original check ran after the "Stopping services" step.

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: The canonical uninstall and command-reference pages already state the missing-OpenShell nonzero restore-and-retry contract.
• 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: Codex Desktop reviewed all nine security categories for PR SHA 190841bc against base SHA 07553d70; all categories passed with no findings. This is agent evidence, not human approval.
• 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: no-docs-needed
• Evidence: docs/manage-sandboxes/uninstall-nemoclaw.mdx and docs/reference/commands.mdx already state the missing-OpenShell nonzero restore-and-retry contract. No documentation or documentation-build input changed. Review covers PR SHA 190841bc against base SHA 07553d70.
• Agent: Codex Desktop documentation-writer subagent

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 check:diff passed 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: npx vitest run --project cli src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts passed 27 tests; npm run build:cli passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; the diff changes one uninstall guard and its focused regression.
• 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)

Exact-state evidence:

• PR SHA: 190841bc46ba8b64ee9811b9c00930e106eb262f
• Base SHA: 07553d70b7721e83f18362e7b172b3f11c321af7
• Refresh: signed, non-force merge from upstream/main
• Displayed commits: four; GitHub reports all four as Verified
• Cross-issue sweep: no adjacent fix or contradiction above the medium-confidence floor
• Human Files changed review and GitHub approval: pending for this exact PR SHA
• DGX Station or other hardware review: not performed and not required by the changed paths

---

Signed-off-by: Kagura kagurachen@agent.qq.com
Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Walkthrough

The uninstall flow now exits nonzero when openshell is unavailable, logs an actionable error, and prevents further cleanup. The gateway segregation test adds service-file setup and verifies no commands or resource-removal operations run.

Changes

OpenShell uninstall failure handling

Layer / File(s)	Summary
Missing OpenShell command handling src/lib/actions/uninstall/run-plan.ts, src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts	The uninstall implementation returns failure with a shared error message when openshell is missing, while the test verifies the updated message and confirms that commands, process termination, and file removal are not invoked.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: apurvvkumaria, cv, laitingsheng

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The code now stops uninstall and returns failure when openshell is missing, matching #7628's expected nonzero exit and retry guidance.
Out of Scope Changes check	✅ Passed	Changes are limited to the uninstall flow and its test, with no unrelated feature work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely matches the main change: uninstall now exits nonzero when openshell is unavailable.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 5 warnings · 0 suggestions

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

Workflow run details

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

[senthilr-nv]

Approved for exact head 9e6cc74 against base 0b722a4. The uninstall guard now fails before cleanup mutations, retains the TOCTOU check, and tests verify no command, kill, or removal occurs. No blocking issues found.

[senthilr-nv]

Automated-review disposition for exact head 190841bc46ba8b64ee9811b9c00930e106eb262f against base 07553d70b7721e83f18362e7b172b3f11c321af7:

The primary PR Review Advisor completed with high confidence and reported 0 blockers, 0 warnings, and 0 suggestions. The optional Nemotron lane stopped after a partial, low-confidence review and preserved five warning-shaped records. Each is dispositioned below:

1. Fail-fast behavior change: intended and accepted. This restores issue nemoclaw uninstall silently skips OpenShell cleanup when openshell binary is unavailable instead of exiting nonzero #7628's binding acceptance criteria and the already-published uninstall contract. Adding a new --force surface would be out of scope and lacks product-scope approval.
2. Guard placement: positive confirmation, not an actionable finding. The guard returns before executePlan.
3. Acceptance coverage: positive confirmation, not an actionable finding. The implementation and regression test satisfy nemoclaw uninstall silently skips OpenShell cleanup when openshell binary is unavailable instead of exiting nonzero #7628.
4. Documentation alignment: positive confirmation, not an actionable finding. The exact-head documentation-writer review found no-docs-needed; the existing uninstall and command-reference pages already state the behavior.
5. --keep-openshell interaction: not actionable. That flag preserves the OpenShell binary, managed service files, and gateway process, but uninstall still removes OpenShell sandboxes, providers, and the selected gateway registration. Those operations require the openshell command, so the unconditional availability guard is correct.

The regression test verifies exit code 1, the actionable error, and that no command, process kill, or file removal occurs. No code or documentation change is required from these partial-lane records.