borgmcp 2.14.1 → 2.15.0

package/src/private-root.ts

@@ -1,8 +1,68 @@
+import { lstatSync, realpathSync } from 'node:fs';
 import { chmod, lstat, mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 
-export const borgConfigRoot = (): string => join(homedir(), '.config', 'borgmcp');
+/**
+ * Optional alternate home root for isolated client runs. The value is the
+ * replacement home directory, not the `.config/borgmcp` directory itself, so
+ * every client-owned path (credentials, seats, worktrees, and agent config)
+ * stays under one root.
+ */
+export const BORG_STATE_ROOT_ENV = 'BORG_STATE_ROOT';
+
+function invalidStateRoot(): Error {
+  return new Error(`${BORG_STATE_ROOT_ENV} must be an absolute canonical path`);
+}
+
+/** Return whether a path and every existing ancestor are free of symlinks. */
+export function isCanonicalPath(root: string): boolean {
+  if (!isAbsolute(root) || resolve(root) !== root) return false;
+  let candidate = root;
+  while (true) {
+    try {
+      const metadata = lstatSync(candidate);
+      return !metadata.isSymbolicLink() && realpathSync(candidate) === candidate;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      const parent = dirname(candidate);
+      if (parent === candidate) return false;
+      candidate = parent;
+    }
+  }
+}
+
+function configuredStateRoot(env: NodeJS.ProcessEnv = process.env): string | null {
+  const configured = env[BORG_STATE_ROOT_ENV];
+  if (configured === undefined) return null;
+  if (configured.length === 0 || !isCanonicalPath(configured)) {
+    throw invalidStateRoot();
+  }
+  return configured;
+}
+
+/** Resolve the effective home root used by all Borg-owned local state. */
+export function borgHomeRoot(env: NodeJS.ProcessEnv = process.env): string {
+  return configuredStateRoot(env) ?? realpathSync(homedir());
+}
+
+export const borgConfigRoot = (): string => join(borgHomeRoot(), '.config', 'borgmcp');
+
+/**
+ * Environment used when a native agent CLI registers Borg. The CLI must write
+ * its own config under the same effective root that config-utils reads; the
+ * eventual MCP child receives BORG_STATE_ROOT separately via its registration.
+ */
+export function borgAgentConfigEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  if (env[BORG_STATE_ROOT_ENV] === undefined) return { ...env };
+  const root = borgHomeRoot(env);
+  return {
+    ...env,
+    HOME: root,
+    CODEX_HOME: join(root, '.codex'),
+    XDG_CONFIG_HOME: join(root, '.config'),
+  };
+}
 
 /** Ensure Borg's local state root exists with owner-only directory permissions. */
 export async function ensurePrivateBorgConfigRoot(root = borgConfigRoot()): Promise<void> {

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

package/src/seat-store.ts

@@ -32,9 +32,10 @@
  */
 
 import { constants } from 'node:fs';
-import { open, link, lstat, mkdir, readFile, realpath, rename, stat, unlink } from 'node:fs/promises';
+import { open, link, lstat, mkdir, readFile, rename, stat, unlink } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { isCanonicalPath } from './private-root.js';
 
 const LOCK_WAIT_MS = 10;
 const LOCK_ATTEMPTS = 500;
@@ -58,7 +59,7 @@ async function assertSecureRoot(
   root: string,
   rootMode: SecureStoreOptions['rootMode'] = 'private',
 ): Promise<void> {
-  if (!isAbsolute(root) || resolve(root) !== root) {
+  if (!isCanonicalPath(root)) {
     throw new Error(`Borg credential store path ${root} is not canonical`);
   }
   let metadata: Awaited<ReturnType<typeof lstat>>;
@@ -83,7 +84,7 @@ async function assertSecureRoot(
   if (uid !== null && metadata.uid !== uid) {
     throw new Error(`Borg credential store root ${root} is not owned by the current user`);
   }
-  if (await realpath(root) !== root) {
+  if (!isCanonicalPath(root)) {
     throw new Error(`Borg credential store root ${root} is not canonical or contains a symlink`);
   }
 }

package/src/seats.ts

@@ -17,13 +17,13 @@
  * hydration reader; every other observation is digest-only.
  */
 
-import os from 'os';
 import path from 'path';
 import { createHash } from 'node:crypto';
 import { readStoreFile, withStore } from './seat-store.js';
 import { LegacySessionCredentialCollisionError } from './server-errors.js';
+import { borgConfigRoot } from './private-root.js';
 
-export const SEATS_FILE = path.join(os.homedir(), '.config', 'borgmcp', 'seats.json');
+export const SEATS_FILE = path.join(borgConfigRoot(), 'seats.json');
 const SEATS_VERSION = 1 as const;
 const REF_RE = /^borg-server-session:[a-f0-9]{64}$/;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/src/self-path.ts

@@ -49,3 +49,8 @@ export function resolveClearRewakePath(): string {
 export function resolveLogAuditPath(): string {
   return resolveSelfBinPath('log-audit.js');
 }
+
+/** Absolute path to the optional pre-tool foreign-path reminder hook. */
+export function resolveForeignPathReminderPath(): string {
+  return resolveSelfBinPath('foreign-path-reminder.js');
+}

package/src/server-trust.ts

@@ -4,7 +4,6 @@ import { constants } from 'node:fs';
 import { access, lstat, mkdir, open, rename, rm, unlink, writeFile } from 'node:fs/promises';
 import { request as httpsRequest } from 'node:https';
 import { connect as tlsConnect } from 'node:tls';
-import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { Readable } from 'node:stream';
 import { BorgServerTrustError } from './server-errors.js';
@@ -27,6 +26,7 @@ import type {
   EnrollmentArtifactBinding,
   EnrollmentTrustPointer,
 } from './enrollment-types.js';
+import { borgHomeRoot } from './private-root.js';
 
 // CR5 TLS LATTICE: OpenSSL/Node TLS certificate-verification error codes. A raw
 // CA / cert-chain / SAN failure from the pinned transport is a potential MITM and
@@ -102,12 +102,12 @@ function invalidateOriginTrustCache(origin: string): void {
 }
 
 function serverDataDirectory(): string {
-  return resolve(process.env.BORG_SERVER_DATA_DIR ?? join(homedir(), '.borg', 'server'));
+  return resolve(process.env.BORG_SERVER_DATA_DIR ?? join(borgHomeRoot(), '.borg', 'server'));
 }
 
 function remoteTrustDirectory(origin: string): string {
   const key = createHash('sha256').update(origin).digest('hex');
-  return join(homedir(), '.borg', 'server-trust', key);
+  return join(borgHomeRoot(), '.borg', 'server-trust', key);
 }
 
 function trustGenerationsDirectory(origin: string): string {

package/src/setup-confirm.ts

@@ -4,7 +4,7 @@
  * Step-1 of the setup wizard writes the user's GLOBAL agent config
  * (registers the borg MCP server + hooks). Before gh#818 this happened
  * silently on first run. This module adds informed-consent disclosure:
- * it lists WHICH files will be written (well-known `os.homedir()` paths)
+ * it lists WHICH files will be written (well-known home-relative paths)
  * and asks to continue before the first mutation.
  *
  * Pure / dep-injected (mirrors `resolveCliChoice` + `setup-action.ts`) so

package/src/stream-owner.ts

@@ -1,10 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
-import { homedir } from 'node:os';
 import path from 'node:path';
+import { borgConfigRoot } from './private-root.js';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const STREAM_LOCKS_DIR = path.join(homedir(), '.config', 'borgmcp', 'stream-locks');
+const STREAM_LOCKS_DIR = path.join(borgConfigRoot(), 'stream-locks');
 const OWNER_FILE = 'owner.json';
 const TAKEOVER_FILE = 'takeover.json';
 const SCHEMA_VERSION = 1;