feat(connection): enforce gateway protocol compatibility

[bkudiess]

Related: #1105

Note

This remains a draft. Do not mark ready until exact-head hosted checks and current-head visible UI proof are complete.

What Problem This Solves

Prevents missing, unknown, stale, or racing Gateway responses from completing or failing the Windows operator/node handshake. It also fails closed on malformed successful handshakes before readiness or token persistence, and reports role-aware protocol compatibility without confusing the Gateway current constant with the effective wire protocol.

Why This Change Was Made

• Only the exact pending connect request ID owns handshake success and errors.
• The full required response envelope and hello-ok shape are validated before side effects.
• Operator sessions reject Gateway current protocols above v4.
• Node role + node mode may accept Gateway current v5 with effective protocol v4 under the upstream N-1 policy.
• Structured mismatch details remain separate from observed Gateway current protocol.
• Structured error codes override textual fallback classification.
• Operator failures remain authoritative when a sticky node mismatch also exists.
• Node-only mismatches stay in the cockpit with protocol guidance and no misleading network retry.
• Explicit Connect and Disconnect recovery remains available. The former inert suppression flag was removed.

Upstream claims are pinned in docs/CONNECTION_PROTOCOL_RESEARCH.md to Core v2026.6.11 commit e085fa1a3ffd32d0ea6917e1e6fb4ecbffbb77d2 and N-1 commit 912af0a56f673787cc5ea813f17582b14e187e7b.

User Impact

Supported connections continue normally. Directional mismatches identify whether the Gateway or Windows app needs updating. Malformed or unowned responses cannot publish readiness, store tokens, alter pairing, or suppress reconnect. Gateway package version remains distinct from wire protocol diagnostics.

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

Validation

Exact local head: 6b6b875e17f3d12918ae89f47386799d6371f6ee

• ./build.ps1: all 5 projects passed
• Shared: 3,763 passed, 32 skipped, 0 failed
• Tray: 2,260 passed, 0 failed
• Connection: 593 passed, 0 failed
• WinNode CLI: 127 passed, 0 failed
• Aggregate: 6,743 passed, 32 skipped, 0 failed
• Ownership stress: 100 racing duplicate operator responses and 100 racing duplicate node responses complete exactly once
• Real abort-order regression: operator mismatch remains terminal Error; no later Disconnected overwrites it

Final immutable-head blind review:

• Claude Opus 5, high: supports at least 90% review confidence; no high/medium blockers
• GPT-5.6 Sol, high: supports at least 90% source-review confidence; no high/medium blockers
• Repository-aware rubber-duck follow-up: clean
• Bundled autoreview failed closed before model invocation because its generated bundle exceeded the 180 KB limit; no autoreview result is claimed

Hosted CI, CodeQL, ClawSweeper, proof: sufficient, and status: ready for maintainer look are pending for this pushed head.

Real Behavior Proof

Environment: isolated Windows tray data, isolated roaming/local roots, disposable loopback fake Gateway on port 19873, and isolated Local MCP on port 19874. No real credentials or user data were used.

Current-head winnode --command app.connection.status observations:

Scenario	Compatibility	Gateway current	Effective	Operator	Node
Gateway too old	gateway_too_old	unavailable	unavailable	Error	Disabled
Gateway too new	gateway_too_new	unavailable	unavailable	Error	Disabled
Compatible	compatible	4	4	Connected	Disabled
Node N-1	compatible	node 5	node 4	Connected	Connected
Sticky node mismatch + operator auth failure	node gateway_too_new	expected 6	unavailable	Error (unauthorized)	Error

winnode --list-tools included app.connection.status. The fake Gateway used the pinned full Core response shape and exact structured mismatch fields.

Proof manifest and SHA-256 hashes are retained in the private session artifact directory for run gwcompat-20260808-213736. All run-owned processes and ports were stopped. The production roaming manifest was unchanged. A pre-existing unowned WSL VHD timestamp changed concurrently, so strict local-root isolation is reported as compromised rather than success-shaped.

Current-head UI screenshots are not verified. Computer Use returned no discoverable app windows despite a responsive Companion window, and no shell/window-manager screenshot workaround was used. The older committed screenshots are not claimed as current-head evidence.

