fix(setup): retry guarded restart after reload owner handoff

[karkarl]

Summary

Related to #1498. This is a user-authorized, focused extraction from a6190ba0935d20c97ecaf69bdc4f0871ebb63589 in #1447 (feat(setup): guide native Gateway installation and onboarding), based directly on main 273b0182745a3093c0e09f306ca8a1fff6ef3c5a. It does not include the native onboarding feature history. #1447 and its branch are unchanged. Do not close #1498: restart-intent coordinator contention remains unresolved.

After reload-mode restoration, SetupWizardRunner.RestoreReloadModeAsync recognizes only the exact diagnostic:

GATEWAY_RESTART_PREPARATION_REFUSED: Cannot verify a live serving Gateway owner for the selected service. Gateway was not signaled.

It reuses VerifyExpectedManagedGatewayAsync, then makes one recovery call to the same guarded Gateway CLI restart. The existing provenance wait allows up to 30 one-second retry delays, plus probe duration, for NoListener or UnknownListener specifically tagged ListenerSnapshotChanged. Other unknown/conflicting listeners, other restart errors, and repeated refusal fail closed.

There is no direct systemd restart fallback, lock deletion, arbitrary signaling, silent downgrade, or ownership bypass. SetupWizardRunner remains the orchestration owner; the existing provenance policy and upstream Gateway admission retain their responsibilities. Listener provenance is not proof of owner-lease or coordinator readiness.

A reload-triggered supervisor transition is a possible timing explanation, not an established cause of every refusal. Local diagnostics captured activating/auto-restart with no MainPID; hosted generic refusals captured an active/running unit and live PID. The public Gateway CLI does not expose the rejected owner-lease predicate, and these snapshots do not establish it.

Extraction provenance and deviations

Current head: 2a685afc057411d695f7093c9b9c0bf3a8a7b923. Original extraction: 77b7e4bb295e2c32df587c17e4e1a35ab0a2f428. The follow-up changes only docs/SETUP_ENGINE_REDESIGN.md; production code and tests are unchanged.

• Production recovery: all 18 added lines are unchanged from a6190ba0.
• Tests: retain all 88 original restart-test lines and add one explicit negative case for StateDatabaseCoordinatorContentionError / restart-intent-recording refusal. Seven restart regression cases passed.
• Documentation: retain the setup-restart paragraph, adapt main-only context, clarify the snapshot-change exception, probe-duration budget, provenance limits, and untreated contention. The review follow-up replaces the asserted absent lease with a possible timing explanation and differing observed service states.
• Exclude all 40 unrelated native-package lines in docs/TEST_COVERAGE.md and native onboarding context from the setup-document conflict.
• Do not duplicate fixture-isolation changes in E2ESetupFixture.cs, SetupAndConnectTestsUninstallIsolation.cs, or AppRefactorContractTests.cs: they are already on main through fb8b9e736f7473705ea14d8e97f6117bcbaddf68.

Required proof pools

• windows-wsl-gateway-e2e: post-wizard managed Gateway restart and setup recovery. Local strict fixture at 77b7e4bb exercised the changed recovery on official Gateway 2026.9.6; runtime code is unchanged at current head.
• windows-wsl-mxc: required strict gateway setup/connect closeout, including real Gateway -> Windows node -> system.run containment. All 17 tests passed without skips at 77b7e4bb.

No new UI surface, node capability, or MCP command contract is introduced.

Validation

Documentation-only follow-up 2a685afc: .\scripts\validate-docs.ps1 passed, checking 50 Markdown files, both proof-pool schema paths, and documentation-flow regression. git diff --check passed. Build/unit/runtime suites were not rerun for this documentation-only change; the results below belong to 77b7e4bb, not a new-head execution.

Extraction 77b7e4bb: local Windows ARM64, build 26694. OPENCLAW_REPO_ROOT pointed to this worktree; tray data and runtime TEMP/TMP were task-owned and isolated. $proof denotes the session-owned results directory. Fresh-worktree tests intentionally allowed restore rather than risking a --no-restore no-op.

