borgmcp 5.4.1 → 5.6.0

package/src/representative-mcp.ts

@@ -0,0 +1,250 @@
+/**
+ * Restricted stdio MCP facade for the human representative.
+ *
+ * A Borg server speaks pinned-TLS HTTPS, not MCP, so a generic MCP host reaches
+ * it through this local stdio process. The surface is five tools: status, send
+ * (to the ONE bound Coordinator), read (that Coordinator's replies), deliver
+ * (the host's durable delivery checkpoint) and ack.
+ * There is deliberately no log/broadcast/dispatch, roster-management, grant,
+ * evict, release, regen or server-lifecycle tool, and no dispatcher escape hatch.
+ *
+ * The connection context is resolved per call and injected, so the same facade
+ * runs over the real seat-scoped backend or a controlled test backend.
+ */
+
+import { ErrorCode } from 'borgmcp-shared/protocol';
+import type { Readable, Writable } from 'node:stream';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  REPRESENTATIVE_DELIVERY_NOTE,
+  REPRESENTATIVE_MESSAGE_LIMIT_BYTES,
+  RepresentativeError,
+  ackRepresentativeReply,
+  deliverRepresentativeReplies,
+  readRepresentativeReplies,
+  serializeRepresentativeResult,
+  representativeStatus,
+  sendRepresentativeMessage,
+  type RepresentativeContext,
+} from './representative-core.js';
+import { RepresentativeStoreError, bindingFingerprint } from './representative-store.js';
+import { createDeliveryStore } from './representative-delivery-store.js';
+import { createRepresentativeOwner } from './representative-owner.js';
+
+export const REPRESENTATIVE_TOOL_NAMES = [
+  'borg_representative-status',
+  'borg_representative-send',
+  'borg_representative-read',
+  'borg_representative-deliver',
+  'borg_representative-ack',
+] as const;
+
+export const REPRESENTATIVE_INSTRUCTIONS =
+  'You are connected as the human representative of one Borg cube: an automated delegate that relays the ' +
+  'human\'s requests, questions and decisions to ONE bound Coordinator drone and reads its replies. You are not the ' +
+  'Coordinator and not the human: never plan or dispatch work for other drones — the Coordinator does that. ' +
+  'Mark content user_authorized ONLY when the human explicitly said it; everything you originate is model_advice. ' +
+  'A relayed decision authorizes only its own text, never broader approval. ' +
+  REPRESENTATIVE_DELIVERY_NOTE;
+
+const TOOLS = [
+  {
+    name: 'borg_representative-status',
+    description:
+      'Show which cube, representative drone and Coordinator this connection is bound to, whether the live cube still matches, ' +
+      'any unresolved (ambiguous) sends, process ownership and the delivery limits. Read-only; never takes ownership.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'borg_representative-send',
+    description:
+      'Relay ONE human request, question or decision to the bound Coordinator. The recipient is fixed; workers and broadcast ' +
+      'are not addressable. Returns a request_id. If the outcome is "ambiguous" (the result names the cause), retry only ' +
+      'with the SAME request_id and identical content (server-deduplicated); never re-send under a new id. A ' +
+      'SEND_REJECTED error names the refusal and its recovery. Do not issue overlapping sends of the same content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['request', 'question', 'decision'] },
+        authorization: {
+          type: 'string',
+          enum: ['user_authorized', 'model_advice'],
+          description:
+            'user_authorized: the human explicitly said/approved this exact content. model_advice: your own suggestion. ' +
+            'A decision must be user_authorized.',
+        },
+        message: { type: 'string', description: `Plain text, at most ${REPRESENTATIVE_MESSAGE_LIMIT_BYTES} bytes.` },
+        request_id: {
+          type: 'string',
+          description: 'Omit for a new request. To retry, pass the request_id returned earlier with identical content.',
+        },
+      },
+      required: ['kind', 'authorization', 'message'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'borg_representative-read',
+    description:
+      'Read the bound Coordinator\'s replies addressed to this representative that come after your delivered checkpoint, ' +
+      'oldest first. Reading changes nothing: the same replies return on every call until you call ' +
+      'borg_representative-deliver. Persist each reply durably, route it by in_reply_to or hold it for the human, then ' +
+      'deliver through the last one you persisted. At most `limit` replies and `max_bytes` of serialized result; a reply ' +
+      'larger than max_bytes is returned whole and alone with oversize:true, and the result never exceeds ' +
+      'max(max_bytes, 16384) bytes (oversize citations reduced to ids, documents_reduced:true). has_more means more ' +
+      'replies follow the window; an empty page never has has_more. ' +
+      'Stop routing if binding_fingerprint differs from the value you persisted at binding time.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_broadcast: { type: 'boolean', description: 'Also return the Coordinator\'s cube-wide broadcasts (marked as such).' },
+        limit: { type: 'integer', minimum: 1, maximum: 50, description: 'Hard cap on returned replies. Default 10.' },
+        max_bytes: {
+          type: 'integer', minimum: 4096, maximum: 60000,
+          description: 'Hard cap on the serialized result size in bytes. Default 32768.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'borg_representative-deliver',
+    description:
+      'Record that every reply up to and including `through` is durably persisted by the host. Only this call moves the ' +
+      'read window. `through` must be a reply borg_representative-read returned; the same or an older id is a no-op ' +
+      '(advanced:false). Call it only after durable persistence: a delivered reply is not returned again. It does not ' +
+      'notify the Coordinator; that is borg_representative-ack.',
+    inputSchema: {
+      type: 'object',
+      properties: { through: { type: 'string', description: 'entry_id of the last reply you persisted.' } },
+      required: ['through'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'borg_representative-ack',
+    description:
+      'Signal to the Coordinator that one of its direct replies (entry_id from borg_representative-read) was received. ' +
+      'It is only that signal: it is not delivery, does not move the read window (that is borg_representative-deliver), ' +
+      'and is not needed for reading.',
+    inputSchema: {
+      type: 'object',
+      properties: { entry_id: { type: 'string' } },
+      required: ['entry_id'],
+      additionalProperties: false,
+    },
+  },
+] as const;
+
+function errorBody(error: unknown): { error: { code: string; message: string; details?: unknown } } {
+  if (error instanceof RepresentativeError || error instanceof RepresentativeStoreError) {
+    const details = error instanceof RepresentativeError ? error.details : undefined;
+    return { error: { code: error.code, message: error.message, ...(details ? { details } : {}) } };
+  }
+  const code = (error as { code?: unknown } | null)?.code;
+  return {
+    error: {
+      code: typeof code === 'string' ? code : 'BACKEND_ERROR',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    },
+  };
+}
+
+const toolResult = (body: unknown, isError = false) => ({
+  content: [{ type: 'text' as const, text: serializeRepresentativeResult(body) }],
+  ...(isError ? { isError: true } : {}),
+});
+
+export interface ServeRepresentativeOptions {
+  /** Resolved on every call; a throw fails that call closed. */
+  context: () => Promise<RepresentativeContext>;
+  /**
+   * The binding generation this process started with. Every call except status
+   * refuses with BINDING_MISMATCH, before any lease, ledger, checkpoint, cursor
+   * or network activity, once the saved binding's fingerprint differs.
+   */
+  pinnedFingerprint?: string;
+  version: string;
+  stdin?: Readable;
+  stdout?: Writable;
+  /** Internal timing seam for heartbeat controls; production uses 20 seconds. */
+  heartbeatIntervalMs?: number;
+}
+
+export async function serveRepresentativeMcp(
+  options: ServeRepresentativeOptions,
+): Promise<{ close: () => Promise<void>; closed: Promise<void> }> {
+  const owner = createRepresentativeOwner(options.heartbeatIntervalMs);
+  const server = new Server(
+    { name: 'borg-human-representative', version: options.version },
+    { capabilities: { tools: {} }, instructions: REPRESENTATIVE_INSTRUCTIONS },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map((tool) => ({ ...tool })) }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params.name;
+    const args = request.params.arguments ?? {};
+    try {
+      if (!(REPRESENTATIVE_TOOL_NAMES as readonly string[]).includes(name)) {
+        throw new RepresentativeError(ErrorCode.INVALID_INPUT, `Unknown tool ${JSON.stringify(name)}; this connection exposes only the representative tools.`);
+      }
+      const ctx = await options.context();
+      const pinned = options.pinnedFingerprint ? { pinned_binding_fingerprint: options.pinnedFingerprint } : {};
+      if (name === 'borg_representative-status') {
+        return toolResult({ ...await representativeStatus(ctx), ...pinned, ownership: await owner.snapshot(ctx.binding) });
+      }
+      if (options.pinnedFingerprint && bindingFingerprint(ctx.binding) !== options.pinnedFingerprint) {
+        throw new RepresentativeError(
+          'BINDING_MISMATCH',
+          'The operator rebound this connection (a new binding generation) while it was running. Restart the MCP server to use the new binding.',
+        );
+      }
+      // An untrustworthy delivery checkpoint stops every effect, not only read
+      // and deliver, so the refusal reaches the human. Read-only; status stays.
+      await createDeliveryStore(ctx.binding).load();
+      await owner.ensure(ctx.binding);
+      // Recheck at each network boundary, not just at tool dispatch: a process
+      // may have paused or lost its lease while awaiting live verification.
+      const backend = ctx.backend;
+      const guarded = { ...ctx, guard: () => owner.ensure(ctx.binding), backend: Object.fromEntries(['whoami', 'roster', 'append', 'readAfter', 'unreadCursor', 'readEntry', 'ack'].map((key) => [key, async (...args: unknown[]) => {
+        await owner.ensure(ctx.binding);
+        if (key === 'readAfter') args[2] = () => owner.ensure(ctx.binding);
+        const result = await (backend[key as keyof typeof backend] as (...args: unknown[]) => Promise<unknown>).apply(backend, args);
+        await owner.ensure(ctx.binding);
+        return result;
+      }])) as unknown as typeof backend };
+      switch (name) {
+        case 'borg_representative-send': {
+          const sent = await sendRepresentativeMessage(guarded, args);
+          return toolResult(sent, sent.outcome === 'ambiguous');
+        }
+        case 'borg_representative-read':
+          return toolResult(await readRepresentativeReplies(guarded, args));
+        case 'borg_representative-deliver':
+          return toolResult(await deliverRepresentativeReplies(guarded, args));
+        default:
+          return toolResult(await ackRepresentativeReply(guarded, args));
+      }
+    } catch (error) {
+      return toolResult(errorBody(error), true);
+    }
+  });
+
+  const transport = new StdioServerTransport(options.stdin, options.stdout);
+  let finish!: () => void;
+  const closed = new Promise<void>((resolve) => { finish = resolve; });
+  const shutdown = async () => {
+    process.removeListener('SIGTERM', signalClose);
+    process.removeListener('SIGINT', signalClose);
+    try { await owner.close(); } finally { finish(); }
+  };
+  const signalClose = () => { void server.close(); };
+  server.onclose = () => { void shutdown().catch(() => {}); };
+  process.once('SIGTERM', signalClose);
+  process.once('SIGINT', signalClose);
+  try { await server.connect(transport); } catch (error) { await shutdown(); throw error; }
+  return { close: async () => { await server.close(); await closed; }, closed };
+}