Security Impact

• New permissions or capabilities? No
• Secrets or tokens handling changed? No
• New or changed network calls? No
• Command or tool execution surface changed? No
• Data access scope changed? No

The change fails closed before token persistence or connected state for invalid owned handshakes, and ignores unowned responses without handshake, token, state, pairing, or reconnect effects.

Compatibility and Migration

• Backward compatible? Yes, for the documented v3-v4 client range and the upstream node-only N-1 window
• Config or environment changes? No
• Migration needed? No

Review Conversations

• No GitHub review conversation was changed by this repair session.
• Maintainer judgment is still required before marking ready.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 9, 2026, 2:55 AM ET / 06:55 UTC.

ClawSweeper review

What this changes

This PR validates Gateway wire-protocol handshakes and projects compatibility results into connection state, tray recovery guidance, local MCP diagnostics, telemetry, documentation, and tests.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep open. This collaborator-authored draft changes established Gateway connection behavior and needs a maintainer decision on its intentional terminal compatibility policy before merge.

Priority: P1
Reviewed head: 6b6b875e17f3d12918ae89f47386799d6371f6ee
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The branch has a coherent, tested compatibility boundary with relevant runtime observations; merge readiness depends on the explicit upgrade-policy decision.
Proof confidence	🌊 off-meta tidepool	Not applicable: This collaborator-authored PR is outside the external-contributor proof gate; its body nevertheless provides relevant current-head local-MCP observations and documents the blocked UI capture.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This collaborator-authored PR is outside the external-contributor proof gate; its body nevertheless provides relevant current-head local-MCP observations and documents the blocked UI capture.
Evidence reviewed	5 items	Current-main baseline: Current main sends protocol range 3 through 4 but does not validate the complete owned connect-response and hello-ok contract before handshake side effects. Branch handshake boundary: The branch adds an owned response-envelope validator and requires protocol, server, features, snapshot, auth, and policy fields before accepting hello-ok. Terminal recovery behavior: The branch marks malformed or incompatible owned handshakes as protocol mismatches, aborts the socket, suppresses automatic reconnect, and emits typed compatibility state.
Findings	None	None.
Security	None	None.

How this fits together

Gateway handshake responses establish operator and Windows-node sessions. The connection manager owns that state and passes it to the tray recovery UI and the local MCP status command.

flowchart LR
A[Gateway connect response] --> B[Handshake contract validation]
B --> C{Owned and compatible?}
C -->|Yes| D[Connection manager state]
C -->|No| E[Terminal compatibility recovery]
D --> F[Tray and MCP diagnostics]
E --> F

Loading

Decision needed

Question	Recommendation
Should malformed owned hello-ok responses and Gateway protocol versions outside the supported window remain terminal, non-retrying failures that require an update and explicit reconnect?	Adopt the terminal compatibility policy: Keep the branch’s fail-closed behavior and directional recovery guidance for unsupported or malformed owned handshakes.

Why: This is an intentional upgrade and availability policy change for existing Gateway installations, not a purely mechanical bug repair.

Before merge

• Resolve merge risk (P1) - Merging intentionally changes malformed or incompatible existing Gateway handshakes into terminal, non-retrying failures until the Gateway or Windows app is updated and explicitly reconnected.
• Resolve merge risk (P1) - The PR spans 40 files across protocol, connection state, WinUI, MCP, telemetry, and docs, so the terminal compatibility policy needs explicit maintainer ownership.
• Complete next step (P2) - A collaborator-authored draft intentionally changes upgrade and reconnect semantics, so maintainer policy approval is required rather than an automated repair.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	40 files, +4,004/-193 lines	The branch couples handshake handling with manager state, WinUI, MCP diagnostics, telemetry, documentation, and regression coverage.

Merge-risk options

Maintainer options:

1. Confirm terminal upgrade behavior
   Approve the fail-closed, explicit-reconnect policy for incompatible or malformed Gateway handshakes before merge.
2. Narrow the compatibility boundary
   Preserve existing recovery behavior for supported legacy handshakes if maintainers do not want update-only terminal failures.

Technical review

Best possible solution:

