fix(sandbox): re-establish gateway pairing after cross-sandbox snapshot restore

[laitingsheng]

Summary

A sandbox created by a cross-sandbox snapshot restore (snapshot restore --to <new>) started without gateway device credentials, so its first openclaw agent run failed with GatewayCredentialsRequiredError. Device identity and pairing tokens are deliberately never captured into snapshots, and — unlike onboard — the restore path never re-established them before handoff. The restore path now runs the same pairing finalisation onboard runs, so a restored destination holds working gateway credentials and its agent runs immediately.

Related Issue

Fixes #7431

Changes

• src/lib/actions/sandbox/snapshot.ts: after a successful OpenClaw cross-sandbox restore, invoke gateway pairing establishment for the freshly created destination. Hermes and Deep Agents destinations skip the OpenClaw-only step; self-restore remains untouched.
• src/lib/actions/sandbox/restore-gateway-pairing.ts: orchestrates the onboard warm-up, auto-pair approval, and strict authenticated verification sequence. Failures propagate so restore exits nonzero with repair guidance.
• src/lib/adapters/openshell/restore-gateway-pairing.ts (new): owns the OpenShell process boundary for the authenticated verification run, with a 30-second timeout and embedded/fallback transport rejection.\n- src/lib/adapters/openshell/restore-gateway-pairing.test.ts and src/lib/actions/sandbox/restore-gateway-pairing.test.ts: cover success, nonzero exit, timeout, missing executable, spawn failure, orchestration order, and propagated failures.
• src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts: asserts a cross-sandbox restore establishes and verifies pairing, verification failure returns repair guidance, and a self-restore does not touch credentials.

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:
• 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: maintainer-reviewed. Pairing remains cross-sandbox only, reuses the existing allowlisted warm-up and approval primitives, and now verifies authenticated gateway use without exposing tokens. Runtime authentication state remains excluded from snapshots, self-restores remain untouched, and verification failure exits nonzero with repair guidance.
• 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: docs-updated
• Evidence: docs/manage-sandboxes/backup-restore.mdx documents authenticated OpenClaw pairing verification after cross-sandbox restore, retained restored state on verification failure, the nonzero result, and the exact connect recovery command.
• Agent: Codex Desktop
• PR: fix(sandbox): re-establish gateway pairing after cross-sandbox snapshot restore #7437

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 commit appears as Verified in GitHub
• 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: snapshot and pairing adapter/action suites → 7 files / 91 tests pass; npm run typecheck:cli, npm run checks, and npm run check:diff pass.
• 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; the change is a localised sandbox action fix, not a broad runtime/test-harness or repo-wide validation change.
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• New Features
  • Restoring a snapshot into a different sandbox now automatically performs gateway pairing for the destination, including warmup, approval, and authenticated verification.
  • Restoring into the same sandbox preserves existing gateway credentials and skips pairing.
• Bug Fixes
  • If gateway pairing verification fails during restoration, the restore now stops with a clear error and retry guidance (e.g., run the destination connect command).
• Tests
  • Added/expanded tests covering pairing call order, propagated failure behavior, and snapshot-restore integration for cross- vs self-restore scenarios.
• Documentation
  • Updated backup/restore guidance to explain destination pairing behavior and what happens when verification fails.

