borgmcp 5.5.0 → 5.6.0

package/docs/HUMAN_REPRESENTATIVE.md

@@ -70,9 +70,14 @@ To resume later, run `borg representative prepare --coordinator <coordinator-dro
 your saved labels. Recovery errors for a bound connection print that complete
 command with its actual labels and worktree. Changing the cube or Coordinator
 is refused unless you
-pass `--rebind`; a rebind also discards the old request ledger. A running
-`borg representative mcp` process never picks up a rebind: its calls fail
-closed until the MCP host restarts it.
+pass `--rebind`; a rebind that changes the cube or Coordinator also discards the
+old request ledger. A rebind of any kind, including one with the same cube and
+Coordinator, requires restarting every adapter and the listener; running ones
+refuse. A running `borg representative mcp` process answers `send`, `read`,
+`deliver` and `ack` with `BINDING_MISMATCH` until the MCP host restarts it;
+its `status` reports the new `binding_fingerprint` beside the
+`pinned_binding_fingerprint` it started with. A running listener stops with
+reason `rebound`.
 
 `prepare` reuses Borg's connection and worktree preparation, including its
 private-state initialization and saved-connection checks. It does not require
@@ -114,9 +119,10 @@ Check a connection at any time with
 
 | Tool | Purpose |
 | --- | --- |
-| `borg_representative-status` | Bound cube, representative, Coordinator; live re-check; unresolved sends; limits. |
+| `borg_representative-status` | Bound cube, representative, Coordinator; live re-check; unresolved sends; limits; `binding_fingerprint`. |
 | `borg_representative-send` | Relay one `request`, `question` or `decision` to the bound Coordinator. |
-| `borg_representative-read` | Unread replies from the bound Coordinator addressed to the representative. Drains everything it fetches. |
+| `borg_representative-read` | The bound Coordinator's replies after the delivered checkpoint, oldest first, bounded. Changes nothing. |
+| `borg_representative-deliver` | Move the delivered checkpoint through a reply the host has durably persisted. |
 | `borg_representative-ack` | Signal to the Coordinator that one direct reply was received. Nothing more. |
 
 There is no tool for logging to other drones, broadcasting, role or drone
@@ -202,32 +208,111 @@ Exactly-once delivery is therefore not claimed; at-most-once per `request_id`
 relies on the server honouring `post_id` deduplication as the shared protocol
 specifies, and on the single-process rule below.
 
-## Reading, cursors and wake limits
-
-- `read` drains only the representative drone's **own** unread cursor. Other
-  drones' cursors are separate client-owned state and are never touched.
-- A read **consumes everything it fetched**, not only what it returns: the
-  Coordinator's replies, and equally the entries it ignores (other drones'
-  entries are counted in `ignored_entries` and never returned; the
-  Coordinator's broadcasts are returned only with `include_broadcast`). None
-  of them appear unread again.
-- If the MCP host stops between reading a reply and relaying it to the human,
-  that reply is gone from the unread view. It still exists in the cube log, but
-  this version offers no tool to list past replies again. Persist the read result
-  in the host before relaying it.
+## Reading, delivery and wake limits
+
+Four separate notions, each with its own tool or owner:
+
+- **Receipt**: `read` returned the reply. Nothing moves; the same reply comes back
+  on every `read` until it is delivered.
+- **Delivered**: the host called `deliver` after durably persisting everything up
+  to that reply. Only `deliver` moves the read window.
+- **Processing and display**: the host's own business after delivery.
+- **`ack`**: a signal to the Coordinator that a direct reply was received. It is
+  not delivery and does not move the window.
+
+Reading:
+
+- `read` returns the Coordinator's replies addressed to the representative that
+  come strictly after the delivered checkpoint, in `(created_at, entry_id)` order.
+  Other drones' entries are counted in `ignored_entries` and never returned; the
+  Coordinator's broadcasts are returned only with `include_broadcast`.
+- `read` never advances anything: not the checkpoint, not the representative's
+  unread cursor, not a server cursor. After a crash at any point, the next `read`
+  returns every reply not yet delivered.
+- Bounds: `limit` (1 to 50, default 10) is a hard cap on returned replies.
+  `max_bytes` (4096 to 60000, default 32768) caps the serialized tool result.
+  Replies are whole or omitted, never truncated; a reply that alone exceeds
+  `max_bytes` is returned alone with `"oversize": true`. The serialized result
+  never exceeds `max(max_bytes, 16384)` bytes: if an oversize reply is still
+  larger than that, its document citations are reduced to ids and it carries
+  `"documents_reduced": true`; message text is never cut. `status` reports this
+  floor as `envelope_floor`; set the host's tool-result ceiling at or above it.
+  The floor covers a message at the server's default post limit (4096 bytes)
+  with ordinary metadata. JSON escaping (a message full of tabs or quotes) or
+  heavy citation metadata can still push a single reply above it, as can a
+  server that allows larger posts. Then `read` refuses with
+  `REPRESENTATIVE_READ_OVERSIZE` (`entry_id`, `measured_bytes`, `bound`) and
+  changes nothing; retry with a larger `max_bytes` (up to 60000).
+- `read` scans past entries that are not for the representative until the page
+  is full or the log ends, so it never returns no replies with `has_more: true`.
+  `has_more` is true only when another reply follows the returned window.
+  Page by delivering and reading again.
+- The result includes `checkpoint` (`entry_id` and `created_at`; null until the
+  first delivery, unless the upgrade below started it at the old read position)
+  and `binding_fingerprint`.
+
+Delivering:
+
+- `deliver` takes `{ "through": "<entry_id>" }` and moves the checkpoint to that
+  reply. Call it only after the host has durably persisted every reply up to it.
+- `through` must be a reply that `read` actually returned since the checkpoint
+  last moved; membership is checked, not only the range, so a broadcast skipped
+  by a read without `include_broadcast` is refused too. Any other entry is refused
+  with `REPRESENTATIVE_DELIVER_UNKNOWN_ENTRY` and nothing changes. The same or an older
+  id is a no-op that returns `advanced: false`, so a retry after a lost result is safe.
+- Implementation note: the checkpoint, an internal read fence (the latest reply
+  any `read` returned) and the replies returned since the checkpoint last moved
+  are stored together in one private file per binding, written atomically.
+  `deliver` accepts only one of those returned replies. None of this is part of
+  the interface.
+
+Binding fence:
+
+- `binding_fingerprint` is the hex SHA-256 of the canonical JSON array
+  `[origin, trustIdentity, cubeId, representativeDroneId, coordinatorDroneId, boundAt]`.
+  It changes on every rebind and on a server trust change, and contains no path or
+  credential. `prepare --rebind` always starts a new generation, even when the
+  cube and Coordinator stay the same. It appears in `status`, `read`, `send`, `deliver` and the listener's
+  `listening` event. Persist it at binding time; if any result shows a different
+  value, stop routing and hold for the human.
+
+Upgrading from a version without `deliver`:
+
+- The first `read` or `deliver` for a binding starts the checkpoint where the old
+  destructive read left the representative's unread cursor: replies that were
+  unread at upgrade time are returned, replies already read are not. When the
+  binding never read, every addressed reply in the cube log is returned. If the
+  upgrade is interrupted before its checkpoint is written, the next read returns
+  every addressed reply instead; deduplicate by `entry_id`.
+  The old position is taken only from a genuine private file (a regular file you
+  own, not a symlink, not writable by group or others, in the private config
+  directory); otherwise the checkpoint starts empty and every addressed reply is
+  returned.
+- That upgrade happens once per representative drone and server authority, and is
+  recorded in a private marker, so it never runs again, even after a checkpoint
+  file is removed. A later
+  binding generation (any `prepare --rebind`, or a trust change) starts with an
+  empty checkpoint, so its first read returns its addressed history. Deduplicate by
+  `entry_id` (the host persists everything it delivers) and page with `limit`.
+
+Known limits:
+
+- Retention is the server's cube log; the local inbox is not a content source.
+- Each `read` scans the cube log from the checkpoint, including entries not
+  addressed to the representative, so a host that never calls `deliver` pays a
+  growing scan. Deliver promptly.
 - Replies preserve document citations (id, title and state). Document bodies are
   not included and cannot be fetched through this connection. Ask the Coordinator
   to provide the content through a supported channel.
-- `limit` is a page-size hint, not a hard cap: when the unread backlog is
-  large the client's digest mode fetches, and drains, more than `limit`.
-- `ack` is only a signal to the Coordinator that a direct reply was received.
-  It does not make delivery reliable, and it neither advances nor restores the
-  unread cursor.
+
+Ownership:
+
 - Exclusive process ownership is enforced for each representative drone. Processes
-  may start idle; the first `send`, `read` or `ack` takes the lease. Other processes
-  receive `REPRESENTATIVE_OWNERSHIP_REQUIRED` before any ledger reservation or
-  write, cursor access, or network call. The refusal names the owner's PID and
-  start time. Use that host, or wait for it to exit before using another.
+  may start idle; the first `send`, `read`, `deliver` or `ack` takes the lease. Other
+  processes receive `REPRESENTATIVE_OWNERSHIP_REQUIRED` before any ledger
+  reservation, delivery-state write, cursor access or network call. The refusal
+  names the owner's PID and start time. Use that host, or wait for it to exit before
+  using another.
 - `status` is allowed in every process, is read-only, and takes no lease. Its
   `ownership` field reports the state, PID, start time, and heartbeat age in
   milliseconds (`ageMs`). A clean exit releases ownership; a dead PID or a
@@ -238,20 +323,97 @@ specifies, and on the single-process rule below.
   deduplication. Retry an ambiguous send with its original `request_id`.
 - `in_reply_to` is a textual match of a known `request_id` quoted in the reply.
   It is a convenience, not a protocol guarantee.
-- **There is no background wake.** A generic MCP host receives nothing
-  unsolicited: replies are seen only when the host calls
-  `borg_representative-read`. This version provides explicit send/read round
-  trips only and makes no claim of automatic ongoing coordination. The
-  Coordinator is woken by the direct message through its own normal wake path.
+
+Wake hints:
+
+- **The MCP process does not push content.** A separate supervised `listen`
+  process emits body-free wake hints. The owning adapter still calls `read` for
+  content. Hints are neither delivery receipts nor authority.
+- Live dedupe is bounded to the surviving inbox tail and recent IDs; an ancient
+  trimmed ID sent again as a live event can produce a duplicate hint. Ordered
+  catch-up also dedupes against its captured resume cursor.
+- The listener retains a bounded tail: above 1024 lines it trims to the latest
+  512. Lost-hint replay covers only that tail; beyond it `read` from the delivered
+  checkpoint is the source of truth. On every `gap`, call `read`.
 
 ### Host conversation routing
 
 The lease selects one consuming process, not a conversation within that host.
 The host must record which conversation owns each `request_id`, persist every
-read result before relaying it, and route replies using `in_reply_to`. Hold
-replies with an unknown or missing request ID for the human instead of dropping
-them. Borg cannot enforce these duties inside the host; it provides neither a
-durable inbox nor a separate unread cursor for each conversation.
+reply durably before calling `deliver`, and route replies using `in_reply_to`.
+Hold replies with an unknown or missing request ID for the human instead of
+dropping them. Borg cannot enforce these duties inside the host; it provides one
+delivered checkpoint per binding, not one per conversation. The listener inbox
+is private client state, not a host content API.
+
+## Supervised listener
+
+For a prepared connection, run a separate long-lived subprocess:
+
+```bash
+borg representative listen --worktree <path>
+```
+
+Supervise it and persist the last `entry_id` durably admitted to the host's work
+queue. On subsequent starts, pass that checkpoint:
+
+```bash
+borg representative listen --worktree <path> --replay-after <entry_id>
+```
+
+There is one listener lease per representative drone and server authority,
+independent of the lazy tools lease. A second listener refuses without consuming
+or appending anything. A dead owner or expired heartbeat permits takeover; a
+process that loses ownership exits and must be restarted. A local lease cannot
+cancel an already-issued request. No eager tools-lease option is needed when one
+adapter exclusively calls `send`, `read`, `deliver` and `ack`.
+
+`representative status` reports `listener` beside tool `ownership`: running
+state, owner PID and start time, heartbeat age (`ageMs`), persisted watermark and
+private inbox path. Status acquires nothing. Do not read the inbox or depend on
+its pathname; it is not the content-delivery interface.
+
+Stdout is newline-delimited JSON only. Stderr contains human diagnostics and
+must not be parsed. The host must ignore unknown fields and unknown event types.
+
+| Event | Fields and meaning |
+| --- | --- |
+| `refused` | The only stdout line on startup refusal: `code`, `exit_code`. Another listener uses `REPRESENTATIVE_LISTENER_OWNED`, plus `owner_pid` and `owner_started_at`. |
+| `listening` | Once connected and holding the lease: `cube_id`, `drone_id`, `binding_fingerprint`, `watermark` (entry id or null), `inbox`. |
+| `entry` | `entry_id`, `created_at`, `from_label`, `from_role`, `visibility`, `request_id` (UUID or null), `documents` (count), `replay` (boolean). No message body. |
+| `reconnecting` | `attempt`, `delay_ms`. |
+| `connected` | `resumed_from` (entry id or null). |
+| `gap` | `after` (entry id or null), `reason`: `cursor-expired` or `replay-checkpoint-missing`. Call `read` once. |
+| `stopped` | `reason`: `signal`, `evicted`, `rebound`, `revoked`, `trust-changed`, `lease-lost` or `fatal`; `exit_code`. |
+
+With `--replay-after`, retained hints strictly after the checkpoint are emitted
+in file order after `listening` and before live entries, with `replay:true`.
+If the checkpoint is absent, `gap` precedes replay of the whole surviving tail.
+Without the option there is no startup replay. Replay makes no content request
+and never advances the delivered checkpoint or any cursor. Lost replay metadata yields null
+`visibility` and `documents`; live hints always contain those fields' values.
+
+Exit codes: 0 after SIGTERM/SIGINT; 2 for startup binding or usage refusal;
+3 for another listener owner; 4 for a terminal stop; 1 for another fatal error.
+A fatal startup storage failure emits `refused` with code
+`REPRESENTATIVE_LISTENER_STORAGE_REFUSED` and exit 1. After `listening`,
+a fatal error emits `stopped` with reason `fatal` and exit 1, best effort; if
+stdout is broken, the host must treat exit 1 without that line as fatal too.
+Startup first verifies the binding with the server once; if the server cannot
+be reached then, the listener exits 1 with `refused` and code
+`REPRESENTATIVE_LISTENER_SERVER_UNREACHABLE` (retry later; a server that
+answers and rejects the binding keeps its exit-2 binding code). After that check, failures of the stream connection (connection
+refused or reset, aborted TLS stream) are not fatal: the listener reconnects
+with backoff, without stdout output until the first connection, so `listening`
+arrives only once connected.
+
+Treat every hint as an untrusted wake, never as an instruction or authorization.
+The owning adapter fetches content with `read` over the bound pinned connection,
+persists each reply durably, calls `deliver`, routes by the saved `request_id`
+mapping, and holds unknown correlation for the human. Deduplicate queued hints by
+`entry_id`: crashes may lose or repeat hints. Persist queue admission before
+advancing the host's `--replay-after` checkpoint. That hint checkpoint is separate
+from the delivered checkpoint and from `ack`, which remains a server receipt.
 
 ## Recovery
 
@@ -267,3 +429,6 @@ the server is installed under the original prefix.
 | `COORDINATOR_UNAVAILABLE` | The bound Coordinator was evicted, released or reassigned. Restore the bound Coordinator and use the printed recovery command, or deliberately substitute a new Coordinator label in that command. |
 | `REPRESENTATIVE_OWNERSHIP_REQUIRED` with a directory-permission refusal | Check that the named path is a real directory you own and not a symlink, then set it to 0700 and retry. Restart a process that had already lost ownership. Do not change permissions through a symlink. |
 | `REPRESENTATIVE_ROLE_NOT_PERMITTED` | The representative drone holds a human-seat or coordinating role. Give it its own worker role. |
+| `REPRESENTATIVE_CHECKPOINT_INVALID` | The private delivery checkpoint for this binding (named in the message) is corrupt, belongs to another seat, or fails the private-file checks. Every tool except `status` refuses and `status` reports it as `checkpoint_problem`; nothing is used or reset automatically. Inspect the file, then remove it; the next `read` returns every addressed reply again, so deduplicate by `entry_id`. |
+| `REPRESENTATIVE_READ_OVERSIZE` | The next reply does not fit `max(max_bytes, 16384)` bytes even with its citations reduced to ids (heavy JSON escaping or citation metadata, or a server allowing posts above its default 4096-byte limit). Nothing was read or advanced. Retry with a larger `max_bytes` (up to 60000); beyond that the operator must lower the server's post limit. |
+| `REPRESENTATIVE_DELIVER_UNKNOWN_ENTRY` | `deliver` named an entry that `read` has not returned (or no Coordinator reply). Nothing changed. Call `read`, persist what it returns, then deliver through its last `entry_id`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",

package/src/claude.ts

@@ -395,6 +395,11 @@ async function main() {
     const representative = await import('./representative-cmd.js');
     const parsed = representative.parseRepresentativeArgs(process.argv.slice(3));
     if (!parsed.ok) {
+      if (process.argv[3] === 'listen') {
+        process.stdout.write(JSON.stringify({ event: 'refused', code: 'INVALID_INPUT', exit_code: 2 }) + '\n');
+        process.stderr.write(parsed.error + '\n');
+        process.exit(2);
+      }
       process.stderr.write(chalk.red(`${consolePrefix()}◼ borg representative: ${parsed.error}\n`));
       process.stderr.write(`Run \`borg representative --help\` for usage.\n`);
       process.exit(1);
