agent-comms 8.15.8 → 8.15.10

package/src/core/room-router.ts

@@ -0,0 +1,180 @@
+/**
+ * The room verb router: one drain loop per session, dispatching each incoming manage-request by verb. A legacy FRAME_VERB command (P2's opaque-payload carriage, still the only path for anything core/room doesn't yet have real semantics for) decodes and routes to the matching TransportEvents callback exactly as WireMeshTransport used to do inline; a registered room verb (room.send, room.join, ...) goes to its own handler; anything else -- an unrecognised verb, or a room verb this phase hasn't registered a handler for yet -- gets unsupported_verb rather than silence.
+ *
+ * core/room's own manage-command shape puts the specific action in params.verb (room.send, room.join, ...), not in the outer command.verb, which is instead the single room:member capability every ordinary membership verb shares (room.join/room.invite are ungated and carry no token at all, but still ride command.verb === "room:member" -- see spec/room.cddl and its own conformance vectors). Dispatch is therefore keyed on params.verb, not command.verb.
+ *
+ * Deliberately empty of real room-verb handlers in this phase (P3.3): the router itself, and the unsupported_verb fallback, are the whole deliverable here. Each later phase (P3.4 admission, P3.5 fan-out, P3.6 state-sync, P3.7 kick) registers the handlers for the verbs it implements.
+ */
+
+import type {
+  AcceptedMeshSession,
+  IncomingManageRequest,
+  ManageOutcome,
+} from "wire-mesh-core/domain/mesh-session";
+import { isMeshMessage } from "./wire-protocol.js";
+import type { MeshMessage } from "./wire-protocol.js";
+import type { ConnectionHandle, TransportEvents } from "./transport.js";
+import { FRAME_VERB } from "./wire-mesh-transport.js";
+
+/** Extracts and validates the carried MeshMessage from an incoming FRAME_VERB command. Returns undefined for anything that isn't a well-formed frame -- an unrecognised or malformed payload is dropped, not thrown. Exported for WireMeshTransport's own quarantine-gate pre-approval check (introduce/connect_request detection), the one place outside this router that still needs to decode a legacy frame directly. */
+export function extractMessage(
+  command: IncomingManageRequest["command"],
+): MeshMessage | undefined {
+  if (command.verb !== FRAME_VERB) return undefined;
+  const params: unknown = command.params;
+  if (typeof params !== "object" || params === null) return undefined;
+  if (!("message" in params)) return undefined;
+  const message: unknown = params.message;
+  return isMeshMessage(message) ? message : undefined;
+}
+
+/** Routes an already-decoded legacy MeshMessage to the matching TransportEvents callback -- moved verbatim from WireMeshTransport's own former route() method. */
+function routeLegacyMessage(
+  handle: Readonly<ConnectionHandle>,
+  message: MeshMessage,
+  events: Readonly<TransportEvents>,
+): void {
+  switch (message.method) {
+    case "introduce": {
+      events.onIntroduction(handle, {
+        peerId: handle.id,
+        dataPort: message.dataPort,
+      });
+      return;
+    }
+    case "peer_list": {
+      events.onPeerList(message.peers);
+      return;
+    }
+    case "peer_joined": {
+      events.onPeerJoined(message.peer);
+      return;
+    }
+    case "become_coordinator": {
+      events.onBecomeCoordinator(message.peerList);
+      return;
+    }
+    case "connect_request": {
+      // Only ever reaches here if a session was somehow promoted without going through WireMeshTransport's own consumeQuarantined handling of it -- can't happen given every requiresApproval accept path routes through consumeQuarantined first, kept here only so an unrecognised-in-context method fails closed rather than falling to the onMessage case below.
+      return;
+    }
+    // Every other wire method -- mesh-state gossip (state_sync/state_update/peer_left) -- has no dedicated TransportEvents callback and falls to the generic onMessage handler, exactly as the old unconditional default case did.
+    case "state_sync":
+    case "state_update":
+    case "peer_left": {
+      events.onMessage(handle, message);
+      return;
+    }
+    default: {
+      // A peer running a newer build can send a wire method this closed union doesn't know about yet -- isMeshMessage's own runtime check only requires a string method field, deliberately looser than MeshMessage's compile-time type, so this branch is reachable at runtime even though every known case above is already covered.
+      events.onMessage(handle, message);
+      return;
+    }
+  }
+}
+
+/** Reads params.verb from an incoming command's params, or undefined if it isn't a plain object with a string verb field. */
+function extractParamsVerb(params: unknown): string | undefined {
+  if (typeof params !== "object" || params === null) return undefined;
+  if (!("verb" in params)) return undefined;
+  return typeof params.verb === "string" ? params.verb : undefined;
+}
+
+/** Extra facts about a request's own transport-level origin that a room-verb handler may need beyond its resolved ConnectionHandle -- currently just the hub-relay address, since RoomVerbHandler's own (request, handle) shape has no way to reach "which raw session/connection this arrived on" (agent-comms#216). Every field is optional, and every call site with nothing to report supplies an empty object rather than omitting origin altogether -- only the hub-relayed dispatch path (dispatchHubRequest, hub-session.ts) has ever anything to report here. */
+export interface RoomRequestOrigin {
+  /** This side's own dialled address for the hub this request was relayed through, when relayed and known -- the answering side's equivalent of wire-mesh-core's own TracePathOptions.localHubAddress/PathTraceLocal.hubAddress on the sending side. Read directly off HubSession's own currently-dialled URL by dispatchHubRequest's caller (HubSession.consume), the one place that both receives the raw hub session and knows this fact -- never rederived here. */
+  relayHubAddress?: string;
+}
+
+/** Handles one already-verified-and-approved incoming request, given its authenticated connection handle and this request's own transport-level origin. Registered per params.verb (room.send, room.join, ...), never per command.verb (the shared room:member capability every ordinary membership verb rides under) -- see this file's own header comment. origin is optional here (mirroring handleRequest's own optionality below) rather than required, since most existing handlers never look at it and a good number of tests call a handler value straight out of roomVerbHandlers with just (request, handle) -- only path.trace's own handler (mesh-graph.ts) actually reads it, and does so via an optional-chained read rather than assuming it is always supplied. */
+export type RoomVerbHandler = (
+  request: IncomingManageRequest,
+  handle: Readonly<ConnectionHandle>,
+  origin?: Readonly<RoomRequestOrigin>,
+) => Promise<ManageOutcome>;
+
+export interface RoomRouterOptions {
+  /** The legacy TransportEvents callbacks, still the only path for anything core/room doesn't yet have real semantics for. */
+  events: TransportEvents;
+  /** Room-verb handlers, keyed by params.verb. Empty in P3.3 -- each later phase registers the verbs it implements. */
+  handlers?: Partial<Record<string, RoomVerbHandler>>;
+}
+
+export interface RoomRouter {
+  /** Handles one request that arrived over an ordinary local peer session: a legacy FRAME_VERB frame goes to the matching TransportEvents callback, and anything else is dispatched as a room verb. Exported for direct unit testing; drainSession below is the thin per-session loop wrapper real callers use. origin defaults to an empty object (nothing to report) when omitted, since an ordinary local peer session has no relay-hub address of its own to report. */
+  handleLocalRequest: (
+    request: IncomingManageRequest,
+    handle: Readonly<ConnectionHandle>,
+    origin?: Readonly<RoomRequestOrigin>,
+  ) => Promise<void>;
+  /** Handles one request that arrived relayed through a hub. Only a room verb is ever dispatched: a legacy FRAME_VERB frame is answered with unsupported_verb and never decoded, so a relayed sender cannot reach the TransportEvents callbacks (mesh-state gossip such as state_sync and state_update) however it is routed here. Separate from handleLocalRequest so that the distinction is structural rather than a check each caller must remember to make first. */
+  handleRelayedRequest: (
+    request: IncomingManageRequest,
+    handle: Readonly<ConnectionHandle>,
+    origin?: Readonly<RoomRequestOrigin>,
+  ) => Promise<void>;
+  /** Consumes one session's incomingManageRequests until it ends, dispatching each request via handleLocalRequest. Becomes the single consumer of that iterable from this point on -- the caller must not also iterate the same session's incomingManageRequests itself once this is called. */
+  drainSession: (
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+  ) => void;
+}
+
+export function createRoomRouter(options: RoomRouterOptions): RoomRouter {
+  /** A room verb is never carried under FRAME_VERB, so a frame reaching here is not a room request whatever its params claim, and is refused like any other unregistered verb. */
+  async function dispatchRoomVerb(
+    request: IncomingManageRequest,
+    handle: Readonly<ConnectionHandle>,
+    origin: Readonly<RoomRequestOrigin>,
+  ): Promise<void> {
+    const verb = extractParamsVerb(request.command.params);
+    const handler =
+      request.command.verb !== FRAME_VERB && verb !== undefined
+        ? options.handlers?.[verb]
+        : undefined;
+    if (handler === undefined) {
+      await request
+        .respond({ result: "error", code: "unsupported_verb" })
+        .catch(() => undefined);
+      return;
+    }
+    const outcome = await handler(request, handle, origin);
+    await request.respond(outcome).catch(() => undefined);
+  }
+
+  async function handleLocalRequest(
+    request: IncomingManageRequest,
+    handle: Readonly<ConnectionHandle>,
+    origin: Readonly<RoomRequestOrigin> = {},
+  ): Promise<void> {
+    if (request.command.verb === FRAME_VERB) {
+      const message = extractMessage(request.command);
+      if (message !== undefined) {
+        routeLegacyMessage(handle, message, options.events);
+      }
+      await request.respond({ result: "ok" }).catch(() => undefined);
+      return;
+    }
+    await dispatchRoomVerb(request, handle, origin);
+  }
+
+  async function handleRelayedRequest(
+    request: IncomingManageRequest,
+    handle: Readonly<ConnectionHandle>,
+    origin: Readonly<RoomRequestOrigin> = {},
+  ): Promise<void> {
+    await dispatchRoomVerb(request, handle, origin);
+  }
+
+  return {
+    handleLocalRequest,
+    handleRelayedRequest,
+    drainSession(session, handle) {
+      void (async () => {
+        for await (const request of session.incomingManageRequests) {
+          await handleLocalRequest(request, handle);
+        }
+      })();
+    },
+  };
+}

