[RomneyDa]

What Problem This Solves

Fixes: WSL Gateway setup fails before installing the CLI because Companion requests Node 24.19.0, which the official installer no longer accepts.

User Impact

New managed WSL Gateway installations request Node 24.22.1, the current upstream installer minimum. Custom installers and existing Gateway release selection remain unchanged. This is a separate prerequisite for #1474 (feat(release): automate Microsoft Store submission), not part of the Store automation diff.

Why This Change Was Made

Update the existing GatewayInstallPolicy runtime pin. Keep exact post-install runtime verification, HTTPS download-before-execution, cleanup, and custom-installer behavior intact. Two existing command-contract assertions now independently require the supported version. The policy document records the current pin without losing its historical value.

Evidence

Reproduced in all three WSL lanes on unchanged main and Store PR CI: Node 24.19.0 is unsupported; use Node 24.22.1+ or Node 26.12.1+. Verified the official installer default/minimum and published Node 24.22.1 Linux x64/ARM64 checksums. Current head: 38355291f2f915ac0db270881b9b61b4d1538bb6. Independent Codex rubber-duck review of the supplied exact diff found no actionable issue; its filesystem tools were unavailable, so it did not independently execute tests.

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-wsl-gateway-e2e: fresh managed Gateway installation and pairing must complete with the new runtime.
• windows-wsl-mxc: strict repository setup/connect validation; no skip is counted as proof.

Validation

• Fail-before: the two revised installer command assertions failed on the old production pin (0 passed, 2 failed).
• Pass-after: the same two tests passed after the pin update (2 passed, 0 failed).
• Broader macOS filter (InstallCli, GatewayInstallPolicyTests, SetupReviewSummaryTests): 64 passed, 1 failed in the Windows candidate-copy cancellation fixture. The candidate-copy case passes in the native Windows run; macOS paths are rejected by the Windows-drive validation before the fake copy is reached.
  Native Windows 11 ARM64 isolated closeout, current source:

Command	Observed result
./build.ps1	Passed, 85.1s
dotnet test tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore	4,656 passed, 1 failed, 27 skipped
dotnet test tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore	4,467 passed, 7 failed
dotnet test tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj --no-restore	2,420 passed, 5 failed, 1 skipped
scripts/validate-docs.ps1	Passed, 64 Markdown files
scripts/validate-mxc-e2e.ps1 -NoBuild -RuntimeIdentifier win-arm64	Failed: 11 pure port tests passed, 7 setup-dependent cases failed before CLI installation because the VM registered the test distro as WSL1, not required WSL2

Fresh test projects were explicitly built before --no-restore. Shared/Tray failures are the previously observed VM symlink privilege, ARM64 prerequisite/native DLL, and redirected-known-folder cases. All five SetupEngine failures reproduced on untouched main e4d79798 in the same VM (10-case filtered control: 5 passed, 5 failed): four restart-classification message assertions and one native VC-runtime staging check. These are recorded as failures, not waived. Both revised installer contract cases and the macOS-blocked candidate-copy case passed on Windows. No assertion, timeout, or skip policy was weakened.

• git diff --check: passed.
• Current-head hosted CI: terminal SUCCESS, attempt 1, head 38355291f2f915ac0db270881b9b61b4d1538bb6. 8 successful jobs, 11 classifier/release skips, 0 failed. CI Gate passed.
• Hosted Tray: 4,474 passed; SetupEngine: 2,425 passed / 1 skipped; integration: 55 passed / 3 skipped; Dev containment: 31 passed.
• Hosted real WSL setup/connect: 43 passed / 7 skipped; network recovery: 2 passed; revocation recovery: 1 passed. All three runs explicitly log Gateway Node runtime: v24.22.1 and complete fresh setup. Hosted MXC exclusions remain exclusions, not strict containment proof.
• UI and Core/CLI lanes were excluded by the unchanged scoped classifier; the mandatory local build/Shared/Tray closeout above still ran. This does not resolve the separate UI bootstrap hang on feat(release): automate Microsoft Store submission #1474 or assert full merge readiness.

Real Behavior Proof

• Environment tested: macOS .NET 10 command-generation tests; native Windows 11 ARM64 local closeout with recorded failures; hosted Windows WSL2 setup and recovery E2Es.
• PR head or commit tested: 38355291f2f915ac0db270881b9b61b4d1538bb6 (same source as the post-change tests).
• Exact steps or command run: dotnet test tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj --filter 'FullyQualifiedName~InstallCli_BuildInstallCommand_DefaultsToInstallerLatest|FullyQualifiedName~InstallCli_BuildInstallCommand_DownloadsCompletelyBeforeExecuting'.
• Evidence after fix: both installer command forms request --node-version '24.22.1'; both assertions pass. Each hosted WSL lane logs Gateway Node runtime: v24.22.1, completes fresh setup, and passes its selected recovery/connect tests.
• Observed result: the official installer accepts the selected runtime, exact post-install verification succeeds, and real Gateway setup/pairing/recovery completes. Existing transfer, custom-installer, and runtime-verification safeguards remain intact.
• Screenshot or artifact links verified? N/A, no UI changed.
• Not verified or blocked: local strict MXC proof remains blocked at WSL2 provisioning, before the changed CLI installer step; hosted skips do not satisfy that custom proof. No current-head ClawSweeper verdict is claimed. No existing Gateway, package, or user profile was upgraded.

Security Impact

• New permissions or capabilities? No.
• Secrets or tokens handling changed? No.
• New or changed network calls? Existing official installer downloads the newer Node archive.
• Command or tool execution surface changed? Runtime version argument only.
• Data access scope changed? No.
• Risk and mitigation: retains upstream archive verification and exact post-install version checks; does not weaken the installer minimum or change custom-installer handling.

Compatibility and Migration

• Backward compatible? Yes for setup configuration and Gateway version selection.
• Config or environment changes? Newly installed managed WSL gateways use Node 24.22.1.
• Migration needed? No automatic migration of running gateways.
• Upgrade steps: use the normal setup/retry flow for a failed installation. No Store-submission or packaging policy change.

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.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

ClawSweeper review ended

ClawSweeper stopped reviewing this revision because the pull request closed.

View the workflow run.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: fix(setup): install a Node runtime supported by the Gateway This is item 1/1 in the current shard. Shard 0/1.

This temporary status tracks the active review worker. The completed review will appear in the durable ClawSweeper review comment.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.