agent-comms 8.15.9 → 8.15.11

package/src/core/loopback-address.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether an address this side dials can only reach this machine, judged from the address literal alone. WireMeshTransport uses it to decide whether a dialled session takes part in the coordinator election (agent-comms#341): the dialler knows nothing about the far side's listener beyond the address it dialled, and a peer list or a first-contact beacon heard over LAN broadcast can name any host.
+ */
+
+import * as net from "node:net";
+
+/** RFC 1122 section 3.2.1.3 reserves the whole of 127.0.0.0/8 for loopback, not just 127.0.0.1. */
+const IPV4_LOOPBACK_NETWORK = "127.0.0.0";
+const IPV4_LOOPBACK_PREFIX_LENGTH = 8;
+/** RFC 4291 section 2.5.3: IPv6 has a single loopback address. */
+const IPV6_LOOPBACK_ADDRESS = "::1";
+
+const LOOPBACK = new net.BlockList();
+LOOPBACK.addSubnet(IPV4_LOOPBACK_NETWORK, IPV4_LOOPBACK_PREFIX_LENGTH, "ipv4");
+LOOPBACK.addAddress(IPV6_LOOPBACK_ADDRESS, "ipv6");
+
+/** True for an IPv4 address in 127.0.0.0/8, the IPv6 loopback address, or an IPv4-mapped IPv6 form of the former. False for every other address and for any hostname, since a name may resolve anywhere and is never evidence of where the far side is. */
+export function isLoopbackAddress(host: string): boolean {
+  if (net.isIPv4(host)) return LOOPBACK.check(host, "ipv4");
+  if (net.isIPv6(host)) return LOOPBACK.check(host, "ipv6");
+  return false;
+}

package/src/core/machine-identity.ts

@@ -0,0 +1,77 @@
+/**
+ * Persistent machine identity (agent-comms#343): one keypair per OS account per host, the third identity scope beside a bridge slot's device identity (identity-store.ts) and the account's user principal (user-identity.ts). It is structurally another grouping issuer, like the principal: it vouches for the devices living on this host with the same group:member proofs (membership-proof.ts), so a peer can group devices by machine and trust or stop trusting a whole host in one act.
+ *
+ * Stored at ~/.agent-comms/machine-identity.json (mode 0600), so it belongs to the OS account whose home directory holds it: every bridge that account runs on the host reads the same file and is vouched for by the same machine key, while another account on the same host mints a machine key of its own and appears as a separate machine. Until the principal becomes portable across hosts (agent-comms#344) this is the same scope as the user principal; a key naming the host across every account needs a signer outside any one account and is agent-comms#367. The key is generated locally on first use and never derived from hardware (issuer-identity-file.ts says why); re-homing a rebuilt host is a deliberate copy of this file.
+ */
+
+import * as path from "node:path";
+import { resolveDataDir } from "./data-directory.js";
+import type { PeerIdentity } from "./identity.js";
+import {
+  isStoredIssuerKey,
+  loadOrCreateIssuerIdentity,
+  readIssuerRecord,
+  writeIssuerRecord,
+  type StoredIssuerKey,
+} from "./issuer-identity-file.js";
+
+export interface MachineIdentityOptions {
+  /** Directory override for tests; defaults to ~/.agent-comms, beside the user identity and every bridge slot. */
+  dir?: string;
+}
+
+/** The machine identity file for options. */
+export function machineIdentityFile(
+  options?: Readonly<MachineIdentityOptions>,
+): string {
+  const dir = resolveDataDir({ dir: options?.dir });
+  return path.join(dir, "machine-identity.json");
+}
+
+/** Loads this account's machine identity for this host, creating it on first use (exclusive create, renewal in place, an unusable file refused rather than regenerated). */
+export function loadOrCreateMachineIdentity(
+  options?: Readonly<MachineIdentityOptions>,
+): PeerIdentity {
+  return loadOrCreateIssuerIdentity(
+    machineIdentityFile(options),
+    isStoredMachineIdentity,
+  );
+}
+
+interface StoredMachineIdentity extends StoredIssuerKey {
+  /** The name this machine asserts for itself (agent-comms#345), signed into a name claim by the machine key whenever a bridge on the host re-advertises. Absent until someone names the machine. */
+  displayName?: string;
+}
+
+function isStoredMachineIdentity(
+  value: unknown,
+): value is StoredMachineIdentity {
+  if (!isStoredIssuerKey(value)) return false;
+  return !("displayName" in value) || typeof value.displayName === "string";
+}
+
+/** The name this machine asserts for itself, or undefined when it has none or the machine identity has not been created yet. Read from disk on every call, so a name set by any bridge on the host is seen by all of them. */
+export function loadMachineDisplayName(
+  options?: Readonly<MachineIdentityOptions>,
+): string | undefined {
+  return readIssuerRecord(machineIdentityFile(options), isStoredMachineIdentity)
+    ?.displayName;
+}
+
+/** Sets (or, given undefined, clears) the name this machine asserts for itself, keeping the key material and every other field. Throws if the machine identity has not been created yet. */
+export function saveMachineDisplayName(
+  options: Readonly<MachineIdentityOptions> | undefined,
+  displayName: string | undefined,
+): void {
+  const file = machineIdentityFile(options);
+  const stored = readIssuerRecord(file, isStoredMachineIdentity);
+  if (stored === undefined) {
+    throw new Error(
+      `no machine identity persisted yet; call loadOrCreateMachineIdentity first (${file})`,
+    );
+  }
+  const next: StoredMachineIdentity = { ...stored };
+  if (displayName === undefined) delete next.displayName;
+  else next.displayName = displayName;
+  writeIssuerRecord(file, next);
+}

package/src/core/machine-list-groups.ts

@@ -0,0 +1,53 @@
+/**
+ * list_agents' machine grouping (agent-comms#343): the listed agents split into one group per machine, this host first, then every other machine by id, then the agents no machine proof places. Split out of tool.ts to keep that file under the repo's max-lines cap.
+ */
+
+import type { AgentIdentity } from "./types.js";
+import type { Namer } from "./naming.js";
+
+/** One run of listed agents and the heading above it; no heading when nothing is grouped at all. */
+export interface AgentGroup {
+  heading: string | undefined;
+  agents: AgentIdentity[];
+}
+
+/** agents grouped by machine, each group keeping the agents' listed order and each heading naming its machine by the display convention (namer). machines maps device id to machine id (MeshStore.listAgentMachines); undefined on a store with no machine identity, in which case, as when no agent is placed on a machine, the list is one ungrouped run. */
+export function groupAgentsByMachine(
+  agents: readonly AgentIdentity[],
+  machines: ReadonlyMap<string, string> | undefined,
+  ownMachine: string | undefined,
+  namer: Namer,
+): AgentGroup[] {
+  if (
+    machines === undefined ||
+    !agents.some((agent) => machines.has(agent.id))
+  ) {
+    return [{ heading: undefined, agents: [...agents] }];
+  }
+  const byMachine = new Map<string, AgentIdentity[]>();
+  const unplaced: AgentIdentity[] = [];
+  for (const agent of agents) {
+    const machine = machines.get(agent.id);
+    if (machine === undefined) {
+      unplaced.push(agent);
+      continue;
+    }
+    const group = byMachine.get(machine);
+    if (group === undefined) byMachine.set(machine, [agent]);
+    else group.push(agent);
+  }
+  const groups: AgentGroup[] = [...byMachine]
+    .sort(([a], [b]) => {
+      if (a === ownMachine) return -1;
+      if (b === ownMachine) return 1;
+      return a.localeCompare(b);
+    })
+    .map(([machine, members]) => ({
+      heading: `Machine ${namer(machine)}${machine === ownMachine ? " (this machine)" : ""}:`,
+      agents: members,
+    }));
+  if (unplaced.length > 0) {
+    groups.push({ heading: "Machine not proven:", agents: unplaced });
+  }
+  return groups;
+}

package/src/core/mcp-registry-retry.ts

@@ -0,0 +1,69 @@
+// Pure retry logic for scripts/publish-mcp-registry.ts, kept here rather than in the script itself so it's testable under src/test/ -- tsconfig.json's rootDir is src/, so a test there can't import from scripts/ (outside that root), while a script importing from src/ is the normal direction. The script itself keeps the actual Date.now()/spawnSync-driven retry loop, which is inherently imperative and time-based; this module holds only the two decisions that loop makes that are worth asserting deterministically.
+
+// The MCP registry validates a publish against the npm registry, where the version semantic-release published seconds earlier may not be visible yet. The registry's own error text says to wait and retry, so retry that failure specifically instead of failing the release job on propagation lag.
+//
+// Confirmed insufficient in production (ExaDev/agent-comms, 2026-09-13, v2.18.0): the original fixed [15, 30, 60, 120] schedule (225s total) exhausted and failed the release job while npm's own CDN still hadn't propagated the just-published version -- a real, observed lag longer than that budget, not a hypothetical one. The release job carries no timeout-minutes of its own, so there's no tight external deadline forcing a small retry budget.
+export const INITIAL_RETRY_DELAY_MS = 15_000;
+export const MAX_RETRY_DELAY_MS = 120_000;
+export const RETRY_BACKOFF_MULTIPLIER = 2;
+const MAX_TOTAL_RETRY_MINUTES = 15;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+export const MAX_TOTAL_RETRY_MS =
+  MAX_TOTAL_RETRY_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/** The next delay in the doubling-with-cap backoff schedule, given the delay just used. */
+export function nextRetryDelayMs(previousDelayMs: number): number {
+  return Math.min(
+    previousDelayMs * RETRY_BACKOFF_MULTIPLIER,
+    MAX_RETRY_DELAY_MS,
+  );
+}
+
+/** The MCP registry's own npm-propagation-lag error text -- the version semantic-release just published may not be visible to the registry's own npm lookup for a few seconds. */
+function isNpmPropagationLag(output: string): boolean {
+  return (
+    output.includes("was not found") &&
+    output.includes("A newly published release can take a moment")
+  );
+}
+
+// Confirmed as a second, distinct retryable failure mode in the same run this retry logic was first fixed for (ExaDev/agent-comms, 2026-09-13, v2.18.1): the registry returned a genuine HTTP 504 (a transient gateway timeout on the registry's own infrastructure, not anything to do with npm propagation), and the retry logic at the time only recognised the propagation-lag text above, so it failed the release job immediately instead of retrying a condition that resolved itself on a plain re-run seconds later. Any 5xx is the registry's own server failing to complete the request, not this side's request being wrong -- exactly the class of error a retry can plausibly fix, unlike a 4xx (this side asked for something invalid) other than the specific propagation-lag 404 already handled above.
+const SERVER_ERROR_STATUS_PATTERN = /server returned status 5\d{2}\b/;
+
+function isRetryableServerError(output: string): boolean {
+  return SERVER_ERROR_STATUS_PATTERN.test(output);
+}
+
+// Confirmed as a third retryable failure mode (ExaDev/agent-comms, 2026-09-17, issue #180, run 35249771867, v3.9.0): the registry request never got as far as an HTTP response at all, a raw connection-level failure from mcp-publisher's own Go HTTP client (a DNS/dial/timeout/reset at the TCP layer), which matches neither the propagation-lag text nor the 5xx status pattern above since there is no status line to match against. This is transient infrastructure the same way a 5xx is: the request itself may well have been valid, retrying it can plausibly succeed.
+const CONNECTION_ERROR_PATTERN =
+  /\b(?:dial tcp|i\/o timeout|connection refused|connection reset|no such host)\b/;
+
+function isConnectionError(output: string): boolean {
+  return CONNECTION_ERROR_PATTERN.test(output);
+}
+
+// Confirmed as a fourth retryable failure mode (ExaDev/agent-comms, 2026-09-17, issue #180, run 35239013253, v3.9.0): mcp-publisher logs in with `login github-oidc` once before the retry loop starts, and a retry attempt late enough in the MAX_TOTAL_RETRY_MS budget can present a JWT that expired in the meantime, producing a 401 that no amount of retrying the same token will ever fix. It's retryable only because the caller re-runs the login step before every retry attempt (see scripts/publish-mcp-registry.ts), which mints a fresh token, so this classifier deliberately matches only the specific "expired" 401 body, not a 401 in general, since a genuine authorisation failure (wrong scope, revoked credential) would 401 again regardless of how fresh the token is.
+const EXPIRED_JWT_STATUS_PATTERN = /server returned status 401\b/;
+
+function isExpiredJwt(output: string): boolean {
+  return EXPIRED_JWT_STATUS_PATTERN.test(output) && output.includes("expired");
+}
+
+// Confirmed as a fifth retryable failure mode (ExaDev/agent-comms, 2026-10-21, release run 39670379457, v8.15.4): the registry's own Postgres had no free connection slots (SQLSTATE 53300), and the registry reported that as an HTTP 400 "Failed to publish server" and not a 5xx, so the status pattern above never matched and the release job failed on its first attempt, before the GitHub release was created. PostgreSQL's SQLSTATE class 53 is "insufficient resources" (no connection slots, disk full, out of memory, configuration limit): a shortage on the registry's side that clears by itself and has nothing to do with the request, so it is retryable whatever HTTP status carries it. Any other SQLSTATE class (a constraint violation, say) describes the request or its data and would fail again.
+const DATABASE_RESOURCE_SHORTAGE_PATTERN = /\bSQLSTATE 53\d{3}\b/;
+
+function isDatabaseResourceShortage(output: string): boolean {
+  return DATABASE_RESOURCE_SHORTAGE_PATTERN.test(output);
+}
+
+/** Recognises a publish failure worth retrying (npm propagation lag, a transient 5xx from the registry's own infrastructure, a connection-level failure that never reached the registry, a login JWT that expired mid-retry-window, or the registry's database running short of resources) as opposed to any other failure -- a genuinely invalid publish request or authorisation failure, for instance, which retrying can never fix. */
+export function isRetryablePublishFailure(output: string): boolean {
+  return (
+    isNpmPropagationLag(output) ||
+    isRetryableServerError(output) ||
+    isConnectionError(output) ||
+    isExpiredJwt(output) ||
+    isDatabaseResourceShortage(output)
+  );
+}

package/src/core/mcp-registry-version.ts

@@ -0,0 +1,18 @@
+// Decides whether a version is already listed on the MCP registry, kept here rather than in scripts/publish-mcp-registry.ts for the same reason as mcp-registry-retry.ts: a test under src/test/ cannot import from scripts/. The registry publish runs as its own CI job after the release and is re-run by hand after an outage, so it must skip a version the registry already lists, because publishing one again fails the job.
+const REGISTRY_BASE_URL = "https://registry.modelcontextprotocol.io";
+const HTTP_OK = 200;
+const HTTP_NOT_FOUND = 404;
+
+/** The registry's endpoint for one version of one server. The name carries a `/` (`io.github.<owner>/<repo>`) that must stay inside a single path segment. */
+export function registryVersionUrl(name: string, version: string): string {
+  return `${REGISTRY_BASE_URL}/v0/servers/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`;
+}
+
+/** Reads the status of a {@link registryVersionUrl} response: 200 means listed, 404 means not listed. Any other status says nothing about whether the version is listed, so it throws and fails the job to be re-run, never guessing either way. */
+export function isPublishedOnRegistry(status: number): boolean {
+  if (status === HTTP_OK) return true;
+  if (status === HTTP_NOT_FOUND) return false;
+  throw new Error(
+    `MCP registry answered ${String(status)} when asked whether the version is listed`,
+  );
+}

package/src/core/membership-proof.ts

@@ -0,0 +1,139 @@
+/**
+ * The proof a device gossips to show that a grouping issuer vouches for it (agent-comms#266 for the user principal, agent-comms#343 for the machine): a short-lived group:member token, minted by that issuer for that one device, carried as one line of text. A receiver that trusts the issuer verifies it against the gossiping device and then trusts the device without it being listed individually, which is what trusting a principal or a machine is for. A receiver that only wants to know which machine a device runs on reads the issuer out of the proof (identifyMembershipProofIssuer).
+ *
+ * A proof shows that the issuer vouches for a device id. It does not show that whoever gossips it is that device: both arrive in the same unauthenticated advert and anyone who has read one can repeat it, so it earns only what GatewayTrust.isReachable grants (see directory-admission.ts). It is also public: it names the issuer, so anyone connected to the hub can see which devices belong to which principal and which run on the same machine. That is why a proof is only ever carried in the agent/self advert, which a hidden or ghost agent never sends.
+ *
+ * Every bridge of one account shares that account's user identity, and every bridge one account runs on a host shares that account's machine identity for the host (machine-identity.ts), so any of them can mint a proof for any device id, which is the same trust the issuer is given anyway. Proofs are short-lived rather than revocable, so removeDevice (which revokes an admitDevice grant) does not affect them and a removed device holding the issuer's key can keep minting its own: they are minted without recording an issued-grant, so a bridge refreshing its own does not rewrite the shared identity file.
+ */
+
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { RevocationView } from "wire-mesh-core/domain/revocation-view";
+import type {
+  CapabilityToken,
+  DeviceId,
+} from "wire-mesh-core/generated/protocol";
+import { mintGroupMembership } from "./device-membership.js";
+import {
+  identifyGroupIssuer,
+  verifyDeviceMembership,
+} from "./device-membership-verification.js";
+import { randomId } from "./random-id.js";
+import { CommsError } from "./store.js";
+import { decodeTokenText, encodeTokenText } from "./token-text.js";
+
+const MS_PER_MINUTE = 60_000;
+const MEMBERSHIP_PROOF_LIFETIME_MINUTES = 15;
+
+/** The longest proof text a receiver will look at. A real proof is a single root-level token, well under half of this; a longer one can only be something else, and the length also bounds how deep a delegation chain could be smuggled in. */
+export const MAX_MEMBERSHIP_PROOF_LENGTH = 4096;
+
+/** How long a minted proof stays valid. Long enough to ride out a missed refresh or a gossip gap, short enough that a device an account stops running stops being trusted soon after. */
+export const MEMBERSHIP_PROOF_LIFETIME_MS =
+  MEMBERSHIP_PROOF_LIFETIME_MINUTES * MS_PER_MINUTE;
+
+export interface MintMembershipProofOptions {
+  /** The grouping issuer vouching for the device: the user principal or the machine. */
+  issuer: IdentityPort;
+  clock: Clock;
+  /** The device the proof is for, and the only device it will verify for. */
+  deviceId: DeviceId;
+}
+
+/** A fresh proof that options.issuer vouches for options.deviceId, as one line of text. Throws MINT_FAILED if the token cannot be minted. */
+export async function mintMembershipProof(
+  options: Readonly<MintMembershipProofOptions>,
+): Promise<string> {
+  const verdict = await mintGroupMembership({
+    issuer: options.issuer,
+    clock: options.clock,
+    tokenId: randomId(),
+    deviceId: options.deviceId,
+    expires: options.clock.now() + MEMBERSHIP_PROOF_LIFETIME_MS,
+  });
+  if (!verdict.ok) {
+    throw new CommsError(
+      `Failed to mint a membership proof: ${verdict.reason}`,
+      "MINT_FAILED",
+    );
+  }
+  return encodeTokenText(verdict.token);
+}
+
+export interface VerifyMembershipProofOptions {
+  proof: string;
+  /** The device the proof is claimed for: the gossiping device the directory entry names. */
+  deviceId: DeviceId;
+  /** The issuer (principal or machine) the proof must have been minted by. */
+  issuerId: DeviceId;
+  /** The verifying node's own identity, clock and revocation view. */
+  identity: IdentityPort;
+  clock: Clock;
+  revocation: RevocationView;
+}
+
+export type MembershipProofVerdict =
+  { ok: true; expires: number } | { ok: false; reason: string };
+
+/** The proof text decoded to a token, or the refusal for text that cannot be one. */
+function decodeProof(
+  proof: string,
+): { ok: true; token: CapabilityToken } | { ok: false; reason: string } {
+  if (proof.length > MAX_MEMBERSHIP_PROOF_LENGTH) {
+    return { ok: false, reason: "too_long" };
+  }
+  try {
+    return { ok: true, token: decodeTokenText(proof) };
+  } catch {
+    return { ok: false, reason: "not_a_token" };
+  }
+}
+
+/** Whether options.proof shows that options.issuerId vouches for options.deviceId right now. Never throws for a bad proof: text that is not a token, a token for another device or issuer, an expired or revoked one, all come back as a refusal. */
+export async function verifyMembershipProof(
+  options: Readonly<VerifyMembershipProofOptions>,
+): Promise<MembershipProofVerdict> {
+  const decoded = decodeProof(options.proof);
+  if (!decoded.ok) return decoded;
+  const verdict = await verifyDeviceMembership(decoded.token, {
+    identity: options.identity,
+    clock: options.clock,
+    revocation: options.revocation,
+    expectedBearer: options.deviceId,
+    groupIssuerId: options.issuerId,
+  });
+  if (!verdict.ok) return { ok: false, reason: verdict.reason };
+  // Every proof is minted at the root and cannot be delegated; a chain here would be someone else's construction.
+  if (verdict.depth !== 0) return { ok: false, reason: "not_root_level" };
+  return { ok: true, expires: verdict.claims.expires };
+}
+
+export type IdentifyMembershipProofOptions = Omit<
+  VerifyMembershipProofOptions,
+  "issuerId"
+>;
+
+export type IdentifiedMembershipProof =
+  | { ok: true; issuerHex: string; expires: number }
+  | { ok: false; reason: string };
+
+/** Which issuer options.proof shows vouching for options.deviceId right now, learned from the proof itself rather than checked against one already known: the same refusals as verifyMembershipProof, plus a proof whose named group is not the key that signed it. */
+export async function identifyMembershipProofIssuer(
+  options: Readonly<IdentifyMembershipProofOptions>,
+): Promise<IdentifiedMembershipProof> {
+  const decoded = decodeProof(options.proof);
+  if (!decoded.ok) return decoded;
+  const verdict = await identifyGroupIssuer(decoded.token, {
+    identity: options.identity,
+    clock: options.clock,
+    revocation: options.revocation,
+    expectedBearer: options.deviceId,
+  });
+  if (!verdict.ok) return { ok: false, reason: verdict.reason };
+  if (verdict.depth !== 0) return { ok: false, reason: "not_root_level" };
+  return {
+    ok: true,
+    issuerHex: verdict.issuerHex,
+    expires: verdict.claims.expires,
+  };
+}

package/src/core/membership-proofs.ts

@@ -0,0 +1,149 @@
+/**
+ * A device's own membership proof under one grouping issuer, kept fresh, and the checks for other devices' proofs (agent-comms#266, agent-comms#343). MeshStore holds one instance per issuer, its user principal and its machine, and hands each its identity, peer id and error sink. The checks do not depend on which issuer an instance mints under, so either instance can verify or identify any proof.
+ */
+
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import {
+  deviceIdFromHex,
+  deviceIdToHex,
+} from "wire-mesh-core/domain/device-id";
+import type { MeshStoreIdentity } from "./mesh-store-shared.js";
+import {
+  MEMBERSHIP_PROOF_LIFETIME_MS,
+  identifyMembershipProofIssuer,
+  mintMembershipProof,
+  verifyMembershipProof,
+  type IdentifiedMembershipProof,
+  type MembershipProofVerdict,
+} from "./membership-proof.js";
+
+/** How many times per proof lifetime the proof is re-minted, so a missed tick or two never lets the advertised proof lapse. */
+const REFRESHES_PER_LIFETIME = 3;
+/** How often an advertised proof, or a name claim riding beside it, is re-minted. */
+export const PROOF_REFRESH_INTERVAL_MS =
+  MEMBERSHIP_PROOF_LIFETIME_MS / REFRESHES_PER_LIFETIME;
+
+export interface MembershipProofsDeps {
+  /** Throws if the store has no identity yet. */
+  getIdentity: () => MeshStoreIdentity;
+  /** The issuer this instance mints under, picked out of the store's identity: its user principal or its machine. */
+  issuerOf: (identity: Readonly<MeshStoreIdentity>) => IdentityPort;
+  /** This device's own id (hex). */
+  getPeerId: () => string;
+  onError: (error: Error) => void;
+}
+
+/** The last account-membership verdict for one device: which proof it was about, against which principal, and until when a positive one holds. */
+interface AccountMemberVerdict {
+  proof: string;
+  principal: string;
+  /** Epoch ms after which a positive verdict needs checking again; a negative one never changes for the same proof and principal. */
+  until: number | undefined;
+}
+
+export class MembershipProofs {
+  private proof: string | undefined;
+  private minting = false;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  /** Keyed by device-id hex. One entry per device this side has checked, replaced whenever that device's proof or this side's principal changes. */
+  private readonly accountVerdicts = new Map<string, AccountMemberVerdict>();
+
+  constructor(private readonly deps: Readonly<MembershipProofsDeps>) {}
+
+  /** This device's current proof, undefined until the first has been minted. */
+  current(): string | undefined {
+    return this.proof;
+  }
+
+  /** Mints a proof now and again on an interval. A failed mint is reported and retried on the next tick; the previous proof stays until it lapses. */
+  start(): void {
+    this.stop();
+    this.refresh();
+    this.timer = setInterval(() => {
+      this.refresh();
+    }, PROOF_REFRESH_INTERVAL_MS);
+    this.timer.unref();
+  }
+
+  stop(): void {
+    clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  /** Whether a gossiped proof shows that issuerHex vouches for deviceHex, as this node sees it: its own identity, clock and revocation view. */
+  async verify(
+    claim: Readonly<{ proof: string; deviceHex: string; issuerHex: string }>,
+  ): Promise<MembershipProofVerdict> {
+    const { identity, clock, revocation } = this.deps.getIdentity();
+    return verifyMembershipProof({
+      proof: claim.proof,
+      deviceId: deviceIdFromHex(claim.deviceHex),
+      issuerId: deviceIdFromHex(claim.issuerHex),
+      identity,
+      clock,
+      revocation,
+    });
+  }
+
+  /** Whether a gossiped proof shows that deviceHex belongs to the account this store holds: the proof verifies against this store's own user principal. A verdict is remembered per device, so a device re-gossiping the same proof is not re-verified on every advert; a positive one is trusted only until its proof expires, a negative one for as long as the proof and this side's principal are unchanged. */
+  async isAccountMember(
+    claim: Readonly<{ proof: string; deviceHex: string }>,
+  ): Promise<boolean> {
+    const { userIdentity, clock } = this.deps.getIdentity();
+    const principal = deviceIdToHex(userIdentity.deviceId);
+    const known = this.accountVerdicts.get(claim.deviceHex);
+    if (known?.proof === claim.proof && known.principal === principal) {
+      if (known.until === undefined) return false;
+      if (known.until > clock.now()) return true;
+    }
+    const verdict = await this.verify({
+      proof: claim.proof,
+      deviceHex: claim.deviceHex,
+      issuerHex: principal,
+    });
+    this.accountVerdicts.set(claim.deviceHex, {
+      proof: claim.proof,
+      principal,
+      until: verdict.ok ? verdict.expires : undefined,
+    });
+    return verdict.ok;
+  }
+
+  /** Which issuer a gossiped proof shows vouching for deviceHex, as this node sees it. */
+  async identify(
+    claim: Readonly<{ proof: string; deviceHex: string }>,
+  ): Promise<IdentifiedMembershipProof> {
+    const { identity, clock, revocation } = this.deps.getIdentity();
+    return identifyMembershipProofIssuer({
+      proof: claim.proof,
+      deviceId: deviceIdFromHex(claim.deviceHex),
+      identity,
+      clock,
+      revocation,
+    });
+  }
+
+  private refresh(): void {
+    if (this.minting) return;
+    this.minting = true;
+    const storeIdentity = this.deps.getIdentity();
+    mintMembershipProof({
+      issuer: this.deps.issuerOf(storeIdentity),
+      clock: storeIdentity.clock,
+      deviceId: deviceIdFromHex(this.deps.getPeerId()),
+    })
+      .then(
+        (proof) => {
+          this.proof = proof;
+        },
+        (error: unknown) => {
+          this.deps.onError(
+            error instanceof Error ? error : new Error(String(error)),
+          );
+        },
+      )
+      .finally(() => {
+        this.minting = false;
+      });
+  }
+}

package/src/core/mesh-graph-trace-tool.ts

@@ -0,0 +1,81 @@
+/**
+ * CommsTool's mesh_graph/mesh_trace action handlers (agent-comms#199) -- split out of tool.ts purely to keep that file under the repo's max-lines cap, the same reason gateway-trust-actions.ts/connection-code-tool.ts were split from it. Free functions over MeshOnlyFeatures's own meshGraph/meshTrace methods rather than class methods, since CommsTool owns no state of its own for this concern.
+ */
+
+import type { CommsAction } from "./types.js";
+import type { CommsResult, MeshOnlyFeatures } from "./tool.js";
+import { tryMeshAction } from "./tool.js";
+import { idWithNames, type Namer } from "./naming.js";
+
+/** Column width the "direct"/"relay" edge-kind label is padded to in meshGraphAction's own listing, matching tool.ts's own aligned-column convention for every other tabular action result. */
+const MESH_GRAPH_EDGE_KIND_COLUMN_WIDTH = 6;
+
+/** Uniform "this bridge isn't backed by a mesh transport" result, mirroring tool.ts's own notMeshBacked for the other MeshOnlyFeatures methods (not exported from there, so re-declared locally the same way gateway-trust-actions.ts's own gatewayTrustUnavailable already does). */
+function meshFeatureUnavailable(action: string): CommsResult {
+  return {
+    isError: true,
+    content: `${action} requires a mesh-backed store (this session is running on FileStore)`,
+  };
+}
+
+/** Reports every known device (nodes, each by its full id, which mesh_trace takes, and its display name from namer) and every self-reported connection edge between them (edges, by display name), assembled from the cached gossip directory: a cheap, possibly-stale snapshot; meshTraceAction below is the live, cache-bust counterpart for one specific device. */
+export function meshGraphAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "meshGraph">>,
+  namer: Namer,
+): CommsResult {
+  if (!store.meshGraph) return meshFeatureUnavailable("mesh_graph");
+  const graph = store.meshGraph();
+  if (graph.nodes.length === 0)
+    return { content: "No known devices in the mesh graph.", isError: false };
+
+  const edgeLines = graph.edges.map((edge) => {
+    const via =
+      edge.kind === "relay" && edge.via !== undefined
+        ? ` via ${namer(edge.via)}`
+        : "";
+    return `  ${edge.kind.padEnd(MESH_GRAPH_EDGE_KIND_COLUMN_WIDTH)} ${namer(edge.from)} -> ${namer(edge.to)}${via}`;
+  });
+  const edgesBlock =
+    edgeLines.length > 0 ? edgeLines.join("\n") : "  (no edges reported)";
+  return {
+    content: `Mesh graph:\nNodes (${String(graph.nodes.length)}):\n${graph.nodes.map((node) => `  ${idWithNames(node, namer)}`).join("\n")}\nEdges:\n${edgesBlock}`,
+    isError: false,
+  };
+}
+
+/** Sends path.trace to action.target and reports the real end-to-end RTT plus each side's own relayed/hub-address knowledge -- the live counterpart to meshGraphAction's gossiped snapshot. */
+export async function meshTraceAction(
+  store: Readonly<Pick<MeshOnlyFeatures, "meshTrace">>,
+  action: CommsAction & { action: "mesh_trace" },
+): Promise<CommsResult> {
+  if (!store.meshTrace) return meshFeatureUnavailable("mesh_trace");
+  return tryMeshAction(`trace ${action.target}`, async () => {
+    // Called via `?.()` rather than a `const meshTrace = store.meshTrace` extraction -- the latter would silently drop `this` (WireMeshTransport.meshTrace reads its own private fields), a real bug this exact pattern caught during development. TypeScript can't carry the `if (!store.meshTrace)` guard above across this closure boundary, so `result` is still typed possibly-undefined even though it never actually is at runtime.
+    const result = await store.meshTrace?.(action.target, action.timeoutMs);
+    if (!result) return meshFeatureUnavailable("mesh_trace").content;
+    if (result.outcome.result === "error") {
+      throw new Error(
+        `${result.outcome.code}${result.outcome.message !== undefined ? `: ${result.outcome.message}` : ""}`,
+      );
+    }
+    const localHub =
+      result.local.hubAddress !== undefined
+        ? ` (hub ${result.local.hubAddress})`
+        : "";
+    const lines = [
+      `Trace to ${action.target}:`,
+      `  RTT: ${String(result.rttMs)}ms`,
+      `  Local:  ${result.local.relayed ? "relayed" : "direct"}${localHub}`,
+    ];
+    if (result.remote) {
+      const remoteHub =
+        result.remote.hubAddress !== undefined
+          ? ` (hub ${result.remote.hubAddress})`
+          : "";
+      lines.push(
+        `  Remote: ${result.remote.relayed ? "relayed" : "direct"}${remoteHub}`,
+      );
+    }
+    return lines.join("\n");
+  });
+}