Command	Result at 77b7e4bb
.\build.ps1	Passed all five targets: Shared, Cli, WinNodeCli, SetupEngine, WinUI
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --logger "trx;LogFileName=Shared.trx" --results-directory $proof	4,106 passed, 33 skipped, 0 failed
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --logger "trx;LogFileName=Tray.trx" --results-directory $proof	3,072 passed, 0 skipped, 0 failed
dotnet test .\tests\OpenClaw.SetupEngine.Tests\OpenClaw.SetupEngine.Tests.csproj --logger "trx;LogFileName=SetupEngine.trx" --results-directory $proof	1,200 passed, 1 skipped, 0 failed; all 7 focused restart cases executed
$env:OPENCLAW_E2E_GATEWAY_VERSION='2026.9.6'; pwsh -NoProfile -File .\scripts\validate-mxc-e2e.ps1 -NoBuild -ResultsDirectory "$proof\mxc-results"	17 passed, 0 skipped, 0 failed, exit 0. -NoBuild reused the full ARM64 app build; the script rebuilt the E2E project. No -AllowSkip.
git diff --cached --check before extraction commit	Passed

Real behavior proof

Strict local fixture at 77b7e4bb; production code and tests are identical at current head:

• Official Gateway 2026.9.6 selected; the classified recovery warning occurred exactly once: Gateway restart owner was unavailable after restoring reload. Rechecking managed ownership before one restart retry.
• Setup completed, the isolated tray connected through its MCP fixture, and all strict tests passed. Required proofs include MirroredWslSafeGatewayPort_IsListeningAndRecorded, RealGateway_SystemRun_ExecutesThroughWindowsNodeMxcSandbox, and RealGateway_SystemRun_BlocksWritesToTrayDataDirectoryInMxcSandbox.
• No typed coordinator-contention marker occurred. This proves the exercised serving-owner recovery, not a remedy for coordinator contention or every historical owner refusal.
• Fixture uninstall exited 0 and teardown completed. The task distro was verified unregistered and both fixture data directories absent. No existing user distro/profile, MSIX registration, auth terminal, or autostart entry was used for proof.
• Only allowlisted counts, diagnostic categories, version, test names, and cleanup outcomes are published. No raw runtime logs, configurations, environments, command lines, tokens, or identity data are attached.

Historical original-source evidence

Run 36055236206 at original a6190ba0 exercised the classified retry once in each Gateway 2026.9.6 shard: setup/connect 40 passed and 6 MXC skips, revocation 1 passed, network 2 passed. SetupEngine was 1,353 passed / 1 skipped; Tray was 3,097 passed. Overall run failed: Shared had 4,167 passed, 2 failed, 1 skipped. Failures: BoundedProcessWaitTests.WaitAsync_CancellationDoesNotWaitForInheritedPipeHandles (3,053 ms against a <3-second limit) and PiperVoiceExtractionTests.ExtractTarBz2Async_CancellationIsBoundedAndKillsExtractor (extractor still running). They are not attributed to #1498 or declared harmless flakes. These are not extracted-head validation results.

Review and remaining gates

Author intent: ready for maintainer reassessment, consistent with GitHub's non-draft state. This is not merge approval or authorization for an agent to merge.

• Scott's review explicitly accepts one repeat through the normal guarded CLI after the exact serving-owner refusal and managed-endpoint recheck, with owner/intent admission on both attempts and other refusals, especially typed contention, failing closed. This is a policy disposition, not merge approval.
• Adversarial/triage review found no significant code defect and requested the same documentation correction and readiness alignment. Both are addressed by 2a685afc and this PR-body update; no retry policy was broadened.
• Required rubber-duck review completed with no blocking findings. Nonblocking follow-ups: stdout-only future refusal diagnostics and retention of the first diagnostic if provenance re-verification fails. Runtime proof exercised the current classifier, and an untrusted listener still fails closed.
• Structured autoreview attempted with python .agents\skills\autoreview\scripts\autoreview --mode local --prompt <focused-extraction-context> --output <session-report> --json-output <session-json>. Not verified / blocked: its secret-like-content guard rejected expanded diff context before the model ran. The scanner was not bypassed or weakened. This is not a clean autoreview result; the limitation remains visible for maintainer disposition rather than claiming a draft state that GitHub no longer has.
• Preserve the security-sensitive review requirement and the issue's clawsweeper:no-new-fix-pr label. The separate focused PR was explicitly user-authorized, not an automated repair.
• StateDatabaseCoordinatorContentionError / approximately 5,011 ms state-lifecycle admission failure occurs before owner resolution. It remains a separate, untreated intent-recording failure.
• The old-owner-still-listening / successor-readiness timing case remains unproven. Provenance cannot establish full upstream readiness; a repeated guarded refusal still fails setup. No broader retry policy is proposed.

