borgmcp 5.5.0 → 5.7.0

package/hermes-plugin/borg-representative-push/plugin.yaml

@@ -0,0 +1,39 @@
+name: borg-representative-push
+version: 1.0.0
+manifest_version: 2
+api_version: 1
+description: >-
+  Wakes one Hermes gateway conversation when the bound Borg Coordinator replies
+  to the human representative. Supervises `borg representative listen` inside
+  the messaging gateway and injects a fixed, body-free prompt; reply content is
+  only ever fetched by the conversation through borg_representative-read.
+license: Apache-2.0
+homepage: https://github.com/Byte-Ventures/borg-mcp-client
+tags: [borg, gateway, representative]
+# Hooks are registered only when the settings below are valid (a post_tool_call
+# observer for the deliver tool), so none is declared unconditionally here.
+config_schema:
+  session_key:
+    type: str
+    required: true
+    description: Gateway session key of the conversation to wake, e.g. agent:main:telegram:dm:<chat id>.
+  worktree:
+    type: str
+    required: true
+    description: Absolute path of the prepared representative worktree.
+  borg_command:
+    type: str
+    default: borg
+    description: The borg executable (borgmcp >= 5.6.0).
+  mcp_server:
+    type: str
+    default: borg-representative
+    description: Name of the mcp_servers entry that runs `borg representative mcp`.
+  reinject_after_s:
+    type: int
+    default: 600
+    description: Seconds before an undelivered reply wakes the conversation again.
+  max_reinjects:
+    type: int
+    default: 3
+    description: Maximum repeat wakes for one undelivered reply.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,6 +45,8 @@
     "dist",
     "src",
     "docs/*.md",
+    "hermes-plugin/borg-representative-push/plugin.yaml",
+    "hermes-plugin/borg-representative-push/__init__.py",
     "README.md",
     "LICENSE",
     "NOTICE",

package/src/claude.ts

@@ -395,10 +395,19 @@ 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);
     }
