fix(restore): restart gateway after pairing approval

[cv]

Summary

Cross-sandbox snapshot restore could inspect a gateway-global pending-device list and approve a different sandbox's request before verifying the restored clone. After restore, this change restarts and warms the clone, approves at most one bounded pairing or scope-upgrade request that matches the clone's local identity, restarts its gateway, and treats one ordinary authenticated verifier as the sole success condition.

Related Issue

Related to #7431 and #4462. Corrects the restore-pairing lifecycle introduced by #7437.

Changes

• Keep the established restart → warm-up → approval → restart → authenticated verification sequence to publish approved state before verification.
• Select only one pending CLI/operator request whose public key and derived device ID match the restored clone.
• Accept canonical pairing-only requests plus bounded write-scope initial or repair requests, including OpenClaw's pre-convergence isRepair: false, scopes: ["operator.write"] shape; reject malformed, ambiguous, duplicate, foreign, empty, read-only, noncanonical, or over-scoped requests.
• Preserve the canonical OpenClaw approval command, stripped gateway credentials, existing one-request budget, and existing timeouts.
• Remove the former two-cycle retry path; verification runs exactly once and is the only success condition.
• Classify production and live-test failures with fixed, output-free values.
• Route the live pairing probe through the clone's sandbox environment and hermetic inference fixture.
• Require trusted PR E2E planning to include snapshot-commands when restored-gateway pairing production modules change.
• Add focused lifecycle, identity/scope, environment-isolation, redaction, and risk-plan regressions, including invalid clone identity and nonrepair write-only cases.

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 repairs internal clone pairing selection and restart ordering without changing the documented snapshot restore contract.
• 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 exact-final-head nine-category review passed with no findings at 9f439dfd418d89be4870c4f3378c57af8a530b3c against origin/main 1bc0283144062b560e7496baa92d3293e4a65089. It reviewed all 16 changed files and confirmed accepted product scope, clone-only environment/inference routing, exact paired device/public-key binding, bounded canonical scopes, stored operator.pairing authorization for the pre-convergence write request, canonical locked publication, fixed output-free classifications, and the unchanged one-approval/one-verifier sequence without retries or longer timeouts.
• 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: At exact final head 9f439dfd418d89be4870c4f3378c57af8a530b3c, the writer reviewed the complete 16-file diff. Existing snapshot documentation already defines automatic clone pairing, ordinary authenticated verification, nonzero failure, retained restored state, and connect recovery. The OpenClaw 2026.7.1 dependency review already bounds exact CLI/operator pairing/read/write transitions through stored-device authentication and canonical fail-closed approval. This internal repair adds no CLI syntax, flag, configuration, API, schema, policy, or supported workflow, so no docs, changelog, or docs build is required.
• 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 published commit appears as Verified in GitHub; exact head 9f439dfd418d89be4870c4f3378c57af8a530b3c has a valid SSH signature and DCO trailer, and GitHub reports verified: true with reason valid.
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed 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: At exact final head 9f439dfd418d89be4870c4f3378c57af8a530b3c, 299/299 targeted tests passed: compiled OpenClaw patch regressions 53/53, clone pairing lifecycle 32/32, snapshot helper 17/17, real pinned OpenClaw dist proof 6/6, and adjacent risk/lifecycle/workflow/dependency/provenance suites 191/191. npm run typecheck:cli, git diff --check, signed commit hooks, and exact committed npm run check:diff all passed.
• 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 to this focused restore-path repair; affected and exact suites plus check:diff passed.
• 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)

Trusted E2E on exact prior head 2193b9ea83e001bcca6b92cb6467eda7d835f037 (child run 30249871943, snapshot job 89925344542) failed snapshot-commands with fixed classification scope-upgrade-pending; that SHA was not retried. Trusted E2E on exact prior head d2808095c7da86640b29affe911b0600dc5fdb11 (child run 30259361580, snapshot job 89955535331) passed seven selected lanes and failed only snapshot-commands with the same fixed classification; that SHA was not retried. Trusted E2E on exact prior head c45892130795ce1e22143af00046b386bb24ee72 (controller 30263636883, child 30263933229, snapshot job 89970220974) again passed seven selected lanes and failed only snapshot-commands at restore-to-clone with fixed classification command-failure; its captured verifier layer was scope-upgrade-pending. Retry/reconciliation steps were skipped and that SHA will not be retried. Trusted E2E on exact prior head f2fd8676e156bdd31ca29ec51660a8c9a6d04525 (controller 30269186094, child 30269513049, snapshot job 89988454045) passed every companion selected lane and failed only snapshot-commands at the first restore-to-clone phase. Artifact 8654481473 (sha256:74af24bfafbc6fa1fb1cf7abe1233a4c1b202d5d70f086c6a9afd77bad154906) recorded fixed outer classification command-failure and verifier layer scope-upgrade-pending, exit 1 without timeout. Evidence verification passed, every retry step was skipped, and that SHA will not be retried. Fresh ordinary gates and automated review must pass on 9f439dfd418d89be4870c4f3378c57af8a530b3c before authorizing only its exact trusted coverage.

---

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

