fix: hand off supervised git updates by abnershang · Pull Request #91296 · openclaw/openclaw

abnershang · 2026-06-08T01:40:24Z

Summary

Route supervised git-source update.run calls through the detached update handoff path.
Keep unsupervised/dev git update calls on the existing in-process path.
Add regression coverage for supervised git handoff behavior.
Align update docs with supervised git handoff behavior.

Real behavior proof

Behavior addressed: a supervised git-source gateway could rebuild dist/ while the live gateway was still serving RPCs, creating a transient stale-artifact window. A previous self-update lab run observed a transient module-resolution failure during that live rebuild window.
Real environment tested: CrabBox GCP disposable VM (cbx_4e5f6399ffa8) from a fresh PR checkout at 50bafd3fc2fe62708bbed8c09259b62b9b62debf, using an isolated user-systemd gateway, isolated OpenClaw profile/state/config, and an isolated loopback port. The production fleet gateway was not changed.

Exact steps or command run after this patch:

crabbox run --provider gcp --type e2-standard-8 --fresh-pr openclaw/openclaw#91296 --script-stdin

Script high-level steps:
1. Install Node 22.19.0 and pnpm 11.2.2 in the disposable VM.
2. Run pnpm install --frozen-lockfile and pnpm build from the fresh PR checkout.
3. Install and start an isolated user-systemd OpenClaw gateway from the PR build.
4. Verify initial gateway health.
5. Call update.run through the backend Gateway RPC surface.
6. Wait for the detached helper log, final restart sentinel, service journal stop/start, and post-update health.
7. Stop the isolated gateway and release the disposable lease.

Evidence after fix:

update.run: status=skipped mode=git reason=managed-service-handoff-started
handoff: status=started command="openclaw update --yes --channel dev --timeout 1800"
restart: ok=true signal=SIGUSR1 reason=update.run
helper: started command=true, child pid logged=true, exited zero=true, completed after 907s
service journal: stop observed=true, start observed=true
health: before=true, after=true
final sentinel: kind=update status=ok version=2026.6.2
final sentinel after.sha=b8adc11977ab9dc1eb558dc070bfe63df75911c5
lease cleanup: stopped=true

Final update steps recorded in the sentinel:

clean check
git checkout main
git fetch
upstream check
git rev-parse @{upstream}
git rev-list
preflight worktree
preflight checkout (b8adc119)
preflight deps install (b8adc119)
preflight build (b8adc119)
preflight cleanup
git rebase
deps install
build
ui:build
openclaw doctor
git rev-parse HEAD (after)

Observed result after fix: the supervised git-source update.run request did not rebuild the live gateway process in-place. It returned the managed handoff result, wrote the handoff sentinel, signaled the isolated service for restart, then the detached helper completed the git update, dependency install, build, UI build, doctor check, service restart, and health verification.
What was not tested: native LLM agent turn and live Discord transport delivery. This proof covers Gateway RPC plus the managed-service lifecycle in an isolated service.

Tests

node scripts/run-vitest.mjs run --config test/vitest/vitest.gateway.config.ts src/gateway/server-methods/update.test.ts
node scripts/test-projects.mjs src/agents/tools/gateway-tool.test.ts
pnpm tsgo:core
pnpm build
git diff --check
crabbox run --provider gcp --type e2-standard-8 --fresh-pr openclaw/openclaw#91296 --script-stdin

Dependency changes

None. Dependency-file scan against origin/main returned no files.

AI-assisted

AI-assisted. I understand the change: supervised git-source updates now use the existing detached update handoff mechanism so the live gateway does not mutate its own built dist tree while handling the update RPC. Local Codex review was attempted but blocked by local Codex CLI auth returning 401 Unauthorized.

clawsweeper · 2026-06-08T01:42:10Z

Codex review: needs real behavior proof before merge. Reviewed June 10, 2026, 8:24 PM ET / 00:24 UTC.

Summary
The PR routes supervised git-source Gateway updates through detached managed-service handoff, adds git candidate preflight and managed-service stop/restart handling, tracks handoff completion in Control UI, and updates related tests and docs.

PR surface: Source +392, Tests +1353, Docs +9. Total +1754 across 22 files.

Reproducibility: yes. at source level and through the earlier systemd run: current main can rebuild a supervised git checkout while the Gateway is live, and the supplied environment reproduced the corrected handoff lifecycle. The exact latest head has not been re-proven.

