fix(installer): recover sandboxes before onboarding

docs/get-started/quickstart.mdx

@@ -109,7 +109,10 @@ After the installer launches `nemoclaw onboard`, the wizard runs preflight check
 It prints a review summary before it registers the provider with OpenShell.
 After you confirm, NemoClaw registers inference, prompts for optional web search and messaging channels, builds and starts the sandbox, sets up OpenClaw, then applies the selected network policy tier and presets.
 At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit.
-If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches.
+If registered sandboxes already exist, the installer runs `nemoclaw backup-all` when the installed CLI supports it, then runs `nemoclaw upgrade-sandboxes --auto` before generic onboarding.
+For a registered sandbox that is non-Ready after the host upgrade, the installer restores its validated latest backup only when the backup identity matches and its registry entry has a NemoClaw-managed image fingerprint.
+Pre-fingerprint and custom-image sandboxes are not recreated automatically because matching agent versions do not prove image provenance.
+If an automatic rebuild fails, or a non-Ready recovery is blocked or fails, the installer exits with a nonzero status and does not start generic onboarding.
 
 The inference provider prompt presents a numbered list.
 

docs/manage-sandboxes/lifecycle.mdx

@@ -262,6 +262,9 @@ $$nemoclaw upgrade-sandboxes --check
 ```
 
 Before upgrade work, the installer runs `$$nemoclaw backup-all` when the installed CLI supports it.
+After the host CLI and OpenShell update, the installer runs `$$nemoclaw upgrade-sandboxes --auto` before generic onboarding.
+If an existing sandbox is non-Ready, the automatic path requires a validated latest backup whose sandbox and agent identity match the registry and positive evidence that NemoClaw managed the image.
+The installer attempts every eligible recovery, exits with a nonzero status if any recovery fails, and does not continue to generic onboarding after that failure.
 For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need:
 
 ```bash

scripts/install.sh

@@ -532,7 +532,7 @@ print_done() {
   local _needs_cli_refresh=false
   needs_shell_reload && _needs_cli_refresh=true
 
-  # #5735: do not claim a clean install when the post-onboard auto-upgrade of a
+  # #5735: do not claim a clean install when the automatic upgrade of a
   # pre-existing sandbox failed (it may have been destroyed before its recreate
   # failed). Surface an explicit incomplete/recovery status instead.
   if [[ "${_UPGRADE_SANDBOXES_FAILED:-false}" == true ]]; then
@@ -909,7 +909,7 @@ ONBOARD_RAN=false
 # auto-onboarding (#3276).
 _CLI_PATH=""
 _PREEXISTING_SANDBOX_COUNT=0
-# #5735: set when the post-onboard auto-upgrade of pre-existing sandboxes
+# #5735: set when automatic recovery/upgrade of pre-existing sandboxes
 # reported a failure. A failed/destructive rebuild must not be reported as a
 # clean install, so print_done downgrades the final banner when this is true.
 _UPGRADE_SANDBOXES_FAILED=false
@@ -1867,12 +1867,12 @@ EOF
 preinstall_backup_and_retire_legacy_gateway() {
   local reg_file="${HOME}/.nemoclaw/sandboxes.json"
   [ -f "$reg_file" ] || return 0
-  command_exists openshell || return 0
 
   local sandbox_count
   sandbox_count="$(registered_sandbox_count)"
   _PREEXISTING_SANDBOX_COUNT="$sandbox_count"
   [ "$sandbox_count" -gt 0 ] 2>/dev/null || return 0
+  command_exists openshell || return 0
 
   if [[ "${NEMOCLAW_SINGLE_SESSION:-}" == "1" ]]; then
     error "Aborting — NEMOCLAW_SINGLE_SESSION is set. Destroy existing sessions with '${_CLI_BIN} <name> destroy' before reinstalling."
@@ -2147,6 +2147,27 @@ run_installer_host_preflight() {
   [[ "$status" -ne 10 ]]
 }
 
+recover_preexisting_sandboxes_before_onboard() {
+  local cli_runner="$1"
+  if [ "${_PREEXISTING_SANDBOX_COUNT:-0}" -le 0 ] 2>/dev/null; then
+    return 0
+  fi
+
+  info "Recovering and upgrading pre-existing sandboxes before onboarding…"
+  # `--auto` is the existing non-interactive maintenance path. When the
+  # pre-upgrade backup signal is present, the CLI also recovers registered
+  # non-Ready sandboxes from their validated latest backup. It attempts every
+  # eligible sandbox before returning non-zero for any failure.
+  if "$cli_runner" upgrade-sandboxes --auto 2>&1; then
+    return 0
+  fi
+
+  _UPGRADE_SANDBOXES_FAILED=true
+  warn "One or more existing sandboxes could not be recovered automatically."
+  warn "Generic onboarding will not run; review the affected sandbox and preserved backup diagnostics above."
+  return 1
+}
+
 run_onboard() {
   show_usage_notice
   info "Running ${_CLI_BIN} onboard…"
@@ -2726,23 +2747,12 @@ main() {
       warn "Set NEMOCLAW_SINGLE_SESSION=1 to abort the installer when sessions are active."
     fi
     if run_installer_host_preflight; then
+      if ! recover_preexisting_sandboxes_before_onboard "$_cli_runner"; then
+        finalize_install
+        return 1
+      fi
       run_onboard || error "Onboarding did not complete successfully."
       ONBOARD_RAN=true
-      # After onboard, check for stale sandboxes that need rebuilding (#1904).
-      # Uses --auto so it runs non-interactively in piped/CI contexts.
-      if [ "${_PREEXISTING_SANDBOX_COUNT:-0}" -gt 0 ] 2>/dev/null && [ -n "$_cli_runner" ]; then
-        info "Checking for sandboxes that need upgrading…"
-        # #5735: a non-zero exit here can mean an existing sandbox was rebuilt
-        # destructively and its recreate failed. Record it so print_done reports
-        # the install as incomplete with recovery guidance instead of a clean
-        # banner. The CLI already prints the affected sandbox name and the
-        # preserved backup path on failure.
-        if ! "$_cli_runner" upgrade-sandboxes --auto 2>&1; then
-          _UPGRADE_SANDBOXES_FAILED=true
-          warn "One or more existing sandboxes could not be upgraded automatically."
-          warn "Review the messages above — affected sandboxes may need '${_CLI_BIN} onboard --resume' or '${_CLI_BIN} <name> rebuild', and any backup path shown above can restore workspace state."
-        fi
-      fi
       restore_onboard_forward_after_post_checks || error "Hermes host forward restore failed."
     elif [ "${NON_INTERACTIVE:-}" = "1" ]; then
       error "Skipping onboarding until the host prerequisites above are fixed."
@@ -2757,9 +2767,8 @@ main() {
 }
 
 # Print the completion summary, then propagate a fatal/non-zero result when the
-# post-onboard auto-upgrade of a pre-existing sandbox failed (#5735, PRA-5). The
-# new sandbox may have onboarded fine, but a failed auto-upgrade can have left an
-# *existing* sandbox destroyed or backup-only, so the install must not be
+# automatic recovery of a pre-existing sandbox failed (#5735, PRA-5). A failed
+# recovery can have left an existing sandbox destroyed or backup-only, so the install must not be
 # reported as success. print_done() has already shown the affected sandbox and
 # recovery guidance (and the "completed with warnings" banner); exiting non-zero
 # here is what keeps automation and operators from treating it as a clean