borgmcp 2.14.0 → 2.14.2

package/docs/EXTRACTION_PROVENANCE.md

@@ -22,7 +22,7 @@ The extraction copied the monorepo's `client/src/` production boundary and top-l
   recovery, `2.0.2`, `2.0.3`, `2.0.4`, `2.0.5`, and `2.0.6` successors were
   published and registry-verified. The immutable `2.0.7` workflow failed before
   package creation or npm publication. The `2.0.8`, `2.0.9`, `2.0.10`, `2.0.11`,
-  `2.1.0`, and `2.1.1` successors were published, and `2.2.0` was subsequently published, and `2.3.0` was subsequently published, and `2.4.0` was subsequently published, and `2.4.1` was subsequently published, and `2.5.0` was subsequently published, and `2.6.0` was subsequently published, and `2.6.1` was subsequently published, and `2.7.0` was subsequently published, and `2.7.1` was subsequently published, and `2.7.2` was subsequently published, and `2.7.3` was subsequently published, and `2.8.0` was subsequently published, and `2.9.0` was subsequently published, and `2.10.0` was subsequently published, and the immutable `2.10.1` release attempt failed before artifact creation or publication. The `2.10.2`, `2.11.0`, `2.12.1`, and `2.13.0` successors were published; the immutable `2.12.0` attempt failed before artifact creation or publication and was superseded by `2.12.1`. The next candidate identity is `2.14.0`. Extraction and
+  `2.1.0`, and `2.1.1` successors were published, and `2.2.0` was subsequently published, and `2.3.0` was subsequently published, and `2.4.0` was subsequently published, and `2.4.1` was subsequently published, and `2.5.0` was subsequently published, and `2.6.0` was subsequently published, and `2.6.1` was subsequently published, and `2.7.0` was subsequently published, and `2.7.1` was subsequently published, and `2.7.2` was subsequently published, and `2.7.3` was subsequently published, and `2.8.0` was subsequently published, and `2.9.0` was subsequently published, and `2.10.0` was subsequently published, and the immutable `2.10.1` release attempt failed before artifact creation or publication. The `2.10.2`, `2.11.0`, `2.12.1`, and `2.13.0` successors were published; the immutable `2.12.0` attempt failed before artifact creation or publication and was superseded by `2.12.1`. The current release identity is `2.14.2`. Extraction and
   versioning do not authorize publication.
 
 ## Review Holds
@@ -47,7 +47,6 @@ client `borgmcp@2.10.0` line. Its annotated tag object
 `sha512-lOxIPg3WcjSBte46iTM7SAFVN6Y0b2oizOKAJ9Q1EijBdOlmsh/cQlpUIaa8F2UJPaTDFsXy3M64gpGs6XgKzA==`
 in the `borgmcp-server-0.9.0-release` registry decision. That server and its
 client line pin historical `borgmcp-shared` version `0.8.1` and remain
-immutable. Client `borgmcp@2.10.2` is published. The immutable `v2.0.7`
-attempt failed before publication and remains preserved. Publication of the next
-candidate remains gated by reviewed `v2.14.0` source, a fresh annotated tag, and
+immutable. Client `borgmcp@2.14.1` is published. The immutable `v2.0.7`
+attempt failed before publication and remains preserved. The current release identity and publication gate remain governed by the reviewed `v2.14.2` source, a fresh annotated tag, and
 the exact-artifact and protected-publication gates.

package/docs/RELEASING.md

