clawmatrix 0.5.1 → 0.6.0

package/src/cluster-service.ts

@@ -237,6 +237,10 @@ export class ClusterRuntime {
         });
         this.knowledgeSync.start().then(() => {
           this.logger.info(`[clawmatrix] Knowledge sync started: ${workspacePath}`);
+          // Sync with any peers that connected before start() completed
+          for (const peerId of this.peerManager.router.getDirectPeerIds()) {
+            this.knowledgeSync?.initPeerSync(peerId);
+          }
         }).catch((err) => {
           this.logger.error(`[clawmatrix] Knowledge sync failed to start: ${err}`);
         });
@@ -643,15 +647,26 @@ export class ClusterRuntime {
       case "availability_req": {
         const af = frame as AvailabilityRequest;
         const range = af.payload.range ?? "24h";
-        const data = this.healthTracker.getAvailability(range);
-        this.peerManager.sendTo(af.from, {
-          type: "availability_res",
-          id: af.id,
-          from: this.config.nodeId,
-          to: af.from,
-          timestamp: Date.now(),
-          payload: { success: true, data },
-        } as AvailabilityResponse);
+        try {
+          const data = this.healthTracker.getAvailability(range);
+          this.peerManager.sendTo(af.from, {
+            type: "availability_res",
+            id: af.id,
+            from: this.config.nodeId,
+            to: af.from,
+            timestamp: Date.now(),
+            payload: { success: true, data },
+          } as AvailabilityResponse);
+        } catch (err) {
+          this.peerManager.sendTo(af.from, {
+            type: "availability_res",
+            id: af.id,
+            from: this.config.nodeId,
+            to: af.from,
+            timestamp: Date.now(),
+            payload: { success: false, error: String((err as Error)?.message ?? err) },
+          } as AvailabilityResponse);
+        }
         break;
       }
       case "acp_req":

package/src/config.ts

@@ -133,23 +133,29 @@ const TerminalConfigSchema = z.object({
   allowFrom: z.array(z.string()).default([]),
 }).optional();
 
-const FileTransferConfigSchema = z.object({
-  enabled: z.boolean().default(false),
-  chunkSize: z.number().default(262_144),       // 256KB
-  maxFileSize: z.number().default(104_857_600),  // 100MB
-  timeout: z.number().default(300_000),          // 5min per-chunk
-  allowedPaths: z.array(z.string()).default([]), // empty = no restriction
-}).optional();
+const FileTransferConfigSchema = z.preprocess(
+  (v) => v ?? {},
+  z.object({
+    enabled: z.boolean().default(true),
+    chunkSize: z.number().default(262_144),       // 256KB
+    maxFileSize: z.number().default(104_857_600),  // 100MB
+    timeout: z.number().default(300_000),          // 5min per-chunk
+    allowedPaths: z.array(z.string()).default([]), // empty = no restriction
+  }),
+).default({});
 
-const KanbanConfigSchema = z.object({
-  enabled: z.boolean().default(false),
-  /** Card ID prefix (e.g. "CM" → CM-1, CM-2). */
-  prefix: z.string().default("CM"),
-  /** Allow agents to auto-claim matching cards. */
-  autoAssign: z.boolean().default(true),
-  /** Archive cards older than this (ms). Default: 30 days. */
-  archiveAfterMs: z.number().default(30 * 24 * 60 * 60 * 1000),
-}).optional();
+const KanbanConfigSchema = z.preprocess(
+  (v) => v ?? {},
+  z.object({
+    enabled: z.boolean().default(true),
+    /** Card ID prefix (e.g. "CM" → CM-1, CM-2). */
+    prefix: z.string().default("CM"),
+    /** Allow agents to auto-claim matching cards. */
+    autoAssign: z.boolean().default(true),
+    /** Archive cards older than this (ms). Default: 30 days. */
+    archiveAfterMs: z.number().default(30 * 24 * 60 * 60 * 1000),
+  }),
+).default({});
 
 const AcpConfigSchema = z.object({
   enabled: z.boolean().default(false),

package/src/connection.ts

@@ -269,6 +269,15 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async onRawMessage(data: unknown) {
     this.lastReceivedAt = Date.now();
 
+    // Debug: log data type for unauthenticated connections to diagnose auth issues
+    if (!this.authenticated && this.role === "outbound") {
+      const dtype = Buffer.isBuffer(data) ? `Buffer(${(data as Buffer).length})` :
+        data instanceof ArrayBuffer ? `ArrayBuffer(${data.byteLength})` :
+        typeof data === "string" ? `string(${data.length})` :
+        `${data?.constructor?.name ?? typeof data}`;
+      debug("auth", `onRawMessage[outbound] dataType=${dtype}`);
+    }
+
     // Normalize non-Buffer binary types to Buffer.
     // Node.js 24+'s built-in WebSocket (undici) delivers binary frames as Blob
     // (binaryType "blob") or ArrayBuffer (binaryType "arraybuffer").
@@ -570,6 +579,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       }
 
       // auth_ok (decrypted from binary envelope, or plaintext legacy)
+      debug("auth", `Outbound received frame type=${frame.type} (authenticated=${this.authenticated})`);
       if (frame.type === "auth_ok") {
         const ok = frame as AuthOk;
         this.remoteNodeId = ok.payload.nodeId;

package/src/device-info.ts

@@ -50,6 +50,15 @@ function resolveWorkspace(openclawConfig?: Record<string, unknown>): string | un
   return undefined;
 }
 
+function resolveClawmatrixVersion(): string | undefined {
+  try {
+    const raw = readFileSync(join(dirname(import.meta.url.replace("file://", "")), "..", "package.json"), "utf-8");
+    const pkg = JSON.parse(raw) as { version?: string };
+    return pkg.version;
+  } catch { /* best effort */ }
+  return undefined;
+}
+
 /** Collect device info once at startup. */
 export function collectDeviceInfo(openclawVersion?: string, openclawConfig?: Record<string, unknown>): DeviceInfo {
   const cpuList = cpus();
@@ -61,6 +70,7 @@ export function collectDeviceInfo(openclawVersion?: string, openclawConfig?: Rec
     totalMemoryMB: Math.round(totalmem() / (1024 * 1024)),
     hostname: hostname(),
     openclawVersion: resolveOpenclawVersion(openclawVersion),
+    clawmatrixVersion: resolveClawmatrixVersion(),
     cwd: process.cwd(),
     workspace: resolveWorkspace(openclawConfig),
   };

package/src/health-tracker.ts

@@ -155,7 +155,10 @@ export class HealthTracker {
       if (ev.peer) everConnected.add(ev.peer);
     }
 
-    const knownNodes = this.getKnownNodes();
+    const knownNodes = new Set(this.getKnownNodes());
+    // Also include nodes we've observed via peer_online events
+    for (const peerId of everConnected) knownNodes.add(peerId);
+
     for (const nodeId of knownNodes) {
       if (nodeId !== this.nodeId && !everConnected.has(nodeId)) continue;
 
@@ -181,12 +184,29 @@ export class HealthTracker {
     observerGaps: Array<[number, number]>,
   ): NodeTimeline | null {
     const sorted = [...events].sort((a, b) => a.ts - b.ts);
-    if (sorted.length === 0) return null;
 
-    const firstSeen = sorted[0]!.ts;
-    const lastSeen = sorted[sorted.length - 1]!.ts;
+    // For remote nodes, also consider peer observation intervals
+    const peerIntervals = nodeId !== this.nodeId
+      ? this.buildPeerIntervals(nodeId, startTs, endTs)
+      : [];
+
+    if (sorted.length === 0 && peerIntervals.length === 0) return null;
+
+    // Determine firstSeen/lastSeen from both self-reported events and peer observations
+    let firstSeen = Infinity;
+    let lastSeen = -Infinity;
+    if (sorted.length > 0) {
+      firstSeen = sorted[0]!.ts;
+      lastSeen = sorted[sorted.length - 1]!.ts;
+    }
+    for (const [s, e] of peerIntervals) {
+      if (s < firstSeen) firstSeen = s;
+      if (e > lastSeen) lastSeen = e;
+    }
 
-    const intervals = this.buildOnlineIntervals(nodeId, sorted, startTs, endTs);
+    const intervals = nodeId !== this.nodeId
+      ? this.mergeIntervals([...this.buildSelfIntervals(sorted, startTs, endTs), ...peerIntervals])
+      : this.buildOnlineIntervals(nodeId, sorted, startTs, endTs);
 
     const buckets: BucketState[] = [];
     let totalOnline = 0;

package/src/index.ts

@@ -1537,6 +1537,291 @@ const plugin = {
       },
     );
 
+    // ── Availability gateway method ──────────────────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.availability",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const { range } = (params ?? {}) as { range?: string };
+          const validRanges = ["24h", "7d", "90d"];
+          const r = validRanges.includes(range ?? "") ? (range as "24h" | "7d" | "90d") : "24h";
+          const result = runtime.healthTracker.getAvailability(r);
+          respond(true, result);
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    // ── Automation gateway methods ──────────────────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.automations.rules",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.automationManager) {
+            respond(true, { rules: [] });
+            return;
+          }
+          respond(true, { rules: runtime.automationManager.getRules() });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.automations.save",
+      async ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.automationManager) {
+            respond(false, { error: "Automations not available" });
+            return;
+          }
+          const { rules } = (params ?? {}) as { rules?: unknown[] };
+          if (!Array.isArray(rules)) {
+            respond(false, { error: "Missing required param: rules (array)" });
+            return;
+          }
+          await runtime.automationManager.saveRules(rules as Parameters<typeof runtime.automationManager.saveRules>[0]);
+          respond(true, { ok: true, count: rules.length });
+        } catch (err) {
+          respond(false, { error: String(err) });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.automations.history",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.automationManager) {
+            respond(true, { executions: [] });
+            return;
+          }
+          const { limit } = (params ?? {}) as { limit?: number };
+          respond(true, { executions: runtime.automationManager.getExecutions(limit ?? 50) });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.automations.run",
+      async ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.automationManager) {
+            respond(false, { error: "Automations not available" });
+            return;
+          }
+          const { ruleId, event } = (params ?? {}) as { ruleId?: string; event?: Record<string, unknown> };
+          if (!ruleId) {
+            respond(false, { error: "Missing required param: ruleId" });
+            return;
+          }
+          const evt = event ? {
+            id: nanoid(),
+            source: String(event.source || "cli"),
+            type: String(event.type || "manual"),
+            data: (event.data ?? {}) as Record<string, unknown>,
+            ts: typeof event.ts === "number" ? event.ts : Date.now(),
+            consumed: false,
+          } as import("./types.ts").IngestedEvent : undefined;
+          const execution = await runtime.automationManager.runRuleById(ruleId, evt);
+          respond(true, { ok: true, execution });
+        } catch (err) {
+          respond(false, { error: String(err) });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.automations.replay",
+      async ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.automationManager) {
+            respond(false, { error: "Automations not available" });
+            return;
+          }
+          const { executionId } = (params ?? {}) as { executionId?: string };
+          if (!executionId) {
+            respond(false, { error: "Missing required param: executionId" });
+            return;
+          }
+          const execution = await runtime.automationManager.replayExecution(executionId);
+          respond(true, { ok: true, execution });
+        } catch (err) {
+          respond(false, { error: String(err) });
+        }
+      },
+    );
+
+    // ── Events ingest gateway method ──────────────────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.events.ingest",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.apiHandler) {
+            respond(false, { error: "API handler not available (listen mode required)" });
+            return;
+          }
+          const { events } = (params ?? {}) as { events?: unknown[] };
+          if (!Array.isArray(events) || events.length === 0) {
+            respond(false, { error: "Missing required param: events (non-empty array)" });
+            return;
+          }
+          const result = runtime.apiHandler.ingestEvents(events as Array<Record<string, unknown>>);
+          respond(true, { ok: true, ...result });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    // ── Board update gateway method ──────────────────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.board.update",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.kanbanManager) {
+            respond(false, { error: "Kanban not enabled" });
+            return;
+          }
+          const { cardId, ...updates } = (params ?? {}) as {
+            cardId?: string; title?: string; description?: string;
+            priority?: string; targetNode?: string; targetAgent?: string;
+            cwd?: string; labels?: string[];
+          };
+          if (!cardId) {
+            respond(false, { error: "Missing required param: cardId" });
+            return;
+          }
+          const card = runtime.kanbanManager.updateCard(cardId, updates as Parameters<typeof runtime.kanbanManager.updateCard>[1]);
+          if (!card) {
+            respond(false, { error: `Card not found: ${cardId}` });
+            return;
+          }
+          respond(true, card);
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    // ── Config gateway method ──────────────────────────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.config.get",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const c = runtime.config;
+          respond(true, {
+            nodeId: c.nodeId,
+            listen: c.listen,
+            tags: c.tags,
+            agents: c.agents.map((a) => ({ id: a.id, model: a.model })),
+            models: c.models.map((m) => ({ id: m.id, provider: m.provider })),
+            e2ee: c.e2ee,
+            toolProxy: c.toolProxy ? { enabled: c.toolProxy.enabled, allow: c.toolProxy.allow, deny: c.toolProxy.deny } : undefined,
+            terminal: c.terminal,
+            acp: c.acp ? { enabled: c.acp.enabled } : undefined,
+            knowledge: c.knowledge ? { enabled: c.knowledge.enabled } : undefined,
+            proxyModels: c.proxyModels?.length ?? 0,
+            peers: c.peers?.length ?? 0,
+          });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    // ── Config file read/write gateway methods ──────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.config.read",
+      async ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.apiHandler) {
+            respond(false, { error: "API handler not available" });
+            return;
+          }
+          const { path: configPath } = (params ?? {}) as { path?: string };
+          if (!configPath) {
+            respond(false, { error: "Missing required param: path" });
+            return;
+          }
+          const result = await runtime.apiHandler.readConfigFile(configPath);
+          respond(result.success, result);
+        } catch (err) {
+          respond(false, { error: String(err) });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.config.write",
+      async ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.apiHandler) {
+            respond(false, { error: "API handler not available" });
+            return;
+          }
+          const { path: configPath, content } = (params ?? {}) as { path?: string; content?: string };
+          if (!configPath || typeof content !== "string") {
+            respond(false, { error: "Missing required params: path, content" });
+            return;
+          }
+          const result = await runtime.apiHandler.writeConfigFile(configPath, content);
+          respond(result.success, result);
+        } catch (err) {
+          respond(false, { error: String(err) });
+        }
+      },
+    );
+
+    // ── Knowledge content gateway method ──────────────────────────────
+
+    api.registerGatewayMethod(
+      "clawmatrix.kb.content",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          if (!runtime.knowledgeSync) {
+            respond(false, { error: "Knowledge sync not enabled" });
+            return;
+          }
+          const { path } = (params ?? {}) as { path?: string };
+          if (!path) {
+            respond(false, { error: "Missing required param: path" });
+            return;
+          }
+          const content = runtime.knowledgeSync.getFileContent(path);
+          if (content === null) {
+            respond(false, { error: "File not found or content not yet synced" });
+            return;
+          }
+          respond(true, { path, content });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
     // Log model selection on each LLM call (fire-and-forget)
     api.on("llm_input", (event) => {
       api.logger.debug(`[clawmatrix] llm_input: provider=${event.provider} model=${event.model}`);

package/src/knowledge-sync.ts

@@ -547,6 +547,13 @@ export class KnowledgeSync {
     })).filter(f => !f.deleted);
   }
 
