feat(connection): enforce gateway protocol compatibility

[bkudiess]

Related: #1105

Note

This compatibility delta was restacked onto current main after #1095, #1101, and #1105 merged. The current reviewed head is 4ed146409f5472a77a1c275065cbd39f32ae4951.

What Problem This Solves

An incompatible Gateway could previously look like a generic connection failure or progress far enough to break Windows-node behavior without telling the operator which component needed updating.

Why This Change Was Made

The Windows operator and node clients now share the documented Gateway wire protocol v3-v4 range and validate the minimal hello-ok shape before publishing connection success or persisting handshake tokens. Successful integer protocol values at or above the client floor remain forward-compatible after the Gateway accepts the advertised range. Structured mismatch responses drive directional recovery for too-old and too-new peers.

The restack preserves current architecture ownership: ConnectEnvelopeBuilder owns connect envelopes, PendingRequestRegistry owns correlated requests, NodeConnectionCoordinator owns node lifecycle/recovery/compatibility, and GatewayConnectionManager owns operator lifecycle and state-machine writes.

User Impact

Supported v3-v4 Gateways connect normally. Gateways below the supported floor show Gateway update required. Newer Gateways that reject the offered range show Windows app update required. Deterministic protocol mismatches stop automatic reconnect loops while preserving explicit reconnect after software is updated.

Gateway package version and wire protocol remain separate diagnostics.

Evidence

Historical visual reference

These screenshots were captured from old head 9f558495cd8a4323f86b54391e6e9209eb0a4231. They remain useful visual references but are not claimed as current-head visible proof. Current-head recapture was blocked because the Windows desktop was locked.

Exact current-head MCP proof

An isolated tray built from 4ed146409f5472a77a1c275065cbd39f32ae4951 connected to a test-owned WSL too-new stub. winnode --list-tools advertised app.connection.status; invocation returned:

{
  "toolAdvertised": true,
  "schemaVersion": 2,
  "connectionState": "Error",
  "protocol": {
    "compatibility": "gateway_too_new",
    "gatewayExpectedProtocol": 5,
    "gatewayMinimumProtocol": 3,
    "retryable": false
  },
  "gateway": { "packageVersion": null },
  "node": { "intended": false },
  "mcp": { "running": true }
}

gateway.packageVersion is intentionally null because an incompatible handshake is rejected before Gateway self-information is published. The retained proof contains no credentials, device IDs, request IDs, raw frames, or user content.

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 current-head local validation at 4ed146409f5472a77a1c275065cbd39f32ae4951:

• ./build.ps1: all projects and documentation passed
• Shared: 3,757 passed, 32 skipped, 0 failed
• Tray: 2,632 passed, 0 failed
• Connection: 652 passed, 0 failed
• Setup Engine: 865 passed, 0 failed
• WinNode CLI: 127 passed, 0 failed
• Functional UI: 19 passed, 0 failed
• Native UI and accessibility: 143 passed, 0 failed
• Final WSL protocol matrix: 7/7 scenarios passed
• Focused post-review operator gateway tests: 232 passed
• Focused post-review connection manager tests: 174 passed

The final WSL matrix covered compatible protocol 4, additive future protocol 5, structured too-old, structured too-new, below-floor successful hello-ok, missing protocol, and malformed string protocol. Each terminal mismatch accepted exactly one connection. Compatible/future sessions retained normal reconnect after the stub intentionally closed the socket.

A broader opt-in E2E run on the same restacked runtime before the final logging/snapshot cleanup passed all 38 relevant real gateway setup, connect, revocation, and network recovery tests. Five unrelated MXC/AppContainer cases failed because MXC was unavailable while host fallback was correctly blocked.

Final identical-prompt adversarial review of 99730e75..4ed14640:

• Claude Opus 4.6: no remaining CRITICAL, HIGH, MEDIUM, or LOW defects
• GPT-5.3 Codex: no remaining CRITICAL, HIGH, MEDIUM, or LOW defects
• Two Opus-only LOW observations from the first pass were independently verified and fixed: gateway-controlled mismatch detail is sanitized, and the paired-node path no longer rebuilds the same compatibility snapshot twice

GitHub CI was triggered for the new head after the lease-protected update and is currently running.

Real Behavior Proof

• Environment tested: Windows, isolated tray data, OpenClawGateway WSL distro, raw WebSocket compatibility stub, isolated Local MCP
• Exact PR head tested: 4ed146409f5472a77a1c275065cbd39f32ae4951
• Exact steps:
  • start the test-owned WSL protocol stub for each compatibility case
  • connect the exact-head operator client and assert published compatibility/failure state
  • verify mismatch cases make one connection and compatible cases retain reconnect
  • launch the exact-head tray with unique OPENCLAW_TRAY_DATA_DIR
  • run winnode --list-tools and winnode --command app.connection.status
