fix(uninstall): stop the selected gateway counting itself a sibling

[yanyunl1991]

Summary

On a host with one gateway, nemoclaw uninstall could detect the selected gateway as a sibling. That false detection scoped cleanup to the selected gateway and preserved shared host resources. This change excludes the selected gateway port from the sibling scan.

Related Issue

Closes #7987.

Reproduction

Run on the contributor's Ubuntu 24.04 x86_64 test host without a GPU, against commit 387cb0864 on main.

1. Onboard one sandbox so one gateway (nemoclaw, port 8080) is registered.
2. Ensure a ~/.nemoclaw/gateways/8080 directory exists.
3. Run nemoclaw uninstall --yes.

Environment

• Ubuntu 24.04 x86_64 test host without a GPU
• NemoClaw commit 387cb08644fe030bb85146255f4b77e3c54697d2 on main
• One sandbox (my-assistant) and one gateway; openshell gateway list -o json returns exactly [{"name":"nemoclaw"}]

Observed on main before the fix

NemoClaw Uninstaller
This will remove NemoClaw resources owned by gateway 'nemoclaw'.
[1/6] Stopping services
Sibling gateways remain; kept shared helper services and sibling forwards.
...
Sibling gateways remain; kept the shared HTTPS Pin Runtime adapter.
Sibling gateways remain; kept shared OpenShell provider registrations.
Sibling gateways remain; kept the shared NemoClaw CLI and shell shims.
Sibling gateways remain; kept shared Docker images.
Sibling gateways remain; kept host-shared Ollama models.
Sibling gateways remain; kept shared runtime files and OpenShell binaries.
Sibling gateways remain; kept shared OpenShell and NemoClaw config.

Eight Sibling gateways remain lines appeared on a host with one gateway.

Observed on fix/uninstall-self-sibling-7987 after the fix

The contributor used the same host and base commit with this change:

NemoClaw Uninstaller
This will remove all NemoClaw resources.
[1/6] Stopping services
No local OpenShell forward processes found
...
Removed /home/<user>/.config/openshell
Claws retracted. Until next time.

Sibling gateways remain occurrences: 0. Scoped banner occurrences: 0. cleanup was incomplete occurrences: 0.

Analysis

inspectOtherGatewayEnvironments in src/lib/actions/uninstall/run-plan.ts walks <shared>/gateways/. For each entry, it determines whether the entry represents another gateway. It excluded the selected gateway by path identity:

const candidate = path.resolve(gatewaysDir, entry.name);
if (candidate === selectedRoot) return false;

selectedRoot is nemoclawStateRoot(home, GATEWAY_PORT). That helper is asymmetric in src/lib/state/state-root.ts:

return gatewayPort === DEFAULT_GATEWAY_PORT
  ? base
  : path.join(base, GATEWAYS_SUBDIR, String(gatewayPort));

For a non-default port, the selected root is <shared>/gateways/<port>, so the comparison excludes it. For the default port, the selected root is the shared root. Therefore, <shared>/gateways/8080 cannot equal it. The entry then reaches the liveness check:

const port = Number(entry.name);          // 8080
const live = liveGatewayNames();
return live.has(resolveGatewayName(port)); // live.has("nemoclaw") -> true

resolveGatewayName(8080) is nemoclaw, which is the selected gateway. Its own liveness therefore marked it as a sibling. A sibling is a different gateway, so this result was incorrect.

otherGatewayEnvironmentsRemain controls scopedToSelectedGateway. That value changes the banner to resources owned by gateway '<name>' and makes each cleanup step preserve shared host state. In scoped mode, uninstall also deletes sandboxes individually instead of using sandbox delete --all. If a per-sandbox deletion cannot reach an absent sandbox, removedSelectedResources becomes false. run-plan.ts then reports Selected gateway cleanup was incomplete; preserving its state for retry. and the reporter exits with status 1. The contributor's host could delete its sandbox, so it exited with status 0 while showing the same eight sibling messages.

Fix

Compare port identity, which the other sibling filters in this file already use:

const port = Number(entry.name);
if (!Number.isInteger(port) || port < 1 || port > 65535) return true;
if (port === GATEWAY_PORT) return false;

Every other sibling filter in run-plan.ts uses GATEWAY_PORT. These include the registry scan and the per-entry checks in the sandbox and registry steps. listGatewayStateRoots in src/lib/state/gateway-registry.ts also skips gatewayPort === DEFAULT_GATEWAY_PORT while enumerating the same directory. The uninstall scan was the only place that used path identity and handled the default port incorrectly.

Whole-class check. selectedRoot was used for this comparison at one site. The other sibling filters are port-based. The only other reader of <shared>/gateways/, listGatewayStateRoots, already excludes the selected port. No other call site needed a change.

Conservative behavior deliberately unchanged. A symbolic link, a non-directory entry, an invalid port name, and a null gateway list still report a sibling. A gateways/8080 entry that is a symbolic link or plain file also remains an unexpected shape. This change removes the confirmed false positive without expanding deletion when inspection is uncertain.

No documentation change required. docs/manage-sandboxes/uninstall-nemoclaw.mdx and docs/reference/commands.mdx already state that uninstall removes shared host resources only when it confirms that no sibling gateways remain. The implementation did not follow that documented contract. This change restores the documented behavior.

Tests. Two cases in run-plan-gateway-segregation.test.ts cover the change:

• A gateways/8080 directory with only nemoclaw live produces full teardown. It emits no Sibling gateways remain message or scoped banner, and it still runs sandbox delete --all. Removing the one-line fix makes this test fail.
• The same gateways/8080 directory with a live nemoclaw-8091 gateway still reports a sibling and preserves gateways/8091.

