[Bug]: Operator RPC can be sent before connect/hello-ok, causing 1008 PolicyViolation

[jaser-deli]

Context

This issue was originally reported in:

openclaw/openclaw#148115

Core triage determined that the Gateway behavior is correct and that the defect belongs to the Windows Companion client maintained in this repository.

The original issue was closed as out-of-repository scope, not because the reported race was considered invalid.

Summary

During Windows Companion startup or reconnect, the operator WebSocket can send RPCs such as node.list, device.pair.list, or models.list before the required connect handshake completes.

The Gateway then correctly rejects the request and closes the socket with:

1008 PolicyViolation: invalid handshake: first request must be connect

Expected behavior

Application RPCs should only be sent after the operator WebSocket has completed the connect handshake and received hello-ok.

Known-good sequence:

operator socket opened
→ connect sent
→ hello-ok received
→ Handshake complete
→ models.list / node.list / other RPCs

Actual behavior

During reconnects, the operator WebSocket can be open before its protocol handshake is complete.

Another connection event may then trigger an RPC on the operator socket before connect has been sent.

Observed example:

04:09:23.717 operator: Connecting to gateway
04:09:23.871 node:     Sending connect (role=node)
04:09:24.310 node:     Received hello-ok
04:09:24.314 operator: gateway connected, waiting for challenge...
04:09:24.315 operator: Received connect.challenge
04:09:24.316 node:     Node status changed: Connected
04:09:24.317 operator: node.list failed: invalid handshake: first request must be connect
04:09:24.318 operator: Server closed connection: PolicyViolation (1008)
04:09:24.321 operator: gateway reconnecting in 4548ms
04:09:26.953 operator: Sending connect

The node.list RPC was sent before the operator socket sent connect.

A startup variant was also observed:

03:16:03.489 operator: gateway connected, waiting for challenge...
03:16:03.520 [ChatBridge] proactive: requesting models.list and sessions.list
03:16:03.523 Sending frame: models.list
03:16:03.541 PolicyViolation - first request must be connect
03:16:05.625 Sending connect

Frequency

Historical Companion logs contained 29 occurrences of this 1008 PolicyViolation.

• 28 occurred during reconnect:
  • 22 involved node.list
  • 6 involved device.pair.list
• 1 startup occurrence involved models.list

After an unrelated WSL lifecycle issue was fixed, a stable 5.5-minute capture showed:

• zero reconnects
• zero PolicyViolation events
• zero first request must be connect
• zero connection failures
• stable operator/node sockets

Version

• Windows Companion: 2026.9.3
• Companion commit: 84928c43
• Gateway: 2026.9.2
• Gateway protocol: 4
• OS: Windows 11

Source-level evidence

The Companion currently exposes gateway readiness as:

IsConnectedToGateway => IsConnected

However, IsConnected appears to represent WebSocket-open state rather than protocol-handshake completion.

A separate handshake state already exists as _hasHandshakeSnapshot.

SendTrackedRequestAsync also appears to check socket connectivity without requiring hello-ok completion.

Observed request paths include:

• RequestNodesAsync
• RequestDevicePairListAsync
• proactive models.list startup requests

This allows RPC admission during the window where the socket is open but the operator handshake has not completed yet.

Possible fix

Gateway readiness could require both socket connectivity and handshake completion, for example:

public bool IsConnectedToGateway =>
    IsConnected && Volatile.Read(ref _hasHandshakeSnapshot);

It may also be useful to add a defensive handshake-readiness guard in tracked RPC send paths so application RPCs cannot be sent before hello-ok.

Gateway behavior

The Gateway appears to be behaving correctly.

It requires the first application frame to be connect, and rejects other requests with 1008 PolicyViolation.

The original core triage explicitly identified the Windows Companion as the correct repair location.

Impact

Severity: intermittent reconnect failure / degraded connection reliability.

No data loss was observed.

A failed operator connection is discarded and retried after approximately 4.5 seconds.

During reconnect activity, the Windows Companion may show user-facing states such as:

• Authentication failed
• Transport error
• Gateway connection failed

Reproduction

A deterministic current-main reproduction has not yet been performed.

The evidence is based on:

• Windows Companion logs
• Gateway journal
• Windows process/socket inspection
• Companion source review
• repeated historical occurrences