+    if (parsed.command.action === 'hermes-plugin-install') {
+      const install = await import('./hermes-plugin-install.js');
+      process.exit(await install.runHermesPluginInstall(parsed.command, install.defaultHermesPluginInstallDeps()));
+    }
     const deps = await representative.buildDefaultRepresentativeDeps();
     if (parsed.command.action === 'prepare') {
       process.exit(await representative.runRepresentativePrepare(parsed.command, deps));
@@ -407,6 +416,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,8 @@ 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 hermes-plugin install [--hermes-home <path>] [--force]\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 +138,26 @@ 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` +
+    `  hermes-plugin install\n` +
+    `            Copy the Borg-owned Hermes push plugin into <Hermes home>/plugins and print the config to add.\n` +
+    `            It wakes one Hermes messaging-gateway conversation (not a Desktop chat). Never edits Hermes\n` +
+    `            config and never starts or restarts Hermes.\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` +
+    `  --hermes-home <path>         hermes-plugin install: absolute Hermes home (default: $HERMES_HOME or ~/.hermes)\n` +
+    `  --force                      hermes-plugin install: replace the files of an existing install\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 +240,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|hermes-plugin  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/hermes-plugin-install.ts

@@ -0,0 +1,147 @@
+/**
+ * `borg representative hermes-plugin install`: copy the Borg-owned Hermes push
+ * plugin (hermes-plugin/borg-representative-push) into <Hermes home>/plugins.
+ *
+ * It only places the plugin's own files. It never edits Hermes config, never
+ * enables the plugin and never starts or restarts Hermes: the operator does
+ * those steps from the printed snippet.
+ */
+import { lstat, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HERMES_PLUGIN_NAME = 'borg-representative-push';
+/** Exactly the shipped files; nothing else in the source directory is copied. */
+export const HERMES_PLUGIN_FILES = ['plugin.yaml', '__init__.py'] as const;
+
+export interface HermesPluginInstallDeps {
+  env: NodeJS.ProcessEnv;
+  homedir(): string;
+  /** Directory holding the packaged plugin files. */
+  sourceDir: string;
+  stdout(text: string): void;
+  stderr(text: string): void;
+}
+
+export function packagedHermesPluginDir(): string {
+  return fileURLToPath(new URL(`../hermes-plugin/${HERMES_PLUGIN_NAME}/`, import.meta.url));
+}
+
+export function defaultHermesPluginInstallDeps(): HermesPluginInstallDeps {
+  return {
+    env: process.env,
+    homedir,
+    sourceDir: packagedHermesPluginDir(),
+    stdout: (text) => { process.stdout.write(text); },
+    stderr: (text) => { process.stderr.write(text); },
+  };
+}
+
+class InstallRefused extends Error {}
+
+function errnoCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException | undefined)?.code;
+}
+
+async function lstatOrNull(path: string) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (errnoCode(error) === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function hermesPluginConfigSnippet(): string {
+  return (
+    `plugins:\n` +
+    `  enabled:\n` +
+    `    - ${HERMES_PLUGIN_NAME}\n` +
+    `  entries:\n` +
+    `    ${HERMES_PLUGIN_NAME}:\n` +
+    `      allow_gateway_injection: true\n` +
+    `      settings:\n` +
+    `        session_key: "agent:main:<platform>:<chat type>:<chat id>"  # the gateway conversation to wake\n` +
+    `        worktree: "<absolute path of the prepared representative worktree>"\n` +
+    `mcp_servers:\n` +
+    `  borg-representative:\n` +
+    `    command: borg\n` +
+    `    args: ["representative", "mcp", "--worktree", "<same absolute worktree path>"]\n` +
+    `    lazy: true\n`
+  );
+}
+
+export async function runHermesPluginInstall(
+  command: { hermesHome?: string; force: boolean },
+  deps: HermesPluginInstallDeps,
+): Promise<number> {
+  try {
+    const home = command.hermesHome ?? (deps.env.HERMES_HOME || join(deps.homedir(), '.hermes'));
+    if (!isAbsolute(home)) throw new InstallRefused(`The Hermes home must be an absolute path: ${home}`);
+    const homeStat = await stat(home).catch(() => null);
+    if (!homeStat?.isDirectory()) {
+      throw new InstallRefused(`No Hermes home at ${home}. Install Hermes first, or pass --hermes-home <path>.`);
+    }
+
+    const sources = await Promise.all(HERMES_PLUGIN_FILES.map(async (name) => {
+      try {
+        return { name, content: await readFile(join(deps.sourceDir, name)) };
+      } catch {
+        throw new InstallRefused(`The packaged plugin file ${name} is missing from ${deps.sourceDir}; reinstall borgmcp.`);
+      }
+    }));
+
+    const pluginsDir = join(home, 'plugins');
+    const pluginsStat = await stat(pluginsDir).catch((error: unknown) => {
+      if (errnoCode(error) === 'ENOENT') return null;
+      throw error;
+    });
+    if (pluginsStat && !pluginsStat.isDirectory()) throw new InstallRefused(`${pluginsDir} is not a directory.`);
+    if (!pluginsStat) await mkdir(pluginsDir, { mode: 0o755 });
+
+    const target = join(pluginsDir, HERMES_PLUGIN_NAME);
+    const existing = await lstatOrNull(target);
+    if (existing?.isSymbolicLink()) {
+      throw new InstallRefused(`${target} is a symbolic link; remove it yourself before installing.`);
+    }
+    if (existing && !existing.isDirectory()) throw new InstallRefused(`${target} exists and is not a directory.`);
+    if (existing && !command.force) {
+      throw new InstallRefused(`${target} already exists. Pass --force to replace the plugin's files.`);
+    }
+    if (!existing) await mkdir(target, { mode: 0o755 });
+
+    for (const { name, content } of sources) {
+      const destination = join(target, name);
+      const temporary = join(target, `.${name}.${process.pid}.tmp`);
+      // 'wx' refuses to follow or reuse anything already at the temporary path.
+      await writeFile(temporary, content, { mode: 0o644, flag: 'wx' });
+      try {
+        await rename(temporary, destination);
+      } catch (error) {
+        await unlink(temporary).catch(() => {});
+        throw error;
+      }
+    }
+
+    deps.stdout(
+      `${existing ? 'Replaced' : 'Installed'} the Hermes plugin ${HERMES_PLUGIN_NAME} in ${target}.\n\n` +
+      `Hermes config was not changed. Add the following to ${join(home, 'config.yaml')}\n` +
+      `(\`hermes plugins enable ${HERMES_PLUGIN_NAME}\` covers the enabled list only):\n\n` +
+      hermesPluginConfigSnippet() +
+      `\nThen:\n` +
+      `- session_key must name a messaging-gateway conversation (for example your Telegram DM). A Hermes\n` +
+      `  Desktop chat cannot be woken: Hermes injects plugin messages only into gateway conversations.\n` +
+      `- Only one process may use the representative tools. With lazy: true, run \`hermes tools\` and disable\n` +
+      `  the mcp-borg-representative toolset on every platform except the one in session_key (Desktop and CLI\n` +
+      `  included). If Desktop already holds the tools lease, restart the Desktop backend once.\n` +
+      `- Restart the gateway (\`hermes gateway restart\`) so it loads the plugin.\n` +
+      `Details: docs/HUMAN_REPRESENTATIVE.md, section "Hermes push plugin".\n`,
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof InstallRefused ? error.message : `Install failed: ${error instanceof Error ? error.message : String(error)}`;
+    deps.stderr(`${message}\n`);
+    return 1;
+  }
+}

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();