agent-comms 8.15.9 → 8.15.10

package/src/core/mesh-store.ts

@@ -0,0 +1,1114 @@
+/**
+ * MeshStore — transport-agnostic peer mesh for agent communication.
+ *
+ * Each bridge instance is a peer in the mesh. Peers find each other through first contact (a UDP presence beaconing over loopback multicast to stores on this machine and over limited broadcast to other machines on the LAN) or through the well-known port, whose holder introduces joiners; neither is required for peers to keep talking once connected. The coordinator duties are held by an elected CoordinatorRole, not by the port holder. All state is held in memory and synchronised between peers. Delivery events are pushed directly over the transport, with no polling and no filesystem.
+ *
+ * Transport is set via setTransport() (e.g. WireMeshTransport for encrypted connections) before init() or any other transport-using method is called -- there is no default, since every real bridge builds its own transport from this store's own events getter, which needs the store to already exist.
+ *
+ * MeshStore itself is an orchestrator: it owns the shared state (the core agents/rooms/messages/dms/deliveryQueues Maps and a handful of smaller fields) and constructs the collaborators that implement almost every behaviour against direct references into that state -- DeliveryEngine, RoomProtocol, RoomMessaging, RoomLifecycle, AgentRegistry, ConnectionApproval, StaleAgentChecker, and PeerLifecycle. Every public method below that isn't inherently a MeshStore-level concern (transport/identity wiring, init/shutdown lifecycle, the events getter, mesh visibility, listener management) is a thin delegating wrapper to whichever collaborator now owns the real implementation, kept here only because CommsStore/MeshOnlyFeatures and a handful of concrete-only call sites (tests, bridge-mesh.ts, the web server, etc.) reach these names directly on a MeshStore-typed value.
+ */
+
+import { bytesToHex, deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { GroupProofs } from "./group-proofs.js";
+import { Naming } from "./naming.js";
+import { Petnames } from "./petnames.js";
+import {
+  ROOM_JOIN_APPROVAL_TIMEOUT_MS,
+  ROOM_REQUEST_TIMEOUT_MS,
+} from "./request-timeouts.js";
+import { DiscoveryManager } from "./discovery.js";
+import { MdnsDiscoveryBackend } from "./discovery-mdns.js";
+import { TailscaleDiscoveryBackend } from "./discovery-tailscale.js";
+import type { MeshStoreIdentity } from "./mesh-store-shared.js";
+import { GatewayTrust, type VerifiedMember } from "./gateway-trust.js";
+import { ReceiverSet } from "./receiver-set.js";
+import {
+  ConnectionCodeLedger,
+  type GenerateConnectionCodeOptions,
+  type RedeemConnectionCodeOptions,
+  type RedeemConnectionCodeResult,
+} from "./connection-code.js";
+import type { MeshStoreOptions } from "./mesh-store-options.js";
+import { DeliveryEngine } from "./delivery-engine.js";
+import { RoomProtocol } from "./room-protocol.js";
+import { RoomMessaging } from "./room-messaging.js";
+import { RoomLifecycle } from "./room-lifecycle.js";
+import { AgentRegistry } from "./agent-registry.js";
+import { ConnectionApproval } from "./connection-approval.js";
+import { CapabilityAskAdmission } from "./capability-ask.js";
+import type { IncomingManageRequest } from "wire-mesh-core/domain/mesh-session";
+import type { DeviceId } from "wire-mesh-core/generated/protocol";
+import {
+  followLedgerRevocations,
+  type AccountLedgerReplica,
+} from "./account-ledger.js";
+import { StaleAgentChecker } from "./stale-agent-checker.js";
+import { PeerLifecycle } from "./peer-lifecycle.js";
+import {
+  CoordinatorRole,
+  type CoordinatorClaimView,
+} from "./coordinator-role.js";
+import type { RoomVerbHandler } from "./room-router.js";
+import { DEFAULT_PRESENCE_STALE_AFTER_MS } from "./gossip-extensions.js";
+import {
+  hostedRoomAdverts,
+  type AgentSelfAdvert,
+  type HostedRoomAdvert,
+} from "./gossip-extensions.js";
+import { peerVersionReaders } from "./peer-versions.js";
+import { listNetworkInterfaces } from "./network-interfaces.js";
+import {
+  parseListenerPolicy,
+  requireMeshGraph,
+  requireMeshTrace,
+} from "./transport-queries.js";
+import { ACCOUNT_JOIN_VERB, AccountJoin } from "./account-join.js";
+import { LanWebUis } from "./lan-web-uis.js";
+import { AGENT_DETAILS_VERB, AgentDetailsExchange } from "./agent-details.js";
+import type {
+  MeshStatePatch,
+  PeerInfo,
+  SerialisedState,
+} from "./wire-protocol.js";
+import type {
+  ListenerInfo,
+  MeshGraph,
+  MeshTraceResult,
+  MeshTransport,
+  TransportEvents,
+} from "./transport.js";
+import { createTransportEvents } from "./transport-events.js";
+import type {
+  CommsStore,
+  SendRoomMessageOptions,
+  SentDm,
+  SentRoomMessage,
+} from "./comms-store.js";
+import type { CapabilityToken } from "wire-mesh-core/generated/protocol";
+import type {
+  AgentIdentity,
+  AgentStatus,
+  ConnectionCode,
+  DeliveryEvent,
+  DmMessage,
+  MeshVisibility,
+  NetworkInterface,
+  Room,
+  RoomMessage,
+  RoomType,
+  StreamingBehavior,
+  Visibility,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_COORDINATOR_PORT = 19876;
+/** A device-id is a SHA-256 digest, so the stand-in peer ID a store starts with (every bridge replaces it with its identity's own device-id) has the same shape and can take part in the coordinator election. */
+const DEVICE_ID_BYTE_LENGTH = 32;
+
+// ---------------------------------------------------------------------------
+// MeshStore
+// ---------------------------------------------------------------------------
+
+export class MeshStore implements CommsStore {
+  peerId: string;
+  readonly startedAt: string;
+  readonly coordinatorPort: number;
+  private readonly hubUrl: string | undefined;
+  /** Read by whoever wires this store to a transport, so both halves of a room.join agree on the approval window. */
+  readonly roomJoinApprovalTimeoutMs: number;
+  /** Forwards a collaborator's failure to this store's own error channel, normalising a non-Error rejection on the way so a bridge always sees one shape. An arrow field rather than a method, so every collaborator can take it as a bare callback reference. */
+  private readonly reportError = (error: unknown): void => {
+    this.onError?.(error instanceof Error ? error : new Error(String(error)));
+  };
+
+  /** This device's own membership proofs under its user principal and its machine, and the checks for other devices' proofs (agent-comms#266, agent-comms#343). */
+  readonly membership = new GroupProofs({
+    getIdentity: () => this.requireIdentity(),
+    peekIdentity: () => this.storeIdentity,
+    getPeerId: () => this.peerId,
+    requireTransport: () => this.requireTransport(),
+    onError: this.reportError,
+  });
+
+  private readonly agents = new Map<string, AgentIdentity>();
+  private readonly rooms = new Map<string, Room>();
+  private readonly messages = new Map<string, RoomMessage[]>();
+  private readonly dms = new Map<string, DmMessage[]>();
+  private readonly deliveryQueues = new Map<string, DeliveryEvent[]>();
+  private readonly identityCache = new Map<string, { id: string }>();
+  private readonly peerInfo = new Map<string, PeerInfo>();
+  private readonly localDeliveryKeys = new Set<string>();
+  private readonly pendingMarkReadTimers: ReturnType<typeof setTimeout>[] = [];
+  /** DM paths this store has itself sent an outbound room.join for -- section 6's own basis for auto-approving the counterpart's reciprocal room.join without a second human decision. Shared between RoomProtocol (reads, in handleRoomJoin) and RoomLifecycle (writes, in requestDmAccess). Never cleared: a DM conversation, once opened, stays open, and holding a stale entry here costs nothing beyond a few bytes per DM this node has ever initiated. */
+  private readonly dmRequestsInitiatedByMe = new Set<string>();
+
+  private transport: MeshTransport | undefined;
+  private storeIdentity: MeshStoreIdentity | undefined;
+  private isShutDown = false;
+  private initialised = false;
+
+  discovery: DiscoveryManager;
+
+  /** The cross-machine trust boundary (agent-comms#156), constructed once in the constructor below (mirroring discovery above) and shared with WireMeshTransport by every construction site (bridge-mesh.ts, test-transport.ts) that passes it into WireMeshTransport's own constructor, so store.addTrustedGateway() and the transport's own hub-forwarding/hub-session gates read the exact same set. Persists across restarts (agent-comms#186) when a slot is passed to this store's own constructor; stays in-memory only, exactly as before, for every construction site that omits one. Public so those construction sites can reach it; addTrustedGateway/removeTrustedGateway/listTrustedGateways below are the methods CommsTool actually calls through MeshOnlyFeatures. */
+  readonly gatewayTrust: GatewayTrust;
+
+  /** Petnames, this machine's own name, and the namer every listing formats ids with (agent-comms#345). Handed to CommsTool alongside discovery. Petnames live beside gatewayTrust's file when a slot is given, in memory otherwise. */
+  readonly naming: Naming;
+
+  /** The connection-code generate/redeem pair (agent-comms#188) bootstrapping gatewayTrust above between two devices with no existing mesh connection. Persists across restarts per slot, from the slot passed to this store's own constructor, whereas gatewayTrust is shared by every slot in the slot's identity directory. generateConnectionCode/redeemConnectionCode below are the methods CommsTool actually calls through MeshOnlyFeatures; redeemConnectionCode is also where a successful redemption's deviceId gets fed into gatewayTrust.add, the actual point of this whole bootstrap. */
+  private readonly connectionCodes: ConnectionCodeLedger;
+
+  /** The LAN web UIs this machine's first-contact presence has heard web beacons for (agent-comms#353), listed by the lan_web_uis action. */
+  readonly lanWebUis = new LanWebUis();
+
+  /** Issues and answers account invites, and joins this machine to an account (agent-comms#344). Public so `agent-comms account invite` and `agent-comms account join` (account-cli.ts) reach it; deliberately not on CommsTool's surface (see account-join.ts). */
+  readonly account: AccountJoin;
+
+  private readonly deliveryEngine: DeliveryEngine;
+  private readonly roomProtocol: RoomProtocol;
+  private readonly roomMessaging: RoomMessaging;
+  private readonly roomLifecycle: RoomLifecycle;
+  private readonly agentRegistry: AgentRegistry;
+  private readonly connectionApproval: ConnectionApproval;
+  private readonly capabilityAskAdmission: CapabilityAskAdmission;
+  private readonly staleAgentChecker: StaleAgentChecker;
+  private readonly coordinatorRole: CoordinatorRole;
+  private readonly peerLifecycle: PeerLifecycle;
+
+  /** Whether this store holds the elected coordinator role (agent-comms#341), and so runs the stale-agent probe, announces departures, and fronts local Claude Code sessions. Independent of whether its transport holds the well-known port. */
+  get holdsCoordinatorRole(): boolean {
+    return this.coordinatorRole.isHolder();
+  }
+
+  /** The coordinator claim this store currently accepts (the elected holder's device-id and the term that put it there), or undefined before it has made or heard one. */
+  get coordinatorClaim(): CoordinatorClaimView | undefined {
+    return this.coordinatorRole.current();
+  }
+
+  /** This store's own current AgentStatus, synchronously -- the value WireMeshTransport's presence re-advertisement timer reads on every tick. undefined before registerAgent has ever run (no self agent record exists yet), in which case there is nothing yet to advertise. */
+  get selfStatus(): AgentStatus | undefined {
+    return this.agents.get(this.peerId)?.status;
+  }
+
+  /** This store's own currently-hosted public/private rooms, synchronously, in the lightweight gossip-safe shape WireMeshTransport's own hosted-rooms re-advertisement timer reads on every tick -- the write half of P3.8's room-discovery replacement for createRoom's own broadcastPatch (agent-comms#48). Secret rooms are never included (never worth advertising at all), and a room this store has merely replicated via the legacy room_upsert broadcast, rather than owns, is excluded too -- "hosted" means "this device is the one a joiner should actually reach", which only its own owner is. */
+  get hostedRooms(): readonly HostedRoomAdvert[] {
+    return hostedRoomAdverts(this.rooms, this.peerId);
+  }
+
+  /** This store's own gossip-safe agent-identity advert, synchronously, in the shape WireMeshTransport's own gossip re-advertisement timer reads on every tick -- the write half of P3.8's eventual agent register/update/offline retirement (agent-comms#48). undefined before registerAgent has ever run (nothing to advertise yet), or when this agent's own visibility isn't "visible" -- gossip already reaches every connected peer regardless of mesh-approval status (see wire-mesh-transport.ts's own allSessions/quarantine comments), so advertising a hidden or ghost agent's identity this way would leak exactly what those visibility levels exist to withhold. */
+  get selfAgentAdvert(): AgentSelfAdvert | undefined {
+    const agent = this.agents.get(this.peerId);
+    if (agent?.visibility !== "visible") return undefined;
+    return {
+      name: agent.name,
+      harness: agent.harness,
+      cwd: agent.cwd,
+      pid: agent.pid,
+      startedAt: agent.startedAt,
+      tags: agent.tags,
+      subscribedRooms: agent.subscribedRooms,
+      ...this.membership.advertFields(),
+    };
+  }
+
+  /**
+   * Whether this store should hold a hub session right now. It has something to say to another machine only when it has an agent that is not a ghost and its machine trusts at least one remote device, principal or machine. Until then, holding a session would put its device id on a public hub for nobody's benefit, and a ghost agent is by definition not reachable from anywhere. A hidden agent does hold one, and advertises only the device advert every session opens with, which is what lets it be reached by device id.
+   */
+  private wantsHubSession(): boolean {
+    const self = this.agents.get(this.peerId);
+    return (
+      self !== undefined &&
+      self.visibility !== "ghost" &&
+      this.gatewayTrust.hasAny()
+    );
+  }
+
+  /** Has the hub session re-evaluate wantsHubSession now, after a change to the agent or to the trust that it reads. Changes made by another process reach it within the link's poll interval instead. */
+  private reconsiderHub(): void {
+    this.requireTransport().reconsiderHub?.();
+  }
+
+  /** Whether the mesh has a live coordinator connection. */
+  get connected(): boolean {
+    return (
+      this.requireTransport().isCoordinator ||
+      this.requireTransport().hasCoordinatorConnection
+    );
+  }
+
+  onDelivery:
+    | ((agentId: string, event: DeliveryEvent) => void | Promise<void>)
+    | undefined;
+
+  private readonly deliveryReceivers = new ReceiverSet<
+    [agentId: string, event: DeliveryEvent]
+  >();
+
+  /**
+   * Observes every delivery event this store's own agent receives, alongside onDelivery, and returns a function that stops observing. Several parties can share one store this way, a bridge's own delivery handler and the web UI it serves, where a single assignable onDelivery would let whichever assigned last silence the other. A listener that throws or rejects is reported through onError and does not stop the others.
+   */
+  addDeliveryListener(
+    listener: (agentId: string, event: DeliveryEvent) => void | Promise<void>,
+  ): () => void {
+    return this.deliveryReceivers.add(listener);
+  }
+
+  /** Fires for every state patch — both locally generated and remote. */
+  onPatch: ((patch: MeshStatePatch) => void | Promise<void>) | undefined;
+
+  private readonly patchReceivers = new ReceiverSet<[patch: MeshStatePatch]>();
+
+  /**
+   * Observes every state patch, alongside onPatch, and returns a function that stops observing. The counterpart of addDeliveryListener: the web UI a bridge serves publishes patches from the bridge's own store, and must not take over the one assignable onPatch. A listener that throws or rejects is reported through onError and does not stop the others.
+   */
+  addPatchListener(
+    listener: (patch: MeshStatePatch) => void | Promise<void>,
+  ): () => void {
+    return this.patchReceivers.add(listener);
+  }
+
+  /**
+   * Fires for a transport-level error a caller may want to observe (a connection rejected for presenting a certificate that doesn't match its claimed peer ID, this store's own inability to join or create a mesh, etc). Left undefined by default (matching onDelivery/onPatch): a caller that wants visibility sets it, exactly like those two.
+   */
+  onError: ((error: Error) => void) | undefined;
+
+  /**
+   * Fires whenever this store gains or loses the elected coordinator role (agent-comms#341): true once a claim naming this store is accepted, false when a superseding claim is accepted or right before shutdown() gives the role up. Holding the well-known port has no bearing on it. A call runs only once the previous one has finished, so a caller stopping something asynchronously is never asked to start it again mid-stop. Left undefined by default (matching onDelivery/onPatch/onError): a caller that wants to react to owning the coordinator role (e.g. bridge-mesh.ts starting/stopping the cc-peer front (agent-comms#157), a Node/filesystem-specific capability that has no place in this transport-agnostic core) sets it, exactly like those three.
+   */
+  onCoordinatorRoleChanged:
+    ((isCoordinator: boolean) => void | Promise<void>) | undefined;
+
+  /** This process's own currently-running cc-peer package version, when it is actually fronting a cc-peer session or running the one-shot `bridge cc-peer` command (agent-comms#198) -- undefined by default (matching onDelivery/onPatch/onError/onCoordinatorRoleChanged), since every other bridge never loads the cc-peer package at all. Set once, right after construction, by front-runtime.ts/bridges/cc-peer/run.ts (a plain closure over cc-peer's own exported CC_PEER_VERSION constant) -- read by both this store's own WireMeshTransport construction (bridge-mesh.ts, for the gossiped versions advert) and CommsTool (for whoami/update/list_agents' own self-report), so the one field backs both surfaces. */
+  getCcPeerVersion: (() => string | undefined) | undefined;
+
+  /** Serialise the full mesh state for state_sync messages. */
+  serialise(): SerialisedState {
+    return {
+      agents: Object.fromEntries(this.agents),
+      rooms: Object.fromEntries(this.rooms),
+      messages: Object.fromEntries(this.messages),
+      dms: Object.fromEntries(this.dms),
+      deliveryQueues: Object.fromEntries(this.deliveryQueues),
+    };
+  }
+
+  constructor(options?: Readonly<MeshStoreOptions>) {
+    const {
+      coordinatorPort = DEFAULT_COORDINATOR_PORT,
+      hubUrl,
+      roomJoinApprovalTimeoutMs = ROOM_JOIN_APPROVAL_TIMEOUT_MS,
+      presenceStaleAfterMs = DEFAULT_PRESENCE_STALE_AFTER_MS,
+      coordinatorClaimWaitMs = ROOM_REQUEST_TIMEOUT_MS,
+      slot,
+    } = options ?? {};
+    this.peerId = bytesToHex(
+      crypto.getRandomValues(new Uint8Array(DEVICE_ID_BYTE_LENGTH)),
+    );
+    this.startedAt = new Date().toISOString();
+    this.coordinatorPort = coordinatorPort;
+    this.hubUrl = hubUrl;
+    this.roomJoinApprovalTimeoutMs = roomJoinApprovalTimeoutMs;
+    this.gatewayTrust = new GatewayTrust({ location: slot });
+    this.naming = new Naming({
+      petnames: new Petnames(slot),
+      issuerNames: async () => this.membership.issuerNames(),
+      listAgents: async (requesterId) => this.listAgents(requesterId),
+      saveMachineName: async (name) => this.membership.saveMachineName(name),
+      saveUserName: async (name) => this.membership.saveUserName(name),
+    });
+    this.connectionCodes = new ConnectionCodeLedger(slot);
+    this.account = new AccountJoin({
+      requireIdentity: () => this.requireIdentity(),
+      requireTransport: () => this.requireTransport(),
+      getPeerId: () => this.peerId,
+      connectionCodes: this.connectionCodes,
+      gatewayTrust: this.gatewayTrust,
+      reconsiderHub: this.reconsiderHub.bind(this),
+      setPetname: (deviceHex, name) => this.naming.setPetname(deviceHex, name),
+      redeemConnectionCode: this.redeemConnectionCode.bind(this),
+      setIdentity: this.setIdentity.bind(this),
+    });
+
+    // Discovery manager — registers available backends
+    this.discovery = new DiscoveryManager();
+    this.discovery.registerBackend(new MdnsDiscoveryBackend());
+    this.discovery.registerBackend(new TailscaleDiscoveryBackend());
+
+    this.deliveryEngine = new DeliveryEngine({
+      agents: this.agents,
+      rooms: this.rooms,
+      messages: this.messages,
+      dms: this.dms,
+      deliveryQueues: this.deliveryQueues,
+      localDeliveryKeys: this.localDeliveryKeys,
+      pendingMarkReadTimers: this.pendingMarkReadTimers,
+      getPeerId: () => this.peerId,
+      requireIdentity: () => this.requireIdentity(),
+      requireTransport: () => this.requireTransport(),
+      getOnDelivery: () =>
+        this.deliveryReceivers.handler(this.onDelivery, this.reportError),
+      getOnPatch: () =>
+        this.patchReceivers.handler(this.onPatch, this.reportError),
+      isShutDown: () => this.isShutDown,
+      // RoomProtocol doesn't exist yet at this point in the constructor -- this closure resolves `this.roomProtocol` lazily, only once markRead actually calls it at runtime, well after the constructor has finished.
+      sendRoomRequestToMember: async (...args) =>
+        this.roomProtocol.sendRoomRequestToMember(...args),
+    });
+
+    this.roomProtocol = new RoomProtocol({
+      rooms: this.rooms,
+      messages: this.messages,
+      dms: this.dms,
+      agents: this.agents,
+      dmRequestsInitiatedByMe: this.dmRequestsInitiatedByMe,
+      getPeerId: () => this.peerId,
+      requireIdentity: () => this.requireIdentity(),
+      requireTransport: () => this.requireTransport(),
+      deliveryEngine: this.deliveryEngine,
+      joinDecisionTimeoutMs: this.roomJoinApprovalTimeoutMs,
+      // RoomLifecycle doesn't exist yet at this point -- deferred the same way DeliveryEngine's sendRoomRequestToMember closure above is.
+      revokeMemberGrant: async (roomId, memberId) =>
+        this.roomLifecycle.revokeMemberGrant(roomId, memberId),
+    });
+
+    this.roomMessaging = new RoomMessaging({
+      rooms: this.rooms,
+      messages: this.messages,
+      dms: this.dms,
+      requireIdentity: () => this.requireIdentity(),
+      roomProtocol: this.roomProtocol,
+      // RoomLifecycle doesn't exist yet at this point -- deferred the same lazy-`this`-capture way as the closures above.
+      requestDmAccess: async (counterpart) =>
+        this.roomLifecycle.requestDmAccess(counterpart),
+      resolveRoomId: (roomIdOrName) =>
+        this.roomLifecycle.resolveRoomId(roomIdOrName),
+      // AgentRegistry doesn't exist yet at this point in the constructor -- deferred the same lazy-`this`-capture way DeliveryEngine's own sendRoomRequestToMember closure above is.
+      resolveAgent: async (id) => this.agentRegistry.getAgent(id),
+    });
+
+    this.roomLifecycle = new RoomLifecycle({
+      rooms: this.rooms,
+      messages: this.messages,
+      agents: this.agents,
+      dmRequestsInitiatedByMe: this.dmRequestsInitiatedByMe,
+      getPeerId: () => this.peerId,
+      requireIdentity: () => this.requireIdentity(),
+      requireTransport: () => this.requireTransport(),
+      deliveryEngine: this.deliveryEngine,
+    });
+
+    this.agentRegistry = new AgentRegistry({
+      agents: this.agents,
+      identityCache: this.identityCache,
+      startedAt: this.startedAt,
+      getPeerId: () => this.peerId,
+      requireTransport: () => this.requireTransport(),
+      presenceStaleAfterMs,
+      deliveryEngine: this.deliveryEngine,
+    });
+
+    this.connectionApproval = new ConnectionApproval({
+      agents: this.agents,
+      peerInfo: this.peerInfo,
+      startedAt: this.startedAt,
+      getPeerId: () => this.peerId,
+      requireTransport: () => this.requireTransport(),
+      getOnDelivery: () =>
+        this.deliveryReceivers.handler(this.onDelivery, this.reportError),
+      queueDelivery: (agentId, event) => {
+        this.deliveryEngine.queueDelivery(agentId, event);
+      },
+    });
+
+    this.capabilityAskAdmission = new CapabilityAskAdmission({
+      getPeerId: () => this.peerId,
+      getOnDelivery: () =>
+        this.deliveryReceivers.handler(this.onDelivery, this.reportError),
+      queueDelivery: (agentId, event) => {
+        this.deliveryEngine.queueDelivery(agentId, event);
+      },
+    });
+
+    this.staleAgentChecker = new StaleAgentChecker({
+      agents: this.agents,
+      deliveryQueues: this.deliveryQueues,
+      identityCache: this.identityCache,
+      peerInfo: this.peerInfo,
+      notifyRoomsOfStatus: async (agentId, status) =>
+        this.deliveryEngine.notifyRoomsOfStatus(agentId, status),
+      broadcastPatch: async (patch) =>
+        this.deliveryEngine.broadcastPatch(patch),
+      bump: (agent) => {
+        this.deliveryEngine.bump(agent);
+      },
+    });
+
+    this.coordinatorRole = new CoordinatorRole({
+      getPeerId: () => this.peerId,
+      requireTransport: () => this.requireTransport(),
+      claimWaitMs: coordinatorClaimWaitMs,
+      onGained: async () => {
+        this.staleAgentChecker.start();
+        this.requireTransport().setRelayEligible?.(true);
+        await this.onCoordinatorRoleChanged?.(true);
+      },
+      onLost: async () => {
+        this.staleAgentChecker.stop();
+        this.requireTransport().setRelayEligible?.(false);
+        await this.onCoordinatorRoleChanged?.(false);
+      },
+      onError: this.reportError,
+    });
+
+    this.peerLifecycle = new PeerLifecycle({
+      peerInfo: this.peerInfo,
+      agents: this.agents,
+      coordinatorPort: this.coordinatorPort,
+      firstContactPort: options?.firstContactPort,
+      onWebBeacon: (b) => {
+        this.lanWebUis.recordBeacon(b);
+      },
+      getPeerId: () => this.peerId,
+      getCoordinatorPeerId: () => this.requireTransport().coordinatorPeerId,
+      requireTransport: () => this.requireTransport(),
+      serialise: () => this.serialise(),
+      roomProtocol: this.roomProtocol,
+      deliveryEngine: this.deliveryEngine,
+      coordinatorRole: this.coordinatorRole,
+      onError: this.reportError,
+    });
+  }
+
+  /** Sets the transport (e.g. WireMeshTransport for encrypted connections). Must be called before init() or any other transport-using method. */
+  setTransport(transport: Readonly<MeshTransport>): void {
+    this.transport = transport;
+  }
+
+  /** The set transport, or throws if setTransport() hasn't been called yet -- the single place every transport-using method reads through, so the "must call setTransport() first" contract is enforced at one boundary rather than checked ad hoc at each call site. */
+  private requireTransport(): MeshTransport {
+    if (this.transport === undefined) {
+      throw new Error(
+        "MeshStore: no transport set; call setTransport() before using the store",
+      );
+    }
+    return this.transport;
+  }
+
+  /** Stops feeding the current account ledger's replicated revocations into the RevocationView; undefined until an identity is attached. */
+  private stopFollowingLedger: (() => void) | undefined;
+
+  /** Sets the identity/clock/slot this store mints and persists room-membership grants against. Must be called before createRoom() or any other identity-using method, mirroring setTransport()'s own contract. */
+  setIdentity(identity: MeshStoreIdentity): void {
+    this.storeIdentity = identity;
+    this.membership.start();
+    this.stopFollowingLedger?.();
+    this.stopFollowingLedger = followLedgerRevocations(
+      identity,
+      this.reportError,
+    );
+  }
+
+  /** The account's replicated grant ledger (agent-comms#344) once an identity is attached, for the transport to replicate. */
+  get accountLedger(): AccountLedgerReplica | undefined {
+    return this.storeIdentity?.accountLedger;
+  }
+
+  /** Every device this side trusts only because a trusted principal or machine vouches for it, with that issuer. */
+  readonly listVerifiedMembers = (): VerifiedMember[] =>
+    this.gatewayTrust.listVerifiedMembers();
+
+  /** The machine (hex) of each device this side can place on one, keyed by device id (agent-comms#343): this device's own, and every gossiped device carrying a valid machine proof. Empty before this store's identity is attached. */
+  readonly listAgentMachines = async (): Promise<Map<string, string>> =>
+    await this.membership.machinesByDevice();
+
+  /** The set identity, or throws if setIdentity() hasn't been called yet -- the single place every identity-using method reads through, mirroring requireTransport() above. */
+  private requireIdentity(): MeshStoreIdentity {
+    if (this.storeIdentity === undefined) {
+      throw new Error(
+        "MeshStore: no identity set; call setIdentity() before using the store",
+      );
+    }
+    return this.storeIdentity;
+  }
+
+  // -----------------------------------------------------------------------
+  // Mesh lifecycle
+  // -----------------------------------------------------------------------
+
+  async init(): Promise<void> {
+    if (this.initialised) return;
+    this.initialised = true;
+    await this.requireTransport().startDataServer();
+    if (this.hubUrl !== undefined) {
+      this.requireTransport().joinHub?.(this.hubUrl, () =>
+        this.wantsHubSession(),
+      );
+    }
+
+    // Register our own peer info
+    this.peerInfo.set(this.peerId, {
+      id: this.peerId,
+      port: this.requireTransport().dataPort,
+      startedAt: this.startedAt,
+    });
+
+    await this.peerLifecycle.joinWellKnownPort();
+
+    this.requireTransport().unref();
+
+    // First contact (agent-comms#341): a coordinator-free presence on this machine or LAN, owned by PeerLifecycle; a no-op unless a firstContactPort was configured, which only bridge-mesh (every real bridge's shared bootstrap) does.
+    this.peerLifecycle.startFirstContact();
+  }
+
+  // -----------------------------------------------------------------------
+  // Transport events accessor (for bridges to wire up)
+  // -----------------------------------------------------------------------
+
+  /** Returns the TransportEvents object that bridges should pass to the transport constructor. */
+  get events(): TransportEvents {
+    return createTransportEvents({
+      peerLifecycle: this.peerLifecycle,
+      connectionApproval: this.connectionApproval,
+      deliveryEngine: this.deliveryEngine,
+      roomProtocol: this.roomProtocol,
+      coordinatorRole: this.coordinatorRole,
+      reportError: this.reportError,
+    });
+  }
+
+  /** Both halves of the agent-comms/agent-details exchange (agent-comms#323): the verb a trusted peer's request is answered by, and the background fetch filling this side's cache from peers this machine trusts. */
+  readonly agentDetailsExchange = new AgentDetailsExchange({
+    selfAgent: () => this.agents.get(this.peerId),
+    hostedRooms: () => this.hostedRooms,
+    isTrusted: (hex) => this.gatewayTrust.isTrusted(hex),
+    requireTransport: () => this.requireTransport(),
+  });
+  /** Room verb handlers this store registers with its own WireMeshTransport, keyed by params.verb per room-router.ts's own dispatch discipline. */
+  get roomVerbHandlers(): Partial<Record<string, RoomVerbHandler>> {
+    return {
+      ...this.roomProtocol.roomVerbHandlers,
+      [ACCOUNT_JOIN_VERB]: this.account.handleJoinRequest,
+      [AGENT_DETAILS_VERB]: this.agentDetailsExchange.handler,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Identity
+  // -----------------------------------------------------------------------
+
+  async readIdentity(
+    harness: string,
+    cwd: string,
+  ): Promise<{ id: string } | undefined> {
+    return this.agentRegistry.readIdentity(harness, cwd);
+  }
+
+  async writeIdentity(harness: string, cwd: string, id: string): Promise<void> {
+    return this.agentRegistry.writeIdentity(harness, cwd, id);
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Agent registry
+  // -----------------------------------------------------------------------
+
+  async registerAgent(opts: {
+    name: string;
+    harness: string;
+    cwd: string;
+    pid: number;
+    visibility: Visibility;
+    tags: string[];
+  }): Promise<AgentIdentity> {
+    const agent = await this.agentRegistry.registerAgent(opts);
+    this.reconsiderHub();
+    return agent;
+  }
+
+  async getAgent(id: string): Promise<AgentIdentity | undefined> {
+    return this.agentRegistry.getAgent(id);
+  }
+
+  async updateAgent(
+    id: string,
+    patch: Partial<
+      Pick<AgentIdentity, "name" | "visibility" | "status" | "tags" | "pid">
+    >,
+  ): Promise<AgentIdentity> {
+    const agent = await this.agentRegistry.updateAgent(id, patch);
+    this.reconsiderHub();
+    return agent;
+  }
+
+  async listAgents(requesterId: string): Promise<AgentIdentity[]> {
+    return this.agentRegistry.listAgents(requesterId);
+  }
+
+  async setAgentOffline(id: string): Promise<void> {
+    return this.agentRegistry.setAgentOffline(id);
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Rooms
+  // -----------------------------------------------------------------------
+
+  async createRoom(
+    opts: Readonly<{
+      name: string;
+      type: RoomType;
+      owner: string;
+      description: string;
+    }>,
+  ): Promise<Room> {
+    return this.roomLifecycle.createRoom(opts);
+  }
+
+  async getRoom(id: string): Promise<Room | undefined> {
+    return this.roomLifecycle.getRoom(id);
+  }
+
+  async listRooms(requesterId: string): Promise<Room[]> {
+    return this.roomLifecycle.listRooms(requesterId);
+  }
+
+  /** Refreshes this store's own local copy of a named room's membership and room-state via a real room.members request (P3.6). Concrete-only -- reached directly by tests. */
+  async refreshRoomMembers(roomPath: string): Promise<Room> {
+    return this.roomLifecycle.refreshRoomMembers(roomPath);
+  }
+
+  /** The requester's own half of section 6's two-round DM consent flow, optionally presenting a dm:send grant (agent-comms#162) the counterpart's own user principal already minted for this device via admitAgentForDm -- when given and valid, the counterpart auto-admits immediately rather than holding the request open for a human decision. Deliberately outside the CommsStore interface, like connection approval, since it is a wire-mesh-specific concern FileStore has no equivalent for. Concrete-only -- reached directly by tests. */
+  async requestDmAccess(
+    counterpart: string,
+    dmSendGrant?: CapabilityToken,
+  ): Promise<void> {
+    return this.roomLifecycle.requestDmAccess(counterpart, dmSendGrant);
+  }
+
+  /** Presents a dm:send grant issued by another user -- see RoomLifecycle.presentDmGrant. */
+  async presentDmGrant(
+    counterpart: string,
+    grant: CapabilityToken,
+  ): Promise<void> {
+    return this.roomLifecycle.presentDmGrant(counterpart, grant);
+  }
+
+  /** This user's own principal id (hex): the identity every device on this account shares, and the thing another user names to admit or trust this whole user rather than one device. Undefined until this store's identity is attached. */
+  getUserPrincipalId(): string | undefined {
+    const user = this.storeIdentity?.userIdentity;
+    return user === undefined ? undefined : deviceIdToHex(user.deviceId);
+  }
+
+  /** This store's machine id (hex, agent-comms#343): the identity every bridge this OS account runs on the host shares, and the thing another machine names to trust or revoke all of them at once. Undefined until this store's identity is attached. */
+  getMachineId(): string | undefined {
+    const machine = this.storeIdentity?.machineIdentity;
+    return machine === undefined ? undefined : deviceIdToHex(machine.deviceId);
+  }
+
+  /** Admits bearerId into this user's own DM-communication scope (agent-comms#162): mints and persists a dm:send grant, self-signed by this store's own user principal. Returns the minted token for the caller to deliver to bearerId out of band. Deliberately outside the CommsStore interface, like requestDmAccess above. Concrete-only -- reached directly by tests. delegationsRemaining defaults to 0 (non-delegable, the original behaviour); a positive value admits bearerId as a user principal capable of sub-delegating to its own devices (agent-comms#187) -- see RoomLifecycle.admitAgentForDm's own doc comment. */
+  async admitAgentForDm(
+    bearerId: string,
+    delegationsRemaining = 0,
+  ): Promise<CapabilityToken> {
+    return this.roomLifecycle.admitAgentForDm(bearerId, delegationsRemaining);
+  }
+
+  /** Revokes bearerId's own dm:send grant for real (agent-comms#162), the DM-scope counterpart to kickFromRoom. A no-op if bearerId was never admitted. Deliberately outside the CommsStore interface, like requestDmAccess above. Concrete-only -- reached directly by tests. */
+  async revokeAgentDmAccess(bearerId: string): Promise<void> {
+    return this.roomLifecycle.revokeAgentDmAccess(bearerId);
+  }
+
+  async joinRoom(roomId: string, agentId: string): Promise<Room> {
+    return this.roomLifecycle.joinRoom(roomId, agentId);
+  }
+
+  async leaveRoom(roomId: string, agentId: string): Promise<void> {
+    return this.roomLifecycle.leaveRoom(roomId, agentId);
+  }
+
+  async inviteToRoom(
+    roomId: string,
+    targetId: string,
+    inviterId: string,
+  ): Promise<void> {
+    return this.roomLifecycle.inviteToRoom(roomId, targetId, inviterId);
+  }
+
+  async declineInvite(
+    roomId: string,
+    agentId: string,
+    reason: string,
+  ): Promise<void> {
+    return this.roomLifecycle.declineInvite(roomId, agentId, reason);
+  }
+
+  async kickFromRoom(
+    roomId: string,
+    targetId: string,
+    kickerId: string,
+  ): Promise<void> {
+    return this.roomLifecycle.kickFromRoom(roomId, targetId, kickerId);
+  }
+
+  async destroyRoom(roomId: string, agentId: string): Promise<void> {
+    return this.roomLifecycle.destroyRoom(roomId, agentId);
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Messages
+  // -----------------------------------------------------------------------
+
+  async sendRoomMessage(
+    roomId: string,
+    from: string,
+    content: string,
+    options?: SendRoomMessageOptions,
+  ): Promise<SentRoomMessage> {
+    return this.roomMessaging.sendRoomMessage(roomId, from, content, options);
+  }
+
+  async readRoomMessages(
+    roomId: string,
+    since?: string,
+  ): Promise<RoomMessage[]> {
+    return this.roomMessaging.readRoomMessages(roomId, since);
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — DMs
+  // -----------------------------------------------------------------------
+
+  async sendDm(
+    from: string,
+    to: string,
+    content: string,
+    streamingBehavior?: StreamingBehavior,
+  ): Promise<SentDm> {
+    return this.roomMessaging.sendDm(from, to, content, streamingBehavior);
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Delivery
+  // -----------------------------------------------------------------------
+
+  async deliver(agentId: string, event: DeliveryEvent): Promise<void> {
+    return this.deliveryEngine.deliver(agentId, event);
+  }
+
+  async drainDelivery(agentId: string): Promise<DeliveryEvent[]> {
+    return this.deliveryEngine.drainDelivery(agentId);
+  }
+
+  // -----------------------------------------------------------------------
+  // Concrete-only surface reached directly by tests
+  // -----------------------------------------------------------------------
+
+  /** Merge a peer's state snapshot into the local state (#27/#28). Concrete-only -- reached directly by tests. */
+  applyStateSync(state: SerialisedState): void {
+    this.deliveryEngine.applyStateSync(state);
+  }
+
+  /** Sends one directed room.send to a single member's own session (P3.5). Concrete-only -- reached directly by tests. */
+  async sendRoomMessageDirected(
+    roomPath: string,
+    memberId: string,
+    text: string,
+  ): Promise<void> {
+    return this.roomProtocol.sendRoomMessageDirected(roomPath, memberId, text);
+  }
+
+  /** Starts only the data server without connecting to a coordinator. Used for testing scenarios where the peer connects via connectToRemote. */
+  async startDataServerOnly(): Promise<void> {
+    return this.connectionApproval.startDataServerOnly();
+  }
+
+  // -----------------------------------------------------------------------
+  // Connection approval (mesh-only)
+  // -----------------------------------------------------------------------
+
+  /** Accept a pending inbound connection. */
+  async acceptConnection(connectionId: string): Promise<void> {
+    return this.connectionApproval.acceptConnection(connectionId);
+  }
+
+  /** Reject a pending inbound connection. */
+  async rejectConnection(connectionId: string, reason: string): Promise<void> {
+    return this.connectionApproval.rejectConnection(connectionId, reason);
+  }
+
+  /** List all pending inbound connections awaiting approval. */
+  listPendingConnections(): {
+    connectionId: string;
+    peerId: string;
+    dataPort: number;
+    name: string;
+    fingerprint: string;
+  }[] {
+    return this.connectionApproval.listPendingConnections();
+  }
+
+  /** Initiate an outbound connection to a remote coordinator requiring approval. */
+  async connectToRemote(host: string, port: number): Promise<void> {
+    return this.connectionApproval.connectToRemote(host, port);
+  }
+
+  // -----------------------------------------------------------------------
+  // Room-join approval (mesh-only)
+  // -----------------------------------------------------------------------
+
+  /** Every room.join request currently held open awaiting this store's own accept/reject decision. */
+  listPendingRoomJoins(): { roomPath: string; requesterId: string }[] {
+    return this.roomProtocol.listPendingRoomJoins();
+  }
+
+  /** Approves a pending room.join request. */
+  acceptRoomJoin(roomPath: string, requesterId: string): void {
+    this.roomProtocol.acceptRoomJoin(roomPath, requesterId);
+  }
+
+  /** Denies a pending room.join request, optionally with a reason. */
+  rejectRoomJoin(roomPath: string, requesterId: string, reason?: string): void {
+    this.roomProtocol.rejectRoomJoin(roomPath, requesterId, reason);
+  }
+
+  // -----------------------------------------------------------------------
+  // Capability-request ask tier (mesh-only, agent-comms#165)
+  // -----------------------------------------------------------------------
+
+  /** Builds a manage-request handler surfacing one capability's incoming capability-requests as held-open asks (agent-comms#165's own tool-layer surface for the ask tier) -- the registration point a capability-gated verb (e.g. agent-comms#162's dm:send) wires into its own session dispatch, backed by this store's identity/clock and this admission's live pending state. */
+  createCapabilityAskHandler(
+    options: Readonly<{
+      capability: string;
+      bearerDevice: DeviceId;
+      timeoutMs: number;
+    }>,
+  ): (incoming: Readonly<IncomingManageRequest>) => Promise<void> {
+    const { identity, clock } = this.requireIdentity();
+    return this.capabilityAskAdmission.createAskHandler({
+      capability: options.capability,
+      identity,
+      clock,
+      bearerDevice: options.bearerDevice,
+      timeoutMs: options.timeoutMs,
+    });
+  }
+
+  /** Every capability-request currently held open awaiting this store's own accept/reject decision. */
+  listPendingCapabilityRequests(): {
+    requestId: string;
+    capability: string;
+    scopeKind: string;
+    scopePath?: string;
+    requesterDevice: string;
+  }[] {
+    return this.capabilityAskAdmission.listPendingCapabilityRequests();
+  }
+
+  /** Approves a pending capability request, minting and returning the granted token. */
+  async acceptCapabilityRequest(
+    requestId: string,
+    options: Readonly<{
+      expires: number;
+      delegationsRemaining?: number;
+      capability?: string;
+    }>,
+  ): Promise<void> {
+    await this.capabilityAskAdmission.acceptCapabilityRequest(
+      requestId,
+      options,
+    );
+  }
+
+  /** Denies a pending capability request, optionally with a reason. */
+  async rejectCapabilityRequest(
+    requestId: string,
+    reason?: string,
+  ): Promise<void> {
+    await this.capabilityAskAdmission.rejectCapabilityRequest(
+      requestId,
+      reason,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // Mesh visibility
+  // -----------------------------------------------------------------------
+
+  /** Set mesh discovery visibility. Delegates to discovery manager. */
+  async setVisibility(level: MeshVisibility, adapter?: string): Promise<void> {
+    await this.discovery.setVisibility(level, adapter);
+  }
+
+  /** Get current mesh discovery visibility. */
+  getVisibility(adapter?: string): MeshVisibility {
+    return this.discovery.getVisibility(adapter);
+  }
+
+  // -----------------------------------------------------------------------
+  // Gateway trust (agent-comms#156) -- the cross-machine trust boundary
+  // -----------------------------------------------------------------------
+
+  /** Trusts a remote device-id (hex): this store will advertise itself on the hub, merge this device's gossiped directory entries, dispatch its relayed requests, and route outbound hub requests to it. The trust is shared by every store on the machine and survives a restart. See GatewayTrust's own class doc for why it is keyed per device-id rather than per remote machine. Trusting a device is itself a route to it appearing, so anything queued for it is retried immediately rather than waiting out the hub's next gossip tick. */
+  addTrustedGateway(deviceHex: string): void {
+    this.gatewayTrust.add(deviceHex);
+    this.reconsiderHub();
+    void this.roomProtocol.flushPendingRoomRequests(deviceHex);
+  }
+
+  /** Withdraws trust from a remote device-id (hex). A no-op if it was never trusted. */
+  removeTrustedGateway(deviceHex: string): void {
+    this.gatewayTrust.remove(deviceHex);
+    this.reconsiderHub();
+  }
+
+  /** Every currently trusted remote device-id (hex). */
+  readonly listTrustedGateways = (): string[] => this.gatewayTrust.list();
+
+  /** Trusts a remote user-principal device-id (hex, agent-comms#187): a peer presenting a token whose delegation chain roots at this principal is trusted via GatewayTrust.isTrustedFor, without its own bare device-id ever needing individual trust. Entirely independent of the bare-device allowlist addTrustedGateway manages. */
+  addTrustedGatewayPrincipal(deviceHex: string): void {
+    this.gatewayTrust.addPrincipal(deviceHex);
+    this.reconsiderHub();
+  }
+
+  /** Withdraws trust from a remote user-principal device-id (hex). A no-op if it was never trusted. */
+  removeTrustedGatewayPrincipal(deviceHex: string): void {
+    this.gatewayTrust.removePrincipal(deviceHex);
+    this.reconsiderHub();
+  }
+
+  /** Every currently trusted remote user-principal device-id (hex). */
+  readonly listTrustedGatewayPrincipals = (): string[] =>
+    this.gatewayTrust.listPrincipals();
+
+  /** Trusts a remote machine device-id (hex, agent-comms#343): every device whose gossiped proof that machine vouches for becomes reachable without being trusted individually. */
+  addTrustedGatewayMachine(deviceHex: string): void {
+    this.gatewayTrust.addMachine(deviceHex);
+    this.reconsiderHub();
+  }
+
+  /** Withdraws trust from a remote machine device-id (hex), and with it every device reachable only through that machine: revoking every bridge that machine key vouches for in one act. A no-op if it was never trusted. */
+  removeTrustedGatewayMachine(deviceHex: string): void {
+    this.gatewayTrust.removeMachine(deviceHex);
+    this.reconsiderHub();
+  }
+
+  /** Every currently trusted remote machine device-id (hex). */
+  readonly listTrustedGatewayMachines = (): string[] =>
+    this.gatewayTrust.listMachines();
+
+  // -----------------------------------------------------------------------
+  // Connection codes (agent-comms#188) -- bootstrapping gateway trust with no existing mesh connection between the two devices
+  // -----------------------------------------------------------------------
+
+  /** Generates a fresh single-use ConnectionCode vouching for this store's own device-id (peerId), for the operator to relay to a counterpart out of band. See ConnectionCodeLedger.generate's own doc comment for what options does. */
+  async generateConnectionCode(
+    options: Readonly<GenerateConnectionCodeOptions> = {},
+  ): Promise<ConnectionCode> {
+    return this.connectionCodes.generate(this.peerId, options);
+  }
+
+  /** Validates a candidate ConnectionCode (see ConnectionCodeLedger.redeem for the checks performed) and, only once it passes every check, trusts the device-id it vouches for via gatewayTrust.add -- the actual point of this whole bootstrap. A rejected candidate never reaches gatewayTrust at all. */
+  async redeemConnectionCode(
+    candidate: Readonly<ConnectionCode>,
+    options: Readonly<RedeemConnectionCodeOptions> = {},
+  ): Promise<RedeemConnectionCodeResult> {
+    const result = await this.connectionCodes.redeem(candidate, options);
+    this.gatewayTrust.add(result.deviceId);
+    this.reconsiderHub();
+    return result;
+  }
+
+  // -----------------------------------------------------------------------
+  // Listener management (coordinator only)
+  // -----------------------------------------------------------------------
+
+  async addListener(
+    host: string,
+    port: number,
+    policy: string,
+  ): Promise<string> {
+    return this.requireTransport().addListener(
+      host,
+      port,
+      parseListenerPolicy(policy),
+    );
+  }
+
+  async removeListener(id: string): Promise<void> {
+    await this.requireTransport().removeListener(id);
+  }
+
+  readonly listListeners = (): ListenerInfo[] =>
+    this.requireTransport().listListeners();
+
+  /** Delegates to the transport's own meshGraph, throwing if the current transport doesn't support it (agent-comms#199) -- CommsTool's own notMeshBacked distinguishes "no MeshStore at all" from this narrower "MeshStore, but a transport without this capability" case by catching the throw, the same way requireTransport's own "no transport set" throw is already handled. */
+  meshGraph(): MeshGraph {
+    return requireMeshGraph(this.requireTransport());
+  }
+
+  /** Delegates to the transport's own meshTrace, same "throw if unsupported" contract as meshGraph above. */
+  async meshTrace(
+    target: string,
+    timeoutMs?: number,
+  ): Promise<MeshTraceResult> {
+    return requireMeshTrace(this.requireTransport(), target, timeoutMs);
+  }
+
+  readonly getNetworkInterfaces = (): NetworkInterface[] =>
+    listNetworkInterfaces();
+
+  // -----------------------------------------------------------------------
+  // Peer versions (agent-comms#198)
+  // -----------------------------------------------------------------------
+
+  private readonly peerVersions = peerVersionReaders(() =>
+    this.requireTransport(),
+  );
+
+  /** deviceId's own gossiped agent-comms package version, if this side has heard it advertised. */
+  readonly getPeerAgentCommsVersion = this.peerVersions.agentComms;
+
+  /** deviceId's own gossiped cc-peer package version, present only while that device is fronting a cc-peer session or running `bridge cc-peer`. */
+  readonly getPeerCcPeerVersion = this.peerVersions.ccPeer;
+
+  /** deviceId's own gossiped wire-mesh-core version (wire-mesh#179). */
+  readonly getPeerWireMeshCoreVersion = this.peerVersions.wireMeshCore;
+
+  /** Asks deviceId for its own, currently-running wire-mesh-core version live rather than trusting whatever it last gossiped (the query_version action's backing call). */
+  readonly queryVersion = this.peerVersions.query;
+
+  // -----------------------------------------------------------------------
+  // Shutdown
+  // -----------------------------------------------------------------------
+
+  async shutdown(): Promise<void> {
+    // Idempotent: a bridge's signal handler and whatever already owns its exit path can both reach here, and a second pass would try to hand the coordinator role on over sessions the first pass has already closed.
+    if (this.isShutDown) return;
+    this.isShutDown = true;
+    this.membership.stop();
+    this.peerLifecycle.stopFirstContact();
+    // 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);
+    // Sent first, so the notice goes out ahead of every session closing, but not waited on until the transport has shut down. A peer that cannot be told is a peer that has gone, so a failure to send it is dropped. Each peer's answer comes under the network deadline, so waiting here would spend that whole deadline on a peer that has gone without this side noticing yet; closing the sessions is what ends every wait that is still open.
+    let farewell: Promise<void> | undefined;
+    if (agent) {
+      agent.status = "offline";
+      farewell = this.deliveryEngine
+        .broadcastPatch({ type: "agent_offline", agentId: this.peerId })
+        .catch(() => undefined);
+    }
+
+    // Gives the elected coordinator role up (stopping the stale-agent probe and firing onCoordinatorRoleChanged(false)) when this store held it; survivors recover it from this store's departure.
+    await this.coordinatorRole.stop();
+    // Graceful handover of the well-known port listener (agent-comms#170): a no-op unless this side currently holds it, so this runs unconditionally rather than being gated behind an isCoordinator check duplicated here. Must run before the transport shuts down: the handoff message rides the very peer sessions shutdown() is about to close.
+    await this.peerLifecycle.sendCoordinatorHandover();
+    await this.requireTransport().shutdown();
+    await farewell;
+  }
+}