SIGN IN SIGN UP

fix(onboard): journal resumed sandbox recreation (#7690)

<!-- markdownlint-disable MD041 -->
## Summary

Resumed same-name sandbox recreation now records a secret-free lifecycle
journal before deletion. Resume continues only when the source identity,
confirmed missing-source state, or matching target generation plus
journal, registry, and live OpenShell ID fingerprints prove the next
action; ambiguous combinations stop before another mutation.

## Related Issue

Progresses #6492

## Changes

- Add checkpoint schema v3 and a journal consumed by resumed onboard. A
direct registry delete cannot recover across process exit;
`sandbox-recreate-transaction.test.ts` protects phase recovery and
ambiguity rejection.
- Bind the journal to the selected sandbox and gateway, source
fingerprints, target intent, target generation, and the created target
ID fingerprint. Non-default-gateway and restart-boundary tests protect
routing and monotonic recovery; an active journal whose gateway differs
from the selected authority now stops before observation or mutation.
- Preserve the source registry row until replacement registration and
stamp the target generation plus ID fingerprint into the replacement
row. Accepted targets also restore dashboard state; ordinary unknown
reuse states keep their prior behavior while journal observation fails
closed.
- Document the resumed-onboard scope. Rebuild and non-resumed re-onboard
adoption remain under #6492.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [x] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Docs updated for user-facing behavior changes
- [ ] Docs not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: Final-diff self-review
confirmed secret-free persistence, fail-closed ambiguity handling before
mutation, and exact source/target identity binding; the recovery matrix
and non-default-gateway paths are covered by tests.
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Documentation Writer Review

- [x] Documentation writer subagent reviewed the completed changes
- Result: `docs-updated`
- Evidence: `src/lib/onboard/lifecycle-contracts.md`; 30 transaction
tests passed; `npm run docs` completed with 0 errors and two existing
Fern upgrade warnings.
- Agent: Codex Desktop
<!-- docs-review-head-sha: 6dc948eb61a485faa428d4e69808671f03e1b0bf -->
<!-- docs-review-agents-blob-sha:
be20a0952410431f1039cb893d2b9168d2ceacd8 -->

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit:
- Station profile/scenario:
- Result:
- Supporting evidence:

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run check:diff` passed when hooks were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — command/result or justification:
Focused CLI lifecycle suite passed, 8 files and 141 tests; the current
advisor regression suite passed 3 files and 80 tests; CLI type-check
passed; `src/lib/onboard.ts` is net -9 lines against the PR base.
- [x] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result: `npm run test:changed`
passed 315 files and 3,331 tests.
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela <cvillela@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added durable sandbox recreation tracking for interrupted onboarding
and resumed same-name replacements.
* Automatically continues safe deletion and creation steps, or reuses a
verified replacement when possible.
* Preserves sandbox identity and lifecycle information across recreation
and registration.

* **Bug Fixes**
  * Prevents unsafe sandbox removal during an active recreation.
* Rejects mismatched or inconsistent recovery states instead of
proceeding.

* **Documentation**
* Documented recovery states and safeguards for resumed sandbox
replacement.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Carlos Villela <cvillela@nvidia.com>
C
Carlos Villela committed
45da24e1b157bdd4e32092ec75520293d39b0da1
Parent: e01587d
Committed by GitHub <noreply@github.com> on 7/28/2026, 7:38:32 AM