borgmcp 5.5.0 → 5.7.0

package/src/representative-cmd.ts

@@ -29,6 +29,7 @@ import {
 } from './representative-core.js';
 import {
   RepresentativeStoreError,
+  bindingFingerprint,
   representativeRecoveryCommand,
   type RepresentativeBinding,
   type RepresentativeStore,
@@ -41,7 +42,9 @@ export const DEFAULT_REPRESENTATIVE_ROLE = 'hermes-representative';
 export type RepresentativeCommand =
   | { action: 'prepare'; coordinator: string; role: string; rebind: boolean; worktreeName?: string; host?: string }
   | { action: 'status'; worktree?: string }
-  | { action: 'mcp'; worktree?: string };
+  | { action: 'mcp'; worktree?: string }
+  | { action: 'listen'; worktree?: string; replayAfter?: string }
+  | { action: 'hermes-plugin-install'; hermesHome?: string; force: boolean };
 
 export type ParsedRepresentativeArgs =
   | { ok: true; command: RepresentativeCommand }
@@ -62,12 +65,13 @@ export interface RepresentativeCmdDeps {
 
 export function parseRepresentativeArgs(args: readonly string[]): ParsedRepresentativeArgs {
   const [action, ...rest] = args;
-  if (action !== 'prepare' && action !== 'status' && action !== 'mcp') {
-    return { ok: false, error: 'expected one of: prepare, status, mcp' };
+  if (action === 'hermes-plugin') return parseHermesPluginArgs(rest);
+  if (action !== 'prepare' && action !== 'status' && action !== 'mcp' && action !== 'listen') {
+    return { ok: false, error: 'expected one of: prepare, status, mcp, listen, hermes-plugin' };
   }
   const values: Record<string, string> = {};
   let rebind = false;
-  const valueFlags = action === 'prepare' ? ['--coordinator', '--role', '--worktree', '--host'] : ['--worktree'];
+  const valueFlags = action === 'prepare' ? ['--coordinator', '--role', '--worktree', '--host'] : action === 'listen' ? ['--worktree', '--replay-after'] : ['--worktree'];
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
     if (action === 'prepare' && arg === '--rebind') {
@@ -91,7 +95,11 @@ export function parseRepresentativeArgs(args: readonly string[]): ParsedRepresen
     if (worktree !== undefined && !isAbsolute(worktree)) {
       return { ok: false, error: '--worktree must be an absolute path to the representative worktree' };
     }
-    return { ok: true, command: { action, ...(worktree ? { worktree } : {}) } };
+    const replayAfter = values['--replay-after'];
+    if (replayAfter && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(replayAfter)) {
+      return { ok: false, error: '--replay-after must be an entry UUID' };
+    }
+    return { ok: true, command: { action, ...(worktree ? { worktree } : {}), ...(replayAfter ? { replayAfter } : {}) } };
   }
   const coordinator = values['--coordinator'];
   if (!coordinator) {
@@ -118,6 +126,30 @@ export function parseRepresentativeArgs(args: readonly string[]): ParsedRepresen
   };
 }
 
+function parseHermesPluginArgs(args: readonly string[]): ParsedRepresentativeArgs {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== 'install') return { ok: false, error: 'expected: hermes-plugin install [--hermes-home <path>] [--force]' };
+  let hermesHome: string | undefined;
+  let force = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--force') {
+      force = true;
+    } else if (arg === '--hermes-home') {
+      const next = rest[i + 1];
+      if (typeof next !== 'string' || next.length === 0 || next.startsWith('-')) {
+        return { ok: false, error: '--hermes-home requires a value' };
+      }
+      if (!isAbsolute(next)) return { ok: false, error: '--hermes-home must be an absolute path' };
+      hermesHome = next;
+      i += 1;
+    } else {
+      return { ok: false, error: `unknown argument: ${arg}. Supported: --hermes-home, --force` };
+    }
+  }
+  return { ok: true, command: { action: 'hermes-plugin-install', force, ...(hermesHome ? { hermesHome } : {}) } };
+}
+
 function canonicalWorktree(path: string, deps: Pick<RepresentativeCmdDeps, 'findProjectRoot'>): string {
   let real = resolve(path);
   try {
@@ -267,7 +299,9 @@ export async function runRepresentativeStatus(
     const status = await representativeStatus(ctx);
     const { representativeOwnership } = await import('./representative-owner.js');
     const ownership = await representativeOwnership(ctx.binding);
-    deps.stdout(`${JSON.stringify({ ...status, ownership }, null, 2)}\n`);
+    const { representativeListenerStatus } = await import('./representative-listener.js');
+    const listener = await representativeListenerStatus(ctx.binding);
+    deps.stdout(`${JSON.stringify({ ...status, ownership, listener }, null, 2)}\n`);
     return status.connected ? 0 : 1;
   } catch (error) {
     deps.stderr(`◼ borg representative status: ${describeError(error)}\n`);
@@ -303,20 +337,9 @@ export async function runRepresentativeMcp(
     heartbeatIntervalMs: io.heartbeatIntervalMs,
     ...(io.stdin ? { stdin: io.stdin } : {}),
     ...(io.stdout ? { stdout: io.stdout } : {}),
-    context: async () => {
-      const ctx = await resolveRepresentativeContext(worktree, deps);
-      if (
-        ctx.binding.cubeId !== pinned.cubeId ||
-        ctx.binding.coordinatorDroneId !== pinned.coordinatorDroneId ||
-        ctx.binding.representativeDroneId !== pinned.representativeDroneId
-      ) {
-        throw new RepresentativeError(
-          'BINDING_MISMATCH',
-          'The operator changed this connection\'s cube or Coordinator while it was running. Restart the MCP server to use the new binding.',
-        );
-      }
-      return ctx;
-    },
+    // The full generation, so any rebind (same selection included) is refused.
+    pinnedFingerprint: bindingFingerprint(pinned),
+    context: () => resolveRepresentativeContext(worktree, deps),
   });
   const stdin = io.stdin ?? process.stdin;
   stdin.once('end', () => { void served.close(); });
@@ -361,3 +384,12 @@ export async function buildDefaultRepresentativeDeps(): Promise<RepresentativeCm
     stderr: (text) => { process.stderr.write(text); },
   };
 }
