refactor(rebuild): unify post-restore verification and completion gating

[jyaunches]

Summary

• remove the disconnected rebuild-finalization.ts implementation and its duplicate tests
• make the live post-restore phase return one typed required/advisory verification result
• have the transaction coordinator consume that result, retain replacement_created with a precise retryable failure code when required verification is incomplete, and publish completed only when every required check passes
• keep advisory doctor/shields findings visible without conflating them with completion blockers
• preserve operator guidance when failure-metadata publication itself fails

Stack

This PR is stacked on draft PR #6470 and should be reviewed after it. It implements #6485 and prepares the completion contract consumed by #6436.

Completion contract

Required verification covers state restore, mutable config permissions/hash, MCP restoration, policy restoration/exact reconciliation, registry reconciliation, shields relock, and configured messaging forwarding. OpenClaw doctor and the existing recovery-shields warning remain explicit advisory findings.

Tests

• npm run build:cli
• npm run typecheck:cli
• npx vitest run --project cli src/lib/actions/sandbox/rebuild-post-restore-verification.test.ts (12 tests)
• npx vitest run --project cli src/lib/actions/sandbox/rebuild-transaction-finalization-boundary.test.ts (5 tests)
• npx vitest run --project cli src/lib/actions/sandbox/rebuild-transaction-boundary.test.ts (16 tests)
• npx vitest run --project cli src/lib/actions/sandbox/rebuild-flow.test.ts (75 tests)
• npm run lint
• pre-commit repository checks, secret scan, source-shape budget, and test-size budget

Line budget relative to #6470

• production: +187 / -276 (net -89)
• tests: +262 / -198 (net +64)
• total: +449 / -474 (net -25)

Closes #6485

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9654c103-6c4c-4e50-8b17-acf6572a3f6a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/6485-rebuild-finalization-gating

---