Related issue

openclaw/openclaw#148115

Screenshots

Screenshots below show the user-visible connection/reconnect failure states.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 14, 2026, 5:47 AM ET / 09:47 UTC.

Summary
The reported race remains present on current main and in the latest release. Source inspection establishes a bounded client-side defect, and no open fixing PR was found.

Reproducibility: yes. at source level: open the operator socket, delay challenge or hello-ok, and invoke node.list, device.pair.list, or proactive models.list. Current guards permit transmission; no runtime reproduction was performed.

Next step
A focused repair can enforce the existing handshake contract, with clear client and test seams and no open PR found to own it.

Review details

Best possible solution:

Centralize handshake-aware, generation-bound application RPC admission in the operator client while retaining connect as the handshake path and preserving post-handshake bootstrap.

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

Yes, at source level: open the operator socket, delay challenge or hello-ok, and invoke node.list, device.pair.list, or proactive models.list. Current guards permit transmission; no runtime reproduction was performed.

Is this the best way to solve the issue?

Yes, client-side admission is the narrow repair, but changing only IsConnectedToGateway is insufficient because direct tracked and response-awaiting RPC sends also bypass handshake readiness.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The precise timing and frequency on current main remain unmeasured; this read-only review ran no builds, tests, or live reproduction.
• An entry-only readiness check may still allow a waiting send to cross onto a replacement socket; the repair must cover connection generation changes.

Codex review notes: model internal, reasoning medium; reviewed against bd9ce43b4d9c.

Label changes

Label changes:

• add P1: Repeated premature RPCs interrupt an existing operator connection workflow on the current release.
• add impact:ux-friction: Recoverable handshake races surface misleading authentication and transport errors; automatic retry and a stable connection interval are documented.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P1: Repeated premature RPCs interrupt an existing operator connection workflow on the current release.
• impact:ux-friction: Recoverable handshake races surface misleading authentication and transport errors; automatic retry and a stable connection interval are documented.

Evidence reviewed

Acceptance criteria:

• ./build.ps1
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore
• dotnet test ./tests/OpenClaw.Connection.Tests/OpenClaw.Connection.Tests.csproj --no-restore
• ./scripts/validate-mxc-e2e.ps1

What I checked:

• Current source confirms premature readiness: IsConnectedToGateway delegates solely to IsConnected. WebSocketClientBase defines IsConnected as WebSocketState.Open, which becomes true before challenge handling and hello-ok. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:288, bd9ce43b4d9c)
• Both reported RPC paths lack handshake admission: SendTrackedRequestAsync checks only IsConnected before registering and sending node.list or device.pair.list. SendWizardRequestAsync at line 1199 does the same for the current models.list path. A readiness-property change alone would leave direct RPC callers unprotected. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:2110, bd9ce43b4d9c)
• Concrete startup trigger: StartProactiveBootstrap checks IsConnectedToGateway and immediately requests models and sessions. Constructing the chat bridge while the socket is open but the handshake is pending therefore reaches the unguarded send paths. (src/OpenClaw.Tray.WinUI/Chat/IChatGatewayBridge.cs:191, bd9ce43b4d9c)
• Existing handshake and transport seams: Validated, correlated hello-ok publishes _hasHandshakeSnapshot before Connected; disconnect resets it. The transport's ordinary send captures the current socket after awaiting its send lock, while a separate generation-bound overload already exists for connect frames. Repair should preserve generation ownership as well as handshake ordering. (src/OpenClaw.Shared/WebSocketClientBase.cs:732, bd9ce43b4d9c)
• Existing tests encode the unsafe assumption: The loopback round-trip fixture deliberately omits hello-ok and waits only for socket readiness. These tests must perform the real handshake when admission is repaired; retaining their current shortcut would mask the reported defect. (tests/OpenClaw.Shared.Tests/GatewayProtocolLiveRoundTripTests.cs:253, bd9ce43b4d9c)
• Latest release remains affected: GitHub identifies v2026.9.3 as the latest release. Comparing its supplied commit with current main shows no changes to the operator client, WebSocket transport, or chat bridge, so the reported admission mechanism remains unchanged. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:288, bd9ce43b4d9c)

Likely related people:

• shanselman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Barbara Kudiess: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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.