fix(setup): gate Local AI on WSL readiness

[karkarl]

Summary

• enforce the read-only WSL readiness gate before the Capabilities page can present Local AI choices
• keep WSL2 virtualization failures classified and displayed as WSL readiness failures
• preserve the engine gate for Local AI and non-Local-AI local gateway setup before any Local AI acquisition
• remove WSL platform failures from Local AI availability aggregation

Adapted from the ordering intent in joelagnel#4 for the post-#1178 setup architecture.

Validation

• dotnet test .\tests\OpenClaw.SetupEngine.Tests\OpenClaw.SetupEngine.Tests.csproj --no-restore - passed, 948/948
• .\build.ps1 - passed, all projects including WinUI
• dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore - passed, 3,812 passed and 32 skipped
• dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore - passed, 2,704/2,704
• git diff --check - passed

Real behavior proof

Current-head automated proof covers the unavailable-host path with synthetic wsl --status output:

• PreflightWsl_FailsTerminalWhenVirtualizationDisabledInFirmware proves the result is EnvironmentBlocked, begins with Windows cannot currently start WSL2., contains virtualization remediation, and contains no Local AI copy.
• PreflightWsl_VirtualizationFailureBlocksWhenLocalAiIsDisabled proves the WSL gate remains terminal when Local AI is disabled.
• SetupWelcome_BlocksOnWslReadinessBeforeLocalAiDecisionUi proves Welcome checks WSL, stops on a blocking result, and only then permits existing-config inspection and navigation to Capabilities. The Local AI hardware hint is also gated behind WSL readiness.
• BuildDefaultSteps_IncludesCurrentSetupFlow and SetupProgress_PreparesWslBeforeLocalAiDownloads prove WSL preflight/platform readiness precede the runtime and model download stages.

Live disabled-virtualization UI proof is Not verified / blocked. This Windows ARM64 host reports healthy WSL 2.9.3 with a running WSL2 configuration. Disabling firmware virtualization is unavailable and unsafe for the validation host, so the blocking dialog cannot be exercised without changing host firmware state.

Rubber-duck review

Completed with no blocking findings. The one actionable observation was a stale contract-test name implying Capabilities still aggregated WSL failures; the test was renamed and strengthened to assert that WslViability is absent from Capabilities.

[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 21, 2026, 7:49 PM ET / 23:49 UTC.

ClawSweeper review

What this changes

The branch makes WSL readiness a Welcome-page prerequisite for local gateway setup and keeps Local AI availability messaging limited to hardware and networking conditions.

Merge readiness

✅ Ready for maintainer review

Keep open. This active collaborator PR fixes a current-main setup ordering gap by stopping blocked WSL environments before the capability and Local AI decision UI.

Priority: P2
Reviewed head: dcf0e3af17c74d0fd66ddd3be5ba7a72e35617c8

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is focused, preserves the pipeline safety check, and adds targeted coverage for the intended failure and ordering paths.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator PR documents the unavailable firmware-state blocker and supplies focused current-head synthetic coverage; no external-contributor proof action is required.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator PR documents the unavailable firmware-state blocker and supplies focused current-head synthetic coverage; no external-contributor proof action is required.
Evidence reviewed	5 items	Current-main gap and branch gate: Current main gathers WSL viability while initializing the Capabilities page; the branch instead checks it in Welcome before existing-config inspection and navigation to Capabilities. Failure classification remains fail-closed: The shared WSL inspector classifies firmware and platform failures as EnvironmentBlocked or InspectionFailed, both of which block setup and provide remediation text. Focused regression coverage: The branch adds coverage for virtualization-disabled terminal failure, Local-AI-disabled behavior, pipeline ordering, and the Welcome-page ordering contract.
Findings	None	None.
Security	None	None.

Live Verification

Command: .\run-app-local.ps1 -NoBuild -AllowNonMain -Isolated

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
• FAIL expect_output: Started OpenClaw Tray

How this fits together

The Windows onboarding wizard takes users from a local-gateway choice through capabilities and then the setup pipeline. WSL readiness determines whether local setup may proceed, while the capability page collects choices and the pipeline performs the installation.

flowchart LR
A[User selects local gateway] --> B[Welcome screen]
B --> C[Read-only WSL readiness]
C -->|Blocked| D[WSL remediation dialog]
C -->|Ready or installable| E[Capabilities and Local AI choices]
E --> F[Setup pipeline]
F --> G[WSL platform and local gateway]
F --> H[Optional Local AI download]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and regression coverage	production +30/-36, tests +77/-20	The focused production reorder is accompanied by substantially more targeted regression coverage across the setup engine and tray contract tests.

Technical review

Best possible solution:

Keep WSL readiness as the shared early gate for local setup while retaining the pipeline's later platform verification before installation or Local AI acquisition.

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

No live disabled-virtualization path is safely available on the stated healthy host. The failing ordering and the blocked-Windows classification are high-confidence source-reproducible through the changed Welcome flow and synthetic WSL command tests.

Is this the best way to solve the issue?

Yes. Moving the read-only readiness check to Welcome prevents capability presentation before the prerequisite is known, without removing the pipeline's authoritative WSL verification.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P2: This is a bounded onboarding correctness repair with a limited but meaningful impact on local gateway setup.
• 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 collaborator PR documents the unavailable firmware-state blocker and supplies focused current-head synthetic coverage; no external-contributor proof action is required.

Label justifications:

• P2: This is a bounded onboarding correctness repair with a limited but meaningful impact on local gateway setup.
• 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 collaborator PR documents the unavailable firmware-state blocker and supplies focused current-head synthetic coverage; no external-contributor proof action is required.

Evidence

What I checked:

• Current-main gap and branch gate: Current main gathers WSL viability while initializing the Capabilities page; the branch instead checks it in Welcome before existing-config inspection and navigation to Capabilities. (src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml.cs:162, dcf0e3af17c7)
• Failure classification remains fail-closed: The shared WSL inspector classifies firmware and platform failures as EnvironmentBlocked or InspectionFailed, both of which block setup and provide remediation text. (src/OpenClaw.SetupEngine/PreflightWslStep.cs:118, dcf0e3af17c7)
• Focused regression coverage: The branch adds coverage for virtualization-disabled terminal failure, Local-AI-disabled behavior, pipeline ordering, and the Welcome-page ordering contract. (tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs:1840, dcf0e3af17c7)
• Feature provenance: Current main's Local AI setup surface was merged by the feature commit that names the merged Local AI PR, making its author the strongest current-main routing candidate. (src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs:269, ccd64bbb7d68)
• Current-main and release status: The exact branch diff is against current main ccd64bb; the PR head is not present on main or in the supplied latest release v2026.7.1. (src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml.cs:162, dcf0e3af17c7)

Likely related people:

• joelagnel: The current-main Local AI setup implementation was introduced by the merged feature commit, which is the direct feature-history predecessor for this ordering repair. (role: merged feature author; confidence: high; commits: ccd64bbb7d68; files: src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs, src/OpenClaw.SetupEngine/PreflightWslStep.cs)

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.