fix(setup): keep legacy fallback on exact stable release

[RomneyDa]

Summary

• keep the legacy setup fallback path instead of failing versionless legacy fallback configs
• map legacy Selection: "fallback" to the hardcoded current gateway version 2026.9.4 instead of the mutable extended-stable tag
• update setup policy docs and tests to reflect the explicit exact-version behavior

Testing

• git diff --check
• not run: dotnet test (dotnet is not installed in this environment)

[clawsweeper]

Codex review: blocked before merge. Reviewed September 13, 2026, 6:39 PM ET / 22:39 UTC.

ClawSweeper review

What this changes

The PR maps legacy setup fallback configurations without a version to Gateway 2026.9.4 instead of extended-stable, and updates migration documentation and tests.

Regression provenance

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

Merge readiness

⛔ Blocked before merge - 3 items remain

The change remains distinct from current main, but it unintentionally allows custom installers to inherit the product fallback version. This is a bounded repair, and the member-authored PR should remain open.

Priority: P2
Reviewed head: d369abd19ff063fd1d1e0af147464f50b92539f2

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The patch is focused, but an existing custom-installer regression contract is violated and upgrade validation remains unestablished.
Proof confidence	🌊 off-meta tidepool	Not applicable: The ordinary external-contributor proof gate does not apply to this MEMBER-authored PR. Its supplied body reports no runtime exercise of the changed setup migration; fresh-install and upgrade validation remain separate compatibility requirements.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The ordinary external-contributor proof gate does not apply to this MEMBER-authored PR. Its supplied body reports no runtime exercise of the changed setup migration; fresh-install and upgrade validation remain separate compatibility requirements.
Evidence reviewed	8 items	Introduced custom-installer regression: ResolveLegacySelection now supplies 2026.9.4 before ValidateAndApply checks custom installers. The synthesized value passes RequireExactVersion, so a custom InstallUrl with Selection=fallback and no Version is accepted. Existing regression contract: ValidateAndApply_CustomInstallerRejectsVersionlessLegacySelection includes fallback and expects InvalidPolicy. Source inspection shows that case no longer throws; tests were not executed. Installer consequence: InstallCliStep passes Gateway.Version into the installer command and later requires the installed package to equal an exact requested version. The unintended synthesized version therefore reaches installation rather than remaining a display-only value.
Findings	1 actionable finding	[P2] Preserve explicit-version validation for custom installers
Security	None	None.

How this fits together

Windows setup translates saved Gateway configuration into an installer version selection. That selection controls the package installed in WSL and the subsequent installed-version verification.

flowchart TD
 A[Saved setup configuration] --> B[Legacy selection migration]
 B --> C{Official installer?}
 C -->|Yes| D[Channel or exact version]
 C -->|No| E[Explicit exact version required]
 D --> F[Install Gateway in WSL]
 E --> F
 F --> G[Verify installed version]

Loading

Before merge

• Preserve explicit-version validation for custom installers (P2) - With a custom InstallUrl, Selection: "fallback", and no Version, this return supplies 2026.9.4 before the custom-installer check. RequireExactVersion consequently succeeds and setup invokes the custom installer with a version the operator never supplied. This contradicts the documented contract and the existing ValidateAndApply_CustomInstallerRejectsVersionlessLegacySelection fallback case. Restrict the synthesized default to official installs or validate the original custom version first.
• Resolve merge risk (P2) - Existing versionless legacy fallback configurations will switch from a moving channel to 2026.9.4; fresh-install and upgrade evidence has not established the resulting installation behavior.
• Complete next step (P2) - Restore custom-installer explicit-version validation, then record required tests and fresh-install/legacy-upgrade validation before merge.

Findings

• [P2] Preserve explicit-version validation for custom installers — src/OpenClaw.SetupEngine/GatewayInstallPolicy.cs:319-320

Agent review details

Security

None.

Review metrics

None.

Merge-risk options

Maintainer options:

1. Preserve custom-installer isolation (recommended)
   Restrict the implicit pin to official installs and validate fresh defaults, migrated fallback configurations, and explicit custom versions before landing.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Reject custom installer configurations without an explicitly supplied exact stable Gateway.Version before applying legacy defaults. Preserve the official versionless fallback mapping to 2026.9.4 and existing explicit versions. Retain the existing rejection regression and validate fresh-install and legacy-upgrade behavior.

Technical review

Best possible solution:

Apply the exact legacy fallback only to official installs, preserve explicit custom-installer versions, and verify fresh setup and legacy-config upgrades.

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

Yes, from source: a custom InstallUrl with Selection=fallback and no Version now passes validation, contradicting the existing rejection test. This introduced failure was not executed.

Is this the best way to solve the issue?