[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

Snapshot restoration now establishes and verifies gateway pairing for newly created destination sandboxes. Cross-sandbox restores run pairing after reconciliation, while self-restores skip it. Pairing and verification failures propagate with retry guidance.

Changes

Restored gateway pairing

Layer / File(s)	Summary
Gateway pairing helper src/lib/actions/sandbox/restore-gateway-pairing.ts, src/lib/actions/sandbox/restore-gateway-pairing.test.ts	Adds gateway verification constants, sandbox-execution verification, dependency wiring, ordered warmup/approval/verification, enriched errors, and unit coverage.
Snapshot restore integration src/lib/actions/sandbox/snapshot.ts, src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts, src/lib/actions/sandbox/snapshot-restore-test-fixture.ts, src/lib/actions/sandbox/snapshot.test.ts	Runs pairing after cross-sandbox restore reconciliation, reports verification failures as command errors, skips self-restore pairing, and mocks the helper in snapshot tests.
Restore behavior documentation docs/manage-sandboxes/backup-restore.mdx	Documents destination pairing preservation, authenticated verification, nonzero failures, and retrying with connect.

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

Sequence Diagram(s)

sequenceDiagram
  participant SnapshotRestore
  participant PairingHelper
  participant ScopeWarmup
  participant ScopeApproval
  participant GatewayVerification

  SnapshotRestore->>PairingHelper: cross-sandbox restore completed
  PairingHelper->>ScopeWarmup: warm up scope upgrade
  ScopeWarmup-->>PairingHelper: completion
  PairingHelper->>ScopeApproval: approve scope pairing
  ScopeApproval-->>PairingHelper: completion
  PairingHelper->>GatewayVerification: execute authenticated verification
  GatewayVerification-->>PairingHelper: success or failure
  PairingHelper-->>SnapshotRestore: complete or raise retryable command error

Loading

Suggested labels: integration: openclaw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address #7431 by automatically re-pairing cross-sandbox restores so restored sandboxes regain gateway credentials.
Out of Scope Changes check	✅ Passed	The added verification, tests, and documentation all support the restore-pairing fix and do not introduce unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: restoring gateway pairing after cross-sandbox snapshot restores.

✨ 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 fix/snapshot-restore-gateway-pairing

---

_{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 63e83b3 in the fix/snapshot-restore... branch remains at 96%, unchanged from commit 3f65c23 in the main branch.

---

_{Updated July 24, 2026 03:34 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / medium confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 12 warnings · 1 suggestion

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: onboard-repair, onboard-resume, state-backup-restore, upgrade-stale-sandbox

3 optional E2E recommendations

• snapshot-commands
• rebuild-openclaw
• 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.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7437.docs.buildwithfern.com/nemoclaw

[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/actions/sandbox/restore-gateway-pairing.test.ts`:
- Line 38: Append the final issue-reference suffix "(`#7431`)" to the test titles
at src/lib/actions/sandbox/restore-gateway-pairing.test.ts lines 38, 56, and 66,
and at src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts line 240,
preserving the existing title text.

In `@src/lib/actions/sandbox/restore-gateway-pairing.ts`:
- Around line 44-68: Move OpenShell resolution and spawnSync execution from
verifyRestoredSandboxGatewayPairing into a dedicated adapter, then have the
action delegate gateway verification through that adapter. In
src/lib/actions/sandbox/restore-gateway-pairing.ts lines 44-68, retain the
action’s orchestration and boolean outcome contract. In
src/lib/actions/sandbox/restore-gateway-pairing.test.ts lines 66-74, mock the
adapter and replace RESTORE_GATEWAY_PAIRING_VERIFY_SCRIPT text assertions with
coverage for successful verification, failed verification, and timeout behavior.

🪄 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: 0c246b91-80a2-48e2-82fc-a4a377fe155b

📥 Commits

Reviewing files that changed from the base of the PR and between bdf1fd6 and b2a6780.

📒 Files selected for processing (5)

• docs/manage-sandboxes/backup-restore.mdx
• src/lib/actions/sandbox/restore-gateway-pairing.test.ts
• src/lib/actions/sandbox/restore-gateway-pairing.ts
• src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts
• src/lib/actions/sandbox/snapshot.ts

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

• docs/manage-sandboxes/backup-restore.mdx
• src/lib/actions/sandbox/snapshot.ts

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts (1)

194-295: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add the #7431 issue-reference suffix to the new test titles.

This whole suite exists to fix issue #7431 (gateway credentials missing after cross-sandbox restore), but none of the new describe/it titles carry the (#1234) suffix required by the coding guideline.

As per coding guidelines, **/*.test.{js,ts}: "Use behavior-oriented test titles and place local issue references in a final (#1234) suffix."

✏️ Suggested title update

-describe("runSandboxSnapshot restore: gateway pairing on a freshly created destination", () => {
+describe("runSandboxSnapshot restore: gateway pairing on a freshly created destination (`#7431`)", () => {

🤖 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 `@src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts` around lines 194
- 295, Append the issue-reference suffix "(`#7431`)" to the new describe and it
titles in the runSandboxSnapshot restore suite. Keep the existing
behavior-oriented wording unchanged and place the suffix at the end of each
title, including the self-restore test.

Source: Coding guidelines

🤖 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 `@src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts`:
- Around line 194-295: Append the issue-reference suffix "(`#7431`)" to the new
describe and it titles in the runSandboxSnapshot restore suite. Keep the
existing behavior-oriented wording unchanged and place the suffix at the end of
each title, including the self-restore test.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 602bfdcb-de87-482e-bc55-2d4a736cf628

📥 Commits

Reviewing files that changed from the base of the PR and between b2a6780 and 5ebdc36.

📒 Files selected for processing (2)

• src/lib/actions/sandbox/snapshot-restore-lifecycle.test.ts
• src/lib/actions/sandbox/snapshot-restore-test-fixture.ts

[prekshivyas]

Approved at exact head af4fc2d after the maintainer gate passed: current-base CI and selected E2E are green, mergeable, DCO/Verified complete, and no unresolved major review findings remain.