upgrade

# OpenClaw Safe Upgrade

Single atomic command. Auto-rollbacks on ANY failure. Survives the gateway restart it triggers.

## Script

```bash
# From an agent session — ALWAYS set escape flag (ensures script survives gateway restart)
_UPGRADE_FORCE_ESCAPE=1 bash skills/upgrade/scripts/safe-upgrade.sh

# Force upgrade even if already on latest
_UPGRADE_FORCE_ESCAPE=1 bash skills/upgrade/scripts/safe-upgrade.sh --force

# Safe read-only checks (no escape needed)
bash skills/upgrade/scripts/safe-upgrade.sh --check      # Pre-flight only
bash skills/upgrade/scripts/safe-upgrade.sh --rollback    # Manual rollback
```

## What Happens (one command, 10 steps)

1. **Cgroup escape**: re-execs via `systemd-run --user --scope` so gateway stop can't kill the script
2. Pre-flight: version check, disk space, breaking changes
3. Backup: installation tarball, config, cron jobs, acpx customizations
4. `npm i -g openclaw@latest`
5. Restore acpx config (ACP agent customizations survive upgrades)
6. Gateway restart (process-isolated: stop + start, survives script's own lifecycle)
7. Wait for gateway health (configurable timeout) → **auto-rollback if fails**
8. Wait for WhatsApp reconnect (non-fatal timeout)
9. Verify: correct version + cron count preserved → **auto-rollback if fails**
10. Record result → optional golden snapshot → cleanup backup

If ANY critical check fails, the script **automatically rolls back** — restores install, config, crons, and acpx. Trap handler catches unexpected exits during critical phases.

## Agent Workflow

1. Run `--check` first. Review output with the user.
2. Inform user: "Launching upgrade — I'll go offline during gateway restart."
3. Run the upgrade:
   ```bash
   _UPGRADE_FORCE_ESCAPE=1 bash skills/upgrade/scripts/safe-upgrade.sh
   ```
   **Do NOT pipe the output** (no `| tee`, no `2>&1 | cat`). The script writes to `/tmp/upgrade-live.log`.
4. **The current session will end** when the gateway restarts. This is expected.
5. After restart, the new ses...