OpenClaw Live Updater

Keep one operator-selected canonical live checkout as a read-only-to-the-agent deployment mirror: clean, standalone, full, on main, and fast-forwarded only. Make every repair in the controlling Codex project worktree.

Boundaries

• Report only in the controlling Codex thread. Never send Slack, Discord, email, or other external messages.
• Never release, tag, bump versions, publish npm, create a GitHub Release, rotate credentials, or weaken a gate.
• Escalate only irreversible or materially risky security, privacy, auth, destructive migration/data-loss, protocol-version, credential-rotation, dependency patch/override, or product choices.
• Diagnose ordinary update, runtime, app, CI, test, and release-validation failures; fix them through a focused PR; prove exact head; land with scripts/pr.
• Never edit, stash, reset, clean, or create a branch in the live mirror.
• Never use launchctl submit or create an ad-hoc KeepAlive job to run updates or Gateway lifecycle commands. A submitted job can relaunch openclaw gateway restart after every exit and cause a persistent restart storm, even without a plist (#114967).

Fast Update And Maintenance

1. Run the deterministic updater and retain its JSON:

   cd "<canonical-live-checkout>"
   node --import tsx .agents/skills/openclaw-live-updater/scripts/update-main.mjs
   

   The helper owns the current working directory by default; it does not search parent directories or infer a clone from the user's home directory. From a controlling worktree, pass the canonical mirror explicitly with --checkout "<canonical-live-checkout>". Stop on any failed invariant. Do not repair the mirror destructively. The helper holds one checkout-scoped lock across update, build, Gateway proof, and Mac work. A concurrent heartbeat returns reason: "overlap"; it must not start another build. A dead owner lock may be recovered, but unreadable or unsafe lock state fails closed. Linux systemd managed Gateways are outside this helper. It refuses before Git mutation with unsupported_gateway_control_platform and leaves operators on the standard update CLI from openclaw-update.

2. The helper verifies one unrewritten expected origin, an owned non-symlinked standalone/full clone, single worktree, clean main, fetches origin/main, rechecks for concurrent changes, and merges --ff-only. It then uses the source runner's canonical local-build metadata contract and parser: both dist/.buildstamp and dist/.runtime-postbuildstamp heads, required runtime-postbuild outputs, dist/entry.js, Control UI index plus referenced local assets, and dist/build-info.json must all match exact afterSha.

   • Every successful update sets actions.gatewayBuild and rebuilds exact new main before any restart.
   • Missing, invalid, or stale build output also forces a build, even when Git did not move.
   • A dependency-input change, absent node_modules, or missing/invalid build provenance requires pnpm install --frozen-lockfile. When a build is required, do not install before acquiring the maintenance suspension and stopping the managed Gateway.
   • Before mutating any entrypoint currently executed by the Gateway, invoke an exact trusted source CLI to acquire gateway.suspend.prepare, binding both prepare and resume to this checkout's managed LaunchAgent loopback port and service auth even when normal CLI configuration points at a remote Gateway. The LaunchAgent may execute either this checkout's dist/index.js or a clean detached canonical snapshot under ~/.openclaw/runtime/gateway-<sha> whose commit is an ancestor of the checkout; reject every other entrypoint. Never execute snapshot code: capture an exact source control build before the Git fast-forward for its prepare and failure-resume calls, preserve any validated generated service-environment wrapper, and stop the managed LaunchAgent with native launchd bootout. If that control build is missing, first accept native proof that the snapshot job is already booted out with its port free; when the isolated snapshot is still running, build the verified clean source checkout to obtain an exact suspension client, then use only that source client for prepare and failure-resume. Never use this recovery build while launchd targets the source checkout. This atomically pauses cron scheduling, closes new work admission, and refuses while active work remains. A busy result defers further mutation to the next heartbeat; never replace this fence with cron list polling. Once ready, stop directly without a source launcher, install frozen dependencies when required, then build unless the exact recovery build already produced the deployment artifact; source launchers can auto-build stale output before dispatching the stop. Every external phase has a wall-clock budget: Git fetch 5 minutes, Git merge 2 minutes, dependency install 15 minutes, Gateway build 20 minutes, service control 60 seconds, probes 30 seconds, and Mac rebuild 30 minutes. Progress output never extends a budget. A timeout must drain the task-owned process tree before rollback, previous-service bootstrap, lock release, or the final JSON result. If POSIX cleanup cannot prove the process group gone, skip service recovery, retain the maintenance lock against that process group, and emit ; after an operator terminates the group, the next heartbeat reclaims the stale lock. Resume the suspension if stop fails. If suspension RPC is unavailable on macOS, proceed only when native inspection proves this checkout's managed LaunchAgent is booted out and its configured port has no listener; never accept a loaded KeepAlive job's transient stopped state. On non-macOS hosts refuse before Git mutation with and leave operators on the standard update CLI. Never treat a Linux systemd Gateway as this helper's stop-proof path. This preserves retry after a post-stop failure without weakening the live-work fence. Preserve outside for the build and restore it even when the build fails, because the JS build cleans regardless of Mac impact classification. Never mutate the live tree while an old Gateway can dynamically import from it. must leave both canonical stamp heads and equal to post-update ; any missing/mismatched stamp or required artifact blocks restart.

3. If changed paths can affect macOS, the helper runs scripts/restart-mac.sh --sign --wait --target-only with SKIP_TSC=1 and SKIP_UI_BUILD=1 only after the exact-SHA JS/UI build completes. Reusing those artifacts keeps the live app bundle out of any later JavaScript build cleanup. Target-only mode may stop the canonical /Applications/OpenClaw.app process and this checkout's exact dist process before launching the rebuilt dist app. It defers when another worktree, temporary bundle, test, or agent-owned OpenClaw process is active; it never kills that process. The script's immediate OK is not proof. The helper waits and requires the exact executable <canonical-live-checkout>/dist/OpenClaw.app/Contents/MacOS/OpenClaw, derived from the verified checkout, then repeats Gateway RPC and health proof.

   Never kill another worktree, temporary bundle, test, or agent-owned OpenClaw process. If a foreign app prevents the exact target from staying alive, record the pending Mac attempt, report it, and retry on the next heartbeat. Escalate only after the conflict persists across repeated heartbeats; never claim Mac proof from another bundle or the short launch check. If actions.macUiVerification is true, exercise the changed behavior with the existing macOS/UI automation workflow after delayed exact-bundle proof.

4. Load $openclaw-testing. Resolve exact current origin/main, then inspect only relevant required checks and workflow jobs whose headSha equals it. Ignore skipped jobs and routine noise such as Auto response, Labeler, docs agents, performance advisory jobs, and stale/cancelled runs superseded by a newer run for the same SHA.

5. For an attributable failure, leave the mirror untouched. Use the controlling Codex worktree, trace the failed surface, add focused proof, run $autoreview, open a focused PR, and land through $openclaw-pr-maintainer's exact scripts/pr sequence. Never weaken or bypass the failing gate. After landing, begin again at step 1 so the mirror, Gateway, app classification, and exact-head checks all converge on new main.

If no update, build repair, pending Mac retry, or exact-head failure exists, report a terse no-op with the SHA and proof checked.

Full Release Validation

Load $release-openclaw-ci and $openclaw-testing. This is validation only, never release preparation or publication.

1. Treat 12 hours as wall-clock cadence, not per-SHA cadence. Inspect Full Release Validation runs from the last 12 hours and verify effective release_profile=full, rerun_group=all, and expected child-job shape. Any valid active or successful full/all umbrella in that window satisfies the cadence even if main advanced afterward. Never duplicate an active full/all run. The scheduled Full Release Validation Nightly (04:00 UTC, stable profile, main-qualification) is additional stable-profile evidence and never satisfies this full/all cadence; when both target the same SHA, the full sweep still runs and may adopt the nightly's per-child receipts.

2. Only when the cadence is due, confirm no full/all run is active, then snapshot exact current origin/main after checking mirror invariants. Run the provider-secret preflight without printing secrets and dispatch the trusted workflow once:

   MAIN_SHA="<exact-main-sha>"
   pnpm ci:full-release \
     -f validation_purpose=main-qualification \
     --sha "$MAIN_SHA" \
     --workflow-sha "$MAIN_SHA" \
     -f provider=openai \
     -f mode=both \
     -f release_profile=full \
     -f rerun_group=all
   

3. Let the helper watch the parent to terminal and verify its release evidence. Retain its parent URL and require the recorded target SHA and children to match the dispatch snapshot. Fetch logs only for failed or blocking jobs. Do not cancel unrelated release checks.

4. For a code or harness failure, repair and land from the Codex worktree as above. Then invoke the same helper with a new frozen exact-main tuple and the narrowest supported rerun_group that covers the failed child; use live_suite_filter for one live/E2E shard. A targeted recovery run does not create a second full/all cadence dispatch.

5. Report exact SHA, parent and child run URLs/IDs, conclusions, repairs and landed PRs, targeted reruns, and any genuine proof gap. Do not write release evidence or publish artifacts unless separately authorized.

Failure Discipline

• Recheck live mirror invariants before every mutation and after every fetch.
• Attribute failures from exact SHA, job, logs, and current source. Provider or infrastructure flakes need independent proof before code edits.
• Keep the task branch focused. No CHANGELOG.md change.
• Finish with the mirror clean/on main, the Codex worktree clean on the expected branch, remote Testbox stopped, and every public GitHub write linked in the controlling thread.