+
+export async function runRepresentativeListen(
+  command: Extract<RepresentativeCommand, { action: 'listen' }>,
+  deps: RepresentativeCmdDeps,
+  options: import('./representative-listener.js').ListenerOptions = {},
+): Promise<number> {
+  const { runListener } = await import('./representative-listener.js');
+  return runListener(command, deps, options);
+}

package/src/representative-core.ts

@@ -25,21 +25,20 @@ import {
   BorgServerTrustError,
   BorgServerUnreachableError,
 } from './server-errors.js';
-import { representativeRecoveryCommand, isRepresentativeUuid, type RepresentativeBinding, type RepresentativeStore } from './representative-store.js';
+import { bindingFingerprint, representativeRecoveryCommand, isRepresentativeUuid, type RepresentativeBinding, type RepresentativeStore } from './representative-store.js';
+import { comparePoints, createDeliveryStore, type DeliveryState } from './representative-delivery-store.js';
+import { readPrivateLocalServerCursor, type LocalServerCursor } from './local-server-cursor.js';
+import { validatePrivateDirectory } from './representative-listener-store.js';
+import { borgConfigRoot } from './private-root.js';
 
 const UUID_SCAN_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
 export const REPRESENTATIVE_MESSAGE_LIMIT_BYTES = 3000;
 
 export const REPRESENTATIVE_DELIVERY_NOTE =
-  'Explicit send/read round trips only: this connection has no background wake or push delivery. ' +
-  'Coordinator replies are seen only when borg_representative-read is called. Each read consumes the unread view of ' +
-  'everything it fetched. The host must persist each read result before relaying it, map request_id to its conversation, ' +
-  'route replies by in_reply_to, and hold replies with an unknown or missing request_id for the human. An already-read ' +
-  'reply cannot be retrieved through this connection. The first send/read/ack takes an exclusive process lease for this ' +
-  'representative drone; other processes refuse those calls without ledger, cursor or network activity. Status stays ' +
-  'read-only and reports ownership. After owner exit, death or lease expiry another process can take over. ' +
-  'A process that loses its lease refuses further calls until restarted. Ownership does not route conversations inside the host. ' +
-  'A local lease cannot cancel an in-flight request; retry an ambiguous send with its original request_id.';
+  'read returns undelivered replies without consuming them; persist, route by in_reply_to (unknown: hold for the ' +
+  'human), then deliver through the last persisted entry_id. ack only notifies the Coordinator. A separate ' +
+  'borg representative listen process emits body-free wake hints. One process at a time owns send/read/deliver/ack; ' +
+  'status is read-only. Stop routing if binding_fingerprint changes.';
 
 export type RepresentativeErrorCode =
   | typeof ErrorCode.INVALID_INPUT
