agent-comms 8.15.8 → 8.15.10

package/src/core/issuer-grouping.ts

@@ -0,0 +1,165 @@
+/**
+ * Which grouping issuer each known device belongs to, for one kind of issuer: the machine (agent-comms#343, list_agents' machine-grouped output) or the user principal (agent-comms#266). This device's own issuer is known directly; every other device's is read from the proof of that kind in its gossiped agent/self advert and identified cryptographically (membership-proof.ts's identifyMembershipProofIssuer), so a device is placed under an issuer only when that issuer's key signed a current proof for it. A device with no such proof (a hidden agent, which sends no agent/self advert, or a bridge that predates the proof) has no issuer here.
+ *
+ * The same pass reads each issuer's self display name claim (agent-comms#345, agent-comms#359) from the adverts of the devices it vouches for, and keeps a name only when the claim is signed by that very issuer's key: the issuer is authentic, the content is its own choice.
+ *
+ * Grouping is display, not trust: a proof names who vouches for a device id, not that the device gossiping it is that device, so nothing here is used to authorise anything. Identifying a proof is cryptography, so verdicts are remembered per proof text until the proof lapses, and the cache is bounded. For the same reason a failure to identify one proof is reported and leaves that device unplaced rather than failing the listing it feeds.
+ */
+
+import {
+  readMembershipProof,
+  type MembershipProofField,
+} from "./gossip-directory.js";
+import type { IdentifiedMembershipProof } from "./membership-proof.js";
+import type { NameClaimVerdict } from "./name-claim.js";
+
+/** The most proofs, and separately the most name claims, whose verdict is remembered. */
+const VERDICT_CACHE_LIMIT = 1024;
+
+export interface IssuerGroupingDeps {
+  /** Which agent/self field carries the proofs of the issuer kind this grouping places devices under. */
+  field: MembershipProofField;
+  /** The name claim a peer gossiped for this kind of issuer, read from its advert. */
+  readNameClaim: (
+    advert: Readonly<Record<string, unknown>>,
+  ) => string | undefined;
+  /** Every device this side has heard gossip from, with its latest advert. */
+  listKnownDevices: () => readonly {
+    deviceId: string;
+    advert: Readonly<Record<string, unknown>>;
+  }[];
+  /** Identifies which issuer a proof shows vouching for a device (MembershipProofs.identify). Called only once getMachineId answers, so the store's identity is attached. */
+  identify: (
+    claim: Readonly<{ proof: string; deviceHex: string }>,
+  ) => Promise<IdentifiedMembershipProof>;
+  /** This device's own id (hex). */
+  getPeerId: () => string;
+  /** This device's own issuer's id (hex), undefined before the store's identity is attached. */
+  getOwnIssuerId: () => string | undefined;
+  /** Where a proof that could not be identified at all (identify rejected) is reported. */
+  onError: (error: Error) => void;
+  /** Verifies a gossiped name claim about subject (name-claim.ts's verifyNameClaim, as this node sees it). */
+  verifyName: (
+    claim: Readonly<{ claim: string; subject: string }>,
+  ) => Promise<NameClaimVerdict>;
+  /** This device's own issuer's name, read locally. */
+  getOwnName: () => string | undefined;
+}
+
+interface CachedName {
+  subject: string;
+  name: string | undefined;
+  until: number;
+}
+
+interface CachedVerdict {
+  deviceHex: string;
+  /** The issuer the proof names, undefined for a proof that did not verify. */
+  issuer: string | undefined;
+  /** When the verdict stops holding (epoch ms): the proof's own expiry, or never for a refusal, since the same text can never become valid later. */
+  until: number;
+}
+
+export class IssuerGrouping {
+  private readonly verdicts = new Map<string, CachedVerdict>();
+  private readonly names = new Map<string, CachedName>();
+
+  constructor(private readonly deps: Readonly<IssuerGroupingDeps>) {}
+
+  /** The issuer (hex) of each device this side can place under one, keyed by device id: this device's own, and every gossiped device with a current, valid proof of this kind. */
+  async issuersByDevice(): Promise<Map<string, string>> {
+    const issuers = new Map<string, string>();
+    const own = this.deps.getOwnIssuerId();
+    // Without an identity attached there is no clock or revocation view to identify a proof against, and no own issuer either.
+    if (own === undefined) return issuers;
+    issuers.set(this.deps.getPeerId(), own);
+    for (const { deviceId, advert } of this.deps.listKnownDevices()) {
+      if (issuers.has(deviceId)) continue;
+      const proof = readMembershipProof(advert, this.deps.field);
+      if (proof === undefined) continue;
+      const issuer = await this.issuerFor(proof, deviceId);
+      if (issuer !== undefined) issuers.set(deviceId, issuer);
+    }
+    return issuers;
+  }
+
+  /** The self display name of each issuer this side can place a device under, keyed by issuer id: this device's own from its file, every other one from a claim its own key signed, gossiped by a device it vouches for. */
+  async issuerNames(): Promise<Map<string, string>> {
+    const names = new Map<string, string>();
+    const issuers = await this.issuersByDevice();
+    const own = this.deps.getOwnIssuerId();
+    const ownName = this.deps.getOwnName();
+    if (own !== undefined && ownName !== undefined) names.set(own, ownName);
+    for (const { deviceId, advert } of this.deps.listKnownDevices()) {
+      const issuer = issuers.get(deviceId);
+      if (issuer === undefined || names.has(issuer)) continue;
+      const claim = this.deps.readNameClaim(advert);
+      if (claim === undefined) continue;
+      const name = await this.nameFor(claim, issuer);
+      if (name !== undefined) names.set(issuer, name);
+    }
+    return names;
+  }
+
+  private async nameFor(
+    claim: string,
+    subject: string,
+  ): Promise<string | undefined> {
+    const cached = this.names.get(claim);
+    if (cached?.subject === subject && cached.until > Date.now()) {
+      return cached.name;
+    }
+    const verdict = await this.deps.verifyName({ claim, subject });
+    remember(
+      this.names,
+      claim,
+      verdict.ok
+        ? { subject, name: verdict.name, until: verdict.expires }
+        : { subject, name: undefined, until: Number.POSITIVE_INFINITY },
+    );
+    return verdict.ok ? verdict.name : undefined;
+  }
+
+  private async issuerFor(
+    proof: string,
+    deviceHex: string,
+  ): Promise<string | undefined> {
+    const cached = this.verdicts.get(proof);
+    if (cached?.deviceHex === deviceHex && cached.until > Date.now()) {
+      return cached.issuer;
+    }
+    let verdict: IdentifiedMembershipProof;
+    try {
+      verdict = await this.deps.identify({ proof, deviceHex });
+    } catch (err) {
+      // Not remembered: the failure is in this side's own view (a revocation view that threw, say), not a verdict on the proof, so the next listing tries again.
+      this.deps.onError(
+        new Error(
+          `could not identify the ${this.deps.field} proof of ${deviceHex}`,
+          {
+            cause: err,
+          },
+        ),
+      );
+      return undefined;
+    }
+    remember(
+      this.verdicts,
+      proof,
+      verdict.ok
+        ? { deviceHex, issuer: verdict.issuerHex, until: verdict.expires }
+        : { deviceHex, issuer: undefined, until: Number.POSITIVE_INFINITY },
+    );
+    return verdict.ok ? verdict.issuerHex : undefined;
+  }
+}
+
+/** Records verdict under key, evicting the oldest entry once the cache holds more than VERDICT_CACHE_LIMIT. */
+function remember<V>(cache: Map<string, V>, key: string, verdict: V): void {
+  cache.delete(key);
+  cache.set(key, verdict);
+  if (cache.size > VERDICT_CACHE_LIMIT) {
+    const oldest = cache.keys().next();
+    if (oldest.done !== true) cache.delete(oldest.value);
+  }
+}