@@ -407,6 +412,9 @@ async function main() {
       process.exit(await representative.runRepresentativeStatus(parsed.command, deps));
     }
     const { pinMcpSeatIdentity } = await import('./cubes.js');
+    if (parsed.command.action === 'listen') {
+      process.exit(await representative.runRepresentativeListen(parsed.command, deps));
+    }
     process.exit(await representative.runRepresentativeMcp(parsed.command, deps, {
       version: getPackageVersion(),
       pinSeat: pinMcpSeatIdentity,

package/src/cli-help.ts

@@ -129,6 +129,7 @@ export function representativeHelpText(version: string): string {
     `  borg representative prepare --coordinator <drone-label> [--role <name>] [--worktree <name>] [--host <host>] [--rebind]\n` +
     `  borg representative status [--worktree <path>]\n` +
     `  borg representative mcp [--worktree <path>]\n` +
+    `  borg representative listen --worktree <path> [--replay-after <entry_id>]\n` +
     `  borg representative --help\n\n` +
     `Commands:\n` +
     `  prepare   Create or resume the representative's own drone in this repository's cube and bind it to\n` +
@@ -136,18 +137,20 @@ export function representativeHelpText(version: string): string {
     `            Fails if that Coordinator is missing, evicted, duplicated, or not in the human seat;\n` +
     `            another drone is never chosen instead.\n` +
     `  status    Show the saved binding, re-check it against the live cube, and list unresolved sends.\n` +
-    `  mcp       Serve the restricted stdio MCP tools (status, send, read, ack) for a generic MCP host.\n\n` +
+    `  mcp       Serve the restricted stdio MCP tools (status, send, read, deliver, ack) for a generic MCP host.\n` +
+    `  listen    Emit body-free JSON wake hints from the server stream; supervise this separate process.\n\n` +
     `Options:\n` +
+    `  --replay-after <entry_id>    listen: replay later retained hints after the last durably enqueued entry\n` +
     `  --coordinator <drone-label>  Exact label of the Coordinator drone (see \`borg drones\`). Required for prepare.\n` +
     `  --role <name>                Existing non-human-seat role for the representative (default: hermes-representative)\n` +
     `  --worktree <name>            prepare: create the drone in a new linked worktree of that name\n` +
-    `  --worktree <path>            status/mcp: absolute path of the prepared representative worktree\n` +
+    `  --worktree <path>            status/mcp/listen: absolute path of the prepared representative worktree\n` +
     `  --host <host>                prepare: explicit Borg server, as in \`borg assimilate --host\`\n` +
     `  --rebind                     prepare: explicitly replace the saved cube/Coordinator selection\n` +
     `  --help, -h                   Show this help\n\n` +
-    `Limits: explicit send/read round trips only — there is no background wake or push to the MCP host.\n` +
-    `Reading drains everything it fetches, so relay replies at once; ack is only a signal to the Coordinator.\n` +
-    `Run exactly one MCP host process per representative worktree (not enforced).\n` +
+    `Limits: the MCP process has no background wake; a separate listen process emits wake hints, not content.\n` +
+    `Reading changes nothing: persist replies durably, then deliver through the last one. On a listener gap, call read.\n` +
+    `The first send/read/deliver/ack takes an exclusive tools lease; listen owns a separate exclusive listener lease.\n` +
     `A retried send reuses its request id so the server stores it once; an unknown outcome is reported as\n` +
     `ambiguous, with its cause, and never re-sent automatically. "User-authorized" is the representative's own label:\n` +
     `the Borg server does not verify it, and one relayed decision is not broader human approval.\n` +
@@ -230,7 +233,7 @@ export function topLevelHelpText(version: string): string {
     `  borg drones              List this machine's registered drones and worktrees\n` +
     `  borg launch <drone-label-or-id-prefix>  Reopen one registered drone from its worktree\n` +
     `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
-    `  borg representative prepare|status|mcp  Let an MCP host (e.g. Hermes) speak for you to one Coordinator drone\n` +
+    `  borg representative prepare|status|mcp|listen  Let an MCP host (e.g. Hermes) speak for you to one Coordinator drone\n` +
     `  borg server <command> [arguments]\n` +
     `  borg --cli claude|codex|opencode  Launch that agent CLI directly\n` +
     `  borg --version           Show installed version\n\n` +

package/src/docs-sections.ts

@@ -96,7 +96,7 @@ export const DOCS_SECTIONS: DocsSection[] = [
     slug: "human-representative",
     title: "Human representative",
     url: HUMAN_REPRESENTATIVE_URL,
-    summary: "A separate non-human-seat drone that relays the human's requests and decisions to one bound Coordinator over a restricted stdio MCP facade: prepare, host configuration, idempotent sends, no background wake.",
+    summary: "A separate non-human-seat drone that relays the human's requests and decisions to one bound Coordinator over a restricted stdio MCP facade: prepare, host configuration, idempotent sends, replayable bounded reads with a delivered checkpoint, and supervised listener hints.",
     keywords: ["representative", "hermes", "human representative", "delegate", "proxy", "borg representative", "borg_representative-send", "mcp host", "request_id", "ambiguous"],
   },
   {

package/src/local-server-cursor.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { borgConfigRoot } from './private-root.js';
 
@@ -146,6 +147,49 @@ export async function getLocalServerCursor(
   return state.cursors[key] ?? null;
 }
 
+/**
+ * Fail-closed read for importing the unread watermark into other private
+ * state. The product writes this file 0600 (writeState); a symlink, a file
+ * that is not a regular file, not owned by this user, or group- or
+ * world-writable, and any unparsable state all read as null, never as a
+ * position. Read-only: nothing is written or locked. The caller validates
+ * the private root the file lives in.
+ */
+export async function readPrivateLocalServerCursor(
+  binding: LocalServerCursorBinding,
+): Promise<LocalServerCursor | null> {
+  // lstat first: a FIFO or device is refused without ever being opened (an
+  // open would block). The non-blocking open and the identity recheck keep a
+  // swapped-in object from being read in its place.
+  let before;
+  try {
+    before = await lstat(CURSOR_FILE);
+  } catch {
+    return null;
+  }
+  if (!before.isFile()) return null;
+  let handle;
+  try {
+    handle = await open(CURSOR_FILE, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch {
+    return null;
+  }
+  try {
+    const metadata = await handle.stat();
+    if (metadata.dev !== before.dev || metadata.ino !== before.ino) return null;
+    if (!metadata.isFile() || (metadata.mode & 0o022) !== 0 ||
+        (typeof process.getuid === 'function' && metadata.uid !== process.getuid())) return null;
+    const parsed = JSON.parse(await handle.readFile('utf8')) as Partial<CursorFile>;
+    if (parsed?.version !== 1 || typeof parsed.cursors !== 'object' || parsed.cursors === null) return null;
+    const cursor = parsed.cursors[cursorKey(binding)];
+    return validCursor(cursor) ? { id: cursor.id, created_at: cursor.created_at } : null;
+  } catch {
+    return null;
+  } finally {
+    await handle.close();
+  }
+}
+
 export async function advanceLocalServerCursor(
   binding: LocalServerCursorBinding,
   cursor: LocalServerCursor,

package/src/log-stream.ts

@@ -61,7 +61,7 @@ import {
 } from './codex-app-wake.js';
 import { formatCubeActivityWakeMessage } from './cube-activity-wake-copy.js';
 import { readBoundedResponseBody } from './server-response.js';
-import { BorgServerError } from './server-errors.js';
+import { BorgServerError, BorgServerTrustError } from './server-errors.js';
 import { markSeatRejected } from './seats.js';
 import { formatDocumentCitations } from './document-render.js';
 import { hasPendingWakeEntry as hasPendingDurableWakeEntry } from './remote-client.js';
@@ -378,7 +378,22 @@ export function startLogStream(opts: { runForever?: () => void } = {}): void {
 // Dependency injection seams (for tests)
 // ------------------------------------------------------------------
 
+/** Production adapter for a separate private stream consumer. Ordinary drone defaults are unchanged. */
+export function streamReconnectDelay(attempt: number): number {
+  return Math.min(RECONNECT_MIN_MS * 2 ** attempt, RECONNECT_MAX_MS) + Math.random() * 500;
+}
+
+export interface StreamConsumer {
+  /** Retained dedupe horizon when an expired wire resume cursor has been cleared. */
+  catchupCursor?: LocalServerCursor | null;
+  connected(): Promise<void>;
+  beforeEvent(): Promise<void>;
+  log(event: Extract<ParsedEvent, { type: 'log' }>, catchupCursor: LocalServerCursor | null): Promise<void>;
+  clearCursor(): Promise<void>;
+}
 export interface StreamDeps {
+  consumer?: StreamConsumer;
+
   /** Override the global fetch (tests inject a controlled Response). */
   fetchImpl?: typeof fetch;
   /** Override persisted trust loading to verify pre-network confinement. */
@@ -424,7 +439,7 @@ export interface StreamDeps {
   settleOpenCodeEntry?: (sourceEntryId: string) => void;
 }
 
-const defaultDeps: Required<StreamDeps> = {
+const defaultDeps: Required<Omit<StreamDeps, 'consumer'>> = {
   fetchImpl: globalThis.fetch.bind(globalThis),
   loadTrust: loadBorgServerTrust,
   getCursor: getLocalServerCursor,
@@ -636,8 +651,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
       }
       streamState.connected = false;
       const delay =
-        Math.min(RECONNECT_MIN_MS * 2 ** attempt, RECONNECT_MAX_MS) +
-        Math.random() * 500;
+        streamReconnectDelay(attempt);
       process.stderr.write(
         `[borg-mcp log stream] reconnect in ${Math.round(delay)}ms: ${err?.message ?? err}\n`
       );
@@ -685,6 +699,8 @@ export async function streamOnce(
   onEventId: (id: string) => void,
   deps: StreamDeps = {}
 ): Promise<void> {
+  // A representative consumer must never alter borg_stream-status's singleton.
+  const state = deps.consumer ? { ...streamState } : streamState;
   const {
     fetchImpl,
     loadTrust,
@@ -714,6 +730,7 @@ export async function streamOnce(
   if (deps.fetchImpl === undefined) {
     const trust = await loadTrust(active.apiUrl);
     if (trust.identity !== active.serverTrustIdentity) {
+      if (deps.consumer) throw new BorgServerTrustError('Borg server trust identity changed; refusing the stream');
       throw new Error('Borg server trust identity changed; refusing the stream');
     }
     requestFetch = trust.fetchImpl;
@@ -804,7 +821,7 @@ export async function streamOnce(
     }
     lastPersistedHwm = next;
     lastPersistedEventId = id;
-    streamState.lastPersistedEventId = id;
+    state.lastPersistedEventId = id;
     onEventId(id);
   };
 
@@ -854,7 +871,7 @@ export async function streamOnce(
   // Set + FIFO array for O(1) membership + bounded memory.
   const recentIds = new Set<string>();
   const recentIdsOrder: string[] = [];
-  let isCatchingUp = lastEventId !== null || cursor !== null;
+  let isCatchingUp = lastEventId !== null || cursor !== null || deps.consumer?.catchupCursor != null;
 
   // gh#29 quality-stream (#5): shared inbox-write + cursor-advance helpers,
   // extracted from the previously-duplicated ack / regular-log branches in the
@@ -973,11 +990,13 @@ export async function streamOnce(
     });
   } catch (err) {
     if (watchdog) clearTimeout(watchdog);
+    if (deps.consumer) abortSignal.removeEventListener('abort', abortFromExternal);
     throw err;
   }
 
   if (!response.ok || !response.body) {
     if (watchdog) clearTimeout(watchdog);
+    if (deps.consumer) abortSignal.removeEventListener('abort', abortFromExternal);
     // gh#877 Path-B (stream bootstrap): an evicted drone's stream re-subscribe
     // returns the authoritative 410 DRONE_EVICTED. Surface it as the terminal
     // typed error so the reconnect loop stops retrying (B25) instead of backing
@@ -1034,34 +1053,36 @@ export async function streamOnce(
       // the dead cursor. The unread watermark (client#41) is untouched, so no
       // undrained wake is lost across the reset.
       if (code === CURSOR_EXPIRED_CODE) {
-        await clearLocalServerCursor({
+        await (deps.consumer ? deps.consumer.clearCursor() : clearLocalServerCursor({
           origin: active.apiUrl,
           trustIdentity: active.serverTrustIdentity,
           cubeId: active.cubeId,
           droneId: active.droneId,
           purpose: 'stream',
-        });
+        }));
         throw new StreamCursorExpiredError();
       }
     }
     throw new Error(`stream HTTP ${response.status}`);
   }
 
-  streamState.connected = true;
+  state.connected = true;
 
   try {
+    await deps.consumer?.connected();
     for await (const event of parseSSE(
       response.body,
       LOCAL_SERVER_SSE_FRAME_LIMIT_BYTES,
     )) {
+      await deps.consumer?.beforeEvent();
       bumpWatchdog();
       const nowIso = new Date().toISOString();
-      streamState.lastWireActivityAt = nowIso;
+      state.lastWireActivityAt = nowIso;
       // Content vs wire split (T1.2): content freshness is what a reader
       // skimming the top-line verdict actually cares about. Heartbeats
       // bump wire-activity only; log and bookmark events bump both.
       if (event.type === 'log' || event.type === 'bookmark') {
-        streamState.lastContentEventAt = nowIso;
+        state.lastContentEventAt = nowIso;
       }
 
       // gh#877 Path-A: terminal eviction control frame. Handled EARLY (before
@@ -1074,8 +1095,9 @@ export async function streamOnce(
       // (the client process cannot reach the agent loop); we only deliver the
       // wake. The reconnect's stream-bootstrap 410 (authoritative) is what flips
       // this loop terminal below.
+      if (event.type === 'eviction' && deps.consumer) break;
       if (event.type === 'eviction') {
-        streamState.lastContentEventAt = nowIso;
+        state.lastContentEventAt = nowIso;
         try {
           const line = formatEvictionSentinelLine(event.reason);
           await appendLine(
@@ -1103,7 +1125,7 @@ export async function streamOnce(
       }
 
       if (event.type === 'heartbeat') {
-        streamState.lastHeartbeatAt = nowIso;
+        state.lastHeartbeatAt = nowIso;
         // First/baseline heartbeat absorb: until this session has seen
         // a broadcast entry, the server's broadcast HWM is our baseline.
         // Direct messages may advance the persistence cursor past this
@@ -1142,6 +1164,16 @@ export async function streamOnce(
         isCatchingUp = false;
         continue;
       }
+      if (event.type === 'log' && deps.consumer) {
+        if (!recentIds.has(event.id)) {
+          await deps.consumer.log(event, isCatchingUp ? cursor ?? deps.consumer.catchupCursor ?? null : null);
+          recentIds.add(event.id); recentIdsOrder.push(event.id);
+          while (recentIdsOrder.length > RECENT_IDS_CAP) recentIds.delete(recentIdsOrder.shift()!);
+        }
+        markEventPersisted(event.id, event.data?.created_at ?? '');
+        markBroadcastPersisted(broadcastHwmFromLogEvent(event));
+        continue;
+      }
       if (event.type === 'log') {
         const isHeartbeatPing =
           typeof event.data?.message === 'string' &&
@@ -1264,7 +1296,8 @@ export async function streamOnce(
     abortSignal.removeEventListener('abort', abortFromExternal);
     if (watchdog) clearTimeout(watchdog);
     clearPendingHwmDivergence();
-    streamState.connected = false;
+    if (deps.consumer) ac.abort(); // release the transport when a consumer stops or throws
+    state.connected = false;
   }
 }
 

package/src/remote-client.ts

@@ -1100,6 +1100,9 @@ export async function readLog(
   apiUrl: string,
   opts: {
     since?: string;
+    /** Exact (created_at, id) resume point, strictly after; null = log start.
+     * Stateless: never reads or advances the unread cursor, never digest. */
+    cursor?: LocalServerCursor | null;
     limit?: number;
     unreadOnly?: boolean;
     serverTrustIdentity?: string;
@@ -1122,7 +1125,11 @@ export async function readLog(
     opts.serverTrustIdentity,
   );
   let cursor: LocalServerCursor | null = null;
+  if (opts.cursor !== undefined && (opts.unreadOnly || opts.since !== undefined)) {
+    throw new Error('readLog cursor cannot be combined with since or unreadOnly');
+  }
   if (opts.continuationGuard) await opts.continuationGuard();
+  if (opts.cursor !== undefined) cursor = opts.cursor;
   if (opts.unreadOnly) cursor = await getLocalServerCursor(localCursorBinding(local));
   if (opts.since !== undefined) cursor = await resolveLocalLogCursor(local, opts.since, opts.continuationGuard);
   let page = await localReadLogPage(local, {
@@ -1131,7 +1138,8 @@ export async function readLog(
     continuationGuard: opts.continuationGuard,
     // Keep the cursor payload stable across a lost response; do not re-read or
     // advance local state until one response has been decoded successfully.
-    ...(opts.unreadOnly && opts.since === undefined ? { retryMode: 'unread-cursor' as const } : {}),
+    // An exact-cursor read is stateless, so the same bounded retries are safe.
+    ...((opts.unreadOnly && opts.since === undefined) || opts.cursor !== undefined ? { retryMode: 'unread-cursor' as const } : {}),
   });
   if (opts.unreadOnly && page.cursor) {
     if (opts.continuationGuard) await opts.continuationGuard();