+  /** Get the CRDT content of a synced file, or null if not found. */
+  getFileContent(relPath: string): string | null {
+    const doc = this.fileDocs.get(relPath);
+    if (!doc || doc.content === undefined) return null;
+    return doc.content;
+  }
+
   /**
    * Set pending attribution for a file path.
    * Called by tool hooks (after_tool_call, ACP stream) before fsWatcher picks up the change.

package/src/peer-manager.ts

@@ -30,28 +30,32 @@ import type { KeyPair } from "./crypto.ts";
 const RECONNECT_MAX = 60_000;
 
 /** Frame types that bypass dedup (streams share one id across chunks; responses share id with request). */
-const SKIP_DEDUP_TYPES = new Set([
+/**
+ * Frame types that bypass dedup. Response frames share the same `id` as their
+ * request, so the relay node would otherwise treat the response as a duplicate.
+ * Streaming chunks reuse a single `id` across many frames.
+ *
+ * Rather than maintaining a fragile manual list, we match by convention:
+ *   - Any type ending in `_res` is a response frame
+ *   - Explicit set covers streams, control frames, and file-transfer chunks
+ */
+const SKIP_DEDUP_EXPLICIT = new Set([
   // Streaming
   "model_stream", "handoff_stream", "acp_stream",
-  // Response frames (share id with their request)
-  "model_res", "tool_res", "tool_batch_res",
-  "handoff_res", "handoff_status_res", "handoff_input_required",
   // Handoff control (reuse original handoff_req id)
   "handoff_input", "handoff_cancel", "handoff_status",
-  // Diagnostics & approval
-  "diagnostic_exec_res", "diagnostic_status_res", "peer_approval_res",
-  // ACP responses
-  "acp_res", "acp_close_res", "acp_list_res", "acp_resume_res",
-  "acp_cancel_res", "acp_set_mode_res", "acp_get_modes_res",
-  "chat_history_res",
-  // Terminal
-  "terminal_open_res", "terminal_data", "terminal_resize",
-  "terminal_close", "terminal_close_res",
+  "handoff_input_required",
+  // Terminal data/control
+  "terminal_data", "terminal_resize", "terminal_close",
   // File transfer
   "file_transfer_chunk", "file_transfer_chunk_ack",
   "file_transfer_ack", "file_transfer_complete",
 ]);
 
+function skipDedup(type: string): boolean {
+  return type.endsWith("_res") || SKIP_DEDUP_EXPLICIT.has(type);
+}
+
 // Reconnect backoff params are now provided by retry.ts → getReconnectBackoff()
 
 /** Classify WebSocket close code into a human-readable reason. */
@@ -111,6 +115,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private probeTimer: ReturnType<typeof setInterval> | null = null;
   /** EMA latency baseline per peer (for spike detection). */
   private latencyBaselines = new Map<string, number>();
+  /** Throttle timer for latency-triggered peer_sync broadcasts. */
+  private latencySyncTimer: ReturnType<typeof setTimeout> | null = null;
   /** Last time a latency-triggered probe was fired per peer (debounce). */
   private lastProbeTime = new Map<string, number>();
   /** Deferred disconnect timers — grace period before broadcasting peer_leave. */
@@ -225,6 +231,10 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       clearTimeout(this.gossipDebounceTimer);
       this.gossipDebounceTimer = null;
     }
+    if (this.latencySyncTimer) {
+      clearTimeout(this.latencySyncTimer);
+      this.latencySyncTimer = null;
+    }
     for (const timer of this.reconnectTimers.values()) {
       clearTimeout(timer);
     }
@@ -643,14 +653,10 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     const attempt = this.reconnectAttempts.get(channelKey) ?? 0;
     debug("peer", `connectToChannel(${nodeId}): attempt=${attempt} url=${url}`);
 
-    // Use the `ws` package for outbound connections.
-    // Node.js 24+'s built-in WebSocket (undici) defaults binaryType to "blob",
-    // causing binary frames to arrive as Blob instead of Buffer — which
-    // onRawMessage cannot handle, silently dropping encrypted frames (including auth_ok).
-    // The `ws` package defaults to binaryType "nodebuffer", avoiding this issue.
-    let ws: InstanceType<typeof WsWebSocket>;
+    // Use a common WS subprotocol for traffic disguise
+    let ws: WebSocket;
     try {
-      ws = new WsWebSocket(url, ["graphql-transport-ws"]);
+      ws = new WebSocket(url, ["graphql-transport-ws"]);
     } catch (err) {
       debug("peer", `connectToChannel(${nodeId}): WebSocket constructor threw: ${err}`);
       this.scheduleChannelReconnect(nodeId, url);
@@ -977,7 +983,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
     conn.on("message", (frame) => this.onFrame(frame, conn));
     conn.on("latency", (latencyMs) => {
-      this.router.updateActiveChannel(nodeId);
+      const changed = this.router.updateActiveChannel(nodeId);
+      if (changed) this.scheduleLatencySync();
       // Update baseline and check for spike
       const baseline = this.latencyBaselines.get(nodeId) ?? latencyMs;
       const newBaseline = baseline * 0.8 + latencyMs * 0.2;
@@ -1150,7 +1157,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Skip dedup for streaming chunks (same id across many chunks) and response
     // frames (share id with their request — relay would otherwise drop the reply).
     // handoff_input/cancel/status reuse the original handoff_req id.
-    if (frame.id && !SKIP_DEDUP_TYPES.has(frame.type) && this.router.isDuplicate(frame.id)) return;
+    if (frame.id && !skipDedup(frame.type) && this.router.isDuplicate(frame.id)) return;
 
     // Handle peer approval responses locally (don't emit to cluster-service)
     if (frame.type === "peer_approval_res") {
@@ -1244,6 +1251,18 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   /** Last sync version sent to each direct peer. */
   private peerSyncVersions = new Map<string, number>();
 
+  /** Throttled broadcast of peer_sync to all connections when latency changes.
+   *  Coalesces rapid updates into a single sync (max once per 5s). */
+  private scheduleLatencySync() {
+    if (this.latencySyncTimer) return; // already scheduled
+    this.latencySyncTimer = setTimeout(() => {
+      this.latencySyncTimer = null;
+      for (const conn of this.router.getDirectConnections()) {
+        this.sendPeerSync(conn);
+      }
+    }, 5_000);
+  }
+
   private sendPeerSync(conn: Connection) {
     const remoteNodeId = conn.remoteNodeId ?? "";
     const sinceVersion = this.peerSyncVersions.get(remoteNodeId) ?? 0;

package/src/router.ts

@@ -192,10 +192,11 @@ export class Router {
     return false;
   }
 
-  /** Re-evaluate the active (best) channel for a peer based on latency. */
-  updateActiveChannel(nodeId: string) {
+  /** Re-evaluate the active (best) channel for a peer based on latency.
+   *  Returns true if latency changed significantly (sync version bumped). */
+  updateActiveChannel(nodeId: string): boolean {
     const channelSet = this.channels.get(nodeId);
-    if (!channelSet || channelSet.size === 0) return;
+    if (!channelSet || channelSet.size === 0) return false;
 
     let best: Connection | null = null;
     let bestLatency = Infinity;
@@ -213,10 +214,22 @@ export class Router {
       this.connections.set(nodeId, best);
       const route = this.routes.get(nodeId);
       if (route) {
+        const prevLatency = route.latencyMs;
         route.connection = best;
         route.latencyMs = best.latencyMs;
+        // Bump sync version when latency changes significantly (>10% or crosses 0)
+        // so delta peer_sync propagates the update to satellite clients.
+        if (prevLatency !== route.latencyMs && (
+          prevLatency === 0 || route.latencyMs === 0 ||
+          Math.abs(route.latencyMs - prevLatency) / Math.max(prevLatency, 1) > 0.1
+        )) {
+          this.syncVersion++;
+          this.peerVersions.set(nodeId, this.syncVersion);
+          return true;
+        }
       }
     }
+    return false;
   }
 
   /** Get the number of live channels for a peer. */
@@ -537,6 +550,11 @@ export class Router {
     return [...this.connections.values()];
   }
 
+  /** Get nodeIds of all directly connected peers. */
+  getDirectPeerIds(): string[] {
+    return [...this.connections.keys()];
+  }
+
   /** Current sync version for delta protocol. */
   get currentSyncVersion(): number {
     return this.syncVersion;

package/src/types.ts

@@ -388,6 +388,7 @@ export interface DeviceInfo {
   totalMemoryMB: number; // total system memory in MB
   hostname: string; // machine hostname
   openclawVersion?: string; // e.g. "2026.3.7"
+  clawmatrixVersion?: string; // e.g. "0.5.0"
   cwd?: string; // process.cwd() at gateway startup
   workspace?: string; // OpenClaw workspace dir (agents.defaults.workspace)
 }