No, not as written: resolving the official fallback before checking custom-installer input weakens an established contract; validate the explicit custom version before synthesizing defaults.

Full review comments:

• [P2] Preserve explicit-version validation for custom installers — src/OpenClaw.SetupEngine/GatewayInstallPolicy.cs:319-320
  With a custom InstallUrl, Selection: "fallback", and no Version, this return supplies 2026.9.4 before the custom-installer check. RequireExactVersion consequently succeeds and setup invokes the custom installer with a version the operator never supplied. This contradicts the documented contract and the existing ValidateAndApply_CustomInstallerRejectsVersionlessLegacySelection fallback case. Restrict the synthesized default to official installs or validate the original custom version first.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against bd9ce43b4d9c.

Labels

Label changes:

• add P2: This is a bounded setup migration change with a source-proven custom-installer validation regression.
• add merge-risk: 🚨 compatibility: The patch changes legacy configuration resolution and lets custom installers inherit a product version that previously required explicit configuration.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The ordinary external-contributor proof gate does not apply to this MEMBER-authored PR. Its supplied body reports no runtime exercise of the changed setup migration; fresh-install and upgrade validation remain separate compatibility requirements.

Label justifications:

• P2: This is a bounded setup migration change with a source-proven custom-installer validation regression.
• merge-risk: 🚨 compatibility: The patch changes legacy configuration resolution and lets custom installers inherit a product version that previously required explicit configuration.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The ordinary external-contributor proof gate does not apply to this MEMBER-authored PR. Its supplied body reports no runtime exercise of the changed setup migration; fresh-install and upgrade validation remain separate compatibility requirements.

Evidence

Acceptance criteria:

• [P1] dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj --filter FullyQualifiedName~GatewayInstallPolicyTests.
• [P1] ./build.ps1.
• [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.
• [P2] Verify fresh defaults, official versionless legacy fallback, explicit legacy versions, and custom-installer rejection/preservation through the setup entrypoint.

What I checked:

• Introduced custom-installer regression: ResolveLegacySelection now supplies 2026.9.4 before ValidateAndApply checks custom installers. The synthesized value passes RequireExactVersion, so a custom InstallUrl with Selection=fallback and no Version is accepted. (src/OpenClaw.SetupEngine/GatewayInstallPolicy.cs:320, d369abd19ff0)
• Existing regression contract: ValidateAndApply_CustomInstallerRejectsVersionlessLegacySelection includes fallback and expects InvalidPolicy. Source inspection shows that case no longer throws; tests were not executed. (tests/OpenClaw.SetupEngine.Tests/GatewayInstallPolicyTests.cs:115, d369abd19ff0)
• Installer consequence: InstallCliStep passes Gateway.Version into the installer command and later requires the installed package to equal an exact requested version. The unintended synthesized version therefore reaches installation rather than remaining a display-only value. (src/OpenClaw.SetupEngine/InstallCliStep.cs:38, d369abd19ff0)
• Merged compatibility decision: GitHub confirms fix(setup): complete npm latest Gateway landing #1381 (fix(setup): complete npm latest Gateway landing) merged on 2026-09-09. Its explicit contract requires custom installers to provide their own exact stable version and forbids inheriting synthesized product versions. (61ccb91e49b8)
• Current-main necessity check: The fetched main implementation still maps versionless legacy fallback to extended-stable, so the requested exact-version migration is not already implemented there. (src/OpenClaw.SetupEngine/GatewayInstallPolicy.cs:321, bd9ce43b4d9c)
• Latest-release check: The latest release, v2026.9.3, also contains the extended-stable migration rather than this PR's exact pin. (src/OpenClaw.SetupEngine/GatewayInstallPolicy.cs:321, 84928c4370bc)

Likely related people:

• shanselman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Karen: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

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

• Preserve custom-installer rejection when no explicit version is supplied.
• Record required validation and fresh-install versus legacy-upgrade results in the repository's proof sections.

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.

[karkarl]

Global repo triage reviewed exact head d369abd19ff063fd1d1e0af147464f50b92539f2.

Decision: HOLD_FOR_AUTHOR. Take confidence: 8%. Recommendation confidence: 99%. Risk: High setup compatibility.

ResolveLegacySelection synthesizes 2026.9.4 before custom-installer validation. Consequently, a custom InstallUrl with versionless Selection: "fallback" now passes the exact-version check and receives a product-selected version that the operator never supplied. This contradicts ValidateAndApply_CustomInstallerRejectsVersionlessLegacySelection. Tray/setup CI and CI Gate fail on this head.

Restrict the implicit fallback pin to official installers, retain explicit-version requirements for custom installers, and rerun SetupEngine plus required repository validation. Fresh-install and legacy-upgrade proof should use windows-clean-installer-upgrade and windows-wsl-gateway-e2e.