[clawsweeper]

Codex review: needs changes before merge. Reviewed September 25, 2026, 11:30 AM ET / 15:30 UTC (Revision 5).

ClawSweeper review

What this changes

After WSL setup restores Gateway reload mode, the branch adds one guarded restart retry for a specific serving-owner refusal, with regression tests and setup documentation.

Regression provenance

Possible regression — suspected (reviewed change; failure trace). No predecessor PR is attributed.

Merge readiness

⛔ Needs changes before merge - 1 item remains

The revised documentation resolves the earlier finding, and the guarded retry remains a distinct, useful fix absent from current main. The reviewed path has no concrete correctness finding; this collaborator PR remains open for the requested security review.

Priority: P0
Reviewed head: 2a685afc057411d695f7093c9b9c0bf3a8a7b923

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	The narrow patch has focused negative coverage and credible real Gateway recovery proof, with the requested security review still a landing gate.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): At the extraction commit, an isolated Windows ARM64 WSL fixture with official Gateway 2026.9.6 observed the classified refusal once, completed setup through the guarded retry, and passed 17 strict Gateway/MXC tests without skips. Production and test blobs are identical at the current documentation-only head. No stored-data contract changes.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): At the extraction commit, an isolated Windows ARM64 WSL fixture with official Gateway 2026.9.6 observed the classified refusal once, completed setup through the guarded retry, and passed 17 strict Gateway/MXC tests without skips. Production and test blobs are identical at the current documentation-only head. No stored-data contract changes.
Evidence reviewed	11 items	Current main still has one restart attempt: The pinned main implementation returns the first restart failure without the proposed recovery branch. Introduced retry remains guarded: The retry requires the specific diagnostic and a successful managed-endpoint check, then calls the existing Gateway restart path once more. Provenance wait fails closed: Only no listener and the typed listener-snapshot race receive bounded delays; conflicting or otherwise unknown ownership returns immediately.
Findings	None	None.
Security	None	None.

How this fits together

The Setup Engine runs the WSL Gateway wizard, restores its reload setting, and asks the Gateway CLI to restart the service. Listener provenance and Gateway admission checks determine whether setup can continue to health verification.

flowchart LR
A[WSL setup wizard] --> B[Restore reload mode]
B --> C[Guarded Gateway restart]
C --> D{Serving owner refused?}
D -->|Yes| E[Check managed listener]
E -->|Trusted| F[One guarded retry]
E -->|Untrusted| H[Setup fails]
D -->|No| G[Health and ownership check]
F --> G

Loading

Before merge

• Complete next step (P2) - Complete the requested security review of the guarded restart retry before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Source and coverage delta	production +18, tests +89, docs +19	Production growth is limited to the guarded retry and has focused failure-path coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1498
Summary: This PR addresses the generic serving-owner refusal subset of the open setup issue; the issue's distinct coordinator-contention failure remains.

Members:

• canonical: Gateway 2026.9.6 blocks WSL setup at guarded post-wizard restart #1498 - It records the setup failure and separates serving-owner refusal from restart-intent contention.
• partial_overlap: feat(setup): guide native Gateway installation and onboarding #1447 - Its larger native-onboarding branch contains the recovery from which this focused PR was extracted.
• adjacent_distinct: fix(setup): retry guarded restart intent contention #1507 - It adds pre-rollback diagnostics for the same setup failure but does not implement retry recovery.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Land the bounded recovery after the requested security review, and track restart-intent coordinator contention separately in #1498 without weakening Gateway admission.

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

