[harjothkhara]

Summary

A gateway-scoped nemoclaw uninstall removed the selected gateway's marked Linux unit before deleting its sandbox through that gateway.
If sandbox deletion failed, later cleanup stopped and the sandbox container remained.

This change deletes the selected gateway's OpenShell resources first.
It removes the marked Linux unit only after OpenShell cleanup succeeds.
Full uninstall behavior is unchanged.

Related Issue

Fixes #8220

Changes

• Move marked Linux unit removal for a gateway-scoped uninstall from Stopping services to OpenShell resources, after selected-sandbox cleanup succeeds.
• Keep the marked Linux unit and gateway process running when selected-sandbox cleanup fails so the user can inspect the remaining state and retry.
• Centralize the default-port, --keep-openshell, and external-supervision checks shared by full and gateway-scoped cleanup.
• Add regressions for successful cleanup ordering and failed selected-sandbox cleanup.
• Document the ordering, partial-completion risk, preserved state, gateway inspection, and gateway-port-preserving retry.

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: Nine-category security review passed with no findings for PR commit c8544155016243c47ed24fc289f54e94da90dadd against base SHA db31c286129e878c3356eed49f76ab259561e47e.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: No waiver. GitHub Actions is running the required checks for PR commit c8544155016243c47ed24fc289f54e94da90dadd.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Reviewed all four effective changed files at PR commit c8544155016243c47ed24fc289f54e94da90dadd against base SHA db31c286129e878c3356eed49f76ab259561e47e. The two changed documentation pages accurately describe cleanup order, failure preservation, possible partial completion, gateway inspection, and retry with the failed gateway port for the shared OpenClaw, Hermes, and LangChain Deep Agents Code uninstall path. The implementation and regression tests match that contract. The normal commit hook passed. Local tests were not run; GitHub Actions is authoritative after the PR commit is pushed.
• Agent: Codex Desktop independent documentation writer; Writing Style Guide path

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh does not change.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub — all 25 commits appear as Verified.
• 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 — GitHub Actions is running for PR commit c8544155016243c47ed24fc289f54e94da90dadd.
• Applicable broad gate passed — GitHub Actions is running for PR commit c8544155016243c47ed24fc289f54e94da90dadd.
• 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) — the authoritative Fern Preview check is running.
• Doc pages follow the style guide (doc changes only) — independent documentation writer review passed.
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; no new page.

Security Review

Verdict

PASS with no findings.
Reviewed PR commit c8544155016243c47ed24fc289f54e94da90dadd against base SHA db31c286129e878c3356eed49f76ab259561e47e.
The change corrects sequencing in the existing supported uninstall lifecycle.
It does not create a product surface or require a product, business, or architecture decision.
This security verdict does not waive repository merge gates.

Findings Table

No findings.

Detailed Analysis

1. Secrets and Credentials — PASS. No secret, credential, sensitive value, or sensitive logging behavior changes.
2. Input Validation and Data Sanitization — PASS. Existing gateway selection and argv-based OpenShell command construction remain unchanged. No shell evaluation, parser, or path surface is added.
3. Authentication and Authorization — PASS. Cleanup remains constrained by gateway selection, default-port scope, managed-unit markers, no-follow file handling, --keep-openshell, and lifecycle authority.
4. Dependencies and Third-Party Libraries — PASS. No dependency, lockfile, container image, download, registry, or provenance change is present.
5. Error Handling and Logging — PASS. Sandbox-deletion and gateway-registration failures return nonzero before unit or process removal. Diagnostics disclose no secret material and document possible partial completion.
6. Cryptography and Data Protection — PASS / not applicable. No cryptographic behavior changes. Preserved retry state prevents the selected sandbox from being abandoned after gateway shutdown.
7. Configuration and Security Headers — PASS. Configuration ownership checks remain in force. Upstream, foreign, symlinked, and externally supervised resources remain preserved. Full-uninstall conditions are unchanged.
8. Security Testing — PASS. Tests cover cleanup ordering, successful container cleanup, sandbox-deletion failure, and gateway-registration failure. GitHub Actions is running these tests for the PR commit.
9. System Security — PASS. The selected OpenShell gateway remains available until its OpenShell resources are removed. Failure preserves an inspectable retry path and sibling gateway isolation.

Files Reviewed

• 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

GitHub Actions is authoritative for PR commit c8544155016243c47ed24fc289f54e94da90dadd against base SHA db31c286129e878c3356eed49f76ab259561e47e.
The new checks are running.
No required check has a maintainer waiver.

---

Signed-off-by: harjoth harjoth.khara@gmail.com

Summary by CodeRabbit

• Bug Fixes

  • Selected sandbox resources are now removed before stopping the gateway service.
  • Failed cleanup exits with an error while preserving the gateway service for retry.
  • Improved cleanup behavior for default gateway services during full and scoped uninstalls.
  • Cleanup now reports when partial removal may have occurred.

• Documentation

  • Added guidance on cleanup ordering, failure handling, partial cleanup, inspecting gateways, and retrying uninstall operations.