package/src/core/issuer-identity-file.ts

@@ -0,0 +1,187 @@
+/**
+ * A persisted grouping-issuer keypair: one locally generated key per file, the shape the user principal (user-identity.ts, agent-comms#160) and the machine identity (machine-identity.ts, agent-comms#343) both take. Neither is ever a live mesh peer, so neither needs identity-store.ts's PID-probed slot lock; the only race that matters is which process's key wins at first creation, which an exclusive ("wx") create settles.
+ *
+ * The key is never derived from anything about the host (platform UUIDs, serials, hostnames): those are linkable, cloned with disk images and swapped with hardware. Moving an identity to a rebuilt host is a deliberate copy of its file, the SSH host-key model.
+ *
+ * Each file is written with owner-only permissions (0600) inside a 0700 directory, and every write is atomic (atomic-file.ts), since another bridge may be reading the file at that moment: a reader sees a complete record or none, so a file that exists but cannot be parsed is never one of this module's own writes in progress. It is refused loudly rather than replaced with a fresh key, because replacing it silently changes the issuer's id and every peer that trusted the old one loses every device it vouched for. Fields an owning module adds beside the key material (issued-grant bookkeeping, a display name) are preserved by every write here: renewal spreads the stored record before replacing the key fields.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createFileExclusive, writeFileAtomic } from "./atomic-file.js";
+import {
+  generateIdentity,
+  certifyKeyPair,
+  getCertificateFingerprint,
+  deriveDeviceId,
+  CERTIFICATE_VALIDITY_MS,
+} from "./identity.js";
+import type { PeerIdentity } from "./identity.js";
+
+/** Renewal margin is one twelfth of the certificate's total validity period, matching identity-store.ts's own renewal margin so every identity ages out on the same schedule. */
+const RENEWAL_MARGIN_FRACTION = 12;
+const RENEWAL_MARGIN_MS = CERTIFICATE_VALIDITY_MS / RENEWAL_MARGIN_FRACTION;
+
+/** Owner-only read and write: the file holds a private key. */
+const IDENTITY_FILE_MODE = 0o600;
+/** Owner-only directory, matching identity-store.ts's own base directory. */
+const IDENTITY_DIR_MODE = 0o700;
+
+/** The key material every issuer identity file holds. An owning module's own fields sit beside these in the same JSON object. */
+export interface StoredIssuerKey {
+  privateKey: string;
+  certificate: string;
+  expiresAt: string;
+}
+
+/** Whether value holds the key-material fields every issuer identity record carries. */
+export function isStoredIssuerKey(value: unknown): value is StoredIssuerKey {
+  if (typeof value !== "object" || value === null) return false;
+  if (
+    !("privateKey" in value) ||
+    !("certificate" in value) ||
+    !("expiresAt" in value)
+  )
+    return false;
+  return (
+    typeof value.privateKey === "string" &&
+    typeof value.certificate === "string" &&
+    typeof value.expiresAt === "string"
+  );
+}
+
+/** Narrows a caught value to Node's own errno-carrying Error subtype, so a specific error code (e.g. ENOENT) can be checked without an `as` assertion. */
+function isErrnoException(value: unknown): value is NodeJS.ErrnoException {
+  return value instanceof Error && "code" in value;
+}
+
+/** Reads the file's raw contents, or undefined if it does not exist yet. Any other filesystem error (permissions, a directory in its place) is surfaced rather than treated as absent. */
+function readRawFile(file: string): string | undefined {
+  try {
+    return fs.readFileSync(file, "utf-8");
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") return undefined;
+    throw err;
+  }
+}
+
+/** The file's parsed record, or undefined when the file does not exist. The owning module supplies a guard for its own full record shape. Throws when the file exists but is not JSON or fails the guard (see the module comment for why that is never repaired here). */
+export function readIssuerRecord<T>(
+  file: string,
+  guard: (value: unknown) => value is T,
+): T | undefined {
+  const raw = readRawFile(file);
+  return raw === undefined ? undefined : parseIssuerRecord(file, raw, guard);
+}
+
+function parseIssuerRecord<T>(
+  file: string,
+  raw: string,
+  guard: (value: unknown) => value is T,
+): T {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw unusableRecord(file, err);
+  }
+  if (!guard(parsed)) throw unusableRecord(file);
+  return parsed;
+}
+
+/** The error for an identity file that exists but holds no usable record. Moving it aside is the operator's decision, since the next load then mints a new key under a new id. */
+function unusableRecord(file: string, cause?: unknown): Error {
+  return new Error(
+    `${file} exists but does not hold a usable identity record; move it aside to mint a new key, which changes this identity's id for every peer that trusts it`,
+    { cause },
+  );
+}
+
+function serializeRecord(stored: Readonly<object>): string {
+  return `${JSON.stringify(stored, null, 2)}\n`;
+}
+
+/** Replaces the file with record in full, owner-only. Callers read the current record first and spread it, so no field another writer owns is lost. */
+export function writeIssuerRecord(
+  file: string,
+  record: Readonly<StoredIssuerKey>,
+): void {
+  writeFileAtomic(file, serializeRecord(record), IDENTITY_FILE_MODE);
+}
+
+/** The identity a stored key record describes: the key, its certificate, and the fingerprint and device-id derived from them. */
+export function issuerPeerIdentity(
+  stored: Readonly<StoredIssuerKey>,
+): PeerIdentity {
+  return {
+    privateKey: stored.privateKey,
+    certificate: stored.certificate,
+    fingerprint: getCertificateFingerprint(stored.certificate),
+    deviceId: deriveDeviceId(stored.privateKey),
+  };
+}
+
+/** The key record that persists identity, with a fresh expiry stamp. */
+export function issuerKeyRecord(
+  identity: Readonly<PeerIdentity>,
+): StoredIssuerKey {
+  return {
+    privateKey: identity.privateKey,
+    certificate: identity.certificate,
+    expiresAt: new Date(Date.now() + CERTIFICATE_VALIDITY_MS).toISOString(),
+  };
+}
+
+/** Renews a stored identity nearing certificate expiry by re-certifying its existing key pair, so its device-id is unchanged (see identity.ts's certifyKeyPair for why a fresh key pair would be wrong). Every other field in the record is kept. Returns the identity unchanged when it is not yet near expiry. */
+function renewIfNeeded(
+  file: string,
+  stored: Readonly<StoredIssuerKey>,
+): PeerIdentity {
+  const expiresAt = Date.parse(stored.expiresAt);
+  const needsRenewal =
+    Number.isNaN(expiresAt) || Date.now() > expiresAt - RENEWAL_MARGIN_MS;
+  if (!needsRenewal) return issuerPeerIdentity(stored);
+
+  const renewed = certifyKeyPair(stored.privateKey);
+  writeIssuerRecord(file, { ...stored, ...issuerKeyRecord(renewed) });
+  return renewed;
+}
+
+/** Generates a fresh identity and persists it at file, which does not exist yet. The create is exclusive, so when a concurrent caller creates the file first this caller keeps the winner's key and returns that instead of overwriting it, judging the winner's record with the owning module's guard. */
+function createIssuerIdentity(
+  file: string,
+  guard: (value: unknown) => value is StoredIssuerKey,
+): PeerIdentity {
+  const identity = generateIdentity();
+  if (
+    createFileExclusive(
+      file,
+      serializeRecord(issuerKeyRecord(identity)),
+      IDENTITY_FILE_MODE,
+    )
+  ) {
+    return identity;
+  }
+  const winner = readIssuerRecord(file, guard);
+  if (winner === undefined) {
+    throw new Error(`${file} was created and removed again while loading it`);
+  }
+  return renewIfNeeded(file, winner);
+}
+
+/**
+ * Loads the issuer identity persisted at file, creating it on first use. A record nearing certificate expiry is renewed in place and a missing file is created exclusively. guard is the owning module's check of its full record shape, the same one its own reads use, so a record that loads here is one every later read-modify-write of that module accepts too. A file that exists but fails guard is an error, never regenerated.
+ */
+export function loadOrCreateIssuerIdentity(
+  file: string,
+  guard: (value: unknown) => value is StoredIssuerKey,
+): PeerIdentity {
+  fs.mkdirSync(path.dirname(file), {
+    recursive: true,
+    mode: IDENTITY_DIR_MODE,
+  });
+
+  const stored = readIssuerRecord(file, guard);
+  if (stored === undefined) return createIssuerIdentity(file, guard);
+  return renewIfNeeded(file, stored);
+}

