Fix onboarding wizard Back desynchronization

[karkarl]

Summary

• remove the Companion-local Back action from Gateway-driven onboarding
• remove stale wizard payload history and replay
• preserve authoritative recovery through Restart onboard and Skip & exit in More options
• document why Back remains unavailable without a Gateway rewind operation
• add a tray contract test that prevents local Back replay from returning

Fixes #1172

Validation

Not verified / blocked on this host because NuGet.org fails TLS negotiation (NU1301, Authentication failed because the remote party sent a TLS alert: 'HandshakeFailure') and this fresh worktree does not contain the required restored assets or Microsoft.ML.OnnxRuntime 1.29.0 package.

Attempted:

• ./build.ps1 - blocked during Shared restore
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj - blocked during restore
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj - blocked during restore
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore --filter "FullyQualifiedName~WizardBack_IsUnavailableWithoutAuthoritativeGatewayRewind" - blocked because project.assets.json is unavailable in the fresh worktree
• git diff --check - passed before commit

Rubber-duck review found no actionable issues.

Real behavior proof

Not verified / blocked. run-app-local.ps1 -Isolated cannot build and launch the current head until the NuGet TLS/restore failure is resolved. Source-level proof in the current head removes WizardBackButton, WizardBack_Click, _stepHistory, and prior-payload replay while retaining the visible More options recovery menu with Restart onboard and Skip & exit.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 22, 2026, 5:47 AM ET / 09:47 UTC.

ClawSweeper review

What this changes

The PR removes the onboarding Back button and local payload replay, preserves restart/exit recovery in More options, documents the Gateway protocol limit, and adds a regression contract test.

Regression provenance

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

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep open. This collaborator-authored PR directly removes the source-proven client-only rewind that desynchronized the Gateway wizard session, while retaining restart and exit recovery; no blocking code defect was found.

Priority: P2
Reviewed head: 4bbadb0b14bbf128ea8c273fab8e06d901a5a42b

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is focused, source-supported, and protected by a targeted contract test; remaining confidence depends on completing normal validation.
Proof confidence	🌊 off-meta tidepool	Not applicable: The external-contributor proof gate does not apply to this collaborator PR; its body nevertheless documents a specific current-head restore blocker, and repository UI policy permits an explicit blocker.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The external-contributor proof gate does not apply to this collaborator PR; its body nevertheless documents a specific current-head restore blocker, and repository UI policy permits an explicit blocker.
Evidence reviewed	5 items	Current-main defect: The base revision stored each received payload and its Back handler re-rendered a prior payload without sending a Gateway rewind request. PR implementation: The PR removes the history stack and Back rendering/handler while continuing to render authoritative payloads and show recovery actions. Protocol boundary: The Gateway client identifies wizard.start, wizard.next, wizard.cancel, and wizard.status as its wizard RPC operations; no rewind operation is represented.
Findings	None	None.
Security	None	None.

Live Verification

Command: powershell -NoProfile -Command "$env:OPENCLAW_SETUP_PREVIEW_PAGE='wizard'; .\run-app-local.ps1 -NoBuild -Isolated -AllowNonMain"

Result: FAIL (failed) — execution before step 1 run: sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

Assertions:

• FAIL expect_output: Launching OpenClaw Tray

How this fits together

The Windows Companion renders onboarding steps supplied by the Gateway wizard and submits answers back to that same session. Recovery controls restart or exit onboarding when the protocol cannot authoritatively rewind a prior step.

flowchart LR
  A[Gateway wizard session] --> B[Authoritative step payload]
  B --> C[Windows onboarding page]
  C --> D[Answer submission]
  D --> A
  C --> E[More options recovery]
  E --> F[Restart or exit]

Loading

Before merge

• Resolve merge risk (P1) - Merging intentionally removes an existing Back affordance. The source retains restart and exit alternatives, but the contributor's environment could not provide current-head UI validation because restore was blocked.
• Complete next step (P2) - This collaborator-authored implementation has no discrete mechanical repair to queue; it needs normal review and completion of validation evidence.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch surface	4 files changed: 20 additions, 28 deletions	The change is narrowly limited to the onboarding UI, its documentation, and a regression contract.

Merge-risk options

Maintainer options:

1. Verify the replacement recovery path (recommended)
   Before merging, confirm an isolated current-head wizard shows no Back control and still permits Restart onboard and Skip & exit from More options.

Technical review

Best possible solution:

Land the removal after CI and an isolated current-head wizard check confirm that Back is absent while More options still exposes restart and exit recovery.

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

Yes. Current-main source records received Gateway payloads locally and re-renders an earlier payload on Back without a matching Gateway operation; the linked report provides the corresponding user flow.

Is this the best way to solve the issue?

