agent-comms 1.14.0 → 1.15.1

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,159 +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,
@@ -245,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 = {
@@ -313,6 +217,135 @@ 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": {
@@ -387,13 +420,24 @@ export class MeshStore {
                             this.localDeliveryKeys.delete(oldest);
                     }
                     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);
-                    }
+                    // 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;
             }
@@ -402,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
@@ -487,13 +486,20 @@ export class MeshStore {
                     this.localDeliveryKeys.delete(oldest);
             }
             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);
-            }
+            // 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 };
@@ -656,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) {
@@ -703,9 +713,7 @@ export class MeshStore {
         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);
         }
     }
     // -----------------------------------------------------------------------
@@ -724,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, []);
@@ -793,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) {
@@ -813,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);
         }
@@ -908,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, {
@@ -1007,9 +1029,7 @@ export class MeshStore {
                 await this.notifyRoomsOfStatus(id, "offline");
             }
             await this.broadcastPatch({ type: "agent_offline", agentId: id });
-            // Clean up stale peer from coordinator's registry
             this.peerInfo.delete(id);
-            this.peerConnections.delete(id);
         }
         // Also purge long-offline agents to prevent indefinite accumulation
         const offlineThreshold = Date.now() - 30 * 60 * 1000; // 30 minutes
@@ -1018,7 +1038,6 @@ export class MeshStore {
             if (agent.status !== "offline")
                 continue;
             const startedAt = new Date(agent.startedAt).getTime();
-            // If the agent went offline long ago, purge it
             if (startedAt < offlineThreshold) {
                 purgeIds.push(id);
             }
@@ -1026,13 +1045,11 @@ export class MeshStore {
         for (const id of purgeIds) {
             this.agents.delete(id);
             this.peerInfo.delete(id);
-            this.peerConnections.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;
         }
@@ -1041,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,
+                });
+            }
+        }
+        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;
             }
         }
-        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));
+    }
+    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);
             }
         }
-        // Always clean up coordinator state, even with no successor
-        this.stopStaleCheck();
-        for (const socket of this.coordinatorServerSockets) {
-            socket.unref();
-            socket.destroy();
+        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";
@@ -1088,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