agent-comms 1.13.0 → 1.15.0

package/dist/core/mesh-store.js

@@ -1,74 +1,30 @@
 /**
- * MeshStore — TCP localhost peer mesh for agent communication.
+ * MeshStore — transport-agnostic peer mesh for agent communication.
  *
  * Each bridge instance is a peer in the mesh. Peers discover each other
  * via a coordinator (the first instance to bind the well-known port).
  * All state is held in memory and synchronised between peers.
- * Delivery events are pushed directly over TCP — no polling, no filesystem.
+ * Delivery events are pushed directly over the transport — no polling,
+ * no filesystem.
  *
- * Falls back to FileStore if the mesh is unavailable.
+ * Transport is injected via the constructor. TcpTransport for localhost
+ * TCP, TlsTransport for encrypted connections, etc.
  */
-import * as net from "node:net";
+import * as os from "node:os";
 import { nanoid } from "./nanoid.js";
 import { CommsError } from "./store.js";
+import { TcpTransport } from "./tcp-transport.js";
+import { dmKey } from "./wire-protocol.js";
+import { DiscoveryManager } from "./discovery.js";
+import { MdnsDiscoveryBackend } from "./discovery-mdns.js";
+import { TailscaleDiscoveryBackend } from "./discovery-tailscale.js";
+import { FederationManager } from "./federation.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const DEFAULT_COORDINATOR_PORT = 19876;
 const COORDINATOR_HOST = "127.0.0.1";
 // ---------------------------------------------------------------------------
