borgmcp 5.5.0 → 5.7.0

package/src/representative-mcp.ts

@@ -2,8 +2,9 @@
  * 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 four tools: status, send
- * (to the ONE bound Coordinator), read (that Coordinator's replies) and ack.
+ * 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.
  *
@@ -21,18 +22,22 @@ import {
   REPRESENTATIVE_MESSAGE_LIMIT_BYTES,
   RepresentativeError,
   ackRepresentativeReply,
+  deliverRepresentativeReplies,
   readRepresentativeReplies,
+  serializeRepresentativeResult,
   representativeStatus,
   sendRepresentativeMessage,
   type RepresentativeContext,
 } from './representative-core.js';
-import { RepresentativeStoreError } from './representative-store.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;
 
@@ -83,29 +88,47 @@ const TOOLS = [
   {
     name: 'borg_representative-read',
     description:
-      'Read unread replies from the bound Coordinator addressed to this representative. Replies arrive only when this tool ' +
-      'is called; there is no background wake. Each call DRAINS the whole fetched unread page for this drone — returned ' +
-      'replies and ignored entries alike (other drones\' entries are counted, never returned) — so they will not appear ' +
-      'unread again: persist the result, then route each reply by in_reply_to to its conversation or hold it for the human. If the host stops before persisting, the reply ' +
-      'is no longer in the unread view.',
+      '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: 200,
-          description: 'Page-size hint, not a hard cap: a large unread backlog may return (and drain) more entries.',
+        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 does not make delivery reliable, does not move or restore the unread cursor, and is ' +
-      'not needed for reading.',
+      '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' } },
@@ -130,13 +153,19 @@ function errorBody(error: unknown): { error: { code: string; message: string; de
 }
 
 const toolResult = (body: unknown, isError = false) => ({
-  content: [{ type: 'text' as const, text: JSON.stringify(body, null, 2) }],
+  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;
@@ -163,16 +192,26 @@ export async function serveRepresentativeMcp(
         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), ownership: await owner.snapshot(ctx.binding) });
+        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, backend: Object.fromEntries(['whoami', 'roster', 'append', 'readUnread', 'readEntry', 'ack'].map((key) => [key, async (...args: unknown[]) => {
+      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 === 'readUnread') args[1] = () => 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;
@@ -184,6 +223,8 @@ export async function serveRepresentativeMcp(
         }
         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));
       }

package/src/representative-store.ts

@@ -12,6 +12,7 @@
  */
 
 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';
@@ -22,6 +23,19 @@ export function isRepresentativeUuid(value: unknown): value is string {
 }
 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;
@@ -177,7 +191,9 @@ export function createRepresentativeStore(storePath: string = representativeStor
         throw new Error('Refusing to save an invalid representative binding');
       }
       const existing = txn.data.bindings[binding.worktree];
-      if (existing && sameSelection(existing, binding)) return 'unchanged' as const;
+      // 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',
@@ -188,7 +204,7 @@ export function createRepresentativeStore(storePath: string = representativeStor
       txn.data.bindings[binding.worktree] = binding;
       // A different selection invalidates the old ledger: its post ids belong to
       // another cube/Coordinator conversation.
-      if (existing) delete txn.data.requests[binding.worktree];
+      if (existing && !sameSelection(existing, binding)) delete txn.data.requests[binding.worktree];
       await txn.commit();
       return existing ? 'rebound' as const : 'created' as const;
     }),

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;

package/src/server-trust.ts

@@ -457,12 +457,7 @@ export async function loadBorgServerTrust(
     let pending = trustCache.get(key);
     if (!pending) {
       pending = (async () => {
-        const [certificate, configText] = await Promise.all([
-          readTrustFile(join(directory, 'ca.crt')),
-          readTrustFile(join(directory, 'server.json')),
-        ]);
-        const config = decodeTrustConfig(configText);
-        const identity = verifyCaIdentity(certificate, config.ca_spki_sha256);
+        const { certificate, identity } = await readLocalAuthorityTrust(directory);
         return { identity, fetchImpl: createPinnedServerFetch(origin, certificate) };
       })();
       trustCache.set(key, pending);
@@ -494,6 +489,30 @@ export async function loadBorgServerTrust(
   });
 }
 
+async function readLocalAuthorityTrust(directory: string): Promise<{ certificate: string; identity: string }> {
+  const [certificate, configText] = await Promise.all([
+    readTrustFile(join(directory, 'ca.crt')),
+    readTrustFile(join(directory, 'server.json')),
+  ]);
+  return { certificate, identity: verifyCaIdentity(certificate, decodeTrustConfig(configText).ca_spki_sha256) };
+}
+
+/**
+ * The current trust identity for `origin`, read from disk on every call with the
+ * same source selection and file checks as loadBorgServerTrust. Its local-authority
+ * branch caches for the process lifetime, which a continuation guard on a
+ * long-lived connection must not rely on; the enrollment branch already rereads
+ * its pointer per call. It returns the identity only and grants no trust. The
+ * local-authority branch builds no fetch; the enrollment delegation may construct
+ * the loader's pinned fetch on a cache miss, but this function sends no request.
+ */
+export async function readBorgServerTrustIdentity(origin: string): Promise<string> {
+  if (!await remoteTrustStateExists(origin) && await trustFilesExist(serverDataDirectory())) {
+    return (await readLocalAuthorityTrust(serverDataDirectory())).identity;
+  }
+  return (await loadBorgServerTrust(origin)).identity;
+}
+
 function pemCertificate(raw: Buffer): string {
   const body = raw.toString('base64').match(/.{1,64}/g)?.join('\n') ?? '';
   return `-----BEGIN CERTIFICATE-----\n${body}\n-----END CERTIFICATE-----\n`;

package/src/stream-owner.ts

@@ -139,8 +139,37 @@ export async function readOwnershipSnapshot(
   deps: StreamOwnerDeps = {}
 ): Promise<StreamOwnershipSnapshot> {
   const lockPath = streamLockPath(cubeId, droneId, deps.locksDir);
-  const inspected = await readBoundOwner(lockPath, deps);
-  if (!inspected) return { state: 'unowned', lockPath };
+  // A refresh renames the lock to `<lock>.takeover` while it rewrites the record
+  // and then restores it. Read-only: report an intact, fresh, live in-flight
+  // owner there; a stale, future-dated, dead or malformed leftover stays
+  // `unowned`. A missing directory or owner leaf is re-resolved from the lock
+  // path, so one refresh overlapping any step cannot hide the owner; genuine
+  // initialization still reports `initializing` after the bounded attempts.
+  let initializing: StreamOwnershipSnapshot | undefined;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const inspected = await readBoundOwner(lockPath, deps);
+    if (inspected) {
+      const snapshot = snapshotFromOwner(lockPath, inspected, deps);
+      if (inspected.raw !== null) return snapshot;
+      initializing = snapshot;
+      continue;
+    }
+    const claimed = await readBoundOwner(takeoverPath(lockPath), deps);
+    if (!claimed || claimed.raw === null) continue;
+    const snapshot = snapshotFromOwner(lockPath, claimed, deps);
+    const ageMs = snapshot.ageMs ?? Infinity;
+    const live = snapshot.pid !== undefined && ageMs >= 0 && ageMs <= STREAM_OWNER_STALE_MS &&
+      isPidAlive(snapshot.pid, deps);
+    return live ? snapshot : { state: 'unowned', lockPath };
+  }
+  return initializing ?? { state: 'unowned', lockPath };
+}
+
+function snapshotFromOwner(
+  lockPath: string,
+  inspected: { raw: string | null; stat: { dev: number; ino: number; mtimeMs: number } },
+  deps: StreamOwnerDeps,
+): StreamOwnershipSnapshot {
   const { raw, stat: lockStat } = inspected;
   if (raw === null) {
     const now = (deps.now ?? (() => new Date()))();
@@ -666,6 +695,9 @@ async function readBoundOwner(lockPath: string, deps: StreamOwnerDeps = {}): Pro
           ? await readStoreFile(path.join(lockPath, OWNER_FILE), { secureRoot: lockPath, createRoot: false })
           : await fs.readFile(path.join(lockPath, OWNER_FILE), 'utf8');
       } catch (error: any) {
+        // A concurrent refresh atomically replaces the owner file; like other
+        // lock inspection, that identity drift is turnover and is re-read.
+        if (error?.code === 'STORE_FILE_IDENTITY_CHANGED') continue;
         if (error?.code !== 'ENOENT') throw error;
         raw = null;
       }