refactor(tray): add guardrails and remove duplicate App code

[shanselman]

Summary

• Add AGENTS.md guardrails for App/ConnectionPage god-file refactors so future agent work names ownership boundaries and invariants.
• Remove the stale duplicate WSL keepalive helper cluster from App.xaml.cs; startup still composes WslGatewayKeepAliveService.
• Add source contract coverage proving App only wires the keepalive service and the service remains the owner of cleanup/distro-resolution behavior.
• Add scripts/setup-dev.ps1 so developers and agents can install/verify local Windows prerequisites with winget, trust the checkout for GitVersion, and optionally run full validation.
• Document the setup script in README/DEVELOPMENT/AGENTS and fix build.ps1 Windows SDK version detection when only one SDK is installed.

Refs #554.

Validation

• ./scripts/setup-dev.ps1 -CheckOnly passed.
• ./build.ps1 passed.
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore passed.
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore passed.

Live gateway smoke was not run because the gateway is not available on this machine.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 27, 2026, 5:18 AM ET / 09:18 UTC.

Summary
The branch removes duplicate WSL keepalive helpers from App.xaml.cs, adds App/ConnectionPage refactor guardrails and contract coverage, adds a winget-backed Windows setup script with docs, and tightens Windows SDK detection.

Reproducibility: yes. for the source cleanup: current main still has duplicate WSL keepalive helpers in App.xaml.cs while startup already uses WslGatewayKeepAliveService. This is a source-level cleanup reproduction, not a runtime bug reproduction.

Review metrics: 2 noteworthy metrics.

• Changed surface: 7 files, +365/-235. The PR mixes source cleanup, contract tests, docs, build prerequisite detection, and a new executable setup script.
• Executable setup surface: 1 PowerShell script added, 274 lines. The new script installs prerequisites and can modify global git safe.directory, so real behavior proof matters beyond normal CI.

Root-cause cluster
Relationship: partial_overlap
Canonical: #554
Summary: This PR is a narrow cleanup under the broader App/ConnectionPage god-file refactor tracker; it does not close the remaining tracker work.

Members:

• canonical: P1: App.xaml.cs (4204 lines) and ConnectionPage.xaml.cs (2840 lines) are unmaintainable god files #554 - The issue is the open broad tracker for staged App/ConnectionPage decomposition, and its latest plan names this PR as the first cleanup step.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted terminal output, logs, screenshot, recording, or linked artifact from current PR head showing scripts/setup-dev.ps1 -CheckOnly or -RunValidation on Windows.
• [P1] Add runtime proof or redacted logs showing tray startup still schedules the WSL keepalive service, or explicitly document the focused blocker if a gateway-capable host is unavailable.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists commands as passed but includes no copied terminal output, redacted logs, screenshots, recordings, or linked artifacts; the contributor should add redacted current-head proof and update the PR body so ClawSweeper can re-review automatically, or ask a maintainer to comment @clawsweeper re-review if it does not.

Risk before merge

• [P1] The new setup script becomes a documented agent/developer setup path and can install packages or add a global git safe.directory entry; code review and CI do not prove that path works correctly on a real Windows host.
• [P1] The PR body reports validation as passed but does not provide current-head terminal output, logs, screenshots, recordings, or linked artifacts for the setup script or tray startup keepalive path.

Maintainer options:

1. Require current-head setup proof (recommended)
   Ask the contributor to add redacted terminal output or logs from the current PR head showing the setup script check or validation path and the relevant tray startup keepalive behavior before merge.
2. Accept manual-script review risk
   Maintainers may choose to merge based on code review and CI alone because the setup script is manually invoked, while owning the risk that local Windows setup behavior was not proven here.
3. Split setup automation out
   If maintainers want the keepalive cleanup without new setup automation risk, split the script/docs into a separate PR and land only the source cleanup and contract test here.

Next step before merge

• [P1] Contributor proof and normal maintainer review are the remaining actions; there is no narrow code defect for automated repair.

