fix(setup): recover uninitialized WSL automatically

[karkarl]

Summary

• recognize the Windows optional-component-required WSL states during both replacement inspection and setup preflight
• route those states through the existing elevated wsl.exe --install --no-distribution recovery step instead of stopping at the Welcome page with a manual wsl --list --quiet instruction
• re-inspect WSL after recovery and report a required Windows restart when initialization is still pending
• preserve the fail-closed path for unknown inspection failures and the existing hardware-virtualization diagnostics

Validation

• ./build.ps1: PASS, Shared, CLI, WinNode CLI, SetupEngine, and WinUI built successfully; 46 Markdown files validated
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore: PASS, 3,812 passed, 32 skipped, 0 failed
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore: PASS, 2,703 passed, 0 failed
• dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj --no-restore: PASS, 956 passed, 0 failed
• git diff --check: PASS
• Rubber-duck review: PASS, no blocking or material findings; the suggested nonzero-exit virtualization regression coverage was added

Real behavior proof

• Current head: a9ad12cc
• Production-path tests prove that an uninitialized optional component is treated as recoverable, the installer is invoked exactly once, readiness is re-inspected, installed WSL is not mutated, UAC cancellation is surfaced, and a still-pending platform returns an explicit reboot requirement.
• The validation host reports WSL 2.9.3.0 ready with existing app-owned distributions, so destructive live proof requiring WSL removal or Windows optional-component disablement was not performed. That would disrupt the host and require a reboot.
• Not verified / blocked: a screenshot of the real missing-WSL UAC and reboot flow on this host. The exact diagnostic and recovery transitions are covered by the focused SetupEngine tests above.

Scope

This change is limited to missing or uninitialized WSL recovery. It does not change Local AI qualification or hardware-virtualization readiness behavior.

[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:41 PM ET / 23:41 UTC.

ClawSweeper review

What this changes

The PR recognizes uninitialized WSL optional-component errors during setup and existing-install inspection, then invokes the existing elevated installer and rechecks readiness.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open for normal collaborator and maintainer review. The narrow change routes recognized uninitialized-WSL diagnostics into the existing recovery step, preserves fail-closed handling for unknown failures, and has focused coverage for ready, recovery, reboot, and cancellation paths; no blocking defect was found.

Priority: P0
Reviewed head: a9ad12cc6c9fdbf9d9d9a4f7bcb1b672f8f86e22

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, well-covered repair with no concrete review finding; live destructive-state proof remains intentionally unavailable on the validation host.
Proof confidence	🌊 off-meta tidepool	Not applicable: The external-contributor proof gate does not apply to this collaborator PR; its body nevertheless documents focused after-change tests and the safe blocker for a destructive UAC/reboot scenario.
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 focused after-change tests and the safe blocker for a destructive UAC/reboot scenario.
Evidence reviewed	7 items	Uninitialized-platform classification: The patch classifies the documented optional-component-required signatures as installable before general environment and unknown-failure handling. Existing installer and reinspection path: The existing ensure step only invokes its installer for an installable state, then reinspects and returns an explicit reboot result when the optional component remains pending. Focused regression coverage: Added tests model recognized status output, a successful reinspection, the restart-required path, elevation cancellation, and replacement inspection without treating unknown failures as safe.
Findings	None	None.
Security	None	None.

How this fits together

The Windows onboarding pipeline checks WSL before it downloads Local AI or creates OpenClaw's managed WSL gateway. Its viability result determines whether setup proceeds, stops with diagnostics, or runs the existing elevated WSL-platform recovery step.

flowchart TD
A[User starts local setup] --> B[Inspect existing WSL gateway]
B --> C[Check WSL version and status]
C --> D{Platform ready?}
D -->|Yes| E[Continue setup]
D -->|Known uninitialized state| F[Elevated WSL platform install]
F --> G[Reinspect WSL readiness]
G -->|Ready| E
G -->|Restart required| H[Show reboot recovery]

Loading

Before merge

• Resolve merge risk (P1) - The exact missing-optional-component UAC and reboot path was not run live because reproducing it would alter Windows features and require a restart; focused tests cover the modeled transitions, and the remaining CI checks should complete before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch scope	3 files affected: 1 implementation, 1 test, 1 documentation	The implementation remains confined to the existing WSL viability and recovery seam.
Code and test delta	implementation +28/-3, tests +163/-2	The recovery classification is accompanied by materially broader scenario coverage.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Land the focused recovery after the pending checks finish, retaining the known-signature allowlist, post-install reinspection, and terminal reboot guidance.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Land the focused recovery after the pending checks finish, retaining the known-signature allowlist, post-install reinspection, and terminal reboot guidance.

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

Yes, at source level: a nonzero wsl --status containing the optional-component-required signatures now follows a deterministic installable path, and focused tests cover recovery, reboot, and cancellation. The destructive Windows state was not recreated live.

Is this the best way to solve the issue?

Yes. Reusing the existing elevated installer and viability seam is narrower and safer than adding a parallel setup path, while preserving terminal handling for unknown diagnostics.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P0: The fixed path blocks first-time local setup until a non-technical user performs a technical WSL recovery, while this PR supplies an in-product recovery route.
• 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 focused after-change tests and the safe blocker for a destructive UAC/reboot scenario.

Label justifications:

• P0: The fixed path blocks first-time local setup until a non-technical user performs a technical WSL recovery, while this PR supplies an in-product recovery route.
• 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 focused after-change tests and the safe blocker for a destructive UAC/reboot scenario.

Evidence

What I checked:

• Uninitialized-platform classification: The patch classifies the documented optional-component-required signatures as installable before general environment and unknown-failure handling. (src/OpenClaw.SetupEngine/PreflightWslStep.cs:118, a9ad12cc6c9f)
• Existing installer and reinspection path: The existing ensure step only invokes its installer for an installable state, then reinspects and returns an explicit reboot result when the optional component remains pending. (src/OpenClaw.SetupEngine/PreflightWslStep.cs:304, a9ad12cc6c9f)
• Focused regression coverage: Added tests model recognized status output, a successful reinspection, the restart-required path, elevation cancellation, and replacement inspection without treating unknown failures as safe. (tests/OpenClaw.SetupEngine.Tests/SetupStepsTests.cs:1306, a9ad12cc6c9f)
• Current-main comparison: The branch differs from current main by 28 implementation additions and 3 removals, plus focused tests and one onboarding-documentation update, so this fix is not already implemented on main. (src/OpenClaw.SetupEngine/PreflightWslStep.cs:118, a9ad12cc6c9f)
• Pipeline placement: The current pipeline runs WSL preflight and platform preparation before Local AI downloads and managed-distro creation. (src/OpenClaw.SetupEngine/SetupPipeline.cs:54, ccd64bbb7d68)
• Contributor validation and proof disclosure: The PR body reports the required build, Shared, Tray, and SetupEngine test runs, and explicitly states that a destructive missing-WSL/UAC/reboot live run was blocked to avoid disabling the host component.

Likely related people:

• Joel: The accessible current-main commit for managed local-AI work is the immediate provenance available for the WSL preparation pipeline; deeper file history is unavailable in this partial checkout. (role: recent area contributor; confidence: low; commits: ccd64bbb7d68; files: src/OpenClaw.SetupEngine/SetupPipeline.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.