Bug: onboarding Back rewinds Companion UI but not Gateway wizard session

[TheAngryPit]

Summary

The Windows Companion onboarding wizard exposes a Back action, but it only rewinds a client-local payload history. The active Gateway wizard session is not rewound because the Companion does not send a corresponding rewind operation.

This can leave the Companion showing an earlier question while the Gateway still expects a later answer. Submitting the displayed step again can cause repeated steps, stale-session errors, connection loss, or a full wizard restart.

Steps to reproduce

1. Start the Windows Companion local-gateway onboarding wizard.
2. Complete at least one answer so the wizard advances to a second step.
3. Press Back.
4. Observe that the previous question is rendered again.
5. Submit an answer for the displayed question.

Expected behaviour

Back should either:

• rewind the authoritative Gateway wizard session and restore the previous step; or
• be unavailable if the current wizard protocol cannot safely rewind.

The UI and Gateway must never disagree about the active step.

Actual behaviour

The Companion pops and re-renders a client-local payload history entry, but does not send a corresponding rewind operation to the Gateway wizard session.

This is visible in WizardPage.xaml.cs: the page pushes payloads into _stepHistory before rendering (ApplyPayloadAsync), while WizardBack_Click only pops and re-applies a previous payload. The current Core wizard RPC contract documents wizard.start, wizard.next, wizard.cancel, and wizard.status; there is no wizard.back operation.

Why this matters

The user can be shown a step that the Gateway no longer considers current. A subsequent answer can therefore be rejected as stale, repeat the flow, or force recovery to start the wizard again. This is particularly disruptive during provider or authentication setup.

Related issues

• Related to #841, which covers losing the wizard connection across a Gateway restart. This issue is narrower: it covers the client-local Back implementation and the missing authoritative rewind.
• Distinct from #688, which covered the installer having no Back button at all.

Environment

• Gateway: OpenClaw 2026.8.1
• Control UI commit observed: 9f5776e071d1
• Release channel: Dev
• Gateway mode: local WSL gateway
• Windows Companion: installed build/source commit 5924d491 (local build; not claimed as an upstream release)

Evidence and proof gap

The source-level mismatch is confirmed. A runtime repro with the real Back action should additionally capture the sessionId and stepId before and after Back, plus the Gateway response when the displayed earlier step is submitted. No Tailscale cause is claimed here.

Proposed direction

Choose one authoritative design:

1. add a supported Gateway-side rewind operation and use it from the Companion; or
2. remove/disable Back for steps that cannot be rewound and preserve only safe recovery actions.

The Companion should not silently render stale protocol state as if it were current.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 17, 2026, 9:11 PM ET / August 18, 2026, 01:11 UTC.

Summary
Keep open. Current main still re-renders a previous local payload on Back without a Gateway request, which can desynchronize the displayed onboarding step from the authoritative session.

Reproducibility: yes. source reproducible: current main renders Back by replaying a prior payload without a Gateway response. A live Gateway run remains needed as PR proof.

Next step
Current source proves a local replay path that violates the gateway-owned wizard contract; one focused onboarding repair can remove it.

Review details

Best possible solution:

Replace local payload replay with a gateway-authoritative Back only when the current payload advertises a supported back option; otherwise keep Back unavailable and retain restart/skip recovery.

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

Yes, source reproducible: current main renders Back by replaying a prior payload without a Gateway response. A live Gateway run remains needed as PR proof.

Is this the best way to solve the issue?

Yes. Using a server-advertised Back transition, with no local replay fallback, is the narrowest maintainable repair.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A real Gateway run must confirm the exact server-advertised __back semantics before landing a client action that submits it.

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

Label changes

Label changes:

• add P2: The defect can disrupt provider or authentication onboarding, but in-product restart and skip recovery remain available.
• add impact:session-state: The rendered client step can disagree with the authoritative Gateway wizard session.
• add impact:ux-friction: A visible Back action can lead users into a stale-step error instead of a safe recovery path.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: The defect can disrupt provider or authentication onboarding, but in-product restart and skip recovery remain available.
• impact:session-state: The rendered client step can disagree with the authoritative Gateway wizard session.
• impact:ux-friction: A visible Back action can lead users into a stale-step error instead of a safe recovery path.

Evidence reviewed

Acceptance criteria:

• ./build.ps1
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore
• Focused onboarding test covering Back behavior
• Current-head local WSL Gateway proof showing the Gateway session and rendered step remain aligned after Back

What I checked:

• Current local replay path: Current main stores each payload locally, then the Back handler pops and reapplies a prior payload without sending any Gateway request. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:769, f8a8825ccbb4)
• Gateway owns wizard progression: The onboarding documentation says the gateway controls server-defined steps through wizard.start and wizard.next, while the client only offers generic request transport. (docs/ONBOARDING_WIZARD.md:39, f8a8825ccbb4)
• Existing authoritative-back signal is discarded: The page recognizes __back/back option values but filters them from selectable options, while independently showing the local Back button. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:641, f8a8825ccbb4)
• Feature provenance: Blame ties the local Back implementation to the page baseline in v2026.7.1; the page has no diff between that release commit and current main. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:769, 4206611f2b2e)
• Release and current-main check: The introduction commit is contained in v2026.7.1, and current main remains at a later commit with the same affected page behavior. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:769, f8a8825ccbb4)

Likely related people:

• Barbara Kudiess: Recent history includes the richer Gateway wizard protocol work in this page. (role: recent onboarding protocol contributor; confidence: medium; commits: 84d2e6ab80c8; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)
• Scott Hanselman: Blame attributes the current local Back implementation and page baseline to the v2026.7.1 commit. (role: current-line provenance contributor; confidence: medium; commits: 4206611f2b2e; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml)

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.