clawmatrix 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/acp-proxy.ts

@@ -2781,13 +2781,15 @@ async function readFirstUserMessageFromTranscript(transcriptPath: string): Promi
         const msg = parsed?.message;
         if (msg?.role !== "user") continue;
         // Extract text from content (string or array of content blocks)
-        if (typeof msg.content === "string") return msg.content.slice(0, 120);
-        if (Array.isArray(msg.content)) {
+        let raw: string | null = null;
+        if (typeof msg.content === "string") raw = msg.content;
+        else if (Array.isArray(msg.content)) {
           for (const block of msg.content) {
-            if (typeof block === "string") return block.slice(0, 120);
-            if (block?.type === "text" && typeof block.text === "string") return block.text.slice(0, 120);
+            if (typeof block === "string") { raw = block; break; }
+            if (block?.type === "text" && typeof block.text === "string") { raw = block.text; break; }
           }
         }
+        if (raw) return stripEnvelope(stripInboundMetadata(raw)).slice(0, 120) || null;
       } catch {
         // skip malformed lines
       }
@@ -2861,7 +2863,8 @@ async function fetchSessionListFromDisk(): Promise<AcpSessionInfo[]> {
       try {
         const content = await readFileText(storePath);
         const entries: Record<string, { sessionId?: string; updatedAt?: number; displayName?: string; subject?: string; label?: string; acp?: { agent?: string } }> = JSON.parse(content);
-        const agent = agentId;
+        // Use ACP agent type if available, otherwise default to "openclaw" for native sessions
+        const agentDefault = "openclaw";
         // Read all transcripts in parallel (first message + mtime)
         const entryList = Object.entries(entries).filter(([, e]) => e.sessionId);
         const transcriptResults = await Promise.all(
@@ -2885,7 +2888,7 @@ async function fetchSessionListFromDisk(): Promise<AcpSessionInfo[]> {
             title: entry.displayName ?? entry.subject ?? entry.label ?? undefined,
             description: firstMsg ?? undefined,
             updatedAt: effectiveTs ? new Date(effectiveTs).toISOString() : undefined,
-            agent,
+            agent: entry.acp?.agent ?? agentDefault,
           });
         }
       } catch {

package/src/cluster-service.ts

@@ -133,6 +133,12 @@ export class ClusterRuntime {
       this.agentById.set(a.id, a);
       for (const t of a.tags) this.agentsByTag.set(t, a);
     }
+
+    // Wire up active task checker for route probing (prevents switching mid-task)
+    this.peerManager.setActiveTaskChecker((nodeId) => {
+      return this.handoffManager.hasPendingForNode(nodeId)
+        || this.modelProxy.hasPendingForNode(nodeId);
+    });
   }
 
   async start() {
@@ -144,8 +150,11 @@ export class ClusterRuntime {
     this.peerManager.on("peerConnected", (nodeId) => {
       this.logger.info(`[clawmatrix] Peer connected: ${nodeId}`);
       this.refreshDiscoveredModels();
-      this.healthTracker.recordPeerOnline(nodeId, "direct");
+      // Init sync state BEFORE recording the event — recordPeerOnline triggers
+      // broadcastSync which must use the freshly initialized syncState.
+      // Reversing this order causes syncState corruption and infinite sync loops.
       this.healthTracker.initPeerSync(nodeId);
+      this.healthTracker.recordPeerOnline(nodeId, "direct");
     });
 
     this.peerManager.on("peerDisconnected", (nodeId) => {

package/src/config.ts

@@ -51,7 +51,8 @@ const ModelInfoSchema = z.object({
 
 const PeerConfigSchema = z.object({
   nodeId: z.string(),
-  url: z.string(),
+  /** Single URL or array of URLs for multi-channel connections. */
+  url: z.union([z.string(), z.array(z.string()).min(1)]),
 });
 
 const ToolProxyConfigSchema = z.object({

package/src/handoff.ts

@@ -678,6 +678,14 @@ export class HandoffManager {
   }
 
   /** Clean up on shutdown. */
+  /** Check if there are pending outbound handoffs targeting a specific node. */
+  hasPendingForNode(nodeId: string): boolean {
+    for (const p of this.pending.values()) {
+      if (p.targetNodeId === nodeId) return true;
+    }
+    return false;
+  }
+
   destroy() {
     if (this.staleCleanupTimer) {
       clearInterval(this.staleCleanupTimer);

package/src/health-tracker.ts

@@ -79,6 +79,12 @@ export class HealthTracker {
   private compactTimer: ReturnType<typeof setInterval> | null = null;
   private saveTimer: ReturnType<typeof setTimeout> | null = null;
   private dirty = false;
+  /** Debounce timer for broadcastSync (prevents rapid-fire broadcasts). */
+  private broadcastTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Round counter per peer to detect non-converging sync loops. */
+  private syncRounds = new Map<string, number>();
+  private static readonly MAX_SYNC_ROUNDS = 10;
+  private static readonly BROADCAST_DEBOUNCE = 500; // ms
 
   constructor(opts: HealthTrackerOptions) {
     this.nodeId = opts.nodeId;
@@ -119,6 +125,10 @@ export class HealthTracker {
       clearInterval(this.compactTimer);
       this.compactTimer = null;
     }
+    if (this.broadcastTimer) {
+      clearTimeout(this.broadcastTimer);
+      this.broadcastTimer = null;
+    }
     if (this.saveTimer) {
       clearTimeout(this.saveTimer);
       this.saveTimer = null;
@@ -165,6 +175,16 @@ export class HealthTracker {
     const message = new Uint8Array(Buffer.from(frame.payload.data, "base64"));
     const syncKey = peerId;
 
+    // Guard against non-converging sync loops
+    const rounds = (this.syncRounds.get(peerId) ?? 0) + 1;
+    if (rounds > HealthTracker.MAX_SYNC_ROUNDS) {
+      debug(TAG, `sync with ${peerId} exceeded ${HealthTracker.MAX_SYNC_ROUNDS} rounds, resetting`);
+      this.syncStates.set(syncKey, Automerge.initSyncState());
+      this.syncRounds.delete(peerId);
+      return;
+    }
+    this.syncRounds.set(peerId, rounds);
+
     try {
       const syncState = this.syncStates.get(syncKey) ?? Automerge.initSyncState();
       const [newDoc, newSyncState] = Automerge.receiveSyncMessage(this.doc, syncState, message);
@@ -172,18 +192,19 @@ export class HealthTracker {
       this.syncStates.set(syncKey, newSyncState);
       this.scheduleSave();
 
-      // Send our response
+      // Send our response (only if there's something to send)
       this.sendSyncMessage(peerId);
     } catch (err) {
       debug(TAG, `error handling sync from ${peerId}: ${err}`);
     }
   }
 
-  /** Initiate sync with a peer (called on peer connect). */
+  /** Initialize sync state for a peer (called on peer connect).
+   *  Does NOT send a message — the subsequent recordPeerOnline → broadcastSync handles that.
+   *  Sending here would race with broadcastSync and corrupt the sync state. */
   initPeerSync(peerId: string) {
     if (peerId === this.nodeId) return;
     this.syncStates.set(peerId, Automerge.initSyncState());
-    this.sendSyncMessage(peerId);
   }
 
   /** Clean up sync state for a disconnected peer. */
@@ -196,7 +217,11 @@ export class HealthTracker {
     const [newSyncState, message] = Automerge.generateSyncMessage(this.doc, syncState);
     this.syncStates.set(peerId, newSyncState);
 
-    if (!message) return;
+    if (!message) {
+      // Sync converged — reset round counter
+      this.syncRounds.delete(peerId);
+      return;
+    }
 
     debug(TAG, `sending health sync to ${peerId} (${message.byteLength} bytes)`);
 
@@ -214,10 +239,17 @@ export class HealthTracker {
   }
 
   private broadcastSync() {
-    const peers = this.peerManager.router.getAllPeers();
-    for (const peer of peers) {
-      this.sendSyncMessage(peer.nodeId);
-    }
+    // Debounce: multiple events in quick succession → single broadcast
+    if (this.broadcastTimer) return;
+    this.broadcastTimer = setTimeout(() => {
+      this.broadcastTimer = null;
+      // Reset round counters — new broadcast starts fresh sync cycle
+      this.syncRounds.clear();
+      const peers = this.peerManager.router.getAllPeers();
+      for (const peer of peers) {
+        this.sendSyncMessage(peer.nodeId);
+      }
+    }, HealthTracker.BROADCAST_DEBOUNCE);
   }
 
   // ── Timeline aggregation ──────────────────────────────────

package/src/model-proxy.ts

@@ -43,6 +43,7 @@ interface PendingModelReq {
   stream: boolean;
   responseFormat: ResponseFormat;
   model?: string;
+  targetNodeId?: string;
   controller?: ReadableStreamDefaultController;
   encoder?: TextEncoder;
   /** Whether real content (not just setup events) has been sent to the stream. */
@@ -356,6 +357,14 @@ export class ModelProxy {
     this.httpServer.listen(this.config.proxyPort, "127.0.0.1");
   }
 
+  /** Check if there are pending model requests targeting a specific node. */
+  hasPendingForNode(nodeId: string): boolean {
+    for (const p of this.pending.values()) {
+      if (p.targetNodeId === nodeId) return true;
+    }
+    return false;
+  }
+
   stop() {
     if (this.cacheCleanupTimer) {
       clearInterval(this.cacheCleanupTimer);
@@ -653,6 +662,7 @@ export class ModelProxy {
     this.pending.set(requestId, {
       resolve: () => {}, reject: () => {},
       timer, stream: true, responseFormat, model,
+      targetNodeId,
       controller, encoder,
       hasContent: false,
       failoverCandidates,
@@ -827,6 +837,7 @@ export class ModelProxy {
       this.pending.set(requestId, {
         resolve: resolve as (v: unknown) => void,
         reject, timer, stream: false, responseFormat,
+        targetNodeId,
       });
 
       const sent = this.peerManager.sendTo(targetNodeId, frame);

package/src/peer-manager.ts

@@ -91,8 +91,19 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private localCapabilities: NodeCapabilities;
   private httpServer: Server | null = null;
   private wss: WebSocketServer | null = null;
+  /** Reconnect timers keyed by `nodeId|url` for per-channel reconnection. */
   private reconnectTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private reconnectAttempts = new Map<string, number>();
+  /** Track which nodeIds have already completed the full peer join (for multi-channel). */
+  private joinedPeers = new Set<string>();
+  /** All configured URLs per peer (for multi-URL peers). */
+  private peerUrls = new Map<string, string[]>();
+  /** Currently active URL per peer. */
+  private activeUrls = new Map<string, string>();
+  /** Last probe latency per URL (ms). */
+  private urlProbeLatencies = new Map<string, number>();
+  /** Route probe interval timer. */
+  private probeTimer: ReturnType<typeof setInterval> | null = null;
   /** Deferred disconnect timers — grace period before broadcasting peer_leave. */
   private disconnectGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private stopped = false;
@@ -191,10 +202,16 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     for (const peer of this.config.peers) {
       this.connectToPeer(peer);
     }
+    // Start route probing for peers with multiple URLs
+    this.startRouteProbing();
   }
 
   async stop() {
     this.stopped = true;
+    if (this.probeTimer) {
+      clearInterval(this.probeTimer);
+      this.probeTimer = null;
+    }
     if (this.gossipDebounceTimer) {
       clearTimeout(this.gossipDebounceTimer);
       this.gossipDebounceTimer = null;
@@ -226,11 +243,13 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.rateLimiter.destroy();
     this.approvalManager.destroy();
     this.router.destroy();
+    this.joinedPeers.clear();
   }
 
   /** Force-stop without broadcasting or waiting — used when graceful stop times out. */
   forceStop() {
     this.stopped = true;
+    if (this.probeTimer) { clearInterval(this.probeTimer); this.probeTimer = null; }
     for (const timer of this.reconnectTimers.values()) clearTimeout(timer);
     this.reconnectTimers.clear();
     for (const [, timer] of this.disconnectGraceTimers) clearTimeout(timer);
@@ -246,6 +265,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.rateLimiter.destroy();
     this.approvalManager.destroy();
     this.router.destroy();
+    this.joinedPeers.clear();
   }
 
   private closeServers() {
@@ -264,6 +284,143 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     }
   }
 
+  // ── Route probing (for multi-URL peers) ──────────────────────────
+  private static readonly PROBE_INTERVAL = 3_600_000; // 1 hour
+  /** Minimum improvement ratio to trigger a route switch. */
+  private static readonly SWITCH_THRESHOLD = 0.7; // new must be ≤70% of current
+
+  private startRouteProbing() {
+    // Only probe if any peer has multiple URLs
+    const hasMultiUrl = [...this.peerUrls.values()].some((urls) => urls.length > 1);
+    if (!hasMultiUrl) return;
+
+    this.probeTimer = setInterval(() => this.probeAllRoutes(), PeerManager.PROBE_INTERVAL);
+  }
+
+  private async probeAllRoutes() {
+    for (const [nodeId, urls] of this.peerUrls) {
+      if (urls.length <= 1) continue;
+      const activeUrl = this.activeUrls.get(nodeId);
+      for (const url of urls) {
+        if (url === activeUrl) continue;
+        // Probe non-active URLs
+        const latency = await this.probeUrl(url);
+        if (latency !== null) {
+          this.urlProbeLatencies.set(url, latency);
+        }
+      }
+      // Also record active connection's real latency
+      if (activeUrl) {
+        const route = this.router.getRoute(nodeId);
+        if (route && route.latencyMs > 0) {
+          this.urlProbeLatencies.set(activeUrl, route.latencyMs);
+        }
+      }
+      // Evaluate if we should switch
+      this.evaluateRouteSwitch(nodeId);
+    }
+  }
+
+  /**
+   * Probe a URL by measuring HTTP response time (WS server also serves HTTP).
+   * Returns latency in ms, or null if unreachable.
+   */
+  private async probeUrl(wsUrl: string): Promise<number | null> {
+    try {
+      const httpUrl = wsUrl.replace(/^ws(s?):\/\//, "http$1://");
+      const start = Date.now();
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 5_000);
+      try {
+        const res = await fetch(httpUrl, {
+          method: "HEAD",
+          signal: controller.signal,
+          // @ts-ignore — Node.js 18+ supports this
+          keepalive: false,
+        });
+        clearTimeout(timeout);
+        if (res.ok || res.status === 200) {
+          return Date.now() - start;
+        }
+        return null;
+      } catch {
+        clearTimeout(timeout);
+        return null;
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  /** Check if we should switch to a better URL for a peer. */
+  private evaluateRouteSwitch(nodeId: string) {
+    const urls = this.peerUrls.get(nodeId);
+    const activeUrl = this.activeUrls.get(nodeId);
+    if (!urls || !activeUrl || urls.length <= 1) return;
+
+    const currentLatency = this.urlProbeLatencies.get(activeUrl);
+    if (!currentLatency || currentLatency <= 0) return;
+
+    // Find best alternative
+    let bestUrl: string | undefined;
+    let bestLatency = Infinity;
+    for (const url of urls) {
+      if (url === activeUrl) continue;
+      const lat = this.urlProbeLatencies.get(url);
+      if (lat !== undefined && lat < bestLatency) {
+        bestLatency = lat;
+        bestUrl = url;
+      }
+    }
+
+    if (!bestUrl || bestLatency >= currentLatency * PeerManager.SWITCH_THRESHOLD) return;
+
+    // Check if there are active tasks — don't switch mid-task
+    if (this.hasActiveTasks(nodeId)) {
+      debug("probe", `${nodeId}: better route found (${activeUrl} ${currentLatency}ms → ${bestUrl} ${bestLatency}ms) but has active tasks, deferring`);
+      return;
+    }
+
+    debug("probe", `${nodeId}: switching route ${activeUrl} ${currentLatency}ms → ${bestUrl} ${bestLatency}ms`);
+    this.switchRoute(nodeId, bestUrl);
+  }
+
+  /** Callback to check if there are active tasks involving a peer. Set by ClusterRuntime. */
+  private activeTaskChecker: ((nodeId: string) => boolean) | null = null;
+
+  /** Register a callback to check for active tasks (used to prevent route switches mid-task). */
+  setActiveTaskChecker(checker: (nodeId: string) => boolean) {
+    this.activeTaskChecker = checker;
+  }
+
+  /** Check if there are active tasks involving a peer (handoffs, model requests, etc.). */
+  private hasActiveTasks(nodeId: string): boolean {
+    return this.activeTaskChecker?.(nodeId) ?? false;
+  }
+
+  /** Switch the active route for a peer to a new URL. */
+  private switchRoute(nodeId: string, newUrl: string) {
+    this.activeUrls.set(nodeId, newUrl);
+    // Connect to the new URL — the new connection will authenticate and join
+    // as an additional channel briefly, then we close the old one.
+    const oldRoute = this.router.getRoute(nodeId);
+    const oldConn = oldRoute?.connection;
+
+    this.connectToChannel(nodeId, newUrl);
+
+    // Close the old connection after a short delay (give new connection time to establish)
+    if (oldConn?.isOpen) {
+      setTimeout(() => {
+        // Only close if a new connection has taken over
+        const currentRoute = this.router.getRoute(nodeId);
+        if (currentRoute?.connection && currentRoute.connection !== oldConn) {
+          debug("probe", `${nodeId}: closing old channel after route switch`);
+          oldConn.close(1000, "route switch");
+        }
+      }, 5_000);
+    }
+  }
+
   /** Set an HTTP request handler for non-WebSocket requests (e.g. web dashboard). */
   private httpRequestHandler: ((req: IncomingMessage, res: ServerResponse) => boolean) | null = null;
 
@@ -380,26 +537,52 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   // ── Outbound connections (standard WebSocket) ──────────────────
   private connectToPeer(peer: PeerConfig) {
+    const urls = Array.isArray(peer.url) ? peer.url : [peer.url];
+    this.peerUrls.set(peer.nodeId, urls);
+    // Connect to the first URL (or best known from probes)
+    const bestUrl = this.pickBestUrl(peer.nodeId, urls);
+    this.activeUrls.set(peer.nodeId, bestUrl);
+    this.connectToChannel(peer.nodeId, bestUrl);
+  }
+
+  /** Pick the best URL for a peer based on probe latencies. Falls back to first URL. */
+  private pickBestUrl(nodeId: string, urls: string[]): string {
+    if (urls.length <= 1) return urls[0];
+    let bestUrl = urls[0];
+    let bestLatency = Infinity;
+    for (const url of urls) {
+      const lat = this.urlProbeLatencies.get(url);
+      if (lat !== undefined && lat < bestLatency) {
+        bestLatency = lat;
+        bestUrl = url;
+      }
+    }
+    return bestUrl;
+  }
+
+  /** Connect a single channel (URL) for a peer. */
+  private connectToChannel(nodeId: string, url: string) {
     if (this.stopped) {
-      debug("peer", `connectToPeer(${peer.nodeId}): skipped (stopped)`);
+      debug("peer", `connectToChannel(${nodeId}): skipped (stopped)`);
       return;
     }
 
-    const attempt = this.reconnectAttempts.get(peer.nodeId) ?? 0;
-    debug("peer", `connectToPeer(${peer.nodeId}): attempt=${attempt} url=${peer.url}`);
+    const channelKey = `${nodeId}|${url}`;
+    const attempt = this.reconnectAttempts.get(channelKey) ?? 0;
+    debug("peer", `connectToChannel(${nodeId}): attempt=${attempt} url=${url}`);
 
     // Use a common WS subprotocol for traffic disguise
     let ws: WebSocket;
     try {
-      ws = new WebSocket(peer.url, ["graphql-transport-ws"]);
+      ws = new WebSocket(url, ["graphql-transport-ws"]);
     } catch (err) {
-      debug("peer", `connectToPeer(${peer.nodeId}): WebSocket constructor threw: ${err}`);
-      this.scheduleReconnect(peer);
+      debug("peer", `connectToChannel(${nodeId}): WebSocket constructor threw: ${err}`);
+      this.scheduleChannelReconnect(nodeId, url);
       return;
     }
 
     ws.addEventListener("open", () => {
-      debug("peer", `connectToPeer(${peer.nodeId}): ws open`);
+      debug("peer", `connectToChannel(${nodeId}): ws open url=${url}`);
       const conn = new Connection(
         ws,
         "outbound",
@@ -411,8 +594,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       conn.bindWebSocket(ws);
 
       conn.on("authenticated", (caps) => {
-        debug("peer", `connectToPeer(${peer.nodeId}): authenticated`);
-        this.reconnectAttempts.delete(peer.nodeId);
+        debug("peer", `connectToChannel(${nodeId}): authenticated url=${url}`);
+        this.reconnectAttempts.delete(channelKey);
         this.onPeerAuthenticated(conn, caps);
       });
 
@@ -426,7 +609,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     const tryReconnect = () => {
       if (!reconnectScheduled) {
         reconnectScheduled = true;
-        this.scheduleReconnect(peer, lastError);
+        this.scheduleChannelReconnect(nodeId, url, lastError);
       }
     };
 
@@ -438,7 +621,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       // Don't reconnect if this was a self-connection (peer URL points to ourselves).
       // Without this guard, outbound detects self → closes → scheduleReconnect → loop.
       if (ev.code === 4002 && ev.reason === "self-connection") {
-        debug("peer", `connectToPeer(${peer.nodeId}): self-connection, will not reconnect`);
+        debug("peer", `connectToChannel(${nodeId}): self-connection, will not reconnect`);
         return;
       }
       if (!lastError) {
@@ -448,24 +631,65 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     });
   }
 
-  private scheduleReconnect(peer: PeerConfig, reason?: string) {
+  private scheduleChannelReconnect(nodeId: string, url: string, reason?: string) {
     if (this.stopped) {
-      debug("peer", `scheduleReconnect(${peer.nodeId}): skipped (stopped)`);
+      debug("peer", `scheduleChannelReconnect(${nodeId}): skipped (stopped)`);
       return;
     }
-    if (this.reconnectTimers.has(peer.nodeId)) return;
+    const channelKey = `${nodeId}|${url}`;
+    if (this.reconnectTimers.has(channelKey)) return;
+
+    const attempt = this.reconnectAttempts.get(channelKey) ?? 0;
+
+    // On first failure, try an alternative URL immediately (failover)
+    if (attempt === 0) {
+      const urls = this.peerUrls.get(nodeId);
+      if (urls && urls.length > 1) {
+        const altUrl = this.pickNextUrl(nodeId, url, urls);
+        if (altUrl && altUrl !== url) {
+          debug("peer", `scheduleChannelReconnect(${nodeId}): failover ${url} → ${altUrl}`);
+          this.activeUrls.set(nodeId, altUrl);
+          this.reconnectAttempts.set(channelKey, attempt + 1);
+          // Connect to alternative immediately, schedule original for later
+          this.connectToChannel(nodeId, altUrl);
+          const timer = setTimeout(() => {
+            this.reconnectTimers.delete(channelKey);
+            // Only reconnect original URL if not already connected
+            if (!this.joinedPeers.has(nodeId)) {
+              this.connectToChannel(nodeId, url);
+            }
+          }, RECONNECT_MAX);
+          this.reconnectTimers.set(channelKey, timer);
+          return;
+        }
+      }
+    }
 
-    const attempt = this.reconnectAttempts.get(peer.nodeId) ?? 0;
     const delay = Math.min(RECONNECT_BASE * 2 ** attempt, RECONNECT_MAX);
-    this.reconnectAttempts.set(peer.nodeId, attempt + 1);
+    this.reconnectAttempts.set(channelKey, attempt + 1);
     const tag = reason ? ` reason="${reason}"` : "";
-    debug("peer", `scheduleReconnect(${peer.nodeId}): attempt=${attempt} delay=${delay}ms${tag}`);
+    debug("peer", `scheduleChannelReconnect(${nodeId}): attempt=${attempt} delay=${delay}ms url=${url}${tag}`);
 
     const timer = setTimeout(() => {
-      this.reconnectTimers.delete(peer.nodeId);
-      this.connectToPeer(peer);
+      this.reconnectTimers.delete(channelKey);
+      this.connectToChannel(nodeId, url);
     }, delay);
-    this.reconnectTimers.set(peer.nodeId, timer);
+    this.reconnectTimers.set(channelKey, timer);
+  }
+
+  /** Pick the next best URL to try, excluding the current one. */
+  private pickNextUrl(nodeId: string, currentUrl: string, urls: string[]): string | undefined {
+    let bestUrl: string | undefined;
+    let bestLatency = Infinity;
+    for (const url of urls) {
+      if (url === currentUrl) continue;
+      const lat = this.urlProbeLatencies.get(url) ?? 10_000;
+      if (lat < bestLatency) {
+        bestLatency = lat;
+        bestUrl = url;
+      }
+    }
+    return bestUrl ?? urls.find((u) => u !== currentUrl);
   }
 
   // ── Peer lifecycle ─────────────────────────────────────────────
@@ -565,6 +789,23 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Cancel disconnect grace timer if the peer is reconnecting
     const wasInGrace = this.cancelDisconnectGrace(nodeId);
 
+    // Check if this peer already has an active connection (additional channel)
+    const isAdditionalChannel = this.joinedPeers.has(nodeId);
+
+    if (isAdditionalChannel) {
+      // Additional channel — just add to the channel pool, no peer_join broadcast
+      this.router.addChannel(nodeId, conn);
+      conn.on("message", (frame) => this.onFrame(frame, conn));
+      conn.on("latency", () => this.router.updateActiveChannel(nodeId));
+      conn.on("close", () => this.onChannelDisconnected(conn));
+      const channelCount = this.router.getChannelCount(nodeId);
+      debug("peer", `completePeerJoin(${nodeId}): additional channel added (total=${channelCount})`);
+      audit("channel_add", { nodeId, detail: `channels=${channelCount}` });
+      return;
+    }
+
+    // First channel — full join flow
+
     // If there's an existing connection for this nodeId (e.g. peer reconnected
     // while old TCP hadn't closed yet), close it AFTER overwriting the route so
     // the stale-close guard in onPeerDisconnected correctly skips cleanup.
@@ -580,9 +821,11 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       oldConn.close(1000, "replaced by new connection");
     }
 
+    this.joinedPeers.add(nodeId);
+
     conn.on("message", (frame) => this.onFrame(frame, conn));
-    conn.on("latency", (ms) => this.router.updateLatency(nodeId, ms));
-    conn.on("close", () => this.onPeerDisconnected(conn));
+    conn.on("latency", () => this.router.updateActiveChannel(nodeId));
+    conn.on("close", () => this.onChannelDisconnected(conn));
 
     this.sendPeerSync(conn);
 
@@ -615,6 +858,25 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.emit("peerConnected", nodeId);
   }
 
+  /** Handle a single channel disconnecting (multi-channel aware). */
+  private onChannelDisconnected(conn: Connection) {
+    const nodeId = conn.remoteNodeId;
+    if (!nodeId) return;
+
+    // Remove this channel from the pool
+    const hasRemaining = this.router.removeChannel(nodeId, conn);
+    if (hasRemaining) {
+      // Other channels still alive — just log, no peer_leave
+      const channelCount = this.router.getChannelCount(nodeId);
+      debug("peer", `onChannelDisconnected(${nodeId}): channel lost, ${channelCount} remaining`);
+      audit("channel_remove", { nodeId, detail: `channels=${channelCount}` });
+      return;
+    }
+
+    // Last channel gone — proceed with peer disconnect logic
+    this.onPeerDisconnected(conn);
+  }
+
   private onPeerDisconnected(conn: Connection) {
     const nodeId = conn.remoteNodeId;
     if (!nodeId) return;
@@ -632,6 +894,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Same-nodeId 本地客户端断开：仅清理路由，不广播 peer_leave
     if (nodeId === this.config.nodeId) {
       this.router.removePeer(nodeId);
+      this.joinedPeers.delete(nodeId);
       return;
     }
 
@@ -680,6 +943,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
     audit("peer_leave", { nodeId });
     this.router.removePeer(nodeId);
+    this.joinedPeers.delete(nodeId);
 
     // Remove satellite contexts that were only reachable via this peer
     for (let i = this.satelliteContexts.length - 1; i >= 0; i--) {

package/src/router.ts

@@ -30,7 +30,9 @@ export class Router {
   private localToolProxy?: ToolProxyInfo;
   private localAcpAgents?: AcpAgentInfo[];
   private routes = new Map<string, RouteEntry>();
-  private connections = new Map<string, Connection>(); // nodeId → direct connection
+  private connections = new Map<string, Connection>(); // nodeId → active (best) direct connection
+  /** All live channels per nodeId (multi-channel support). */
+  private channels = new Map<string, Set<Connection>>();
   /** Double-map dedup: current window + previous window. Rotated periodically. */
   private seenCurrent = new Map<string, true>();
   private seenPrevious = new Map<string, true>();
@@ -128,6 +130,7 @@ export class Router {
     this.seenCurrent.clear();
     this.seenPrevious.clear();
     this.failedRequests.clear();
+    this.channels.clear();
   }
 
   // ── Route table management ─────────────────────────────────────
@@ -139,6 +142,10 @@ export class Router {
     const old = this.routes.get(nodeId);
     if (old) this.unindexEntry(old);
     this.connections.set(nodeId, connection);
+    // Add to channel set
+    let channelSet = this.channels.get(nodeId);
+    if (!channelSet) { channelSet = new Set(); this.channels.set(nodeId, channelSet); }
+    channelSet.add(connection);
     const entry: RouteEntry = {
       nodeId,
       agents: capabilities.agents,
@@ -157,6 +164,74 @@ export class Router {
     this.indexEntry(entry);
   }
 
+  /** Add an additional channel to an existing peer (multi-channel). */
+  addChannel(nodeId: string, connection: Connection) {
+    let channelSet = this.channels.get(nodeId);
+    if (!channelSet) { channelSet = new Set(); this.channels.set(nodeId, channelSet); }
+    channelSet.add(connection);
+    this.updateActiveChannel(nodeId);
+  }
+
+  /** Remove a single channel. Returns true if the peer still has live channels. */
+  removeChannel(nodeId: string, connection: Connection): boolean {
+    const channelSet = this.channels.get(nodeId);
+    if (channelSet) {
+      channelSet.delete(connection);
+      if (channelSet.size === 0) {
+        this.channels.delete(nodeId);
+        return false;
+      }
+      // Pick new active channel
+      this.updateActiveChannel(nodeId);
+      return true;
+    }
+    return false;
+  }
+
+  /** Re-evaluate the active (best) channel for a peer based on latency. */
+  updateActiveChannel(nodeId: string) {
+    const channelSet = this.channels.get(nodeId);
+    if (!channelSet || channelSet.size === 0) return;
+
+    let best: Connection | null = null;
+    let bestLatency = Infinity;
+    for (const conn of channelSet) {
+      if (!conn.isOpen) continue;
+      // Prefer lower latency; treat 0 (unmeasured) as high
+      const lat = conn.latencyMs > 0 ? conn.latencyMs : 10_000;
+      if (lat < bestLatency) {
+        bestLatency = lat;
+        best = conn;
+      }
+    }
+
+    if (best) {
+      this.connections.set(nodeId, best);
+      const route = this.routes.get(nodeId);
+      if (route) {
+        route.connection = best;
+        route.latencyMs = best.latencyMs;
+      }
+    }
+  }
+
+  /** Get the number of live channels for a peer. */
+  getChannelCount(nodeId: string): number {
+    const channelSet = this.channels.get(nodeId);
+    if (!channelSet) return 0;
+    let count = 0;
+    for (const conn of channelSet) {
+      if (conn.isOpen) count++;
+    }
+    return count;
+  }
+
+  /** Get all channels for a peer (for diagnostics/status). */
+  getChannels(nodeId: string): Connection[] {
+    const channelSet = this.channels.get(nodeId);
+    return channelSet ? [...channelSet] : [];
+  }
+
   addRelayPeer(peer: PeerInfo, viaNodeId: string) {
     // Don't add ourselves
     if (peer.nodeId === this.nodeId) return;
@@ -192,6 +267,7 @@ export class Router {
 
   removePeer(nodeId: string) {
     this.connections.delete(nodeId);
+    this.channels.delete(nodeId);
     const removed = this.routes.get(nodeId);
     if (removed) {
       this.unindexEntry(removed);
@@ -346,11 +422,27 @@ export class Router {
     const route = this.routes.get(targetNodeId);
     if (!route) return false;
 
+    // Try active connection first
     if (route.connection?.isOpen) {
       route.connection.send(frame);
       return true;
     }
 
+    // Fallback: try other channels (multi-channel failover)
+    const channelSet = this.channels.get(targetNodeId);
+    if (channelSet) {
+      for (const conn of channelSet) {
+        if (conn.isOpen) {
+          conn.send(frame);
+          // Promote to active
+          this.connections.set(targetNodeId, conn);
+          route.connection = conn;
+          route.latencyMs = conn.latencyMs;
+          return true;
+        }
+      }
+    }
+
     // Relay through intermediate node
     if (route.reachableVia) {
       const relay = this.connections.get(route.reachableVia);

package/src/tools/cluster-peers.ts

@@ -41,6 +41,7 @@ export function createClusterPeersTool(): AnyAgentTool {
             const sentinelOnline = sentinelStatus === "direct" || sentinelStatus === "relay";
             const effectiveStatus = status === "unreachable" && sentinelOnline ? "sentinel-only" : status;
 
+            const channelCount = runtime.peerManager.router.getChannelCount(entry.nodeId);
             return {
               nodeId: entry.nodeId,
               agents: entry.agents.map((a) => ({
@@ -53,6 +54,7 @@ export function createClusterPeersTool(): AnyAgentTool {
               tools: entry.toolProxy?.enabled ? (entry.toolProxy.allow ?? []) : [],
               status: effectiveStatus,
               latencyMs: entry.latencyMs,
+              ...(channelCount > 1 ? { channels: channelCount } : {}),
               ...(hasSentinel ? {
                 sentinel: sentinelOnline ? "online" : "offline",
               } : {}),