Make setup wizard resilient to richer gateway protocol steps

[bkudiess]

Summary

• Make the gateway setup wizard handle progress/status and action-style protocol steps without getting stuck.
• Share step classification, URL/code formatting, and auth-aware timeout logic between headless setup and the WinUI wizard.
• Preserve raw option values for unknown choice-style steps and harden gateway restart replay.

Fix details

• Progress and non-interactive steps now acknowledge the current step with sessionId + answer.stepId, matching the gateway wizard.next contract.
• Added WizardNextPayload plus regression tests showing that session-only polling repeats the current step, while acknowledgement advances it.
• Progress polling remains bounded by per-step and aggregate caps.

Behavioral proof

I ran the branch locally through setup and the real gateway wizard. The machine's WSL online Ubuntu install path returned TRUST_E_BAD_DIGEST, so the proof run used a temporary uncommitted local-rootfs override to get past WSL distro creation. No rootfs override changes are included in this PR.

Observed live wizard flow:

OpenClaw setup
Config handling
QuickStart
Model/auth provider
Default model
Model check
How channels work
Select channel (QuickStart)
Web search
Search provider
Skills status
Configure skills now? (recommended)
Hooks
Enable hooks?
Grant permissions

Representative live UI/log evidence:

Docs: https://docs.openclaw.ai/channels/pairing
Live gateway output
Updated config: ~/.openclaw/openclaw.json
Workspace OK: ~/.openclaw/workspace
Sessions OK: ~/.openclaw/agents/main/sessions

[WS] hello-ok ... methods include wizard.start, wizard.next, wizard.cancel, wizard.status
step.completed: verify-e2e -> Success
Pipeline completed successfully in 166.2s

Screenshots captured locally for review artifacts:

openclaw-live-wizard-first-step.png
openclaw-live-wizard-after-config-handling.png
openclaw-live-wizard-after-channel-info.png
openclaw-live-wizard-after-channel-skip.png
openclaw-live-wizard-after-search-skip.png
openclaw-live-wizard-after-hooks-skip.png
openclaw-live-final-permissions.png

Focused protocol harness

A local harness also verified the protocol helper behavior directly:

classify progress: Progress
progress continues without answer: True
classify action without options: NonInteractive
action without options continues: True
classify action with options: RequiresAnswer
url line kind: Url
url highlight: https://example.test/device
code line kind: Code
code highlight: WDJB-MJHT
auth timeout: 300000
ordinary timeout: 30000
unknown-with-options wire kind: Number
unknown-with-options wire value: 42

Protocol/source proof

Checked against upstream OpenClaw gateway/macOS sources:

• packages/gateway-protocol/src/schema/wizard.ts defines progress and action, options[].value as Unknown, initialValue as Unknown, and optional sensitive / executor.
• src/wizard/session.ts exposes the runtime step union and uses unknown option values.
• apps/macos/Sources/OpenClaw/OnboardingWizard.swift consumes the same wizard start/next model and preserves selected option values through AnyCodable.

Validation

• ./build.ps1 — all projects passed.
• dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj — 331 passed.
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj — 1163 passed.
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-build — 2422 passed / 29 skipped on rerun.

Notes

• The wizard protocol is forward-only; this PR does not add a back-step operation.
• The temporary local-rootfs setup override used for proof is not part of this PR.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 25, 2026, 7:52 PM ET / 23:52 UTC.

Summary
The PR changes the setup wizard runner and WinUI wizard page to classify richer gateway steps, acknowledge non-answer steps, share URL/code formatting and timeouts, and add SetupEngine regression tests.

Reproducibility: yes. source-level: current docs and upstream protocol include richer wizard step shapes, while current main handles only the older forward step set and the gateway requires an answer envelope to clear currentStep. I did not run live Windows setup in this read-only review.

Review metrics: 3 noteworthy metrics.

• Changed setup callers: 2 production callers changed. Both headless setup and the WinUI wizard now share the richer wizard-step behavior.
• Changed surface: 10 files, +762/-151. The diff is broad enough that setup-state and proof review matter before merge.
• Focused tests added: 4 test files added. New unit coverage targets the classifier, acknowledgement envelope, formatting, and timeout helpers that carry the protocol change.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• none.