package/src/core/room-token-verification.ts

@@ -0,0 +1,85 @@
+/**
+ * core/room's six verifier obligations (spec/room.cddl), layered on top of verifyCapabilityToken (obligations 2, 4, and 5 -- bearer match, ordinary token-claims checks, and delegations-remaining narrowing -- already live there). This module adds the checks specific to room-shaped scopes: the token must actually carry the room:member capability the six obligations presuppose (room.cddl's own obligation 1 opens with "a room:member token's delegation chain..." -- a token minted for some other capability that happens to be scoped to a room path must not pass just because scope.kind/path line up), the chain must terminate at the correct root for the path's own shape (1), and the token's own scope must actually name the room the request claims to act on (3). Obligation 6 (refuse an unrecognised content-type/kind) is a message-handling concern, not a token-verification one, and belongs to the room verb router instead.
+ */
+
+import {
+  verifyCapabilityToken,
+  type TokenVerdictReason,
+  type VerifyCapabilityTokenOptions,
+} from "wire-mesh-core/domain/tokens";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type {
+  CapabilityToken,
+  DeviceId,
+  TokenClaims,
+} from "wire-mesh-core/generated/protocol";
+import { parseRoomPath } from "./room-path.js";
+import type { DelegationPolicy } from "./delegation-policy.js";
+
+/** The one capability that authorises every ordinary room-membership verb (room.send/read/leave/members) -- "one resource, not several", the same pattern exec:pty already uses for its own four inner verbs. room.join/room.invite are deliberately ungated and never reach this check at all. This same string is also the outer manage-command's own verb for every room-domain command (gated or ungated): core/room's own convention puts the specific action in params.verb, with command.verb fixed to this capability name -- exported so wire-level command construction (see wire-mesh-transport.ts/mesh-store.ts) shares this one constant rather than a second, independently-typed copy of the same literal. */
+export const ROOM_MEMBER_CAPABILITY = "room:member";
+
+/** room:member's own issuer-side delegation policy (agent-comms#163): a member's grant must never itself become the parent of a further delegation, so room:member is unconditionally non-delegable, with no per-agent override -- there is no legitimate case for one bearer's own room membership to be redelegable when every other bearer's isn't, unlike a general-purpose capability a future issuer (device-to-user membership, DM send) might reasonably narrow per bearer. Shared by every room:member mint call site (the owner's own root grant, an invite, and a real admission) via resolveDelegationsRemaining, replacing what was previously each site's own repeated `delegationsRemaining: 0` literal. */
+export const ROOM_MEMBER_DELEGATION_POLICY: DelegationPolicy = {
+  nonDelegable: new Set([ROOM_MEMBER_CAPABILITY]),
+};
+
+export type RoomTokenVerdictReason =
+  | TokenVerdictReason
+  | "wrong_capability"
+  | "wrong_scope_kind"
+  | "wrong_scope_path"
+  | "wrong_chain_root";
+
+export type RoomTokenVerdict =
+  | { ok: true; claims: TokenClaims }
+  | { ok: false; reason: RoomTokenVerdictReason };
+
+export interface VerifyRoomTokenOptions extends Omit<
+  VerifyCapabilityTokenOptions,
+  "expectedBearer"
+> {
+  /** The peer identity actually authenticated on the arriving connection (obligation 2) -- never a relay-asserted or gossip-derived value. Mandatory here: every room verb requires a bearer, unlike verifyCapabilityToken's own optional field for callers presenting a token to authorise themselves rather than a specific counterparty. */
+  expectedBearer: DeviceId;
+  /** The room path this request claims to act on (obligation 3) -- must equal the token's own scope.path, and its own shape determines the chain root obligation 1 requires. */
+  roomPath: string;
+}
+
+/**
+ * Verifies a `room:member` capability token against all six of core/room's verifier obligations. Delegates obligations 2/4/5 to verifyCapabilityToken directly; adds obligation 3 (scope.kind/scope.path must match the room being acted on) and obligation 1 (the chain's root must be the room's own owner for a named room, or the verifying identity itself for a DM -- never either named participant directly, since a DM token minted by anyone other than the verifier would let a sender self-issue authority to message a stranger unsolicited).
+ */
+export async function verifyRoomToken(
+  token: CapabilityToken,
+  options: VerifyRoomTokenOptions,
+): Promise<RoomTokenVerdict> {
+  const verdict = await verifyCapabilityToken(token, {
+    identity: options.identity,
+    clock: options.clock,
+    revocation: options.revocation,
+    expectedBearer: options.expectedBearer,
+  });
+  if (!verdict.ok) {
+    return verdict;
+  }
+
+  if (verdict.claims.capability !== ROOM_MEMBER_CAPABILITY) {
+    return { ok: false, reason: "wrong_capability" };
+  }
+  if (verdict.claims.scope.kind !== "room") {
+    return { ok: false, reason: "wrong_scope_kind" };
+  }
+  if (verdict.claims.scope.path !== options.roomPath) {
+    return { ok: false, reason: "wrong_scope_path" };
+  }
+
+  const parsed = parseRoomPath(options.roomPath);
+  const expectedRootHex =
+    parsed.kind === "owner-named"
+      ? parsed.owner
+      : deviceIdToHex(options.identity.deviceId);
+  if (deviceIdToHex(verdict.rootIssuer) !== expectedRootHex) {
+    return { ok: false, reason: "wrong_chain_root" };
+  }
+
+  return { ok: true, claims: verdict.claims };
+}

