fix(onboard): settle OpenClaw pairing after rebuild

[rsliter]

Outcome

Rebuilding an ordinary OpenClaw sandbox settles canonical CLI pairing before onboarding reports success. The first agent command after rebuild no longer requires manual recovery.

This is the clean maintainer replacement for #10493. That fork branch contains 302 obsolete divergent commits and cannot be refreshed without rewriting contributor history. The implementation remains credited to @jiaqiang000.

Related issue

Fixes #10479

Changes

• Remove the rebuild-only exemption from ordinary OpenClaw pairing settlement.
• Remove the finalization-only handoff plumbing that existed solely for that exemption.
• Keep one ordering regression proving deployment verification waits for pairing settlement.
• Require one fatal public agent turn after the live rebuild and remove the redundant unchecked inference probe.
• Keep the E2E assertion ratchet aligned with the reduced assertion surface.

Scope

This restores the existing rebuild contract. It adds no product surface, retry mechanism, registry, or new live target. The effective diff is 9 files, +79/-212.

Verification

Exact candidate: 328b47ec5ea442e7f069de0416e2b0c408a3ff6c
Recorded base: 2cbc32c1573d8da6e5d2c62592fcb023a888d002

• Focused onboarding flow and finalization tests: 94/94 passed.
• E2E client and agent-turn support tests: 88 passed with 38 intentionally skipped live variants.
• E2E assertion census: 1794 direct assertions across 85 files passed its ratchet.
• Semantic phase coverage: 134 tests across 87 files passed.
• NODE_OPTIONS=--max-old-space-size=8192 npm run check:diff passed, including CLI typecheck and the repository's pre-commit and pre-push validation.
• The exact-head managed-image workflow run 34536497880 passed after rerunning only MCP discovery pass 1. Its first attempt timed out against an externally generated Cloudflare endpoint while identical pass 2 succeeded on the same published candidate; the failed-job rerun passed without a code change.
• Trusted focused rebuild-openclaw E2E run 34608282431 passed with correlation 2c86e95a-f2a1-4374-a20f-367269465293 using trusted workflow c5d9cb2b1873a5e2397cd67656c505304e848818. Retained evidence binds the tested candidate to 328b47ec5ea442e7f069de0416e2b0c408a3ff6c: the post-rebuild agent returned 42, the workspace marker survived, token rotation passed, and cleanup removed the rebuilt sandbox, OpenShell sandbox, gateway, old image, and restored state files with no failures.

Review notes

• Fresh exact-head CodeRabbit review reported no actionable findings.
• Exact-head PR Review Advisor run 34606196713 completed all nine specialist reviews successfully. The full customer value, security, verification, documentation, migration, delivery, operability, reduction, and architecture writeups report no actionable defect. Each applicable specialist selected the existing rebuild-openclaw E2E, which passed at the exact candidate above.
• Earlier Advisor findings were addressed by binding the agent proof to the candidate CLI, asserting successful marker reads, and using a named 120-second post-rebuild agent-turn budget. The current focused tests and exact live E2E cover those repairs.
• Independent security review passed all nine categories. The change adds no dependency, secret, policy, credential, or product surface.
• The required npm run review:local attempt was unavailable because its temporary OpenShell gateway refused connections. It produced no findings. Exact local checks, required CI, CodeRabbit, managed-image validation, and the focused live E2E all passed.

---

Signed-off-by: Rebecca Sliter 571084+rsliter@users.noreply.github.com

Summary by CodeRabbit

• Bug Fixes

  • Improved onboarding reliability by requiring standard OpenClaw pairing to complete before deployment verification.
  • Prevented deployment verification from starting while pairing remains pending.
  • Improved rebuild validation by confirming agent readiness and successful post-rebuild responses.

• Tests

  • Updated coverage for pairing and recovery sequencing.
  • Strengthened end-to-end rebuild checks, including agent response validation and endpoint reachability.
  • Added fast-test coverage for the rebuild workflow.

[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]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 245bbdcd-02be-44a3-a241-16c2e68d76c8

