agent-comms 9.1.0 → 9.1.2

package/src/bridges/user/web/server.ts

@@ -18,6 +18,7 @@ import type { MeshStore } from "../../../core/mesh-store.js";
 import { CommsError } from "../../../core/store.js";
 import type { MeshStatePatch } from "../../../core/wire-protocol.js";
 import type { WebUrlStatus } from "../../../core/tool.js";
+import { MAX_MESSAGE_BYTES } from "../../../core/message-limits.js";
 import {
   createRoomAction,
   declineInviteAction,
@@ -59,6 +60,13 @@ import {
 } from "./web-access.js";
 import { bridgePortRange } from "./bridge-port-range.js";
 import { startWebBeacon } from "./web-beacon.js";
+import {
+  REQUEST_TIMEOUT_MS,
+  meshErrorMessage,
+  invalidJsonBody,
+  readBoundedBody,
+  serveRoute,
+} from "./request-handling.js";
 import {
   createFrontendAssetLoader,
   FrontendNotBuiltError,
@@ -81,6 +89,10 @@ const frontendAssets = createFrontendAssetLoader(
   fileURLToPath(new URL("./dist", import.meta.url)),
 );
 
+/** The body of the 503 for a frontend that was never built. */
+const FRONTEND_NOT_BUILT_BODY =
+  "The web frontend is not built. A git checkout does not include the build output; install the npm package, or run `pnpm build:frontend` in a checkout with its development dependencies installed.";
+
 /**
  * The frontend build output, or undefined after answering 503 because the build is absent. The server module is imported by every bridge, so a checkout without the build must still start; only the routes that serve the frontend are unavailable.
  */
@@ -94,7 +106,8 @@ function frontendOrUnavailable(
     res.writeHead(HTTP_SERVICE_UNAVAILABLE, {
       "Content-Type": "text/plain; charset=utf-8",
     });
-    res.end(error.message);
+    // Fixed text: the error's own message names the install path of this machine, which is not for a client.
+    res.end(FRONTEND_NOT_BUILT_BODY);
     return undefined;
   }
 }
@@ -244,6 +257,10 @@ export async function createWebServer(options?: {
   firstContactPort?: number | undefined;
   /** Overrides the hub a fresh controller's own coordinator role dials on takeover -- ChatController's own hubUrl, ignored when existingController is supplied since that controller already made its own choice. See ChatController's own hubUrl doc comment. */
   hubUrl?: string | undefined;
+  /** Overrides REQUEST_TIMEOUT_MS, the time a client has to send a whole request. A test sets it small to see the 408. */
+  requestTimeoutMs?: number | undefined;
+  /** Overrides how often Node checks connections against that timeout (its default is thirty seconds, so a timeout takes effect up to that much after it is due). A test sets it small. */
+  connectionsCheckingIntervalMs?: number | undefined;
 }): Promise<WebServerHandle> {
   const {
     port,
@@ -255,6 +272,8 @@ export async function createWebServer(options?: {
     coordinatorPort,
     firstContactPort,
     hubUrl,
+    requestTimeoutMs = REQUEST_TIMEOUT_MS,
+    connectionsCheckingIntervalMs,
   } = options ?? {};
   const controller =
     existingController ??
@@ -282,10 +301,33 @@ export async function createWebServer(options?: {
     localClientAddresses,
   };
 
-  const server = http.createServer((req, res) => {
-    if (!admitRequest(accessPolicy, req, res)) return;
-    handleRequest(req, res, controller, webConsoleDist);
-  });
+  const server = http.createServer(
+    {
+      requestTimeout: requestTimeoutMs,
+      headersTimeout: requestTimeoutMs,
+      ...(connectionsCheckingIntervalMs !== undefined && {
+        connectionsCheckingInterval: connectionsCheckingIntervalMs,
+      }),
+    },
+    (req, res) => {
+      // Every response, the fixed routes and the operator's web-console files alike, forbids a browser to guess a type other than the one declared.
+      res.setHeader("X-Content-Type-Options", "nosniff");
+      try {
+        if (!admitRequest(accessPolicy, req, res)) return;
+        handleRequest(req, res, controller, webConsoleDist);
+      } catch (err) {
+        // A request the synchronous routing cannot handle is answered, not thrown: an exception out of this listener would end the process.
+        process.stderr.write(
+          `agent-comms web UI: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+        if (!res.headersSent) {
+          jsonError(res, "Internal server error", HTTP_INTERNAL_SERVER_ERROR);
+        } else {
+          res.end();
+        }
+      }
+    },
+  );
 
   let boundPort: number;
   try {
@@ -308,10 +350,15 @@ export async function createWebServer(options?: {
     publisher.publish({ kind: "delivery", event });
   });
 
-  const wss = new WebSocketServer({ noServer: true });
+  const wss = new WebSocketServer({
+    noServer: true,
+    maxPayload: MAX_MESSAGE_BYTES,
+  });
   const rpcHandler = new RPCHandler(meshRouter);
 
   server.on("upgrade", (req, socket, head) => {
+    // A socket error before or after the upgrade (a peer that resets, say) is that connection's alone.
+    socket.on("error", reportSocketError);
     const decision = authorise(accessPolicy, requestOf(req));
     if (decision.kind !== "allow") {
       const status =
@@ -333,6 +380,8 @@ export async function createWebServer(options?: {
   });
 
   wss.on("connection", (ws) => {
+    // A socket error (a message over the size limit closes the socket with code 1009 and raises one) is handled here: an error event with no listener would end the process.
+    ws.on("error", reportSocketError);
     // RPCHandler.upgrade() wants a DOM-shaped WebSocket (addEventListener's overload set), which "ws"'s own type declarations don't structurally satisfy (its addEventListener options param is narrower than DOM's) -- .message()/.close() accept the looser { send } shape "ws" does satisfy, and are the documented manual equivalent to .upgrade().
     const context = { controller, publisher };
     ws.on("message", (data, isBinary) => {
@@ -341,10 +390,10 @@ export async function createWebServer(options?: {
       const bytes = raw instanceof ArrayBuffer ? Buffer.from(raw) : raw;
       // Buffer's .buffer is typed ArrayBufferLike (Buffer can wrap a SharedArrayBuffer); RPCHandler.message() wants the narrower Uint8Array<ArrayBuffer> -- a fresh Uint8Array.from() copy is always backed by a plain ArrayBuffer, satisfying that exactly.
       const payload = isBinary ? Uint8Array.from(bytes) : bytes.toString();
-      void rpcHandler.message(ws, payload, { context });
+      rpcHandler.message(ws, payload, { context }).catch(reportSocketError);
     });
     ws.on("close", () => {
-      void rpcHandler.close(ws);
+      rpcHandler.close(ws).catch(reportSocketError);
     });
   });
 
@@ -362,6 +411,13 @@ export async function createWebServer(options?: {
   return { server, controller, wss, publisher, host, accessToken };
 }
 
+/** Reports a failure of one WebSocket connection to stderr: it only ever affects that connection. */
+function reportSocketError(err: unknown): void {
+  process.stderr.write(
+    `agent-comms web UI: socket error: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+}
+
 function requestOf(req: http.IncomingMessage): {
   method: string;
   url: string;
@@ -454,12 +510,16 @@ export async function runWeb(userName: string, port?: number): Promise<void> {
     process.exit(0);
   };
 
-  process.on("SIGINT", () => {
-    void cleanup();
-  });
-  process.on("SIGTERM", () => {
-    void cleanup();
-  });
+  const shutDown = (): void => {
+    cleanup().catch((err: unknown) => {
+      process.stderr.write(
+        `agent-comms web UI: shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      process.exit(1);
+    });
+  };
+  process.on("SIGINT", shutDown);
+  process.on("SIGTERM", shutDown);
 }
 
 // ---------------------------------------------------------------------------
@@ -472,7 +532,14 @@ function handleRequest(
   controller: ChatController,
   webConsoleDist: string | undefined,
 ): void {
-  const url = new URL(req.url ?? "/", `http://localhost`);
+  let url: URL;
+  try {
+    url = new URL(req.url ?? "/", `http://localhost`);
+  } catch {
+    // A request target that names no URL (an empty authority, say) is a bad request, not a fault.
+    jsonError(res, "Bad request", HTTP_BAD_REQUEST);
+    return;
+  }
 
   // wire-mesh's web-console — an alternate, generic reference-client UI, served only when AGENT_COMMS_WEB_CONSOLE_DIST resolves to a real build.
   if (
@@ -550,8 +617,8 @@ function handleRequest(
     const filename = url.pathname.slice("/icons/".length);
     const assets = frontendOrUnavailable(res);
     if (assets === undefined) return;
-    const icon = assets.icons[filename];
-    if (icon) {
+    const icon = assets.icons.get(filename);
+    if (icon !== undefined) {
       res.writeHead(HTTP_OK, {
         "Content-Type": "image/svg+xml",
         "Cache-Control": "public, max-age=604800",
@@ -563,18 +630,16 @@ function handleRequest(
 
   // API routes
   if (url.pathname === "/api/agents" && req.method === "GET") {
-    void (async () => {
-      const agents = await controller.getAgents();
-      json(res, agents);
-    })();
+    serveRoute(req, res, async () => {
+      json(res, await controller.getAgents());
+    });
     return;
   }
 
   if (url.pathname === "/api/rooms" && req.method === "GET") {
-    void (async () => {
-      const rooms = await controller.getRooms();
-      json(res, rooms);
-    })();
+    serveRoute(req, res, async () => {
+      json(res, await controller.getRooms());
+    });
     return;
   }
 
@@ -583,7 +648,7 @@ function handleRequest(
     url.pathname.endsWith("/messages") &&
     req.method === "GET"
   ) {
-    void (async () => {
+    serveRoute(req, res, async () => {
       const roomId = url.pathname.split("/")[3];
       if (roomId === undefined || roomId === "") {
         jsonError(res, "Room ID required", HTTP_BAD_REQUEST);
@@ -595,7 +660,7 @@ function handleRequest(
         since,
       });
       json(res, messages);
-    })();
+    });
     return;
   }
 
@@ -613,7 +678,7 @@ function handleRequest(
   }
 
   if (url.pathname === "/api/mesh/trace" && req.method === "GET") {
-    void (async () => {
+    serveRoute(req, res, async () => {
       const target = url.searchParams.get("target");
       if (target === null || target === "") {
         jsonError(res, "target query parameter required", HTTP_BAD_REQUEST);
@@ -635,23 +700,31 @@ function handleRequest(
           meshErrorStatus(err, HTTP_BAD_REQUEST),
         );
       }
-    })();
+    });
     return;
   }
 
   if (url.pathname === "/api/action" && req.method === "POST") {
-    void (async () => {
-      const body = await readBody(req);
-      const parsed: unknown = JSON.parse(body);
-      if (typeof parsed !== "object" || parsed === null) {
-        jsonError(res, "Invalid JSON", HTTP_BAD_REQUEST);
-        return;
+    serveRoute(req, res, async () => {
+      const body = await readBoundedBody(req);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        throw invalidJsonBody();
+      }
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed)
+      ) {
+        throw invalidJsonBody();
       }
       const params = Object.fromEntries(Object.entries(parsed));
 
       const result = await executeAction(controller, params);
       json(res, result);
-    })();
+    });
     return;
   }
 
@@ -791,11 +864,6 @@ function jsonError(
   res.end(JSON.stringify({ error: message }));
 }
 
-/** Extracts a reportable message from whatever meshGraph()/meshTrace() threw -- a CommsError has a real message, anything else is reported generically rather than leaking an unexpected error shape to the client. */
-function meshErrorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : "Unknown error";
-}
-
 /** A transport that doesn't support mesh_graph/mesh_trace (CommsError code NOT_SUPPORTED, e.g. this bridge is running on FileStore rather than a real mesh) is a client-visible "this endpoint isn't available here" rather than a server fault. Any other error falls back to `otherwise` -- HTTP_BAD_REQUEST for mesh_trace, since its only other realistic failure is a malformed client-supplied target; HTTP_INTERNAL_SERVER_ERROR for mesh_graph, which takes no client input at all. */
 function meshErrorStatus(err: unknown, otherwise: number): number {
   if (err instanceof CommsError && err.code === "NOT_SUPPORTED") {
@@ -803,16 +871,3 @@ function meshErrorStatus(err: unknown, otherwise: number): number {
   }
   return otherwise;
 }
-
-async function readBody(req: http.IncomingMessage): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    req.on("data", (chunk: Buffer) => {
-      chunks.push(chunk);
-    });
-    req.on("end", () => {
-      resolve(Buffer.concat(chunks).toString());
-    });
-    req.on("error", reject);
-  });
-}

package/src/bridges/user/web/web-access.ts

@@ -32,6 +32,7 @@ const ACCESS_TOKEN_BYTES = 32;
 /** The port a Host header with no explicit port names (HTTP). */
 const HTTP_DEFAULT_PORT = 80;
 
+const HTTP_BAD_REQUEST = 400;
 const HTTP_UNAUTHORIZED = 401;
 const HTTP_FORBIDDEN = 403;
 const HTTP_FOUND = 302;
@@ -360,7 +361,10 @@ export function authorise(
     return { kind: "allow" };
   }
   if (request.method === "GET") {
-    const url = new URL(request.url, "http://placeholder");
+    const url = parseRequestUrl(request.url);
+    if (url === undefined) {
+      return { kind: "deny", status: HTTP_BAD_REQUEST, message: "Bad request" };
+    }
     const offered = url.searchParams.get(ACCESS_QUERY_PARAM);
     if (offered !== null && tokensMatch(offered, token)) {
       url.searchParams.delete(ACCESS_QUERY_PARAM);
@@ -375,6 +379,15 @@ export function authorise(
   return { kind: "deny", status: HTTP_UNAUTHORIZED, message: "Unauthorized" };
 }
 
+/** The URL a request line names, or undefined when it names none: a request target that cannot be parsed is refused, never thrown out of the request listener, which would end the process. */
+function parseRequestUrl(target: string): URL | undefined {
+  try {
+    return new URL(target, "http://placeholder");
+  } catch {
+    return undefined;
+  }
+}
+
 /** The URLs an operator can open on the LAN, each carrying the token for the one-time exchange. A wildcard bind lists every external, non-link-local address of this machine that the bind family can reach (IPv6 bracketed, and only under `::`, since `0.0.0.0` accepts IPv4 alone); a specific bind lists that address. The list is empty when a wildcard bind finds no such address. */
 export function accessUrls(
   policy: Readonly<AccessPolicy> & { readonly token: string },

package/src/bridges/user/web/web-assets.ts

@@ -21,7 +21,8 @@ export interface FrontendAssets {
   meshWorkerJs: string;
   swJs: string;
   manifestJson: string;
-  icons: Readonly<Record<string, Buffer>>;
+  /** The PWA icons by file name. A map, not an object: the name comes from the request path, and an object would also answer a name that is a member of every object (`constructor`, `toString`). */
+  icons: ReadonlyMap<string, Buffer>;
 }
 
 /** The frontend build output is absent from the directory it should be in. */
@@ -56,9 +57,12 @@ export function loadFrontendAssets(assetDir: string): FrontendAssets {
   const indexHtml = readIfPresent(path.join(assetDir, "index.html"));
   if (indexHtml === undefined) throw new FrontendNotBuiltError(assetDir);
 
-  const icons: Record<string, Buffer> = {};
+  const icons = new Map<string, Buffer>();
   for (const filename of ICON_FILENAMES) {
-    icons[filename] = fs.readFileSync(path.join(assetDir, "icons", filename));
+    icons.set(
+      filename,
+      fs.readFileSync(path.join(assetDir, "icons", filename)),
+    );
   }
 
   return {

package/src/bridges/user/web/web-console-static.ts

@@ -14,21 +14,22 @@ export const WEB_CONSOLE_MOUNT = "/web-console";
 const HTTP_OK = 200;
 const HTTP_NOT_FOUND = 404;
 
-const CONTENT_TYPES: Record<string, string> = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "application/javascript; charset=utf-8",
-  ".mjs": "application/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".txt": "text/plain; charset=utf-8",
-  ".wasm": "application/wasm",
-};
+/** Content type by extension. A map: the extension comes from the requested name, and an object would also answer a name that is a member of every object. */
+const CONTENT_TYPES: ReadonlyMap<string, string> = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".js", "application/javascript; charset=utf-8"],
+  [".mjs", "application/javascript; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".json", "application/json; charset=utf-8"],
+  [".map", "application/json; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".png", "image/png"],
+  [".ico", "image/x-icon"],
+  [".woff", "font/woff"],
+  [".woff2", "font/woff2"],
+  [".txt", "text/plain; charset=utf-8"],
+  [".wasm", "application/wasm"],
+]);
 
 const DEFAULT_CONTENT_TYPE = "application/octet-stream";
 
@@ -45,6 +46,20 @@ export function resolveWebConsoleDist(): string | undefined {
   return dist;
 }
 
+/**
+ * The real path of `file`, when it is a regular file that lies inside `dist` once every symbolic link in both paths has been followed, and undefined for anything else: a missing file, a directory, a name that cannot be resolved, or a link, anywhere along the path, that leads outside the directory. The name is checked after resolution, never before, so a link inside the directory cannot be used to read a file outside it.
+ */
+function realFileWithin(dist: string, file: string): string | undefined {
+  try {
+    const realDist = fs.realpathSync(dist);
+    const realFile = fs.realpathSync(file);
+    const inside = realFile.startsWith(`${realDist}${path.sep}`);
+    return inside && fs.statSync(realFile).isFile() ? realFile : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Serves a request under the web-console mount from a resolved dist directory.
  *
@@ -68,23 +83,16 @@ export function serveWebConsole(
 
   const resolvedDist = path.resolve(distDir);
   const resolvedFile = path.resolve(resolvedDist, relative);
-  const withinDist =
-    resolvedFile === resolvedDist ||
-    resolvedFile.startsWith(`${resolvedDist}${path.sep}`);
-
-  if (
-    !withinDist ||
-    !fs.existsSync(resolvedFile) ||
-    !fs.statSync(resolvedFile).isFile()
-  ) {
+  const servable = realFileWithin(resolvedDist, resolvedFile);
+  if (servable === undefined) {
     res.writeHead(HTTP_NOT_FOUND);
     res.end("Not found");
     return true;
   }
 
   const contentType =
-    CONTENT_TYPES[path.extname(resolvedFile)] ?? DEFAULT_CONTENT_TYPE;
+    CONTENT_TYPES.get(path.extname(servable)) ?? DEFAULT_CONTENT_TYPE;
   res.writeHead(HTTP_OK, { "Content-Type": contentType });
-  res.end(fs.readFileSync(resolvedFile));
+  res.end(fs.readFileSync(servable));
   return true;
 }

package/src/core/coordinator-role.ts

@@ -3,12 +3,15 @@
  *
  * Claims travel as wire-mesh session frames (MeshTransport.broadcastCoordinatorClaim/sendCoordinatorClaim), and only over sessions to peers on this machine, because both duties the role assigns are facts about one machine: a PID probe can only see local processes and the cc-peer front can only reach local Claude Code sessions.
  *
- * When a claim is made: a store claims only when it knows of no incumbent and is the first on the machine as far as it can tell. A store that bound the well-known port with no first-contact presence configured can meet other stores only through that port, so it claims at once; one that may be reachable through first contact (it bound the port, or could neither join nor bind it) first waits one claim wait for an incumbent's announcement, so a store arriving at an existing mesh never takes the role at an equal term before the holder's claim reaches it. Both ends of every machine-local session announce the incumbent they know as the session is enrolled. When the incumbent departs, the lowest device-id among the peers this side has a machine-local session to claims at once at a raised term, and every other survivor claims too if, one claim wait later, the claim it accepts still names a holder it has no session to, which covers a lowest-id peer that is itself gone or was never reachable. The same wait follows accepting a claim whose holder this side has no session to, so a claim naming a device that never joined cannot pin the role vacant.
+ * When a claim is made: a store claims only when it knows of no incumbent and is the first on the machine as far as it can tell. A store that bound the well-known port with no first-contact presence configured can meet other stores only through that port, so it claims at once; one that may be reachable through first contact (it bound the port, or could neither join nor bind it) first waits one claim wait for an incumbent's announcement, so a store arriving at an existing mesh never takes the role at an equal term before the holder's claim reaches it. Both ends of every machine-local session announce the incumbent they know as the session is enrolled. When the incumbent departs, the lowest device-id among the peers this side has a machine-local session to claims at once at a raised term, and every other survivor claims too if, one claim wait later, the claim it accepts still names a holder it has no session to, which covers a lowest-id peer that is itself gone or was never reachable. A claim that is accepted names a holder that is here when it is accepted, so the wait after an accepted claim never starts: the claim waits are the one after a departure and the one at start-up.
+ *
+ * Whose claims count: claims are accepted from the peers this machine already trusts with a machine-local session, and this module does not authenticate them further. A claim is evaluated only when its holder is this side, the peer that sent it (the session's authenticated device-id, never a field of the frame), or a peer this side has a machine-local session to. A claim gossiped onward by a peer other than its holder is therefore still accepted wherever the holder is reachable, which is every peer of a fully connected machine. Any other claim waits until its holder's session is enrolled and is dropped after one claim wait, and is not evaluated at all when, by then, its sender has no machine-local session. Waiting claims are bounded per sender: each machine-local peer has at most PENDING_CLAIMS_PER_SENDER of them, at most one per holder, kept in the election's own order (higher term first, an equal term by lowest holder id), and a claim whose term no later claim could supersede is not kept.
  */
 
 import {
   CoordinatorElection,
   compareDeviceIds,
+  isSupersedableTerm,
   type CoordinatorClaim,
 } from "wire-mesh-core/domain/coordinator-election";
 import {
@@ -43,6 +46,14 @@ export interface CoordinatorRoleDeps {
   onError: (error: unknown) => void;
 }
 
+/** Orders waiting claims as the election ranks claims: a higher term first, and at an equal term the lower holder id, compared as the election compares it. */
+function rankedFirst(left: PendingClaim, right: PendingClaim): number {
+  if (left.frame.term !== right.frame.term) {
+    return right.frame.term - left.frame.term;
+  }
+  return compareDeviceIds(left.frame.coordinator, right.frame.coordinator);
+}
+
 function sameClaim(
   frame: Readonly<CoordinatorFrame>,
   claim: Readonly<CoordinatorClaim>,
@@ -53,6 +64,17 @@ function sameClaim(
   );
 }
 
+/** How many claims one machine-local peer may have waiting for their holders to enrol, one per holder. */
+const PENDING_CLAIMS_PER_SENDER = 4;
+
+/** A claim set aside because its holder is neither this side, its sender nor a peer with a session here, with who sent it and the timer that drops it after one claim wait. */
+interface PendingClaim {
+  readonly handle: Readonly<ConnectionHandle>;
+  readonly frame: Readonly<CoordinatorFrame>;
+  readonly holder: string;
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
 export class CoordinatorRole {
   /** Built on first use rather than at construction, because MeshStore's peerId is assigned after its constructor runs (every bridge sets it to the identity's device-id). */
   private electionInstance: CoordinatorElection | undefined;
@@ -67,6 +89,8 @@ export class CoordinatorRole {
   private takeoverStreak = 0;
   /** The claim, as `term:holder`, each peer was last answered with. A peer whose view lags keeps sending the claims it knows, and answering each one with the same incumbent only multiplies the traffic: the answer is repeated only when the incumbent changes or the peer's session is enrolled afresh, since the earlier answer may have been lost with the old session. */
   private readonly answered = new Map<string, string>();
+  /** The claims set aside, by the device-id of the session that sent each, best first in the election's own order. */
+  private readonly pending = new Map<string, PendingClaim[]>();
 
   constructor(private readonly deps: Readonly<CoordinatorRoleDeps>) {}
 
@@ -104,23 +128,42 @@ export class CoordinatorRole {
   /** Tells a peer whose machine-local session was just enrolled which claim this side accepts, so a joiner learns the incumbent instead of claiming over it. A no-op while this side knows of none. */
   async announceTo(handle: Readonly<ConnectionHandle>): Promise<void> {
     this.answered.delete(handle.id);
-    const frame = this.electionInstance?.announceCurrent();
-    if (frame === undefined) return;
-    await this.deps.requireTransport().sendCoordinatorClaim(handle, frame);
+    // Taken before the first await, so a claim released here is neither dropped by its timer nor taken twice while the announcement is being sent.
+    const released = this.takePendingFor(handle.id);
+    try {
+      const frame = this.electionInstance?.announceCurrent();
+      if (frame !== undefined) {
+        await this.deps.requireTransport().sendCoordinatorClaim(handle, frame);
+      }
+    } catch (error) {
+      this.deps.onError(error);
+    }
+    // The session just enrolled may be the holder claims were set aside for. One claim failing to evaluate never costs the others theirs.
+    for (const waiting of released) {
+      try {
+        await this.handleClaim(waiting.handle, waiting.frame);
+      } catch (error) {
+        this.deps.onError(error);
+      }
+    }
   }
 
-  /** Evaluates a claim a peer gossiped. An accepted claim is gossiped on to every peer so the supersession reaches peers the sender is not connected to, and when it names a holder this side has no session to, this side waits one claim wait for that holder to appear before claiming over it; a stale or tiebreak-losing claim is answered with the incumbent so its sender converges, and a claim whose term no later claim could supersede is dropped unevaluated, neither gossiped nor answered. Receiving the incumbent itself is neither, and is dropped without a reply, which is what stops two peers that agree from echoing it forever. */
+  /** Evaluates a claim a peer gossiped. An accepted claim is gossiped on to every peer so the supersession reaches peers the sender is not connected to, a claim whose holder is not here waits for that holder to enrol and is dropped after one claim wait; a stale or tiebreak-losing claim is answered with the incumbent so its sender converges, and a claim whose term no later claim could supersede is dropped unevaluated, neither gossiped nor answered. Receiving the incumbent itself is neither, and is dropped without a reply, which is what stops two peers that agree from echoing it forever. */
   async handleClaim(
     handle: Readonly<ConnectionHandle>,
     frame: Readonly<CoordinatorFrame>,
   ): Promise<void> {
     if (this.stopped) return;
+    if (!this.holderIsHere(handle, frame)) {
+      this.setAside(handle, frame);
+      return;
+    }
     const result = this.election.evaluate(frame);
     if (result.outcome === "accepted") {
       this.answered.clear();
       this.cancelClaimWait();
-      if (this.incumbentUnreachable()) this.startClaimWait();
-      else this.takeoverStreak = 0;
+      // The holder of an accepted claim is here, so there is no incumbent to wait out.
+      this.takeoverStreak = 0;
       await this.deps.requireTransport().broadcastCoordinatorClaim(frame);
     } else if (
       result.outcome === "retained" &&
@@ -155,9 +198,85 @@ export class CoordinatorRole {
   async stop(): Promise<void> {
     this.stopped = true;
     this.cancelClaimWait();
+    this.dropAllPending();
     await this.syncHolding();
   }
 
+  /** Whether the holder a claim names is this side, the peer that sent it, or a peer this side has a machine-local session to. The sender is the handle's authenticated device-id, so a peer cannot name itself as someone else. */
+  private holderIsHere(
+    handle: Readonly<ConnectionHandle>,
+    frame: Readonly<CoordinatorFrame>,
+  ): boolean {
+    const holder = deviceIdToHex(frame.coordinator);
+    return (
+      holder === this.deps.getPeerId() ||
+      holder === handle.id ||
+      this.deps.requireTransport().electionPeerIds().has(holder)
+    );
+  }
+
+  /** Keeps a claim whose holder is not here until that holder's session is enrolled, and drops it after one claim wait. The sender keeps at most PENDING_CLAIMS_PER_SENDER of them, one per holder, so a new claim for a holder already waiting replaces it only at a higher term, and when the sender is over its share the claim the election ranks last goes. */
+  private setAside(
+    handle: Readonly<ConnectionHandle>,
+    frame: Readonly<CoordinatorFrame>,
+  ): void {
+    // A claim whose term no later claim could supersede is dropped by the election unevaluated, wherever its holder is, so it never takes a place here.
+    if (!isSupersedableTerm(frame.term)) return;
+    const holder = deviceIdToHex(frame.coordinator);
+    const mine = this.pending.get(handle.id) ?? [];
+    const same = mine.find((entry) => entry.holder === holder);
+    if (same !== undefined) {
+      if (same.frame.term >= frame.term) return;
+      this.forget(handle.id, same);
+    }
+    const timer = setTimeout(() => {
+      const waiting = (this.pending.get(handle.id) ?? []).find(
+        (entry) => entry.holder === holder && entry.frame === frame,
+      );
+      if (waiting !== undefined) this.forget(handle.id, waiting);
+    }, this.deps.claimWaitMs);
+    // Never what keeps a process alive: a store shutting down stops the role anyway.
+    timer.unref();
+    const kept = [
+      ...(this.pending.get(handle.id) ?? []),
+      { handle, frame, holder, timer },
+    ].sort(rankedFirst);
+    this.pending.set(handle.id, kept);
+    for (const extra of kept.slice(PENDING_CLAIMS_PER_SENDER)) {
+      this.forget(handle.id, extra);
+    }
+  }
+
+  /** Removes one waiting claim and its timer. */
+  private forget(sender: string, entry: PendingClaim): void {
+    clearTimeout(entry.timer);
+    const rest = (this.pending.get(sender) ?? []).filter(
+      (other) => other !== entry,
+    );
+    if (rest.length === 0) this.pending.delete(sender);
+    else this.pending.set(sender, rest);
+  }
+
+  /** Takes every waiting claim that names `holder`, best first, except those whose sender no longer has a machine-local session here. */
+  private takePendingFor(holder: string): PendingClaim[] {
+    const senders = this.deps.requireTransport().electionPeerIds();
+    const taken: PendingClaim[] = [];
+    for (const [sender, entries] of [...this.pending]) {
+      for (const entry of entries) {
+        if (entry.holder !== holder) continue;
+        this.forget(sender, entry);
+        if (senders.has(sender)) taken.push(entry);
+      }
+    }
+    return taken.sort(rankedFirst);
+  }
+
+  private dropAllPending(): void {
+    for (const [sender, entries] of [...this.pending]) {
+      for (const entry of entries) this.forget(sender, entry);
+    }
+  }
+
   private isLowestSurvivor(departedPeerId: string): boolean {
     const selfId = this.deps.getPeerId();
     const self = deviceIdFromHex(selfId);