Adopt one documented terminal compatibility policy for owned handshake failures, preserve explicit Connect and Disconnect recovery, and land it only with maintainer agreement on the upgrade behavior.

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

Not applicable as a standalone issue. The PR body supplies a current-head local-MCP scenario matrix, and source inspection confirms the tested handshake boundary.

Is this the best way to solve the issue?

Unclear until maintainers choose the intended compatibility policy. The implementation is coherent, but deciding to make previously tolerated handshake shapes terminal is product and upgrade policy.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4712e227d110.

Labels

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• remove proof: 📸 screenshot: Current real behavior proof evidence kind is not_applicable.
• remove proof: sufficient: Current real behavior proof status is not_applicable, not sufficient.
• remove rating: 🦞 diamond lobster: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P1: The PR changes live operator and Windows-node Gateway connection behavior.
• merge-risk: 🚨 compatibility: It changes which Gateway handshake and protocol versions existing installations accept.
• merge-risk: 🚨 availability: A mismatch disables automatic reconnection until an explicit recovery follows an update.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This collaborator-authored PR is outside the external-contributor proof gate; its body nevertheless provides relevant current-head local-MCP observations and documents the blocked UI capture.

Evidence

What I checked:

• Current-main baseline: Current main sends protocol range 3 through 4 but does not validate the complete owned connect-response and hello-ok contract before handshake side effects. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:2092, 4712e227d110)
• Branch handshake boundary: The branch adds an owned response-envelope validator and requires protocol, server, features, snapshot, auth, and policy fields before accepting hello-ok. (src/OpenClaw.Shared/GatewayProtocolContract.cs:17, 6b6b875e17f3)
• Terminal recovery behavior: The branch marks malformed or incompatible owned handshakes as protocol mismatches, aborts the socket, suppresses automatic reconnect, and emits typed compatibility state. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:2695, 6b6b875e17f3)
• Related shipped policy: Merged PR feat(setup): enforce validated protocol-v4 Gateway releases #1105 established protocol-v4 validated Gateway setup releases, but it does not implement this PR’s live handshake ownership and UI/MCP diagnostics. (e295df266c72)
• Feature history: Recent current-main connection recovery work in the affected clients and manager was authored by Barbara Kudiess; managed Gateway restart recovery was recently maintained by Scott Hanselman. (src/OpenClaw.Connection/GatewayConnectionManager.cs:1, 603886a81d34)

Likely related people:

• bkudiess: Barbara Kudiess authored recent current-main gateway recovery and credential-handoff work in the affected operator and node connection paths. (role: recent connection contributor; confidence: high; commits: 603886a81d34, bc210e048aa9; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• Scott Hanselman: Authored the recent managed Gateway setup and restart-recovery work that shares the upgrade and reconnect boundary. (role: recent adjacent contributor; confidence: medium; commits: 01faa6419b42; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, docs/CONNECTION_ARCHITECTURE.md)

Rank-up moves

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

• Record maintainer approval or narrowing of the terminal compatibility policy before merge.

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.

History

Review history (15 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T00:06:21.975Z sha f9ca1c2 :: found issues before merge. :: [P2] Capture collector proof for protocol telemetry | [P2] Refresh UI and MCP proof on the current head
• reviewed 2026-08-09T00:32:28.822Z sha 775f044 :: found issues before merge. :: [P2] Capture collector proof for protocol telemetry | [P2] Refresh UI and MCP proof on the current head
• reviewed 2026-08-09T00:47:35.521Z sha 775f044 :: found issues before merge. :: [P2] Capture collector proof for protocol telemetry
• reviewed 2026-08-09T01:28:32.026Z sha 9f55849 :: found issues before merge. :: [P2] Capture collector proof for protocol telemetry
• reviewed 2026-08-09T01:47:30.517Z sha 9f55849 :: found issues before merge. :: [P2] Capture current-head collector proof for protocol telemetry
• reviewed 2026-08-09T02:17:32.993Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T03:16:15.842Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T04:09:47.247Z sha 9f55849 :: needs maintainer review before merge. :: none

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: A newer review tuple already exists; this stale result was superseded.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31290093545
• Updated: 2026-08-09T02:19:39.314Z

[bkudiess]

@clawsweeper re-review