Add controlled update cutover guardrail

README.md

@@ -148,6 +148,7 @@ journalctl --user -u openclaw-gateway -f
 - `health-check.sh` can report a process uptime failure immediately after `openclaw gateway restart` if the target has a minimum uptime threshold (e.g. 300s). That is expected — lower the threshold during smoke tests, then restore it.
 - `security-scan.sh` reports file paths and line numbers for suspected secrets, but redacts the secret values themselves.
 - `check-update.sh` is intended for real post-upgrade triage. It is normal to report a version change the first time it runs after an upgrade.
+- `update-cutover.sh` is the controlled update guardrail. Run it before and after production/macOS/custom-runtime upgrades to capture baseline evidence, force an official-vs-custom lane decision, record app/CLI scope, prompt hack/workaround review, and verify the post-update state. It does not run `openclaw update` itself.
 - `post-update.sh` is the explicit post-update orchestrator. It skips the heavy sequence when the current version matches the stored state and otherwise runs `check-update.sh --fix`, `heal.sh`, the workspace reconcile script if present, `security-scan.sh`, and a final `openclaw health --json`.
 - On the VPS, the workspace reconcile stage refreshes model policy, auth/profile state, voice defaults, and the gateway service through `openclaw_post_update_reconcile.py` (or the equivalent systemd oneshot wrapper).
 - After the health check it best-effort touches `~/.openclaw/state/policy-guard.trigger` (creating parent dirs if needed). The VPS can wire `openclaw-policy-guard.path` to that sentinel after updates.

SKILL.md

@@ -26,6 +26,7 @@ On Knox's machine, the canonical ops checkout is `/Users/knox/Developer/openclaw
 | Script | When to use |
 |--------|-------------|
 | `heal.sh` | First thing on any health check — fixes gateway, auth mode, exec approvals, crons, and stuck sessions in one pass |
+| `update-cutover.sh` | Controlled upgrade guardrail — preflight baseline, official/custom lane gate, macOS app-scope check, hack-audit prompt, and post-cutover verification |
 | `post-update.sh` | Run after `openclaw update` — orchestrates check-update, heal, workspace reconcile, security scan, and final health check in sequence |
 | `watchdog.sh` | Continuous monitoring; run every 5 min via LaunchAgent. HTTP health check → auto-restart → escalation after 3 failures |
 | `watchdog-install.sh` | Set up the watchdog as a macOS LaunchAgent (survives reboots) |
@@ -57,6 +58,12 @@ On Knox's machine, the canonical ops checkout is `/Users/knox/Developer/openclaw
 # One-pass heal:
 bash scripts/heal.sh
 
+# Controlled OpenClaw upgrade cutover:
+bash scripts/update-cutover.sh --preflight --target-version v2026.X.Y --lane official --app-scope cli
+# ...run the approved OpenClaw update...
+bash scripts/post-update.sh
+bash scripts/update-cutover.sh --post --target-version v2026.X.Y --lane official --app-scope cli --cutover-dir ~/.openclaw/update-cutovers/<stamp>-v2026.X.Y
+
 # Install always-on watchdog (macOS):
 bash scripts/watchdog-install.sh
 
@@ -134,6 +141,19 @@ If outdated: `curl -fsSL https://openclaw.ai/install.sh | bash && openclaw gatew
 
 After any version upgrade, run `check-update.sh` to catch breaking config changes.
 
+## Controlled Update Cutover
+
+For routine patch updates on simple installs, `post-update.sh` is enough after the update. For production gateways, macOS installs, custom/local runtimes, or any update meant to fix a live incident, treat the update as a controlled cutover:
+
+1. Run `update-cutover.sh --preflight --target-version <version> --lane official|custom --app-scope cli|app|both|none`.
+2. Review the generated `CUTOVER.md`: release risks, official/custom lane, macOS app scope, current config/cron/channel baseline, hack/workaround audit, rollback target, and single-restart plan.
+3. Run the approved OpenClaw update only after the cutover gate is satisfied.
+4. Run `post-update.sh`.
+5. Run `update-cutover.sh --post ... --cutover-dir <same-dir>` and any host-specific channel smoke tests.
+6. If verification fails, stop layering fixes; roll back to the prior known-good runtime target and verify restored health.
+
+`update-cutover.sh` intentionally does **not** execute `openclaw update`; it records evidence and enforces the decision gates around the update.
+
 ---
 
 ## Fix Priority (Health Check Order)