Wizard architecture redesign — survive gateway restarts

[samanthamsong]

Epic: «Local gateway is the golden path for the Windows companion app» (#834)
Backlog Doc ID: #17 · Priority: P1 · Area: setup & onboarding

Description
Onboarding breaks because of wizard design: when the gateway restarts, it drops the wizard's connection. Likely a gateway-protocol issue on the OpenClaw side.

Definition of done
The onboarding wizard reconnects cleanly across a gateway restart without dead-ends.

Part of the «Local gateway is the golden path for the Windows companion app» tracking issue (#834).

[clawsweeper]

Thanks for the context here. I did a careful shell check against current main, and this is already implemented.

Current main already addresses the restart-lost wizard session path: the merged setup wizard protocol work reconnects/restarts wizard sessions after restart-like disconnects, and the WinUI wizard now exposes recovery actions instead of leaving users in a dead-end. This is current-main-only and is not in the latest v0.6.3 release.

I found the merged PR that appears to have closed this: #824: Make setup wizard resilient to richer gateway protocol steps.

So I’m closing this as already implemented rather than keeping a duplicate issue open.

Review details

Best possible solution:

Keep the current-main implementation; if maintainers later want exact-step resume after a gateway restart, track that as a narrower gateway protocol enhancement.

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

Yes, source-level: restart-like disconnects in the headless runner now trigger reconnect/replay, and interactive disconnects route to visible recovery. I did not run a live Windows gateway restart in this read-only cleanup review.

Is this the best way to solve the issue?

Yes. The current implementation is the maintainable fix for the no-dead-end requirement: it reconnects the setup runner and exposes retry/restart/skip recovery in the UI while acknowledging that gateway restart clears exact wizard session position.

Security review:

Security review: No patch is under review for this issue.

AGENTS.md: found and applied where relevant.

What I checked:

• Repository policy read: AGENTS.md was read fully; its connection/onboarding guidance directed the review through the connection, setup, and onboarding wizard surfaces. (AGENTS.md:31, 1c377cb64b65)
• Headless setup reconnect behavior: Current SetupWizardRunner catches restart-like wizard disconnects, reconnects the gateway client, clears replay-scoped session state, and calls wizard.start again. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:96, 1c377cb64b65)
• Interactive lost-connection recovery: Current WizardPage turns active wizard client disconnect/error status into a selectable error state rather than leaving the wizard stuck. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:159, 1c377cb64b65)
• Interactive retry and restart controls: Current WizardPage error handling enables Start wizard again / Skip wizard, and app-managed WSL recovery can restart the gateway and re-enter the gateway config wizard. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:870, c81f6f2f93df)
• Documented expected behavior: The onboarding wizard docs now say gateway restarts or lost wizard connections present recovery choices so the user is not trapped, and app-managed WSL gateway restart resumes at the first config question. (docs/ONBOARDING_WIZARD.md:39, 1c377cb64b65)
• Fix provenance: Blame ties the restart-reconnect/replay implementation in SetupWizardRunner to merged commit 84d2e6a. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:96, 84d2e6ab80c8)

Likely related people:

• bkudiess: Authored the merged setup wizard resilience commit and the adjacent app-managed WSL gateway dependency-recovery commit used by the restart/retry path. (role: recent area contributor; confidence: high; commits: 84d2e6ab80c8, 1e6951331f1c; files: src/OpenClaw.SetupEngine/SetupWizardRunner.cs, src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, docs/ONBOARDING_WIZARD.md)
• ranjeshj: Merged earlier wizard recovery actions and out-of-process SetupEngine redesign work in the same setup/onboarding area. (role: earlier wizard recovery contributor; confidence: medium; commits: 9d304c110c0f, 623427cead04, cefce3952ab1; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/SetupWizardRunner.cs, docs/ONBOARDING_WIZARD.md)
• Christine Yan: Recent history touches the install wizard page in the same rendering/protocol-adjacent area shortly before the restart/protocol hardening work. (role: recent adjacent contributor; confidence: medium; commits: 992da748c31b, 85445c78066b; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/SetupWizardRunner.cs)

Codex review notes: model internal, reasoning high; reviewed against 1c377cb64b65; fix evidence: merged PR #824, commit 84d2e6ab80c8, main fix timestamp 2026-06-25T19:57:44-07:00.