Review metrics: 2 noteworthy metrics.

Managed-service lifecycle modes: 3 supervisors affected. The handoff and restart contract covers launchd, user-systemd, and Windows scheduled tasks, while current real proof covers only user-systemd.
Current-head proof drift: 20 later commits after proof head. The branch materially changed lifecycle and failure behavior after the recorded Crabbox run, so that run cannot establish the exact-head merge gate.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P1] Add exact-current-head managed-service proof for success and a post-stop failure path, with private details redacted.
[P1] Obtain explicit maintainer acceptance of fail-closed downtime or revise recovery to restore the prior runnable service.

Proof guidance:

[P1] Needs stronger real behavior proof before merge: The supplied user-systemd output is convincing for the earlier 50bafd3 head, but the exact current head has extensive later lifecycle changes without matching after-fix real proof; contributors should add redacted logs or terminal output and update the PR body to trigger review, or ask a maintainer for @clawsweeper re-review.

Risk before merge

[P1] A supervised git update now stops the matching managed Gateway before checkout mutation; post-core plugin convergence failure can leave it stopped, so existing operators may need manual recovery rather than getting the prior best-effort continued service.
[P2] The only supplied real environment run targets 50bafd3fc2fe62708bbed8c09259b62b9b62debf; the current head adds 20-plus later commits affecting service identity, preflight fallback, rollback, UI completion polling, and restart-health failure behavior.
[P1] The live proof covers user-systemd only; launchd and Windows scheduled-task service ownership/restart behavior remains supported mainly by source and mocked tests, not current-head real lifecycle evidence.

Maintainer options:

Prove the final fail-closed lifecycle (recommended)
Run the exact current head in a real managed service and demonstrate both successful handoff and a post-stop failure, including sentinel output, service state, health, and documented recovery.
Restore the last runnable service on failure
Change post-core convergence failure handling to roll back or restart the prior runnable checkout before exiting, with focused failure-path tests and real proof.
Accept operator-recovery downtime
Maintainers may intentionally accept that selected failed supervised git updates leave the Gateway stopped, provided the compatibility and recovery contract is explicit.

Next step before merge

[P1] Maintainers should decide the fail-closed service-availability contract, then require exact-head real lifecycle proof before merge.

Security
Cleared: No concrete security or supply-chain regression was found; the diff adds no dependencies or workflow permissions and keeps handoff metadata in restricted temporary files.

Review details

Best possible solution:

Keep the detached handoff and preflight-before-stop design, but land only after the stopped-service terminal policy is explicitly accepted and the exact current head proves successful update plus at least one post-stop failure/recovery path in a real managed service.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level and through the earlier systemd run: current main can rebuild a supervised git checkout while the Gateway is live, and the supplied environment reproduced the corrected handoff lifecycle. The exact latest head has not been re-proven.

Is this the best way to solve the issue?

Mostly yes: detached handoff with preflight before service stop is the cleanest owner-boundary fix for the live rebuild race. The unresolved question is the product contract for failures after the service has been stopped, not the central handoff architecture.

AGENTS.md: found and applied where relevant.

Codex review notes: reasoning high; reviewed against d559dfecfa7e.

Label changes

Label changes:

add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The supplied user-systemd output is convincing for the earlier 50bafd3 head, but the exact current head has extensive later lifecycle changes without matching after-fix real proof; contributors should add redacted logs or terminal output and update the PR body to trigger review, or ask a maintainer for @clawsweeper re-review.
remove status: ⏳ waiting on author: Current PR status label is status: 📣 needs proof.

Label justifications:

P1: A defect in this update path can interrupt a supervised Gateway and leave an active user workflow unavailable until recovery.
merge-risk: 🚨 compatibility: Existing supervised git update behavior changes to detached handoff and introduces fail-closed outcomes that may require operator action.
merge-risk: 🚨 availability: The patch deliberately stops the live Gateway before mutation, and some subsequent failures can leave the service offline.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The supplied user-systemd output is convincing for the earlier 50bafd3 head, but the exact current head has extensive later lifecycle changes without matching after-fix real proof; contributors should add redacted logs or terminal output and update the PR body to trigger review, or ask a maintainer for @clawsweeper re-review.

Evidence reviewed

PR surface:

