fix(cli): clear sandbox registry when gateway is destroyed during onboard (fixes: #532)

[craigamcw]

Implemented feature with help from Claude Code

When onboard detects a stale gateway or starts a fresh one, it runs openshell gateway destroy which deletes all sandboxes in OpenShell. However the local NemoClaw registry (~/.nemoclaw/sandboxes.json) was not cleared, leaving stale entries that caused nemoclaw list to show sandboxes that no longer exist and nemoclaw <name> connect to fail with "sandbox not found".

Summary

Clear the local NemoClaw sandbox registry when a stale gateway is destroyed during onboard preflight. Previously, openshell gateway destroy deleted sandboxes in OpenShell but left stale entries in ~/.nemoclaw/sandboxes.json, causing nemoclaw list to show sandboxes that no longer exist.

Related Issue

#532

Changes

• Add clearAll() to registry module to reset all sandbox entries.
• Call registry.clearAll() after gateway destroy in both preflight cleanup and startGateway (covers all destroy paths).
• Add 3 tests for clearAll: multi-sandbox clear, disk persistence, and idempotent call on empty registry.

Type of Change

• Code change for a new feature, bug fix, or refactor.
• Code change with doc updates.
• Doc only. Prose changes without code sample modifications.
• Doc only. Includes code sample changes.

Testing

• make check passes.
• npm test passes.
• make docs builds without warnings. (for doc-only changes)

Checklist

General

• I have read and followed the contributing guide.
• I have read and followed the style guide. (for doc-only changes)

Code Changes

• make format applied (TypeScript and Python).
• Tests added or updated for new or changed behavior.
• No secrets, API keys, or credentials committed.
• Doc pages updated for any user-facing behavior changes (new commands, changed defaults, new features, bug fixes that contradict existing docs).

Doc Changes

• Follows the style guide. Try running the update-docs agent skill to draft changes while complying with the style guide. For example, prompt your agent with "/update-docs catch up the docs for the new changes I made in this PR."
• New pages include SPDX license header and frontmatter, if creating a new page.
• Cross-references and links verified.

Summary by CodeRabbit

• Bug Fixes

  • Improved cleanup of sandbox registry state when gateways are destroyed or during preflight cleanup, ensuring stale sandbox entries no longer persist in local registry after gateway removal.

• Tests

  • Added comprehensive test coverage for registry cleanup functionality, validating proper state reset and persistent storage updates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8811f89b-efba-4633-b19a-1f6c5b95ab4f

📥 Commits

Reviewing files that changed from the base of the PR and between 04012f7 and 4336181.

📒 Files selected for processing (3)

• bin/lib/onboard.js
• bin/lib/registry.js
• test/registry.test.js

---

📝 Walkthrough

Walkthrough

Adds a clearAll() function to the registry module that resets all sandboxes and default selections, and integrates it into the onboard script's cleanup paths when gateways are stopped or destroyed, ensuring registry state remains synchronized with gateway lifecycle.

Changes

Cohort / File(s)	Summary
Core Registry Functionality bin/lib/registry.js	Introduces clearAll() function that persists an empty registry state (no sandboxes, defaultSandbox: null) and exports it as a public module method.
Onboard Integration bin/lib/onboard.js	Calls registry.clearAll() in two locations: after destroying the nemoclaw gateway in preflight cleanup and immediately after destroying an existing gateway in startGateway, with updated inline comments.
Test Coverage test/registry.test.js	Adds three test cases validating that clearAll() removes all sandboxes, nullifies the default selection, persists changes to disk, and safely handles already-empty registries.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 The registry once held so much care,
But when gateways fall, we clear the air—
All sandboxes gone, defaults reset,
A rabbit's cleanup, our finest bet! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: clearing the sandbox registry when a gateway is destroyed during onboard, which directly addresses the bug fix and relates to all modified files.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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