• Observed result:
  • protocol 4 and additive protocol 5 are compatible
  • expected protocol 2 produces terminal gateway_too_old
  • expected protocol 5 produces terminal gateway_too_new
  • below-floor, missing, and malformed successful versions fail closed
  • terminal mismatches do not reconnect automatically
  • MCP reports current/minimum/maximum compatibility separately from package version
• Screenshot or artifact links verified? Historical screenshot links resolve; current-head visual proof blocked
• Not verified or blocked:
  • current-head screenshot capture was blocked by the locked Windows desktop
  • MXC/AppContainer merge proof is unavailable on this host

Security Impact

• New permissions or capabilities? No
• Secrets or tokens handling changed? No credential semantics changed; gateway-controlled mismatch text is now sanitized before logging
• New or changed network calls? No new network calls
• Command or tool execution surface changed? No
• Data access scope changed? No

The change fails closed before token persistence or connected state when protocol validation fails. Credential precedence remains device token, shared gateway token, then bootstrap token.

Compatibility and Migration

• Backward compatible? Yes; preserves protocol v3-v4 and adds explicit handling outside it
• Config or environment changes? No
• Migration needed? No
• If yes, list the exact upgrade steps: N/A

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 18, 2026, 8:26 PM ET / August 19, 2026, 00:26 UTC.

ClawSweeper review

What this changes

The PR validates Gateway wire-protocol compatibility during operator and node handshakes, presents directed recovery states, exposes them through local MCP diagnostics, and adds regression coverage.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep open pending maintainer confirmation that terminal enforcement of the v3-v4 Gateway support window is the intended upgrade policy; current main records the handshake protocol but does not branch on it.

Priority: P1
Reviewed head: 4ed146409f5472a77a1c275065cbd39f32ae4951
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The branch has coherent implementation and current-head runtime evidence, with the remaining blocker being a maintainer-owned compatibility-policy decision rather than a patch defect.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The PR supplies exact-head WSL-stub and local-MCP live output showing a terminal gateway-too-new state; the prepared screenshots are explicitly historical visual references, not the basis for current-head proof.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR supplies exact-head WSL-stub and local-MCP live output showing a terminal gateway-too-new state; the prepared screenshots are explicitly historical visual references, not the basis for current-head proof.
Evidence reviewed	5 items	Current main only recorded protocol metadata: The current-main protocol research document says Windows advertised v3-v4 and recorded hello-ok.protocol for diagnostics without branching on it, confirming this PR supplies new enforcement rather than duplicating an existing behavior. Shared handshake contract: The branch requires an object hello-ok with an integer protocol at or above the supported floor, while retaining additive forward compatibility after the Gateway accepts the advertised range. Failure is terminal before connection success: Both the operator and node paths reject invalid connect responses, publish sanitized compatibility state, abort the socket, and suppress automatic reconnect for a protocol mismatch.
Findings	None	None.
Security	None	None.

Live Verification

Command: dotnet run --project ./src/OpenClaw.WinNode.Cli/OpenClaw.WinNode.Cli.csproj -- --help

Result: FAIL (failed) — execution before step 1 run: sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

Assertions:

• FAIL expect_output: winnode - invoke OpenClaw node commands on the local Windows tray over MCP

How this fits together

The Windows tray and node clients connect to a Gateway over a WebSocket handshake, then publish connection state to the tray UI and local MCP diagnostics. This change validates the protocol before success, token persistence, and reconnect behavior.

flowchart LR
  A[Gateway handshake] --> B[Protocol validation]
  B --> C{Compatible?}
  C -->|Yes| D[Connected state and token handoff]
  C -->|No| E[Terminal compatibility state]
  E --> F[Tray recovery guidance]
  E --> G[Local MCP diagnostics]
  D --> H[Node and operator services]

Loading

Decision needed

Question	Recommendation
Should Windows clients now treat accepted hello-ok payloads below protocol v3 or with malformed protocol values as terminal compatibility failures, while retaining forward compatibility for accepted integer values above v4?	Adopt v3-v4 enforcement: Accept terminal recovery for malformed and below-v3 handshakes, with future accepted protocol integers remaining compatible.

Why: This is an intentional upgrade-policy change: it replaces prior diagnostic-only handling with a non-retrying connection failure for existing deployments outside the declared support contract.

Before merge

• Resolve merge risk (P1) - Merging deliberately makes malformed or below-v3 successful handshakes terminal and non-retrying, so affected existing Gateway deployments must update rather than continue with the prior generic-failure behavior.
• Resolve merge risk (P1) - The current-head CI test and Gateway recovery jobs are still running and should complete before landing.
• Complete next step (P2) - The patch has no discrete mechanical defect; a maintainer must explicitly accept the upgrade policy and let the current-head checks complete.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Reviewed PR scope	46 files affected, +2,681 / -65	The change spans handshake clients, state propagation, WinUI recovery, MCP diagnostics, telemetry, documentation, and regression tests.

Root-cause cluster