package/src/core/lan-web-actions.ts

@@ -0,0 +1,34 @@
+/**
+ * The lan_web_uis action's handler, split out of tool.ts to keep that file under the repo's max-lines cap.
+ */
+
+import {
+  notMeshBacked,
+  type CommsResult,
+  type MeshOnlyFeatures,
+} from "./tool.js";
+import { idWithNames, type Namer } from "./naming.js";
+
+/** Lists the LAN web UIs heard as web beacons (agent-comms#353): each as its ready-to-open URL beside the full peer id and its names, since the entry a user acts on is the peer id. */
+export function lanWebUisAction(
+  store: Readonly<MeshOnlyFeatures>,
+  namer: Namer,
+): CommsResult {
+  if (!store.lanWebUis) return notMeshBacked("lan_web_uis");
+  const entries = store.lanWebUis.list();
+  if (entries.length === 0) {
+    return {
+      content:
+        "No LAN web UIs heard. A bridge announces its web UI on the local network only while it is bound beyond loopback (AGENT_COMMS_WEB_HOST).",
+      isError: false,
+    };
+  }
+  const lines = entries.map(
+    (entry) =>
+      `http://${entry.host}:${entry.webPort.toString()}  ${idWithNames(entry.peerId, namer)}`,
+  );
+  return {
+    content: `LAN web UIs:\n${lines.join("\n")}`,
+    isError: false,
+  };
+}