@@ -59,7 +58,9 @@ export type RepresentativeErrorCode =
   | 'COORDINATOR_UNAVAILABLE'
   | 'REPRESENTATIVE_ROLE_NOT_PERMITTED'
   | 'REPRESENTATIVE_ROLE_MISMATCH'
-  | 'NOT_A_COORDINATOR_REPLY';
+  | 'NOT_A_COORDINATOR_REPLY'
+  | 'REPRESENTATIVE_DELIVER_UNKNOWN_ENTRY'
+  | 'REPRESENTATIVE_READ_OVERSIZE';
 
 export interface RepresentativeErrorDetails {
   owner?: import('./stream-owner.js').StreamOwnershipSnapshot;
@@ -67,6 +68,9 @@ export interface RepresentativeErrorDetails {
   cause_code?: string;
   cause_message?: string;
   recovery?: string;
+  entry_id?: string;
+  measured_bytes?: number;
+  bound?: number;
 }
 
 export class RepresentativeError extends Error {
@@ -99,11 +103,12 @@ export interface RepresentativeBackend {
     unreachableRecipients?: Array<{ id: string; label: string }>;
   }>;
   /**
-   * Drains THIS seat's own unread cursor only (no other drone's cursor exists
-   * here) — the WHOLE returned page, including entries the caller then filters
-   * out. `limit` is a page-size hint: the client's digest mode may return more.
+   * One stateless page of the cube log strictly after an exact (created_at, id)
+   * cursor, ascending. Reads and advances no unread cursor; never digest mode.
    */
-  readUnread(limit?: number, continuationGuard?: () => Promise<void>): Promise<{ entries: LogEntry[]; has_more?: boolean }>;
+  readAfter(cursor: LocalServerCursor | null, limit: number, continuationGuard?: () => Promise<void>): Promise<{ entries: LogEntry[]; has_more?: boolean }>;
+  /** This seat's client-owned unread cursor, read only; the slice 2 migration input. */
+  unreadCursor(): Promise<LocalServerCursor | null>;
   readEntry(entryId: string): Promise<{ entry: LogEntry }>;
   ack(entryId: string): Promise<void>;
 }
@@ -113,6 +118,8 @@ export interface RepresentativeContext {
   backend: RepresentativeBackend;
   store: RepresentativeStore;
   now?: () => Date;
+  /** Checked immediately before each private delivery-state write (the tools lease in MCP). */
+  guard?: () => Promise<void>;
 }
 
 /** Real backend: the existing seat-scoped client calls for one hydrated seat. */
@@ -126,8 +133,20 @@ export async function createSeatBackend(active: ActiveCube): Promise<Representat
       client.appendLog(active.sessionToken, active.apiUrl, message, {
         to, postId, transportRetry: false, serverTrustIdentity: trust,
       }),
-    readUnread: (limit, continuationGuard) =>
-      client.readLog(active.sessionToken, active.apiUrl, { unreadOnly: true, limit, serverTrustIdentity: trust, continuationGuard }),
+    readAfter: (cursor, limit, continuationGuard) =>
+      client.readLog(active.sessionToken, active.apiUrl, { cursor, limit, serverTrustIdentity: trust, continuationGuard }),
+    // Migration input only: an unsafe private root or cursor file is no cursor,
+    // so the checkpoint starts empty and replays instead of trusting it.
+    unreadCursor: async () => {
+      try {
+        if (!await validatePrivateDirectory(borgConfigRoot(), false)) return null;
+      } catch {
+        return null;
+      }
+      return readPrivateLocalServerCursor({
+        origin: active.apiUrl, trustIdentity: trust!, cubeId: active.cubeId, droneId: active.droneId,
+      });
+    },
     readEntry: (entryId) =>
       client.readLogEntry(active.sessionToken, active.apiUrl, { entry_id: entryId }, trust),
     ack: (entryId) => client.ackLogEntry(active.sessionToken, active.apiUrl, entryId, 'ack', trust),
@@ -184,7 +203,7 @@ export function resolveCoordinator(
 }
 
 /** Re-prove, against the live cube, that this seat and the bound Coordinator are still the bound ones. */
-async function verifyLiveBinding(ctx: RepresentativeContext): Promise<{ coordinator: RosterDrone; self: RosterDrone }> {
+export async function verifyLiveBinding(ctx: RepresentativeContext): Promise<{ coordinator: RosterDrone; self: RosterDrone }> {
   const { binding, backend } = ctx;
   const me = await backend.whoami();
   if (me.cube_id !== binding.cubeId || me.drone_id !== binding.representativeDroneId) {
@@ -402,6 +421,13 @@ function classifyAppendFailure(error: unknown, binding: RepresentativeBinding):
 export async function sendRepresentativeMessage(
   ctx: RepresentativeContext,
   raw: unknown,
+): Promise<RepresentativeSendResult & { binding_fingerprint: string }> {
+  return { ...await sendOnce(ctx, raw), binding_fingerprint: bindingFingerprint(ctx.binding) };
+}
+
+async function sendOnce(
+  ctx: RepresentativeContext,
+  raw: unknown,
 ): Promise<RepresentativeSendResult> {
   const input = validateSendInput(raw);
   const { binding, store } = ctx;
@@ -574,6 +600,10 @@ export interface RepresentativeReply {
   /** A ledger request id quoted in the reply text. Textual correlation only. */
   in_reply_to: string | null;
   message: string;
+  /** This entry alone exceeds max_bytes; it is returned whole and alone. */
+  oversize?: true;
+  /** Oversize and still above the envelope bound: citations were reduced to ids. */
+  documents_reduced?: true;
 }
 
 function isAddressedCoordinatorEntry(binding: RepresentativeBinding, entry: LogEntry): 'direct' | 'broadcast' | null {
@@ -584,48 +614,215 @@ function isAddressedCoordinatorEntry(binding: RepresentativeBinding, entry: LogE
   return 'broadcast';
 }
 
+/** The exact text an MCP tool result carries; `max_bytes` measures this. */
+export function serializeRepresentativeResult(body: unknown): string {
+  return JSON.stringify(body, null, 2);
+}
+
+const READ_SCAN_PAGE = 500;
+/**
+ * A serialized read result never exceeds max(max_bytes, this). An oversize
+ * entry is returned alone; if it still exceeds the bound, its citations are
+ * reduced to ids. Message text is never cut: the server caps a post (4096
+ * bytes by default), so the reduced entry fits.
+ */
+export const REPRESENTATIVE_ENVELOPE_FLOOR = 16384;
+
+/**
+ * Run `use` with this generation's delivery state. On the first call for a
+ * generation, `use` runs alone in the per-seat queue with the proposed start,
+ * and nothing is written until it calls `commit`: a read refused as oversize
+ * leaves no tombstone and no checkpoint behind.
+ */
+async function withDeliveryState<T>(
+  ctx: RepresentativeContext,
+  use: (state: DeliveryState, commit: () => Promise<void>) => Promise<T>,
+): Promise<T> {
+  const store = createDeliveryStore(ctx.binding);
+  const saved = await store.load();
+  if (saved) {
+    // A checkpoint always implies an upgraded seat; restore a lost tombstone.
+    if (!await store.migrated()) await store.markMigrated(ctx.guard);
+    return use(saved, async () => {});
+  }
+  return store.initialize(async () => {
+    const again = await store.load();
+    if (again) return use(again, async () => {});
+    // The seat already upgraded (a tombstone or a sibling generation exists):
+    // this generation (rebind, new Coordinator, or a removed invalid checkpoint)
+    // starts empty and replays its addressed history. Nothing on disk is ever
+    // read back as a position, and the legacy cursor is never imported again.
+    const upgraded = await store.migrated() || await store.otherGenerationExists();
+    // One-time upgrade: start where the pre-checkpoint destructive read left
+    // the unread view. The cursor is used only in memory.
+    const cursor = upgraded ? null : await ctx.backend.unreadCursor();
+    return use({ checkpoint: cursor, readThrough: cursor, returned: [] }, async () => {
+      // The tombstone is created exclusively first, so an interruption before
+      // the checkpoint replays (duplicates the host dedupes). An initializer in
+      // another process that won the create (excluded by the tools lease in
+      // practice) makes this one start empty.
+      const start = !upgraded && await store.markMigrated(ctx.guard) ? cursor : null;
+      if (upgraded) await store.markMigrated(ctx.guard);
+      await store.advance({ checkpoint: start, readThrough: start }, ctx.guard);
+    });
+  });
+}
+
+const checkpointView = (point: LocalServerCursor | null) =>
+  ({ entry_id: point?.id ?? null, created_at: point?.created_at ?? null });
+
 export async function readRepresentativeReplies(
   ctx: RepresentativeContext,
   raw: unknown,
-): Promise<{ replies: RepresentativeReply[]; ignored_entries: number; has_more: boolean; delivery: string }> {
+): Promise<{
+  replies: RepresentativeReply[]; checkpoint: { entry_id: string | null; created_at: string | null };
+  has_more: boolean; ignored_entries: number; binding_fingerprint: string; delivery: string;
+}> {
   const input = (raw ?? {}) as Record<string, unknown>;
-  const unknown = Object.keys(input).filter((key) => key !== 'include_broadcast' && key !== 'limit' && input[key] !== undefined);
+  const allowed = ['include_broadcast', 'limit', 'max_bytes'];
+  const unknown = Object.keys(input).filter((key) => !allowed.includes(key) && input[key] !== undefined);
   if (unknown.length > 0) throw new RepresentativeError(ErrorCode.INVALID_INPUT, `Unsupported field(s): ${unknown.join(', ')}.`);
   if (input.include_broadcast !== undefined && typeof input.include_broadcast !== 'boolean') {
     throw new RepresentativeError(ErrorCode.INVALID_INPUT, 'include_broadcast must be a boolean.');
   }
-  if (input.limit !== undefined && (!Number.isInteger(input.limit) || (input.limit as number) < 1 || (input.limit as number) > 200)) {
-    throw new RepresentativeError(ErrorCode.INVALID_INPUT, 'limit must be an integer from 1 to 200.');
-  }
+  const bounded = (name: string, min: number, max: number, fallback: number) => {
+    const value = input[name];
+    if (value === undefined) return fallback;
+    if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) {
+      throw new RepresentativeError(ErrorCode.INVALID_INPUT, `${name} must be an integer from ${min} to ${max}.`);
+    }
+    return value as number;
+  };
+  const limit = bounded('limit', 1, 50, 10);
+  const maxBytes = bounded('max_bytes', 4096, 60000, 32768);
   await verifyLiveBinding(ctx);
-  const page = await ctx.backend.readUnread(input.limit as number | undefined);
+  return withDeliveryState(ctx, async (state, commit) => {
   const requestIds = await ctx.store.transactRequests(ctx.binding.worktree, (records) =>
     new Set(records.map((record) => record.requestId)));
-  const replies: RepresentativeReply[] = [];
-  for (const entry of page.entries) {
-    const addressed = isAddressedCoordinatorEntry(ctx.binding, entry);
-    if (addressed === null || (addressed === 'broadcast' && input.include_broadcast !== true)) continue;
-    const quoted = (entry.message.match(UUID_SCAN_RE) ?? []).map((id) => id.toLowerCase());
-    replies.push({
-      entry_id: entry.id,
-      created_at: entry.created_at,
-      from_drone_id: ctx.binding.coordinatorDroneId,
-      from_label: ctx.binding.coordinatorLabel,
-      addressed,
-      in_reply_to: quoted.find((id) => requestIds.has(id)) ?? null,
-      message: entry.message,
-      ...(entry.documents?.length ? {
-        documents: entry.documents,
-        document_delivery: 'Document bodies are not included and cannot be fetched through this connection. Ask the Coordinator to provide the content through a supported channel.',
-      } : {}),
-    });
+
+  // Deliberate ceiling: every read scans the cube log from the checkpoint,
+  // including entries not addressed here, so an undelivered backlog costs a
+  // growing scan. Upgrade path: a separate scan hint that deliver advances.
+  // One addressed entry beyond `limit` is collected only to answer has_more.
+  const candidates: Array<{ reply: RepresentativeReply; point: LocalServerCursor; ignoredBefore: number }> = [];
+  let ignored = 0;
+  let cursor = state.checkpoint;
+  let last = state.checkpoint;
+  scan: for (;;) {
+    const page = await ctx.backend.readAfter(cursor, READ_SCAN_PAGE);
+    for (const entry of page.entries) {
+      const point = { id: entry.id, created_at: entry.created_at };
+      // Client-side (created_at, id) filter: never repeat or regress.
+      if (comparePoints(point, last) <= 0) continue;
+      last = point;
+      const addressed = isAddressedCoordinatorEntry(ctx.binding, entry);
+      if (addressed === null || (addressed === 'broadcast' && input.include_broadcast !== true)) { ignored += 1; continue; }
+      const quoted = (entry.message.match(UUID_SCAN_RE) ?? []).map((id) => id.toLowerCase());
+      candidates.push({ point, ignoredBefore: ignored, reply: {
+        entry_id: entry.id,
+        created_at: entry.created_at,
+        from_drone_id: ctx.binding.coordinatorDroneId,
+        from_label: ctx.binding.coordinatorLabel,
+        addressed,
+        in_reply_to: quoted.find((id) => requestIds.has(id)) ?? null,
+        message: entry.message,
+        ...(entry.documents?.length ? {
+          documents: entry.documents,
+          document_delivery: 'Document bodies are not included and cannot be fetched through this connection. Ask the Coordinator to provide the content through a supported channel.',
+        } : {}),
+      } });
+      if (candidates.length > limit) break scan;
+    }
+    const tail = page.entries.at(-1);
+    if (!page.has_more || !tail) break;
+    cursor = { id: tail.id, created_at: tail.created_at };
+  }
+
+  const result = (count: number, oversize = false) => {
+    const taken = candidates.slice(0, count);
+    const replies: RepresentativeReply[] = taken.map(({ reply }, index) =>
+      (oversize && index === 0 ? { ...reply, oversize: true as const } : reply));
+    return {
+      replies,
+      checkpoint: checkpointView(state.checkpoint),
+      has_more: candidates.length > count,
+      ignored_entries: count < candidates.length ? candidates[count].ignoredBefore : ignored,
+      binding_fingerprint: bindingFingerprint(ctx.binding),
+      delivery: REPRESENTATIVE_DELIVERY_NOTE,
+    };
+  };
+  // Measure the real serialized result; entries are whole or omitted.
+  let count = 0;
+  while (count < Math.min(limit, candidates.length) &&
+    Buffer.byteLength(serializeRepresentativeResult(result(count + 1))) <= maxBytes) count += 1;
+  const oversize = count === 0 && candidates.length > 0;
+  let final = result(oversize ? 1 : count, oversize);
+  const bound = Math.max(maxBytes, REPRESENTATIVE_ENVELOPE_FLOOR);
+  if (oversize && final.replies[0].documents?.length &&
+      Buffer.byteLength(serializeRepresentativeResult(final)) > bound) {
+    const reply = final.replies[0];
+    final = { ...final, replies: [{
+      ...reply, documents: reply.documents!.map(({ id }) => ({ id }) as DocumentCitation), documents_reduced: true as const,
+    }] };
+  }
+  const measured = Buffer.byteLength(serializeRepresentativeResult(final));
+  if (oversize && measured > bound) {
+    // Nothing is cut or overrun, and nothing moves: no content, no deliver.
+    throw new RepresentativeError('REPRESENTATIVE_READ_OVERSIZE',
+      `The next reply does not fit ${bound} bytes even alone with its citations reduced to ids. Nothing was read or ` +
+      'advanced. Raise max_bytes (up to 60000); beyond that the operator must reduce the server post limit.',
+      { entry_id: final.replies[0].entry_id, measured_bytes: measured, bound });
+  }
+  await commit();
+  const window = candidates.slice(0, final.replies.length).map(({ point }) => point);
+  if (window.length > 0) {
+    // The deliver fence and membership widen before the caller sees the entries.
+    await createDeliveryStore(ctx.binding).advance({ readThrough: window.at(-1)!, returned: window }, ctx.guard);
+  }
+  return final;
+  });
+}
+
+export async function deliverRepresentativeReplies(
+  ctx: RepresentativeContext,
+  raw: unknown,
+): Promise<{ checkpoint: { entry_id: string | null; created_at: string | null }; advanced: boolean; binding_fingerprint: string }> {
+  const input = (raw ?? {}) as Record<string, unknown>;
+  const unknown = Object.keys(input).filter((key) => key !== 'through');
+  if (unknown.length > 0 || !isRepresentativeUuid(input.through)) {
+    throw new RepresentativeError(ErrorCode.INVALID_INPUT, 'through must be the full UUID of a reply returned by borg_representative-read.');
+  }
+  const through = input.through;
+  await verifyLiveBinding(ctx);
+  return withDeliveryState(ctx, async (state, commit) => {
+  await commit();
+  const outside = () => new RepresentativeError('REPRESENTATIVE_DELIVER_UNKNOWN_ENTRY',
+    'That entry is not in the current read window: deliver only a reply that borg_representative-read returned. Nothing changed.');
+  let entry: LogEntry;
+  try {
+    ({ entry } = await ctx.backend.readEntry(through));
+  } catch (error) {
+    if ((error as { status?: unknown })?.status === 404) throw outside();
+    throw error;
   }
+  if (entry.id !== through || isAddressedCoordinatorEntry(ctx.binding, entry) === null) throw outside();
+  const point = { id: entry.id, created_at: entry.created_at };
+  const fingerprint = bindingFingerprint(ctx.binding);
+  if (state.checkpoint && comparePoints(point, state.checkpoint) <= 0) {
+    return { checkpoint: checkpointView(state.checkpoint), advanced: false, binding_fingerprint: fingerprint };
+  }
+  // Membership of the full tuple, not the range or the id alone: only an entry
+  // a read actually returned, as the server reports it now, inside the window.
+  if (!state.returned.some((returned) => returned.id === point.id && returned.created_at === point.created_at) ||
+      state.readThrough === null || comparePoints(point, state.readThrough) > 0) throw outside();
+  const { before, after } = await createDeliveryStore(ctx.binding).advance({ checkpoint: point }, ctx.guard);
   return {
-    replies,
-    ignored_entries: page.entries.length - replies.length,
-    has_more: page.has_more === true,
-    delivery: REPRESENTATIVE_DELIVERY_NOTE,
+    checkpoint: checkpointView(after.checkpoint),
+    // The serialized transition, not this call's earlier snapshot.
+    advanced: comparePoints(after.checkpoint!, before?.checkpoint ?? null) > 0,
+    binding_fingerprint: fingerprint,
   };
+  });
 }
 
 export async function ackRepresentativeReply(
@@ -661,6 +858,9 @@ export async function representativeStatus(ctx: RepresentativeContext): Promise<
   unresolved_requests: Array<{ request_id: string; state: string; kind: string; updated_at: string }>;
   delivery: string;
   authority: string;
+  binding_fingerprint: string;
+  checkpoint_problem?: { code: string; message: string };
+  envelope_floor: number;
 }> {
   const { binding } = ctx;
   let problem: { code: string; message: string } | undefined;
@@ -672,6 +872,12 @@ export async function representativeStatus(ctx: RepresentativeContext): Promise<
       message: error instanceof Error ? error.message : 'Unknown error',
     };
   }
+  let checkpointProblem: { code: string; message: string } | undefined;
+  try {
+    await createDeliveryStore(binding).load();
+  } catch (error) {
+    checkpointProblem = { code: (error as { code?: string }).code ?? 'BACKEND_ERROR', message: error instanceof Error ? error.message : 'Unknown error' };
+  }
   const unresolved = (await ctx.store.readRequests(binding.worktree))
       .filter((record) => record.state === 'pending' || record.state === 'ambiguous')
       .map((record) => ({
@@ -695,5 +901,8 @@ export async function representativeStatus(ctx: RepresentativeContext): Promise<
     authority:
       'Borg records these messages as posts from the representative drone. The user-authorized / model-advice label is this ' +
       'connection\'s own attribution and is not verified or enforced by the Borg server.',
+    binding_fingerprint: bindingFingerprint(binding),
+    ...(checkpointProblem ? { checkpoint_problem: checkpointProblem } : {}),
+    envelope_floor: REPRESENTATIVE_ENVELOPE_FLOOR,
   };
 }