🦞 Tracking: Connect & pair reliably — local and remote

[samanthamsong]

🦞 Tracking issue (epic) — this rolls up the scenario below. It holds no code itself; the work
lives in the child issues in the checklist below. Triage here, build there.

Outcome

I can connect and pair my node reliably, for local and remote gateways.

Definition of done

Pairing (incl. the QR flow) is robust for local and remote gateways, recovers from restarts, and we can test it when we make fixes.

Child issues

• Remote gateway node pairing broken — node token scopes empty, approval flow incomplete #710 — remote pairing broken (token scopes empty)
• QR-code pairing leaves the tray app permanently stuck in role: "node" #720 — QR pairing stuck in 'node' role
• Molty v0.6.0 Node Mode: WebSocket handshake fails with code 1006 on Gateway v2026.5.28 (WSL2) #667 — WebSocket handshake 1006 on WSL2
• Connection / pairing reliability — local and remote #844 — Connection / pairing reliability — local and remote
• End-to-end testing — cover the QR-code pairing flow #845 — End-to-end testing — cover the QR-code pairing flow
• WSL integration reliability + orchestration #846 — WSL integration reliability + orchestration

Backlog: One-pagers/FY27-Windows-Node-work-items.md • Narrative: User-scenarios/scenario-s2-connect-and-pair.md

[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. This collaborator-owned tracking epic remains necessary: its definition of done still spans independently open work for remote/local connection reliability, WSL recovery, mobile pairing, and upstream QR generation. Current main has substantial bootstrap-token handoff and reconnect safeguards, but it does not establish that every linked scenario is resolved.

Reproducibility: no. This is a tracking epic, not one executable bug report; current source and tests demonstrate token-handoff safeguards but do not provide a single live path covering every linked local, remote, WSL, mobile, and QR scenario.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should this issue remain the canonical cross-scenario pairing epic, with #844 narrowed to a specific reliability gap, or should the two tracking scopes be consolidated into one maintained roadmap item?	Keep this as the canonical epic: Retain this issue as the scenario-level tracker, narrow the overlapping child scope, and require each child to carry a reproducible acceptance check.

Why: The open reports cover several distinct product paths, while the two broad tracking descriptions overlap. Source inspection can verify safeguards, but cannot choose the intended ownership and reporting structure.

Next step
This collaborator-owned umbrella needs a maintainer-selected consolidation and ownership plan, not a single repair PR.

Review details

Best possible solution:

Retain one canonical pairing-reliability epic, assign each remaining scenario to a scoped child issue with a current-head validation owner, and remove or narrow any duplicate umbrella scope after that consolidation.

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

No. This is a tracking epic, not one executable bug report; current source and tests demonstrate token-handoff safeguards but do not provide a single live path covering every linked local, remote, WSL, mobile, and QR scenario.

Is this the best way to solve the issue?

Unclear. Current main follows a maintainable credential-precedence and durable-token recovery design, but maintainers must first consolidate the overlapping umbrella scopes and require current-head proof from each remaining child path.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The umbrella has no single current-main reproduction proving that its local, remote, WSL, mobile, and upstream QR scenarios all meet the definition of done.
• The overlap between this tracking epic and Connection / pairing reliability — local and remote #844 needs an explicit maintainer ownership decision to avoid two broad reports acting as competing sources of truth.

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

Label changes

Label justifications:

• P1: The epic tracks unresolved pairing and reconnection workflows that can block real gateway use, but the umbrella does not itself establish an active emergency regression.
• impact:auth-provider: Its central outcome depends on bootstrap, shared, and device-token credential selection and pairing approval.
• impact:session-state: The stated definition of done explicitly requires recovery after restarts, which depends on durable gateway identity and connection state.

Evidence reviewed

What I checked:

• Open child work remains: The tracking body and supplied timeline identify still-open reports for connection/pairing reliability, WSL orchestration, mobile pairing, and upstream QR generation. They describe distinct remaining scenarios rather than a completed implementation.
• Current bootstrap handoff is implemented: Current main persists received device tokens, retains bootstrap credentials until both operator and node tokens are durable, then schedules an operator reconnect using the persisted operator token or retained shared token. (src/OpenClaw.Connection/GatewayConnectionManager.cs:1802, 8ac00c5f4977)
• Current regression coverage covers the handoff invariant: Connection-manager tests explicitly cover clearing bootstrap credentials only after durable operator and node tokens, preserving bootstrap credentials until both roles are durable, and post-bootstrap operator reconnect behavior. (tests/OpenClaw.Connection.Tests/GatewayConnectionManagerTests.cs:3482, 8ac00c5f4977)
• Recent connection-recovery provenance: Recent current-main connection work includes recovery after local gateway listener or token drift, authored by Barbara Kudiess; its patch touches the connection manager, registry, node connector, setup flow, and related tests. (src/OpenClaw.Connection/GatewayConnectionManager.cs:1, bc210e048aa9)
• Release/main-only check: The latest release commit is not an ancestor of current main; several connection changes are therefore current-main-only relative to v0.6.12, so release provenance cannot establish the epic as fully shipped. (8ac00c5f4977)
• History inspection limitation: A targeted blame and historical pattern search required fetching missing promisor objects, but network DNS resolution failed. The owner assessment therefore relies on locally available recent commit history and changed-file provenance. (src/OpenClaw.Connection/GatewayConnectionManager.cs:1802)

Likely related people:

• Barbara Kudiess: Authored recent current-main recovery and device-identity hardening that changed the connection manager, gateway registry, setup flow, and focused connection tests. (role: recent connection-recovery contributor; confidence: high; commits: bc210e048aa9, c04c5fb06238; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.Connection/GatewayRegistry.cs, tests/OpenClaw.Connection.Tests/GatewayConnectionManagerTests.cs)
• Vincent Koc: Authored the current-main saved SSH tunnel recovery change in the connection manager and its focused tests, which is adjacent to the epic's remote gateway reliability outcome. (role: recent remote-connection recovery contributor; confidence: medium; commits: d7d153ca5d40; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.Connection/SshTunnelService.cs, tests/OpenClaw.Connection.Tests/GatewayConnectionManagerTests.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.