package/src/representative-owner.ts

@@ -0,0 +1,105 @@
+/** Lifecycle adapter for the existing stream lease; no separate lock protocol. */
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { borgConfigRoot, borgHomeRoot } from './private-root.js';
+import {
+  acquireStreamLease, readOwnershipSnapshot, STREAM_OWNER_STALE_MS,
+  type StreamLease, type StreamOwnerDeps, type StreamOwnershipSnapshot,
+} from './stream-owner.js';
+import { RepresentativeError } from './representative-core.js';
+import type { RepresentativeBinding } from './representative-store.js';
+
+export function representativeOwnerDeps(binding: RepresentativeBinding): StreamOwnerDeps {
+  const authority = createHash('sha256').update(JSON.stringify([binding.origin, binding.trustIdentity])).digest('hex');
+  return {
+    // Separate from stream-locks, which borg_stream-status inspects. One lease
+    // across all worktrees using this authority/cube/drone, never one per host.
+    locksDir: join(borgConfigRoot(), 'representative-host-locks', authority),
+    privateRoot: { root: borgConfigRoot(), boundary: borgHomeRoot() },
+    worktree: binding.worktree, droneLabel: binding.representativeLabel, cubeName: binding.cubeName,
+  };
+}
+
+export function representativeOwnership(binding: RepresentativeBinding): Promise<StreamOwnershipSnapshot> {
+  return privateStorage(() => readOwnershipSnapshot(binding.cubeId, binding.representativeDroneId, representativeOwnerDeps(binding)));
+}
+
+async function privateStorage<T>(operation: () => Promise<T>): Promise<T> {
+  try { return await operation(); }
+  catch (error) {
+    if (error instanceof RepresentativeError) throw error;
+    const message = error instanceof Error ? error.message : 'invalid private state';
+    // Only this exact directory-mode refusal permits manual permission recovery.
+    // Symlink, ownership and other failures must not suggest chmod through a path.
+    const looseDirectory = /^Borg credential store root (.+) has insecure permissions; expected 0700$/s.exec(message);
+    const detail = looseDirectory
+      ? `directory ${looseDirectory[1]} has insecure permissions; expected 0700. ` +
+        '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.'
+      : message.replace(/^Borg credential store /, '');
+    throw new RepresentativeError('REPRESENTATIVE_OWNERSHIP_REQUIRED',
+      'Representative lease storage refused: ' + detail);
+  }
+}
+
+export function createRepresentativeOwner(heartbeatIntervalMs = 20_000) {
+  let lease: StreamLease | null = null;
+  let selected: RepresentativeBinding | undefined;
+  let deps: StreamOwnerDeps;
+  let lost = false, closed = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let tail: Promise<unknown> = Promise.resolve();
+  const processNonce = randomUUID();
+  // Serialize lease mutations, including heartbeats, but NOT tool execution:
+  // overlapping sends still use the existing atomic request reservation.
+  const serial = <T>(op: () => Promise<T>): Promise<T> => {
+    const result = tail.then(op);
+    tail = result.catch(() => {});
+    return result;
+  };
+  const snapshot = (binding: RepresentativeBinding) => privateStorage(() => readOwnershipSnapshot(
+    binding.cubeId, binding.representativeDroneId,
+    { ...representativeOwnerDeps(binding), processNonce },
+  ));
+  const refuse = async (binding: RepresentativeBinding): Promise<never> => {
+    const owner = await snapshot(binding);
+    throw new RepresentativeError(
+      'REPRESENTATIVE_OWNERSHIP_REQUIRED',
+      `This representative is owned by another MCP process (pid ${owner.pid ?? 'unknown'}, started ${owner.startedAt ?? 'unknown'}), ` +
+      'or this process lost its lease. Use the owning host; after it exits or its lease expires, retry from the intended host. ' +
+      'Restart a process that lost ownership before using it again. Status remains available.',
+      { owner },
+    );
+  };
+  const refresh = async () => {
+    try {
+      if (!lease || !await lease.refresh()) lost = true;
+    } catch { lost = true; }
+    if (lost && timer) { clearInterval(timer); timer = undefined; }
+  };
+  return {
+    snapshot,
+    ensure: (binding: RepresentativeBinding) => serial(async () => {
+      if (selected && (selected.origin !== binding.origin || selected.trustIdentity !== binding.trustIdentity ||
+          selected.cubeId !== binding.cubeId || selected.representativeDroneId !== binding.representativeDroneId)) lost = true;
+      if (closed || lost) return refuse(binding);
+      if (lease) {
+        await refresh();
+        if (lost) return refuse(binding);
+        return;
+      }
+      deps = { ...representativeOwnerDeps(binding), processNonce };
+      lease = await privateStorage(() => acquireStreamLease(binding.cubeId, binding.representativeDroneId, STREAM_OWNER_STALE_MS, deps));
+      if (!lease) return refuse(binding);
+      selected = binding;
+      timer = setInterval(() => { void serial(refresh); }, heartbeatIntervalMs);
+      timer.unref();
+    }),
+    close: () => serial(async () => {
+      closed = true;
+      if (timer) { clearInterval(timer); timer = undefined; }
+      await lease?.release();
+      lease = null;
+    }),
+  };
+}