package/src/core/lan-web-uis.ts

@@ -0,0 +1,55 @@
+/**
+ * The LAN web UIs this machine has heard web beacons for (agent-comms#353): the receiving half of the beacon bridges broadcast when their web server binds beyond loopback, kept as a bounded, expiring table so `lan_web_uis` can list neighbouring dashboards without anything accumulating.
+ */
+
+import { FIRST_CONTACT_INTERVAL_MS } from "./first-contact.js";
+
+/** Missed beacon intervals tolerated before an entry expires: the same conventional missed-heartbeat threshold the gossip presence check uses (gossip-extensions.ts's PRESENCE_STALE_MISSED_TICKS), for the same reason -- one dropped and one slow beacon is absorbed, a genuinely departed bridge leaves the list. */
+const BEACON_STALE_MISSED_TICKS = 3;
+
+const STALE_AFTER_MS = FIRST_CONTACT_INTERVAL_MS * BEACON_STALE_MISSED_TICKS;
+
+/** One neighbouring web UI as last heard: where it listens, and when. */
+export interface LanWebUiEntry {
+  peerId: string;
+  host: string;
+  webPort: number;
+  heardAtMs: number;
+}
+
+/** The table of LAN web UIs heard on this machine's first-contact presence. An entry is refreshed by every beacon its bridge sends, and a bridge that stops beaconing drops out of `list()` once its entry is stale. */
+export class LanWebUis {
+  private readonly entries = new Map<string, LanWebUiEntry>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /** Records (or refreshes) the UI a beacon announced, keyed by peer id so a bridge that restarts on a new port replaces its own entry rather than accumulating one per restart. */
+  record(peerId: string, host: string, webPort: number): LanWebUiEntry {
+    const entry: LanWebUiEntry = {
+      peerId,
+      host,
+      webPort,
+      heardAtMs: this.now(),
+    };
+    this.entries.set(peerId, entry);
+    return entry;
+  }
+
+  /** record for a beacon as first contact hands it up, host already taken from the datagram's source address. */
+  recordBeacon(
+    beacon: Readonly<{ peerId: string; host: string; webPort: number }>,
+  ): LanWebUiEntry {
+    return this.record(beacon.peerId, beacon.host, beacon.webPort);
+  }
+
+  /** Every unexpired entry, ordered by peer id so the listing is stable between calls. */
+  list(): readonly Readonly<LanWebUiEntry>[] {
+    const cutoff = this.now() - STALE_AFTER_MS;
+    for (const [peerId, entry] of this.entries) {
+      if (entry.heardAtMs < cutoff) this.entries.delete(peerId);
+    }
+    return [...this.entries.values()].sort((a, b) =>
+      a.peerId < b.peerId ? -1 : a.peerId > b.peerId ? 1 : 0,
+    );
+  }
+}

