fix(cli): gc scans locally prebuilt sandbox image repo for orphans

[rluo8]

Summary

nemoclaw gc never removed orphaned locally-prebuilt sandbox images because it scanned only the gateway-built image repository (openshell/sandbox-from). This makes gc enumerate every sandbox image repo, so orphans under nemoclaw-sandbox-local (the docker-driver-gateway prebuild path — Linux or macOS/Apple Silicon) are detected, and the "run 'nemoclaw gc' to clean up" remediation that destroy --force prints actually works.

Related Issue

Fixes #6301

Changes

• src/lib/domain/sandbox/image-tag.ts: add SANDBOX_FROM_IMAGE_REPO, LOCAL_SANDBOX_IMAGE_REPO, and SANDBOX_IMAGE_REPOS as the single source of truth for sandbox image repositories.
• src/lib/actions/maintenance.ts: garbageCollectImages() now queries every repo in SANDBOX_IMAGE_REPOS and unions the results before orphan detection (was hardcoded to openshell/sandbox-from only).
• src/lib/onboard/sandbox-prebuild.ts: reuse the shared LOCAL_SANDBOX_IMAGE_REPO constant instead of a private literal.
• Tests: images.test.ts gains a mixed-repo case (local orphan detected, registered local image preserved); maintenance.test.ts asserts gc scans both repos.

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:

Verification

• [√] PR description includes the DCO sign-off declaration 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:
• 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)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Rui Luo ruluo@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved sandbox image cleanup to scan all sandbox image repositories, rather than a single hard-coded source, to remove unused images more reliably.
  • Fixed local sandbox image reference handling so repository names and tags are generated consistently across the app.
  • Enhanced orphan image detection to correctly flag unregistered local images even when repository context differs.
• Tests
  • Added coverage for orphan-detection and garbage-collection behavior across both sandbox image repositories.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 769d872b-e0ce-4d27-926f-9006c59f1f5a

📥 Commits

Reviewing files that changed from the base of the PR and between 3ea5e42 and d48b75a.

📒 Files selected for processing (1)

• src/lib/actions/maintenance.test.ts

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

• src/lib/actions/maintenance.test.ts

---

📝 Walkthrough

Walkthrough

This PR extends sandbox image garbage collection to scan both gateway-built and locally prebuilt image repositories, so orphaned local images are detected. It also centralizes sandbox image repository names into shared constants and updates related tag and prebuild code to use them.

Changes

Sandbox Image Repository Scanning

Layer / File(s)	Summary
Repository constants and usages src/lib/domain/sandbox/image-tag.ts, src/lib/onboard/sandbox-prebuild.ts	Adds exported repository constants and updates fallback tag resolution plus local prebuild image references to use them.
Multi-repository GC scan src/lib/actions/maintenance.ts, src/lib/actions/maintenance.test.ts, src/lib/domain/maintenance/images.test.ts	garbageCollectImages now scans all sandbox image repositories, and tests cover the new local orphan detection path and repository enumeration.

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

Possibly related PRs

• NVIDIA/NemoClaw#3653: Both PRs modify sandbox image-tag handling in src/lib/domain/sandbox/image-tag.ts, including the fallback tag format used downstream.

Suggested labels: bug-fix

Suggested reviewers: cjagwani, prekshivyas, ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main fix: garbage collection now scans locally prebuilt sandbox image repositories for orphaned images.
Linked Issues check	✅ Passed	The changes address #6301 by having gc scan all sandbox image repos, so orphaned nemoclaw-sandbox-local images are detected and cleaned.
Out of Scope Changes check	✅ Passed	The added constants, tests, and prebuild refactor all support the gc orphan-fix and do not introduce unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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: 1

🧹 Nitpick comments (1)

src/lib/domain/sandbox/image-tag.ts (1)

21-21: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Regex still hardcodes the repo string the new constant was meant to centralize.

BUILT_SANDBOX_IMAGE_RE duplicates "openshell/sandbox-from" as a literal even though SANDBOX_FROM_IMAGE_REPO was just introduced for this exact purpose. Building the regex from the constant would avoid future drift between the two.

♻️ Suggested fix

-const BUILT_SANDBOX_IMAGE_RE = /Built image (openshell\/sandbox-from:\d+)/;
+const BUILT_SANDBOX_IMAGE_RE = new RegExp(
+  `Built image (${SANDBOX_FROM_IMAGE_REPO.replace(/\//g, "\\/")}:\\d+)`,
+);

🤖 Prompt for 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.

In `@src/lib/domain/sandbox/image-tag.ts` at line 21, The BUILT_SANDBOX_IMAGE_RE
regex in image-tag.ts still hardcodes the sandbox repo string instead of using
SANDBOX_FROM_IMAGE_REPO. Update the regex construction to reference the new
constant so the Built image pattern stays centralized and cannot drift from the
repo value.

🤖 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/maintenance.test.ts`:
- Line 47: The garbage-collection test in maintenance.test.ts is only asserting
the dockerListImagesFormat mock was called, so it never proves orphan detection
works for the local repo. Update the test around
garbageCollectImages/findOrphanedSandboxImages to have dockerListImagesFormat
return distinct rows for each repo, including an orphan from
nemoclaw-sandbox-local, and assert on an observable result such as the logged
orphan or the removal count rather than the mock call itself. This will verify
the real GC path instead of just the query setup.

---

Nitpick comments:
In `@src/lib/domain/sandbox/image-tag.ts`:
- Line 21: The BUILT_SANDBOX_IMAGE_RE regex in image-tag.ts still hardcodes the
sandbox repo string instead of using SANDBOX_FROM_IMAGE_REPO. Update the regex
construction to reference the new constant so the Built image pattern stays
centralized and cannot drift from the repo value.

🪄 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: aa9eb893-4b73-4c2a-ba38-934e5ee06ca1

📥 Commits

Reviewing files that changed from the base of the PR and between f0d2549 and 3ea5e42.

📒 Files selected for processing (5)

• src/lib/actions/maintenance.test.ts
• src/lib/actions/maintenance.ts
• src/lib/domain/maintenance/images.test.ts
• src/lib/domain/sandbox/image-tag.ts
• src/lib/onboard/sandbox-prebuild.ts

[cv]

Maintainer review: GC now enumerates and unions both local sandbox-image repositories while preserving registered images, with focused output and preservation tests. CI, DCO, commit verification, and review-thread checks are clean.

[wscurran]

✨
Related open issues:

• #6301 [macOS][Sandbox] nemoclaw gc reports "Nothing to clean up" while the sandbox image left behind by destroy --force (gateway down) is still on disk

---

Related open issues:

• #6301 [macOS][Sandbox] nemoclaw gc reports "Nothing to clean up" while the sandbox image left behind by destroy --force (gateway down) is still on disk