Relationship: canonical
Canonical: #1127
Summary: This PR is the canonical remaining implementation for protocol enforcement; the linked merged work established adjacent protocol and connection ownership boundaries.

Members:

• adjacent_distinct: refactor(gateway): extract protocol core owners #1095 - It merged the shared connect-envelope and protocol-core ownership seam, but did not add runtime compatibility enforcement.
• adjacent_distinct: refactor(connection): extract domain coordinators #1101 - It merged connection-domain coordinators that this PR uses for state propagation, not the protocol policy itself.
• partial_overlap: feat(setup): enforce validated protocol-v4 Gateway releases #1105 - It established validated protocol-v4 Gateway releases, while this PR enforces the client handshake boundary at runtime.

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

Merge-risk options

Maintainer options:

1. Confirm and land the v3-v4 contract (recommended)
   Accept the documented support window and land after the exact-head Gateway recovery and test jobs finish successfully.
2. Broaden compatibility before enforcement
   Revise the range and its test matrix before merge if supported older Gateway deployments must continue connecting.

Technical review

Best possible solution:

Confirm the documented v3-v4 support policy, retain the shared validation boundary and directed recovery, then land only after the current-head Gateway and test jobs finish successfully.

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

Not applicable as a feature review. Current-main source confirms the prior behavior only recorded hello-ok protocol metadata, while the PR supplies a concrete WSL-stub and local-MCP validation path for the new behavior.

Is this the best way to solve the issue?

Yes, subject to maintainer approval of the strict support window. A shared handshake contract is the narrowest maintainable place to keep operator and node behavior aligned.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• remove proof: 📸 screenshot: Current real behavior proof evidence kind is live_output.

Label justifications:

• P1: The PR changes a live Gateway connection path used by Windows operators and nodes.
• merge-risk: 🚨 compatibility: Previously tolerated successful handshakes below the supported floor or with malformed protocol values become terminal failures.
• merge-risk: 🚨 availability: Protocol classification controls reconnect suppression and can leave a client disconnected until software is updated.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR supplies exact-head WSL-stub and local-MCP live output showing a terminal gateway-too-new state; the prepared screenshots are explicitly historical visual references, not the basis for current-head proof.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR supplies exact-head WSL-stub and local-MCP live output showing a terminal gateway-too-new state; the prepared screenshots are explicitly historical visual references, not the basis for current-head proof.

Evidence

What I checked:

• Current main only recorded protocol metadata: The current-main protocol research document says Windows advertised v3-v4 and recorded hello-ok.protocol for diagnostics without branching on it, confirming this PR supplies new enforcement rather than duplicating an existing behavior. (docs/CONNECTION_PROTOCOL_RESEARCH.md:71, b37307cbd51f)
• Shared handshake contract: The branch requires an object hello-ok with an integer protocol at or above the supported floor, while retaining additive forward compatibility after the Gateway accepts the advertised range. (src/OpenClaw.Shared/GatewayProtocolContract.cs:23, 4ed146409f54)
• Failure is terminal before connection success: Both the operator and node paths reject invalid connect responses, publish sanitized compatibility state, abort the socket, and suppress automatic reconnect for a protocol mismatch. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:2044, 4ed146409f54)
• Current-head proof and regression coverage: The PR body provides exact-head WSL-stub and local-MCP output for a terminal gateway-too-new result; source tests cover valid v3-v5 hello responses, invalid/malformed responses, structured mismatches, localized recovery, and MCP diagnostics. (tests/OpenClaw.Shared.Tests/GatewayProtocolContractTests.cs:89, 4ed146409f54)
• Recent connection provenance: The current head is the sanitization and snapshot-cleanup follow-up for this protocol work; the checked-out history is grafted, so deeper local file history is unavailable, while related merged protocol-core work is identified in the supplied PR context. (src/OpenClaw.Shared/GatewayProtocolContract.cs:1, 4ed146409f54)

Likely related people:

• karkarl: Authored the current-head protocol-diagnostics follow-up and applied the active-landing status in the PR timeline. (role: recent connection contributor; confidence: high; commits: 4ed146409f54; files: src/OpenClaw.Shared/GatewayProtocolContract.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.Tray.WinUI/Services/ConnectionDiagnosticsProjection.cs)
• bkudiess: Authored this branch's initial protocol implementation and the related merged protocol-core refactor. (role: protocol-core contributor; confidence: high; commits: 6feca1b9dc14, 323f46d3ded7; files: src/OpenClaw.Shared/ConnectEnvelopeBuilder.cs, src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Shared/WindowsNodeClient.cs)

Rank-up moves

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

• Confirm the terminal v3-v4 support policy and wait for the in-progress exact-head Gateway recovery and test jobs.

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 (20 earlier review cycles; latest 8 shown)

• 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
• reviewed 2026-08-09T06:55:51.390Z sha 6b6b875 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T08:46:01.978Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T10:20:42.283Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T11:59:10.755Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T14:50:38.690Z sha 9f55849 :: needs maintainer review before merge. :: none