fix(upgrade): warn that non-.openclaw sandbox data is not preserved on recreate (#7073)

[yanyunl1991]

Context

Part of #7073. A legacy v0.0.55 → current upgrade recreates the managed sandbox and restores it from a pre-upgrade backup. That backup scopes to /sandbox/.openclaw only (see rebuild-backup-phase.ts manifest dir: "/sandbox/.openclaw"), so any files the user keeps elsewhere in the sandbox (e.g. /sandbox/user-data) are dropped by the recreate with no prior notice.

I reproduced the loss on real hardware: after a legacy-recreate, non-.openclaw paths are absent from the recreated sandbox while .openclaw state is restored intact.

Note: the messaging-channel loss facet of #7073 is being addressed separately via the maintainer's recommended v0.0.63 migration bridge (which writes the plan-based messaging registry entry that #5123 made authoritative). I validated that bridge on a fresh v0.0.63 install and reported the migrated-sandbox residual behavior in the issue thread. This PR does not claim to close that facet, so it does not Fixes #7073.

Change

Print a warning in the prepared-backup-recovery summary. It shows in both upgrade-sandboxes --check (dry run) and the real recreate, immediately after the list of sandboxes that will be recovered — i.e. before the destructive step — so users can back up non-.openclaw paths externally first.

  Prepared backup recovery:
    my-assistant  2026-07-17T08-27-20-142Z  (non-Ready)
    ⚠ Recovery restores /sandbox/.openclaw state only. Files outside .openclaw
      (e.g. /sandbox/user-data) are NOT preserved by the recreate — back them up
      before upgrading.

Verification

• New unit test drives the real upgradeSandboxes through the prepared-recovery branch and asserts the warning is emitted.
• Verified end-to-end on an x86_64 Ubuntu 24.04 host: forced a registered sandbox non-Ready with a validated backup and confirmed the live binary prints the warning in the --check output.
• typecheck:cli and the full upgrade-sandboxes-recovery suite (35 tests) pass.

Independent validation

The reporter independently ran the full v0.0.55 → v0.0.63 → v0.0.81 bridge on their own hardware and confirmed: the messaging bridge preserves the Slack channel (schema-v1 messaging.plan written on the v0.0.63 re-apply, survives to v0.0.81), while /sandbox/user-data seeded before the final upgrade is still lost afterward — i.e. the non-.openclaw data loss this PR warns about is the tracked concern of the issue, and an external backup remains required.

Scope

Deliberately narrow: a warning only. It does not change backup scope or restore behavior (widening the backup to cover arbitrary sandbox paths is a larger design decision about what the managed lifecycle owns). This just closes the silent-data-loss gap by making the boundary explicit before the irreversible recreate.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved sandbox upgrade/recovery messaging by adding a warning that recreate restores only the validated managed-state directory recorded in the recovery manifest, not other directories such as /sandbox/user-data, and reminding users to back up those paths beforehand.

• Tests

  • Enhanced the recovery test harness to support per-agent restore manifest directories and added a parameterized test (issue #7073) verifying upgrade warning order and that rebuildSandbox runs only in { auto: true } mode (none in { check: true }).

Signed-off-by: Yanyun Liao yanyunl@nvidia.com

[coderabbitai]

📝 Walkthrough

Walkthrough

Prepared backup recovery now reports the validated agent-specific state directory restored during recreation and warns that files outside it are not preserved. Tests cover multiple manifests, warning order, preservation boundaries, and automatic versus check modes.

Changes

Prepared recovery scope

Layer / File(s)	Summary
Agent-specific recovery manifests src/lib/actions/upgrade-sandboxes-recovery.test.ts	The recovery harness generates manifests for multiple agent directories, supports partial registry overrides, and maps default backup manifests to each sandbox’s agent type.
Recovery warning and regression coverage src/lib/actions/upgrade-sandboxes.ts, src/lib/actions/upgrade-sandboxes-recovery.test.ts	The upgrade action warns that only the recorded managed-state directory is restored; parameterized tests verify warning contents and order, excluded data, and rebuild behavior in automatic and check modes.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The warning now covers the legacy recreate path and tells users that data outside the managed-state directory is not preserved, matching #7073.
Out of Scope Changes check	✅ Passed	The changes stay focused on recreate-warning behavior and its tests, with no unrelated feature additions.
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 accurately summarizes the main change: adding a recreate warning that non-.openclaw sandbox data is not preserved.

✨ 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/7073-legacy-upgrade-channel-and-userdata

---

_{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 main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/7073-legacy-upgr... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 027632a	fix/7073-legacy-upgr... db7734a	+/-
src/lib/onboard...corporate-ca.ts	100%	92%	-8%
src/lib/onboard...host-anchors.ts	94%	90%	-4%
src/lib/actions...eway-restart.ts	93%	90%	-3%
src/lib/onboard...u-patch-mode.ts	93%	90%	-3%
src/lib/onboard...tch-recreate.ts	95%	94%	-1%
src/lib/messagi...flow-planner.ts	93%	93%	0%
src/lib/actions...de-sandboxes.ts	89%	90%	+1%
src/lib/onboard...carryforward.ts	92%	96%	+4%
src/lib/sandbox...vileged-exec.ts	75%	87%	+12%
src/lib/onboard...box-prebuild.ts	69%	88%	+19%

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/upgrade-sandboxes-recovery.test.ts`:
- Around line 193-204: Extend the recovery warning test around upgradeSandboxes
to cover both auto mode and check mode, using the public entrypoints. Capture
console warning and rebuildSandbox events in a shared sequence, then assert the
non-.openclaw preservation warnings occur before rebuilding in each mode while
retaining the existing message assertions.

🪄 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: 6d0adf15-c98e-4a82-a5fa-5b19abc54e47

📥 Commits

Reviewing files that changed from the base of the PR and between 027632a and 9c88fd0.

📒 Files selected for processing (2)

• src/lib/actions/upgrade-sandboxes-recovery.test.ts
• src/lib/actions/upgrade-sandboxes.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high 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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

Since last review: 0 prior items resolved · 0 still apply · 0 new items found

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: state-backup-restore, upgrade-stale-sandbox

Workflow run details

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/upgrade-sandboxes-recovery.test.ts`:
- Around line 238-267: The recovery test currently allows one console.log call
to satisfy multiple path assertions. Update the warning recorder around
upgradeSandboxes to capture each matching warning call as a distinct event, then
assert exactly one warning event for every statePath and verify the expected
warning content; ensure the assertions fail if multiple agent paths are merged
into one log call.

🪄 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: abc88b7a-c8be-4a03-ad81-094eb3f3b841

📥 Commits

Reviewing files that changed from the base of the PR and between 9c88fd0 and c3d400d.

📒 Files selected for processing (2)

• src/lib/actions/upgrade-sandboxes-recovery.test.ts
• src/lib/actions/upgrade-sandboxes.ts

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

• src/lib/actions/upgrade-sandboxes.ts

[apurvvkumaria]

Approved at exact head db7734a. The preservation warning is manifest-derived, emitted before destructive rebuild in both auto and check paths, and covered as one distinct warning per recovered sandbox. Focused validation passed 36/36; ordinary CI, both selected protected E2E scenarios, CodeRabbit, and the advisor are green with zero unresolved threads or actionable findings. The lack of an acknowledgement pause is consistent with this PR's explicit warning-only scope.