Source +392, Tests +1353, Docs +9. Total +1754 across 22 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	9	593	201	+392
Tests	11	1431	78	+1353
Docs	2	40	31	+9
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	22	2064	310	+1754

What I checked:

Correct lifecycle boundary: The Gateway delegates supervised git updates to the existing detached helper; the CLI performs fetch and candidate preflight before invoking the new callback immediately before checkout mutation, limiting service downtime while preventing the live process from rebuilding its own dist tree. (src/infra/update-runner.ts:824, 649bdd994894)
Service ownership protection: Before git mutation, the CLI reads the managed service state and stops it only when its command resolves to the checkout being mutated; a service for another OpenClaw root remains running. (src/cli/update-cli/update-command.ts:851, 649bdd994894)
Fail-closed availability behavior: Ordinary update errors restart a service stopped for mutation, but a later post-core plugin convergence error exits before that recovery helper or the normal restart path runs, intentionally leaving the managed Gateway stopped until operator repair. (src/cli/update-cli/update-command.ts:3779, 649bdd994894)
Control UI handoff compatibility: The latest branch recognizes the successful ok: true plus result.status: skipped handoff response and polls update.status after reconnect until the final sentinel arrives, addressing the earlier client misclassification finding. (ui/src/ui/controllers/config.ts:285, 649bdd994894)
Earlier-head real environment proof: The PR body records a disposable GCP user-systemd run at head 50bafd3 that observed handoff initiation, service stop/start, successful helper completion, final sentinel, and healthy Gateway before and after; this is meaningful but does not validate the many later force-pushed commits through 649bdd9. (50bafd3fc2fe)
Documented upgrade contract: The docs now state that package and git updates stop matching managed services before mutable work and may exit non-zero with manual recovery instructions when restart health cannot be established. Public docs: docs/cli/update.md. (docs/cli/update.md:154, 649bdd994894)

Likely related people:

