feat: guide Windows onboarding from setup to native AI tasks

[bkudiess]

What Problem This Solves

Windows onboarding needs a coherent native path from Gateway connection and PC access choices to a verified AI and a useful first task.

User Impact

Users can configure a Gateway, choose PC access, connect an AI provider, and finish in native Chat, Channels, or Skills. Talk to my agent is Recommended. Provider authorization uses one focused dialog without duplicated device-code text.

Why This Change Was Made

This combines native onboarding, Local AI/connection recovery, verified destination handoff, and supporting artwork/accessibility. Superseded permission-preview and browser-completion paths are removed. Credential identity, concurrent persistence, cancellation, startup preferences, and restart recovery are guarded and regression-tested.

Draft: final hosted CI and current-head live proof are still in progress. Main was merged and conflicts resolved while retaining its Store/Inno migration safeguards. No remaining integration defect was found by either independent reviewer.

Evidence

• Independent Opus and GPT reviews drove scoped fixes and source verification. Both final identity-lock and main-integration recurrence checks were clean.
• A real Windows Sandbox probe found a missing-task CLR/COM exception mismatch; the fix was added and verified against the real guest Task Scheduler.
• An isolated product-CLI run installed Gateway 2026.9.6, paired the test profile, and verified proof/proof-ok through the real Gateway with a synthetic local provider (670 ms). No real provider credentials were used.
• The first canonical MXC attempt failed during common Gateway setup, before containment assertions, due to a Gateway SQLite coordinator/restart-intent refusal. An unchanged fresh-resource retry is in progress; no skip or safety guard was bypassed.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Required proof pools

• windows-winui-interactive: native onboarding, authorization, accessibility, destinations, and startup/restart recovery.
• windows-wsl-gateway-e2e: WSL setup, pairing, persistence/recovery, and verified completion.
• windows-wsl-mxc: applicable setup/connect and containment E2E proof. Not yet passed for this head.

Validation

Current head: ee5afb5e0eb8073e59fcc68fc5e6be284be7665c, resolved tree 6a9628330d094fb0258eb8a4d4172b708715d90f. This exact source tree passed validation before the merge commit was created; source content did not change during publication.

Command / scope	Result
.\build.ps1	Passed
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore	4,145 passed, 33 skipped
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore	3,330 passed
dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj --no-restore	1,162 passed, 1 skipped
dotnet test .\tests\OpenClaw.SetupEngine.Tests\OpenClaw.SetupEngine.Tests.csproj --no-restore	1,719 passed, 1 skipped; all 395 SetupSteps cases executed
Focused WinUI framework selection	23 passed; not a full UI-suite/pixel-proof claim
Migration integration contracts	44 passed within the full Tray run
Staged/unstaged diff checks	Passed
.\scripts\validate-mxc-e2e.ps1 -NoBuild -ResultsDirectory <isolated results>	First run: 11 passed, 7 failed at shared setup prerequisite; fresh retry pending

All tests used isolated roots. Earlier disposal/timing flakes and stale metadata failures were retained; final full local closeout passed after recovery. Hosted CI is pending and is not represented by local counts.

Real Behavior Proof

• Environment tested: Windows Sandbox for disposable guest UI/startup; uniquely named WSL distro and isolated profile for real Gateway proof.
• PR head or commit tested: latest merged tree proof is in progress. The completed Gateway run used e4d0cd1; the completed missing-task fix probe maps to a62ec5d1. These are explicitly prior-head evidence, not full proof of ee5afb5e.
• Exact steps or command run: actual SetupEngine.Program.Main provisioning with a pinned Gateway, followed by product GatewayAiSetupClient discovery/verification; finite guest Task Scheduler enable/preserve/disable probe; framework UI tests and separately labeled full-frame/UIAutomation captures.
• Evidence after fix: signing identity and exact session bound successfully; guest startup transitioned Absent -> ExpectedEnabled -> preserved -> Absent, and the owned task/Run value were removed.
• Observed result: those bounded runs passed; protected profiles, existing Gateways/distros, default distro and global WSL settings remained unchanged. The failed canonical MXC fixture also cleaned up its own resources.
• Screenshot or artifact links verified? N/A (no final-head media uploaded yet).
• Not verified or blocked: final-head native completion into all three pages, complete interactive/pixel proof, MXC containment, installer/ARM64/Linux execution. Guest English OCR installation failed (0x80072EE6); separate full-frame/UIAutomation evidence is not counted as an OCR-harness pass. Canonical MXC setup currently encountered StateDatabaseCoordinatorContentionError while recording Gateway restart intent; the ownership guard was not bypassed.

Security Impact

• New permissions or capabilities? No new node capability permission; existing opt-in choices are exposed.
• Secrets or tokens handling changed? Yes
• New or changed network calls? Yes
• Command or tool execution surface changed? Yes, setup/validation orchestration; no new node command.
• Data access scope changed? Yes, reviewed settings patches and profile-local identity/receipt coordination.
• Risk and mitigation: temporary validation preserves signing-key continuity; automatic stronger-credential fallback requires typed rejection and endpoint admission. Completion binds the actual accepted local signing identity, Gateway endpoint, session, agent and model. Receipts expire and are leased. Persistence writers coordinate comparison/replacement and surface conflicts. Isolated instances cannot claim OS startup registration. Live-proof gaps remain open above.

Compatibility and Migration

• Backward compatible? Existing Gateway/Settings and classic recovery routes remain. Experimental ai-v2 browser handles and incomplete development receipts fail visibly rather than being trusted.
• Config or environment changes? Internal setup/isolation contracts were extended; no required user environment change.
• Migration needed? No manual onboarding migration. Main's Store/Inno migration safeguards are preserved. Existing numeric native destination values are retained.

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

This PR will remain draft until remaining validation/proof gates are completed or a maintainer explicitly accepts the documented limitations.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

ClawSweeper review blocked

Automated review did not run, so no review verdict was produced.

Reason: The input-safety check rejected material in this revision. No detected value, path, or scanner output is reproduced here.

Automatic review is on hold, including after source changes. Request a fresh re-review after resolving the failure; maintainers can also release the hold through an intentional scanner-policy update.

Next step: If this is a genuine credential, remove and rotate it. If it is an intentional test fixture, a maintainer must review and qualify it.

View the workflow run.