fix(onboard): repair journaled rebuild image retirement

[apurvvkumaria]

Summary

Journaled same-name rebuilds now register the replacement's live lifecycle identity after creation and retire an obsolete owned Docker image only after exact replacement and ownership proof. Skipped retirements emit bounded reason codes, and the Hermes rebuild fixture records exact provider, workload, and replacement lifecycle evidence.

Related Issue

Related: #8590

Changes

• Preserve portable lifecycle generation before create while reading the journaled live identity only after replacement creation.
• Remove eager pre-replacement image deletion and require an explicit runtime provider plus an exact matching unshared legacy-Dockerfile receipt before retirement.
• Report every bounded retirement skip reason and add focused lifecycle, cleanup-authority, ordering, logging, and Hermes E2E-support regressions.

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 Recover and Rebuild Sandboxes page already documents post-registration owned-image retirement, retention, and fail-closed mismatch handling; the completed documentation review found no contract change.
• 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: Independent security/correctness review approved full-index diff SHA-256 1c296f8d6354658bb2317087dbdaf49516d8ac6db44d102c172ee7f9ab24cca5; final commit-object/tree rebind passed for 9d85c318882ff4c88a5b12f3205732b725593b02.
• 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 docs/manage-sandboxes/recover-rebuild-sandboxes.mdx; its existing identity, generation, owned-image retirement, retention, and fail-closed contract remains accurate.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• 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
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Focused CLI tests passed 107/107; test/onboard-sandbox-recreation.test.ts passed 11/11; E2E support tests passed 5/5. npm run typecheck:cli, npm run checks:repository, title/project/size/source-shape checks, changed-path Biome checks, and git diff --check also passed.
• 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: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved sandbox recreation safety by validating workload ownership and identity before retiring replaced images.
  • Prevented cleanup when workload authority cannot be confirmed, reducing the risk of removing unrelated resources.
  • Ensured recreated sandboxes retain accurate lifecycle generation and replacement identity information.
  • Added clear, reason-specific diagnostics when image retirement is skipped.

• Tests

  • Expanded coverage for sandbox recreation, lifecycle receipts, image cleanup safeguards, and replacement identity tracking.

