OpenClaw Main Closes Managed-Update Handoff and Plugin-Convergence Gaps

OpenClaw’s new scheduled update campaigns have gained another round of important follow-up fixes on main. The updater now distinguishes live terminal policy from stale task-owned terminals, migrates configured plugins before final validation, avoids duplicate package installation, verifies launchd actually restarted and reports the real outcome in Control UI.

Together they close the dangerous middle of an update. Choosing a target is not enough; the updater must prove which service, checkout and completed workload it owns until the replacement process is healthy.

These are merged source changes. Confirm the first release containing all required fixes before relying on the combined lifecycle. This article was updated on August 11 to include the later plugin-convergence, terminal-policy, restart-verification and UI-result repairs.

1. Completed tasks no longer look like active work

PR #121267 fixes task-owned terminal PTYs that survived after a detached run completed. Those stale registrations remained in Gateway active-work accounting, so gateway.suspend.prepare could report busy indefinitely and managed deployment could not proceed safely.

The repair ties terminal cleanup to exact task lifecycle rather than session-name inference. Completed, failed, timed-out, cancelled and lost tasks close their owned terminal registrations, including a pending spawn that finishes late. Deliberate conversation-owned or operator-owned terminals retain their existing persistence.

This matters because discounting “old-looking” terminals at suspension time would be unsafe. The producer that owns the task must close them; the suspension gate should continue counting every genuinely live PTY.

2. Supervisors are stopped before files move

PR #103537 addresses a race where package or checkout files could be replaced while a loaded supervisor was between Gateway instances.

On macOS, an enabled LaunchAgent with KeepAlive may respawn as soon as the process stops. Linux and Windows managed handoffs can represent the same transition. A replacement running underneath a respawning process risks loading a mixed tree or colliding with mutation.

The updater now distinguishes an enabled, respawn-pending managed service from an ordinarily stopped or persistently disabled one. It quiesces the former before replacement and leaves disabled LaunchAgents, unloaded jobs, ordinary stopped units and foreign mutation roots untouched. Failed replacement must not revive a service the operator deliberately disabled.

3. A handoff cannot switch checkouts

PR #121288 binds managed handoff, restart sentinel and install receipt to the canonical install root selected by the update owner.

Previously, a detached child could rediscover a different OpenClaw checkout. Receipts were associated with revision and profile but not root, so two checkouts at the same SHA could share the wrong installedAt evidence.

The fix rejects a handoff or restart that resolves to another checkout. Symlink aliases remain valid when they canonicalise to the same root.

Interpretation: a commit SHA identifies source content, not the process installation that an operator authorised to mutate.

4. Pinned dev campaigns survive restart with provenance intact

Scheduled dev updates intentionally apply an exact commit and may leave the checkout detached. PR #121328 fixes the next restart losing the upstream that produced that commit, after which update status reported no-upstream and future hourly campaigns stopped.

The updater now carries both the frozen SHA and canonical upstream through the handoff, verifies ancestry before mutation, verifies final detached HEAD, and persists upstream provenance only in a successful receipt. Startup reuses it only when both canonical root and SHA still match. A normal tracked branch remains authoritative, and an unmanaged detached checkout still has no invented upstream.

5. Open terminals become an explicit update policy

PR #121601 replaces an accidental all-or-nothing terminal blocker with an explicit policy upgrade. A containing updater can preserve deliberate operator terminals where supported instead of leaving every Gateway update waiting indefinitely.

That does not make terminals harmless. Operators still need to prove which terminal survives, which task-owned PTY must close, and whether a process inside it can observe or execute against a changing installation. The safe rule is ownership, not age: completed task terminals close; deliberate operator terminals follow the updater’s documented policy.

6. Plugin migration and installation converge once

PR #122048 moves plugin-config migration before final validation so an installed plugin and its current configuration are judged as one upgraded state rather than validating a stale shape too early.

PR #122161 then fixes the same configured plugin being installed twice during one package upgrade. The repair makes updater Doctor phases explicit and prevents ambient convergence state leaking into fresh child environments.

For operators, a successful core package replacement is not enough. The installed plugin artifact, migrated config and post-plugin validation must agree exactly once.

7. Restart and UI outcome become proof, not optimism

PR #121747 makes the macOS updater verify the launchctl bootstrap postcondition rather than treating command invocation as service recovery. A managed update is incomplete until the intended LaunchAgent is actually loaded.

PR #121686 fixes the Control UI side of the same problem. The update dialog remains visible through installation and disconnect, reports the recorded failing step and captured cause, and replays verified success after reload. The sidebar no longer returns immediately to a stale “commits behind” call to action while work is still running.

One limit remains explicit upstream: a detached helper that dies before persisting its result can still leave its useful handoff log outside the normal Gateway logs. A truthful UI cannot display evidence the backend never durably recorded.

Recommended rollout

Treat these fixes as one acceptance boundary for managed automatic updates:

1. choose a non-production Gateway with the same supervisor type as production;
2. create one completed background task with a terminal and prove suspension becomes ready;
3. keep one intentional operator terminal live and prove suspension remains blocked;
4. run a harmless package-replacement fixture while observing supervisor state;
5. verify no Gateway respawns until mutation and recovery ownership permit it;
6. persistently disable the service, force an update failure and require it to remain disabled;
7. place a second checkout at the same revision and require foreign-root handoff and receipt reuse to fail;
8. apply a pinned dev campaign, restart, advance the test upstream and prove a second campaign is discovered; and
9. install a configured plugin fixture and require one artifact request, migrated config and successful post-plugin validation;
10. on macOS, require the expected LaunchAgent to be loaded after bootstrap—not merely a zero exit code;
11. watch one update from Control UI through disconnect and reload, then force a synthetic failure and require its real failing step; and
12. reconcile running Gateway version, checkout root, exact SHA, plugin state, receipt and supervisor state.

Never use an unreviewed production update as the first lifecycle test. A successful command exit is not enough if the service serving traffic came from a different root.

Bottom line

Scheduled campaigns are only trustworthy when suspension, terminal ownership, plugin convergence, service control, mutation identity, visible outcome and restart provenance agree. Track a containing build for the full set, then test the stop–replace–migrate–restart chain under the supervisor you actually run.