borgmcp 5.4.1 → 5.6.0

package/src/representative-delivery-store.ts

@@ -0,0 +1,235 @@
+/** Private per-binding DELIVERED checkpoint and read fence for the representative. */
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { borgConfigRoot } from './private-root.js';
+import { atomicWrite0600, readStoreFile } from './seat-store.js';
+import type { LocalServerCursor } from './local-server-cursor.js';
+import { bindingFingerprint, isRepresentativeUuid, type RepresentativeBinding } from './representative-store.js';
+import { validatePrivateDirectory } from './representative-listener-store.js';
+
+/**
+ * `checkpoint`: the host's durable delivery point; only `deliver` moves it.
+ * `readThrough`: the highest entry any `read` returned; `deliver` may not pass it.
+ */
+export interface DeliveryState {
+  checkpoint: LocalServerCursor | null;
+  readThrough: LocalServerCursor | null;
+  /**
+   * Entries a read returned since the checkpoint last moved: `deliver` checks
+   * membership here, not just the range. Every window starts at the
+   * checkpoint, so this stays within the largest window (two, with and without
+   * broadcasts), and deliver prunes it.
+   */
+  returned: LocalServerCursor[];
+}
+
+/** Two windows of at most 50 replies (with and without broadcasts). */
+const RETURNED_CAP = 100;
+
+const deliveryRoot = () => join(borgConfigRoot(), 'representative-delivery');
+
+/**
+ * This binding's own checkpoint file exists but cannot be trusted. It is never
+ * used and never silently reset: every tool except status refuses until the
+ * operator inspects and removes it.
+ */
+export class DeliveryCheckpointError extends Error {
+  readonly code = 'REPRESENTATIVE_CHECKPOINT_INVALID';
+  constructor(file: string, reason: string) {
+    super(`The representative delivery checkpoint ${file} is invalid (${reason}). Nothing was read or delivered. ` +
+      'Inspect the file and remove it; the next read then replays every addressed reply from the start.');
+    this.name = 'DeliveryCheckpointError';
+  }
+}
+
+export function deliveryPaths(binding: RepresentativeBinding) {
+  const directory = join(deliveryRoot(), bindingFingerprint(binding));
+  return { directory, file: join(directory, 'checkpoint.json') };
+}
+
+/**
+ * The seat every generation of a binding shares: the same fields as the
+ * client unread-cursor key, without Coordinator or boundAt.
+ */
+function seatKey(binding: RepresentativeBinding): string {
+  return createHash('sha256').update(JSON.stringify([
+    binding.origin, binding.trustIdentity, binding.cubeId, binding.representativeDroneId,
+  ])).digest('hex');
+}
+
+function point(value: unknown): LocalServerCursor | null {
+  if (value === null) return null;
+  const candidate = value as { id?: unknown; created_at?: unknown } | undefined;
+  if (!isRepresentativeUuid(candidate?.id) || typeof candidate?.created_at !== 'string' ||
+      !Number.isFinite(Date.parse(candidate.created_at))) {
+    throw new Error('Representative delivery checkpoint is invalid');
+  }
+  return { id: candidate.id, created_at: candidate.created_at };
+}
+
+/** (created_at, id) order, the server log order. */
+export function comparePoints(a: LocalServerCursor, b: LocalServerCursor | null): number {
+  if (b === null) return 1;
+  if (a.created_at !== b.created_at) return a.created_at < b.created_at ? -1 : 1;
+  return a.id === b.id ? 0 : a.id < b.id ? -1 : 1;
+}
+
+async function readFile(directory: string, file: string): Promise<{ seat: string; state: DeliveryState } | null> {
+  if (!await validatePrivateDirectory(directory, false)) return null;
+  const raw = await readStoreFile(file, { secureRoot: directory, verifyLeafIdentity: true, createRoot: false });
+  if (raw === null) return null;
+  let parsed: { version?: unknown; seat?: unknown; checkpoint?: unknown; readThrough?: unknown; returned?: unknown };
+  try { parsed = JSON.parse(raw); } catch { throw new Error('Representative delivery checkpoint is invalid'); }
+  if (parsed?.version !== 1 || typeof parsed.seat !== 'string') throw new Error('Representative delivery checkpoint is invalid');
+  const returned = parsed.returned ?? [];
+  if (!Array.isArray(returned) || returned.length > RETURNED_CAP) throw new Error('Representative delivery checkpoint is invalid');
+  return { seat: parsed.seat, state: {
+    checkpoint: point(parsed.checkpoint), readThrough: point(parsed.readThrough),
+    returned: returned.map((value) => point(value)!).map((value) => { if (!value) throw new Error('Representative delivery checkpoint is invalid'); return value; }),
+  } };
+}
+
+// One queue per state file: overlapping tool calls in one process never write
+// from a stale load. Other processes are excluded by the tools lease.
+const queues = new Map<string, Promise<unknown>>();
+
+const later = (a: LocalServerCursor | null, b: LocalServerCursor | null) =>
+  a === null ? b : b === null ? a : comparePoints(a, b) >= 0 ? a : b;
+
+/**
+ * The one-time upgrade tombstone for a seat. Its existence alone means the
+ * legacy import was attempted; nothing in it is ever read back as a position.
+ * Its directory name is not 64 hex characters, so the generation scan never
+ * mistakes it for a checkpoint.
+ */
+export function createDeliveryStore(binding: RepresentativeBinding) {
+  const paths = deliveryPaths(binding);
+  const seat = seatKey(binding);
+  const marker = { directory: join(deliveryRoot(), `seat-${seat}`), file: join(deliveryRoot(), `seat-${seat}`, 'migration.json') };
+  const options = { secureRoot: paths.directory, verifyLeafIdentity: true, createRoot: false };
+  const load = async (): Promise<DeliveryState | null> => {
+    let saved;
+    try {
+      saved = await readFile(paths.directory, paths.file);
+    } catch (error) {
+      throw new DeliveryCheckpointError(paths.file, error instanceof Error ? error.message : 'unreadable');
+    }
+    if (!saved) return null;
+    if (saved.seat !== seat) throw new DeliveryCheckpointError(paths.file, 'it belongs to another representative seat');
+    const { checkpoint, readThrough } = saved.state;
+    if (checkpoint && (readThrough === null || comparePoints(checkpoint, readThrough) > 0)) {
+      throw new DeliveryCheckpointError(paths.file, 'its checkpoint is beyond its read fence');
+    }
+    if (saved.state.returned.some((entry) => comparePoints(entry, checkpoint) <= 0 || comparePoints(entry, readThrough) > 0)) {
+      throw new DeliveryCheckpointError(paths.file, 'a returned entry lies outside its window');
+    }
+    return saved.state;
+  };
+  return {
+    /** Null when this binding generation has no checkpoint yet. A corrupt file fails closed. */
+    load,
+    /**
+     * Whether the seat's upgrade tombstone exists. Any object at that path,
+     * readable or not, counts, so a planted or damaged marker can only cause a
+     * replay (duplicates), never an import or a skip.
+     */
+    async migrated(): Promise<boolean> {
+      try {
+        if (!await validatePrivateDirectory(marker.directory, false)) return false;
+        await lstat(marker.file);
+        return true;
+      } catch (error) {
+        return (error as NodeJS.ErrnoException).code !== 'ENOENT';
+      }
+    },
+    /**
+     * Create the tombstone exclusively (O_EXCL, no-follow, 0600, fsynced).
+     * False when it already exists: another initializer got there first.
+     * `guard` runs just before the create.
+     */
+    async markMigrated(guard?: () => Promise<void>): Promise<boolean> {
+      await guard?.();
+      await validatePrivateDirectory(marker.directory, true);
+      let handle;
+      try {
+        handle = await open(marker.file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false;
+        throw error;
+      }
+      try {
+        await handle.writeFile(JSON.stringify({ version: 1, seat }) + '\n');
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      return true;
+    },
+    /**
+     * Run a first-call initialization alone for this seat within the process:
+     * overlapping first reads see each other's result instead of both
+     * importing. Other processes are excluded by the tools lease, and the
+     * exclusive tombstone create backs that up.
+     */
+    initialize<T>(operation: () => Promise<T>): Promise<T> {
+      const key = `seat:${seat}`;
+      const result = (queues.get(key) ?? Promise.resolve()).then(operation, operation);
+      queues.set(key, result.catch(() => {}));
+      return result;
+    },
+    /**
+     * Whether any other generation of this seat already has a checkpoint, which
+     * means the one-time upgrade from the unread cursor already happened. An
+     * unreadable or unsafe sibling counts as one: the new generation then
+     * replays its history (duplicates, never loss) instead of trusting it.
+     */
+    async otherGenerationExists(): Promise<boolean> {
+      if (!await validatePrivateDirectory(deliveryRoot(), false)) return false;
+      const own = bindingFingerprint(binding);
+      for (const name of await readdir(deliveryRoot())) {
+        if (name === own || !/^[0-9a-f]{64}$/.test(name)) continue;
+        const directory = join(deliveryRoot(), name);
+        try {
+          if ((await readFile(directory, join(directory, 'checkpoint.json')))?.seat === seat) return true;
+        } catch {
+          return true;
+        }
+      }
+      return false;
+    },
+    /**
+     * Move either field forward only, from the state on disk at write time, in
+     * one atomic durable 0600 write. Always writes when no file exists yet, so a
+     * completed migration is never repeated. `guard` runs just before the write.
+     * Returns the states before and after, so callers report the real transition.
+     */
+    advance(update: Partial<DeliveryState>, guard?: () => Promise<void>): Promise<{ before: DeliveryState | null; after: DeliveryState }> {
+      const run = async () => {
+        const before = await load();
+        const checkpoint = later(before?.checkpoint ?? null, update.checkpoint ?? null);
+        const readThrough = later(before?.readThrough ?? null, update.readThrough ?? null);
+        // Union of returned windows, pruned to entries still after the checkpoint.
+        const returned = [...(before?.returned ?? []), ...(update.returned ?? [])]
+          .filter((entry, index, all) => all.findIndex((other) => other.id === entry.id) === index)
+          .filter((entry) => comparePoints(entry, checkpoint) > 0)
+          .sort((a, b) => comparePoints(a, b))
+          .slice(-RETURNED_CAP);
+        const after = { checkpoint, readThrough, returned };
+        // Invariant on every write: the delivered checkpoint never passes the read fence.
+        if (checkpoint && (readThrough === null || comparePoints(checkpoint, readThrough) > 0)) {
+          throw new DeliveryCheckpointError(paths.file, 'a write would move the checkpoint beyond the read fence');
+        }
+        if (before && JSON.stringify(before) === JSON.stringify(after)) return { before, after: before };
+        await guard?.();
+        await validatePrivateDirectory(paths.directory, true);
+        await atomicWrite0600(paths.file, JSON.stringify({ version: 1, seat, ...after }) + '\n', options);
+        return { before, after };
+      };
+      const result = (queues.get(paths.file) ?? Promise.resolve()).then(run, run);
+      queues.set(paths.file, result.catch(() => {}));
+      return result;
+    },
+  };
+}

package/src/representative-listener-store.ts

@@ -0,0 +1,115 @@
+/** Bounded private listener tail and crash-recoverable hint metadata. */
+import { createHash } from 'node:crypto';
+import { join, relative, sep } from 'node:path';
+import { borgConfigRoot, borgHomeRoot } from './private-root.js';
+import { assertSecureRoot, atomicWrite0600, readStoreFile } from './seat-store.js';
+import { formatInboxLine, inboxRawHasEntry, INBOX_TAIL_LINES_CAP, INBOX_TAIL_TRIM_THRESHOLD_LINES, type EnrichedEntry } from './log-stream.js';
+import type { LocalServerCursor } from './local-server-cursor.js';
+import type { RepresentativeBinding } from './representative-store.js';
+import { isRepresentativeUuid } from './representative-store.js';
+
+type Metadata = { visibility: 'direct' | 'broadcast'; documents: number };
+type State = { version: 1; watermark: LocalServerCursor | null; resumeReset: boolean; hints: Record<string, Metadata> };
+export interface ListenerHint {
+  event: 'entry'; entry_id: string; created_at: string; from_label: string; from_role: string;
+  visibility: 'direct' | 'broadcast' | null; request_id: string | null; documents: number | null; replay: boolean;
+}
+const empty = (): State => ({ version: 1, watermark: null, resumeReset: false, hints: {} });
+export function listenerPaths(binding: RepresentativeBinding) {
+  const key = createHash('sha256').update(JSON.stringify([binding.worktree, binding.origin, binding.trustIdentity,
+    binding.cubeId, binding.representativeDroneId, binding.coordinatorDroneId, binding.boundAt])).digest('hex');
+  const directory = join(borgConfigRoot(), 'representative-inboxes', key);
+  return { directory, inbox: join(directory, 'inbox.log'), state: join(directory, 'stream.json') };
+}
+function requestId(message: string): string | null {
+  return /\brequest_id:\s*([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?![0-9a-f-])/i.exec(message)?.[1] ?? null;
+}
+function parseLine(line: string) {
+  const match = /^(\S+) (.*?) \((.*?)\): \[entry_id: ([0-9a-f-]+)\] (.*)$/i.exec(line);
+  if (!match || !isRepresentativeUuid(match[4]) || !Number.isFinite(Date.parse(match[1]))) throw new Error('Invalid representative inbox line');
+  return { id: match[4], created_at: match[1], label: match[2], role: match[3], message: match[5] };
+}
+function newer(a: LocalServerCursor, b: LocalServerCursor | null) {
+  return b === null || a.created_at > b.created_at || (a.created_at === b.created_at && a.id > b.id);
+}
+
+/** Validate a private directory under the Borg config root and every ancestor
+ * with the store's policy; never repairs unsafe state. False when absent. */
+export async function validatePrivateDirectory(directory: string, create: boolean): Promise<boolean> {
+  let current = borgHomeRoot();
+  for (const component of relative(current, directory).split(sep)) {
+    if (!await assertSecureRoot(current, current === borgConfigRoot() || current.startsWith(borgConfigRoot() + sep) ? 'private' : 'owner-controlled', create)) return false;
+    current = join(current, component);
+  }
+  return assertSecureRoot(current, 'private', create);
+}
+
+export function createListenerInbox(binding: RepresentativeBinding, guard: () => Promise<void> = async () => {}) {
+  const paths = listenerPaths(binding);
+  const options = { secureRoot: paths.directory, verifyLeafIdentity: true, createRoot: false };
+  const validate = (create: boolean) => validatePrivateDirectory(paths.directory, create);
+  const load = async () => {
+    if (!await validate(false)) return { state: empty(), lines: [] as string[] };
+    const raw = await readStoreFile(paths.inbox, options) ?? '';
+    const saved = await readStoreFile(paths.state, options);
+    let state = empty();
+    if (saved !== null) {
+      // Lost/corrupt metadata cannot suppress surviving inbox lines on replay.
+      // The secure read itself still fails closed on ownership/path/identity drift.
+      try {
+        const parsed = JSON.parse(saved);
+        if (parsed.version === 1 && typeof parsed.resumeReset === 'boolean' && parsed.hints && typeof parsed.hints === 'object' &&
+            (parsed.watermark === null || (isRepresentativeUuid(parsed.watermark?.id) && Number.isFinite(Date.parse(parsed.watermark?.created_at))))) state = parsed;
+      } catch { /* recover the watermark and nullable replay metadata from the tail */ }
+    }
+    const lines = raw.split('\n').filter(Boolean);
+    for (const line of lines) {
+      const point = parseLine(line);
+      if (newer(point, state.watermark)) { state.watermark = { id: point.id, created_at: point.created_at }; state.resumeReset = false; }
+    }
+    return { state, lines };
+  };
+  const write = async (file: string, raw: string) => {
+    await guard(); await validate(true);
+    await atomicWrite0600(file, raw, options);
+  };
+  const hint = (line: string, state: State, replay: boolean): ListenerHint => {
+    const parsed = parseLine(line), metadata = state.hints[parsed.id];
+    return { event: 'entry', entry_id: parsed.id, created_at: parsed.created_at,
+      from_label: parsed.label, from_role: parsed.role, request_id: requestId(parsed.message), replay,
+      visibility: metadata?.visibility === 'direct' || metadata?.visibility === 'broadcast' ? metadata.visibility : null,
+      documents: Number.isInteger(metadata?.documents) && metadata.documents >= 0 ? metadata.documents : null };
+  };
+  return {
+    paths,
+    snapshot: async () => { const { state } = await load(); return { watermark: state.watermark?.id ?? null, inbox: paths.inbox }; },
+    dedupeCursor: async () => (await load()).state.watermark,
+    cursor: async () => { const { state } = await load(); return state.resumeReset ? null : state.watermark; },
+    clearCursor: async () => { const { state } = await load(); state.resumeReset = true; await write(paths.state, JSON.stringify(state)); },
+    replay: async (after: string) => {
+      const { state, lines } = await load(); const index = lines.findIndex(line => parseLine(line).id === after);
+      return { missing: index < 0, hints: lines.slice(index + 1).map(line => hint(line, state, true)) };
+    },
+    append: async (entry: EnrichedEntry & { id: string; created_at: string; visibility: 'direct' | 'broadcast' }, catchupCursor: LocalServerCursor | null = null) => {
+      if (!isRepresentativeUuid(entry.id) || !Number.isFinite(Date.parse(entry.created_at)) ||
+          !['direct', 'broadcast'].includes(entry.visibility)) throw new Error('Invalid representative stream entry');
+      const { state, lines } = await load(); const line = formatInboxLine(entry);
+      if (lines.some(value => parseLine(value).id === entry.id && inboxRawHasEntry(value, entry.id, line)) ||
+          (catchupCursor !== null && !newer(entry, catchupCursor))) return null;
+      state.hints[entry.id] = { visibility: entry.visibility, documents: entry.documents?.length ?? 0 };
+      // Metadata first, then atomic inbox publication, then watermark/metadata trim.
+      // A crash after publication recovers its watermark from the surviving tail.
+      await write(paths.state, JSON.stringify(state));
+      lines.push(line);
+      const kept = lines.length > INBOX_TAIL_TRIM_THRESHOLD_LINES ? lines.slice(-INBOX_TAIL_LINES_CAP) : lines;
+      await write(paths.inbox, kept.join('\n') + '\n');
+      if (newer(entry, state.watermark)) state.watermark = { id: entry.id, created_at: entry.created_at };
+      state.resumeReset = false;
+      state.hints = Object.fromEntries(kept.map(value => parseLine(value).id).filter(id => state.hints[id]).map(id => [id, state.hints[id]]));
+      await write(paths.state, JSON.stringify(state));
+      // Linear scans/rewrites are deliberately bounded to 1025 lines; a larger
+      // retention policy would need an indexed journal instead of this tail.
+      return hint(line, state, false);
+    },
+  };
+}

package/src/representative-listener.ts

@@ -0,0 +1,215 @@
+/** Supervised body-free wake channel; independent of the lazy MCP tools lease. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { borgConfigRoot } from './private-root.js';
+import { acquireStreamLease, readOwnershipSnapshot, STREAM_OWNER_STALE_MS, type StreamLease } from './stream-owner.js';
+import { representativeOwnerDeps } from './representative-owner.js';
+import { createListenerInbox } from './representative-listener-store.js';
+import { streamOnce, streamReconnectDelay, type StreamDeps } from './log-stream.js';
+import { resolveRepresentativeContext, type RepresentativeCmdDeps } from './representative-cmd.js';
+import { DroneEvictedError, CubeDeletedError } from './drone-lifecycle.js';
+import { BorgServerTrustError, BorgServerUnreachableError } from './server-errors.js';
+import { isTransportFailure } from './seat-probe.js';
+import { readBorgServerTrustIdentity } from './server-trust.js';
+import { RepresentativeError, verifyLiveBinding } from './representative-core.js';
+import { bindingFingerprint, type RepresentativeBinding } from './representative-store.js';
+import type { ActiveCube } from './cubes.js';
+
+type StopReason = 'signal' | 'evicted' | 'rebound' | 'revoked' | 'trust-changed' | 'lease-lost' | 'fatal';
+export interface ListenerOptions {
+  /** Controlled transport/timing seams; the CLI supplies no overrides. */
+  streamDeps?: StreamDeps;
+  heartbeatIntervalMs?: number;
+  reconnectDelay?: (attempt: number) => number;
+}
+function listenerOwnerDeps(binding: RepresentativeBinding) {
+  const authority = createHash('sha256').update(JSON.stringify([binding.origin, binding.trustIdentity])).digest('hex');
+  return { ...representativeOwnerDeps(binding), locksDir: join(borgConfigRoot(), 'representative-listener-locks', authority) };
+}
+export async function representativeListenerStatus(binding: RepresentativeBinding) {
+  const ownership = await readOwnershipSnapshot(binding.cubeId, binding.representativeDroneId, listenerOwnerDeps(binding));
+  let alive = false;
+  if (ownership.pid) {
+    try { process.kill(ownership.pid, 0); alive = true; }
+    catch (error) { alive = (error as NodeJS.ErrnoException).code === 'EPERM'; }
+  }
+  return { ...ownership, running: alive && (ownership.ageMs ?? Infinity) <= STREAM_OWNER_STALE_MS,
+    ...await createListenerInbox(binding).snapshot() };
+}
+function codeOf(error: unknown): string {
+  if (error instanceof DroneEvictedError) return 'DRONE_EVICTED';
+  if (error instanceof CubeDeletedError) return 'CUBE_DELETED';
+  if (error instanceof BorgServerTrustError) return 'TRUST_CHANGED';
+  return typeof (error as any)?.code === 'string' ? (error as any).code : 'LISTENER_ERROR';
+}
+function terminalReason(error: unknown): StopReason | undefined {
+  const code = codeOf(error);
+  if (code === 'DRONE_EVICTED' || code === 'CUBE_DELETED' || code === 'SEAT_UNAVAILABLE') return 'evicted';
+  if (code === 'BINDING_MISMATCH' || code === 'COORDINATOR_UNAVAILABLE') return 'rebound';
+  if (code.includes('TRUST')) return 'trust-changed';
+  if (['SESSION_REVOKED', 'SESSION_REJECTED', 'CREDENTIAL_REJECTED'].includes(code)) return 'revoked';
+  return undefined;
+}
+
+export async function runListener(
+  command: { worktree?: string; replayAfter?: string }, deps: RepresentativeCmdDeps, options: ListenerOptions = {},
+): Promise<number> {
+  const emit = async (event: unknown) => {
+    deps.stdout(JSON.stringify(event) + '\n');
+    // The command exits after its final event; wait for the pipe to flush.
+    await new Promise<void>((resolve, reject) => process.stdout.write('', error => error ? reject(error) : resolve()));
+  };
+  let lease: StreamLease | null = null;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let started = false, reason: StopReason | undefined, active: ActiveCube;
+  const abort = new AbortController();
+  let pending: Promise<unknown> = Promise.resolve();
+  const serial = <T>(fn: () => Promise<T>) => {
+    const result = pending.then(fn); pending = result.catch(() => {}); return result;
+  };
+  const stop = (why: StopReason) => { reason ??= why; abort.abort(); };
+  const signal = () => stop('signal');
+  let outputBroken = false;
+  const outputError = () => { outputBroken = true; reason = 'fatal'; abort.abort(); };
+  process.stdout.on('error', outputError);
+  const exitCode = () => reason === 'signal' ? 0 : reason === 'fatal' ? 1 : 4;
+  try {
+    let worktree = command.worktree ?? deps.cwd();
+    try { worktree = realpathSync(worktree); } catch { /* resolve refuses missing bindings */ }
+    worktree = deps.findProjectRoot(worktree);
+    const ctx = await resolveRepresentativeContext(worktree, deps);
+    // Only this server step maps transport failures to SERVER_UNREACHABLE; typed
+    // rejections keep their binding codes and storage keeps STORAGE_REFUSED.
+    await verifyLiveBinding(ctx).catch((error: unknown) => {
+      throw isTransportFailure(error) && !(error instanceof BorgServerUnreachableError)
+        ? new BorgServerUnreachableError('Borg server unreachable during startup verification', { cause: error }) : error;
+    });
+    const binding = ctx.binding;
+    active = (await deps.hydrateSeat(worktree))!;
+    const ownerDeps = listenerOwnerDeps(binding);
+    lease = await acquireStreamLease(binding.cubeId, binding.representativeDroneId, STREAM_OWNER_STALE_MS, ownerDeps);
+    if (!lease) {
+      const owner = await readOwnershipSnapshot(binding.cubeId, binding.representativeDroneId, ownerDeps);
+      await emit({ event: 'refused', code: 'REPRESENTATIVE_LISTENER_OWNED', exit_code: 3,
+        owner_pid: owner.pid ?? null, owner_started_at: owner.startedAt ?? null });
+      return 3;
+    }
+    const guard = async () => {
+      if (abort.signal.aborted) throw new Error('listener stopped');
+      const current = await deps.store.getBinding(worktree);
+      if (!current || JSON.stringify([current.origin, current.trustIdentity, current.cubeId, current.representativeDroneId, current.coordinatorDroneId, current.boundAt]) !==
+          JSON.stringify([binding.origin, binding.trustIdentity, binding.cubeId, binding.representativeDroneId, binding.coordinatorDroneId, binding.boundAt])) {
+        stop('rebound'); throw new RepresentativeError('BINDING_MISMATCH', 'Representative binding changed');
+      }
+      const saved = await deps.hydrateSeat(worktree);
+      if (!saved) { stop('revoked'); throw new RepresentativeError('SEAT_UNAVAILABLE', 'Representative seat unavailable'); }
+      if (saved.serverTrustIdentity !== binding.trustIdentity) { stop('trust-changed'); throw new BorgServerTrustError('Representative trust changed'); }
+      if (saved.cubeId !== binding.cubeId || saved.droneId !== binding.representativeDroneId || saved.apiUrl !== binding.origin) {
+        stop('rebound'); throw new RepresentativeError('BINDING_MISMATCH', 'Representative seat changed');
+      }
+      // Recheck authority trust while the stream stays open, not only on reconnect.
+      // Controlled transports may omit trust loading; production never does.
+      if (!options.streamDeps?.fetchImpl || options.streamDeps.loadTrust) {
+        try {
+          // Read fresh: the loader's local-authority cache never observes a change.
+          const identity = options.streamDeps?.loadTrust
+            ? (await options.streamDeps.loadTrust(binding.origin)).identity
+            : await readBorgServerTrustIdentity(binding.origin);
+          if (identity !== binding.trustIdentity) throw new BorgServerTrustError('Representative authority trust changed');
+        } catch (error) { stop('trust-changed'); throw error; }
+      }
+      const observed = await readOwnershipSnapshot(binding.cubeId, binding.representativeDroneId, ownerDeps);
+      if (observed.processNonce !== lease!.record.processNonce) { stop('lease-lost'); throw new Error('Listener ownership lost'); }
+    };
+    const inbox = createListenerInbox(binding, guard);
+    await inbox.snapshot(); // refuse unsafe persisted paths before emitting listening
+    process.once('SIGTERM', signal); process.once('SIGINT', signal);
+    timer = setInterval(() => {
+      void serial(async () => { await guard(); if (!await lease!.refresh()) stop('lease-lost'); }).catch(error => { if (!reason) stop(terminalReason(error) ?? 'lease-lost'); });
+    }, options.heartbeatIntervalMs ?? 20_000);
+    let attempt = 0;
+    let consumerFailure: unknown;
+    let pendingGap: string | null | undefined;
+    // Failures of the listener's own guard, storage and output are fatal; every
+    // other non-terminal stream failure is transport and reconnects, as in the
+    // ordinary stream loop (pinned HTTPS surfaces raw errno/string codes).
+    const local = <A extends unknown[], T>(fn: (...args: A) => Promise<T>) => async (...args: A): Promise<T> => {
+      try { return await fn(...args); } catch (error) { consumerFailure ??= error; throw error; }
+    };
+    while (!reason) {
+      const resumed = await inbox.cursor();
+      try {
+        consumerFailure = undefined;
+        await local(() => serial(guard))();
+        await streamOnce(active, resumed?.id ?? null, () => {}, {
+          ...options.streamDeps, getCursor: local(async () => inbox.cursor()), abortSignal: abort.signal,
+          consumer: {
+            catchupCursor: await local(() => inbox.dedupeCursor())(),
+            beforeEvent: local(() => serial(guard)),
+            clearCursor: local(() => serial(async () => {
+              const previous = await inbox.snapshot(); await inbox.clearCursor();
+              if (started) await emit({ event: 'gap', after: previous.watermark, reason: 'cursor-expired' });
+              else pendingGap = previous.watermark;
+            })),
+            connected: local(() => serial(async () => {
+              await guard();
+              if (!started) {
+                await emit({ event: 'listening', cube_id: binding.cubeId, drone_id: binding.representativeDroneId,
+                  binding_fingerprint: bindingFingerprint(binding), ...await inbox.snapshot() });
+                started = true;
+                if (pendingGap !== undefined) await emit({ event: 'gap', after: pendingGap, reason: 'cursor-expired' });
+                if (command.replayAfter) {
+                  const replay = await inbox.replay(command.replayAfter);
+                  if (replay.missing) await emit({ event: 'gap', after: command.replayAfter, reason: 'replay-checkpoint-missing' });
+                  for (const hint of replay.hints) { await guard(); await emit(hint); }
+                }
+              } else await emit({ event: 'connected', resumed_from: resumed?.id ?? null });
+            })),
+            log: local((event, catchupCursor) => serial(async () => {
+              await guard();
+              const hint = await inbox.append({ ...event.data, id: event.id }, catchupCursor);
+              if (hint) { await guard(); await emit(hint); }
+            })),
+          },
+        });
+        attempt = 0;
+      } catch (error) {
+        if (reason) { if (!started) throw error; break; }
+        if (consumerFailure) throw consumerFailure;
+        const terminal = terminalReason(error);
+        if (terminal) { if (!started) throw error; stop(terminal); break; }
+        deps.stderr(`Representative listener: ${error instanceof Error ? error.message : 'stream disconnected'}\n`);
+      }
+      if (reason) break;
+      const delay = Math.round((options.reconnectDelay ?? streamReconnectDelay)(attempt++));
+      if (started) await emit({ event: 'reconnecting', attempt, delay_ms: delay });
+      await new Promise<void>(resolve => {
+        const done = () => { clearTimeout(timeout); abort.signal.removeEventListener('abort', done); resolve(); };
+        const timeout = setTimeout(done, delay); abort.signal.addEventListener('abort', done, { once: true });
+        if (abort.signal.aborted) done();
+      });
+    }
+    return exitCode();
+  } catch (error) {
+    deps.stderr(`Representative listener refused: ${error instanceof Error ? error.message : String(error)}\n`);
+    if (!started && (error instanceof RepresentativeError || terminalReason(error))) {
+      await emit({ event: 'refused', code: typeof (error as any)?.code === 'string' ? (error as any).code : 'BACKEND_ERROR', exit_code: 2 }); return 2;
+    }
+    if (started) reason = 'fatal';
+    else if (!outputBroken) await emit({ event: 'refused', code: error instanceof BorgServerUnreachableError
+      ? 'REPRESENTATIVE_LISTENER_SERVER_UNREACHABLE' : 'REPRESENTATIVE_LISTENER_STORAGE_REFUSED', exit_code: 1 });
+    return 1;
+  } finally {
+    if (timer) clearInterval(timer);
+    process.removeListener('SIGTERM', signal); process.removeListener('SIGINT', signal);
+    await pending;
+    let releaseFailed = false;
+    try { await lease?.release(); } catch (error) { releaseFailed = true; reason = 'fatal'; deps.stderr(`Listener lease release failed: ${String(error)}\n`); }
+    if (started && reason && !outputBroken) {
+      try { await emit({ event: 'stopped', reason, exit_code: exitCode() }); } catch { /* stdout failure is fatal to the host */ }
+    }
+    process.stdout.removeListener('error', outputError);
+    if (releaseFailed || outputBroken) return 1;
+  }
+}