fix(rebuild): guard destructive delete target

[cv]

Summary

Closes two destructive-delete safety gaps discovered after #7196 merged. Rebuild now rereads the sandbox registry immediately before deletion, verifies the canonical sandbox and recorded gateway binding still match the prepared target, and treats an accepted but unconfirmed deletion as ambiguous so shields are not relocked prematurely.

Related Issue

Follow-up to #7196 and #7062.

Changes

• Reread and resolve the canonical sandbox target and recorded gateway at the delete edge.
• Abort deletion, restore MCP state, and relock shields when the sandbox identity or gateway binding drifts after MCP preparation.
• Mark an accepted but unconfirmed delete as ambiguous so the outer finally path does not claim a locked posture.
• Recognize OpenShell's exact structured sandbox-absence response while leaving gateway, provider, transport, and mixed diagnostics ambiguous.
• Add regressions for sandbox-name drift, gateway-binding drift, MCP restoration, ambiguous deletion, and structured absence classification.

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: This correction restores the delete-edge identity and ambiguous-deletion behavior already documented in the rebuild, MCP, and trusted-boundary guides.
• 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: The correction narrows the destructive action by revalidating the exact target and gateway at the delete edge, fails closed on drift, restores MCP before relocking, and only classifies the exact structured sandbox-not-found response as absence.
• 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: Existing canonical docs already require delete-edge target/gateway revalidation and ambiguous-deletion handling; the structured response classifier is an internal compatibility correction that does not change commands, configuration, supported surfaces, or operator guidance.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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 — normal hooks passed for the maintainer follow-up commit; the original exact head passed npm run check:diff.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — 46 focused CLI tests passed for the current exact head; CLI typecheck, build, source-shape, test-title, project-membership, and formatting checks passed. The original change also passed its 88 changed tests and 52 adjacent integration tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; the correction is isolated to the rebuild destroy phase and its focused tests.
• 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: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Prevented sandbox deletion when gateway/registry details change during rebuild preparation by re-checking the delete target right before execution.
  • Improved gateway pinning so the delete targets the intended gateway even if ambient gateway selection shifts.
  • Treated deletion as ambiguous when transport errors block confirmation, triggering the ambiguous-delete flow rather than “deleted” handling.
  • Expanded handling of structured “sandbox not found” responses for destructive reconciliation.
• Tests
  • Added/extended coverage for gateway mismatch scenarios, ambiguous deletion behavior, and structured absence variants.

[coderabbitai]

📝 Walkthrough

Walkthrough

Rebuild destruction now resolves and revalidates gateway-bound sandbox targets before deletion. Registry changes abort deletion and restore MCP state. Transport failures remain ambiguous, preventing deletion completion callbacks and shield relocking. Structured OpenShell absence responses are recognized during deletion convergence checks.

Changes

Sandbox delete safety

Layer / File(s)	Summary
Gateway-bound delete target validation src/lib/actions/sandbox/rebuild-destroy-phase.ts, src/lib/actions/sandbox/rebuild-destroy-phase.test.ts	Deletion targets now include gateway identity and sandbox name, are rechecked against the registry after MCP preparation, and abort with MCP recovery when changed.
Ambiguous deletion propagation src/lib/actions/sandbox/rebuild-destroy-phase.ts, src/lib/actions/sandbox/rebuild-destroy-phase.test.ts, src/lib/actions/sandbox/rebuild-shields-finally.test.ts	Transport errors invoke the ambiguous-state callback, while the rebuild flow rejects without relocking shields and keeps the rebuild window unlocked.
Structured absence detection src/lib/actions/sandbox/gateway-state.ts, src/lib/actions/sandbox/rebuild-destroy-phase.test.ts	Structured OpenShell sandbox-not-found responses are classified as absence, with gateway and provider convergence cases covered by tests.

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

Possibly related PRs

• NVIDIA/NemoClaw#7194: Modifies rebuild/destroy deletion gating and registry-state handling in the same phase.

Suggested labels: area: sandbox, bug-fix

Suggested reviewers: laitingsheng, apurvvkumaria, yimoj

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main rebuild safety change: guarding the destructive delete target.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/7196-destroy-gateway-safety

---

_{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 a3d5882 in the codex/7196-destroy-g... branch remains at 96%, unchanged from commit 4fdbb79 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit a3d5882 in the codex/7196-destroy-g... branch remains at 81%, unchanged from commit 4fdbb79 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 4fdbb79	codex/7196-destroy-g... a3d5882	+/-
src/lib/platform.ts	89%	84%	-5%
src/lib/onboard/tracing.ts	85%	80%	-5%
src/lib/actions...ateway-state.ts	77%	76%	-1%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/onboard...ward-cleanup.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/state/g...way-registry.ts	94%	94%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/actions...estroy-phase.ts	84%	86%	+2%

---

_{Updated July 26, 2026 03:30 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 · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

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: onboard-repair, onboard-resume, state-backup-restore, upgrade-stale-sandbox

2 optional E2E recommendations

• sandbox-rebuild
• mcp-bridge

Workflow run details

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

[apurvvkumaria]

Maintainer follow-up at a3d588227a679860aa207ed6959060123aa85b16:

The failed upgrade-stale-sandbox E2E accepted the delete (exit=0), but all 17 owner-pinned convergence probes returned status=1,state=unknown. Cleanup later exposed the definitive OpenShell 0.0.85 absence response: code: "Some requested entity was not found", message: "sandbox not found". The strict absence classifier did not recognize that current structured form, so rebuild correctly failed closed before registry removal/recreation.

The new signed, GitHub-verified commit recognizes only that exact anchored structured sandbox-absence pair. Gateway/provider absence, mixed diagnostics, transport failures, signals, timeouts, wrong sandbox names, and generic status: NotFound remain ambiguous and fail closed.

Local validation at the new head: 46 focused CLI tests passed, including positive exact-response coverage and negative gateway/provider cases; CLI build/typecheck, source-shape, test-title, project-membership, formatting, normal commit hooks, and normal push hooks also passed. Documentation review found no public-doc change needed. Exact-head CI and the credentialed E2E rerun remain pending; this is not yet merge-ready.

[apurvvkumaria]

Approved at exact head a3d588227a679860aa207ed6959060123aa85b16: the structured OpenShell 0.0.85 absence case is recognized without weakening fail-closed handling for unknown delete failures; focused tests, security review, DCO/commit verification, all required CI, and the exact-head E2E gate pass. No unresolved review threads remain.