@@ -205,8 +205,18 @@ Never move, replace, reuse, or rerun that tag or workflow. The annotated `v2.13.
 `fc5e4d9299210b70f979c7d39130a9c12ea265ea`. Workflow run `30894287863`, attempt 1,
 successfully published that exact source as `borgmcp@2.13.0`; the same-run artifact report records integrity
 `sha512-YuF3NwY5iBRVKhgdRiK+3GX+6O8O7S/V9g+XYN/1A0so9RLIYoQWpS91qJewqGQ59nyIARjRmk2wKhK8ODxU0Q==`.
+Never move, replace, reuse, or rerun that tag or workflow. The annotated `v2.14.0` tag object
+`eb9d5cb14b08b1a2eb6d48b2492acbc6cecb7bef` peels to protected-main commit
+`4dd92bcbac26f460a4f137f766992e8f93843576`. Workflow run `30929322201`, attempt 1,
+successfully published that exact source as `borgmcp@2.14.0`; the same-run artifact report records integrity
+`sha512-haKgpQbcbaRya1XqYQaOy7yZiHMxeP8QO3fr7ahHaYDNYrDvlGmXNlW9VMtqnRJ9mtVDC5UTkeuQmCRJMzF/Tg==`.
+Never move, replace, reuse, or rerun that tag or workflow. The annotated `v2.14.1` tag object
+`c1c8b526dcc31259f6b821f0a6fdd0017a42435c` peels to protected-main commit
+`3de4cbf2e5adf6883334fe4e9b7aa1f43868daae`. Workflow run `30943397747`, attempt 1,
+successfully published that exact source as `borgmcp@2.14.1`; the same-run artifact report records integrity
+`sha512-VqkOp3jo/KnzgusCk98TFj/U8U7Q/gt8agvIbjiSWrV0lIHnsD+A+7w3C+GMQeyA08KXxRuZDF3No9sDomqMTQ==`.
 Never move, replace, reuse, or rerun that tag or workflow. The next candidate
-uses the unused `v2.14.0` identity from a fresh reviewed protected-main commit
+uses the unused `v2.14.2` identity from a fresh reviewed protected-main commit
 and requires the complete release gate again.
 
 ## Release Prerequisites

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",

package/src/assimilate-cmd.ts

@@ -1060,7 +1060,7 @@ export async function runAssimilate(
     }
     if (error instanceof RepositoryAssociationOperationError) {
       const recovery = error.failure === 'repository-already-associated'
-        ? 'This repository is already associated with another cube. Run the same command again to use the existing managed association, or ask the server operator to correct the repository binding.'
+        ? 'This repository is already associated with another cube. The selected cube grant is valid, but it cannot replace that existing repository binding. Run the same command again to use the existing managed association, or ask the server operator to correct the repository binding.'
         : error.failure === 'cube-already-associated'
           ? 'The selected cube is already associated with another repository. Choose a different cube, or run the command from the repository already linked to that cube.'
           : error.failure === 'access-denied'

package/src/inbox-monitor.ts

@@ -42,6 +42,12 @@ const ENTRY_LINE_RE =
   /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\S*)\s+(\S+)\s+\(([^)]+)\):\s*(.*)$/;
 
 export const RECENT_EMITTED_LINE_CAP = 1024;
+/**
+ * Allow a small amount of server/host clock skew at monitor arm. Lines older
+ * than this boundary are historical materialized inbox content, not live
+ * activity for this monitor instance.
+ */
+export const INBOX_ARM_TIMESTAMP_SKEW_MS = 5_000;
 
 export class RecentLineDeduper {
   private readonly seen = new Set<string>();
@@ -86,13 +92,35 @@ export function formatEventLine(inboxLine: string): string | null {
   return `${label} (${role}): ${summary}`;
 }
 
+/**
+ * Return whether an inbox entry is fresh enough to have been produced after
+ * this monitor armed. A malformed timestamp fails closed when this guard is
+ * active; callers without an arm boundary retain the legacy parser behavior.
+ */
+export function isInboxLineAtOrAfterArm(
+  inboxLine: string,
+  armTimeMs: number,
+  skewMs = INBOX_ARM_TIMESTAMP_SKEW_MS,
+): boolean {
+  const match = ENTRY_LINE_RE.exec(inboxLine);
+  if (!match || !Number.isFinite(armTimeMs) || !Number.isFinite(skewMs) || skewMs < 0) {
+    return false;
+  }
+  const timestampMs = Date.parse(match[1]);
+  return Number.isFinite(timestampMs) && timestampMs >= armTimeMs - skewMs;
+}
+
 export function formatFreshEventLine(
   inboxLine: string,
   deduper: RecentLineDeduper,
   includeWakeMessage = false,
+  armTimeMs?: number,
 ): string | null {
   const pretty = formatEventLine(inboxLine);
   if (pretty === null) return null;
+  if (armTimeMs !== undefined && !isInboxLineAtOrAfterArm(inboxLine, armTimeMs)) {
+    return null;
+  }
   return deduper.remember(inboxLine)
     ? includeWakeMessage ? formatCubeActivityWakeMessage(pretty) : pretty
     : null;
@@ -887,6 +915,7 @@ function main(): void {
   // wire behavior is identical — only the per-line projection changes.
   // `-n 0` skips backfilling history so fresh sessions don't replay
   // old entries on every restart.
+  const monitorArmTimeMs = Date.now();
   const deduper = new RecentLineDeduper();
   seedDeduperFromInboxTail(inboxPath, deduper);
 
@@ -918,7 +947,7 @@ function main(): void {
 
     const rl = createInterface({ input: tail.stdout, crlfDelay: Infinity });
     rl.on('line', (line) => {
-      const pretty = formatFreshEventLine(line, deduper, true);
+      const pretty = formatFreshEventLine(line, deduper, true, monitorArmTimeMs);
       if (pretty !== null) {
         console.log(pretty);
         // Delivered → the tail is current; re-anchor the offset to the live

package/src/log-stream.ts

@@ -739,7 +739,10 @@ export async function streamOnce(
   // Local mirror of the resume cursor, updated AFTER each successful
   // disk write (or dedup-recognized replay). Heartbeat-hwm comparison
   // reads this value.
-  let lastPersistedEventId: string | null = lastEventId;
+  // Seed it from the persisted cursor as well as the in-memory Last-Event-ID:
+  // a reconnect after process restart must not treat the cursor's durable
+  // horizon as unknown while catchup is being replayed.
+  let lastPersistedEventId: string | null = cursor?.id ?? lastEventId;
   let lastBroadcastHwm: BroadcastHwm | null = null;
   let pendingHwmDivergence:
     | { hwm: BroadcastHwm; timer: NodeJS.Timeout }
@@ -769,7 +772,9 @@ export async function streamOnce(
   // a created_at would itself widen the next reconnect's window (the very
   // storm this fixes). Proven older-or-equal events are still recorded in
   // recentIds for dedup but do not move the cursor or re-fire onEventId.
-  let lastPersistedHwm: BroadcastHwm | null = null;
+  let lastPersistedHwm: BroadcastHwm | null = cursor
+    ? { id: cursor.id, created_at: cursor.created_at }
+    : null;
   const markEventPersisted = (id: string, createdAt: string) => {
     const next: BroadcastHwm = { id, created_at: createdAt };
     if (
@@ -842,16 +847,36 @@ export async function streamOnce(
     const line = formatInboxLine(withSseEventId(ev.data, ev.id));
     const deliveryId = ev.wake_nonce ?? ev.id;
     const isReping = ev.wake_nonce !== undefined;
-    const alreadyPersisted = (ev.wake_nonce !== undefined || isCatchingUp) && (
-      // gh#441: pass the rendered line so the dedup can also recognize LEGACY
-      // (no-entry_id-prefix) on-disk lines, not just the [entry_id:] marker.
+    const eventHwm = ev.data?.created_at
+      ? { id: ev.id, created_at: ev.data.created_at }
+      : null;
+    const atOrBeforeResumeCursor = Boolean(
+      isCatchingUp &&
+      lastPersistedHwm &&
+      eventHwm &&
+      compareBroadcastHwm(eventHwm, lastPersistedHwm) <= 0
+    );
+    // The persisted stream cursor is the authoritative catchup horizon. Only
+    // fall back to file-content inspection when there is no comparable cursor
+    // (legacy/no-cursor sessions), or for a nonce reping whose durable line is
+    // intentionally reused while its wake identity is delivered again.
+    const consultInboxFile = ev.wake_nonce !== undefined ||
+      (isCatchingUp && lastPersistedHwm === null);
+    const alreadyPersisted = atOrBeforeResumeCursor || (
+      consultInboxFile &&
+      // gh#441: pass the rendered line so the fallback dedup can also
+      // recognize LEGACY (no-entry_id-prefix) on-disk lines, not just the
+      // [entry_id:] marker.
       await hasInboxEntryId(active.cubeId, active.droneId, ev.id, line)
     );
     if (alreadyPersisted) {
-      // Replay still re-enters the OpenCode delivery queue. Ordinary entries
-      // correlate by canonical inbox text; re-pings add a stable nonce marker
-      // to the injected text so each distinct nonce submits exactly once.
-      await injectOpenCode(formatOpenCodeWakePrompt(line, ev.wake_nonce), deliveryId, isReping);
+      // An ordinary entry at/before the persisted cursor is already delivered
+      // and must not re-enter the OpenCode queue. Re-pings are the explicit
+      // exception: each wake nonce is a new delivery identity even when the
+      // underlying inbox line is already durable.
+      if (isReping) {
+        await injectOpenCode(formatOpenCodeWakePrompt(line, ev.wake_nonce), deliveryId, true);
+      }
       markEventPersisted(ev.id, ev.data?.created_at ?? '');
       return 'persisted-skip';
     }

package/src/remote-client.ts

@@ -80,6 +80,11 @@ export interface RemoteConnection {
 // retryAfter can't wedge the call.
 const RATE_LIMIT_MAX_RETRIES = 3;
 const RATE_LIMIT_MAX_WAIT_MS = 60_000; // cap a single Retry-After honor
+const UNREAD_CURSOR_MAX_TRANSPORT_RETRIES = 1;
+// Replay is opt-in: most local requests are mutations or have ambiguous
+// delivery, while unread-log reads carry an explicit cursor and are safe to
+// repeat with the exact same request body.
+type AuthedFetchRetryMode = 'unread-cursor';
 export const LOCAL_SERVER_RESPONSE_LIMIT_BYTES = 32 * 1024 * 1024;
 // A typed auth-error envelope is tiny; anything larger is hostile and the
 // bounded read throws → the 401 fails closed to non-destructive CREDENTIAL_REJECTED.
@@ -179,6 +184,25 @@ export async function retryOn429(
   return response;
 }
 
+function isConnectionReset(error: unknown): boolean {
+  let candidate: unknown = error;
+  for (let depth = 0; depth < 2; depth += 1) {
+    if (candidate === null || typeof candidate !== 'object') return false;
+    const typed = candidate as { code?: unknown; cause?: unknown };
+    if (typed.code === 'ECONNRESET') return true;
+    candidate = typed.cause;
+  }
+  return false;
+}
+
+function unreadLogTransportFailure(cause: unknown): BorgServerUnreachableError {
+  return new BorgServerUnreachableError(
+    'Borg could not complete the unread log read after one automatic retry. ' +
+      'The request may have reached the server; repeat `borg_read-log unread_only=true` until caught up.',
+    { cause },
+  );
+}
+
 async function localAuthorityContext(
   sessionToken: string,
   apiUrl: string,
@@ -271,6 +295,7 @@ async function localServerRequest<T>(
   path: string,
   method: 'GET' | 'POST' | 'PUT' | 'PATCH',
   payload?: Record<string, unknown>,
+  options: { retryMode?: AuthedFetchRetryMode } = {},
 ): Promise<T | null> {
   return decodeLocalProtocolResponse<T>((signal) => authedFetch(path, {
       method,
@@ -286,6 +311,7 @@ async function localServerRequest<T>(
           headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
           body: JSON.stringify(createProtocolEnvelope(randomUUID(), payload)),
         }),
+      retryMode: options.retryMode,
     }), true);
 }
 
@@ -492,7 +518,11 @@ function localCursorBinding(active: ActiveCube) {
 
 async function localReadLogPage(
   active: ActiveCube,
-  opts: { cursor?: LocalServerCursor | null; limit?: number } = {},
+  opts: {
+    cursor?: LocalServerCursor | null;
+    limit?: number;
+    retryMode?: AuthedFetchRetryMode;
+  } = {},
 ): Promise<any> {
   const payload = await localServerRequest<any>(
     active,
@@ -502,6 +532,7 @@ async function localReadLogPage(
       cursor: opts.cursor ?? null,
       ...(opts.limit === undefined ? {} : { limit: opts.limit }),
     },
+    { retryMode: opts.retryMode },
   );
   if (!payload) throw new Error('Local Borg server returned an empty log response');
   return payload;
@@ -627,6 +658,7 @@ async function authedFetch(
     authToken?: string;
     serverTrustIdentity?: string;
     localSessionCredentialRef?: string;
+    retryMode?: AuthedFetchRetryMode;
   } = {}
 ): Promise<Response> {
   const {
@@ -635,6 +667,7 @@ async function authedFetch(
     authToken,
     serverTrustIdentity: suppliedTrustIdentity,
     localSessionCredentialRef,
+    retryMode,
     headers,
     ...rest
   } = init;
@@ -697,7 +730,35 @@ async function authedFetch(
     return res;
   };
 
-  const response = await buildRequest(token);
+  let transportRetriesRemaining = retryMode === 'unread-cursor'
+    ? UNREAD_CURSOR_MAX_TRANSPORT_RETRIES
+    : 0;
+  const requestWithRetry = async (): Promise<Response> => {
+    try {
+      return await buildRequest(token);
+    } catch (error) {
+      if (retryMode !== 'unread-cursor' || !isConnectionReset(error)) throw error;
+      if (transportRetriesRemaining === 0) throw unreadLogTransportFailure(error);
+      transportRetriesRemaining -= 1;
+      debugLog('↻ retrying unread log read after ECONNRESET');
+      try {
+        return await buildRequest(token);
+      } catch (retryError) {
+        if (isConnectionReset(retryError)) throw unreadLogTransportFailure(retryError);
+        throw retryError;
+      }
+    }
+  };
+
+  let response = await requestWithRetry();
+  let rateLimitRetryExhausted = false;
+  if (retryMode === 'unread-cursor') {
+    response = await retryOn429(response, requestWithRetry, {
+      sleep,
+      log: debugLog,
+    });
+    rateLimitRetryExhausted = response.status === 429;
+  }
 
   if (response.status === 401) {
     // Reached only after pinned-TLS trust is verified (localAuthorityContext
@@ -805,11 +866,14 @@ async function authedFetch(
       if (localSessionCredentialRef !== undefined) markSeatRejected(localSessionCredentialRef);
       throw new CubeDeletedError();
     }
+    const retryGuidance = rateLimitRetryExhausted
+      ? ' Repeat `borg_read-log unread_only=true` until caught up.'
+      : '';
     throw new BorgServerHttpError(
       response.status,
       serverMessage
-        ? `Borg server request failed (HTTP ${response.status}): ${serverMessage}`
-        : `Borg server request failed (HTTP ${response.status})`,
+        ? `Borg server request failed (HTTP ${response.status}): ${serverMessage}${retryGuidance}`
+        : `Borg server request failed (HTTP ${response.status})${retryGuidance}`,
       code,
     );
   }
@@ -954,7 +1018,13 @@ export async function readLog(
   let cursor: LocalServerCursor | null = null;
   if (opts.unreadOnly) cursor = await getLocalServerCursor(localCursorBinding(local));
   if (opts.since !== undefined) cursor = await resolveLocalLogCursor(local, opts.since);
-  const page = await localReadLogPage(local, { cursor, limit: opts.limit });
+  const page = await localReadLogPage(local, {
+    cursor,
+    limit: opts.limit,
+    // Keep the cursor payload stable across a lost response; do not re-read or
+    // advance local state until one response has been decoded successfully.
+    ...(opts.unreadOnly && opts.since === undefined ? { retryMode: 'unread-cursor' as const } : {}),
+  });
   if (opts.unreadOnly && page.cursor) {
     await advanceLocalServerCursor(localCursorBinding(local), page.cursor);
   }