Peter Steinberger: Introduced the Gateway config/update restart flow in commit 71c3126 and has the largest historical contribution count across the central update, Gateway, and Control UI files. (role: introduced behavior; confidence: high; commits: 71c31266a1db; files: src/gateway/server-methods/update.ts, src/infra/update-runner.ts, src/cli/update-cli/update-command.ts)
Vincent Koc: Recent current-main blame and release consolidation cover the update handler and runner surfaces, making him a useful reviewer for interactions with the latest update architecture. (role: recent area contributor; confidence: medium; commits: 40da4a31d27a, 5181e4f7c82b; files: src/gateway/server-methods/update.ts, src/infra/update-runner.ts)
shakkernerd: Authored the extensive follow-up repairs for UI verification, service ownership, delayed stopping, preflight fallback, rollback, and restart health on the current branch; this is branch ownership rather than current-main provenance. (role: current branch repair owner; confidence: high; commits: 0debc9c84d2e, f64302ea35d9, 203146ded3b1; files: src/cli/update-cli/update-command.ts, src/infra/update-runner.ts, src/gateway/server-methods/update.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ab73ba3b3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-08T01:43:49Z

+        installSurface.kind === "global" ||
+        (installSurface.kind === "git" && supervisor)


Stop the supervised gateway before git handoff updates

When this branch includes supervised git installs, the detached helper waits for the parent to exit and then runs openclaw update, but the CLI only stops a managed service for package updates (src/cli/update-cli/update-command.ts:3362) and git updates go straight to runGitUpdate (src/cli/update-cli/update-command.ts:3415). In a launchd/systemd git-source gateway, the supervisor can relaunch the gateway as soon as this process exits, so the helper still rebuilds the git checkout/dist tree while the newly restarted gateway is serving RPCs—the same stale-artifact window this change is meant to avoid.

Useful? React with 👍 / 👎.

abnershang · 2026-06-08T02:35:16Z

@clawsweeper re-review

clawsweeper · 2026-06-08T02:35:19Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/27112834256
Updated: 2026-06-08T02:43:05.138Z

abnershang · 2026-06-08T05:30:32Z

@clawsweeper re-review

clawsweeper · 2026-06-08T05:30:34Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/27117994517
Updated: 2026-06-08T05:39:29.168Z

shakkernerd · 2026-06-11T01:19:10Z

Merged using rebase.

What changed after review:

Preserved consumed update restart sentinels so the Gateway UI can still confirm a successful handoff after startup deletes the sentinel file.
Made pending update status polling read-only so it cannot overwrite a detached updater's final ok or error sentinel.
Treated unknown managed-service roots conservatively for git updates, so wrapper-based Gateway services are stopped instead of being left running while their checkout may be mutated.

Verification:

Rebased/refreshed onto current origin/main before pushing.
Testbox-through-Crabbox tbx_01ktt3rejyxpb8vrvth2mpnzw5 / Actions run 27317044557: corepack pnpm test src/gateway/server-restart-sentinel.test.ts ui/src/ui/app-gateway.node.test.ts src/cli/update-cli.test.ts src/gateway/server-methods/update.test.ts passed, 311 tests.
Auto-review: clean, no accepted/actionable findings reported.
GitHub checks: no required checks configured/reported on the pushed head; PR was mergeable and clean at the matched head.

Landed on main:

Final landed SHA: 400b3e0; range f03e337...400b3e0.

Thanks @abnershang!

openclaw-barnacle Bot added gateway Gateway runtime size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 8, 2026

chatgpt-codex-connector Bot reviewed Jun 8, 2026

View reviewed changes

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 8, 2026

openclaw-barnacle Bot added docs Improvements or additions to documentation cli CLI command changes size: M and removed size: XS labels Jun 8, 2026

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels Jun 8, 2026

openclaw-barnacle Bot added triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. and removed proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 8, 2026

shakkernerd added 24 commits June 11, 2026 02:18

fix: refresh update status sentinel

23546a8

fix: protect managed git update service ownership

3841cf3

fix: defer git update service stop until mutation

2237a07

fix: keep gateway stopped after plugin update failure

4599315

fix: extend managed update handoff polling

41d2265

fix: resolve dev update preflight from remote main

e5fa2ab

fix: stop git service when switching install roots

a6cf332

fix: require service identity for update handoffs

bf16020

fix: resolve dev preflight manager from candidate

84441d2

fix: preserve git mode for supervised handoff

ab4c748

fix: stop package service during dev switch

8c9f9ed

fix: honor selected dev preflight fallback

8efac14

fix: preserve dev branch upstream after fallback

5cb59cc

fix: roll back failed dev upstream setup

4e0128d

fix: clean up failed dev branch fallback

ed355db

fix: constrain dev remote fallback

1b1505a

fix: verify managed git restart service

dc6f7fc

fix: continue dev preflight after manager failures

0a9ff93

fix: avoid stale cleanup for reachable gateway probes

08bae6b

fix: isolate update tests from supervisor env

49edcef

fix: fail stopped service update restart errors

4723a45

fix: preserve consumed update restart status

cb1aead

fix: keep update status polling read only

a714278

fix: stop unknown-root git services

d7b31f1

shakkernerd force-pushed the fix/supervised-git-update-handoff branch from 649bdd9 to d7b31f1 Compare June 11, 2026 01:18

shakkernerd merged commit 400b3e0 into openclaw:main Jun 11, 2026
21 checks passed

Haderach-Ram mentioned this pull request Jun 11, 2026

Ecosystem Digest — 2026-06-11 Haderach-Ram/openclaw-radar#36

Open

This was referenced Jun 27, 2026

fix(launchd): verify profile updater jobs by metadata #97264

Merged

[Bug]: Gateway update fails due to managed-service handoff timeout during self-update #99666

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: hand off supervised git updates#91296

fix: hand off supervised git updates#91296
shakkernerd merged 28 commits into
openclaw:mainfrom
abnershang:fix/supervised-git-update-handoff

abnershang commented Jun 8, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 8, 2026

Uh oh!

abnershang commented Jun 8, 2026

Uh oh!

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

abnershang commented Jun 8, 2026

Uh oh!

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

shakkernerd commented Jun 11, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		installSurface.kind === "global" \|\|
		(installSurface.kind === "git" && supervisor)

Uh oh!

Uh oh!

Conversation

abnershang commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Real behavior proof

Tests

Dependency changes

AI-assisted

Uh oh!

clawsweeper Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

abnershang commented Jun 8, 2026

Uh oh!

clawsweeper Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

abnershang commented Jun 8, 2026

Uh oh!

clawsweeper Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

shakkernerd commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

abnershang commented Jun 8, 2026 •

edited

Loading

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

shakkernerd commented Jun 11, 2026 •

edited

Loading