fix(cli): stabilize restored snapshot pairing verification

[sandl99]

Summary

Snapshot restore could create a clone whose OpenShell phase was Ready before its persisted startup command had finished starting the managed OpenClaw supervisor. NemoClaw then applied snapshot state while clone initialization was still active, allowing the restored workspace marker to disappear and gateway pairing verification to fail. The first readiness fix also treated the clone's temporarily undiscoverable direct container as a terminal refusal. This change requires a bounded managed-supervisor readiness proof before any snapshot state is applied, retries only the typed direct-container discovery gap, and strengthens the live test to prove that the authenticated session belongs to the clone rather than the source sandbox.

Related Issue

Fixes #7818

Changes

• Wait for the new OpenClaw clone's managed supervisor after OpenShell reports Ready and before applying snapshot state.
• Sanitize and retry the exact typed direct-container discovery gap within that existing bound; keep identity, driver, and integrity refusals terminal.
• Fail closed when the bounded supervisor proof does not succeed: leave the destination registered, apply no snapshot state, and report the recovery choices.
• Keep the existing classified restored-gateway recovery path for the exact missing-supervisor case.
• Strengthen snapshot-commands so one unique post-restore session must exist in the clone's session store, remain absent from the source, and produce exactly one authenticated inference request.
• Apply the actionable review findings: reuse the bounded scope parser, assert the timeout/watcher subprocess status, and execute the generated-shell test fixture through standard input instead of an argv command string.
• Accept the canonical sanitized credential placeholder in snapshot leak scans while continuing to reject concrete credentials.
• Document the OpenClaw-only restore readiness and failure contract in the backup/restore guide and command reference.
• Clarify the reviewed restored-clone credential boundary: descriptor-backed paired-token custody, exact live preflight, canonical rotation, and atomic client-auth synchronization.

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: Codex Desktop reviewed all nine security categories at head 3e36ca0529214640d4667bfe1effdbd3f033c881 and reported PASS with no findings. Snapshot application fails closed until the managed clone gateway is proven healthy. The bounded read-only readiness check retries only typed direct-container absence and a bare GATEWAY_HEALTH_TIMEOUT; diagnostic-bearing output plus identity, driver, and integrity refusals remain terminal. Paired-token authentication remains pinned to clone descriptors and loopback transport; pre-approval mismatches prevent the approval call, and post-state mismatches fail client synchronization without claiming rollback of a persisted server transition. Raw sensitive diagnostics remain suppressed.
• 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: Independently reviewed all 26 changed files at head fbe22b450861ef52c7b27339c74a540a947559c4. The latest E2E scanner change accepts only the canonical sanitized credential placeholder and needs no additional documentation; the existing three documentation updates remain accurate. The focused scanner test passed 61/61, and Biome plus git diff --check passed. The broad E2E-support lane passed 1,838 tests; its seven failures concern untouched systemd and workflow fixtures.
• Agent: Codex Desktop documentation-writer subagent

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 check:diff passed when hooks were skipped or unavailable — exact-head hooks and npm run validate:pr passed repository checks, Biome, gitleaks, source-shape, test-size, commitlint, and CLI TypeScript checks.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — the focused snapshot credential scanner run passed 61/61 at exact head. On the preceding runtime head, process-recovery passed 2 files and 47 tests; snapshot/restore lifecycle passed 3 files and 74 tests; the broad snapshot-focused run passed 13 files and 112 tests. CLI build/typecheck, repository checks, E2E phase semantics, documentation sync, and documentation build passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Exact-head CI run 30611717158 passed all sharded tests, static checks, build/typecheck, audits, and platform checks. Trusted E2E child run 30612401782 passed snapshot-commands, rebuild OpenClaw, state backup/restore, onboarding, cloud inference, and both security-posture matrices.
• 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) — passed with 0 errors and 2 pre-existing Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Prekshi Vyas prekshiv@nvidia.com
Signed-off-by: San Dang sdang@nvidia.com

Summary by CodeRabbit

• New Features
  • Expanded auto-pair approval “receipt” statuses with more granular list-phase and validation outcomes (timeouts, exec failures, empty/invalid responses, missing pending, and gateway/scope/device pairing issues).
  • Improved local-device-only approvals by recovering eligible pending devices and tightening reconciliation of final authorization results.
• Bug Fixes
  • Enhanced restored gateway pairing restarts with an additional recovery path when the supervisor is reported as not running.
• Tests
  • Broadened receipt parsing and expanded restored-clone coverage with scenario-driven sandbox behaviors, including stdout/stderr leakage checks and completion/timeout handling.

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

[github-actions]

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

[cv]

Blocking on current-head live E2E. The exact-head snapshot-commands job at 8c7ff317 failed during the first clone restore: after OpenShell reported the clone Ready, the new supervisor-readiness gate exited in 3.7 seconds with managed OpenClaw supervisor did not become ready and Snapshot state was not restored, so the test classified the result as command-failure. This occurs before the pairing path and therefore does not verify the fix for the original scope-upgrade-pending; approval=list-failed breakage.

waitForManagedGatewaySupervisor() is configured for an 11-attempt, 3-second bounded window, but it returns immediately for any first probe result outside the exact success / SUPERVISOR_NOT_RUNNING / SUPERVISOR_BUSY forms. Please preserve the fail-closed boundary, expose a sanitized classification for the observed first probe failure, handle only the proven transient startup state, and rerun snapshot-commands repeatedly at the new head. The branch must also be refreshed onto current main before approval.

Evidence: https://github.com/NVIDIA/NemoClaw/actions/runs/30606026011/job/91078463431