package/src/core/room-wire-extensions.ts

@@ -0,0 +1,60 @@
+/**
+ * Room-state and inviter-agent wire extensions riding room.join/room.members/room.invite's own open extension tails (P3.6/P3.8) -- agent-comms' own application data convention, since core/room itself has no concept of a display name, description, or inviter identity. Split out of MeshStore as plain functions (the originals were `private static` methods with zero `this` access) because both room-protocol.ts and room-lifecycle.ts need them.
+ */
+
+import { RoomType } from "./types.js";
+import type { AgentIdentity, Room } from "./types.js";
+
+/**
+ * Room metadata (name/description/type) riding room-join-ok/room-members-ok's own open extension tail (P3.6), agent-comms' own convention for the "namespaced room-state extension" the design names -- core/room itself has no concept of a display name or description, so this is application data, not a wire-level field. Absent entirely for a DM path (room is undefined there; a DM has no name/description/type to report) rather than a hollow placeholder.
+ */
+export function roomStateExtension(room: Readonly<Room> | undefined): {
+  "room-state"?: { name: string; description: string; type: RoomType };
+} {
+  if (room === undefined) return {};
+  return {
+    "room-state": {
+      name: room.name,
+      description: room.description,
+      type: room.type,
+    },
+  };
+}
+
+/** The receiving-side counterpart of roomStateExtension: narrows an incoming response's own "room-state" field (an unknown, since it rides the wire schema's open catchall tail) to the shape this store's own convention actually sends, or undefined for a peer running without it (an older version, or a DM's own room-join-ok, which never carries one). */
+export function parseRoomStateExtension(
+  value: unknown,
+): { name: string; description: string; type: RoomType } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  if (!("name" in value) || !("description" in value) || !("type" in value))
+    return undefined;
+  if (typeof value.name !== "string" || typeof value.description !== "string")
+    return undefined;
+  const parsedType = RoomType.safeParse(value.type);
+  if (!parsedType.success) return undefined;
+  return {
+    name: value.name,
+    description: value.description,
+    type: parsedType.data,
+  };
+}
+
+/**
+ * The inviter's own display name and cwd, riding room-invite's own open extension tail -- agent-comms' own application data, the same convention roomStateExtension already establishes for room metadata. Unlike room-state (which needs gossip on the requester's own side of room.join/members), the inviter here is always this store's own local agent record: inviteToRoom only ever succeeds for the room's real owner, which per this store's own organising fact (one bridge is one agent is one device) is always this.peerId, so the record is always this store's own registration, never a gossip-dependent lookup.
+ */
+export function inviterAgentExtension(inviter: Readonly<AgentIdentity>): {
+  "inviter-agent": { name: string; cwd: string };
+} {
+  return { "inviter-agent": { name: inviter.name, cwd: inviter.cwd } };
+}
+
+/** The receiving-side counterpart of inviterAgentExtension: narrows an incoming room.invite's own "inviter-agent" field to the shape this store's own convention sends, or undefined for a peer running without it (an older version) -- the caller falls back to the inviter's bare device-id in that case, the same honest degradation parseRoomStateExtension's own absent case already accepts. */
+export function parseInviterAgentExtension(
+  value: unknown,
+): { name: string; cwd: string } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  if (!("name" in value) || !("cwd" in value)) return undefined;
+  if (typeof value.name !== "string" || typeof value.cwd !== "string")
+    return undefined;
+  return { name: value.name, cwd: value.cwd };
+}

