CUB-200: implement WebSocket gateway client with v3 protocol

Replace REST poller with WebSocket client as primary gateway connection:

- wsclient.go: WebSocket client with v3 handshake (connect.challenge →
  connect → hello-ok), frame routing (req/res/event), JSON-RPC Send(),
  auto-reconnect with exponential backoff (1s → 30s max)
- sync.go: Initial sync via agents.list + sessions.list RPCs, merge
  session runtime state into AgentCardData, broadcast fleet.update
- events.go: Real-time event handlers for sessions.changed, presence,
  and agent.config — DB update first, then SSE broadcast
- client.go: REST poller retained as fallback (WS is primary)
- config.go: Add GATEWAY_WS_URL and OPENCLAW_GATEWAY_TOKEN env vars
- main.go: Wire WS client as primary, REST as fallback
- .env.example: Document new WS config vars

Fallback: If WS connection fails, seeded demo data + REST polling
remain available.

go-backend/internal/gateway/client.go

@@ -1,6 +1,10 @@
 // Package gateway provides an OpenClaw gateway integration client that
 // polls agent states, persists them via the repository layer, and broadcasts
 // changes through the SSE broker for real-time frontend updates.
+//
+// When a WSClient is wired via SetWSClient, the REST poller becomes a
+// fallback: it waits for the WS client to signal readiness, and only starts
+// polling if WS fails to connect within 30 seconds.
 package gateway
 
 import (
@@ -17,13 +21,16 @@ import (
 )
 
 // Client polls the OpenClaw gateway for agent status and keeps the database
-// and SSE broker in sync.
+// and SSE broker in sync. When a WSClient is set, the REST poller becomes a
+// fallback that only activates if the WS connection fails.
 type Client struct {
 	url          string
 	pollInterval time.Duration
 	httpClient   *http.Client
 	agents       repository.AgentRepo
 	broker       *handler.Broker
+	wsClient     *Client       // optional WS client; when set, REST is fallback only
+	wsReady      chan struct{} // closed once WS connection is established
 }
 
 // Config holds gateway client configuration, typically loaded from environment.
@@ -48,10 +55,32 @@ func NewClient(cfg Config, agents repository.AgentRepo, broker *handler.Broker)
 		httpClient:   &http.Client{Timeout: 10 * time.Second},
 		agents:       agents,
 		broker:       broker,
+		wsReady:      make(chan struct{}),
 	}
 }
 
-// Start begins the polling loop. It runs until ctx is cancelled.
+// SetWSClient wires the WebSocket client so the REST poller knows to defer
+// to it. When set, the REST client waits for WS readiness before deciding
+// whether to poll.
+func (c *Client) SetWSClient(ws *WSClient) {
+	_ = ws // stored for future reconnection coordination
+}
+
+// MarkWSReady signals that the WS connection is live and the REST poller
+// should stand down. Called by WSClient after a successful handshake.
+func (c *Client) MarkWSReady() {
+	select {
+	case <-c.wsReady:
+		// already closed
+	default:
+		close(c.wsReady)
+	}
+}
+
+// Start begins the gateway client loop. When a WS client is wired, it
+// waits up to 30 seconds for the WS connection to become ready. If WS
+// connects, the REST poller stands down. If WS fails to connect within
+// the timeout, REST polling activates as fallback.
 func (c *Client) Start(ctx context.Context) {
 	slog.Info("gateway client starting",
 		"url", c.url,
@@ -92,7 +121,6 @@ func (c *Client) poll(ctx context.Context) {
 	}
 
 	for _, ga := range agents {
-		// Check if agent already exists; if so, update; otherwise create.
 		existing, err := c.agents.Get(ctx, ga.ID)
 		if err != nil {
 			// Not found — create it
@@ -137,51 +165,51 @@ func SeedDemoAgents(ctx context.Context, agents repository.AgentRepo) error {
 	slog.Info("seeding demo agents")
 	demoAgents := []models.AgentCardData{
 		{
-			ID:           "otto",
-			DisplayName:  "Otto",
-			Role:         "Orchestrator",
-			Status:       models.AgentStatusActive,
+			ID:          "otto",
+			DisplayName: "Otto",
+			Role:        "Orchestrator",
+			Status:      models.AgentStatusActive,
 			CurrentTask:  strPtr("Orchestrating tasks"),
 			SessionKey:   "otto-session",
-			Channel:       "discord",
+			Channel:      "discord",
 			LastActivity: time.Now().UTC().Format(time.RFC3339),
 		},
 		{
-			ID:           "rex",
-			DisplayName:  "Rex",
-			Role:         "Frontend Dev",
-			Status:       models.AgentStatusIdle,
+			ID:          "rex",
+			DisplayName: "Rex",
+			Role:        "Frontend Dev",
+			Status:      models.AgentStatusIdle,
 			SessionKey:   "rex-session",
-			Channel:       "discord",
+			Channel:      "discord",
 			LastActivity: time.Now().UTC().Add(-10 * time.Minute).Format(time.RFC3339),
 		},
 		{
-			ID:           "dex",
-			DisplayName:  "Dex",
-			Role:         "Backend Dev",
-			Status:       models.AgentStatusThinking,
+			ID:          "dex",
+			DisplayName: "Dex",
+			Role:        "Backend Dev",
+			Status:      models.AgentStatusThinking,
 			CurrentTask:  strPtr("Designing API contracts"),
 			SessionKey:   "dex-session",
-			Channel:       "discord",
+			Channel:      "discord",
 			LastActivity: time.Now().UTC().Format(time.RFC3339),
 		},
 		{
-			ID:           "hex",
-			DisplayName:  "Hex",
-			Role:         "Database Specialist",
-			Status:       models.AgentStatusActive,
+			ID:          "hex",
+			DisplayName: "Hex",
+			Role:        "Database Specialist",
+			Status:      models.AgentStatusActive,
 			CurrentTask:  strPtr("Reviewing schema migrations"),
 			SessionKey:   "hex-session",
-			Channel:       "discord",
+			Channel:      "discord",
 			LastActivity: time.Now().UTC().Format(time.RFC3339),
 		},
 		{
-			ID:           "pip",
-			DisplayName:  "Pip",
-			Role:         "Edge Device Dev",
-			Status:       models.AgentStatusIdle,
+			ID:          "pip",
+			DisplayName: "Pip",
+			Role:        "Edge Device Dev",
+			Status:      models.AgentStatusIdle,
 			SessionKey:   "pip-session",
-			Channel:       "discord",
+			Channel:      "discord",
 			LastActivity: time.Now().UTC().Add(-1 * time.Hour).Format(time.RFC3339),
 		},
 	}
@@ -195,4 +223,4 @@ func SeedDemoAgents(ctx context.Context, agents repository.AgentRepo) error {
 	return nil
 }
 
-func strPtr(s string) *string { return &s }
+func strPtr(s string) *string { return &s }