agent-comms 8.15.8 → 8.15.10

package/src/core/handshake.ts

@@ -0,0 +1,354 @@
+/**
+ * Protocol handshake — version negotiation for the mesh wire format, fixing #31: a mixed fleet of old and new peers negotiates down to what both actually support (or refuses loudly) instead of one side silently misinterpreting the other's state sync.
+ *
+ * The frame is wire-mesh's handshake-frame (spec/handshake.cddl in ExaDev/wire-mesh), CBOR-encoded, negotiated by wire-mesh-core's `negotiate()` — the same mechanism every wire-mesh consumer speaks. The `version` field carries agent-comms' own wire-format version (not wire-mesh's protocol version): version 1 is the current format, the one with entity revision fields (#29) and deliveryQueues (#30). A peer that never sends a handshake frame is a legacy peer (version 0, unversioned) and the connection proceeds exactly as before — mixed-fleet tolerance during rollout, the scenario #31 describes.
+ *
+ * Wire order: a client sends its handshake frame as the very first bytes on a connection and does not wait — the rest of its traffic is ordinary newline-delimited JSON. A server sends its frame only in reply to a received one, so legacy clients never see binary bytes at all. The one unavoidable cross-build artefact is a legacy server receiving a new client's CBOR frame into its line buffer, where it lands without a newline and is flushed as a single malformed (skipped) line when the first JSON message arrives — the pre-existing malformed-line behaviour.
+ */
+
+import {
+  decodeSequence,
+  encode as cborEncode,
+  cdeDecodeOptions,
+  cdeEncodeOptions,
+} from "cbor2";
+import {
+  negotiate,
+  type NegotiationResult,
+} from "wire-mesh-core/domain/handshake";
+
+/** agent-comms' own wire-format version. 1 = the current format (entity revision fields, deliveryQueues). */
+export const MESH_PROTOCOL_VERSION = 1;
+
+/**
+ * The capability domain this mesh negotiates under — a wire-mesh namespaced-domain-id (registrant-owned, no allocator): ExaDev's agent-comms mesh semantics. Peers that do not share it are not this protocol.
+ */
+export const AGENT_COMMS_DOMAIN = "dev.exadev.agent-comms/mesh";
+
+/** Handshake frames are tiny; anything larger than this is not a frame, it is garbage. */
+const MAX_HANDSHAKE_BYTES = 1024;
+
+/** CBOR map head first byte, inclusive. */
+const CBOR_MAP_HEAD_MIN = 0xa0;
+/** CBOR map head last byte, inclusive. */
+const CBOR_MAP_HEAD_MAX = 0xbf;
+
+/** CBOR map head byte range (0xa0-0xbf); JSON always starts with the byte 0x7b. */
+function isCborMapHead(byte: number): boolean {
+  return byte >= CBOR_MAP_HEAD_MIN && byte <= CBOR_MAP_HEAD_MAX;
+}
+
+const JSON_OBJECT_START = 0x7b; // '{'
+const HEX_RADIX = 16;
+
+interface HandshakeShape {
+  type: "handshake";
+  version: number;
+  domains: string[];
+}
+
+/**
+ * Narrow structural check for a received handshake frame.
+ *
+ * Deliberately NOT the generated handshakeFrameSchema: its domain union's regexp branches are emitted double-escaped by cddl.js (ExaDev/cddl.js#10), so schema-validating any namespaced domain — including ours — rejects valid frames until that fix lands. This guard checks exactly the shape `negotiate()` consumes.
+ */
+function isHandshakeShape(value: unknown): value is HandshakeShape {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("type" in value) || value.type !== "handshake") return false;
+  if (!("version" in value) || typeof value.version !== "number") return false;
+  if (!("domains" in value) || !Array.isArray(value.domains)) return false;
+  return value.domains.every((d) => typeof d === "string");
+}
+
+function localFrame(): HandshakeShape {
+  return {
+    type: "handshake",
+    version: MESH_PROTOCOL_VERSION,
+    domains: [AGENT_COMMS_DOMAIN],
+  };
+}
+
+/** The handshake frame this build sends, CBOR-encoded (canonical), ready to write as a connection's first bytes. */
+export function encodeHandshakeFrame(): Uint8Array {
+  return cborEncode(localFrame(), cdeEncodeOptions);
+}
+
+/** Negotiates this build's protocol against a received handshake frame — core's negotiation over agent-comms' versions. */
+export function negotiateMeshProtocol(
+  remote: HandshakeShape,
+): NegotiationResult {
+  return negotiate(localFrame(), remote);
+}
+
+export type HandshakeOutcome =
+  | { kind: "pending" }
+  | { kind: "legacy"; rest: Buffer; reason: "json-first-byte" }
+  | { kind: "negotiated"; rest: Buffer; result: NegotiationResult }
+  | { kind: "refused"; reason: string };
+
+/**
+ * Per-connection gate fed the incoming byte stream. Consumes the (optional) leading handshake frame and classifies the connection: negotiated (a version was agreed — for a server, the caller replies with `encodeHandshakeFrame()`), legacy (first byte was the JSON object-start byte — a pre-handshake peer, proceed exactly as before), or refused (a handshake we cannot speak: destroy the connection loudly rather than desync — the #31 enforcement point). After the first classification every subsequent feed passes the bytes through unchanged.
+ */
+export class ConnectionHandshake {
+  private decided: "legacy" | "negotiated" | null = null;
+  private readonly pending: Buffer[] = [];
+  private pendingLength = 0;
+
+  constructor(private readonly role: "client" | "server") {}
+
+  feed(data: Buffer): HandshakeOutcome {
+    if (this.decided !== null) {
+      if (this.decided === "negotiated") {
+        return {
+          kind: "negotiated",
+          rest: data,
+          result: this.negotiatedResult(),
+        };
+      }
+      return { kind: "legacy", rest: data, reason: "json-first-byte" };
+    }
+    // The connection's very first byte only classifies legacy vs. CBOR. A later chunk (the second half of a split frame) starts mid-item, and its own leading byte is not a fresh frame head -- re-checking it against isCborMapHead on every chunk was the bug a reassembly test caught.
+    if (this.pending.length === 0) {
+      const first = data[0];
+      if (first === undefined) {
+        return { kind: "pending" };
+      }
+      if (first === JSON_OBJECT_START) {
+        this.decided = "legacy";
+        return { kind: "legacy", rest: data, reason: "json-first-byte" };
+      }
+      if (!isCborMapHead(first)) {
+        return {
+          kind: "refused",
+          reason: `unexpected first byte 0x${first.toString(HEX_RADIX)} — not a handshake frame or JSON message`,
+        };
+      }
+    }
+    // A CBOR item: accumulate until it decodes (frames are tiny; TCP may split them).
+    this.pending.push(data);
+    this.pendingLength += data.length;
+    if (this.pendingLength > MAX_HANDSHAKE_BYTES) {
+      return {
+        kind: "refused",
+        reason: `handshake frame exceeds ${String(MAX_HANDSHAKE_BYTES)} bytes`,
+      };
+    }
+    const joined = Buffer.concat(this.pending);
+    let value: unknown;
+    try {
+      // decodeSequence yields lazily: its first item resolves as soon as enough bytes exist for it, tolerating (rather than choking on) non-CBOR bytes that follow in the same buffer -- the ordinary case once a client's JSON traffic lands in the same TCP read as the frame. Plain decode() throws "Extra data in input" the instant anything trails the item, which would misclassify every such read as still-pending forever.
+      const item = decodeSequence(joined, cdeDecodeOptions).next();
+      if (item.done !== false) {
+        return { kind: "pending" };
+      }
+      value = item.value;
+    } catch {
+      return { kind: "pending" };
+    }
+    if (!isHandshakeShape(value)) {
+      return {
+        kind: "refused",
+        reason: "CBOR item on a new connection is not a handshake frame",
+      };
+    }
+    // The frame consumed only its own bytes; anything after it is the stream's JSON traffic.
+    const encoded = cborEncode(value, cdeEncodeOptions);
+    const rest = joined.subarray(encoded.length);
+    const result = negotiateMeshProtocol(value);
+    if (!result.ok) {
+      return {
+        kind: "refused",
+        reason: `handshake refused (${this.role}): peer protocol version ${String(value.version)}, no shared domain`,
+      };
+    }
+    this.decided = "negotiated";
+    this.lastResult = result;
+    return { kind: "negotiated", rest, result };
+  }
+
+  private lastResult: NegotiationResult | undefined;
+
+  private negotiatedResult(): NegotiationResult {
+    if (this.lastResult === undefined) {
+      throw new Error("negotiated connection has no negotiation result");
+    }
+    return this.lastResult;
+  }
+
+  /** True once this connection was classified (legacy or negotiated) — further feed() calls pass through. */
+  get settled(): boolean {
+    return this.decided !== null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Socket attachment (TCP/TLS) — one helper, every connection site
+// ---------------------------------------------------------------------------
+
+/** The slice of the Node socket surface the handshake needs — satisfied by net.Socket and tls.TLSSocket alike. */
+export interface HandshakeSocket {
+  write: (data: Uint8Array | string) => unknown;
+  destroy: () => void;
+  on: (event: "data", listener: (data: Buffer) => void) => unknown;
+}
+
+/**
+ * Wires a connection's handshake: a client sends its frame immediately (and
+ * never waits — the rest of its traffic is JSON either way); a server sends
+ * its frame only in reply to a received one, so legacy clients never see
+ * binary bytes. Payload bytes after classification (and everything on a
+ * legacy connection) flow to `onPayload` unchanged. A refused handshake
+ * destroys the connection and reports the reason — the loud #31 refusal
+ * replacing silent desync.
+ */
+export function attachSocketHandshake(
+  socket: Readonly<HandshakeSocket>,
+  role: "client" | "server",
+  onPayload: (data: Buffer) => void,
+  onError?: (error: Error) => void,
+): void {
+  const gate = new ConnectionHandshake(role);
+  if (role === "client") {
+    socket.write(encodeHandshakeFrame());
+  }
+  // A settled connection reports "negotiated" (or "legacy") on every subsequent feed, not just the classifying one -- feed() has no separate signal for "just decided" versus "already decided, passing through". Without this guard the server branch below wrote a fresh reply frame on every single data event for the rest of the connection's life, corrupting the peer's JSON-line buffer with stray CBOR bytes mid-stream.
+  let serverReplySent = false;
+  socket.on("data", (data: Buffer) => {
+    const outcome = gate.feed(data);
+    switch (outcome.kind) {
+      case "pending":
+        return;
+      case "legacy":
+        onPayload(outcome.rest);
+        return;
+      case "negotiated":
+        if (role === "server" && !serverReplySent) {
+          // Reply only once, on evidence the peer speaks the handshake — a legacy client must never receive binary bytes.
+          serverReplySent = true;
+          socket.write(encodeHandshakeFrame());
+        }
+        onPayload(outcome.rest);
+        return;
+      case "refused":
+        onError?.(new Error(outcome.reason));
+        socket.destroy();
+        return;
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket attachment — binary first message is the handshake
+// ---------------------------------------------------------------------------
+
+/**
+ * Gate for a WebSocket connection, where every message is already framed: a
+ * binary first message is the peer's handshake frame (reply in kind via
+ * `sendBinary` when serving), a text first message is a legacy peer's JSON.
+ * Binary messages after the first, or a non-handshake binary first message,
+ * are refused.
+ */
+export class WsHandshakeGate {
+  private settled = false;
+
+  constructor(
+    private readonly role: "client" | "server",
+    private readonly sendBinary: (data: Uint8Array) => void,
+  ) {}
+
+  /**
+   * Classifies one incoming message. `isBinary` is the WS library's own frame-type flag (`ws`'s `message` event passes `(data, isBinary)`), not `typeof raw === "string"`: in Node, `ws` always delivers `data` as a Buffer regardless of whether the frame was sent as text or binary, so a `typeof` check can never see a text frame as a string here and would misclassify every legacy JSON message as an unexpected second handshake. `"payload"` means deliver it to the existing JSON message path (text only); `"consumed"` means it was the handshake and nothing downstream should see it; a throw is the refused case — the caller closes the socket.
+   */
+  feed(raw: unknown, isBinary: boolean): "payload" | "consumed" {
+    if (this.settled) {
+      if (!isBinary) return "payload";
+      throw new Error(
+        "binary message after connection start on a WebSocket mesh connection",
+      );
+    }
+    if (!isBinary) {
+      this.settled = true;
+      return "payload";
+    }
+    const bytes =
+      raw instanceof Buffer
+        ? raw
+        : raw instanceof ArrayBuffer
+          ? new Uint8Array(raw)
+          : ArrayBuffer.isView(raw)
+            ? new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
+            : undefined;
+    if (bytes === undefined) {
+      throw new Error("unsupported WebSocket message type");
+    }
+    const gate = new ConnectionHandshake(this.role);
+    const outcome = gate.feed(Buffer.from(bytes));
+    if (outcome.kind === "pending") {
+      throw new Error(
+        "handshake frame did not arrive as one WebSocket message",
+      );
+    }
+    if (outcome.kind === "refused") {
+      throw new Error(outcome.reason);
+    }
+    if (outcome.kind === "legacy") {
+      // A text-shaped payload cannot reach here (handled above); binary that
+      // is not a handshake frame is a refusal in ConnectionHandshake.
+      throw new Error(
+        "unexpected legacy classification for a binary WebSocket message",
+      );
+    }
+    if (this.role === "server") {
+      this.sendBinary(encodeHandshakeFrame());
+    }
+    if (outcome.rest.length > 0) {
+      throw new Error(
+        "handshake frame carried trailing bytes in a WebSocket message",
+      );
+    }
+    this.settled = true;
+    return "consumed";
+  }
+}
+
+/** The slice of the WebSocket surface the handshake needs. */
+export interface HandshakeWs {
+  send: (data: string | Uint8Array) => unknown;
+  terminate: () => void;
+  // isBinary is the `ws` library's own frame-type flag (its `message` event always passes it as the second argument) -- the only reliable way to tell a text frame from a binary one, since `data` itself arrives as a Buffer in Node either way.
+  on: (
+    event: "message",
+    listener: (raw: unknown, isBinary: boolean) => void,
+  ) => unknown;
+}
+
+/**
+ * Wires a WebSocket connection's handshake: a client sends its frame as a
+ * binary message immediately (before any JSON); a server replies in kind only
+ * on receiving one, so legacy clients never see a binary message. Text
+ * messages flow to `onText` unchanged; a refused handshake terminates the
+ * connection and reports the reason.
+ */
+export function attachWsHandshake(
+  ws: Readonly<HandshakeWs>,
+  role: "client" | "server",
+  onText: (raw: unknown) => void,
+  onError?: (error: Error) => void,
+): void {
+  const gate = new WsHandshakeGate(role, (data) => {
+    ws.send(data);
+  });
+  if (role === "client") {
+    ws.send(encodeHandshakeFrame());
+  }
+  ws.on("message", (raw: unknown, isBinary: boolean) => {
+    try {
+      if (gate.feed(raw, isBinary) === "payload") {
+        onText(raw);
+      }
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(String(error)));
+      ws.terminate();
+    }
+  });
+}

package/src/core/hub-forwarding.ts

@@ -0,0 +1,24 @@
+/**
+ * hub-forwarding -- local-to-remote routing, split from wire-mesh-transport.ts under the repo's max-lines cap: falls a room-domain request back through the hub's own relay-connect/relay-data pairing when its target isn't a local peer session.
+ */
+
+import type {
+  CapabilityScope,
+  CapabilityToken,
+  ManageCommand,
+} from "wire-mesh-core/generated/protocol";
+import type { ManageOutcome } from "wire-mesh-core/domain/mesh-session";
+import type { HubSession } from "./hub-session.js";
+
+/** Routes a room-domain request through the hub's relay-connect/relay-data pairing when memberId isn't a local peer session -- WireMeshTransport.sendRoomRequest's own fallback, since the member may be a remote agent reachable only through the hub this store is connected to (agent-comms#155's local-to-remote leg). WireMeshTransport.sendRoomRequest itself gates memberId against the gateway trust boundary (agent-comms#156) before ever calling this, so by the time this runs memberId is already known-trusted -- this function stays focused on the hub-connectivity outcome alone. Resolves the same not_connected outcome sendRoomRequest already returned before the hub existed at all when this side holds no hub session, which is a store that has no agent yet, has a ghost agent, or whose machine trusts nobody. */
+export async function routeRoomRequestViaHub(options: {
+  hub: Readonly<Pick<HubSession, "isConnected" | "sendRoomRequest">>;
+  memberId: string;
+  command: ManageCommand;
+  scope: Readonly<CapabilityScope>;
+  token?: CapabilityToken | undefined;
+}): Promise<ManageOutcome> {
+  const { hub, memberId, command, scope, token } = options;
+  if (!hub.isConnected) return { result: "error", code: "not_connected" };
+  return hub.sendRoomRequest(memberId, command, scope, token);
+}

package/src/core/hub-link.ts

@@ -0,0 +1,176 @@
+/**
+ * HubLink keeps one store's own session on the relay hub alive while the store should have one: it dials in the background, waits for the session to end, and dials again after a delay that doubles up to a ceiling while the hub stays unreachable. Every store owns one (agent-comms#293), because reachability from another machine has to belong to the device itself and not to whichever store on the machine happens to hold the local coordinator role.
+ *
+ * The store decides through shouldConnect whether it wants a session at all, and a change of mind, made in this process or by another one editing the shared trust file, is picked up within a poll interval, or at once through reconsider(). A store with nothing to say to another machine (nothing trusted, no agent, or a ghost agent) holds no session, so it puts nothing on the hub, not even its device id.
+ *
+ * Which hub is dialled is chosen afresh before every dial (agent-comms#342): the hub is a set of relays, ranked by relay-selection.ts, with the configured public hub as the fallback. A dial that fails, or a session the relay drops, excludes that URL from selection for the redial ceiling (the cadence an unreachable hub is retried at anyway), so a relay that has gone falls through to the next choice instead of being redialled on every pass; and a session held over one relay is moved as soon as selection prefers another.
+ *
+ * The dial never blocks the caller: a bridge starting up offline must not wait out a connect timeout before it can serve its tools, and a hub that is down or restarting is an ordinary, recoverable state. Failures reach onError and the loop carries on.
+ */
+
+import type { HubSession } from "./hub-session.js";
+
+/** Delay before the first redial after a failed dial or a lost session. */
+export const HUB_RECONNECT_INITIAL_DELAY_MS = 1000;
+
+/** Ceiling the redial delay doubles up to while the hub stays unreachable, so an outage is retried about once a minute rather than backing off without bound. */
+export const HUB_RECONNECT_MAX_DELAY_MS = 60_000;
+
+/** How often a link re-evaluates shouldConnect while it has nothing to react to: a store that wants no session notices it now wants one, and a store holding one notices it no longer should, without anyone calling reconsider(). Bounds how long a trust change made by another process on the machine takes to show. */
+export const HUB_LINK_POLL_INTERVAL_MS = 5000;
+
+/** Factor the redial delay grows by after each failed dial. */
+const RECONNECT_DELAY_GROWTH_FACTOR = 2;
+
+/** The parts of a HubSession a HubLink drives. */
+export type HubLinkSession = Pick<
+  HubSession,
+  "connect" | "disconnect" | "isConnected" | "whenDisconnected"
+>;
+
+export interface HubLinkOptions {
+  hub: Readonly<HubLinkSession>;
+  /** The hub to hold a session on next, given the URLs whose last dial or session failed. Read before every dial and every poll interval while connected. */
+  selectUrl: (excluded: ReadonlySet<string>) => string;
+  /** Whether the store wants a hub session right now. Read every poll interval and on reconsider(); a session held when this turns false is dropped, and none is dialled while it is false. */
+  shouldConnect: () => boolean;
+  /** Called each time a session is established, after the dial resolves, with the URL it was established to. WireMeshTransport uses it to advertise this store's presence at once instead of waiting for the next presence tick, and to know whether it holds an uplink to the public hub. */
+  onConnected: (url: string) => void;
+  /** Called each time an established session ends, whoever ended it. */
+  onDisconnected: () => void;
+  /** Reports a failed dial. Never called for anything else. */
+  onError: (error: Error) => void;
+  /** Overrides HUB_RECONNECT_INITIAL_DELAY_MS, for a test that must not wait a second per redial. */
+  initialDelayMs?: number;
+  /** Overrides HUB_RECONNECT_MAX_DELAY_MS. */
+  maxDelayMs?: number;
+  /** Overrides HUB_LINK_POLL_INTERVAL_MS. */
+  pollIntervalMs?: number;
+}
+
+export class HubLink {
+  private readonly initialDelayMs: number;
+  private readonly maxDelayMs: number;
+  private readonly pollIntervalMs: number;
+  private stopped = false;
+  private running: Promise<void> | undefined;
+  /** Cancels the wait between dials, so stop() does not sit out a delay. */
+  private wake: (() => void) | undefined;
+  /** When each URL's last dial failed or its session was dropped by the far end (epoch ms); a successful dial to a URL clears its entry. */
+  private readonly failedAt = new Map<string, number>();
+
+  constructor(private readonly options: Readonly<HubLinkOptions>) {
+    this.initialDelayMs =
+      options.initialDelayMs ?? HUB_RECONNECT_INITIAL_DELAY_MS;
+    this.maxDelayMs = options.maxDelayMs ?? HUB_RECONNECT_MAX_DELAY_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? HUB_LINK_POLL_INTERVAL_MS;
+  }
+
+  /** Begins running in the background and returns at once. A second call while running does nothing. */
+  start(): void {
+    if (this.running !== undefined || this.stopped) return;
+    this.running = this.run();
+  }
+
+  /** Re-evaluates shouldConnect now instead of at the next poll, and cuts short any wait, including the delay before a redial. Call it when something shouldConnect reads has changed. */
+  reconsider(): void {
+    this.wake?.();
+  }
+
+  /** Stops, drops the live session, and resolves once the loop has ended. */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    this.wake?.();
+    await this.options.hub.disconnect();
+    await this.running;
+  }
+
+  /** A method call rather than a direct property read, so TypeScript's control-flow narrowing does not treat the flag as staying false across the awaits in run(), during which stop() can set it. */
+  private isStopped(): boolean {
+    return this.stopped;
+  }
+
+  private async run(): Promise<void> {
+    let delayMs = this.initialDelayMs;
+    while (!this.isStopped()) {
+      if (!this.options.shouldConnect()) {
+        await this.sleep(this.pollIntervalMs);
+        continue;
+      }
+      let sessionEnded = false;
+      const url = this.options.selectUrl(this.excludedUrls());
+      try {
+        await this.options.hub.connect(url);
+        if (this.options.hub.isConnected) {
+          delayMs = this.initialDelayMs;
+          this.failedAt.delete(url);
+          this.options.onConnected(url);
+          sessionEnded = await this.holdWhileWanted(url);
+          this.options.onDisconnected();
+        }
+      } catch (error) {
+        this.options.onError(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+        sessionEnded = true;
+      }
+      if (sessionEnded) this.failedAt.set(url, Date.now());
+      if (this.isStopped()) return;
+      if (!sessionEnded) continue;
+      await this.sleep(delayMs);
+      delayMs = Math.min(
+        delayMs * RECONNECT_DELAY_GROWTH_FACTOR,
+        this.maxDelayMs,
+      );
+    }
+  }
+
+  /** Holds the live session to url until the hub ends it, resolving true, or until the store stops wanting it or selection prefers another hub, when it drops the session itself and resolves false. */
+  private async holdWhileWanted(url: string): Promise<boolean> {
+    const hubEnded = this.options.hub
+      .whenDisconnected()
+      .then(() => "ended" as const);
+    while (!this.isStopped()) {
+      const outcome = await Promise.race([
+        hubEnded,
+        this.sleep(this.pollIntervalMs).then(() => "woke" as const),
+      ]);
+      if (outcome === "ended") return true;
+      if (this.isStopped()) return false;
+      if (
+        !this.options.shouldConnect() ||
+        this.options.selectUrl(this.excludedUrls()) !== url
+      ) {
+        await this.options.hub.disconnect();
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /** The URLs that failed within the last redial ceiling. */
+  private excludedUrls(): ReadonlySet<string> {
+    const cutoff = Date.now() - this.maxDelayMs;
+    const excluded = new Set<string>();
+    for (const [url, at] of this.failedAt) {
+      if (at > cutoff) excluded.add(url);
+      else this.failedAt.delete(url);
+    }
+    return excluded;
+  }
+
+  /** Waits ms, or until reconsider() or stop() cuts it short. Each wait clears the wake handle only if it is still its own, since holdWhileWanted leaves a losing wait pending and its late end must not wipe the handle of the wait that replaced it. */
+  private async sleep(ms: number): Promise<void> {
+    let wakeThis: (() => void) | undefined;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      timer.unref();
+      wakeThis = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      this.wake = wakeThis;
+    });
+    if (this.wake === wakeThis) this.wake = undefined;
+  }
+}