Bug: openclaw update --yes self-restart conflicts with launchd supervisor and exits non-zero after successful update

Summary

On a macOS install managed by LaunchAgent, openclaw update --yes from 2026.4.29 to 2026.5.18 completed the version swap and plugin update, but then failed during its internal restart step with:

Gateway did not become healthy after restart.
Service runtime: status=running, state=running, pid=38228
Port 18789 is already in use.
- pid 38228 jeff: /opt/homebrew/opt/node/bin/node /opt/homebrew/lib/node_modules/openclaw/dist/index.js gateway --port 18789 (127.0.0.1:18789)
- Gateway already running locally. Stop it (openclaw gateway stop) or use a different port.

The update process exited non-zero even though the installed version advanced to 2026.5.18 and the gateway ultimately became healthy.

Environment

• Host: macOS 14.7.4 arm64
• Node: 25.6.1
• Install: pnpm-global at /opt/homebrew/lib/node_modules/openclaw
• Gateway: LaunchAgent ai.openclaw.gateway, KeepAlive=true, RunAtLoad=true, ThrottleInterval=1
• From: OpenClaw 2026.4.29 (a448042)
• To: OpenClaw 2026.5.18 (50a2481)

Operator workflow

The update pipeline intentionally stops the LaunchAgent before touching the bundle:

launchctl bootout gui/<uid>/ai.openclaw.gateway
openclaw update --yes
openclaw doctor --fix
launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/ai.openclaw.gateway.plist

This is done to avoid a known macOS failure mode where KeepAlive=true respawns the old gateway while files are being replaced, leaving a running Node process referencing stale hashed chunks.

What happened

The update itself succeeded:

• global update succeeded
• global install swap succeeded
• internal doctor succeeded
• plugin updates succeeded
• openclaw --version returned OpenClaw 2026.5.18 (50a2481)

But the internal Restarting service... step appears to have spawned a gateway process, then treated that same process as a port conflict. The command exited non-zero, which made external automation treat the whole update as failed.

Net result:

• update succeeded
• restart health check reported failure
• an orphan gateway process was left outside the original supervisor flow
• a later launchctl bootstrap printed Bootstrap failed: 5: Input/output error, while launchd still ended up showing the gateway as running

Expected behavior

For supervised installs, operators need one of:

• openclaw update --yes --no-restart
• openclaw update --yes --manage-service=never
• automatic detection of launchd/systemd/supervisord with handoff to the supervisor
• a structured exit code where “update succeeded, restart failed” is distinguishable from “update failed”

Suggested fixes

1. Add --no-restart or --manage-service=auto|never to openclaw update.
2. Make the restart health check pid-aware. If the updater just spawned pid 38228, do not classify pid 38228 listening on the expected port as “already running locally.”
3. Split exit codes:
   • 0: update and restart succeeded
   • 2: update succeeded, restart failed
   • 1: update itself failed
4. Consider --json output for machine-readable update state:

{
  "before": "2026.4.29",
  "after": "2026.5.18",
  "update": "succeeded",
  "restart": {
    "status": "failed",
    "reason": "port-in-use"
  }
}

Workaround

Our local pipeline now captures the updater exit code without set -e, immediately checks openclaw --version, and treats a version advance as update success while continuing with external validation.

That workaround is brittle. A first-class --no-restart flag would be cleaner.