Summary

• Problem: the browser Control UI still advertised Gateway protocol range 4..4 after the Gateway protocol constants moved to 5.
• Why it matters: the Gateway rejects the browser connect frame with code=1002 reason=protocol mismatch, leaving the operator UI unable to connect.
• What changed: ui/src/ui/gateway.ts now uses MIN_CLIENT_PROTOCOL_VERSION and PROTOCOL_VERSION from the shared Gateway protocol constants, and the node UI gateway test asserts those emitted fields.
• What did NOT change (scope boundary): no Gateway server compatibility behavior, stale-service-worker handling, or native client protocol handling changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: Control UI advertises protocol 4 after Gateway moves to protocol 5 #82882
• Related [Bug]: Gateway unusable on Windows 10: Protocol mismatch -> unauthorized #82315
• Related [Bug]: 2026.5.12 update on MacOS 26.5 causes web/app ws connection failures with "wrong protocol" errors #82037
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior addressed: Browser Control UI connect frames now advertise the shared current Gateway protocol range instead of stale literal protocol 4 values.
• Real environment tested: Windows source checkout at commit 31ca8b2a670fcc41513f75cc52f4c506908a59b8; local shell with Node v24.15.0. The reported failing environment was a browser Control UI served by pnpm ui:dev against a local Gateway on loopback port 18789.
• Exact steps or command run after this patch: Inspected current source for remaining protocol literals, ran patch hygiene, and ran a source-level terminal assertion that the browser connect builder uses MIN_CLIENT_PROTOCOL_VERSION / PROTOCOL_VERSION and that the regression test asserts both emitted fields.
• Evidence after fix:

$ git diff --check
exit code 0, no whitespace errors

$ node -e "const fs=require('fs'); const src=fs.readFileSync('ui/src/ui/gateway.ts','utf8'); const test=fs.readFileSync('ui/src/ui/gateway.node.test.ts','utf8'); const checks=[/MIN_CLIENT_PROTOCOL_VERSION/,/PROTOCOL_VERSION/,/minProtocol: MIN_CLIENT_PROTOCOL_VERSION/,/maxProtocol: PROTOCOL_VERSION/]; for (const re of checks) if (!re.test(src)) throw new Error('missing '+re); if (/minProtocol: 4|maxProtocol: 4/.test(src)) throw new Error('hardcoded protocol remains'); if (!/connectFrame\\.params\\?\\.minProtocol\\)\\.toBe\\(MIN_CLIENT_PROTOCOL_VERSION\\)/.test(test)) throw new Error('missing minProtocol assertion'); if (!/connectFrame\\.params\\?\\.maxProtocol\\)\\.toBe\\(PROTOCOL_VERSION\\)/.test(test)) throw new Error('missing maxProtocol assertion'); console.log('source assertions passed: UI connect params use shared protocol constants and test asserts them');"
source assertions passed: UI connect params use shared protocol constants and test asserts them

• Observed result after fix: ui/src/ui/gateway.ts has no remaining minProtocol: 4 or maxProtocol: 4 literals; the emitted connect params are wired to the shared protocol constants that currently evaluate to 5.
• What was not tested: Focused Vitest and ui:build could not be completed in this local Windows checkout because dependency install and command shims are blocked by local process-spawn permission failures. pnpm install retried once and failed in esbuild postinstall with spawnSync ... EPERM; node scripts/run-vitest.mjs ui/src/ui/gateway.node.test.ts failed with spawn EPERM; direct Vitest and Bun Vitest attempts timed out without useful output; Crabbox was unavailable because the local wrapper failed binary sanity checks; WSL had no Node installed.
• Before evidence:

Redacted Gateway log excerpt from the failing browser Control UI handshake:
protocol mismatch remote=127.0.0.1 client=openclaw-control-ui webchat vcontrol-ui
closed before connect remote=127.0.0.1 origin=http://localhost:5173 host=localhost:18789 code=1002 reason=protocol mismatch

Structured fields:
cause=protocol-mismatch
lastFrameMethod=connect
minProtocol=4
maxProtocol=4
expectedProtocol=5
minimumProbeProtocol=5
client=openclaw-control-ui
mode=webchat
version=control-ui
platform=Win32

Root Cause (if applicable)

• Root cause: ui/src/ui/gateway.ts encoded protocol 4 as a literal in both the GatewayConnectParams type and buildConnectParams, so Gateway protocol bumps did not update the browser Control UI client.
• Missing detection / guardrail: the existing browser gateway tests did not assert the emitted minProtocol and maxProtocol fields against the shared protocol constants.
• Contributing context (if known): native protocol levels already have guard coverage, but the browser Control UI client did not share that guardrail.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: ui/src/ui/gateway.node.test.ts
• Scenario the test should lock in: a browser Control UI connect frame advertises MIN_CLIENT_PROTOCOL_VERSION as minProtocol and PROTOCOL_VERSION as maxProtocol.
• Why this is the smallest reliable guardrail: the failure is in the connect frame builder before the Gateway accepts or rejects the WebSocket handshake.
• Existing test that already covers this (if any): none for the browser connect protocol fields.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

The browser Control UI can connect to a protocol 5 Gateway after the protocol bump instead of repeatedly failing the handshake with protocol mismatch.

Diagram (if applicable)

Before:
Control UI connect frame -> minProtocol=4/maxProtocol=4 -> Gateway protocol 5 rejection

After:
Control UI connect frame -> shared protocol constants -> Gateway protocol 5 handshake can proceed

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Windows browser client against local Gateway logs; patch built in a Windows source checkout.
• Runtime/container: Node v24.15.0 locally; no container proof.
• Model/provider: NOT_ENOUGH_INFO
• Integration/channel (if any): Browser Control UI / Gateway WebSocket
• Relevant config (redacted): local Gateway loopback port 18789; Vite Control UI origin http://localhost:5173

Steps

1. Run current Gateway with PROTOCOL_VERSION = 5.
2. Serve the browser Control UI with pnpm ui:dev.
3. Open the UI and let it connect to ws://127.0.0.1:18789.

Expected

• The Control UI advertises the current shared protocol range and the Gateway accepts the version range.

Actual

• Before this patch, the Control UI advertised minProtocol=4 and maxProtocol=4; the Gateway logged expectedProtocol=5 and closed with code=1002 reason=protocol mismatch.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: confirmed current origin/main still hardcoded protocol 4 in the browser Control UI; confirmed the patch removes the stale literals and wires the connect builder/test to the shared protocol constants; ran git diff --check and source-level terminal assertions.
• Edge cases checked: searched for remaining minProtocol: 4 / maxProtocol: 4 literals under ui/src and src/gateway/protocol.
• What you did not verify: focused Vitest, UI build, and live browser reconnection after patch were blocked by local Windows spawn/toolchain failures described above.

Review Conversations

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

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: local automated test execution was blocked in this checkout.
  • Mitigation: the change is narrow, a regression assertion was added, and the exact local blocker is documented so CI or a clean maintainer environment can run the intended Vitest/build proof.