package/src/representative-store.ts

@@ -0,0 +1,224 @@
+/**
+ * Private on-disk state for the human representative connection.
+ *
+ * One 0600 file under the Borg config root holds, per representative worktree:
+ * - the BINDING: the one explicit cube + Coordinator drone this worktree's
+ *   dedicated seat may talk to. Changing it requires an explicit operator rebind.
+ * - the REQUEST LEDGER: one record per sent request id, so a retry never becomes
+ *   a second message and an ambiguous send survives a reconnect.
+ *
+ * The file never holds a bearer (the seat store owns credentials) and never
+ * holds message text (only a payload digest).
+ */
+
+import { decodeUuid } from 'borgmcp-shared/protocol';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { borgConfigRoot } from './private-root.js';
+import { shellEscape } from './shell-escape.js';
+import { readStoreFile, withStore } from './seat-store.js';
+
+export function isRepresentativeUuid(value: unknown): value is string {
+  try { decodeUuid(value); return true; } catch { return false; }
+}
+const SETTLED_REQUEST_LIMIT = 200;
+
+/**
+ * Host fence for one binding generation: hex SHA-256 of the canonical JSON array
+ * [origin, trustIdentity, cubeId, representativeDroneId, coordinatorDroneId,
+ * boundAt]. It changes on every rebind (boundAt) and trust change, and carries
+ * no path or credential.
+ */
+export function bindingFingerprint(binding: RepresentativeBinding): string {
+  return createHash('sha256').update(JSON.stringify([
+    binding.origin, binding.trustIdentity, binding.cubeId,
+    binding.representativeDroneId, binding.coordinatorDroneId, binding.boundAt,
+  ])).digest('hex');
+}
+
+export interface RepresentativeBinding {
+  /** Canonical worktree holding the dedicated representative seat. */
+  worktree: string;
+  origin: string;
+  trustIdentity: string;
+  cubeId: string;
+  cubeName: string;
+  representativeDroneId: string;
+  representativeLabel: string;
+  representativeRoleName: string;
+  coordinatorDroneId: string;
+  coordinatorLabel: string;
+  coordinatorRoleName: string;
+  repositoryOrigin?: string;
+  boundAt: string;
+}
+
+export function representativeRecoveryCommand(binding: RepresentativeBinding): string {
+  return `cd ${shellEscape(binding.worktree)} && borg representative prepare --coordinator ${shellEscape(binding.coordinatorLabel)} --role ${shellEscape(binding.representativeRoleName)} --rebind`;
+}
+
+export type RepresentativeRequestState = 'pending' | 'ambiguous' | 'sent' | 'rejected';
+
+export interface RepresentativeRequestRecord {
+  /** Stable request identity; also the protocol `post_id` idempotency key. */
+  requestId: string;
+  /** sha256 of kind, authorization, message, cube and Coordinator — never the text. */
+  payloadDigest: string;
+  kind: string;
+  authorization: string;
+  state: RepresentativeRequestState;
+  entryId?: string;
+  /** An attempt under this id may have reached the log; a later refusal must not clear that. */
+  maybeStored?: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface RepresentativeFile {
+  version: 1;
+  bindings: Record<string, RepresentativeBinding>;
+  requests: Record<string, RepresentativeRequestRecord[]>;
+}
+
+export class RepresentativeStoreError extends Error {
+  constructor(readonly code: 'BINDING_CONFLICT', message: string) {
+    super(message);
+    this.name = 'RepresentativeStoreError';
+  }
+}
+
+export interface RepresentativeStore {
+  getBinding(worktree: string): Promise<RepresentativeBinding | null>;
+  readRequests(worktree: string): Promise<RepresentativeRequestRecord[]>;
+  saveBinding(
+    binding: RepresentativeBinding,
+    options: { rebind: boolean },
+  ): Promise<'created' | 'unchanged' | 'rebound'>;
+  /** Read-compare-write over one worktree's ledger under the store lock. */
+  transactRequests<T>(
+    worktree: string,
+    op: (records: RepresentativeRequestRecord[]) => T,
+  ): Promise<T>;
+}
+
+const BINDING_STRING_FIELDS = [
+  'worktree', 'origin', 'trustIdentity', 'cubeId', 'cubeName',
+  'representativeDroneId', 'representativeLabel', 'representativeRoleName',
+  'coordinatorDroneId', 'coordinatorLabel', 'coordinatorRoleName', 'boundAt',
+] as const;
+
+function validBinding(value: unknown, key: string): value is RepresentativeBinding {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const binding = value as Record<string, unknown>;
+  return BINDING_STRING_FIELDS.every((field) => typeof binding[field] === 'string' && binding[field] !== '') &&
+    binding.worktree === key &&
+    isRepresentativeUuid(binding.cubeId as string) &&
+    isRepresentativeUuid(binding.representativeDroneId as string) &&
+    isRepresentativeUuid(binding.coordinatorDroneId as string) &&
+    binding.representativeDroneId !== binding.coordinatorDroneId &&
+    (binding.repositoryOrigin === undefined || typeof binding.repositoryOrigin === 'string');
+}
+
+function validRequest(value: unknown): value is RepresentativeRequestRecord {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return isRepresentativeUuid(String(record.requestId ?? '')) &&
+    typeof record.payloadDigest === 'string' &&
+    typeof record.kind === 'string' &&
+    typeof record.authorization === 'string' &&
+    ['pending', 'ambiguous', 'sent', 'rejected'].includes(record.state as string) &&
+    (record.entryId === undefined || typeof record.entryId === 'string') &&
+    (record.maybeStored === undefined || typeof record.maybeStored === 'boolean') &&
+    typeof record.createdAt === 'string' &&
+    typeof record.updatedAt === 'string';
+}
+
+function parseFile(raw: string): RepresentativeFile | null {
+  const parsed = JSON.parse(raw) as Partial<RepresentativeFile> | null;
+  if (
+    parsed === null || typeof parsed !== 'object' || parsed.version !== 1 ||
+    parsed.bindings === null || typeof parsed.bindings !== 'object' || Array.isArray(parsed.bindings) ||
+    parsed.requests === null || typeof parsed.requests !== 'object' || Array.isArray(parsed.requests)
+  ) return null;
+  for (const [key, binding] of Object.entries(parsed.bindings)) {
+    if (!validBinding(binding, key)) return null;
+  }
+  for (const records of Object.values(parsed.requests)) {
+    if (!Array.isArray(records) || !records.every(validRequest)) return null;
+  }
+  return parsed as RepresentativeFile;
+}
+
+const emptyFile = (): RepresentativeFile => ({ version: 1, bindings: {}, requests: {} });
+
+function sameSelection(a: RepresentativeBinding, b: RepresentativeBinding): boolean {
+  return a.origin === b.origin &&
+    a.trustIdentity === b.trustIdentity &&
+    a.cubeId === b.cubeId &&
+    a.representativeDroneId === b.representativeDroneId &&
+    a.coordinatorDroneId === b.coordinatorDroneId;
+}
+
+/** Settled history is bounded; unresolved (pending/ambiguous) records are never dropped. */
+function pruneSettled(records: RepresentativeRequestRecord[]): RepresentativeRequestRecord[] {
+  const settled = records.filter((record) => record.state === 'sent' || record.state === 'rejected');
+  if (settled.length <= SETTLED_REQUEST_LIMIT) return records;
+  const drop = new Set(settled.slice(0, settled.length - SETTLED_REQUEST_LIMIT).map((record) => record.requestId));
+  return records.filter((record) => !drop.has(record.requestId));
+}
+
+export function representativeStorePath(): string {
+  return join(borgConfigRoot(), 'representative.json');
+}
+
+export function createRepresentativeStore(storePath: string = representativeStorePath()): RepresentativeStore {
+  // Atomic writer renames make a single read a complete snapshot, without a
+  // store-lock write or pruning settled history during read-only status.
+  const read = async () => {
+    const raw = await readStoreFile(storePath);
+    if (raw === null) return emptyFile();
+    let data: RepresentativeFile | null;
+    try { data = parseFile(raw); } catch { data = null; }
+    if (!data) throw new Error('Borg representative store is malformed or unsupported; refusing to read it');
+    return data;
+  };
+  return {
+    getBinding: async (worktree) => (await read()).bindings[worktree] ?? null,
+    readRequests: async (worktree) => (await read()).requests[worktree] ?? [],
+
+    saveBinding: (binding, options) => withStore(storePath, emptyFile, parseFile, async (txn) => {
+      if (!validBinding(binding, binding.worktree)) {
+        throw new Error('Refusing to save an invalid representative binding');
+      }
+      const existing = txn.data.bindings[binding.worktree];
+      // An explicit rebind always starts a new generation (new boundAt, so a new
+      // binding_fingerprint), even for the same selection.
+      if (existing && sameSelection(existing, binding) && !options.rebind) return 'unchanged' as const;
+      if (existing && !options.rebind) {
+        throw new RepresentativeStoreError(
+          'BINDING_CONFLICT',
+          `This worktree is already bound to Coordinator ${existing.coordinatorLabel} in cube ${existing.cubeName}. ` +
+            `To confirm the new selection, run \`${representativeRecoveryCommand(binding)}\`.`,
+        );
+      }
+      txn.data.bindings[binding.worktree] = binding;
+      // A different selection invalidates the old ledger: its post ids belong to
+      // another cube/Coordinator conversation.
+      if (existing && !sameSelection(existing, binding)) delete txn.data.requests[binding.worktree];
+      await txn.commit();
+      return existing ? 'rebound' as const : 'created' as const;
+    }),
+
+    transactRequests: (worktree, op) => withStore(storePath, emptyFile, parseFile, async (txn) => {
+      const records = txn.data.requests[worktree] ?? [];
+      const before = JSON.stringify(records);
+      const result = op(records);
+      const next = pruneSettled(records);
+      if (JSON.stringify(next) !== before) {
+        txn.data.requests[worktree] = next;
+        await txn.commit();
+      }
+      return result;
+    }),
+  };
+}

package/src/seat-probe.ts

@@ -68,7 +68,7 @@ const TRANSPORT_ERRNOS = new Set([
   'ABORT_ERR',
 ]);
 
-function isTransportFailure(err: unknown): boolean {
+export function isTransportFailure(err: unknown): boolean {
   if (err instanceof BorgServerUnreachableError) return true;
   const e = err as { name?: string; code?: string; cause?: { code?: string } };
   if (e?.name === 'AbortError') return true;