borgmcp 5.4.1 → 5.6.0

package/src/assimilate-cmd.ts

@@ -441,6 +441,7 @@ async function selectAssimilationAuthority(
   flags: AssimilateFlags,
   deps: AuthorityResolutionDeps,
   mode: 'assimilate' | 'cube-init',
+  authoritySelectionCommand?: string,
 ): Promise<AssimilationAuthority | null> {
   if (flags.server !== undefined) {
     try {
@@ -460,7 +461,7 @@ async function selectAssimilationAuthority(
   }
   if (!deps.isTTY() || flags.yes) {
     if (deps.defaultAuthority) return deps.defaultAuthority;
-    const command = mode === 'cube-init'
+    const command = authoritySelectionCommand ? `\`${authoritySelectionCommand}\`` : mode === 'cube-init'
       ? '`borg server cube init --host <host>`'
       : '`borg assimilate --host <host> --here`';
     deps.stderr(`No local server selected. Use ${command} to select a local server.\n`);
@@ -1132,11 +1133,11 @@ export interface CubeRoleResolutionOutcome {
   cli: BorgCli;
 }
 
-export async function resolveAssimilationCubeRole(
+function resolveConnectionRole(
   input: CubeRoleResolutionInput,
   deps: CubeRoleResolutionDeps,
-): Promise<AssimilationPhaseOutcome<CubeRoleResolutionOutcome>> {
-  const { requestedRole, flags, cubeDetail, isFirstDrone, savedLocalRole, apiUrl } = input;
+): AssimilationPhaseOutcome<{ resolvedRole: Role }> {
+  const { requestedRole, cubeDetail, isFirstDrone, savedLocalRole, apiUrl } = input;
   let resolvedRole: Role | undefined;
   if (savedLocalRole) {
     resolvedRole = savedLocalRole;
@@ -1166,6 +1167,17 @@ export async function resolveAssimilationCubeRole(
     }
   }
 
+  return continueAssimilation({ resolvedRole });
+}
+
+export async function resolveAssimilationCubeRole(
+  input: CubeRoleResolutionInput,
+  deps: CubeRoleResolutionDeps,
+): Promise<AssimilationPhaseOutcome<CubeRoleResolutionOutcome>> {
+  const role = resolveConnectionRole(input, deps);
+  if (role.kind === 'stop') return role;
+  const { resolvedRole } = role.value;
+  const { flags, apiUrl } = input;
   const effectiveModel: string | null = flags.model ?? null;
   const cli = await deps.resolveCli(flags.cli);
   try {
@@ -1192,7 +1204,7 @@ export interface SeatPreparationInput {
   serverTrustIdentity: string;
   cubeDetail: CubeDetail;
   resolvedRole: Role;
-  cli: BorgCli;
+  cli?: BorgCli;
   effectiveModel: string | null;
   projectRoot: string;
   existing: CanonicalActiveCube | null;
@@ -1267,8 +1279,7 @@ export async function prepareAssimilationSeat(
         cube_id: cubeDetail.id,
         role_id: resolvedRole.id,
         hostname: deps.getHostname(),
-        agent_kind: cli,
-        model: effectiveModel,
+        ...(cli !== undefined ? { agent_kind: cli, model: effectiveModel } : {}),
         working_repo: resolveWorkingRepo(projectRoot),
         ...(reattachPriorId ? { prior_drone_id: reattachPriorId } : {}),
         ...(remintInvalidPrior ? { remint_invalid_prior: true } : {}),
@@ -1471,6 +1482,7 @@ export interface AuthorityResolutionInput {
   args: AssimilateArgs;
   mode: 'assimilate' | 'cube-init';
   repositoryContext: GitRepositoryContext;
+  authoritySelectionCommand?: string;
 }
 
 export interface AuthorityResolutionOutcome {
@@ -1493,6 +1505,13 @@ export async function resolveAssimilationAuthority(
   deps: AuthorityResolutionDeps,
 ): Promise<AssimilationPhaseOutcome<AuthorityResolutionOutcome>> {
   const { args, mode, repositoryContext } = input;
+  // Representative retries must refuse before private-state initialization or
+  // installation checks can mutate anything when no authority was selected.
+  if (input.authoritySelectionCommand && args.flags.server === undefined &&
+      deps.defaultAuthority === undefined && !args.flags.enroll && (!deps.isTTY() || args.flags.yes)) {
+    await selectAssimilationAuthority(args.flags, deps, mode, input.authoritySelectionCommand);
+    return { kind: 'stop', code: 1 };
+  }
   const hostlessEnrollment = args.flags.enroll === true &&
     args.flags.server === undefined && deps.defaultAuthority === undefined;
   const artifactOnlyEnrollment = hostlessEnrollment && deps.isTTY();
@@ -1624,7 +1643,7 @@ export async function resolveAssimilationAuthority(
     localSeatReadError = error;
   }
 
-  const selectedAuthority = await selectAssimilationAuthority(args.flags, deps, mode);
+  const selectedAuthority = await selectAssimilationAuthority(args.flags, deps, mode, input.authoritySelectionCommand);
   if (!selectedAuthority) return { kind: 'stop', code: 1 };
   let authority = selectedAuthority;
   if (localSeatReadError !== undefined) {
@@ -1750,12 +1769,31 @@ export async function runAssimilate(
   args: AssimilateArgs,
   deps: AssimilateDeps,
   options: RunAssimilateOptions = {},
+): Promise<number> {
+  return runAssimilationFlow(args, deps, options);
+}
+
+/** Prepare a host-neutral connection using the same durable assimilation lifecycle. */
+export async function prepareConnection(
+  args: AssimilateArgs,
+  deps: AssimilateDeps,
+  options: { validateRole: (role: Role) => void; onPrepared: (prepared: PreparedAssimilation) => void; authoritySelectionCommand?: string },
+): Promise<number> {
+  return runAssimilationFlow(args, deps, { launch: false, ...options }, options.validateRole, options.authoritySelectionCommand);
+}
+
+async function runAssimilationFlow(
+  args: AssimilateArgs,
+  deps: AssimilateDeps,
+  options: RunAssimilateOptions,
+  validateConnectionRole?: (role: Role) => void,
+  authoritySelectionCommand?: string,
 ): Promise<number> {
   const repository = await resolveAssimilationRepository(args, deps);
   if (repository.kind === 'stop') return repository.code;
   const { mode, repositoryContext } = repository.value;
 
-  const authorityResolution = await resolveAssimilationAuthority({ args, mode, repositoryContext }, deps);
+  const authorityResolution = await resolveAssimilationAuthority({ args, mode, repositoryContext, authoritySelectionCommand }, deps);
   if (authorityResolution.kind === 'stop') return authorityResolution.code;
   const {
     authority,
@@ -2172,16 +2210,18 @@ export async function runAssimilate(
     }
   }
 
-  const cubeRole = await resolveAssimilationCubeRole({
-    requestedRole: args.role,
-    flags: args.flags,
-    cubeDetail,
-    isFirstDrone,
-    savedLocalRole,
-    apiUrl: authority.apiUrl,
-  }, deps);
+  const roleInput = {
+    requestedRole: args.role, flags: args.flags, cubeDetail, isFirstDrone,
+    savedLocalRole, apiUrl: authority.apiUrl,
+  };
+  const cubeRole = validateConnectionRole
+    ? resolveConnectionRole(roleInput, deps)
+    : await resolveAssimilationCubeRole(roleInput, deps);
   if (cubeRole.kind === 'stop') return cubeRole.code;
-  const { resolvedRole, effectiveModel, cli } = cubeRole.value;
+  const { resolvedRole } = cubeRole.value;
+  validateConnectionRole?.(resolvedRole);
+  const cli = 'cli' in cubeRole.value ? cubeRole.value.cli as BorgCli : undefined;
+  const effectiveModel = 'effectiveModel' in cubeRole.value ? cubeRole.value.effectiveModel as string | null : null;
 
   const seat = await prepareAssimilationSeat({
     apiUrl: auth.apiUrl,
@@ -2202,6 +2242,7 @@ export async function runAssimilate(
   }, deps);
   if (seat.kind === 'stop') return seat.code;
   const { result, assignedRole, sessionExpected } = seat.value;
+  validateConnectionRole?.(assignedRole);
 
   const worktree = await prepareAssimilationWorktree({
     flags: args.flags,
@@ -2266,7 +2307,7 @@ export async function runAssimilate(
   // of that request. The resolver therefore saved the preference against the
   // invoking checkout. Once a sibling exists, save the same choice under its
   // own project key so a later --here launch in that worktree can read it.
-  if (spawnedWorktreePath) {
+  if (spawnedWorktreePath && cli !== undefined) {
     try {
       await deps.setCliPreferenceForWorktree(cli, spawnedWorktreePath);
     } catch (err) {
@@ -2281,8 +2322,10 @@ export async function runAssimilate(
   }
 
   try {
-    deps.mkdirp(scratchRoot);
-    deps.provisionLaunchAccess?.(cli, seatWorktree, launchAccessPaths);
+    if (cli !== undefined) {
+      deps.mkdirp(scratchRoot);
+      deps.provisionLaunchAccess?.(cli, seatWorktree, launchAccessPaths);
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     deps.stderr(
@@ -2320,6 +2363,14 @@ export async function runAssimilate(
     }
   }
 
+  if (validateConnectionRole) {
+    options.onPrepared?.({
+      cubeId: result.cube_id, cubeName: cubeDetail.name, droneId: result.drone_id,
+      droneLabel: result.drone_label, roleName: assignedRole.name, worktree: seatWorktree,
+    });
+    return 0;
+  }
+
   // gh#793: best-effort GC of orphaned inbox files (evicted/dead drones) in the
   // cube just joined — lazy-on-assimilate, no cron/new command. NEVER blocks or
   // fails the assimilate (whole call swallowed). Local-only signal (CubeDetail
@@ -2371,7 +2422,7 @@ export async function runAssimilate(
     cubeDetail,
     assignedRole,
     apiUrl: auth.apiUrl,
-    cli,
+    cli: cli!,
     effectiveModel,
     agentCwd,
     seatWorktree,

package/src/claude.ts

@@ -390,6 +390,36 @@ async function main() {
       buildDefaultSeatCommandDeps(),
     ));
   }
+  if (process.argv[2] === 'representative') {
+    // Loaded on demand: the representative facade is unrelated to agent launch.
+    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);
+    }
+    const deps = await representative.buildDefaultRepresentativeDeps();
+    if (parsed.command.action === 'prepare') {
+      process.exit(await representative.runRepresentativePrepare(parsed.command, deps));
+    }
+    if (parsed.command.action === 'status') {
+      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,
+    }));
+  }
   if (process.argv[2] === 'launch-all') {
     const parsed = parseLaunchAllArgs(process.argv.slice(3));
     if (!parsed.ok) {

package/src/cli-help.ts

@@ -113,6 +113,52 @@ export function launchSeatHelpText(version: string): string {
   );
 }
 
+export function representativeHelpText(version: string): string {
+  return (
+    `borg representative (borgmcp ${version}) — connect a human representative (e.g. Hermes) to one Coordinator\n\n` +
+    `Vocabulary:\n` +
+    `  cube                  One repository's shared coordination space on your Borg server.\n` +
+    `  drone                 One connected agent session in a cube; its role defines how it works.\n` +
+    `  human seat            The one role in a cube that speaks with the human's authority.\n` +
+    `  Coordinator           The drone holding the human seat. It plans the work and dispatches the other drones.\n` +
+    `  human representative  A SEPARATE automated drone, under its own non-human-seat role, that relays the\n` +
+    `                        human's requests, questions and decisions to that one Coordinator and reads its\n` +
+    `                        replies. It is not the human, never takes the human seat, and never addresses\n` +
+    `                        other drones or broadcasts.\n\n` +
+    `Usage:\n` +
+    `  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` +
+    `            exactly the named Coordinator drone. Launches no agent CLI and changes no other drone.\n` +
+    `            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, 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/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: 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` +
+    `No command takes a credential; the drone's saved connection stays in Borg's private store.\n` +
+    `Details: docs/HUMAN_REPRESENTATIVE.md\n`
+  );
+}
+
 export function doctorHelpText(version: string): string {
   return (
     `borg doctor (borgmcp ${version}) — inspect Borg agent integrations without changing them\n\n` +
@@ -139,6 +185,7 @@ export function clientSubcommandHelpText(
     case 'drones': return seatsHelpText(version);
     case 'launch': return launchSeatHelpText(version);
     case 'launch-all': return launchAllHelpText(version);
+    case 'representative': return representativeHelpText(version);
     case 'doctor': return doctorHelpText(version);
     default: return null;
   }
@@ -186,6 +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|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

@@ -15,6 +15,7 @@ const REPOSITORY_URL = "https://github.com/Byte-Ventures/borg-mcp-client";
 const LOCAL_SERVER_URL = `${REPOSITORY_URL}/blob/main/docs/LOCAL_SERVER.md`;
 const SEAT_LIFECYCLE_URL = `${REPOSITORY_URL}/blob/main/docs/SEAT_LIFECYCLE.md`;
 const DOCUMENTS_URL = `${REPOSITORY_URL}/blob/main/docs/DOCUMENTS.md`;
+const HUMAN_REPRESENTATIVE_URL = `${REPOSITORY_URL}/blob/main/docs/HUMAN_REPRESENTATIVE.md`;
 
 export interface DocsSection {
   /** logical topic key */
@@ -91,6 +92,13 @@ export const DOCS_SECTIONS: DocsSection[] = [
     summary: "Immutable cube-local Markdown or plain text, revisions, removal, and structured activity-log citations.",
     keywords: ["document", "documents", "citation", "cite", "durable content", "supersede", "revision", "borg_put-document", "borg_get-document"],
   },
+  {
+    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, 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"],
+  },
   {
     slug: "tools",
     title: "Tool reference",

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';
 
@@ -90,11 +91,17 @@ async function readState(): Promise<CursorFile> {
   }
 }
 
-async function writeState(state: CursorFile): Promise<void> {
+async function writeState(state: CursorFile, continuationGuard?: () => Promise<void>): Promise<void> {
   await mkdir(dirname(CURSOR_FILE), { recursive: true });
   const temporary = `${CURSOR_FILE}.${process.pid}.${Date.now()}.tmp`;
   await writeFile(temporary, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
-  await rename(temporary, CURSOR_FILE);
+  try {
+    if (continuationGuard) await continuationGuard();
+    await rename(temporary, CURSOR_FILE);
+  } catch (error) {
+    await unlink(temporary).catch(() => undefined);
+    throw error;
+  }
 }
 
 async function withLock<T>(operation: () => Promise<T>): Promise<T> {
@@ -140,13 +147,58 @@ 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,
+  continuationGuard?: () => Promise<void>,
 ): Promise<void> {
   if (!validCursor(cursor)) throw new Error('invalid local Borg server cursor');
   const key = cursorKey(binding);
   await withLock(async () => {
+    if (continuationGuard) await continuationGuard();
     const state = await readState();
     const prior = state.cursors[key];
     if (
@@ -157,7 +209,7 @@ export async function advanceLocalServerCursor(
       return;
     }
     state.cursors[key] = cursor;
-    await writeState(state);
+    await writeState(state, continuationGuard);
   });
 }
 

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;
   }
 }