Yes: an isolated official Gateway 2026.9.6 fixture observed the specific first-attempt refusal, and current main still has the single-attempt path. I did not run a fresh current-main reproduction.

Is this the best way to solve the issue?

Yes: the retry is limited to one classified refusal, checks the managed listener again, and invokes the existing guarded CLI path. Coordinator contention remains a separate failure.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 273b0182745a.

Labels

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P0: The guarded restart refusal can block first-time WSL setup after the wizard, leaving the user without a completed installation.
• merge-risk: 🚨 security-boundary: The PR permits one additional authority-bearing restart attempt; the accepted design retains endpoint verification and upstream owner and intent admission.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): At the extraction commit, an isolated Windows ARM64 WSL fixture with official Gateway 2026.9.6 observed the classified refusal once, completed setup through the guarded retry, and passed 17 strict Gateway/MXC tests without skips. Production and test blobs are identical at the current documentation-only head. No stored-data contract changes.
• proof: sufficient: Contributor real behavior proof is sufficient. At the extraction commit, an isolated Windows ARM64 WSL fixture with official Gateway 2026.9.6 observed the classified refusal once, completed setup through the guarded retry, and passed 17 strict Gateway/MXC tests without skips. Production and test blobs are identical at the current documentation-only head. No stored-data contract changes.

Evidence

What I checked:

• Current main still has one restart attempt: The pinned main implementation returns the first restart failure without the proposed recovery branch. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:614, 273b0182745a)
• Introduced retry remains guarded: The retry requires the specific diagnostic and a successful managed-endpoint check, then calls the existing Gateway restart path once more. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:619, 2a685afc0574)
• Provenance wait fails closed: Only no listener and the typed listener-snapshot race receive bounded delays; conflicting or otherwise unknown ownership returns immediately. (src/OpenClaw.SetupEngine/GatewayWizardRestartRecoveryPolicy.cs:106, 2a685afc0574)
• Gateway CLI contract applies: The PR invokes the upstream Gateway CLI; Gateway 2026.9.6 awaits restart-intent preparation before service.restart. (src/cli/daemon-cli/lifecycle-core.ts:655, eb377ac59e6c)
• Upstream admission checks the selected owner: Intent preparation checks a live supervised owner and selected service identity before recording restart intent; intent-recording failure remains a distinct refusal. (src/infra/restart-intent.ts:289, eb377ac59e6c)
• Focused positive and negative cases: Added cases cover recovery, untrusted listeners, repeated refusal, unrelated errors, and coordinator contention without a second attempt. (tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs:4269, 2a685afc0574)

Likely related people:

• shanselman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• karkarl: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• SebTardif: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (4 earlier review cycles)

• reviewed 2026-09-25T00:40:15.087Z sha 77b7e4b :: blocked before merge. :: none
• reviewed 2026-09-25T00:45:08.837Z sha 77b7e4b :: blocked before merge. :: [P2] Describe the owner-lease gap as a hypothesis
• reviewed 2026-09-25T05:33:56.299Z sha 77b7e4b :: needs changes before merge. :: [P2] Qualify the unobserved owner-lease explanation
• reviewed 2026-09-25T15:26:11.235Z sha 2a685af :: needs maintainer review before merge. :: none

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[shanselman]

Hi Karen, Copilot here. Thanks for extracting this narrow recovery and for the current-head official Gateway 2026.9.6 proof: the changed warning appeared once, the guarded CLI retry completed setup, and strict Gateway/MXC ran 17 passed, 0 skipped. The separate StateDatabaseCoordinatorContentionError remains correctly outside this retry; the endpoint check is not being treated as proof of the upstream owner lease.