Yes. Removing the unsafe local rewind is the narrowest maintainable repair because the represented Gateway wizard contract has no rewind operation and recovery actions remain available.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P2: The defect can interrupt provider or authentication onboarding but is not an emergency availability or security event.
• add merge-risk: 🚨 compatibility: The patch deliberately removes an existing onboarding navigation control and replaces its user recovery path with restart or exit.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator PR; its body nevertheless documents a specific current-head restore blocker, and repository UI policy permits an explicit blocker.

Label justifications:

• P2: The defect can interrupt provider or authentication onboarding but is not an emergency availability or security event.
• merge-risk: 🚨 compatibility: The patch deliberately removes an existing onboarding navigation control and replaces its user recovery path with restart or exit.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator PR; its body nevertheless documents a specific current-head restore blocker, and repository UI policy permits an explicit blocker.

Evidence

What I checked:

• Current-main defect: The base revision stored each received payload and its Back handler re-rendered a prior payload without sending a Gateway rewind request. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:381, ccd64bbb7d68)
• PR implementation: The PR removes the history stack and Back rendering/handler while continuing to render authoritative payloads and show recovery actions. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:379, 4bbadb0b14bb)
• Protocol boundary: The Gateway client identifies wizard.start, wizard.next, wizard.cancel, and wizard.status as its wizard RPC operations; no rewind operation is represented. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:1184, 4bbadb0b14bb)
• Recovery and regression coverage: The XAML retains Restart onboard and Skip & exit, and the added contract test asserts the old Back symbols are absent and those recovery handlers remain. (tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs:1423, 4bbadb0b14bb)
• History and release boundary: Blame attributes the existing local replay lines to the v2026.7.1 commit, while this PR commit is after the supplied current-main base and therefore is neither on main nor in that release. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:381, 4206611f2b2e)

Likely related people:

• Scott Hanselman: Current-main blame assigns the local payload history and Back handler to this release commit; deeper history is unavailable in the partial checkout. (role: recorded source-line introducer; confidence: medium; commits: 4206611f2b2e; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Let the running CI suites complete.
• When restore is available, run the required build and shared/tray tests, then capture an isolated wizard check with Back absent and recovery controls present.

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.

[TheAngryPit]

Exact-head validation for 4bbadb0b14bbf128ea8c273fab8e06d901a5a42b against base ccd64bbb7d687d9929091109c8d722ad9ba962d9 is now complete.

Validation

• Repository dependency preflight: PASS; npm lockfile matched and lifecycle scripts remained disabled.
• Supported Debug/Dev build: PASS for docs validation, Shared, Cli, WinNodeCli, SetupEngine, and WinUI.
• Focused WizardBack_IsUnavailableWithoutAuthoritativeGatewayRewind: 1 passed, 0 failed.
• Full Shared suite: 3,812 passed, 32 skipped, 0 failed.
• Full Tray suite: 2,704 passed, 0 skipped, 0 failed.
• git diff --check: PASS; exact-head checkout remained clean.
• Current GitHub checks: terminal green (13 pass, 8 intentional skips, 0 failed/pending); PR remains MERGEABLE/CLEAN at the same head/base.

Real behavior proof

The exact-head Debug/Dev executable was launched through the repository-supported, Gateway-free OPENCLAW_SETUP_PREVIEW_PAGE=wizard path with dedicated app data. The rendered WinUI window was inspected independently through Windows UI Automation; only More options was opened, and neither recovery action was invoked.

• Back: 0 before and after opening the menu
• More options: 1 visible control
• Restart onboard: 1 visible menu item
• Skip & exit: 1 visible menu item

The capture-time UIA record binds the source head/base and executable SHA-256 and passes all four assertions. The screenshot contains repository-supplied synthetic preview data only and was cropped to the app window.

The screenshot is hosted from immutable evidence commit 2d881d0a.

Artifact hashes:

• UIA JSON: 4C9DF16ACD3D7874BE98D44317E67CA7DCFF457CB10A597248215E4AB2F4FD0D
• Screenshot: DFD76A64713B367FD1D7CF1C2AB9FB74D9954F588256430432ACC666FF8E7528
• Focused TRX: 34B0680C3B3969D987B74BEAE0EE57B116FA018591C6758427038F1F05169F7C
• Shared TRX: E21EC700EB4DA5E74A220BE1CC491A0CAC5C0823006D142156A12AE4B14D3320
• Tray TRX: 0C0709C934B04E3B9035C03D175679EF51298FA8E7613E178C992F88695E710F

Cleanup was exact-PID and verified; no Gateway/WSL distro, production Companion, settings, credentials, or pairings were used or changed.

Proof boundary: runtime_proven for the exact-head Debug/Dev wizard preview layout and recovery-menu availability. This does not claim a live Gateway wizard session or downstream execution of either recovery action.

@clawsweeper re-review

[TheAngryPit]

@clawsweeper re-review

[TheAngryPit]

@karkarl The exact-head build, full test, UI Automation, and sanitized visual proof are published above and address both remaining validation items. This account has READ permission only, so ClawSweeper cannot accept our re-review command. Could you please post @clawsweeper re-review and, if the evidence looks good, mark the PR ready for review?