package/src/core/ledger-lock.ts

@@ -0,0 +1,81 @@
+/**
+ * Mutual exclusion for appending to one machine's writer log of the account ledger (agent-comms#344). A data-domain log is single-writer: two appends reading the same head would both write the next sequence number and fork the log. Every bridge on a machine shares that machine's writer log, and several stores can live in one process (the cc-peer front fronts many sessions), so appends are serialised both within this process (a promise chain per lock) and across processes (a PID lock file, pid-lock-file.ts, the same claim identity-store.ts uses for a bridge slot).
+ */
+
+import { releaseLockFile, tryAcquireLock } from "./pid-lock-file.js";
+
+/** Runs `critical` with exclusive access to whatever this lock guards. */
+export interface LedgerLock {
+  run: <T>(critical: () => Promise<T>) => Promise<T>;
+}
+
+const MS_PER_SECOND = 1000;
+/** How long an append waits for another process's append to finish. An append is one small file write, so a holder still busy after this long has hung or is wedged, and failing loudly beats waiting forever. */
+const LOCK_WAIT_SECONDS = 10;
+const LOCK_WAIT_MS = LOCK_WAIT_SECONDS * MS_PER_SECOND;
+/** Between attempts to claim a lock another live process holds: short against an append's own cost, long enough not to spin. */
+const LOCK_RETRY_MS = 20;
+
+const sleep = async (ms: number): Promise<void> =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+/** The tail of each lock's queue in this process, keyed by what the lock guards. */
+const tails = new Map<string, Promise<unknown>>();
+
+async function serialised<T>(
+  key: string,
+  critical: () => Promise<T>,
+): Promise<T> {
+  const previous = tails.get(key) ?? Promise.resolve();
+  const next = previous.then(critical, critical);
+  const tail = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  tails.set(key, tail);
+  try {
+    return await next;
+  } finally {
+    if (tails.get(key) === tail) tails.delete(key);
+  }
+}
+
+async function claimFile(lockFile: string): Promise<void> {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    const claim = tryAcquireLock(lockFile);
+    if (claim.acquired) return;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `account ledger lock ${lockFile} is still held by pid ${String(claim.heldBy)} after ${String(LOCK_WAIT_SECONDS)}s`,
+      );
+    }
+    await sleep(LOCK_RETRY_MS);
+  }
+}
+
+/** A lock shared by every process on this machine that names the same lock file. */
+export function createFileLedgerLock(lockFile: string): LedgerLock {
+  return {
+    run: async (critical) =>
+      serialised(lockFile, async () => {
+        await claimFile(lockFile);
+        try {
+          return await critical();
+        } finally {
+          releaseLockFile(lockFile);
+        }
+      }),
+  };
+}
+
+let nextInProcessLock = 0;
+
+/** A lock with no file behind it, for a ledger whose storage lives only in this process's memory. */
+export function createInProcessLedgerLock(): LedgerLock {
+  nextInProcessLock += 1;
+  const key = `in-process:${String(nextInProcessLock)}`;
+  return { run: async (critical) => serialised(key, critical) };
+}

