agent-comms 8.15.8 → 8.15.10

package/src/core/wire-mesh-transport.ts

@@ -0,0 +1,1007 @@
+/**
+ * WireMeshTransport — MeshTransport implemented over wire-mesh-core, carrying the existing MeshMessage union as an opaque payload rather than inventing new wire semantics. This is the P2 substrate swap's own deliverable: MeshStore, CommsTool, and every existing agent/room/message behaviour above the transport are completely unaffected -- only how bytes move between peers changes.
+ *
+ * Every agent-comms MeshMessage rides as a single namespaced manage-command verb (FRAME_VERB) under one flat scope (FRAME_SCOPE); the message itself is carried opaquely in the command's own params.message field. This needs no spec/CDDL change: manage-command-params is already an open `{* tstr => any}` socket for exactly this purpose.
+ *
+ * Peer identity is authenticated at the transport layer, not asserted on the wire: createTlsTransport verifies a peer's presented certificate cryptographically and exposes the result as Connection.peerDeviceId before any MeshMessage is ever exchanged, which is what lets the `pong` self-identification message retire entirely -- there is nothing left for it to prove that the connection itself hasn't already proven.
+ *
+ * connect_request's accept/reject flow maps onto sendManageRequest's own request/response round trip directly, rather than a separate pair of connect_accepted/connect_rejected messages: manage-request-frame already tolerates arbitrary latency between a request and its response, so "waiting for a human to approve" is simply a manage-response that hasn't been sent yet, not a protocol gap needing its own mechanism. connect_request therefore holds its own IncomingManageRequest open (rather than responding immediately) until acceptConnection/rejectConnection is actually called.
+ */
+
+import { createTlsTransport } from "wire-mesh-core/adapters/tls-transport";
+import {
+  ROOM_JOIN_APPROVAL_TIMEOUT_MS,
+  ROOM_REQUEST_TIMEOUT_MS,
+  manageRequestTimeoutMs,
+} from "./request-timeouts.js";
+import { dialRemote } from "./ws-dial.js";
+import { HubSession } from "./hub-session.js";
+import { PRESENCE_READVERTISE_INTERVAL_MS } from "./gossip-extensions.js";
+import { GatewayTrust, type GatewayTrustReader } from "./gateway-trust.js";
+import {
+  advertisedListenerAddresses,
+  listenerPort,
+  listTrackedListeners,
+  registerDefaultListener,
+  registerListener,
+  unregisterListener,
+  type TrackedListener,
+} from "./listener-registry.js";
+import {
+  findPresenceAdvert,
+  KnownDevices,
+  listKnownDevicesEntries,
+  mergeAndAnnounceReachable,
+  readvertiseGossip,
+  startGossipInterval,
+} from "./gossip-directory.js";
+import { directoryAdmission, staysAdmitted } from "./directory-admission.js";
+import { routeRoomRequestViaHub } from "./hub-forwarding.js";
+import { ElectionSessions } from "./election-sessions.js";
+import { isLoopbackAddress } from "./loopback-address.js";
+import type { AgentStatus } from "./types.js";
+import { RelayRole } from "./relay-role.js";
+import { ALL_INTERFACES_HOST } from "./relay-server.js";
+import {
+  DEFAULT_PENDING_CONNECTION_TIMEOUT_MS,
+  expirePendingConnection,
+  type ConnectionDecision,
+  type PendingConnection,
+} from "./pending-connection.js";
+import {
+  acceptMeshSession,
+  type AcceptedMeshSession,
+  type ManageOutcome,
+} from "wire-mesh-core/domain/mesh-session";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import {
+  computeMeshGraph,
+  handlePathTraceRequest,
+  traceMeshPath,
+} from "./mesh-graph.js";
+import {
+  accountReplicationFrom,
+  DataFrameRouter,
+  hubDataChannel,
+} from "./data-frame-routing.js";
+import type {
+  CapabilityScope,
+  CapabilityToken,
+  CoordinatorFrame,
+  DataHaveFrame,
+  DataRequestFrame,
+  Frame,
+  ManageCommand,
+  PeerAdvert,
+  RevocationEntry,
+} from "wire-mesh-core/generated/protocol";
+import type {
+  Connection,
+  Listener,
+  Transport,
+} from "wire-mesh-core/ports/transport";
+import type { MeshMessage, PeerInfo } from "./wire-protocol.js";
+import type {
+  ConnectionHandle,
+  ListenerInfo,
+  ListenerPolicy,
+  MeshGraph,
+  MeshTransport,
+  MeshTraceResult,
+  TransportEvents,
+} from "./transport.js";
+import type { PeerIdentity } from "./identity.js";
+import { toIdentityPort } from "./wire-mesh-identity.js";
+import { PeerLinkError } from "./peer-link-error.js";
+import {
+  DATA_SERVER_ACCEPT,
+  DEFAULT_LISTENER_ACCEPT,
+  operatorListenerAccept,
+  type AcceptOptions,
+  type ConnectToRemoteOptions,
+  type WireMeshTransportOptions,
+} from "./wire-mesh-transport-options.js";
+import {
+  createRoomRouter,
+  extractMessage,
+  type RoomRouter,
+} from "./room-router.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const COORDINATOR_HOST = "127.0.0.1";
+
+/** This project's own namespaced domain (registrant "exadev.io", local name "agent-comms-v1"), matching namespaced-domain-id's "<registrant>/<local-name>" shape -- registry/core-domains.md's own recommended pattern for a third party. Exported for test use only: a security test simulating a hostile client that skips connect_request needs to construct a well-formed frame under the same domain/verb/scope this transport itself listens on, rather than duplicating these as separately-maintained magic strings that could silently drift from the real values. */
+export const DOMAIN = "exadev.io/agent-comms-v1";
+
+/** One verb for the entire MeshMessage union: this phase carries every message opaquely rather than modelling each arm as its own verb, which is core/room's own job once P3 gives this substrate real room semantics. */
+export const FRAME_VERB = "exadev.io/agent-comms-v1:frame";
+
+/** No finer-grained authorisation model exists above "you're an approved member of this mesh" at this phase -- once a session is past the quarantine gate (see handleAcceptedConnection), it's trusted for every message this domain carries. */
+export const FRAME_SCOPE: Readonly<CapabilityScope> = {
+  kind: "agent-comms-mesh",
+};
+
+// ---------------------------------------------------------------------------
+// Message carriage
+// ---------------------------------------------------------------------------
+
+export function buildCommand(message: MeshMessage): ManageCommand {
+  return { verb: FRAME_VERB, params: { message } };
+}
+
+// ---------------------------------------------------------------------------
+// WireMeshTransport
+// ---------------------------------------------------------------------------
+
+export class WireMeshTransport implements MeshTransport {
+  private readonly wireTransport: Transport;
+  private readonly events: TransportEvents;
+  private readonly identityReady: Promise<
+    Awaited<ReturnType<typeof toIdentityPort>>
+  >;
+
+  private _dataPort = 0;
+  private _isCoordinator = false;
+  private shutDown = false;
+
+  /** A method call, not a direct property read -- deliberately, so TS's control-flow narrowing (which does track `this.shutDown` as staying false for the rest of a function once an early `if (this.shutDown) return` has passed, with no awareness that an `await` in between gave a concurrent shutdown() call the chance to flip it) doesn't treat every later re-check in the same async function as unreachable. Each of these re-checks is real: shutdown() can run at any time this function is suspended on an await. */
+  private isShuttingDown(): boolean {
+    return this.shutDown;
+  }
+
+  // -- Data server (accepts data connections from already-known peers) --
+  private dataListener: Listener | undefined;
+
+  // -- Coordinator listeners (the well-known bootstrap port, plus any additional adapters addListener creates) --
+  private readonly coordinatorListeners = new Map<string, TrackedListener>();
+  private defaultListenerId: string | undefined;
+
+  // -- The session dialled via connectToCoordinator, when this instance is not itself the coordinator -- and that same coordinator's own device-id hex, set alongside it: coordinatorPeerId reports it, so PeerLifecycle can tell the coordinator's departure from an ordinary peer's. The session is dropped when it closes and the hex when this side takes the coordinator role itself, so coordinatorPeerId below names a coordinator this instance genuinely still answers to.
+  private coordinatorSession: AcceptedMeshSession | undefined;
+  private coordinatorDeviceHex: string | undefined;
+
+  // -- The hub relay mode (agent-comms#151), owning its own file under the max-lines cap: see hub-session.ts for the full connection model.
+  readonly hub: HubSession;
+
+  // -- Which relay the hub session is held over, and the relay this store serves while it holds the elected coordinator role and an uplink (agent-comms#342): see relay-role.ts.
+  readonly relay: RelayRole;
+
+  // -- Every live session, keyed by the peer's authenticated device-id hex (== ConnectionHandle.id) -- covers coordinator-client, coordinator-accepted, and peer data sessions alike, since send()/broadcast() must reach whichever kind of session a peer happens to be reachable through. A single-slot-per-key map by construction: mesh formation genuinely establishes TWO independent sessions to the same peer (see the dataDials comment below), and the second one registered here simply overwrites the first as far as addressing goes -- fine for send()/broadcast() (either socket reaches the same peer), but NOT fine for shutdown, which must close every live session regardless of whether it's still reachable through this map. allSessions below exists specifically so shutdown never leaks the one this map's overwrite silently stopped tracking.
+  private readonly peerSessions = new Map<string, AcceptedMeshSession>();
+
+  // -- Every live session this transport has ever created, accepted or dialled, for shutdown's own use only -- never used for addressing (peerSessions is), so it never loses track of one session to another sharing the same peer id.
+  private readonly allSessions = new Set<AcceptedMeshSession>();
+
+  // The machine-local sessions coordinator claims travel over (agent-comms#341): see election-sessions.ts.
+  private readonly electionSessions: ElectionSessions;
+
+  // -- Every device this side has heard gossip from, across every session's own directory and the hub's, keyed by device-id hex: the mesh-wide aggregation room discovery and agent listing read. See KnownDevices for which entries it keeps and for how long.
+  private readonly knownDevices = new KnownDevices((deviceHex) =>
+    staysAdmitted(this.gatewayTrust, deviceHex),
+  );
+
+  /** Every device this side has ever heard gossip from, mesh-wide -- not just its own directly-connected peers -- with each one's own latest full advert (addresses, snapshot-seconds, and every open-extension field such as presence/status). See gossip-directory.ts's own listKnownDevicesEntries for the actual implementation, kept out of this already-large file. */
+  listKnownDevices(): readonly {
+    deviceId: string;
+    advert: Readonly<PeerAdvert>;
+  }[] {
+    return listKnownDevicesEntries(this.knownDevices.current());
+  }
+
+  /** Assembles this side's own best-effort view of the mesh's connection graph (agent-comms#199) -- see mesh-graph.ts's own computeMeshGraph for the actual implementation, kept out of this already-large file. */
+  meshGraph(): MeshGraph {
+    return computeMeshGraph(this.knownDevices.current());
+  }
+
+  /** Sends path.trace to targetDeviceHex (agent-comms#199) -- see mesh-graph.ts's own traceMeshPath for the actual direct-or-hub fallback, kept out of this already-large file. */
+  async meshTrace(
+    targetDeviceHex: string,
+    timeoutMs?: number,
+  ): Promise<MeshTraceResult> {
+    return traceMeshPath(
+      this.peerSessions,
+      this.hub,
+      targetDeviceHex,
+      timeoutMs,
+    );
+  }
+
+  /** Registers a session in both peerSessions (addressing -- last one in for a given peer wins) and allSessions (shutdown -- every session, always). */
+  private trackSession(key: string, session: AcceptedMeshSession): void {
+    this.peerSessions.set(key, session);
+    this.allSessions.add(session);
+  }
+
+  // -- Peers this side has dialled via connectToPeer specifically (in flight or established) -- deliberately separate from peerSessions, which also holds sessions this side reached the SAME peer through for an unrelated reason (most concretely, the coordinator-client session connectToCoordinator opens to the coordinator's own device-id). Mesh formation deliberately establishes a second, independent connection in each direction so each side's own acceptor can push its own state (see mesh-store.ts's own handlePeerConnected), so connectToPeer's "don't dial twice" guard must not be satisfied by an unrelated session that merely happens to share the same peer ID.
+  private readonly dataDials = new Set<string>();
+
+  // -- connect_request frames awaiting a human accept/reject decision, keyed by the requester's device-id hex --
+  private readonly pendingConnections = new Map<string, PendingConnection>();
+
+  // -- The single consumer of every approved session's incomingManageRequests, once quarantine (if any) is past. Owns verb dispatch (the legacy opaque frame, plus whichever real core/room verbs later phases register handlers for) -- this transport itself no longer decodes or routes a MeshMessage at all beyond handing a session off here.
+  private readonly roomRouter: RoomRouter;
+
+  private readonly pendingConnectionTimeoutMs: number;
+  private readonly roomJoinApprovalTimeoutMs: number;
+
+  /** Reads this side's own current AgentStatus for the next gossip re-advertisement tick -- a pull, not a push, so MeshStore never needs to reach into this transport's internals on every status change (see updateAgent/setAgentOffline, which patch MeshStore's own agents map and let the next tick pick it up). undefined when no presence source was wired in (every existing construction site that predates this feature). */
+  private readonly getCurrentPresence: WireMeshTransportOptions["getCurrentPresence"];
+  /** Reads this side's own currently-hosted public/private rooms for the next gossip re-advertisement tick, the same pull-not-push shape getCurrentPresence already established -- createRoom/destroyRoom patch MeshStore's own rooms map and let the next tick pick it up, rather than pushing an update here on every mutation. undefined when no hosted-rooms source was wired in. */
+  private readonly getHostedRooms: WireMeshTransportOptions["getHostedRooms"];
+  private gossipInterval: ReturnType<typeof setInterval> | undefined;
+
+  /** Reads this side's own gossip-safe agent-identity advert for the next gossip re-advertisement tick, the same pull-not-push shape getCurrentPresence/getHostedRooms already established. undefined when no agent-identity source was wired in, or when MeshStore's own getter decides this agent shouldn't advertise itself this way right now (e.g. not "visible", or no self-agent record yet). */
+  private readonly getSelfAgentAdvert: WireMeshTransportOptions["getSelfAgentAdvert"];
+
+  /** Reads this side's own currently-running cc-peer package version for the next gossip re-advertisement tick (agent-comms#198). Unlike getCurrentPresence/getHostedRooms/getSelfAgentAdvert (constructor-injected, since MeshStore already has a real value for each at construction time), this is a plain mutable field set post-construction -- bridge-mesh.ts assigns it right after building this transport, mirroring MeshStore's own onDelivery/onError/onCoordinatorRoleChanged convention, so this transport doesn't need its own constructor parameter for a fact only two of many bridges ever have. undefined for every bridge that never loads cc-peer at all. */
+  getCcPeerVersion: (() => string | undefined) | undefined;
+
+  /** Answers, stores and offers this side's core/data frames: the room-notice oplog over dataStorage, and the account's replicated grant ledger (agent-comms#344). See DataFrameRouter. */
+  private readonly dataFrames: DataFrameRouter;
+
+  /** The cross-machine trust boundary (agent-comms#156): gates outbound gossip advertisement (hasAny), inbound directory merge (bare-device trust, a principal's own device, or a verified membership proof, wired into HubSession as admitEntries), the legacy per-device frame path (isTrusted, bare-device trust only), and outbound targeted hub requests (isReachable); see GatewayTrust's own class doc. A real room-domain manage-request relayed through the hub is never gated on this at all since agent-comms#192: hub-session.ts's own dispatchHubRequest relies purely on that verb's own capability-token verification instead. Defaults to a fresh, empty (deny-all) instance when no caller wires one in, matching every existing construction site that predates this feature. */
+  private readonly gatewayTrust: GatewayTrustReader;
+
+  /** See WireMeshTransportOptions's own doc comment -- all eight fields are optional and bundled into one `options` parameter, so a caller needing only gatewayTrust no longer has to pass `undefined` for every one before it. */
+  constructor(
+    events: Readonly<TransportEvents>,
+    identity: Readonly<PeerIdentity>,
+    options?: WireMeshTransportOptions,
+  ) {
+    const {
+      roomVerbHandlers,
+      pendingConnectionTimeoutMs = DEFAULT_PENDING_CONNECTION_TIMEOUT_MS,
+      roomJoinApprovalTimeoutMs = ROOM_JOIN_APPROVAL_TIMEOUT_MS,
+      getCurrentPresence,
+      presenceReadvertiseIntervalMs = PRESENCE_READVERTISE_INTERVAL_MS,
+      getHostedRooms,
+      dataStorage,
+      getSelfAgentAdvert,
+      accountReplication,
+      gatewayTrust = new GatewayTrust(),
+      verifyMembership,
+      relayListenHost = ALL_INTERFACES_HOST,
+    } = options ?? {};
+    this.events = events;
+    this.wireTransport = createTlsTransport({
+      certificatePem: identity.certificate,
+      privateKeyPem: identity.privateKey,
+    });
+    this.identityReady = toIdentityPort(identity);
+    this.gatewayTrust = gatewayTrust;
+    this.electionSessions = new ElectionSessions(events);
+    this.relay = new RelayRole({
+      listenHost: relayListenHost,
+      ownDeviceHex: deviceIdToHex(Uint8Array.from(identity.deviceId)),
+      knownDevices: this.knownDevices,
+      machineLocalPeers: this.electionSessions,
+      gatewayTrust,
+      readvertise: () => {
+        readvertiseGossip(this.gossipOptions());
+      },
+      events,
+    });
+    // Built before this.hub below (roomRouter has no dependency on it) so the hub can be wired with a direct this.roomRouter.handleRelayedRequest reference rather than a lazy closure. path.trace (agent-comms#199) is always registered here, ahead of any caller-supplied roomVerbHandlers, since every real construction site wants it answered identically regardless of which room verbs it registers.
+    this.roomRouter = createRoomRouter({
+      events,
+      handlers: { "path.trace": handlePathTraceRequest, ...roomVerbHandlers },
+    });
+    this.roomJoinApprovalTimeoutMs = roomJoinApprovalTimeoutMs;
+    this.dataFrames = new DataFrameRouter({
+      dataStorage,
+      account: accountReplicationFrom(accountReplication, (deviceHex) =>
+        this.knownDevices.current().get(deviceHex),
+      ),
+      peerSessions: this.peerSessions,
+      onError: this.events.onError,
+      hub: hubDataChannel(() => this.hub),
+      announceIntervalMs: presenceReadvertiseIntervalMs,
+    });
+    this.hub = new HubSession({
+      roomJoinApprovalTimeoutMs,
+      identityReady: this.identityReady,
+      events: this.events,
+      isShuttingDown: this.isShuttingDown.bind(this),
+      advertisedAddresses: this.advertisedAddresses,
+      onFrame: async (conn, frame) => this.handleDataFrame(conn, frame),
+      onRelayedDataFrame: this.dataFrames.routeRelayed,
+      trackForShutdown: (session) => {
+        this.allSessions.add(session);
+      },
+      untrack: (session) => {
+        this.allSessions.delete(session);
+      },
+      onDirectory: (entries) => {
+        mergeAndAnnounceReachable(this.knownDevices, entries, this.events);
+      },
+      handleRoomRequest: this.roomRouter.handleRelayedRequest,
+      isTrusted: (deviceHex) => this.gatewayTrust.isTrusted(deviceHex),
+      admitEntries: directoryAdmission({ gatewayTrust, verifyMembership }),
+    });
+    this.pendingConnectionTimeoutMs = pendingConnectionTimeoutMs;
+    this.getCurrentPresence = getCurrentPresence;
+    this.getHostedRooms = getHostedRooms;
+    this.getSelfAgentAdvert = getSelfAgentAdvert;
+    this.gossipInterval = startGossipInterval({
+      ...this.gossipOptions(),
+      intervalMs: presenceReadvertiseIntervalMs,
+    });
+  }
+
+  /** Everything readvertiseGossip needs, read live from this transport's own fields, so the periodic tick and an on-demand readvertise (a new hub session's first advert) send the same thing. */
+  private gossipOptions(): Parameters<typeof readvertiseGossip>[0] {
+    return {
+      allSessions: this.allSessions,
+      hub: this.hub,
+      hasAnyTrustedGateway: () => this.gatewayTrust.hasAny(),
+      onError: this.events.onError,
+      getCurrentPresence: this.getCurrentPresence,
+      getHostedRooms: this.getHostedRooms,
+      getSelfAgentAdvert: this.getSelfAgentAdvert,
+      getCcPeerVersion: () => this.getCcPeerVersion?.(),
+      getRelayOffer: () => this.relay.offer(),
+    };
+  }
+
+  /** Sends one data-have or data-request frame directly to an already-connected peer: the mechanical send primitive a future catch-up policy calls once it decides to (see DataFrameRouter's dataStorage doc comment). Throws if this side has never received any frame from that peer yet (there is no connection to send on), matching sendManageRequest's own "no reachable session" failure mode for an unknown peer. */
+  async sendDataFrame(
+    peerDeviceHex: string,
+    frame: Readonly<DataHaveFrame> | Readonly<DataRequestFrame>,
+  ): Promise<void> {
+    await this.dataFrames.send(peerDeviceHex, frame);
+  }
+
+  /** Routes one core/data frame: see data-frame-routing.ts's own DataFrameRouter for the actual dispatch, kept out of this already-large file. */
+  private async handleDataFrame(
+    connection: Readonly<Connection>,
+    frame: Frame,
+  ): Promise<void> {
+    await this.dataFrames.route(connection, frame);
+  }
+
+  // -- Public getters --
+
+  get dataPort(): number {
+    return this._dataPort;
+  }
+
+  get isCoordinator(): boolean {
+    return this._isCoordinator;
+  }
+
+  get hasCoordinatorConnection(): boolean {
+    return this.coordinatorSession !== undefined;
+  }
+
+  get coordinatorPeerId(): string | undefined {
+    return this.coordinatorDeviceHex;
+  }
+
+  // -----------------------------------------------------------------------
+  // Connection acceptance -- shared by every listener (coordinator or data)
+  // -----------------------------------------------------------------------
+
+  private async handleAcceptedConnection(
+    connection: Readonly<Connection>,
+    accept: Readonly<AcceptOptions>,
+  ): Promise<void> {
+    const { policy, fireOnPeerConnected, requiresApproval, machineLocal } =
+      accept;
+    const peerDeviceId = connection.peerDeviceId;
+    if (peerDeviceId === undefined) {
+      // No certificate presented at all -- nothing to authenticate this peer against.
+      await connection.close();
+      return;
+    }
+    const deviceIdHex = deviceIdToHex(peerDeviceId);
+    const session = await this.openSession(connection);
+    if (session === undefined) return;
+    // ConnectionHandle.policy is `?: ListenerPolicy`, not `?: ListenerPolicy | undefined` -- under exactOptionalPropertyTypes these are genuinely different types, so the key must be entirely absent rather than present-with-undefined-value when this listener has no policy of its own.
+    const handle: ConnectionHandle = {
+      id: deviceIdHex,
+      ...(policy !== undefined ? { policy } : {}),
+    };
+
+    if (requiresApproval) {
+      // A listener a stranger can dial cold (the coordinator port, or any addListener-created listener) must not hand out full routing on the strength of a TLS handshake alone -- that only proves which key the far side holds, never that a human has approved them as a mesh member. Quarantine every request from this session until it's either an `introduce` (the pre-existing, ungated coordinator-handoff path, unchanged from before this substrate swap) or an approved `connect_request`.
+      this.allSessions.add(session);
+      this.consumeQuarantined(session, handle, machineLocal);
+      this.watchForDisconnect(session, handle, deviceIdHex);
+      return;
+    }
+
+    this.trackSession(deviceIdHex, session);
+    if (fireOnPeerConnected) {
+      const info: PeerInfo = {
+        id: deviceIdHex,
+        port: 0,
+        startedAt: new Date().toISOString(),
+      };
+      this.events.onPeerConnected(handle, info);
+    }
+
+    this.consumeIncoming(session, handle, machineLocal);
+    this.watchForDisconnect(session, handle, deviceIdHex);
+  }
+
+  /** Reads a not-yet-trusted session's requests until it's promoted (an `introduce`, handled and trusted immediately, matching the pre-existing coordinator-handoff trust boundary) or a `connect_request` arrives, at which point this same loop iteration blocks on the human decision Promise stored in pendingConnections -- resumed in place by acceptConnection/rejectConnection (or by watchForDisconnect, if the requester disconnects first) -- rather than ever stopping and later re-entering the session's incomingManageRequests from a second call, which would require assuming a fresh access yields a distinct, independently-advancing iterator rather than resuming the one already in progress. Anything else arriving before introduce/connect_request is a protocol violation from an unapproved peer and is refused and closed rather than routed. */
+  private consumeQuarantined(
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+    machineLocal: boolean,
+  ): void {
+    // Watched from the start, so any claim this session gossips before it introduces itself is read and dropped rather than held back and replayed once it is trusted.
+    this.electionSessions.watch(session, handle);
+    void (async () => {
+      let approved = false;
+      for await (const request of session.incomingManageRequests) {
+        if (this.shutDown) break;
+        if (approved) {
+          await this.roomRouter.handleLocalRequest(request, handle);
+          continue;
+        }
+        const message = extractMessage(request.command);
+        if (message === undefined) {
+          await request.respond({ result: "ok" }).catch(() => undefined);
+          continue;
+        }
+        if (message.method === "introduce") {
+          this.trackSession(handle.id, session);
+          // Trusted from here on, so its coordinator claims count from here on, and only from here on.
+          if (machineLocal) this.electionSessions.enrol(session, handle);
+          this.events.onIntroduction(handle, {
+            peerId: handle.id,
+            dataPort: message.dataPort,
+          });
+          await request.respond({ result: "ok" }).catch(() => undefined);
+          approved = true;
+          continue;
+        }
+        if (message.method === "connect_request") {
+          // Held open deliberately (see this file's own header comment). Answered later by acceptConnection/rejectConnection, or by expirePendingConnection if neither happens within pendingConnectionTimeoutMs.
+          const decision = await new Promise<ConnectionDecision>((resolve) => {
+            this.pendingConnections.set(handle.id, {
+              respond: request.respond,
+              dataPort: message.dataPort,
+              name: message.name,
+              fingerprint: message.fingerprint,
+              policy: handle.policy,
+              session,
+              resolve,
+              // unref()'d so a stray pending connection (this timer failing to be cleared through some path not yet covered) can never by itself keep the process alive for up to pendingConnectionTimeoutMs after everything else is done -- confirmed necessary directly: shutdown() originally cleared every pendingConnections entry without clearing its timer, and the whole test process hung for the full default timeout before exiting.
+              timeoutHandle: setTimeout(() => {
+                expirePendingConnection(this.pendingConnections, handle.id);
+              }, this.pendingConnectionTimeoutMs).unref(),
+            });
+            this.events.onConnectionRequest(handle, {
+              peerId: handle.id,
+              dataPort: message.dataPort,
+              name: message.name,
+              fingerprint: message.fingerprint,
+            });
+          });
+          if (decision === "reject") {
+            // Rejection can arrive via rejectConnection (session still open) or via shutdown/disconnect (session already closing) -- catch rather than assume which.
+            await session.close().catch(() => undefined);
+            return;
+          }
+          // acceptConnection has already called trackSession synchronously, before firing onIntroduction -- nothing left to do here beyond trusting subsequent requests on this same session.
+          approved = true;
+          continue;
+        }
+        // Any other message before introduce/connect_request is a protocol violation from an unapproved peer -- refuse and terminate rather than route it.
+        await request
+          .respond({ result: "error", code: "not_approved" })
+          .catch(() => undefined);
+        await session.close().catch(() => undefined);
+        return;
+      }
+    })();
+  }
+
+  /** Opens a mesh session over an already-established connection, wired to this transport's own frame dispatch and advertised addresses. Every session this transport owns is built exactly this way, whether the connection was accepted by a listener or dialled at a peer, at the coordinator, or at a remote gateway, so the wiring lives here rather than being restated at each call site. Resolves undefined, with the session closed, when shutdown() has begun by the time the session is open, whether it began before the connection arrived or while the session was opening: shutdown() closes only the sessions it can see, so one opened after it started would stay open, and its peer would never learn that this side had gone (agent-comms#372). */
+  private async openSession(
+    connection: Readonly<Connection>,
+  ): Promise<AcceptedMeshSession | undefined> {
+    const identity = await this.identityReady;
+    const session = await acceptMeshSession(connection, identity, [DOMAIN], {
+      onFrame: async (conn, frame) => {
+        await this.handleDataFrame(conn, frame);
+      },
+      addresses: this.advertisedAddresses,
+    });
+    if (this.isShuttingDown()) {
+      await session.close();
+      return undefined;
+    }
+    return session;
+  }
+
+  /** Delegates the whole post-approval drain loop to roomRouter: this transport no longer decodes or routes a MeshMessage itself, only hands the session off. Also starts this session's own independent revocationAnnouncements drain, since a gossiped revocation is not a manage-request and has no verb for roomRouter to dispatch, and its coordinator-frame watch for the same reason, enrolling the session in the election only when machineLocal says it reaches this machine. */
+  private consumeIncoming(
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+    machineLocal: boolean,
+  ): void {
+    this.roomRouter.drainSession(session, handle);
+    this.drainRevocationAnnouncements(session);
+    this.electionSessions.watch(session, handle);
+    if (machineLocal) this.electionSessions.enrol(session, handle);
+  }
+
+  /** Reads every revocation-entry this session's peer announces, for as long as the session lives, handing each one to MeshStore via onRevocationAnnounce -- one call per entry, matching revocationAnnouncements' own per-entry flattening of a revocation-announce frame's entries array. */
+  private drainRevocationAnnouncements(session: AcceptedMeshSession): void {
+    void (async () => {
+      for await (const entry of session.revocationAnnouncements) {
+        this.events.onRevocationAnnounce(entry);
+      }
+    })();
+  }
+
+  private watchForDisconnect(
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+    deviceIdHex: string,
+  ): void {
+    void (async () => {
+      // The presence this session last reported. Every session event carries the whole directory, including events this side causes by sending a frame and the final closed event, so the peer's advert repeats long after the peer sent it. Only a change is news: re-reporting a stale advert would mark a departed peer's agent running again after the coordinator has set it offline, and nothing would ever correct that.
+      let reportedPresence: AgentStatus | undefined;
+      for await (const event of session.events) {
+        this.knownDevices.mergeLocal(event.directory);
+        const presence = findPresenceAdvert(deviceIdHex, event.directory);
+        if (presence !== undefined && presence !== reportedPresence) {
+          reportedPresence = presence;
+          this.events.onPresenceAdvert(handle, presence);
+        }
+        if (event.state.status === "closed") {
+          const wasTracked = this.peerSessions.get(deviceIdHex) === session;
+          if (wasTracked) this.peerSessions.delete(deviceIdHex);
+          this.allSessions.delete(session);
+          this.electionSessions.delete(session);
+          // Dropping the closed coordinator session is what makes hasCoordinatorConnection answer honestly once the coordinator process is gone; coordinatorDeviceHex deliberately survives, so the onPeerDisconnected fired just below can still be recognised as the coordinator's own departure rather than an ordinary peer's.
+          if (this.coordinatorSession === session)
+            this.coordinatorSession = undefined;
+          // A requester disconnecting before a human decides must unblock consumeQuarantined's own still-suspended loop iteration -- otherwise that promise, and the closure awaiting it, never settle.
+          const pending = this.pendingConnections.get(deviceIdHex);
+          if (pending !== undefined) {
+            clearTimeout(pending.timeoutHandle);
+            pending.resolve("reject");
+            this.pendingConnections.delete(deviceIdHex);
+          }
+          // A no-op when this session was never a connectToPeer dial (e.g. the coordinator-client or an accepted connection) -- Set.delete on an absent key is always safe.
+          this.dataDials.delete(deviceIdHex);
+          if (wasTracked && !this.shutDown) {
+            this.events.onPeerDisconnected(handle);
+          }
+          return;
+        }
+      }
+    })();
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Data server
+  // -----------------------------------------------------------------------
+
+  async startDataServer(): Promise<void> {
+    this.dataListener = await this.wireTransport.listen(
+      `${COORDINATOR_HOST}:0`,
+      (connection) => {
+        void this.handleAcceptedConnection(connection, DATA_SERVER_ACCEPT);
+      },
+    );
+    this._dataPort = listenerPort(this.dataListener);
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Coordinator connection (client side)
+  // -----------------------------------------------------------------------
+
+  async connectToCoordinator(
+    host: string,
+    port: number,
+    peerId: string,
+    dataPort: number,
+  ): Promise<void> {
+    const connection = await this.wireTransport.connect(
+      `${host}:${String(port)}`,
+    );
+    const session = await this.openSession(connection);
+    if (session === undefined) {
+      throw new Error("connectToCoordinator: the transport has shut down");
+    }
+    this.coordinatorSession = session;
+    // Fire-and-forget, matching the previous transport's own contract: this resolves once the introduction is sent, not once a response arrives; peer_list/peer_joined/become_coordinator arrive asynchronously via the normal dispatch path below, independent of this call's own promise. Written before the session is enrolled below, because enrolling announces the elected coordinator over it and the port holder drops any claim that reaches it ahead of the introduce.
+    void this.sendFrame(
+      session,
+      buildCommand({ method: "introduce", peerId, dataPort }),
+    ).catch(() => undefined);
+    const coordinatorDeviceId = connection.peerDeviceId;
+    if (coordinatorDeviceId !== undefined) {
+      const handle: ConnectionHandle = {
+        id: deviceIdToHex(coordinatorDeviceId),
+      };
+      this.coordinatorDeviceHex = handle.id;
+      this.trackSession(handle.id, session);
+      // Machine-local only when the address dialled was a loopback one: the dialler knows nothing else about where the far side is.
+      this.consumeIncoming(session, handle, isLoopbackAddress(host));
+      this.watchForDisconnect(session, handle, handle.id);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Become coordinator (server side)
+  // -----------------------------------------------------------------------
+
+  async becomeCoordinator(host: string, port: number): Promise<void> {
+    this.defaultListenerId = await registerDefaultListener({
+      wireTransport: this.wireTransport,
+      coordinatorListeners: this.coordinatorListeners,
+      host,
+      port,
+      onAccepted: (connection) => {
+        void this.handleAcceptedConnection(connection, DEFAULT_LISTENER_ACCEPT);
+      },
+      isShuttingDown: () => this.isShuttingDown(),
+    });
+    this._isCoordinator = true;
+    // This side now IS the coordinator, so it answers to no other one: leaving a departed coordinator's device-id here would keep coordinatorPeerId naming a peer whose disconnect has already been dealt with, and would leave a stale device-id where the coordinator role is now this side's own.
+    this.coordinatorDeviceHex = undefined;
+    this.coordinatorSession = undefined;
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Peer-to-peer data connections
+  // -----------------------------------------------------------------------
+
+  async connectToPeer(
+    peer: Readonly<PeerInfo>,
+    _ownPeerId: string,
+  ): Promise<void> {
+    if (this.shutDown || this.dataDials.has(peer.id)) return;
+    this.dataDials.add(peer.id);
+    const host = peer.host ?? COORDINATOR_HOST;
+    const connection = await this.wireTransport
+      .connect(`${host}:${String(peer.port)}`)
+      .catch((error: unknown) => {
+        this.events.onError?.(
+          new PeerLinkError("dial", peer.id, peer.port, error),
+        );
+        return undefined;
+      });
+    if (connection === undefined) {
+      this.dataDials.delete(peer.id);
+      return;
+    }
+    const peerDeviceId = connection.peerDeviceId;
+    if (peerDeviceId === undefined) {
+      this.dataDials.delete(peer.id);
+      await connection.close();
+      return;
+    }
+    const deviceIdHex = deviceIdToHex(peerDeviceId);
+    if (deviceIdHex !== peer.id) {
+      // The peer we reached does not hold the key peer.id claims to name -- refuse exactly like a mismatched fingerprint would have under the previous transport.
+      this.events.onError?.(
+        new Error(
+          `connectToPeer: peer at port ${String(peer.port)} authenticated as ${deviceIdHex}, expected ${peer.id}`,
+        ),
+      );
+      this.dataDials.delete(peer.id);
+      await connection.close();
+      return;
+    }
+    const session = await this.openSession(connection);
+    if (session === undefined) {
+      this.dataDials.delete(peer.id);
+      return;
+    }
+    this.trackSession(deviceIdHex, session);
+    const handle: ConnectionHandle = { id: deviceIdHex };
+    // Machine-local only when the address dialled was a loopback one. A peer list or a first-contact beacon heard over LAN broadcast can name any host, and a device there can serve a session under the very device-id it announced, so authenticating the far side proves who it is, never that it is on this machine.
+    this.consumeIncoming(session, handle, isLoopbackAddress(host));
+    this.watchForDisconnect(session, handle, deviceIdHex);
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Send / broadcast
+  // -----------------------------------------------------------------------
+
+  async send(
+    handle: Readonly<ConnectionHandle>,
+    message: MeshMessage,
+  ): Promise<void> {
+    const session = this.peerSessions.get(handle.id);
+    if (session === undefined) return;
+    await this.sendFrame(session, buildCommand(message)).catch(
+      (error: unknown) => {
+        this.events.onError?.(
+          new PeerLinkError("send", handle.id, undefined, error),
+        );
+      },
+    );
+  }
+
+  /** Sends one opaque MeshMessage frame over a session under the ordinary network deadline. The deadline is what makes it safe to await: wire-mesh-core waits forever for a manage-response when given none, so a frame sent to a peer whose socket has already died but whose close this side has not yet observed would never settle, and MeshStore.shutdown() awaits exactly such a broadcast on its way out. */
+  private async sendFrame(
+    session: AcceptedMeshSession,
+    command: ManageCommand,
+  ): Promise<ManageOutcome> {
+    return session.sendManageRequest(
+      command,
+      FRAME_SCOPE,
+      undefined,
+      undefined,
+      ROOM_REQUEST_TIMEOUT_MS,
+    );
+  }
+
+  async broadcast(message: MeshMessage): Promise<void> {
+    const command = buildCommand(message);
+    await Promise.all(
+      [...this.peerSessions.values()].map(async (session) =>
+        this.sendFrame(session, command).catch(() => undefined),
+      ),
+    );
+  }
+
+  async broadcastRevocation(
+    entries: readonly RevocationEntry[],
+  ): Promise<void> {
+    await Promise.all(
+      [...this.peerSessions.values()].map(async (session) =>
+        session.sendRevocationAnnounce(entries).catch(() => undefined),
+      ),
+    );
+  }
+
+  async broadcastCoordinatorClaim(
+    frame: Readonly<CoordinatorFrame>,
+  ): Promise<void> {
+    await this.electionSessions.broadcast(frame);
+  }
+
+  async sendCoordinatorClaim(
+    handle: Readonly<ConnectionHandle>,
+    frame: Readonly<CoordinatorFrame>,
+  ): Promise<void> {
+    await this.electionSessions.sendTo(handle.id, frame);
+  }
+
+  electionPeerIds(): ReadonlySet<string> {
+    return this.electionSessions.peerIds();
+  }
+
+  async sendRoomRequest(
+    memberId: string,
+    command: ManageCommand,
+    scope: Readonly<CapabilityScope>,
+    token?: CapabilityToken,
+  ): Promise<ManageOutcome> {
+    const session = this.peerSessions.get(memberId);
+    if (session !== undefined) {
+      return session.sendManageRequest(
+        command,
+        scope,
+        undefined,
+        token,
+        manageRequestTimeoutMs(command, this.roomJoinApprovalTimeoutMs),
+      );
+    }
+    // no_route, never unauthorized: this side has nowhere to send the request, which is a fact about this side's own routing rather than an answer from memberId, and a caller must be able to tell the two apart. A device with no session that this side is willing to relay for may become reachable later, once it connects or once an operator trusts it, so a request for it is worth holding; a request the recipient itself refused never is.
+    if (!this.gatewayTrust.isReachable(memberId)) {
+      return { result: "error", code: "no_route" };
+    }
+    return routeRoomRequestViaHub({
+      hub: this.hub,
+      memberId,
+      command,
+      scope,
+      token,
+    });
+  }
+
+  /** Asks deviceId for its own, currently-running wire-mesh-core version, live, right now (agent-comms#198's own query_version action) -- rides sendRoomRequest's own routing (a direct peerSessions session when one exists, else a trusted hub relay, else "unauthorized") against wire-mesh-core's deliberately-ungated core/version domain (spec/version.cddl): "version:get" on the outer manage-command only exists to satisfy manage-command.verb's own capability-verb grammar, and the scope below (kind "node") is arbitrary -- the receiving side never actually inspects either for this verb. */
+  async queryVersion(deviceId: string): Promise<ManageOutcome> {
+    return this.sendRoomRequest(
+      deviceId,
+      { verb: "version:get", params: { verb: "version.get" } },
+      { kind: "node" },
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Connection approval (connectToRemote flow)
+  // -----------------------------------------------------------------------
+
+  async connectToRemote(
+    options: Readonly<ConnectToRemoteOptions>,
+  ): Promise<void> {
+    const { host, port, peerId, dataPort, name, fingerprint } = options;
+    const connection = await dialRemote(this.wireTransport, host, port);
+    const session = await this.openSession(connection);
+    if (session === undefined) {
+      throw new Error("connectToRemote: the transport has shut down");
+    }
+    const outcome = await session.sendManageRequest(
+      buildCommand({
+        method: "connect_request",
+        peerId,
+        dataPort,
+        name,
+        fingerprint,
+      }),
+      FRAME_SCOPE,
+    );
+    if (outcome.result === "error") {
+      await session.close();
+      throw new Error(outcome.message ?? outcome.code);
+    }
+    const coordinatorDeviceId = connection.peerDeviceId;
+    if (coordinatorDeviceId !== undefined) {
+      const handle: ConnectionHandle = {
+        id: deviceIdToHex(coordinatorDeviceId),
+      };
+      this.trackSession(handle.id, session);
+      this.consumeIncoming(session, handle, false);
+      this.watchForDisconnect(session, handle, handle.id);
+    }
+  }
+
+  async acceptConnection(handle: Readonly<ConnectionHandle>): Promise<void> {
+    const pending = this.pendingConnections.get(handle.id);
+    if (pending === undefined) {
+      throw new Error(`No pending connection for handle ${handle.id}`);
+    }
+    clearTimeout(pending.timeoutHandle);
+    this.pendingConnections.delete(handle.id);
+    await pending.respond({ result: "ok" });
+    // Must happen before onIntroduction fires below: mesh-store's own handleIntroduction sends a reply on this exact handle synchronously as part of handling that event, which needs peerSessions already populated -- waiting for consumeQuarantined's own suspended loop to resume (via resolve() below) would race, since that only happens on a later microtask tick.
+    this.trackSession(handle.id, pending.session);
+    const acceptedHandle: ConnectionHandle = {
+      id: handle.id,
+      ...(pending.policy !== undefined ? { policy: pending.policy } : {}),
+    };
+    this.events.onIntroduction(acceptedHandle, {
+      peerId: handle.id,
+      dataPort: pending.dataPort,
+    });
+    // Resumes consumeQuarantined's own still-blocked loop iteration so it starts trusting subsequent requests on this same session.
+    pending.resolve("accept");
+  }
+
+  async rejectConnection(
+    handle: Readonly<ConnectionHandle>,
+    reason: string,
+  ): Promise<void> {
+    const pending = this.pendingConnections.get(handle.id);
+    if (pending === undefined) {
+      throw new Error(`No pending connection for handle ${handle.id}`);
+    }
+    clearTimeout(pending.timeoutHandle);
+    this.pendingConnections.delete(handle.id);
+    await pending.respond({
+      result: "error",
+      code: "rejected",
+      message: reason,
+    });
+    // Resumes consumeQuarantined's blocked loop iteration, which closes the session itself -- it was never tracked anywhere else to close it from here.
+    pending.resolve("reject");
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Listener management
+  // -----------------------------------------------------------------------
+
+  async addListener(
+    host: string,
+    port: number,
+    policy: ListenerPolicy,
+  ): Promise<string> {
+    return registerListener({
+      wireTransport: this.wireTransport,
+      coordinatorListeners: this.coordinatorListeners,
+      host,
+      port,
+      policy,
+      onAccepted: (connection) => {
+        void this.handleAcceptedConnection(
+          connection,
+          operatorListenerAccept(policy),
+        );
+      },
+    });
+  }
+
+  async removeListener(id: string): Promise<void> {
+    await unregisterListener(
+      this.coordinatorListeners,
+      this.defaultListenerId,
+      id,
+    );
+  }
+
+  listListeners(): ListenerInfo[] {
+    return listTrackedListeners(this.coordinatorListeners);
+  }
+
+  /** This side's own directly-reachable "host:port" candidates (wire-mesh#38), passed into every acceptMeshSession call's own self-advert -- see advertisedListenerAddresses' own doc for what's included/excluded and why. */
+  private get advertisedAddresses(): string[] {
+    return advertisedListenerAddresses(this.coordinatorListeners);
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Hub (agent-comms#154, per-store since agent-comms#293)
+  // -----------------------------------------------------------------------
+
+  joinHub(url: string, shouldConnect: () => boolean): void {
+    this.relay.joinHub(this.hub, url, shouldConnect);
+  }
+
+  reconsiderHub(): void {
+    this.relay.reconsiderHub();
+  }
+
+  setRelayEligible(eligible: boolean): void {
+    this.relay.setEligible(eligible);
+  }
+
+  // -----------------------------------------------------------------------
+  // MeshTransport -- Shutdown / unref
+  // -----------------------------------------------------------------------
+
+  async shutdown(): Promise<void> {
+    this.shutDown = true;
+    // A shut-down transport holds no listener, so it is no longer the coordinator -- leaving the flag set would have a second shutdown pass try to hand the role on, and would have isCoordinator lie to anything that outlives the transport.
+    this._isCoordinator = false;
+
+    // Closing starts here, ahead of every other cleanup step below (agent-comms#302), but the returned promises are deliberately not awaited until the end of this method. A graceful coordinator handover sends its become_coordinator message before this shutdown() call even starts (PeerLifecycle.sendCoordinatorHandover runs first in MeshStore.shutdown()), so the successor can already be racing to rebind this exact host:port through a bounded number of retries (bind-retry.ts) that assume the port frees up promptly. Node's net.Server.close() (which tls.Server inherits unchanged) releases the OS-level bound port as soon as it's *called* -- confirmed directly against the Node version this runs on, not assumed from the API docs -- but the promise it returns resolves only once every connection already accepted through that listener has also ended, exactly the delay #302 was caused by when close() itself wasn't even invoked until after that same cleanup ran. Firing close() now and awaiting it later, once sessions are already being closed anyway, gets both: the port frees at once for the successor, and shutdown() still doesn't return until the listeners are fully torn down. Nothing new should be accepted in the meantime regardless of exactly when the listener finishes closing, since shutDown is already true and handleAcceptedConnection's own guard closes anything that slips in.
+    const dataListenerClosing = this.dataListener?.close();
+    const coordinatorListenersClosing = [
+      ...this.coordinatorListeners.values(),
+    ].map(async (tracked) => tracked.listener.close());
+
+    await this.relay.stop();
+    if (this.gossipInterval !== undefined) {
+      clearInterval(this.gossipInterval);
+      this.gossipInterval = undefined;
+    }
+    this.dataFrames.stop();
+    this.dataDials.clear();
+
+    for (const pending of this.pendingConnections.values()) {
+      clearTimeout(pending.timeoutHandle);
+      await pending
+        .respond({ result: "error", code: "shutting_down" })
+        .catch(() => undefined);
+      // Unblocks consumeQuarantined's own suspended loop iteration for this session -- otherwise it never settles, even though the session itself is about to be closed below via allSessions.
+      pending.resolve("reject");
+    }
+    this.pendingConnections.clear();
+
+    // Every live session, whichever of possibly several to the same peer -- peerSessions alone would only close the last one registered under a shared key, leaving any other (e.g. the coordinator-client session to a peer this side also has a data connection to) still open.
+    for (const session of this.allSessions) {
+      await session.close().catch(() => undefined);
+    }
+    this.allSessions.clear();
+    this.electionSessions.clear();
+    this.peerSessions.clear();
+    this.coordinatorSession = undefined;
+
+    // The two closes started right at the top of this method have had this entire method's own cleanup time to finish now that every session they were waiting on is closed -- awaiting them here should very rarely find either still pending, but shutdown() still guarantees both listeners are fully torn down before it returns.
+    await dataListenerClosing;
+    this.dataListener = undefined;
+    await Promise.all(coordinatorListenersClosing);
+    this.coordinatorListeners.clear();
+  }
+
+  unref(): void {
+    this.dataListener?.unref?.();
+    for (const tracked of this.coordinatorListeners.values()) {
+      tracked.listener.unref?.();
+    }
+  }
+}