The existing #7315 orphan and live-sibling cases and the non-default-port segregation cases are unchanged. The contributor reported 106 passing tests across src/lib/actions/uninstall/.

Changes

• Update src/lib/actions/uninstall/run-plan.ts to exclude the selected gateway port from the sibling scan.
• Update src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts to cover the selected gateway and a different live gateway.

Platform Scope

The reporter selected All Platforms after reproducing the defect on Ubuntu 22.04 and 24.04. The contributor verified the change on Ubuntu 24.04 x86_64. The defect is a path-and-port comparison and has no architecture-specific branch.

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 existing uninstall documentation already states the restored behavior. No supported contract changed.
• 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: Security review PASS: fix(uninstall): stop the selected gateway counting itself a sibling #7993 (comment)
• 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: Reviewed the completed change and the existing contract in docs/manage-sandboxes/uninstall-nemoclaw.mdx and docs/reference/commands.mdx. Those pages already state that shared host resources are removed only when no sibling gateways remain, so no documentation file changed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; this PR does not change scripts/prepare-dgx-station-host.sh.
• 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
• 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 — the contributor reported npx prek run --all-files; final-commit evidence for all normal hooks is not recorded.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — the contributor reported 106 passing uninstall tests. GitHub CI passed for commit 479ce777465eb5fc9ca6db91de24e921e2a72cd9.
• Applicable broad gate passed — GitHub CI and the E2E gate passed for commit 479ce777465eb5fc9ca6db91de24e921e2a72cd9.
• 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) — Not applicable; no documentation file changed.
• Doc pages follow the style guide (doc changes only) — Not applicable; no documentation file changed.
• New doc pages include SPDX header and frontmatter (new pages only) — Not applicable; no documentation page was added.

AI Disclosure

• AI-assisted — tool: Claude Code

---

Signed-off-by: Yanyun Liao yanyunl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved gateway uninstall handling so the selected gateway is no longer incorrectly detected as a sibling.
  • Ensured genuine sibling gateways are still detected and retain their scoped cleanup behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The uninstall plan now excludes the selected gateway’s own port directory from sibling detection. Regression tests verify full teardown for a single gateway and scoped cleanup when another live gateway remains.

Changes

Uninstall sibling detection

Layer / File(s)	Summary
Filter the selected gateway port src/lib/actions/uninstall/run-plan.ts	The sibling-directory scan validates directory ports and excludes GATEWAY_PORT before checking live OpenShell gateway names.
Validate gateway segregation src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts	Tests verify full teardown without siblings and scoped cleanup with a genuine nemoclaw-8091 sibling.

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

Possibly related PRs

• NVIDIA/NemoClaw#7901: Refines sibling-gateway detection in the same uninstall plan.

Suggested labels: area: sandbox

Suggested reviewers: cv, laitingsheng, ericksoa

🚥 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
Linked Issues check	✅ Passed	The changes address issue #7987 by excluding the selected gateway port and testing both single-gateway and genuine-sibling cases.
Out of Scope Changes check	✅ Passed	The changes are limited to sibling gateway detection and regression tests required by issue #7987.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main uninstall fix: preventing the selected gateway from being detected as its own sibling.

✨ 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/uninstall-self-sibling-7987

---

_{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 479ce77 in the fix/uninstall-self-s... branch remains at 96%, unchanged from commit 4cd4d64 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 479ce77 in the fix/uninstall-self-s... branch remains at 81%, unchanged from commit a931be4 in the main branch.

Show a code coverage summary of the most impacted files.

File	main a931be4	fix/uninstall-self-s... 479ce77	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/actions...all/run-plan.ts	83%	83%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/state/config-io.ts	93%	93%	0%
src/lib/state/g...way-registry.ts	94%	94%	0%
src/lib/credentials/store.ts	55%	56%	+1%
src/lib/platform.ts	84%	89%	+5%
src/lib/onboard...shboard-port.ts	90%	96%	+6%

---

_{Updated August 03, 2026 09:10 UTC}

[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

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

1 semantic terminology decision

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

• established — sibling gateway at src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts:1258: Retain the established term for the distinct live gateway that requires scoped cleanup.

E2E guidance

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

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.

[cv]

Security review for commit SHA 479ce77: PASS.

1. Secrets and credentials — PASS. No credential or token path changes.
2. Input validation and sanitization — PASS. The selected port is already digit-only and range checked; names must match the derived gateway name. Symlinks, non-directories, malformed names, and uncertain inventory remain fail-closed.
3. Authentication and authorization — PASS. No endpoint or permission change; teardown authority is revalidated before cleanup.
4. Dependencies — PASS. No dependency, image, package, or registry changes.
5. Error handling and logging — PASS. Inspection failures still preserve shared resources and expose no new data.
6. Cryptography and data protection — PASS. No cryptographic, transport, or sensitive-data behavior changes.
7. Configuration and isolation — PASS. No network, container, policy, port-exposure, or security-header changes.
8. Security testing — PASS. Regression tests cover the selected gateway with no sibling and a genuine live sibling. Existing tests cover malformed or unavailable inventory and a sibling appearing between inspections. GitHub CI is authoritative.
9. System security and TOCTOU — PASS. Only the validated selected port is excluded. Live and per-port sibling checks remain, and full cleanup repeats inspection before execution. The pre-existing residual cross-process timing window is unchanged.

No security finding blocks merge. Required GitHub checks, automated review, E2E evidence, and approval for this commit remain separate merge gates.

[cv]

Approved for commit 479ce77. The change restores the documented uninstall behavior, both commits are verified, the independent documentation writer review found no documentation update was needed, the security review passed, no review threads remain, and the required GitHub checks and E2E gate pass for this commit.