package/src/core/self-name-claim.ts

@@ -0,0 +1,67 @@
+/**
+ * One grouping issuer's self display name claim (agent-comms#345 for the machine, agent-comms#359 for the user principal), kept fresh beside that issuer's proof: re-minted on the proofs' own cadence from whatever name the issuer's identity file currently holds, so a name set or cleared by any bridge on the host reaches every bridge's advert within one refresh, and the setting bridge's at once.
+ */
+
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { MeshStoreIdentity } from "./mesh-store-shared.js";
+import { MEMBERSHIP_PROOF_LIFETIME_MS } from "./membership-proof.js";
+import { PROOF_REFRESH_INTERVAL_MS } from "./membership-proofs.js";
+import { mintNameClaim } from "./name-claim.js";
+
+export interface SelfNameClaimDeps {
+  /** Throws if the store has no identity yet. */
+  getIdentity: () => MeshStoreIdentity;
+  /** The issuer this instance signs its claim as, picked out of the store's identity: its user principal or its machine. */
+  issuerOf: (identity: Readonly<MeshStoreIdentity>) => IdentityPort;
+  /** The name the issuer currently asserts for itself, read from its identity file; undefined when it has none. */
+  loadName: (identity: Readonly<MeshStoreIdentity>) => string | undefined;
+  onError: (error: Error) => void;
+}
+
+export class SelfNameClaim {
+  private claim: string | undefined;
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(private readonly deps: Readonly<SelfNameClaimDeps>) {}
+
+  /** The current claim, undefined while the issuer has no name or before the first claim is minted. */
+  current(): string | undefined {
+    return this.claim;
+  }
+
+  start(): void {
+    this.stop();
+    void this.refresh();
+    this.timer = setInterval(() => {
+      void this.refresh();
+    }, PROOF_REFRESH_INTERVAL_MS);
+    this.timer.unref();
+  }
+
+  stop(): void {
+    clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  /** Re-reads the issuer's name and re-mints its claim now; drops the claim when the issuer has no name. A failed mint is reported and the previous claim is kept until the next refresh. */
+  async refresh(): Promise<void> {
+    const identity = this.deps.getIdentity();
+    const name = this.deps.loadName(identity);
+    if (name === undefined) {
+      this.claim = undefined;
+      return;
+    }
+    try {
+      this.claim = await mintNameClaim({
+        issuer: this.deps.issuerOf(identity),
+        clock: identity.clock,
+        name,
+        lifetimeMs: MEMBERSHIP_PROOF_LIFETIME_MS,
+      });
+    } catch (error) {
+      this.deps.onError(
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+}

package/src/core/send-outcome.ts

@@ -0,0 +1,69 @@
+/**
+ * send-outcome -- classifies what actually happened to one directed room-domain request, so a caller can tell a delivery from a message that is merely held for retry and from one the recipient refused outright. The distinction that matters is whether trying again could ever change the answer: a deadline that passed or a route that did not exist may succeed on the next attempt, while a refusal (an unverifiable token, an unknown verb, a denied decision) is the recipient's settled answer and will be repeated every time.
+ */
+
+import type { ManageOutcome } from "wire-mesh-core/domain/mesh-session";
+import type { MessageDelivery, TransientSendFailure } from "./types.js";
+
+/** Wire error codes that name a failure to reach the recipient at all, rather than an answer from it. Everything else, including a code this version does not recognise, is treated as a refusal: a send whose failure cannot be explained is reported to its sender now rather than queued to fail again unseen. */
+const TRANSIENT_OUTCOME_CODES: ReadonlyMap<string, TransientSendFailure> =
+  new Map([
+    ["timeout", "timeout"],
+    ["not_connected", "not_connected"],
+    // This side's own transport answering that it has nowhere to send the request (no session, and no gateway willing to relay for that device). Reported as not_connected because that is exactly what it means to the sender: no route to the recipient existed when the request was attempted.
+    ["no_route", "not_connected"],
+  ]);
+
+/**
+ * What became of one directed room-domain request. `undelivered` is the retryable class: the recipient never answered, so the request may still succeed later and is worth holding. `refused` is terminal: the recipient did answer, with a failure it will give again, so the sender is told now rather than waiting on a retry that cannot help.
+ */
+export type RoomRequestOutcome =
+  | { kind: "delivered" }
+  | { kind: "undelivered"; reason: TransientSendFailure }
+  | { kind: "refused"; code: string; message?: string };
+
+/** Classifies a wire manage-outcome into the three states above. A non-ok outcome whose code names an unreached recipient is undelivered; every other non-ok outcome is a refusal carrying the recipient's own code, and its own message when it sent one (a rejected room.join carries the refuser's stated reason there), so the sender can be told exactly what it was refused with. */
+export function classifyManageOutcome(
+  outcome: Readonly<ManageOutcome>,
+): RoomRequestOutcome {
+  if (outcome.result === "ok") return { kind: "delivered" };
+  const reason = TRANSIENT_OUTCOME_CODES.get(outcome.code);
+  if (reason !== undefined) return { kind: "undelivered", reason };
+  return {
+    kind: "refused",
+    code: outcome.code,
+    ...(outcome.message !== undefined && { message: outcome.message }),
+  };
+}
+
+/** A one-line, human-readable rendering of a refusal for an error message or a tool result: the recipient's own code, plus the message it sent when it sent one. */
+export function describeRefusal(
+  outcome: Readonly<{ code: string; message?: string }>,
+): string {
+  return outcome.message === undefined
+    ? outcome.code
+    : `${outcome.code}: ${outcome.message}`;
+}
+
+/** A one-line, human-readable rendering of what became of a message for one recipient, phrased to read as a clause after the message's own id ("read by a1b2c3", "queued for a1b2c3 (timeout), not yet delivered"). Shared by every surface that reports a delivery status, so a tool result, a terminal line and a browser line never describe the same state differently. */
+export function describeDeliveryFor(
+  delivery: Readonly<MessageDelivery>,
+  agent: string,
+): string {
+  switch (delivery.status) {
+    case "delivered":
+      return `delivered to ${agent}`;
+    case "read":
+      return `read by ${agent}`;
+    case "queued":
+      return `queued for ${agent} (${delivery.reason}), not yet delivered`;
+    case "refused":
+      return `refused by ${agent} (${delivery.code})`;
+    case "dropped":
+      return `dropped for ${agent}, never delivered`;
+    case "expired":
+      return `expired for ${agent}, never delivered`;
+    default:
+      return delivery satisfies never;
+  }
+}

package/src/core/shutdown-signals.ts

@@ -0,0 +1,57 @@
+/**
+ * The termination-signal handling every bridge needs, in one place. A bridge that exits without running MeshStore.shutdown() never hands its coordinator role on, so if it held that role the mesh is left with no coordinator until the surviving peers notice and race for the port -- recoverable, but it loses whatever the coordinator process alone was doing (the stale-agent probe and the cc-peer front) for as long as the race takes.
+ *
+ * Which signals a process should answer is not in question; what differs is what it may do afterwards. A bridge that owns its own process exits. A bridge loaded into someone else's process (a plugin) must not: registering any listener for SIGINT or SIGTERM removes Node's own default terminate behaviour, so a plugin that handled the signal and then did nothing would silently swallow its host's Ctrl-C. Such a bridge re-raises instead, which reaches the host's own handler if it has one and terminates the process as usual if it does not.
+ */
+
+/** The termination signals a bridge answers. SIGHUP matters as much as the other two here: a bridge started from a terminal that closes receives only SIGHUP, and without it that exit is silently ungraceful. */
+const SHUTDOWN_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"] as const;
+
+/** The exit status a bridge reports when it shut down in answer to a signal: this is an orderly exit that did exactly what it was asked to. */
+const CLEAN_EXIT_CODE = 0;
+
+/** What a bridge does once its shutdown has run. "exit" ends the process and suits a bridge that owns it. "reraise" re-sends the same signal with this handler removed, so a bridge loaded into a host process leaves the decision to the host rather than exiting on its behalf. */
+export type ShutdownDisposition = "exit" | "reraise";
+
+export interface ShutdownSignalOptions {
+  /** The orderly shutdown itself, normally MeshStore.shutdown() plus whatever else the bridge owns. It is never expected to throw: a rejection here is reported to onError and the process still goes on to exit or re-raise. */
+  shutdown: () => Promise<void>;
+  /** See ShutdownDisposition. */
+  disposition: ShutdownDisposition;
+  /** Reports a shutdown that failed part way. Optional, since a bridge whose only sink is a protocol stream on stdout may have nowhere useful to write during its own exit. */
+  onError?: ((error: Error) => void) | undefined;
+}
+
+/**
+ * Installs one handler per termination signal, each running `shutdown` once and then exiting or re-raising per `disposition`. Registered with `once`, so a second signal of the same kind while the shutdown is still in flight takes the default action rather than starting a second one -- which is also what makes "reraise" terminate rather than loop.
+ *
+ * Returns a function that removes every handler it installed, for a caller that shuts down by some other route (a host's own lifecycle hook, or a test) and does not want the handlers outliving it.
+ */
+export function installShutdownSignalHandlers(
+  options: Readonly<ShutdownSignalOptions>,
+): () => void {
+  const { shutdown, disposition, onError } = options;
+  const installed = SHUTDOWN_SIGNALS.map((signal) => {
+    const handler = (): void => {
+      void shutdown()
+        .catch((error: unknown) => {
+          onError?.(error instanceof Error ? error : new Error(String(error)));
+        })
+        .finally(() => {
+          if (disposition === "exit") {
+            process.exit(CLEAN_EXIT_CODE);
+            return;
+          }
+          process.kill(process.pid, signal);
+        });
+    };
+    process.once(signal, handler);
+    return { signal, handler };
+  });
+
+  return () => {
+    for (const { signal, handler } of installed) {
+      process.off(signal, handler);
+    }
+  };
+}

package/src/core/stale-agent-checker.ts

@@ -0,0 +1,108 @@
+/**
+ * StaleAgentChecker: periodic liveness probe, run only by the elected coordinator (agent-comms#341), over every registered agent's own PID, marking a dead process's agent offline and, separately, purging agent records that have sat offline past a fixed threshold. Split out of MeshStore purely to keep mesh-store.ts under the repo's max-lines cap; owns its own probe-interval timer exclusively (nothing outside this class ever reads or writes it).
+ */
+
+import type { AgentIdentity, AgentStatus, DeliveryEvent } from "./types.js";
+import type { MeshStatePatch, PeerInfo } from "./wire-protocol.js";
+
+/** The state and collaborators StaleAgentChecker needs from MeshStore -- the core agent/delivery/peer/identity Maps it reads and mutates directly (shared references into MeshStore's own fields), plus the two DeliveryEngine operations a status change and an offline patch need to broadcast. */
+export interface StaleAgentCheckerDeps {
+  agents: Map<string, AgentIdentity>;
+  deliveryQueues: Map<string, DeliveryEvent[]>;
+  identityCache: Map<string, { id: string }>;
+  peerInfo: Map<string, PeerInfo>;
+  notifyRoomsOfStatus: (agentId: string, status: AgentStatus) => Promise<void>;
+  broadcastPatch: (patch: MeshStatePatch) => Promise<void>;
+  /** Raises an agent's sync revision, so the offline record outranks every snapshot taken while the agent was running. */
+  bump: (agent: AgentIdentity) => void;
+}
+
+/** How often the elected coordinator probes registered agent PIDs for liveness. */
+const PROBE_INTERVAL_MS = 5000;
+
+/** How long an agent may sit "offline" before its record is purged entirely, to prevent indefinite accumulation. */
+const OFFLINE_PURGE_THRESHOLD_MINUTES = 30;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+const OFFLINE_PURGE_THRESHOLD_MS =
+  OFFLINE_PURGE_THRESHOLD_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+export class StaleAgentChecker {
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(private readonly deps: StaleAgentCheckerDeps) {}
+
+  /** Starts the periodic probe (while this store holds the elected coordinator role). No-op if already running. */
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.probeStaleAgents();
+    }, PROBE_INTERVAL_MS);
+  }
+
+  /** Stops the periodic probe, if running. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private async probeStaleAgents(): Promise<void> {
+    const {
+      agents,
+      deliveryQueues,
+      identityCache,
+      peerInfo,
+      notifyRoomsOfStatus,
+      broadcastPatch,
+      bump,
+    } = this.deps;
+    const deadIds: string[] = [];
+
+    for (const [id, agent] of agents) {
+      if (agent.status !== "active") continue;
+      if (!this.isProcessAlive(agent.pid)) {
+        deadIds.push(id);
+      }
+    }
+
+    for (const id of deadIds) {
+      const agent = agents.get(id);
+      if (agent) {
+        agent.status = "offline";
+        bump(agent);
+        agents.set(id, agent);
+        await notifyRoomsOfStatus(id, "offline");
+      }
+      await broadcastPatch({ type: "agent_offline", agentId: id });
+      peerInfo.delete(id);
+    }
+
+    // Also purge long-offline agents to prevent indefinite accumulation.
+    const offlineThreshold = Date.now() - OFFLINE_PURGE_THRESHOLD_MS;
+    const purgeIds: string[] = [];
+    for (const [id, agent] of agents) {
+      if (agent.status !== "offline") continue;
+      const startedAt = new Date(agent.startedAt).getTime();
+      if (startedAt < offlineThreshold) {
+        purgeIds.push(id);
+      }
+    }
+    for (const id of purgeIds) {
+      agents.delete(id);
+      peerInfo.delete(id);
+      identityCache.delete(id);
+      deliveryQueues.delete(id);
+    }
+  }
+
+  private isProcessAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}