Security
Cleared: No concrete security or supply-chain regression was found; the new setup script is manually invoked, uses exact winget IDs, and documents its scoped git safe.directory behavior.

Review details

Best possible solution:

Merge after redacted current-head real behavior proof is attached for the setup script and keepalive startup seam, while keeping the broader App/ConnectionPage decomposition tracker open.

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

Yes for the source cleanup: current main still has duplicate WSL keepalive helpers in App.xaml.cs while startup already uses WslGatewayKeepAliveService. This is a source-level cleanup reproduction, not a runtime bug reproduction.

Is this the best way to solve the issue?

Yes for the code shape: deleting the unused App copy and protecting the ownership boundary with a contract test is the narrowest maintainable cleanup. Merge readiness still depends on real behavior proof from a real setup.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add merge-risk: 🚨 automation: The diff adds and documents a setup/validation automation path whose Windows runtime behavior is not proven by the PR body or CI alone.

Label justifications:

• P3: This is low-risk cleanup and developer setup ergonomics, not an active user-facing regression, crash, data-loss, or security emergency.
• merge-risk: 🚨 automation: The diff adds and documents a setup/validation automation path whose Windows runtime behavior is not proven by the PR body or CI alone.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists commands as passed but includes no copied terminal output, redacted logs, screenshots, recordings, or linked artifacts; the contributor should add redacted current-head proof and update the PR body so ClawSweeper can re-review automatically, or ask a maintainer to comment @clawsweeper re-review if it does not.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its tray/setup proof requirements apply because the PR touches App startup, agent-facing instructions, and a developer setup script. (AGENTS.md:45, 1fb28ee19072)
• Proof skill read: The openclaw-proof-validation skill requires current-head real behavior proof or an explicit blocker for setup/tray-sensitive PRs. (.agents/skills/openclaw-proof-validation/SKILL.md:1, 1fb28ee19072)
• Current main still has the cleanup target: Current main starts WslGatewayKeepAliveService in App startup while also retaining the old private TryEnsureLocalGatewayKeepAliveAsync helper cluster later in App.xaml.cs. (src/OpenClaw.Tray.WinUI/App.xaml.cs:693, 1fb28ee19072)
• PR head preserves the service startup seam: At PR head, App.xaml.cs still constructs WslGatewayKeepAliveService and schedules TryEnsureAsync before InitializeGatewayClient. (src/OpenClaw.Tray.WinUI/App.xaml.cs:693, 7fe6e715bb91)
• PR head adds ownership contract coverage: The new contract test asserts App wires the keepalive service, duplicate helper names are absent from App sources, and the dedicated service owns cleanup/distro-resolution behavior. (tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs:44, 7fe6e715bb91)
• New executable setup surface: The added setup script can install prerequisites with winget, refresh PATH, add the checkout to global git safe.directory, and optionally run validation. (scripts/setup-dev.ps1:114, 7fe6e715bb91)

Likely related people:

• AlexAlves87: The merged WSL keepalive extraction PR moved the App helper cluster into WslGatewayKeepAliveService and provided runtime proof for that original ownership transfer. (role: introduced service extraction; confidence: high; commits: 7d9bcf7fac40; files: src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Tray.WinUI/Services/WslGatewayKeepAliveService.cs)
• Andy Ye: Current-main blame attributes the WSL keepalive service, App startup service call, and duplicate helper cluster to commit 4ae4625 in the checked-out history. (role: current-main area contributor; confidence: high; commits: 4ae4625b9fc4; files: src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Tray.WinUI/Services/WslGatewayKeepAliveService.cs, tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs)
• shanselman: Prior merged history touched AppRefactorContractTests and nearby tray/source-contract coverage, and this contributor also authored the current branch. (role: adjacent refactor and setup contributor; confidence: high; commits: cd02defd9942; files: tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs)
• TheAngryPit: Recent merged build.ps1 work changed Windows host/prerequisite detection, which is adjacent to this PR's Windows SDK detection and setup-script surface. (role: recent build-script contributor; confidence: medium; commits: 4337fe742586, 7a7f39df2397; files: build.ps1)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.