fix(uninstall): preserve OpenShell gateway state

[senthilr-nv]

Summary

nemoclaw uninstall --keep-openshell now preserves the local gateway state required by the retained OpenShell service and process. Uninstall also preserves that state whenever the gateway is externally supervised. Previously, cleanup could remove openshell-gateway.toml while leaving the gateway process or enabled user service running.

Related Issue

Fixes #7830.

Changes

• Preserve the selected OpenShell gateway's local state when --keep-openshell is selected, including scoped cleanup when sibling gateways remain.
• Preserve the selected local gateway state across full, shared-registry scoped, and ordinary scoped cleanup when the gateway is externally supervised.
• Keep normal NemoClaw-managed full uninstall behavior unchanged: it still removes the managed gateway state.
• Extend the gateway-service and gateway-segregation tests to cover preservation and removal across each cleanup branch.
• Document managed and externally supervised local-state preservation in the uninstall guide, CLI reference, and lifecycle-authority reference.

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, and docs/deployment/gateway-lifecycle-authority.mdx remain accurate after rebasing onto current main; npm run docs previously passed with zero errors and two pre-existing Fern warnings. The rebased focused uninstall suite passes 78/78.
• Agent: OpenAI Codex / Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• Station profile/scenario: v0.0.97 dual-DGX Station rollback reproduction is recorded in Uninstall keep-openshell removes required gateway state #7830.
• Result: The release command reproduced the missing gateway-state restart loop.
• Supporting evidence: Uninstall keep-openshell removes required gateway state #7830

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 — rebased head: npm exec -- vitest run --project cli src/lib/actions/uninstall/run-plan-gateway-service.test.ts src/lib/actions/uninstall/run-plan.test.ts src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts src/lib/actions/uninstall/run-plan-dual-station.test.ts (78 passed)
• 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) — zero errors and two pre-existing Fern warnings
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Uninstall now more reliably preserves local OpenShell gateway configuration/state when --keep-openshell is set, including scoped uninstall scenarios and cases involving external supervision.
  • A full uninstall still removes NemoClaw-managed gateway state and related files after completion.
• Documentation
  • Clarified what ~/.local/state/nemoclaw contains on Linux and how $$ nemoclawn uninstall options (including --yes and --keep-openshell) affect it.
• Tests
  • Updated uninstall and gateway segregation tests to verify persistence and cleanup behavior for OpenShell gateway state.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The uninstall flow now preserves local gateway state when --keep-openshell is used or the gateway is externally supervised, while full uninstall continues removing it. Tests cover scoped and full cleanup, and documentation describes the updated behavior.

Changes

Gateway state preservation

Layer / File(s)	Summary
Conditional gateway state cleanup src/lib/actions/uninstall/run-plan.ts	Local gateway state is retained for keepOpenShell and externally supervised paths, and removed during full cleanup.
Gateway state scenario validation src/lib/actions/uninstall/run-plan-gateway-service.test.ts, src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts	Tests create gateway state, simulate gateway listings, and verify retention across scoped scenarios and deletion during full uninstall.
Uninstall behavior documentation docs/deployment/gateway-lifecycle-authority.mdx, docs/manage-sandboxes/uninstall-nemoclaw.mdx, docs/reference/commands.mdx	Documentation describes local gateway state contents and its preservation for retained and externally supervised gateways.

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

Sequence Diagram(s)

sequenceDiagram
  participant UninstallCommand
  participant executePlan
  participant GatewayState
  UninstallCommand->>executePlan: Run uninstall with retention options
  executePlan->>GatewayState: Preserve local gateway state
  UninstallCommand->>executePlan: Run full uninstall
  executePlan->>GatewayState: Remove local gateway state

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7631: Modifies related OpenShell cleanup behavior in the uninstall planning logic.