Mantis proof suggestion
A visible Windows setup wizard pass would materially help maintainers verify progression through gateway progress/action steps. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify the Windows setup wizard advances through gateway progress/action steps to the permissions page without looping.

Risk before merge

• [P1] A mismatch with live gateway progress/action semantics could loop or block first-run setup because both headless and WinUI callers now rely on acknowledgement envelopes to advance non-answer steps.
• [P1] Restart replay resets counters and restarts the gateway wizard session after a gateway disconnect; maintainers should confirm that is acceptable for partially completed setup choices.

Maintainer options:

1. Accept With Setup-Focused Review (recommended)
   Maintainers can land after confirming the final head's acknowledgement, polling, and restart replay behavior match the live gateway setup contract.
2. Ask For One More Live Progress Proof
   If maintainers want lower risk, ask for a short log or recording showing a live progress/action repeat advancing through the answer-envelope path after the force-push.

Next step before merge

• No automated repair is queued; the remaining action is maintainer review of setup session-state and availability risk before merge.

Security
Cleared: The diff changes C# setup wizard parsing, rendering, timeout, polling, and tests; no concrete security or supply-chain regression was found.

Review details

Best possible solution:

Land the shared wizard-protocol handling once maintainers accept the session-state and availability risk, while keeping Back-navigation semantics tracked separately.

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

Yes, source-level: current docs and upstream protocol include richer wizard step shapes, while current main handles only the older forward step set and the gateway requires an answer envelope to clear currentStep. I did not run live Windows setup in this read-only review.

Is this the best way to solve the issue?

Yes. Sharing classification, answer shaping, message formatting, and auth-aware timeouts across both setup callers is the narrow maintainable fix for this protocol-resilience gap.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This is a normal-priority setup wizard resilience fix with first-run setup impact but no emergency signal.
• merge-risk: 🚨 session-state: The PR changes wizard session advancement, acknowledgement envelopes, progress counters, and restart replay state.
• merge-risk: 🚨 availability: A bad wizard progression path could loop or block first-run setup on richer gateway steps.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): The PR body includes live setup states and logs reaching permissions plus focused protocol-harness output for the changed wizard handling.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes live setup states and logs reaching permissions plus focused protocol-harness output for the changed wizard handling.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its setup-validation and onboarding guidance are relevant, but this review was read-only so build/tests were not rerun locally. (AGENTS.md:1, ee8fc930a606)
• Current docs define affected wizard surface: Current main documents gateway-driven setup through wizard.start / wizard.next and includes Progress as a supported wizard step type. (docs/ONBOARDING_WIZARD.md:29, ee8fc930a606)
• Current main does not contain the new shared helpers: The classifier, acknowledgement payload, timeout, and message-formatting helper files added by this PR are absent from current main. (src/OpenClaw.SetupEngine/WizardStepClassifier.cs, ee8fc930a606)
• Current main baseline uses older session-only no-answer handling: The current headless setup runner sends only sessionId when there is no explicit answer, which is the path this PR replaces for progress and non-interactive steps. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:147, ee8fc930a606)
• Feature history provenance: Blame ties the current setup runner and WinUI wizard baseline around the older wizard.next handling to commit 06ed71f. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:147, 06ed71f3c01f)
• PR head acknowledges progress in headless setup: The PR head classifies progress steps, bounds polling, and sends WizardNextPayload.Acknowledge(sessionId, stepId) before continuing. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:171, ca697b5a446e)

Likely related people:

• Régis Brid: Current-main blame ties the original headless setup runner and much of the WinUI wizard implementation to this commit. (role: setup wizard baseline contributor; confidence: high; commits: 06ed71f3c01f; files: src/OpenClaw.SetupEngine/SetupWizardRunner.cs, src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)
• bkudiess: Current main includes recent WSL gateway dependency-recovery work by this contributor in the same WizardPage and onboarding docs, beyond this PR alone. (role: recent adjacent wizard contributor; confidence: high; commits: 1e6951331f1c; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, docs/ONBOARDING_WIZARD.md)
• Christine Yan: Recent merged install-wizard work touched WizardPage rendering adjacent to this PR's URL/code display changes. (role: recent area contributor; confidence: medium; commits: 992da748c31b; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)

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.

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞🧹
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.

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞🧹
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.