📥 Commits

Reviewing files that changed from the base of the PR and between 7fac669 and f9e1e88.

📒 Files selected for processing (1)

• ci/e2e-assertion-budget.json

Included review availability: Your plan provides up to 12 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The rebuild flow no longer uses recreateJournalHandoff to skip ordinary OpenClaw pairing. Finalization tests verify pairing order, and the rebuild E2E test verifies agent usability after rebuild.

Changes

Rebuild pairing restoration

Layer / File(s)	Summary
Remove pairing handoff and require pairing src/lib/onboard/machine/flow-context.ts, src/lib/onboard/machine/handlers/finalization.ts, src/lib/onboard/machine/core-flow-phases.ts, src/lib/onboard/machine/final-flow-phases.ts	Removed recreateJournalHandoff from flow contexts, finalization options, and handler calls. Ordinary OpenClaw pairing is now required.
Validate pairing order src/lib/onboard/machine/handlers/finalization.test.ts, src/lib/onboard/machine/rebuild-pairing-handoff.test.ts, test/e2e/mock-parity.json	The tests verify that deployment verification waits for pairing settlement. The obsolete handoff test is deleted, and the fast-test list includes the finalization test.
Validate post-rebuild agent readiness test/e2e/live/rebuild-openclaw.test.ts, ci/e2e-assertion-budget.json	The rebuild test runs an agent request and expects 42. Obsolete inference and policy assertions are removed, and assertion budgets are updated.

Priority: ➖ Normal

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

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant RebuildE2E as rebuild-openclaw.test.ts
  participant Finalization as finalization handler
  participant Pairing as OpenClaw pairing
  participant Agent as nemoclaw agent
  RebuildE2E->>Finalization: complete rebuild finalization
  Finalization->>Pairing: settle ordinary OpenClaw pairing
  Pairing-->>Finalization: pairing settles
  Finalization-->>RebuildE2E: continue post-verification
  RebuildE2E->>Agent: request response after rebuild
  Agent-->>RebuildE2E: return JSON answer 42

Loading

Suggested reviewers: ericksoa

Merge Risk: ⚪ Minimal · up to f9e1e

The rebuild pairing and readiness changes have no unresolved merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #10479 by removing the rebuild-only pairing bypass, requiring ordinary OpenClaw pairing settlement, and adding regression coverage that verifies post-rebuild agent usability.
Out of Scope Changes check	✅ Passed	The assertion-budget updates, test coverage changes, E2E validation, and mock-parity update directly support the pairing-after-rebuild fix. No unrelated changes are evident.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: fixing OpenClaw pairing settlement after a rebuild.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-10479-rebuild-pairing

---

_{Comment @coderabbitai help to get the list of available commands.}

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 328b47e in the codex/fix-10479-rebu... branch remains at 96%, unchanged from commit c5d9cb2 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 328b47e in the codex/fix-10479-rebu... branch remains at 83%, unchanged from commit c5d9cb2 in the main branch.

Show a line coverage summary of the most impacted files.

File	main c5d9cb2	codex/fix-10479-rebu... 328b47e	+/-
src/lib/actions...dbox/destroy.ts	92%	89%	-3%
src/lib/actions...oy-execution.ts	94%	91%	-3%
src/lib/domain/...ycle/options.ts	87%	85%	-2%
src/lib/actions...-add-restart.ts	31%	30%	-1%
src/lib/onboard...uild-context.ts	75%	75%	0%
src/lib/actions...confirmation.ts	69%	69%	0%
src/lib/domain/...dbox/destroy.ts	97%	97%	0%
src/lib/onboard...finalization.ts	98%	98%	0%
src/lib/onboard...eway-process.ts	89%	90%	+1%
src/lib/actions...oy-preflight.ts	83%	84%	+1%

---

_{Updated September 11, 2026 13:45 UTC}

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[rsliter]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-actions]

PR Review Advisor finished for commit 328b47e. Include the Advisor findings in the complete PR feedback collection. Verify and group valid findings before repair.

All previous runs