Suggested reviewers: apurvvkumaria, jyaunches

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address #7830 by preserving the OpenShell gateway's local state while keeping the service and process intact, and normal uninstall still removes managed state.
Out of Scope Changes check	✅ Passed	The code, tests, and documentation changes all relate to uninstall behavior and gateway-state preservation; no clearly unrelated changes are evident.
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 matches the main change: uninstall now preserves OpenShell gateway state.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/actions/uninstall/run-plan-gateway-service.test.ts`:
- Around line 117-127: Add a sibling-gateway or unreadable-gateway-list scenario
alongside the test using fixture, writeManagedService, writeGatewayEnv, and
writeGatewayState, so uninstall enters the scoped cleanup branch while
keepOpenShell is enabled. Assert exitCode remains successful and
gatewayStatePath still exists, verifying selected gateway state is preserved;
keep the existing service and environment assertions as appropriate.

In `@src/lib/actions/uninstall/run-plan.ts`:
- Around line 1758-1760: Guard the scoped cleanup removal of
paths.selectedGatewayLocalStateDir with options.keepOpenShell in the uninstall
plan, matching the existing protection for paths.gatewayLocalStateDir. Add a
sibling/unreadable-list regression test covering scopedToSelectedGateway with
keepOpenShell enabled, ensuring the selected gateway state is retained.
- Around line 1758-1760: Update the uninstall plan around the keepOpenShell
conditional so it only selects whether gateway state should be preserved or
removed, and delegate the actual persisted gateway local-state deletion to the
relevant state-layer API under src/lib/state. Remove the direct removePath call
from the action while preserving the existing keepOpenShell logging behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 533e7a05-fd9f-433c-8b35-a9028f845763

📥 Commits

Reviewing files that changed from the base of the PR and between ae71359 and 0de40b9.

📒 Files selected for processing (4)

• docs/manage-sandboxes/uninstall-nemoclaw.mdx
• docs/reference/commands.mdx
• src/lib/actions/uninstall/run-plan-gateway-service.test.ts
• src/lib/actions/uninstall/run-plan.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of 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

2 optional E2E recommendations

• gateway-guard-recovery
• openshell-gateway-upgrade

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover legacy sibling cleanup with --keep-openshell

• Location: src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts:652
• Category: tests
• Problem: The legacy default-root sibling cleanup test exercises the changed preservation branch with keepOpenShell set to false only. It does not prove that the new guard preserves gatewayLocalStateDir when --keep-openshell is set.
• Impact: A regression in the legacy shared-registry branch can again remove the configuration file required by a retained gateway service while the ordinary scoped and full-path tests still pass.
• Recommendation: Add a legacy default-port sibling fixture with a gateway-state file, run uninstall with keepOpenShell enabled, and assert that the file remains.
• Verification: Read the legacy shared-registry branch in src/lib/actions/uninstall/run-plan.ts:1715-1727 and run the added Vitest case.
• Test coverage: A unit test for default-port legacy sibling cleanup with keepOpenShell: true that asserts openshell-docker-gateway/openshell-gateway.toml remains after uninstall.
• Evidence: src/lib/actions/uninstall/run-plan.ts:1715-1727 adds the keepOpenShell preservation guard in the legacy shared-registry cleanup path. src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts:652 existing legacy sibling coverage uses keepOpenShell: false at line 691.

Workflow run details

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/actions/uninstall/run-plan.ts`:
- Around line 1722-1723: Update all three cleanup branches in run-plan.ts: at
lines 1722-1723, 1752-1753, and 1760-1762, require both the existing retention
condition and !externallySupervised before removing gateway state; otherwise
retain the corresponding path and emit an appropriate retention log. Apply this
to paths.selectedGatewayLocalStateDir in the shared-registry branch,
selected-gateway state in the scoped cleanup branch, and
paths.gatewayLocalStateDir in the non-scoped cleanup branch.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8b6e8849-2f0f-4230-bd3f-e80bd4695125

📥 Commits

Reviewing files that changed from the base of the PR and between 0de40b9 and 1016d24.

📒 Files selected for processing (2)

• src/lib/actions/uninstall/run-plan-gateway-service.test.ts
• 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-gateway-service.test.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts`:
- Line 142: Strengthen the assertion in the uninstall test around
gatewayStatePath to verify the file contents remain identical to the original
TOML after uninstall, not merely that the path exists. Capture the pre-uninstall
contents and compare them with the post-uninstall read while preserving the
existing existence check.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 452a2a8d-0418-48b7-aad2-37531b4538f3

📥 Commits

Reviewing files that changed from the base of the PR and between 1016d24 and e4b2448.

📒 Files selected for processing (3)

• src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts
• src/lib/actions/uninstall/run-plan-gateway-service.test.ts
• src/lib/actions/uninstall/run-plan.ts

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

• src/lib/actions/uninstall/run-plan.ts
• src/lib/actions/uninstall/run-plan-gateway-service.test.ts

[senthilr-nv]

CI is green for the changed behavior, reviews, docs receipt, security scans, builds, and selected E2E coverage. The focused uninstall suite passes 78/78.

The remaining red checks (static-checks, CLI shard 7, and their aggregate jobs) all report the same current-main source-architecture ratchet: src/lib/core/shell-quote.ts fan-in is 26 while its stale limit is 27. This PR does not touch that file or its import graph. Current main commit 3aea38c4 (merged via #7632) records the same condition as unrelated base debt.

No change to #7831 is warranted for that baseline issue. Maintainer approval plus the repository's normal waiver/fix-forward decision for the unrelated ratchet is the remaining merge action.