WSL integration reliability + orchestration

[samanthamsong]

Epic: «Connect & pair reliably — local and remote» (#835)
Backlog Doc ID: #29 · Priority: P2 · Area: pairing & connectivity

Description
Improve WSL reliability and orchestration. When connected it's reliable, but we need to find where it fails.

Definition of done
Known WSL failure points identified and fixed; reconnect is reliable. Related: #667.

Part of the «Connect & pair reliably — local and remote» tracking issue (#835).

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 1, 2026, 12:40 PM ET / 16:40 UTC.

Summary
Keep open. Current main now has bounded automatic recovery for setup-managed local WSL gateways, including reconnect and WSL restart safeguards, but this collaborator-authored planning item still lacks an agreed topology matrix and acceptance criteria for its broader orchestration goal.

Reproducibility: not applicable. as a single bug reproduction. The issue is a broad planning request and provides no current failing WSL topology, command sequence, expected result, or observed result to validate.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Maintainer decision needed

Question	Recommendation
Which WSL gateway topologies and recovery guarantees should this planning item own beyond the current app-managed local WSL auto-repair path?	Scope to managed local WSL recovery: Define success for the app-managed local WSL gateway path, use the current repair and E2E coverage as its baseline, and create focused follow-ups only for demonstrated gaps.

Why: Current main already implements a safe, narrow local recovery mechanism, but expanding it to remote, SSH, relay, credential, or pairing scenarios changes product behavior and safety boundaries that source inspection cannot choose.

Next step
A maintainer must choose the supported WSL scenarios and observable reconnect criteria before this broad planning item can be safely split into implementation work.

Review details

Best possible solution:

Define the supported WSL topology matrix and reconnect success criteria, retain the current bounded local-Windows repair path as the baseline, then split any remaining confirmed scenario into focused source and E2E work.

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

Not applicable as a single bug reproduction. The issue is a broad planning request and provides no current failing WSL topology, command sequence, expected result, or observed result to validate.

Is this the best way to solve the issue?

No. Current main already supplies a narrow repair for app-managed local WSL gateways, but the requested broader orchestration work needs a maintainer-defined topology and acceptance boundary before it can be the best solution.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Current recovery deliberately covers only app-owned setup-managed local WSL gateways. It excludes remote gateways, SSH tunnels, and authentication, pairing, TLS, scope, rate-limit, and token-drift failures, so closing this broader item would overstate the implemented coverage.
• The issue does not state which WSL distributions, relay modes, local versus remote topologies, or observable reconnect guarantees are in scope, so a new implementation task could duplicate existing recovery work or widen repair behavior unsafely.

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

Label changes

Label changes:

• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• remove clawsweeper:fix-shape-clear: Current issue advisory state no longer selects this label.
• remove clawsweeper:needs-info: Current issue advisory state no longer selects this label.
• remove issue-rating: 🦪 silver shellfish: Current issue advisory state no longer selects this label.

Label justifications:

• P2: This is a normal-priority reliability planning item with meaningful but not currently demonstrated urgent user impact.
• impact:other: The concrete subject is WSL gateway orchestration and recovery, which does not yet establish a narrower confirmed impact class.

Evidence reviewed

What I checked:

• Current local-Windows recovery implementation: The monitor watches only setup-managed local WSL records, waits for a sustained transport failure, and delegates repair rather than maintaining a parallel reconnect loop. (src/OpenClaw.Tray.WinUI/Services/ManagedLocalGatewayAutoRepairMonitor.cs:11, bc210e048aa9)
• Recovery protects user intent and gateway ownership: The coordinator binds repair to the active managed local record, aborts on explicit disconnect or gateway changes, probes before restart, and uses a bounded restart budget. (src/OpenClaw.Tray.WinUI/Services/ManagedLocalGatewayRepairCoordinator.cs:174, 8ac00c5f4977)
• Current tests cover bounded repair paths: Tray tests cover transport recovery, user disconnect, gateway switches, authentication exclusions, port ownership, restart budgets, and reconnect verification; the E2E recovery suite exercises gateway restart and ready-state recovery. (tests/OpenClaw.Tray.Tests/ManagedLocalGatewayRepairCoordinatorTests.cs:120, 8ac00c5f4977)
• Architecture assigns this recovery boundary: The architecture ledger names the monitor and coordinator as the authoritative owners for managed-local repair and keeps repair implementation out of the application composition root. (docs/ARCHITECTURE.md:123, 8ac00c5f4977)
• Fix provenance: Commit bc210e048aa9b84a41b521a00541851bafc8b778 introduced managed-local gateway recovery after listener or token drift, including bounded managed-WSL repair and reconnect verification. (src/OpenClaw.Tray.WinUI/Services/ManagedLocalGatewayAutoRepairMonitor.cs:30, bc210e048aa9)
• Release provenance: The recovery commit is on current main but is not contained in release v0.6.12, whose tagged commit predates it. This is current-main-only coverage. (bc210e048aa9)

Likely related people:

• Barbara Kudiess: Introduced the current managed-local WSL recovery implementation and related listener/token-drift safeguards on current main. (role: recent recovery feature owner; confidence: high; commits: bc210e048aa9, f51a8618ed7b; files: src/OpenClaw.Tray.WinUI/Services/ManagedLocalGatewayAutoRepairMonitor.cs, src/OpenClaw.Tray.WinUI/Services/ManagedLocalGatewayRepairCoordinator.cs)
• Caleb Eden: Recent current-main history includes work keeping WSL operations inside the app-owned setup directory, adjacent to the supported local-Windows topology. (role: recent WSL setup contributor; confidence: medium; commits: d0fca93d5f61; files: src/OpenClaw.SetupEngine/SetupSteps.cs)
• Scott Hanselman: The managed-local recovery provenance records Scott Hanselman as a co-author, and the repository release and connection-history trail places him close to this area. (role: co-author and adjacent connection-history contributor; confidence: medium; commits: bc210e048aa9, 15ed439dc5a3; files: docs/ARCHITECTURE.md, src/OpenClaw.Tray.WinUI/App.xaml.cs)

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.