One concrete wording fix before readiness: docs/SETUP_ENGINE_REDESIGN.md says the live-owner lease is absent during a reload-triggered systemd restart. That causal predicate has not been observed. Our local #1498 diagnostic captured activating/auto-restart with no MainPID, while hosted generic refusals captured an active/running unit and live PID; the public Gateway CLI does not expose the rejected lease predicate. Please phrase reload-induced owner handoff as a possible timing explanation, not the established cause, and keep the distinction from intent-recording contention. For example: “Gateway 2026.9.6 may refuse the guarded restart when it cannot verify a live serving owner; the rejected lease predicate is not exposed. A reload-triggered supervisor transition is one possible explanation, but observed service states differ.”

Scott explicitly accepts one repeat through the normal guarded Gateway CLI after the exact serving-owner refusal and managed-endpoint recheck, provided both attempts keep Gateway owner/intent admission and other refusals (especially typed contention) fail closed. This is a policy disposition, not merge approval: your PR body currently says “Draft pending” / “No merge is authorized,” although GitHub marks the PR non-draft. Do you intend #1515 to remain a draft while you finish the documentation/review, or is it ready for a maintainer to reassess once those are aligned? I stopped without committing or pushing any changes.

Local supplemental check, not new-head proof: the full ARM64 build passed. One Shared-suite run failed the unrelated intermittent MCP disposal test; its exact focused rerun passed. I did not call the full required floor green or waive it after stopping at your draft/no-merge wording.

[karkarl]

Global triage: HOLD_FOR_AUTHOR. Take confidence 65%; recommendation confidence 98%; effort extra-small; risk medium.

The production retry remains narrowly bounded and guarded, and current-head proof is strong: build, Shared, Tray, SetupEngine, strict Gateway setup, and windows-wsl-mxc all passed, including 17 MXC tests with no skips. No significant code defect was found.

One documentation finding remains. docs/SETUP_ENGINE_REDESIGN.md states that the live-owner lease is absent, but the observed diagnostics do not expose that rejected lease predicate and showed differing service states. Describe reload-induced owner handoff as a possible timing explanation rather than an established cause.

Also reconcile the PR body's draft/no-merge wording with GitHub's non-draft ready state before maintainer reassessment. This is a policy and author-intent hold, not a request to broaden the accepted one-retry behavior. Restart-intent coordinator contention correctly remains outside this fix.

[karkarl]

Addressed both reviews in 2a685af. The setup documentation now describes a reload-triggered supervisor transition as a possible timing explanation, records the differing local/hosted service snapshots, and states that neither exposes the rejected admission-time owner-lease predicate. Production recovery and tests are unchanged; typed restart-intent coordinator contention remains outside the retry.

Author intent is ready for maintainer reassessment, consistent with the existing non-draft state. The PR body no longer says Draft pending. Scott's acceptance of the single guarded repeat is recorded as a policy disposition, not merge approval; no agent merge is authorized. The structured-autoreview scanner limitation and security-sensitive review requirement remain explicit.

Documentation validation passed (50 Markdown files, both proof-pool schema paths, and documentation-flow regression), as did git diff --check. Build/unit/runtime results remain attributed to 77b7e4b; they were not rerun or relabeled as new-head proof for this documentation-only follow-up.

[karkarl]

@clawsweeper re-review

Please reassess current head 2a685af. Scott's and the adversarial review's documentation correction and readiness-wording requests are addressed. The guarded retry implementation is unchanged; coordinator contention remains outside scope. Documentation validation passed, and prior runtime proof remains explicitly attributed to 77b7e4b. Review only; no autofix or automerge requested.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/36154838450
• Updated: 2026-09-25T15:32:35.593Z

[bkudiess]

Security-review disposition for head 2a685af: the focused AI-assisted source review found no actionable security vulnerabilities. The retry remains limited to the specific serving-owner refusal, rechecks managed endpoint ownership, and invokes the same guarded Gateway CLI without an ownership bypass. Repeated refusal still fails setup. This is not a claim of independent live WSL security testing or formal security-team certification.

The documentation concern is resolved. The user has explicitly authorized merging this reviewed head. The separate coordinator-contention failure remains tracked in #1498 and is not resolved by this PR.