[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

📝 Walkthrough

Walkthrough

The restored gateway pairing flow now uses bounded cycles, restarting before warm-up and after approval before verification. Unit, snapshot-restore, E2E authentication, and risk-plan tests cover the revised sequence and routing.

Changes

Restored gateway pairing

Layer / File(s)	Summary
Recovery cycle control flow src/lib/actions/sandbox/restore-gateway-pairing.ts	The recovery budget is renamed to cycles, with an initial restart and a restart after each warm-up and approval sequence before verification.
Recovery cycle sequencing tests src/lib/actions/sandbox/restore-gateway-pairing.test.ts	Tests validate revised ordering across successive approved transitions, post-approval restart failure handling, and updated restart counts.
Snapshot restore validation test/snapshot-gateway-guard.test.ts	Snapshot restore validation expects the registered image tag and two gateway restarts before pairing verification.
E2E authentication validation and routing test/e2e/live/snapshot-commands.test.ts, tools/e2e/workflow-boundary.mts, test/pr-risk-plan.test.ts	The snapshot E2E flow verifies authenticated restored-gateway pairing and inference requests, while pairing runtime changes select the snapshot-commands focused job and risk-plan mapping.

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

Suggested labels: area: sandbox, area: e2e, bug-fix

Suggested reviewers: prekshivyas, jyaunches, laitingsheng

Sequence Diagram(s)

sequenceDiagram
  participant SnapshotRestore
  participant RestoredGatewayPairing
  participant Gateway
  participant PairingVerifier
  SnapshotRestore->>RestoredGatewayPairing: establish pairing
  RestoredGatewayPairing->>Gateway: restart before warm-up
  RestoredGatewayPairing->>Gateway: warm up and approve transition
  RestoredGatewayPairing->>Gateway: restart after approval
  RestoredGatewayPairing->>PairingVerifier: verify pairing

Loading

🚥 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 accurately summarizes the main change: restarting the gateway after pairing approval during restore flow.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-restored-gateway-pairing-restart

---

_{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 b545da5 in the codex/fix-restored-g... branch remains at 96%, unchanged from commit a8748ab in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit b545da5 in the codex/fix-restored-g... branch remains at 80%, unchanged from commit a8748ab in the main branch.

Show a code coverage summary of the most impacted files.

File	main a8748ab	codex/fix-restored-g... b545da5	+/-
src/lib/actions...time-command.ts	100%	82%	-18%
src/lib/actions...-add-restart.ts	19%	10%	-9%
src/lib/actions...on-readiness.ts	100%	91%	-9%
src/lib/actions...lution-probe.ts	95%	88%	-7%
src/lib/actions...x/mcp-bridge.ts	41%	35%	-6%
src/lib/state/o...oint-migrate.ts	96%	92%	-4%
src/lib/actions...e-validation.ts	84%	81%	-3%
src/lib/onboard...shboard-port.ts	93%	90%	-3%
src/lib/actions...dbox/destroy.ts	95%	93%	-2%
src/lib/onboard...eway-service.ts	82%	81%	-1%

---

_{Updated July 27, 2026 16:45 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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 1 blocker · 2 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 1 more blocker, 2 more warnings, the same number of suggestions.

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: cloud-onboard, credential-sanitization, security-posture, onboard-repair, onboard-resume, snapshot-commands, state-backup-restore, upgrade-stale-sandbox

1 optional E2E recommendation

• issue-4462-scope-upgrade-approval

Workflow run details

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

[coderabbitai]

🧹 Nitpick comments (1)

test/snapshot-gateway-guard.test.ts (1)

305-305: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert restart ordering, not only restart count.

The assertion at Line 318 verifies two identical restart entries but does not prove that the second restart occurred before authenticated pairing verification. Add an observable verification marker to the fixture and assert the full sequence so the title at Line 305 reflects actual behavioral coverage.

As per path instructions, tests should prioritize behavioral confidence over implementation lock-in.

Also applies to: 318-318

🤖 Prompt for 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.

In `@test/snapshot-gateway-guard.test.ts` at line 305, Update the test named
“snapshot restore --to uses registered imageTag and restarts the VM gateway
before pairing verification” to add an observable pairing-verification marker in
the fixture, then assert the complete event sequence showing both gateway
restarts occur before authenticated pairing verification. Replace the
count/duplicate-entry assertion near the restart checks with this ordered
behavioral assertion.

Source: Path instructions

🤖 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.

Nitpick comments:
In `@test/snapshot-gateway-guard.test.ts`:
- Line 305: Update the test named “snapshot restore --to uses registered
imageTag and restarts the VM gateway before pairing verification” to add an
observable pairing-verification marker in the fixture, then assert the complete
event sequence showing both gateway restarts occur before authenticated pairing
verification. Replace the count/duplicate-entry assertion near the restart
checks with this ordered behavioral assertion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0d787b71-b0d1-4847-8162-f5f53fd50a51

📥 Commits

Reviewing files that changed from the base of the PR and between 3e123dc and 790b4d1.

📒 Files selected for processing (1)

• test/snapshot-gateway-guard.test.ts

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@test/e2e/live/snapshot-commands.test.ts`:
- Line 214: Update the test around the “snapshot restore --to returns only after
restored gateway pairing is authenticated” case and its corresponding lines
430-442 so authentication is observed or asserted before the restore command
resolves. Start the authentication event/status probe before invoking restore,
and ensure the assertion proves the pairing was already authenticated at
completion rather than allowing a later recovery to satisfy the test.
- Around line 128-130: Update the assertions around resultText(result) to avoid
passing raw child output as Vitest messages or asserting directly on unsanitized
stdout/stderr. Use the existing redaction/observation helper to derive
timestamp/stream-only data, then assert on sanitized lengths or boolean match
results while preserving the exit-code and rejection checks without exposing
command contents, tokens, or credentials.
- Around line 113-125: Update the pairing probe helper around sandbox.execShell
to pass the target sandboxName and inference fixture into commandEnv(). Ensure
commandEnv() accepts and uses both values, so the openclaw agent request routes
through the restored clone and its intended inference fixture before
inference.requests() is asserted.

🪄 Autofix (Beta)

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: 50047e64-d30b-4f50-b1c1-559abdbffe1a

📥 Commits

Reviewing files that changed from the base of the PR and between 3f669da and 8b04fce.

📒 Files selected for processing (1)

• test/e2e/live/snapshot-commands.test.ts

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.