-// Framing
-// ---------------------------------------------------------------------------
-function encode(msg) {
-    return JSON.stringify(msg) + "\n";
-}
-class MessageBuffer {
-    buffer = "";
-    append(data) {
-        this.buffer += data;
-        const results = [];
-        let idx = this.buffer.indexOf("\n");
-        while (idx !== -1) {
-            const line = this.buffer.slice(0, idx);
-            this.buffer = this.buffer.slice(idx + 1);
-            if (line.length > 0) {
-                try {
-                    results.push(JSON.parse(line));
-                }
-                catch {
-                    /* skip malformed lines */
-                }
-            }
-            idx = this.buffer.indexOf("\n");
-        }
-        return results;
-    }
-}
-function isMeshMessage(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    if (!("method" in value))
-        return false;
-    return typeof value.method === "string";
-}
-function dmKey(a, b) {
-    const sorted = [a, b].sort();
-    return `${sorted[0] ?? a}--${sorted[1] ?? b}`;
-}
-// ---------------------------------------------------------------------------
-// Async socket write
-// ---------------------------------------------------------------------------
-function writeAsync(socket, data) {
-    return new Promise((resolve, reject) => {
-        socket.write(data, "utf-8", (err) => {
-            if (err)
-                reject(err);
-            else
-                resolve();
-        });
-    });
-}
-// ---------------------------------------------------------------------------
 // MeshStore
 // ---------------------------------------------------------------------------
 export class MeshStore {
@@ -81,157 +37,123 @@ export class MeshStore {
     dms = new Map();
     deliveryQueues = new Map();
     identityCache = new Map();
-    dataServer;
-    dataPort = 0;
-    coordinatorServer;
-    isCoordinator = false;
-    peerConnections = new Map();
-    /** All sockets accepted by the data server — destroyed on shutdown. */
-    dataServerSockets = new Set();
-    /** All sockets accepted by the coordinator server — destroyed on shutdown. */
-    coordinatorServerSockets = new Set();
-    /** Socket connected to the coordinator (client side) — destroyed on shutdown. */
-    coordinatorSocket;
+    transport;
     peerInfo = new Map();
     staleCheckTimer;
+    isShutDown = false;
+    pendingMarkReadTimers = [];
+    // -- Pending inbound connections awaiting approval --
+    pendingInboundConnections = new Map();
     onDelivery;
+    /** Fires for every state patch — both locally generated and remote. */
+    onPatch;
+    /** Serialise the full mesh state for state_sync messages. */
+    serialise() {
+        return {
+            agents: Object.fromEntries(this.agents),
+            rooms: Object.fromEntries(this.rooms),
+            messages: Object.fromEntries(this.messages),
+            dms: Object.fromEntries(this.dms),
+        };
+    }
+    lastLocalDeliveryKey;
+    localDeliveryKeys = new Set();
+    discovery;
+    federation;
     constructor(coordinatorPort = DEFAULT_COORDINATOR_PORT) {
         this.peerId = nanoid(8);
         this.startedAt = new Date().toISOString();
         this.coordinatorPort = coordinatorPort;
+        // Wire up transport with this store's event handlers.
+        // TcpTransport is the default; callers can replace via setTransport().
+        this.transport = new TcpTransport(this.events);
+        // Discovery manager — registers available backends
+        this.discovery = new DiscoveryManager();
+        this.discovery.registerBackend(new MdnsDiscoveryBackend());
+        this.discovery.registerBackend(new TailscaleDiscoveryBackend());
+        // Federation manager — coordinator-to-coordinator links
+        this.federation = new FederationManager(this.peerId, // mesh ID is the coordinator's peer ID
+        `mesh-${this.peerId}`, {
+            onAgentVisible: (agent) => this.handleFedAgentVisible(agent),
+            onAgentGone: (agentId) => this.handleFedAgentGone(agentId),
+            onRoomMessage: (roomId, message) => this.handleFedRoomMessage(roomId, message),
+            onRoomJoin: (roomId, agentId, agentName) => this.handleFedRoomJoin(roomId, agentId, agentName),
+            onRoomLeave: (roomId, agentId) => this.handleFedRoomLeave(roomId, agentId),
+            getVisibleAgents: () => this.getVisibleAgentsForFed(),
+            getFederatedRoomMemberships: () => this.getFederatedRoomMembershipsForFed(),
+        });
+    }
+    /** Replace the transport (e.g. with TlsTransport for encrypted connections). */
+    setTransport(transport) {
+        this.transport = transport;
     }
     // -----------------------------------------------------------------------
     // Mesh lifecycle
     // -----------------------------------------------------------------------
     async init() {
-        await this.startDataServer();
-        await this.tryJoinMesh();
-        // Unref all root handles so the event loop can exit when pi shuts down.
-        // Sockets/servers still function normally for I/O but don't keep the
-        // process alive. shutdown() will destroy them explicitly.
-        this.dataServer?.unref();
-        this.coordinatorServer?.unref();
-        this.coordinatorSocket?.unref();
-    }
-    startDataServer() {
-        return new Promise((resolve, reject) => {
-            this.dataServer = net.createServer((socket) => {
-                this.handleDataConnection(socket);
-            });
-            this.dataServer.listen(0, COORDINATOR_HOST, () => {
-                const addr = this.dataServer?.address();
-                if (addr && typeof addr === "object") {
-                    this.dataPort = addr.port;
-                }
-                resolve();
-            });
-            this.dataServer.on("error", reject);
+        await this.transport.startDataServer();
+        // Register our own peer info
+        this.peerInfo.set(this.peerId, {
+            id: this.peerId,
+            port: this.transport.dataPort,
+            startedAt: this.startedAt,
         });
-    }
-    async tryJoinMesh() {
-        try {
-            await this.connectToCoordinator();
-        }
-        catch {
-            await this.becomeCoordinator();
-        }
-    }
-    connectToCoordinator() {
-        return new Promise((resolve, reject) => {
-            const socket = net.createConnection({ port: this.coordinatorPort, host: COORDINATOR_HOST }, () => {
-                this.coordinatorSocket = socket;
-                const intro = {
-                    method: "introduce",
-                    peerId: this.peerId,
-                    dataPort: this.dataPort,
-                };
-                socket.write(encode(intro));
-                // Read the peer_list response
-                const buf = new MessageBuffer();
-                socket.on("data", (data) => {
-                    const items = buf.append(data.toString());
-                    for (const item of items) {
-                        if (isMeshMessage(item)) {
-                            this.handleCoordinatorResponse(item);
+        // Try joining an existing mesh; fall back to becoming coordinator.
+        // If becomeCoordinator fails with EADDRINUSE (another process won the race),
+        // retry connecting — the new coordinator should be ready by now.
+        const MAX_RETRIES = 3;
+        const RETRY_DELAY_MS = 200;
+        let connected = false;
+        let lastError;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                await this.transport.connectToCoordinator(COORDINATOR_HOST, this.coordinatorPort, this.peerId, this.transport.dataPort);
+                connected = true;
+                break;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                // Only try to become coordinator on the first attempt
+                if (attempt === 0) {
+                    try {
+                        await this.transport.becomeCoordinator(COORDINATOR_HOST, this.coordinatorPort);
+                        this.startStaleCheck();
+                        connected = true;
+                        break;
+                    }
+                    catch (coordErr) {
+                        const msg = coordErr instanceof Error ? coordErr.message : String(coordErr);
+                        if (!msg.includes("EADDRINUSE")) {
+                            throw coordErr;
                         }
+                        // EADDRINUSE — another process became coordinator. Retry connect.
                     }
-                });
-                socket.on("error", () => {
-                    /* ignore late errors */
-                });
-                clearTimeout(timer);
-                resolve();
-            });
-            const timer = setTimeout(() => {
-                socket.destroy();
-                reject(new Error("Coordinator connection timeout"));
-            }, 2000);
-            socket.on("error", (err) => {
-                clearTimeout(timer);
-                socket.destroy();
-                reject(err);
-            });
-        });
-    }
-    handleCoordinatorResponse(msg) {
-        if (msg.method === "peer_list") {
-            for (const peer of msg.peers) {
-                this.peerInfo.set(peer.id, peer);
-                void this.connectToPeerData(peer);
+                }
+                // Wait before retrying
+                if (attempt < MAX_RETRIES - 1) {
+                    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+                }
             }
         }
-        else if (msg.method === "peer_joined") {
-            this.peerInfo.set(msg.peer.id, msg.peer);
-            void this.connectToPeerData(msg.peer);
+        if (!connected) {
+            throw new Error(`Failed to join or create mesh on port ${String(this.coordinatorPort)}: ${lastError?.message ?? "unknown error"}`);
         }
-    }
-    becomeCoordinator() {
-        return new Promise((resolve, reject) => {
-            this.coordinatorServer = net.createServer((socket) => {
-                this.handleCoordinatorConnection(socket);
-            });
-            this.coordinatorServer.listen(this.coordinatorPort, COORDINATOR_HOST, () => {
-                this.isCoordinator = true;
-                this.startStaleCheck();
-                this.peerInfo.set(this.peerId, {
-                    id: this.peerId,
-                    port: this.dataPort,
-                    startedAt: this.startedAt,
-                });
-                resolve();
-            });
-            this.coordinatorServer.on("error", (err) => {
-                const isAddrInUse = err instanceof Error && "code" in err && err.code === "EADDRINUSE";
-                if (isAddrInUse) {
-                    this.coordinatorServer = undefined;
-                    void this.connectToCoordinator().then(resolve, reject);
-                }
-                else {
-                    reject(err instanceof Error ? err : new Error(String(err)));
-                }
-            });
-        });
+        this.transport.unref();
     }
     // -----------------------------------------------------------------------
-    // Coordinator protocol
+    // TransportEvents — callbacks from the transport layer
     // -----------------------------------------------------------------------
-    handleCoordinatorConnection(socket) {
-        this.coordinatorServerSockets.add(socket);
-        socket.on("close", () => this.coordinatorServerSockets.delete(socket));
-        socket.on("error", () => {
-            this.coordinatorServerSockets.delete(socket);
-        });
-        const buffer = new MessageBuffer();
-        socket.on("data", (data) => {
-            const items = buffer.append(data.toString());
-            for (const item of items) {
-                if (isMeshMessage(item) && item.method === "introduce") {
-                    void this.handleIntroduction(socket, item);
-                }
-            }
-        });
+    handlePeerList(peers) {
+        for (const peer of peers) {
+            this.peerInfo.set(peer.id, peer);
+            void this.transport.connectToPeer(peer, this.peerId);
+        }
+    }
+    handlePeerJoined(peer) {
+        this.peerInfo.set(peer.id, peer);
+        void this.transport.connectToPeer(peer, this.peerId);
     }
-    async handleIntroduction(socket, msg) {
+    async handleIntroduction(handle, msg) {
         const newPeer = {
             id: msg.peerId,
             port: msg.dataPort,
@@ -243,45 +165,29 @@ export class MeshStore {
             method: "peer_list",
             peers: [...this.peerInfo.values()],
         };
-        await writeAsync(socket, encode(peerList));
-        // Broadcast arrival to all existing data connections
+        await this.transport.send(handle, peerList);
+        // Broadcast arrival to all existing peers
         const joined = { method: "peer_joined", peer: newPeer };
-        await this.broadcastToDataConnections(joined);
+        await this.transport.broadcast(joined);
         // Connect to the new peer's data server
-        void this.connectToPeerData(newPeer);
+        void this.transport.connectToPeer(newPeer, this.peerId);
     }
-    // -----------------------------------------------------------------------
-    // Data connections
-    // -----------------------------------------------------------------------
-    handleDataConnection(socket) {
-        this.dataServerSockets.add(socket);
-        socket.on("close", () => this.dataServerSockets.delete(socket));
-        const buffer = new MessageBuffer();
-        let remotePeerId;
-        socket.on("data", (data) => {
-            const items = buffer.append(data.toString());
-            for (const item of items) {
-                if (isMeshMessage(item)) {
-                    void this.handleDataMessage(item);
-                    if (item.method === "pong") {
-                        remotePeerId = item.peerId;
-                    }
-                }
-            }
-            if (remotePeerId && !this.peerConnections.has(remotePeerId)) {
-                this.peerConnections.set(remotePeerId, { socket, buffer });
-            }
-        });
-        socket.on("close", () => {
-            if (remotePeerId)
-                this.peerConnections.delete(remotePeerId);
-        });
-        socket.on("error", () => {
-            if (remotePeerId)
-                this.peerConnections.delete(remotePeerId);
-        });
+    async handlePeerConnected(handle, _info) {
+        // If we have state and the peer doesn't, send state sync
+        if (this.agents.size > 0) {
+            const state = {
+                agents: Object.fromEntries(this.agents),
+                rooms: Object.fromEntries(this.rooms),
+                messages: Object.fromEntries(this.messages),
+                dms: Object.fromEntries(this.dms),
+            };
+            await this.transport.send(handle, {
+                method: "state_sync",
+                state,
+            });
+        }
     }
-    async handleDataMessage(msg) {
+    async handleDataMessage(handle, msg) {
         if (msg.method === "state_sync") {
             // Merge — don't replace — so our own state isn't lost
             const incoming = {
@@ -311,11 +217,153 @@ export class MeshStore {
             await this.applyPatch(msg.patch);
         }
     }
+    async handleBecomeCoordinator(peerList) {
+        // Take over as coordinator using the data server we already have
+        await this.transport.becomeCoordinator(COORDINATOR_HOST, this.coordinatorPort);
+        this.peerInfo.clear();
+        for (const peer of peerList) {
+            this.peerInfo.set(peer.id, peer);
+            void this.transport.connectToPeer(peer, this.peerId);
+        }
+        this.startStaleCheck();
+    }
+    handlePeerDisconnected(handle) {
+        this.peerInfo.delete(handle.id);
+    }
+    // -----------------------------------------------------------------------
+    // Connection approval
+    // -----------------------------------------------------------------------
+    handleConnectionRequest(handle, request) {
+        this.pendingInboundConnections.set(handle.id, {
+            peerId: request.peerId,
+            dataPort: request.dataPort,
+            name: request.name,
+            fingerprint: request.fingerprint,
+        });
+        // Deliver connection_request event to the owning agent
+        const connectionId = handle.id;
+        const event = {
+            type: "connection_request",
+            connectionId,
+            peerId: request.peerId,
+            dataPort: request.dataPort,
+            name: request.name,
+            fingerprint: request.fingerprint,
+        };
+        const arr = this.deliveryQueues.get(this.peerId) ?? [];
+        arr.push(event);
+        this.deliveryQueues.set(this.peerId, arr);
+        if (this.onDelivery) {
+            void this.onDelivery(this.peerId, event);
+        }
+    }
+    /** Accept a pending inbound connection. */
+    async acceptConnection(connectionId) {
+        const pending = this.pendingInboundConnections.get(connectionId);
+        if (!pending) {
+            throw new Error(`No pending connection ${connectionId}`);
+        }
+        this.pendingInboundConnections.delete(connectionId);
+        const handle = { id: connectionId };
+        await this.transport.acceptConnection(handle);
+    }
+    /** Reject a pending inbound connection. */
+    async rejectConnection(connectionId, reason) {
+        const pending = this.pendingInboundConnections.get(connectionId);
+        if (!pending) {
+            throw new Error(`No pending connection ${connectionId}`);
+        }
+        this.pendingInboundConnections.delete(connectionId);
+        const handle = { id: connectionId };
+        await this.transport.rejectConnection(handle, reason);
+    }
+    /** List all pending inbound connections awaiting approval. */
+    listPendingConnections() {
+        return [...this.pendingInboundConnections.entries()].map(([id, info]) => ({
+            connectionId: id,
+            ...info,
+        }));
+    }
+    /** Initiate an outbound connection to a remote coordinator requiring approval.
+     *  Fires the connect_request and returns immediately. The connection
+     *  completes asynchronously when the coordinator accepts or rejects. */
+    async connectToRemote(host, port) {
+        const agent = this.agents.get(this.peerId);
+        // Fire-and-forget: don't await the full approval handshake.
+        // The coordinator will either accept (triggering normal introduction flow)
+        // or reject (closing the socket). Handle rejection to avoid unhandled rejection.
+        this.transport
+            .connectToRemote(host, port, this.peerId, this.transport.dataPort, agent?.name ?? "", "")
+            .catch((err) => {
+            // Rejection is expected when the coordinator denies the connection.
+            // Log silently — the calling tool already returned success.
+            void err;
+        });
+    }
+    /** Start only the data server without connecting to a coordinator.
+     *  Used for testing scenarios where the peer connects via connectToRemote. */
+    async startDataServerOnly() {
+        await this.transport.startDataServer();
+        this.peerInfo.set(this.peerId, {
+            id: this.peerId,
+            port: this.transport.dataPort,
+            startedAt: this.startedAt,
+        });
+        this.transport.unref();
+    }
+    // -----------------------------------------------------------------------
+    // Transport events accessor (for bridges to wire up)
+    // -----------------------------------------------------------------------
+    /** Returns the TransportEvents object that bridges should pass to the transport constructor. */
+    get events() {
+        return {
+            onMessage: (handle, msg) => {
+                void this.handleDataMessage(handle, msg);
+            },
+            onPeerConnected: (handle, info) => {
+                void this.handlePeerConnected(handle, info);
+            },
+            onPeerDisconnected: (handle) => {
+                this.handlePeerDisconnected(handle);
+            },
+            onIntroduction: (handle, msg) => {
+                void this.handleIntroduction(handle, msg);
+            },
+            onPeerList: (peers) => {
+                this.handlePeerList(peers);
+            },
+            onPeerJoined: (peer) => {
+                this.handlePeerJoined(peer);
+            },
+            onBecomeCoordinator: (peerList) => {
+                void this.handleBecomeCoordinator(peerList);
+            },
+            onConnectionRequest: (handle, request) => {
+                this.handleConnectionRequest(handle, request);
+            },
+        };
+    }
+    // -----------------------------------------------------------------------
+    // State patch application
+    // -----------------------------------------------------------------------
     async applyPatch(patch) {
         switch (patch.type) {
-            case "agent_upsert":
-                this.agents.set(patch.agent.id, patch.agent);
+            case "agent_upsert": {
+                // Merge subscribedRooms to avoid losing local room memberships.
+                const existingAgent = this.agents.get(patch.agent.id);
+                if (existingAgent) {
+                    const merged = patch.agent;
+                    for (const r of existingAgent.subscribedRooms) {
+                        if (!merged.subscribedRooms.includes(r))
+                            merged.subscribedRooms.push(r);
+                    }
+                    this.agents.set(merged.id, merged);
+                }
+                else {
+                    this.agents.set(patch.agent.id, patch.agent);
+                }
                 break;
+            }
             case "agent_offline": {
                 const agent = this.agents.get(patch.agentId);
                 if (agent) {
@@ -324,9 +372,23 @@ export class MeshStore {
                 }
                 break;
             }
-            case "room_upsert":
-                this.rooms.set(patch.room.id, patch.room);
+            case "room_upsert": {
+                // Merge members rather than overwriting — last-write-wins can lose
+                // members added locally when a remote patch arrives with a stale list.
+                const existing = this.rooms.get(patch.room.id);
+                if (existing) {
+                    const merged = patch.room;
+                    for (const m of existing.members) {
+                        if (!merged.members.includes(m))
+                            merged.members.push(m);
+                    }
+                    this.rooms.set(merged.id, merged);
+                }
+                else {
+                    this.rooms.set(patch.room.id, patch.room);
+                }
                 break;
+            }
             case "room_delete":
                 this.rooms.delete(patch.roomId);
                 break;
@@ -347,14 +409,35 @@ export class MeshStore {
                 arr.push(patch.event);
                 this.deliveryQueues.set(patch.agentId, arr);
                 if (patch.agentId === this.peerId && this.onDelivery) {
-                    void this.onDelivery(patch.agentId, patch.event);
-                    // Auto-mark read — push bridges consume immediately
-                    if (patch.event.type === "room_message") {
-                        await this.markRead(patch.event.message.id, this.peerId, patch.event.message.room);
-                    }
-                    else if (patch.event.type === "dm") {
-                        await this.markRead(patch.event.message.id, this.peerId);
+                    // Deduplicate against local deliveries
+                    const eventKey = JSON.stringify(patch.event);
+                    if (this.localDeliveryKeys.has(eventKey))
+                        break;
+                    this.localDeliveryKeys.add(eventKey);
+                    if (this.localDeliveryKeys.size > 50) {
+                        const oldest = this.localDeliveryKeys.values().next().value;
+                        if (oldest !== undefined)
+                            this.localDeliveryKeys.delete(oldest);
                     }
+                    void this.onDelivery(patch.agentId, patch.event);
+                    // Auto-mark read — scheduled as a macrotask to yield to the event
+                    // loop. Without this yield, the delivery → markRead → broadcast
+                    // → peer receives → handleDataMessage chain monopolises the
+                    // microtask queue and starves macrotasks (timers, new connections,
+                    // sendRoomMessage return values).
+                    const evt = patch.event;
+                    const timer = setTimeout(() => {
+                        if (this.isShutDown)
+                            return;
+                        if (evt.type === "room_message") {
+                            void this.markRead(evt.message.id, this.peerId, evt.message.room);
+                        }
+                        else if (evt.type === "dm") {
+                            void this.markRead(evt.message.id, this.peerId);
+                        }
+                    }, 0);
+                    if (!this.isShutDown)
+                        this.pendingMarkReadTimers.push(timer);
                 }
                 break;
             }
@@ -363,63 +446,18 @@ export class MeshStore {
                 break;
             }
         }
-    }
-    async connectToPeerData(peer) {
-        if (peer.id === this.peerId)
-            return;
-        if (this.peerConnections.has(peer.id))
-            return;
-        return new Promise((resolve) => {
-            const socket = net.createConnection({ port: peer.port, host: COORDINATOR_HOST }, () => {
-                const buf = new MessageBuffer();
-                this.peerConnections.set(peer.id, { socket, buffer: buf });
-                // Identify ourselves
-                const pong = { method: "pong", peerId: this.peerId };
-                socket.write(encode(pong));
-                // If we have state and peer doesn't, send state sync
-                if (this.agents.size > 0) {
-                    const state = {
-                        agents: Object.fromEntries(this.agents),
-                        rooms: Object.fromEntries(this.rooms),
-                        messages: Object.fromEntries(this.messages),
-                        dms: Object.fromEntries(this.dms),
-                    };
-                    socket.write(encode({ method: "state_sync", state }));
-                }
-                // Wire up ongoing message handling
-                socket.on("data", (data) => {
-                    const items = buf.append(data.toString());
-                    for (const item of items) {
-                        if (isMeshMessage(item)) {
-                            void this.handleDataMessage(item);
-                        }
-                    }
-                });
-                resolve();
-            });
-            socket.on("close", () => this.peerConnections.delete(peer.id));
-            socket.on("error", () => {
-                this.peerConnections.delete(peer.id);
-                socket.destroy();
-                resolve();
-            });
-        });
+        if (this.onPatch) {
+            await this.onPatch(patch);
+        }
     }
     // -----------------------------------------------------------------------
-    // Broadcast (async — writes to TCP sockets)
+    // Broadcast
     // -----------------------------------------------------------------------
-    async broadcastToDataConnections(msg) {
-        const data = encode(msg);
-        const writes = [];
-        for (const [, peer] of this.peerConnections) {
-            writes.push(writeAsync(peer.socket, data).catch(() => {
-                /* broken connection — cleanup handled by close/error listeners */
-            }));
-        }
-        await Promise.all(writes);
-    }
     async broadcastPatch(patch) {
-        await this.broadcastToDataConnections({ method: "state_update", patch });
+        await this.transport.broadcast({ method: "state_update", patch });
+        if (this.onPatch) {
+            await this.onPatch(patch);
+        }
     }
     async deliverLocallyAndBroadcast(agentId, event) {
         // Local delivery
@@ -434,14 +472,34 @@ export class MeshStore {
             await this.emitDeliveryStatus(event.message.id, agentId, "delivered");
         }
         if (agentId === this.peerId && this.onDelivery) {
-            void this.onDelivery(agentId, event);
-            // Auto-mark read — push bridges consume immediately
-            if (event.type === "room_message") {
-                await this.markRead(event.message.id, agentId, event.message.room);
-            }
-            else if (event.type === "dm") {
-                await this.markRead(event.message.id, agentId);
+            // Deduplicate: skip if this exact event was already delivered locally.
+            // The mesh can echo delivery patches through multiple peer paths,
+            // causing applyPatch to fire onDelivery for the same event.
+            const eventKey = JSON.stringify(event);
+            if (this.localDeliveryKeys.has(eventKey))
+                return;
+            this.localDeliveryKeys.add(eventKey);
+            // Prevent unbounded growth — evict oldest when cap reached
+            if (this.localDeliveryKeys.size > 50) {
+                const oldest = this.localDeliveryKeys.values().next().value;
+                if (oldest !== undefined)
+                    this.localDeliveryKeys.delete(oldest);
             }
+            void this.onDelivery(agentId, event);
+            // Auto-mark read — scheduled as a macrotask to yield to the event
+            // loop (see matching comment in applyPatch for rationale).
+            const timer = setTimeout(() => {
+                if (this.isShutDown)
+                    return;
+                if (event.type === "room_message") {
+                    void this.markRead(event.message.id, agentId, event.message.room);
+                }
+                else if (event.type === "dm") {
+                    void this.markRead(event.message.id, agentId);
+                }
+            }, 0);
+            if (!this.isShutDown)
+                this.pendingMarkReadTimers.push(timer);
         }
         // Remote delivery
         const patch = { type: "delivery", agentId, event };
@@ -470,6 +528,22 @@ export class MeshStore {
             });
         }
     }
+    async notifyRoomsOfNameChange(agentId, oldName, newName) {
+        const agent = this.agents.get(agentId);
+        if (!agent)
+            return;
+        const event = {
+            type: "name_changed",
+            agent: agentId,
+            oldName,
+            newName,
+        };
+        for (const roomId of agent.subscribedRooms) {
+            await this.deliverToRoom(roomId, event, agentId);
+        }
+        // Also deliver to the agent itself so it sees confirmation
+        await this.deliverLocallyAndBroadcast(agentId, event);
+    }
     async emitDeliveryStatus(messageId, agentId, status, room) {
         // Find the sender for this message
         const senderId = this.findMessageSender(messageId, room);
@@ -588,6 +662,10 @@ export class MeshStore {
         this.agents.set(id, agent);
         await this.writeIdentity(opts.harness, opts.cwd, id);
         await this.broadcastPatch({ type: "agent_upsert", agent });
+        // Broadcast presence to federated links
+        if (agent.visibility === "visible") {
+            await this.federation.broadcastAgentVisible(agent);
+        }
         return agent;
     }
     async getAgent(id) {
@@ -599,9 +677,13 @@ export class MeshStore {
         if (!agent)
             throw new CommsError(`Agent ${id} not found`, "AGENT_NOT_FOUND");
         const oldStatus = agent.status;
+        const oldName = agent.name;
         Object.assign(agent, patch);
         this.agents.set(id, agent);
         await this.broadcastPatch({ type: "agent_upsert", agent });
+        if (patch.name !== undefined && patch.name !== oldName) {
+            await this.notifyRoomsOfNameChange(id, oldName, patch.name);
+        }
         if (patch.status && patch.status !== oldStatus) {
             await this.notifyRoomsOfStatus(id, patch.status);
         }
@@ -619,14 +701,19 @@ export class MeshStore {
     }
     async setAgentOffline(id) {
         const agent = this.agents.get(id);
-        if (agent) {
-            agent.status = "offline";
-            this.agents.set(id, agent);
+        if (!agent)
+            return;
+        if (agent.status === "offline")
+            return;
+        // Only the owning store should broadcast the status change.
+        // Other stores learn about it via the agent_offline mesh patch.
+        const isOwner = id === this.peerId;
+        agent.status = "offline";
+        this.agents.set(id, agent);
+        if (isOwner) {
             await this.notifyRoomsOfStatus(id, "offline");
             await this.broadcastPatch({ type: "agent_offline", agentId: id });
-        }
-        if (this.isCoordinator) {
-            await this.handoverCoordinator();
+            await this.federation.broadcastAgentGone(id);
         }
     }
     // -----------------------------------------------------------------------
@@ -645,6 +732,7 @@ export class MeshStore {
             description: opts.description,
             members: [opts.owner],
             invited: [],
+            federated: opts.federated ?? false,
         };
         this.rooms.set(id, room);
         this.messages.set(id, []);
@@ -714,6 +802,11 @@ export class MeshStore {
             room: roomId,
             agent: agentId,
         }, agentId);
+        // Notify federated links if the room is federated
+        if (room.federated) {
+            const agentName = agent?.name ?? agentId;
+            await this.federation.broadcastRoomJoin(roomId, agentId, agentName);
+        }
         return room;
     }
     async leaveRoom(roomId, agentId) {
@@ -734,6 +827,10 @@ export class MeshStore {
             room: roomId,
             agent: agentId,
         });
+        // Notify federated links if the room is federated
+        if (room.federated) {
+            await this.federation.broadcastRoomLeave(roomId, agentId);
+        }
         if (room.members.length === 0 && room.owner === agentId) {
             await this.destroyRoom(roomId, agentId);
         }
@@ -829,6 +926,10 @@ export class MeshStore {
         arr.push(message);
         this.messages.set(roomId, arr);
         await this.broadcastPatch({ type: "message_add", roomId, message });
+        // Forward to federated links if the room is federated
+        if (room.federated) {
+            await this.federation.forwardRoomMessage(roomId, message);
+        }
         for (const memberId of room.members) {
             if (memberId !== from) {
                 await this.deliverLocallyAndBroadcast(memberId, {
@@ -928,11 +1029,27 @@ export class MeshStore {
                 await this.notifyRoomsOfStatus(id, "offline");
             }
             await this.broadcastPatch({ type: "agent_offline", agentId: id });
+            this.peerInfo.delete(id);
+        }
+        // Also purge long-offline agents to prevent indefinite accumulation
+        const offlineThreshold = Date.now() - 30 * 60 * 1000; // 30 minutes
+        const purgeIds = [];
+        for (const [id, agent] of this.agents) {
+            if (agent.status !== "offline")
+                continue;
+            const startedAt = new Date(agent.startedAt).getTime();
+            if (startedAt < offlineThreshold) {
+                purgeIds.push(id);
+            }
+        }
+        for (const id of purgeIds) {
+            this.agents.delete(id);
+            this.peerInfo.delete(id);
+            this.identityCache.delete(id);
         }
     }
     isProcessAlive(pid) {
         try {
-            // Sending signal 0 doesn't kill the process — it just checks existence
             process.kill(pid, 0);
             return true;
         }
@@ -941,45 +1058,171 @@ export class MeshStore {
         }
     }
     // -----------------------------------------------------------------------
-    // Coordinator handover
+    // Mesh visibility
     // -----------------------------------------------------------------------
-    async handoverCoordinator() {
-        if (!this.isCoordinator)
-            return;
-        let successor;
-        for (const [id, info] of this.peerInfo) {
-            if (id === this.peerId)
+    /** Set mesh discovery visibility. Delegates to discovery manager. */
+    async setVisibility(level, adapter) {
+        await this.discovery.setVisibility(level, adapter);
+    }
+    /** Get current mesh discovery visibility. */
+    getVisibility(adapter) {
+        return this.discovery.getVisibility(adapter);
+    }
+    // -----------------------------------------------------------------------
+    // Listener management (coordinator only)
+    // -----------------------------------------------------------------------
+    async addListener(host, port, policy) {
+        function isListenerPolicy(v) {
+            return (v === "full" || v === "observe" || v === "rooms-only" || v === "gateway");
+        }
+        if (!isListenerPolicy(policy)) {
+            throw new CommsError(`Invalid policy "${policy}"`, "INVALID_POLICY");
+        }
+        return this.transport.addListener(host, port, policy);
+    }
+    async removeListener(id) {
+        return this.transport.removeListener(id);
+    }
+    listListeners() {
+        return this.transport.listListeners();
+    }
+    getNetworkInterfaces() {
+        const interfaces = os.networkInterfaces();
+        const result = [];
+        for (const [name, addrs] of Object.entries(interfaces)) {
+            if (addrs === undefined)
                 continue;
-            if (!successor || info.startedAt < successor.startedAt) {
-                successor = info;
+            for (const addr of addrs) {
+                result.push({
+                    name,
+                    address: addr.address,
+                    family: addr.family,
+                    internal: addr.internal,
+                });
             }
         }
-        if (successor) {
-            const peer = this.peerConnections.get(successor.id);
-            if (peer) {
-                const msg = {
-                    method: "become_coordinator",
-                    peerList: [...this.peerInfo.values()].filter((p) => p.id !== this.peerId),
-                };
-                await writeAsync(peer.socket, encode(msg));
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // Federation (coordinator-to-coordinator)
+    // -----------------------------------------------------------------------
+    async fedConnect(host, port, name) {
+        return this.federation.connect(host, port, name);
+    }
+    async fedDisconnect(linkId) {
+        await this.federation.disconnect(linkId);
+    }
+    fedLinks() {
+        return this.federation.listLinks();
+    }
+    // -----------------------------------------------------------------------
+    // Federation callbacks (inbound from remote meshes)
+    // -----------------------------------------------------------------------
+    async handleFedAgentVisible(agent) {
+        // Store remote agent with a prefixed ID to avoid collisions with local agents
+        const remoteId = `fed:${agent.id}@${agent.harness}`;
+        const remoteAgent = {
+            ...agent,
+            id: remoteId,
+            tags: [...agent.tags, "federated"],
+        };
+        this.agents.set(remoteId, remoteAgent);
+        await this.broadcastPatch({ type: "agent_upsert", agent: remoteAgent });
+    }
+    async handleFedAgentGone(agentId) {
+        // The agentId comes from the remote mesh — we need to find the prefixed version
+        const prefix = `fed:${agentId}@`;
+        for (const [localId, agent] of this.agents) {
+            if (localId.startsWith(prefix)) {
+                agent.status = "offline";
+                this.agents.set(localId, agent);
+                await this.broadcastPatch({ type: "agent_offline", agentId: localId });
+                break;
             }
         }
-        // Always clean up coordinator state, even with no successor
-        this.stopStaleCheck();
-        for (const socket of this.coordinatorServerSockets) {
-            socket.unref();
-            socket.destroy();
+    }
+    async handleFedRoomMessage(roomId, message) {
+        const room = this.rooms.get(roomId);
+        if (!room?.federated)
+            return;
+        // Store the message locally
+        const arr = this.messages.get(roomId) ?? [];
+        arr.push(message);
+        this.messages.set(roomId, arr);
+        // Deliver to all local room members
+        for (const memberId of room.members) {
+            await this.deliverLocallyAndBroadcast(memberId, {
+                type: "room_message",
+                message,
+            });
+        }
+    }
+    async handleFedRoomJoin(roomId, agentId, _agentName) {
+        const room = this.rooms.get(roomId);
+        if (!room?.federated)
+            return;
+        // Create a shadow agent ID for the remote agent
+        const remoteId = `fed:${agentId}`;
+        if (!room.members.includes(remoteId)) {
+            room.members.push(remoteId);
+            this.rooms.set(roomId, room);
+            await this.broadcastPatch({ type: "room_upsert", room });
+        }
+        // Notify local members
+        await this.deliverToRoom(roomId, {
+            type: "member_joined",
+            room: roomId,
+            agent: remoteId,
+        }, remoteId);
+    }
+    async handleFedRoomLeave(roomId, agentId) {
+        const room = this.rooms.get(roomId);
+        if (!room?.federated)
+            return;
+        const remoteId = `fed:${agentId}`;
+        room.members = room.members.filter((m) => m !== remoteId);
+        this.rooms.set(roomId, room);
+        await this.broadcastPatch({ type: "room_upsert", room });
+        await this.deliverToRoom(roomId, {
+            type: "member_left",
+            room: roomId,
+            agent: remoteId,
+        });
+    }
+    getVisibleAgentsForFed() {
+        const result = [];
+        for (const agent of this.agents.values()) {
+            // Only broadcast agents that belong to this mesh (not federated)
+            // and are visible
+            if (agent.visibility === "visible" && !agent.id.startsWith("fed:")) {
+                result.push(agent);
+            }
+        }
+        return result;
+    }
+    getFederatedRoomMembershipsForFed() {
+        const result = new Map();
+        for (const [roomId, room] of this.rooms) {
+            if (room.federated) {
+                // Only include local members (not federated ones)
+                const localMembers = room.members.filter((m) => !m.startsWith("fed:"));
+                result.set(roomId, localMembers);
+            }
         }
-        this.coordinatorServerSockets.clear();
-        this.coordinatorServer?.unref();
-        this.coordinatorServer?.close();
-        this.coordinatorServer = undefined;
-        this.isCoordinator = false;
+        return result;
     }
     // -----------------------------------------------------------------------
     // Shutdown
     // -----------------------------------------------------------------------
     async shutdown() {
+        this.isShutDown = true;
+        // Clear any pending markRead timers so they don't fire after the
+        // transport is shut down (which would attempt sends on closed sockets)
+        // or keep the event loop alive after process.exit().
+        for (const timer of this.pendingMarkReadTimers) {
+            clearTimeout(timer);
+        }
+        this.pendingMarkReadTimers.length = 0;
         const agent = this.agents.get(this.peerId);
         if (agent) {
             agent.status = "offline";
@@ -988,37 +1231,9 @@ export class MeshStore {
                 agentId: this.peerId,
             });
         }
-        await this.handoverCoordinator();
-        // Destroy the coordinator client socket (not tracked in peerConnections)
-        this.coordinatorSocket?.unref();
-        this.coordinatorSocket?.destroy();
-        this.coordinatorSocket = undefined;
-        // Destroy all identified peer connections
-        for (const [, peer] of this.peerConnections) {
-            peer.socket.unref();
-            peer.socket.destroy();
-        }
-        this.peerConnections.clear();
-        // Destroy all data server accepted sockets (including unidentified)
-        for (const socket of this.dataServerSockets) {
-            socket.unref();
-            socket.destroy();
-        }
-        this.dataServerSockets.clear();
-        // Destroy all coordinator server accepted sockets
-        for (const socket of this.coordinatorServerSockets) {
-            socket.unref();
-            socket.destroy();
-        }
-        this.coordinatorServerSockets.clear();
         this.stopStaleCheck();
-        // Close servers — stop accepting new connections
-        this.dataServer?.unref();
-        this.dataServer?.close();
-        this.dataServer = undefined;
-        this.coordinatorServer?.unref();
-        this.coordinatorServer?.close();
-        this.coordinatorServer = undefined;
+        await this.federation.shutdown();
+        await this.transport.shutdown();
     }
 }
 //# sourceMappingURL=mesh-store.js.map