[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: 87de2448-0075-43a7-a9f2-d4d46cba0697

📥 Commits

Reviewing files that changed from the base of the PR and between 9d85c31 and 9b12759.

📒 Files selected for processing (2)

• src/lib/onboard/sandbox-gpu-create-flow.test.ts
• test/e2e/support/rebuild-hermes-image-state.test.ts

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

• src/lib/onboard/sandbox-gpu-create-flow.test.ts
• test/e2e/support/rebuild-hermes-image-state.test.ts

---

📝 Walkthrough

Walkthrough

Sandbox recreation now passes lifecycle generation directly, delays source-image cleanup until replacement identity is registered, validates cleanup authority, reports skip reasons, and records validated replacement lifecycle receipts in rebuild artifacts.

Changes

Sandbox recreation lifecycle and cleanup

Layer / File(s)	Summary
Direct lifecycle generation flow src/lib/onboard.ts, src/lib/onboard/sandbox-gpu-create-flow.ts, src/lib/onboard/sandbox-gpu-create-flow.test.ts	Sandbox GPU creation accepts lifecycleGeneration directly. Returned lifecycle registration data contains the generation and no longer contains the live identity fingerprint. Final registration uses runtime-generated lifecycle fields.
Source workload retirement validation src/lib/onboard/sandbox-recreate-transaction.ts, src/lib/onboard/machine/handlers/sandbox.ts, src/lib/onboard/runtime-provider/replaced-workload.test.ts, src/lib/onboard/machine/handlers/sandbox-recreate-journal.test.ts, test/onboard-sandbox-recreation.test.ts	Cleanup now requires an owned image and validated Docker workload authority. Skipped retirement emits a reason-specific diagnostic. Tests cover authority failures, bounded skip reasons, deferred retirement, lifecycle generation, and replacement identity fingerprints.
Replacement receipt and rebuild state test/e2e/live/rebuild-hermes-image-state.ts, test/e2e/live/rebuild-hermes.test.ts, test/e2e/support/rebuild-hermes-image-state.test.ts	Rebuild state includes Docker workload metadata. Replacement lifecycle receipts require a UUID generation and a 64-character hexadecimal identity fingerprint, and are recorded in a phase-6 artifact.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboard
  participant SandboxGpuCreateFlow
  participant LifecycleInstaller
  participant Registry
  Onboard->>SandboxGpuCreateFlow: pass recreation lifecycleGeneration
  SandboxGpuCreateFlow->>LifecycleInstaller: install lifecycle
  LifecycleInstaller-->>SandboxGpuCreateFlow: return registryGeneration
  SandboxGpuCreateFlow-->>Onboard: return lifecycle registration
  Onboard->>Registry: register replacement sandbox
  Registry-->>Onboard: persist replacement identity

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8073: Both changes modify journaled sandbox recreation and source cleanup authority validation.
• NVIDIA/NemoClaw#8583: Both changes modify sandbox recreation coordination in src/lib/onboard.ts.

Suggested labels: bug-fix, area: onboarding

🚥 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 and concisely describes the main change: repairing journaled rebuild image retirement in onboarding.
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.

✨ 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/fix-journaled-rebuild-retirement

---

_{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 9b12759 in the codex/fix-journaled-... branch remains at 96%, unchanged from commit 8096cdd in the main branch.

---

_{Updated August 09, 2026 21:44 UTC}

[coderabbitai]

Actionable comments posted: 2

🤖 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/onboard/sandbox-gpu-create-flow.test.ts`:
- Around line 683-691: The test mock for installPortableDemoLifecycle in
runSandboxGpuCreateFlow must return the received registryGeneration option
instead of input.lifecycleGeneration. Keep the existing
lifecycleRegistrationFields assertion so the test verifies registryGeneration is
forwarded through the portable lifecycle installer.

In `@test/e2e/support/rebuild-hermes-image-state.test.ts`:
- Around line 43-59: Extend the test for
requireRebuildHermesReplacementLifecycleReceipt with a receipt whose
lifecycleGeneration is a syntactically valid non-version-4 UUID, while retaining
the valid receipt and missing-generation cases. Assert that this receipt is
rejected for lifecycle generation validation.

🪄 Autofix

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: 9005fd02-2ac2-4a1c-806f-15eab0bbb196

📥 Commits

Reviewing files that changed from the base of the PR and between 8096cdd and 9d85c31.

📒 Files selected for processing (11)

• src/lib/onboard.ts
• src/lib/onboard/machine/handlers/sandbox-recreate-journal.test.ts
• src/lib/onboard/machine/handlers/sandbox.ts
• src/lib/onboard/runtime-provider/replaced-workload.test.ts
• src/lib/onboard/sandbox-gpu-create-flow.test.ts
• src/lib/onboard/sandbox-gpu-create-flow.ts
• src/lib/onboard/sandbox-recreate-transaction.ts
• test/e2e/live/rebuild-hermes-image-state.ts
• test/e2e/live/rebuild-hermes.test.ts
• test/e2e/support/rebuild-hermes-image-state.test.ts
• test/onboard-sandbox-recreation.test.ts

[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 after a partial review · low confidence · 1 blocker · 1 warning · 1 suggestion

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

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

• established — replacement-unproven at src/lib/onboard/machine/handlers/sandbox.ts:128: Keep replacement-unproven as the skip reason for an unproven replacement.
• established — owned image at src/lib/onboard/sandbox-recreate-transaction.ts:86: Keep owned image for an image eligible for destructive retirement after ownership proof.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: cloud-inference, cloud-onboard, managed-image-multiarch-startup, managed-image-protected-runtime, security-posture, onboard-repair, onboard-resume, openshell-gateway-upgrade, rebuild-hermes, rebuild-hermes-stale-base, ubuntu-repo-cloud-langchain-deepagents-code

Workflow run details

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