agent-comms 9.0.14 → 9.1.0

package/src/core/bridge-mesh.ts

@@ -129,6 +129,7 @@ export function createBridgeMeshSyncFromIdentity(
     getNewerVersionIfAny: () => versionChecker.getNewerVersionIfAny(),
     getUnreadableLedgerEntries: () =>
       store.accountLedger?.unreadableEntries().length ?? 0,
+    getStalledLedgerLogs: () => transport.dataFrames.stalledLogs(),
   });
   const revocation = createRevocationView();
   return {

package/src/core/data-frame-routing.ts

@@ -7,7 +7,7 @@ import {
   handleDataHave,
   handleDataRequest,
 } from "wire-mesh-core/domain/data-sync";
-import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { bytesToHex, deviceIdToHex } from "wire-mesh-core/domain/device-id";
 import { isDataFrame } from "wire-mesh-core/domain/hub-mailbox";
 import type { DataDomainFrame } from "wire-mesh-core/domain/mesh-session";
 import type {
@@ -19,6 +19,7 @@ import type { Connection } from "wire-mesh-core/ports/transport";
 import type { KeyValueStorage } from "wire-mesh-core/ports/storage";
 import type { AccountLedgerReplica } from "./account-ledger.js";
 import { readMembershipProof } from "./gossip-directory.js";
+import { LedgerGapTracker, type StalledLedgerLog } from "./ledger-gaps.js";
 import type { WireMeshTransportOptions } from "./wire-mesh-transport-options.js";
 
 /** The most entries one data-entries reply carries, for every log this side answers for, the account ledger's included: a longer log catches up over several rounds, so the bound only caps one frame's size. */
@@ -86,6 +87,7 @@ export async function routeDataFrame(
     dataStorage: KeyValueStorage | undefined;
     account: Readonly<AccountReplication> | undefined;
     peerSessions: ReadonlyMap<string, unknown>;
+    gaps?: Pick<LedgerGapTracker, "noteHave"> | undefined;
     onError: ((error: Error) => void) | undefined;
   }>,
   connection: Readonly<Connection>,
@@ -105,6 +107,9 @@ export async function routeDataFrame(
       ledger.ownsLog(frame.peer)
     ) {
       if (!(await deps.account.isAccountPeer(deviceIdHex))) return;
+      if (frame.type === "data-have") {
+        deps.gaps?.noteHave(deviceIdHex, frame.peer, frame["head-seq"]);
+      }
       const reply = await ledger.handleDataFrame(frame);
       if (reply !== null) await connection.send(reply);
       return;
@@ -133,6 +138,7 @@ export async function routeRelayedDataFrame(
   deps: Readonly<{
     account: Readonly<AccountReplication> | undefined;
     hub: Readonly<HubDataChannel> | undefined;
+    gaps?: Pick<LedgerGapTracker, "noteHave"> | undefined;
     onError: ((error: Error) => void) | undefined;
   }>,
   fromDeviceHex: string,
@@ -144,6 +150,9 @@ export async function routeRelayedDataFrame(
     const ledger = account.ledger();
     if (ledger?.ownsLog(frame.peer) !== true) return;
     if (!(await account.isAccountPeer(fromDeviceHex))) return;
+    if (frame.type === "data-have") {
+      deps.gaps?.noteHave(fromDeviceHex, frame.peer, frame["head-seq"]);
+    }
     const reply = await ledger.handleDataFrame(frame);
     if (reply !== null) await hub.send(fromDeviceHex, reply);
   } catch (error: unknown) {
@@ -151,7 +160,15 @@ export async function routeRelayedDataFrame(
   }
 }
 
-/** Offers every account writer log this machine holds to every device that holds the same account and that this side can reach (agent-comms#344): over a live, trusted data connection, or, for a device it meets only through the relay hub, over a relay pairing. Such a device that is behind asks for what it is missing, which is the data-domain fan-out that carries each machine's grants and revocations to every other. A device reachable both ways is offered the logs once, directly. Called on the gossip cadence, so a machine that was away when an entry was written still catches up the next time it is reachable. A send that fails is reported and the rest carry on; the next round retries it. */
+/** What one round of offering the account ledger found out. */
+export interface LedgerOfferRound {
+  /** Whether this side reached any device of the account: an offer went out to at least one, or there was nothing to offer and a device was there to offer it to. False means this machine is offline as far as the account goes, which says nothing about whether any peer withholds anything; an offer to one device that failed does not make it false while another got through. */
+  reached: boolean;
+  /** This side's head sequence of each log it holds, by log id hex, read once for the round. */
+  localHeads: ReadonlyMap<string, number>;
+}
+
+/** Offers every account writer log this machine holds to every device that holds the same account and that this side can reach (agent-comms#344): over a live, trusted data connection, or, for a device it meets only through the relay hub, over a relay pairing. Such a device that is behind asks for what it is missing, which is the data-domain fan-out that carries each machine's grants and revocations to every other. A device reachable both ways is offered the logs once, directly. Called on the gossip cadence, so a machine that was away when an entry was written still catches up the next time it is reachable. A send that fails is reported through onError and the rest carry on; the next round retries it. Resolves with whether any device was reached and with this side's heads, read once. */
 export async function announceAccountLedger(
   deps: Readonly<{
     connectionsByPeer: ReadonlyMap<string, Readonly<Connection>>;
@@ -160,47 +177,77 @@ export async function announceAccountLedger(
     peerSessions: ReadonlyMap<string, unknown>;
     onError: ((error: Error) => void) | undefined;
   }>,
-): Promise<void> {
+): Promise<LedgerOfferRound> {
   const ledger = deps.account.ledger();
-  if (ledger === undefined) return;
+  if (ledger === undefined) return { reached: false, localHeads: new Map() };
   const frames = await ledger.announcements();
-  if (frames.length === 0) return;
+  const localHeads = new Map<string, number>();
+  for (const frame of frames) {
+    localHeads.set(bytesToHex(frame.peer), frame["head-seq"]);
+  }
+  let devices = 0;
+  let sent = 0;
   const reportError = (error: unknown): void => {
     deps.onError?.(error instanceof Error ? error : new Error(String(error)));
   };
+  // A device whose membership cannot be read is reported and skipped: one device that makes this throw must not stop the round from being counted.
+  const isAccountPeer = async (deviceHex: string): Promise<boolean> => {
+    try {
+      return await deps.account.isAccountPeer(deviceHex);
+    } catch (error: unknown) {
+      reportError(error);
+      return false;
+    }
+  };
   const direct = new Set<string>();
   const offers: Promise<void>[] = [];
   for (const [deviceHex, connection] of deps.connectionsByPeer) {
     if (!deps.peerSessions.has(deviceHex)) continue;
-    if (!(await deps.account.isAccountPeer(deviceHex))) continue;
+    if (!(await isAccountPeer(deviceHex))) continue;
     direct.add(deviceHex);
+    devices += 1;
     for (const frame of frames) {
       try {
         await connection.send(frame);
+        sent += 1;
       } catch (error: unknown) {
         reportError(error);
       }
     }
   }
   const { hub } = deps;
-  if (hub === undefined) return;
-  for (const deviceHex of hub.peers()) {
-    if (direct.has(deviceHex)) continue;
-    if (!(await deps.account.isAccountPeer(deviceHex))) continue;
-    // Each device is offered concurrently: a pairing to a device that is not there waits out its own handshake, which must not hold up the others.
-    offers.push(
-      (async () => {
-        for (const frame of frames) {
-          try {
-            await hub.send(deviceHex, frame);
-          } catch (error: unknown) {
-            reportError(error);
+  if (hub !== undefined) {
+    let hubPeers: readonly string[] = [];
+    try {
+      hubPeers = hub.peers();
+    } catch (error: unknown) {
+      reportError(error);
+    }
+    for (const deviceHex of hubPeers) {
+      if (direct.has(deviceHex)) continue;
+      if (!(await isAccountPeer(deviceHex))) continue;
+      devices += 1;
+      // Each device is offered concurrently: a pairing to a device that is not there waits out its own handshake, which must not hold up the others.
+      offers.push(
+        (async () => {
+          for (const frame of frames) {
+            try {
+              await hub.send(deviceHex, frame);
+              sent += 1;
+            } catch (error: unknown) {
+              reportError(error);
+            }
           }
-        }
-      })(),
-    );
+        })(),
+      );
+    }
   }
   await Promise.all(offers);
+
+  return {
+    reached: sent > 0 || (frames.length === 0 && devices > 0),
+    localHeads,
+  };
 }
 
 export interface DataFrameRouterDeps {
@@ -226,6 +273,9 @@ export class DataFrameRouter {
 
   private announceInterval: ReturnType<typeof setInterval> | undefined;
 
+  /** What each peer says the account's writer logs reach, and the rounds this side has stayed behind it. Undefined for a transport with no account ledger. */
+  private readonly gaps: LedgerGapTracker | undefined;
+
   /** Whether an announcement round is still running, so a round slowed by an unreachable hub peer is not stacked on by the next tick. */
   private announcing = false;
 
@@ -233,9 +283,24 @@ export class DataFrameRouter {
     this.dataStorage = deps.dataStorage;
     const { account } = deps;
     if (account === undefined) return;
+    const gaps = new LedgerGapTracker({
+      request: async (source, frame) => this.requestFrom(source, frame),
+      isLive: (source) =>
+        deps.peerSessions.has(source) ||
+        (deps.hub?.peers().includes(source) ?? false),
+      onError: (error) => {
+        deps.onError?.(error);
+      },
+    });
+    this.gaps = gaps;
     this.announceInterval = setInterval(() => {
       if (this.announcing) return;
       this.announcing = true;
+      const report = (error: unknown): void => {
+        deps.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      };
       announceAccountLedger({
         connectionsByPeer: this.connectionsByPeer,
         account,
@@ -243,11 +308,10 @@ export class DataFrameRouter {
         peerSessions: deps.peerSessions,
         onError: deps.onError,
       })
-        .catch((error: unknown) => {
-          deps.onError?.(
-            error instanceof Error ? error : new Error(String(error)),
-          );
-        })
+        .then(async (offered) =>
+          gaps.round(offered.localHeads, { offline: !offered.reached }),
+        )
+        .catch(report)
         .finally(() => {
           this.announcing = false;
         });
@@ -255,6 +319,27 @@ export class DataFrameRouter {
     this.announceInterval.unref();
   }
 
+  /** Sends a data-request to one source, over its direct session when it has one and through the relay hub otherwise. */
+  private async requestFrom(
+    source: string,
+    frame: Readonly<DataRequestFrame>,
+  ): Promise<void> {
+    const connection = this.connectionsByPeer.get(source);
+    if (connection !== undefined && this.deps.peerSessions.has(source)) {
+      await connection.send(frame);
+      return;
+    }
+    if (this.deps.hub === undefined) {
+      throw new Error(`no route to ${source} to ask it for ledger entries`);
+    }
+    await this.deps.hub.send(source, frame);
+  }
+
+  /** The account ledger's logs this side has stayed behind for several rounds, for whoami. Empty when there is no account ledger. */
+  stalledLogs(): StalledLedgerLog[] {
+    return this.gaps?.stalled() ?? [];
+  }
+
   /** See routeDataFrame. */
   async route(connection: Readonly<Connection>, frame: Frame): Promise<void> {
     await routeDataFrame(
@@ -263,6 +348,7 @@ export class DataFrameRouter {
         dataStorage: this.dataStorage,
         account: this.deps.account,
         peerSessions: this.deps.peerSessions,
+        gaps: this.gaps,
         onError: this.deps.onError,
       },
       connection,
@@ -279,6 +365,7 @@ export class DataFrameRouter {
       {
         account: this.deps.account,
         hub: this.deps.hub,
+        gaps: this.gaps,
         onError: this.deps.onError,
       },
       fromDeviceHex,

package/src/core/ledger-gaps.ts

@@ -0,0 +1,234 @@
+/**
+ * Gap detection for the account ledger's replicated writer logs (agent-comms#344), with no wire change. A `data-have` frame already carries the head sequence of the log it names, so each machine can see how far every peer says a log goes. A machine that stays behind that head for several rounds in a row, while the entries it asks for do not arrive, has a log something is withholding or dropping: a revocation could be in the missing part.
+ *
+ * What is kept: for each log, each live source's own announced head. A source is a peer this side reached over a direct session or over the relay hub. Each replication round compares those heads with this side's own and counts the rounds a log has stayed behind without advancing. At LEDGER_STALL_ROUNDS the log is reported as stalled, and again only if the gap grew and LEDGER_REPORT_REPEAT_ROUNDS rounds have passed, and the entries are asked of every source that announced a higher head, not only the one that answered first. A log that catches up, or whose announcing sources have gone, is forgotten.
+ *
+ * What is bounded: the logs tracked (MAX_TRACKED_LEDGER_LOGS, preferring logs this side already holds), how far ahead of this side's head an announced head may be (MAX_ANNOUNCED_HEAD_DISTANCE), how many reports of an ignored announcement are remembered, and how often a repeated report is made. Reports of ignored announcements are remembered apart from the logs, so forgetting a log never makes a report repeat.
+ *
+ * What it cannot see: a single path that withholds everything, including the higher head, since the head is learned from the same frames; a log beyond the tracked limit that this side does not hold; a head more than MAX_ANNOUNCED_HEAD_DISTANCE ahead, which is ignored; a log that is slow but still advancing, which is never behind for LEDGER_STALL_ROUNDS rounds without moving; and a machine that reaches no peer of the account at all, whose rounds are not counted.
+ */
+
+import { bytesToHex } from "wire-mesh-core/domain/device-id";
+import type { DataRequestFrame } from "wire-mesh-core/generated/protocol";
+
+/** How many consecutive replication rounds a log may stay behind an announced head, without a new entry arriving, before it is reported as stalled. */
+export const LEDGER_STALL_ROUNDS = 3;
+
+/** How many rounds pass before a gap that has grown since it was last reported is reported again, so a peer that raises its head every round gets one report per interval and not one per round. */
+export const LEDGER_REPORT_REPEAT_ROUNDS = 10;
+
+/** The most writer logs tracked at once. The account's logs are one per machine that ever wrote, so this is far above any real account. At the limit a log this side holds takes the place of one it does not, and any other log announced is not tracked, which is reported at most once per LEDGER_REPORT_REPEAT_ROUNDS rounds. */
+export const MAX_TRACKED_LEDGER_LOGS = 256;
+
+/** How many out-of-range reports are remembered per tracked log; the oldest is forgotten first. */
+const REMEMBERED_REPORTS_PER_LOG = 4;
+const MAX_REMEMBERED_REPORTS =
+  REMEMBERED_REPORTS_PER_LOG * MAX_TRACKED_LEDGER_LOGS;
+
+/** The furthest an announced head may be ahead of this side's own and still be believed. Heads count ledger entries, which are grants and revocations, and a reply carries a bounded batch, so a head further ahead than this is not an honest gap: it is not recorded, and is reported once. */
+export const MAX_ANNOUNCED_HEAD_DISTANCE = 1_000_000;
+
+/** A log this side is behind, reported once it has stayed so for LEDGER_STALL_ROUNDS rounds. */
+export interface StalledLedgerLog {
+  /** The writer log's id, hex. */
+  log: string;
+  /** This side's head sequence for it. */
+  localHead: number;
+  /** The highest head any live source announced. */
+  announcedHead: number;
+  /** The rounds it has stayed behind. */
+  rounds: number;
+}
+
+/** What the tracker needs from its owner. */
+export interface LedgerGapDeps {
+  /** Sends a request for the entries after `frame["from-seq"]` of a log to one source, directly or through the hub. A rejection is reported and does not stop the others. */
+  request: (source: string, frame: Readonly<DataRequestFrame>) => Promise<void>;
+  /** Whether a source is still reachable: its announced heads are forgotten when it is not. */
+  isLive: (source: string) => boolean;
+  /** Where a stall is reported, and a failed request. */
+  onError: (error: Error) => void;
+}
+
+interface LogState {
+  /** The log's id as the wire carries it, for the request frames. */
+  id: Uint8Array<ArrayBuffer>;
+  /** The head each source announced. */
+  heads: Map<string, number>;
+  /** This side's head at the last round, and how many rounds in a row it has been behind without it moving. */
+  lastLocal: number | undefined;
+  rounds: number;
+  /** The gap reported last, so a report repeats only when the gap grows, and the round it was reported in, so it repeats at most once per LEDGER_REPORT_REPEAT_ROUNDS. */
+  reportedGap: number;
+  reportedAtRound: number | undefined;
+}
+
+/** What a round is told about how it went. */
+export interface LedgerRoundOptions {
+  /** True when this machine reached no peer of the account this round: no offer went out, so nothing was asked of anyone. The round still notices a log that has caught up, but it is not counted as a round the log stayed behind. */
+  offline?: boolean;
+}
+
+export class LedgerGapTracker {
+  private readonly logs = new Map<string, LogState>();
+  private roundNumber = 0;
+  private overLimitReportedAtRound: number | undefined;
+  /** The logs this side held at the last round, which a log announced at the tracking limit is preferred for. */
+  private held: ReadonlySet<string> = new Set();
+  /** The `log:source` of every out-of-range announcement reported, oldest first, kept apart from the logs so that a log forgotten and announced again is not reported again. */
+  private readonly reportedOutOfRange = new Set<string>();
+
+  constructor(private readonly deps: Readonly<LedgerGapDeps>) {}
+
+  /** Records the head `source` announced for a log. Called for every `data-have` an account peer sends for one of the account's logs. */
+  noteHave(source: string, log: Uint8Array, head: number): void {
+    const key = bytesToHex(log);
+    let state = this.logs.get(key);
+    if (state === undefined) {
+      if (this.logs.size >= MAX_TRACKED_LEDGER_LOGS && !this.makeRoomFor(key)) {
+        this.reportOverLimit();
+        return;
+      }
+      state = {
+        id: Uint8Array.from(log),
+        heads: new Map(),
+        lastLocal: undefined,
+        rounds: 0,
+        reportedGap: 0,
+        reportedAtRound: undefined,
+      };
+      this.logs.set(key, state);
+    }
+    state.heads.set(source, head);
+  }
+
+  /** Makes room for a log at the tracking limit by dropping a tracked log this side holds nothing of, and only when this side holds the new one. */
+  private makeRoomFor(key: string): boolean {
+    if (!this.held.has(key)) return false;
+    for (const other of this.logs.keys()) {
+      if (this.held.has(other)) continue;
+      this.logs.delete(other);
+      return true;
+    }
+    return false;
+  }
+
+  private reportOverLimit(): void {
+    const last = this.overLimitReportedAtRound;
+    if (
+      last !== undefined &&
+      this.roundNumber - last < LEDGER_REPORT_REPEAT_ROUNDS
+    ) {
+      return;
+    }
+    this.overLimitReportedAtRound = this.roundNumber;
+    this.deps.onError(
+      new Error(
+        `the account ledger announces more than ${String(MAX_TRACKED_LEDGER_LOGS)} writer logs, which is more than any account has: the logs beyond them that this machine holds nothing of are ignored, so one of them that stays behind is not reported`,
+      ),
+    );
+  }
+
+  /** Remembers that an out-of-range announcement was reported, and whether it had been before. */
+  private firstReportOfOutOfRange(key: string, source: string): boolean {
+    const id = `${key}:${source}`;
+    if (this.reportedOutOfRange.has(id)) return false;
+    this.reportedOutOfRange.add(id);
+    if (this.reportedOutOfRange.size > MAX_REMEMBERED_REPORTS) {
+      const [oldest] = this.reportedOutOfRange;
+      if (oldest !== undefined) this.reportedOutOfRange.delete(oldest);
+    }
+    return true;
+  }
+
+  /**
+   * One replication round: compares every announced head with this side's (`localHeads`, by log id hex, absent for a log this side holds nothing of), counts the rounds each log stays behind without advancing, and on reaching LEDGER_STALL_ROUNDS reports it and asks every source that announced a higher head for the entries. Resolves once the requests have been sent.
+   */
+  async round(
+    localHeads: ReadonlyMap<string, number>,
+    options: Readonly<LedgerRoundOptions> = {},
+  ): Promise<void> {
+    this.roundNumber += 1;
+    this.held = new Set(localHeads.keys());
+    const requests: Promise<void>[] = [];
+    for (const [key, state] of this.logs) {
+      const local = localHeads.get(key) ?? 0;
+      for (const [source, head] of [...state.heads]) {
+        if (!this.deps.isLive(source)) {
+          state.heads.delete(source);
+        } else if (head - local > MAX_ANNOUNCED_HEAD_DISTANCE) {
+          state.heads.delete(source);
+          if (this.firstReportOfOutOfRange(key, source)) {
+            this.deps.onError(
+              new Error(
+                `a peer announced head ${String(head)} for account ledger log ${key}, which is out of range for a log this machine holds up to entry ${String(local)} of, and the announcement is ignored`,
+              ),
+            );
+          }
+        } else {
+          this.reportedOutOfRange.delete(`${key}:${source}`);
+        }
+      }
+      const announced = Math.max(0, ...state.heads.values());
+      if (announced <= local) {
+        this.logs.delete(key);
+        continue;
+      }
+      if (options.offline === true) continue;
+      if (state.lastLocal === local) {
+        state.rounds += 1;
+      } else {
+        state.rounds = 1;
+        state.reportedGap = 0;
+      }
+      state.lastLocal = local;
+      if (state.rounds < LEDGER_STALL_ROUNDS) continue;
+      const gap = announced - local;
+      const due =
+        state.reportedAtRound === undefined ||
+        this.roundNumber - state.reportedAtRound >= LEDGER_REPORT_REPEAT_ROUNDS;
+      if (gap > state.reportedGap && due) {
+        state.reportedGap = gap;
+        state.reportedAtRound = this.roundNumber;
+        this.deps.onError(
+          new Error(
+            `account ledger log ${key} has stayed behind for ${String(state.rounds)} rounds: this machine holds up to entry ${String(local)} and a peer announces ${String(announced)}; a grant or a revocation in the missing entries is not applied here, and the entries are being asked of every peer that announced them`,
+          ),
+        );
+      }
+      for (const [source, head] of state.heads) {
+        if (head <= local) continue;
+        requests.push(
+          this.deps
+            .request(source, {
+              type: "data-request",
+              peer: state.id,
+              "from-seq": local,
+            })
+            .catch((error: unknown) => {
+              this.deps.onError(
+                error instanceof Error ? error : new Error(String(error)),
+              );
+            }),
+        );
+      }
+    }
+    await Promise.all(requests);
+  }
+
+  /** The logs that have stayed behind for LEDGER_STALL_ROUNDS rounds or more as of the last round, for whoami. */
+  stalled(): StalledLedgerLog[] {
+    const out: StalledLedgerLog[] = [];
+    for (const [key, state] of this.logs) {
+      if (state.rounds < LEDGER_STALL_ROUNDS) continue;
+      const announced = Math.max(0, ...state.heads.values());
+      out.push({
+        log: key,
+        localHead: state.lastLocal ?? 0,
+        announcedHead: announced,
+        rounds: state.rounds,
+      });
+    }
+    return out;
+  }
+}

package/src/core/tool.ts

@@ -7,6 +7,7 @@
  *   3. Return the result string to the LLM
  */
 
+import type { StalledLedgerLog } from "./ledger-gaps.js";
 import { renderAgentList } from "./agent-list-format.js";
 import type { AgentDetailsExchange } from "./agent-details.js";
 import { plainNamer, type Namer, type Naming } from "./naming.js";
@@ -252,12 +253,17 @@ export interface CommsToolOptions {
   readonly getNewerVersionIfAny?: () => string | undefined;
   /** How many stored account ledger entries cannot be read, for whoami; omitted when the store has no account ledger. */
   readonly getUnreadableLedgerEntries?: () => number;
+  /** The account ledger's writer logs this side has stayed behind for several rounds, for whoami; omitted when the transport has no account ledger. */
+  readonly getStalledLedgerLogs?: () => readonly StalledLedgerLog[];
   /** Fetches a signer's armored PGP public key by fingerprint, used by gateway_redeem_connection_code when the caller supplies a fingerprint but not the key text itself. Defaults to the real keys.openpgp.org lookup (pgp-keyserver.ts); a test that would otherwise trigger real network I/O injects a fake resolver instead, the same reasoning bridge-mesh.ts's own fetchLatestVersion override already establishes for getNewerVersionIfAny above. */
   readonly fetchPgpPublicKeyByFingerprintImpl?: (
     fingerprint: string,
   ) => Promise<string>;
 }
 
+/** The most stalled-log lines whoami and update print, so a peer cannot make the result as long as it likes. */
+const MAX_STALLED_LEDGER_LINES = 8;
+
 export class CommsTool {
   /** Reports this bridge's own web UI address for the web_url action. Assignable post-construction, mirroring MeshStore's own onDelivery/onCoordinatorRoleChanged hooks, because the underlying web server handle isn't known until after this bridge's own tryStartBridgeWebServer() call -- which every real bridge makes after building its CommsTool, not before. Undefined (the default) means this bridge never wires web UI reporting. */
   getWebUrlStatus?: () => WebUrlStatus;
@@ -266,6 +272,8 @@ export class CommsTool {
   private readonly naming: Naming | undefined;
   private readonly getNewerVersionIfAny: (() => string | undefined) | undefined;
   private readonly getUnreadableLedgerEntries: (() => number) | undefined;
+  private readonly getStalledLedgerLogs:
+    (() => readonly StalledLedgerLog[]) | undefined;
   private readonly fetchPgpPublicKeyByFingerprintImpl: (
     fingerprint: string,
   ) => Promise<string>;
@@ -279,12 +287,14 @@ export class CommsTool {
       naming,
       getNewerVersionIfAny,
       getUnreadableLedgerEntries,
+      getStalledLedgerLogs,
       fetchPgpPublicKeyByFingerprintImpl = fetchPgpPublicKeyByFingerprint,
     } = options ?? {};
     this.discovery = discovery;
     this.naming = naming;
     this.getNewerVersionIfAny = getNewerVersionIfAny;
     this.getUnreadableLedgerEntries = getUnreadableLedgerEntries;
+    this.getStalledLedgerLogs = getStalledLedgerLogs;
     this.fetchPgpPublicKeyByFingerprintImpl =
       fetchPgpPublicKeyByFingerprintImpl;
   }
@@ -469,6 +479,7 @@ export class CommsTool {
         `Account ledger: ${String(unreadableLedger)} unreadable entries; a grant or revocation recorded only in them is not applied here until they are repaired or replaced from another machine's replica`,
       );
     }
+    lines.push(...this.stalledLedgerLines());
     const updateAvailable = this.formatUpdateAvailableLine();
     if (updateAvailable !== undefined) lines.push(updateAvailable);
     return {
@@ -484,6 +495,24 @@ export class CommsTool {
       : this.naming.namer(ctx.agentId);
   }
 
+  /** The `Account ledger log <id> is behind` lines for whoami and update, one per writer log this side has stayed behind, at most MAX_STALLED_LEDGER_LINES of them and then one `Account ledger: <n> more logs are behind` line. The wording is part of the interface: the README states it. */
+  private stalledLedgerLines(): string[] {
+    const stalled = this.getStalledLedgerLogs?.() ?? [];
+    const lines = stalled
+      .slice(0, MAX_STALLED_LEDGER_LINES)
+      .map(
+        (log) =>
+          `Account ledger log ${log.log} is behind: this machine holds up to entry ${String(log.localHead)}, a peer announces ${String(log.announcedHead)}, and ${String(log.rounds)} rounds have passed without the missing entries arriving; a grant or a revocation in them is not applied here`,
+      );
+    if (stalled.length > MAX_STALLED_LEDGER_LINES) {
+      lines.push(
+        `Account ledger: ${String(stalled.length - MAX_STALLED_LEDGER_LINES)} more logs are behind`,
+      );
+    }
+
+    return lines;
+  }
+
   private async whoami(ctx: Readonly<CommsContext>): Promise<CommsResult> {
     const agent = await this.store.getAgent(ctx.agentId);
     if (!agent) return { content: "Not registered.", isError: true };
@@ -505,6 +534,7 @@ export class CommsTool {
       `Tags: ${agent.tags.join(", ") || "(none)"}`,
       `Rooms: ${agent.subscribedRooms.join(", ") || "(none)"}`,
     ];
+    lines.push(...this.stalledLedgerLines());
     const updateAvailable = this.formatUpdateAvailableLine();
     if (updateAvailable !== undefined) lines.push(updateAvailable);
     return {

package/src/core/wire-mesh-transport.ts

@@ -239,8 +239,8 @@ export class WireMeshTransport implements MeshTransport {
   /** Reads this side's own currently-running cc-peer package version for the next gossip re-advertisement tick (agent-comms#198). Unlike getCurrentPresence/getHostedRooms/getSelfAgentAdvert (constructor-injected, since MeshStore already has a real value for each at construction time), this is a plain mutable field set post-construction -- bridge-mesh.ts assigns it right after building this transport, mirroring MeshStore's own onDelivery/onError/onCoordinatorRoleChanged convention, so this transport doesn't need its own constructor parameter for a fact only two of many bridges ever have. undefined for every bridge that never loads cc-peer at all. */
   getCcPeerVersion: (() => string | undefined) | undefined;
 
-  /** Answers, stores and offers this side's core/data frames: the room-notice oplog over dataStorage, and the account's replicated grant ledger (agent-comms#344). See DataFrameRouter. */
-  private readonly dataFrames: DataFrameRouter;
+  /** Answers, stores and offers this side's core/data frames: the room-notice oplog over dataStorage, and the account's replicated grant ledger (agent-comms#344). See DataFrameRouter. Public for whoami: the router knows which account ledger logs this side has stayed behind for several rounds (ledger-gaps.ts). */
+  readonly dataFrames: DataFrameRouter;
 
   /** The cross-machine trust boundary (agent-comms#156): gates outbound gossip advertisement (hasAny), inbound directory merge (bare-device trust, a principal's own device, or a verified membership proof, wired into HubSession as admitEntries), the legacy per-device frame path (isTrusted, bare-device trust only), and outbound targeted hub requests (isReachable); see GatewayTrust's own class doc. A real room-domain manage-request relayed through the hub is never gated on this at all since agent-comms#192: hub-session.ts's own dispatchHubRequest relies purely on that verb's own capability-token verification instead. Defaults to a fresh, empty (deny-all) instance when no caller wires one in, matching every existing construction site that predates this feature. */
   private readonly gatewayTrust: GatewayTrustReader;