_{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 remains at 96%, unchanged from the refactor/6435-rebuil... branch.

TypeScript / code-coverage/cli

The overall coverage in the refactor/6485-rebuil... branch remains at 76%, unchanged from the refactor/6435-rebuil... branch.

Show a code coverage summary of the most impacted files.

File	refactor/6435-rebuil... 10091a3	refactor/6485-rebuil... 61e8c5d	+/-
src/lib/sandbox...vileged-exec.ts	89%	45%	-44%
src/lib/actions...ess-recovery.ts	79%	64%	-15%
src/lib/inference/nim.ts	71%	64%	-7%
src/lib/state/sandbox.ts	76%	72%	-4%
src/lib/agent/onboard.ts	71%	80%	+9%
src/lib/actions...-monkeypatch.ts	72%	81%	+9%
src/lib/actions...dbox/destroy.ts	71%	88%	+17%
src/lib/onboard...eway-cleanup.ts	55%	79%	+24%
src/lib/actions...-coordinator.ts	0%	86%	+86%
src/lib/state/r...-transaction.ts	0%	97%	+97%

---

_{Updated July 08, 2026 23:23 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Consider PRA-1: Wrapper comment documents deliberate adapter pattern with removal condition.
Open items: 0 required · 0 warnings · 2 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Action checklist

• PRA-1 In-scope improvement: Wrapper comment documents deliberate adapter pattern with removal condition in src/lib/actions/sandbox/rebuild-post-restore-phase.ts:240
• PRA-2 In-scope improvement: Transaction finalize catch block swallows recordFailure errors but blocks completion in src/lib/actions/sandbox/rebuild-transaction-coordinator.ts:251

Findings index

ID	Severity	Category	Location	Required action
PRA-1	Improvement	docs	src/lib/actions/sandbox/rebuild-post-restore-phase.ts:240	Keep the comment; it correctly documents the source-of-truth boundary and removal condition.
PRA-2	Improvement	correctness	src/lib/actions/sandbox/rebuild-transaction-coordinator.ts:251	Accept as deliberate boundary; document removal condition in code comment.

Review findings by urgency: 0 required fixes, 0 items to resolve/justify, 2 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

• None.

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

PRA-1 Improvement — Wrapper comment documents deliberate adapter pattern with removal condition

• Location: src/lib/actions/sandbox/rebuild-post-restore-phase.ts:240
• Category: docs
• Problem: Line 240 comment 'Wrapper comment — intentional adapter pattern with documented removal condition' signals a tolerance path around registry.updateSandbox. The try/catch catches errors, redacts them via redactFull, logs, and sets registryReconciliationVerified = false. This is a deliberate fallback, not a bug.
• Impact: Maintainability — future readers understand this is a boundary adapter with defined removal criteria rather than technical debt.
• Suggested action: Keep the comment; it correctly documents the source-of-truth boundary and removal condition.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Read rebuild-post-restore-phase.ts lines 229-242 and confirm try/catch wraps registry.updateSandbox with redactFull on error.
• Missing regression test: Already covered by rebuild-transaction-finalization-boundary.test.ts lines testing throwing and false return paths with redacted errors.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: rebuild-post-restore-phase.ts:229-242; rebuild-transaction-finalization-boundary.test.ts registry error tests

PRA-2 Improvement — Transaction finalize catch block swallows recordFailure errors but blocks completion

• Location: src/lib/actions/sandbox/rebuild-transaction-coordinator.ts:251
• Category: correctness
• Problem: Lines 251-255 catch errors from store.recordFailure, log them, but keep completion blocked (return false). Test confirms guidance emitted even when metadata write fails.
• Impact: Durability — if transaction journal is unavailable, failure metadata may not persist, but completion is still correctly blocked.
• Suggested action: Accept as deliberate boundary; document removal condition in code comment.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Read rebuild-transaction-coordinator.ts lines 251-255 and rebuild-transaction-finalization-boundary.test.ts first test case.
• Missing regression test: Covered by rebuild-transaction-finalization-boundary.test.ts first test (recordFailure throws).
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: rebuild-transaction-coordinator.ts:251-255; rebuild-transaction-finalization-boundary.test.ts:1

Simplification opportunities: 2 possible cuts, net -23 lines possible

These are safe simplification checks only. Do not remove validation, security controls, data-loss prevention, or required tests.

• PRA-1 shrink (src/lib/actions/sandbox/rebuild-post-restore-phase.ts:240): try/catch wrapper around registry.updateSandbox
  • Replacement: Typed failure return from registry boundary carrying redacted diagnostics
  • Net: -15 lines
  • Safety boundary: registry.updateSandbox must return structured failure with redacted error before wrapper can be removed
• PRA-2 shrink (src/lib/actions/sandbox/rebuild-transaction-coordinator.ts:251): catch block swallowing recordFailure errors
  • Replacement: Stronger transaction store durability guarantees
  • Net: -8 lines
  • Safety boundary: Transaction store must provide atomic failure persistence before catch can be removed

Since last review details

Current findings, using the urgency labels above:

PRA-1 Improvement — Wrapper comment documents deliberate adapter pattern with removal condition

• Location: src/lib/actions/sandbox/rebuild-post-restore-phase.ts:240
• Category: docs
• Problem: Line 240 comment 'Wrapper comment — intentional adapter pattern with documented removal condition' signals a tolerance path around registry.updateSandbox. The try/catch catches errors, redacts them via redactFull, logs, and sets registryReconciliationVerified = false. This is a deliberate fallback, not a bug.
• Impact: Maintainability — future readers understand this is a boundary adapter with defined removal criteria rather than technical debt.
• Suggested action: Keep the comment; it correctly documents the source-of-truth boundary and removal condition.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Read rebuild-post-restore-phase.ts lines 229-242 and confirm try/catch wraps registry.updateSandbox with redactFull on error.
• Missing regression test: Already covered by rebuild-transaction-finalization-boundary.test.ts lines testing throwing and false return paths with redacted errors.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: rebuild-post-restore-phase.ts:229-242; rebuild-transaction-finalization-boundary.test.ts registry error tests

PRA-2 Improvement — Transaction finalize catch block swallows recordFailure errors but blocks completion

• Location: src/lib/actions/sandbox/rebuild-transaction-coordinator.ts:251
• Category: correctness
• Problem: Lines 251-255 catch errors from store.recordFailure, log them, but keep completion blocked (return false). Test confirms guidance emitted even when metadata write fails.
• Impact: Durability — if transaction journal is unavailable, failure metadata may not persist, but completion is still correctly blocked.
• Suggested action: Accept as deliberate boundary; document removal condition in code comment.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Read rebuild-transaction-coordinator.ts lines 251-255 and rebuild-transaction-finalization-boundary.test.ts first test case.
• Missing regression test: Covered by rebuild-transaction-finalization-boundary.test.ts first test (recordFailure throws).
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: rebuild-transaction-coordinator.ts:251-255; rebuild-transaction-finalization-boundary.test.ts:1

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[github-actions]

E2E Advisor Recommendation

Required E2E: sandbox-rebuild, rebuild-openclaw, rebuild-hermes
Optional E2E: mcp-bridge, network-policy, state-backup-restore

Dispatch hint: sandbox-rebuild,rebuild-openclaw,rebuild-hermes

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/refactor/6435-rebuild-destructive-journal
Head: HEAD
Confidence: high

Required E2E

• sandbox-rebuild (high): This is the closest live coverage for the changed nemoclaw <sandbox> rebuild --yes lifecycle: real onboard, registry mutation, rebuild, state preservation, registry refresh, and backup credential hygiene.
• rebuild-openclaw (high): The refactor changes OpenClaw rebuild post-restore finalization, registry reconciliation, mutable config repair/hash verification, policy reconciliation, shields relock, and transaction completion; this live job exercises old OpenClaw rebuild through the real CLI and OpenShell sandbox.
• rebuild-hermes (high): The same rebuild transaction and post-restore verification path is used for Hermes, including messaging state, registry reconciliation, backup hygiene, and host forwarding-related rebuild boundaries.

Optional E2E

• mcp-bridge (high): Useful adjacent confidence because MCP bridge restore is now a required post-restore blocker, though this existing job focuses on MCP add/remove/runtime isolation rather than rebuild transaction finalization.
• network-policy (high): Optional confidence for the policy/security boundary because the PR changes rebuild policy reconciliation and DCode observability preset failure handling, but the existing network-policy job is not specifically a rebuild reconciliation test.
• state-backup-restore (medium): Optional adjacent coverage for real snapshot/backup/restore mechanics affected by rebuild recovery outcomes, although the changed code is specifically rebuild post-restore finalization rather than the standalone snapshot restore command.

New E2E recommendations

• rebuild-transaction-finalization (high): No existing live E2E appears to intentionally force registry reconciliation failure, shields relock failure, messaging forwarding failure, or MCP restore failure after replacement creation and assert the durable transaction remains active at replacement_created with a retryable failure code.
  • Suggested test: Add a live or controlled integration E2E for rebuild post-restore failure finalization that injects one required verification failure after replacement creation and validates retry guidance plus retained durable transaction state.
• dcode-rebuild-policy-reconciliation (medium): The PR changes DCode observability policy reconciliation failure semantics, but the existing recommended live rebuild jobs do not directly exercise DCode managed observability preset removal during rebuild.
  • Suggested test: Add a DCode rebuild E2E that toggles managed observability/network policy during rebuild and verifies exact live policy reconciliation, registry policyPresetsFinalized state, and fail-closed behavior when reconciliation cannot be verified.

Dispatch hint

• Workflow: .github/workflows/e2e.yaml
• jobs input: sandbox-rebuild,rebuild-openclaw,rebuild-hermes

[github-actions]

E2E Target Recommendation

Required E2E targets: sandbox-rebuild, ubuntu-repo-cloud-langchain-deepagents-code
Optional E2E targets: rebuild-openclaw

Dispatch required E2E targets:

• gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=sandbox-rebuild
• gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-langchain-deepagents-code

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/refactor/6435-rebuild-destructive-journal
Head: HEAD
Confidence: high

Required E2E targets

• sandbox-rebuild: The PR changes the rebuild pipeline, post-restore verification, and transaction finalization. The sandbox-rebuild free-standing E2E job runs a real Docker/OpenShell OpenClaw rebuild and verifies state preservation, registry refresh, and backup hygiene across the changed completion boundary.
  • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=sandbox-rebuild
• ubuntu-repo-cloud-langchain-deepagents-code: The changed rebuild post-restore verification and transaction retention paths also affect DCode rebuild recovery and policy reconciliation. This live-supported typed target exercises the DCode invalid-credential rebuild lifecycle through registry-targets.test.ts.
  • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field targets=ubuntu-repo-cloud-langchain-deepagents-code

Optional E2E targets

• rebuild-openclaw: Broader adjacent OpenClaw rebuild coverage: old-base rebuild, policy presets, gateway token rotation, registry/session state, and destructive delete/recreate behavior. Useful if extra confidence is needed for the finalization changes.
  • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=rebuild-openclaw

Relevant changed files

• src/lib/actions/sandbox/rebuild-finalization.ts
• src/lib/actions/sandbox/rebuild-mcp-phase.ts
• src/lib/actions/sandbox/rebuild-pipeline.ts
• src/lib/actions/sandbox/rebuild-post-restore-phase.ts
• src/lib/actions/sandbox/rebuild-transaction-coordinator.ts

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 0 suggestions · 2 test follow-ups
Since last review: 2 prior items resolved · 0 still apply · 0 new items found

Action checklist

• PRA-T1 Add or justify test follow-up: Runtime validation
• PRA-T2 Add or justify test follow-up: Acceptance clause

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

• PRA-T1 Runtime validation — Exercise a full rebuild flow where every required post-restore observation is verified and assert the durable transaction is completed only after registry reconciliation, shields relock, MCP restore, and messaging forwarding have all succeeded.. Static and harness coverage is strong for the refactor and negative paths, but the changed surfaces are destructive sandbox lifecycle, registry, MCP, messaging, shields, and transaction completion boundaries where behavioral runtime validation gives additional confidence.
• PRA-T2 Acceptance clause — Targeted `cli` tests, `npm run typecheck:cli`, repository checks, and coverage ratchet pass. — add test evidence or identify existing coverage. The review did not execute commands or evaluate CI; static inventory confirms targeted changed test files exist for post-restore verification, transaction finalization boundary, and rebuild flow coverage.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[jyaunches]

Addressed the initial PR Review Advisor findings in d9586cecb:

• moved the finalization metadata-write case out of the 501-line transaction test hotspot; the original file is back to 475 lines
• documented the registry source-of-truth boundary and log thrown registry failures with full secret redaction while retaining REGISTRY_RECONCILIATION_UNVERIFIED
• added focused transaction-boundary coverage for registry exceptions, shields relock failure, and configured messaging-forward failure
• upgraded the existing exact-policy reconciliation test to assert retained replacement_created state and its fixed failure code
• corrected the secondary rebuild harness's success default, which fixed the three failed CLI shards
• retained the existing completion-publication failure coverage in rebuild-transaction-boundary.test.ts (store.complete rejection leaves active replacement_created and surfaces the failure)

The focused verifier, finalization-boundary, transaction-boundary, rebuild-flow, DCode, and local-provider suites pass locally. Required live E2E runs have been dispatched for sandbox-rebuild, rebuild-openclaw, rebuild-hermes, and ubuntu-repo-cloud-langchain-deepagents-code.

[github-actions]

E2E Target Results — ⚠️ Run cancelled — no signal

Run: 28981966437
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: rebuild-hermes
Summary: 0 passed, 0 failed, 1 cancelled, 0 skipped

Job	Result
rebuild-hermes	⚠️ cancelled

[github-actions]

E2E Target Results — ⚠️ Run cancelled — no signal

Run: 28981966641
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: sandbox-rebuild
Summary: 0 passed, 0 failed, 1 cancelled, 0 skipped

Job	Result
sandbox-rebuild	⚠️ cancelled

[github-actions]

E2E Target Results — ⚠️ Run cancelled — no signal

Run: 28981966487
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: rebuild-openclaw
Summary: 0 passed, 0 failed, 1 cancelled, 0 skipped

Job	Result
rebuild-openclaw	⚠️ cancelled

[github-actions]

E2E Target Results — ⚠️ Run cancelled — no signal

Run: 28981966473
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: ubuntu-repo-cloud-langchain-deepagents-code
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 0 passed, 0 failed, 1 cancelled, 0 skipped

Job	Result
live	⚠️ cancelled

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28982052746
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: sandbox-rebuild
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
sandbox-rebuild	✅ success

[github-actions]

E2E Target Results — ✅ All selected jobs passed

Run: 28982053077
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: ubuntu-repo-cloud-langchain-deepagents-code
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
live	✅ success

[github-actions]

E2E Target Results — ⚠️ Run cancelled — no signal

Run: 28982052878
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: rebuild-openclaw
Summary: 0 passed, 0 failed, 1 cancelled, 0 skipped

Job	Result
rebuild-openclaw	⚠️ cancelled

[github-actions]

E2E Target Results — ⚠️ Run cancelled — no signal

Run: 28982052790
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: rebuild-hermes
Summary: 0 passed, 0 failed, 1 cancelled, 0 skipped

Job	Result
rebuild-hermes	⚠️ cancelled

[github-actions]

E2E Target Results — ✅ All selected jobs passed

Run: 28982301085
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: ubuntu-repo-cloud-langchain-deepagents-code
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
live	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28982301148
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: sandbox-rebuild
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
sandbox-rebuild	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28982301131
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: rebuild-openclaw
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
rebuild-openclaw	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28982301095
Workflow ref: refactor/6485-rebuild-finalization-gating
Requested targets: (default — all supported)
Requested jobs: rebuild-hermes
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
rebuild-hermes	✅ success

[jyaunches]

Final validation on head 61e8c5dbd:

• PR Review Advisor: merge_as_is, zero required findings/warnings/suggestions
• all five CLI shards, build/typecheck, static checks, installer integration, CodeQL, growth guardrails, macOS, and WSL checks passed
• required live E2E passed:
  • sandbox-rebuild
  • rebuild-openclaw
  • rebuild-hermes
  • ubuntu-repo-cloud-langchain-deepagents-code

This supplies the advisor's remaining runtime-validation and CI-evidence follow-ups. The PR remains draft as requested.

[jyaunches]

Closing this draft stack as requested while the broader human-and-agent lifecycle architecture is reconsidered.