package/src/core/listener-registry.ts

@@ -0,0 +1,133 @@
+/**
+ * listener-registry -- WireMeshTransport's own operator-registered listener bookkeeping (addListener/removeListener/listListeners, plus the advertisedAddresses list they feed), split out under the repo's max-lines cap the same reason hub-session.ts, connection-approval.ts, room-router.ts, peer-lifecycle.ts, and gossip-directory.ts were each split from the same file. Free functions over a TrackedListener registry (WireMeshTransport's own coordinatorListeners Map, passed in directly) rather than a class, since WireMeshTransport already owns and mutates that Map itself and every other piece of split-out state in this file follows the same shape. Deliberately excludes the default bootstrap coordinator listener (startDataServer/becomeCoordinator's own concern) -- this registry only ever tracks listeners an operator explicitly registered via addListener.
+ */
+
+import { nanoid } from "./nanoid.js";
+import {
+  BECOME_COORDINATOR_BIND_RETRIES,
+  BECOME_COORDINATOR_BIND_RETRY_DELAY_MS,
+  retryOnAddrInUse,
+} from "./bind-retry.js";
+import type {
+  Connection,
+  Listener,
+  Transport,
+} from "wire-mesh-core/ports/transport";
+import type { ListenerInfo, ListenerPolicy } from "./transport.js";
+
+/** Length of the random id minted for a tracked listener -- shared with WireMeshTransport's own becomeCoordinator, which mints an id for the default bootstrap listener the same way, outside this registry. */
+export const LISTENER_ID_LENGTH = 8;
+
+export interface TrackedListener {
+  listener: Listener;
+  policy: ListenerPolicy;
+  host: string;
+  port: number;
+  isDefault: boolean;
+}
+
+/** Reads the port a listener actually bound, from its own reported address -- never the port it was asked to bind, which is 0 whenever the caller wanted the OS to assign a free one. Bookkeeping that stores the requested port instead silently reports 0 for every OS-assigned listener. */
+export function listenerPort(listener: Readonly<Listener>): number {
+  const port = listener.address.split(":").pop();
+  return port === undefined ? 0 : Number(port);
+}
+
+/** Registers a new listener at host:port under the given policy, tracking it in coordinatorListeners (mutated in place) and dispatching every accepted connection to onAccepted -- WireMeshTransport.addListener's own body, unchanged in behaviour. */
+export async function registerListener(options: {
+  wireTransport: Readonly<Pick<Transport, "listen">>;
+  coordinatorListeners: Map<string, TrackedListener>;
+  host: string;
+  port: number;
+  policy: ListenerPolicy;
+  onAccepted: (connection: Readonly<Connection>) => void;
+}): Promise<string> {
+  const {
+    wireTransport,
+    coordinatorListeners,
+    host,
+    port,
+    policy,
+    onAccepted,
+  } = options;
+  const id = nanoid(LISTENER_ID_LENGTH);
+  const listener = await wireTransport.listen(
+    `${host}:${String(port)}`,
+    onAccepted,
+  );
+  coordinatorListeners.set(id, {
+    listener,
+    policy,
+    host,
+    port: listenerPort(listener),
+    isDefault: false,
+  });
+  return id;
+}
+
+/** Binds the default bootstrap coordinator listener at host:port and tracks it, returning its id -- WireMeshTransport.becomeCoordinator's own bookkeeping, kept beside the registry that owns the same Map. Unlike registerListener this retries a port conflict, because both routes to the coordinator role contend for an occupied port: a graceful handover names its successor while the outgoing coordinator's own listener is still open, and a crash race has every surviving peer attempting the bind at once. The entry is marked default, which is what keeps it out of the advertised-address list and unremovable through removeListener. Closes the listener it bound and rejects when isShuttingDown() holds once the bind completes, which covers a shutdown that began before the bind as well as one during it: the transport's shutdown() closes only the listeners tracked when it began, so one bound later would hold the port for as long as the process lives (a crash-race contest still running when its store shuts down is one such caller). */
+export async function registerDefaultListener(options: {
+  wireTransport: Readonly<Pick<Transport, "listen">>;
+  coordinatorListeners: Map<string, TrackedListener>;
+  host: string;
+  port: number;
+  onAccepted: (connection: Readonly<Connection>) => void;
+  isShuttingDown: () => boolean;
+}): Promise<string> {
+  const { wireTransport, coordinatorListeners, host, port, onAccepted } =
+    options;
+  const id = nanoid(LISTENER_ID_LENGTH);
+  const listener = await retryOnAddrInUse(
+    async () => wireTransport.listen(`${host}:${String(port)}`, onAccepted),
+    BECOME_COORDINATOR_BIND_RETRIES,
+    BECOME_COORDINATOR_BIND_RETRY_DELAY_MS,
+  );
+  if (options.isShuttingDown()) {
+    await listener.close();
+    throw new Error("becomeCoordinator: the transport has shut down");
+  }
+  coordinatorListeners.set(id, {
+    listener,
+    policy: "full",
+    host,
+    port: listenerPort(listener),
+    isDefault: true,
+  });
+  return id;
+}
+
+/** Closes and untracks a previously registered listener -- WireMeshTransport.removeListener's own body, unchanged in behaviour. Throws if id names the default bootstrap listener (never registered through registerListener, so never removable through this path); a no-op if id names no tracked listener at all. */
+export async function unregisterListener(
+  coordinatorListeners: Map<string, TrackedListener>,
+  defaultListenerId: string | undefined,
+  id: string,
+): Promise<void> {
+  if (id === defaultListenerId) {
+    throw new Error("Cannot remove the default listener");
+  }
+  const tracked = coordinatorListeners.get(id);
+  if (tracked === undefined) return;
+  coordinatorListeners.delete(id);
+  await tracked.listener.close();
+}
+
+/** Every currently tracked listener, in the shape ListenerInfo exposes externally -- WireMeshTransport.listListeners's own body, unchanged in behaviour. */
+export function listTrackedListeners(
+  coordinatorListeners: ReadonlyMap<string, Readonly<TrackedListener>>,
+): ListenerInfo[] {
+  return [...coordinatorListeners.entries()].map(([id, tracked]) => ({
+    id,
+    host: tracked.host,
+    port: tracked.port,
+    policy: tracked.policy,
+    isDefault: tracked.isDefault,
+  }));
+}
+
+/** This side's own directly-reachable "host:port" candidates (wire-mesh#38), passed into every acceptMeshSession call's own self-advert -- WireMeshTransport's own advertisedAddresses getter body, unchanged in behaviour. Deliberately excludes the default bootstrap coordinator listener -- it always binds COORDINATOR_HOST (127.0.0.1, hardcoded, never configurable), which is meaningless to advertise to a remote peer -- and includes only listeners an operator explicitly registered via addListener, which by construction represent a deliberate "make me reachable from elsewhere" declaration. */
+export function advertisedListenerAddresses(
+  coordinatorListeners: ReadonlyMap<string, Readonly<TrackedListener>>,
+): string[] {
+  return [...coordinatorListeners.values()]
+    .filter((tracked) => !tracked.isDefault)
+    .map((tracked) => `${tracked.host}:${String(tracked.port)}`);
+}