borgmcp 5.1.1 → 5.2.0

package/src/assimilate-cmd.ts

@@ -331,6 +331,7 @@ export interface AssimilateDeps {
     trustIdentity: string;
     serverCapabilities?: readonly string[];
   }>;
+  listServerCredentialOrigins?: (origin: string) => Promise<string[]>;
   resumeServerEnrollment: (
     apiUrl: string,
     onPending?: () => void,
@@ -533,13 +534,26 @@ function localAssimilateCliCommand(apiUrl: string, cli: BorgCli): string {
   return `\`borg assimilate --host ${apiUrl} --cli ${cli}\``;
 }
 
-function reportServerFailure(
-  deps: Pick<AssimilateDeps, 'stderr'>,
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+
+function isSiblingEndpoint(reachedOrigin: string, enrolledOrigin: string): boolean {
+  const reached = new URL(reachedOrigin);
+  const enrolled = new URL(enrolledOrigin);
+  return reached.hostname === enrolled.hostname
+    || (reached.port === enrolled.port
+      && isLoopbackHostname(reached.hostname)
+      && isLoopbackHostname(enrolled.hostname));
+}
+
+async function reportServerFailure(
+  deps: Pick<AssimilateDeps, 'stderr' | 'listServerCredentialOrigins'>,
   apiUrl: string,
   error: unknown,
   enroll = false,
   mode: 'assimilate' | 'cube-init' = 'assimilate',
-): number {
+): Promise<number> {
   const message = error instanceof Error ? error.message : String(error);
   const retryCommand = localAssimilateCommand(apiUrl, enroll, mode);
   if (error instanceof BorgServerError && error.code === 'CREATE_CUBE_DENIED') {
@@ -551,6 +565,42 @@ function reportServerFailure(
     return 1;
   }
   if (error instanceof BorgServerError && error.code === 'NOT_ENROLLED') {
+    let enrolledOrigins: string[] = [];
+    try {
+      enrolledOrigins = (await deps.listServerCredentialOrigins?.(apiUrl) ?? []).filter((origin) => {
+        try {
+          const parsed = new URL(origin);
+          return parsed.protocol === 'https:' && parsed.origin === origin && origin !== apiUrl;
+        } catch {
+          return false;
+        }
+      });
+    } catch {
+      // Preserve the existing recovery when the optional diagnostic lookup is unavailable.
+    }
+    const siblingOrigins = enrolledOrigins.filter((origin) => isSiblingEndpoint(apiUrl, origin));
+    if (siblingOrigins.length > 0) {
+      const enrollmentLabel = siblingOrigins.length === 1 ? 'a saved enrollment' : 'saved enrollments';
+      const commandLabel = siblingOrigins.length === 1 ? 'the enrolled endpoint' : 'one of the enrolled endpoints';
+      const commands = siblingOrigins
+        .map((origin) => localAssimilateCommand(origin, false, mode))
+        .join(' or ');
+      deps.stderr(
+        `Borg found ${enrollmentLabel} for ${siblingOrigins.join(', ')}, but this command is reaching ${apiUrl}. ` +
+          `Use ${commandLabel} instead: ${commands}.\n`,
+      );
+      return 1;
+    }
+    if (enrolledOrigins.length > 0) {
+      deps.stderr(
+        `This client is enrolled against ${enrolledOrigins.join(', ')}, not ${apiUrl}. ` +
+          `Confirm that the host, port, and IPv4 or IPv6 loopback ` +
+          `form in ${apiUrl} match the endpoint used during enrollment. If this client has never ` +
+          `enrolled with that server, run ${localAssimilateCommand(apiUrl, true, mode)} from the ` +
+          `operator’s terminal.\n`,
+      );
+      return 1;
+    }
     deps.stderr(
       `Borg could not find a saved enrollment for ${apiUrl}. ` +
         `This can mean that this client has not enrolled with the server, or that its enrollment ` +
@@ -1267,7 +1317,7 @@ export async function prepareAssimilationSeat(
         return { kind: 'stop', code: diagnoseSessionTermination(deps, apiUrl, 'superseded') };
       }
     }
-    return { kind: 'stop', code: reportServerFailure(deps, apiUrl, error) };
+    return { kind: 'stop', code: await reportServerFailure(deps, apiUrl, error) };
   }
 
   if (result.prepareAborted) {
@@ -1281,7 +1331,7 @@ export async function prepareAssimilationSeat(
   if (result.local_session === undefined) {
     return {
       kind: 'stop',
-      code: reportServerFailure(deps, apiUrl, new Error('Borg server did not return compatible secure session metadata')),
+      code: await reportServerFailure(deps, apiUrl, new Error('Borg server did not return compatible secure session metadata')),
     };
   }
   const assignedRole = cubeDetail.roles.find((role) => role.id === result.role_id) ?? resolvedRole;
@@ -1592,7 +1642,7 @@ export async function resolveAssimilationAuthority(
     hasPersistedIdentity = existing !== null || await deps.hasPersistedActiveCube();
   } catch (error) {
     if (error instanceof LegacySessionCredentialCollisionError) {
-      return { kind: 'stop', code: reportServerFailure(deps, error.origin, error, false, mode) };
+      return { kind: 'stop', code: await reportServerFailure(deps, error.origin, error, false, mode) };
     }
     localSeatReadError = error;
   }
@@ -1601,7 +1651,7 @@ export async function resolveAssimilationAuthority(
   if (!selectedAuthority) return { kind: 'stop', code: 1 };
   let authority = selectedAuthority;
   if (localSeatReadError !== undefined) {
-    return { kind: 'stop', code: reportServerFailure(deps, authority.apiUrl, localSeatReadError, false, mode) };
+    return { kind: 'stop', code: await reportServerFailure(deps, authority.apiUrl, localSeatReadError, false, mode) };
   }
 
   const projectRoot = repositoryContext.root;
@@ -1704,7 +1754,7 @@ export async function resolveAssimilationAuthority(
   } catch (error) {
     return {
       kind: 'stop',
-      code: reportServerFailure(deps, authority.apiUrl, error, args.flags.enroll === true, mode),
+      code: await reportServerFailure(deps, authority.apiUrl, error, args.flags.enroll === true, mode),
     };
   }
 
@@ -1861,7 +1911,7 @@ export async function runAssimilate(
       return 1;
     }
     if (error instanceof BorgServerError) {
-      return reportServerFailure(deps, auth.apiUrl, error, false, mode);
+      return await reportServerFailure(deps, auth.apiUrl, error, false, mode);
     }
     deps.stderr(
       'Repository cube initialization failed.\n' +

package/src/assimilate-deps.ts

@@ -67,7 +67,7 @@ import {
   addProjectSessionStartHook,
   provisionLaunchAccess,
 } from './config-utils.js';
-import { findPendingServerEnrollment } from './config.js';
+import { findPendingServerEnrollment, listServerCredentialOrigins } from './config.js';
 import { setTerminalTitle as setTitle } from './terminal-title.js';
 import { defaultCliChoiceDeps, resolveCliChoice } from './cli-platform.js';
 import { prepareCodexRemoteLaunch, defaultCodexRemoteDeps } from './codex-remote.js';
@@ -268,6 +268,7 @@ export function buildDefaultAssimilateDeps(
       }
       return connectLocalBorgServer(apiUrl);
     },
+    listServerCredentialOrigins,
     resumeServerEnrollment: async (apiUrl, onPending) =>
       resumeLocalBorgServerEnrollment(apiUrl, {
         ...(onPending === undefined ? {} : { onPending }),

package/src/config.ts

@@ -566,6 +566,31 @@ export async function hasServerCredentialForOrigin(origin: string): Promise<bool
   }), { processShared: processSharedEnrollmentLock() });
 }
 
+export async function listServerCredentialOrigins(origin: string): Promise<string[]> {
+  const backend = await getServerCredentialBackend();
+  if (!backend.entries) return [];
+  return withEnrollmentOriginLock(origin, () => withCredentialStoreLock(async () => {
+    const accounts = await backend.entries!();
+    const origins = new Set<string>();
+    for (const [account, value] of Object.entries(accounts)) {
+      try {
+        const candidate = JSON.parse(value) as { origin?: unknown; trustIdentity?: unknown };
+        if (typeof candidate.origin !== 'string' || typeof candidate.trustIdentity !== 'string') continue;
+        const record = decodeActiveServerCredentialRecord(
+          value,
+          candidate.origin,
+          candidate.trustIdentity,
+        );
+        if (account !== serverCredentialAccount(record.origin, record.trustIdentity)) continue;
+        origins.add(record.origin);
+      } catch {
+        // Ignore unrelated or malformed backend entries.
+      }
+    }
+    return [...origins].sort();
+  }), { processShared: processSharedEnrollmentLock() });
+}
+
 function decodePendingServerEnrollment(
   stored: string,
   origin: string,

package/src/index.ts

@@ -606,7 +606,9 @@ export async function main() {
               drone: displayedResult.drone,
               role: displayedResult.role,
               behind_by: typeof displayedResult.behind_by === 'number' ? displayedResult.behind_by : null,
-              decision_topics: (displayedResult.decisions ?? []).map((d: any) => d.topic),
+              ...(Array.isArray(displayedResult.decisions)
+                ? { decision_topics: displayedResult.decisions.map((d) => d.topic) }
+                : {}),
               running_version: getPackageVersion(),
               on_disk_version: onDiskVersion,
               wake_path_healthy: inboxMonitorHealthy,

package/src/regen-format.ts

@@ -22,6 +22,7 @@ import { shellEscape } from './shell-escape.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 import { isBorgSession } from './launch-gate.js';
 import type { AgentKind } from './agent-runtime.js';
+import type { Decision } from 'borgmcp-shared/protocol';
 
 export type HandoverMode = 'origin' | 'local';
 
@@ -385,6 +386,14 @@ Any time you make a factual claim that could be verified — "this shipped as ve
 - Cube log state → \`borg_read-log unread_only=true\` for wake triage, draining until \`behind_by=0\`; don't cite from memory or from another drone's summary
 - Ratified cube decision → \`borg_decisions {topic}\` — cite the registry's active decision by topic; NEVER restate a ratified decision from memory (a memory restatement drifts on the axis). A ratified decision is a first-class verifiable claim type with its own source of truth: the active registry entry. Recording one is \`borg_decide\`: Coordinator/Queen are workflow-eligible to ratify, but role labels grant no server permission; the selected local client needs a live cube-manage grant.
 
+**Durable layers:**
+1. Decision registry (\`borg_decide\` / \`borg_decisions\`): choices between alternatives that could be revisited, cited by topic, served into every drone's context, capped at 16,384 active bytes per cube.
+2. Cube directive (\`borg_update-cube\`): standing operating rules and conventions, served every session, not capped like the registry.
+3. Cube documents (\`borg_put-document\` / \`borg_get-document\`): large or detailed material — contracts, designs, evidence — cited by id, never inlined.
+4. Repository \`AGENTS.md\`: rules specific to one repository, read only by seats working there.
+
+Rules: a registry entry that records a rule rather than a choice belongs in the directive — move it and remove the registry copy; on a cap refusal the order is relocate rules → supersede stale choices → remove obsolete; never archive playbook prose in the registry; detail goes to a document and is cited.
+
 **The discipline is universal to reviewer-class actions** (Code Reviewer formal gates + Security Auditor SR gates + PM-courtesy verifications + UX-courtesy reviews + any drone making a verification-worthy factual claim in their cube-log post). It lives in this universal playbook rather than any one role's text because it applies to ALL reviewers.
 
 **Four-surface propagation:**
@@ -554,7 +563,8 @@ export function formatRegenMarkdown(
     // gh#740: active ratified decisions for the cube. Rendered in the
     // always-shown band (lite + full) so the source of truth is in context at
     // mid-session restatement moments. Absent on a pre-gh#740 worker → omitted.
-    decisions?: any[];
+    decisions?: Decision[];
+    decisions_error?: string;
   },
   opts: { mode?: RegenMode; handoverMode?: HandoverMode } = {}
 ): string {
@@ -612,16 +622,28 @@ export function formatRegenMarkdown(
   const taxonomyTip = nullTaxonomyTip(result.cube.message_taxonomy);
 
   // gh#740: render active ratified decisions concisely (one line each), capped
-  // with an elision footer. Section omitted when there are none (or the field
-  // is absent on a pre-gh#740 worker — mixed-client safe). Lives in the
+  // with an elision footer. Empty and failed reads are explicit and distinct;
+  // an absent field from a pre-gh#740 worker is omitted. Lives in the
   // always-shown band below so it surfaces on LITE wakes (the mid-session
   // restatement moment), not just the session-start full regen (PM F1).
   const RATIFIED_DECISIONS_CAP = 12;
-  const activeDecisions = Array.isArray(result.decisions) ? result.decisions : [];
   const decisionsSection = (() => {
-    if (activeDecisions.length === 0) return '';
+    if (result.decisions_error !== undefined) {
+      const errorClass = /^[A-Za-z][A-Za-z0-9]*Error$/.test(result.decisions_error)
+        ? result.decisions_error
+        : 'UnknownError';
+      return [
+        '## Ratified decisions',
+        `The decision registry could not be read (${errorClass}). Active decisions are unavailable.`,
+      ].join('\n');
+    }
+    if (!Array.isArray(result.decisions)) return '';
+    const activeDecisions = result.decisions;
+    if (activeDecisions.length === 0) {
+      return ['## Ratified decisions', 'No active decisions are recorded.'].join('\n');
+    }
     const shown = activeDecisions.slice(0, RATIFIED_DECISIONS_CAP);
-    const lines = shown.map((d: any) => `- **${d.topic}:** ${d.decision}`);
+    const lines = shown.map((d) => `- **${d.topic}:** ${d.decision}`);
     const remaining = activeDecisions.length - shown.length;
     if (remaining > 0) lines.push(`- _+${remaining} more — \`borg_decisions\`_`);
     return ['## Ratified decisions', 'Cite these by topic — do NOT restate a ratified decision from memory.', ...lines].join('\n');

package/src/remote-client.ts

@@ -57,6 +57,7 @@ import {
   type ListDocumentsResult,
   type RemoveDocumentResult,
   type CreateCubeRepository,
+  type Decision,
 } from 'borgmcp-shared/protocol';
 import { Buffer } from 'node:buffer';
 import { canonicalizeWorkingRepoIdentity } from './working-repo.js';
@@ -1261,9 +1262,9 @@ export async function listDecisions(
   apiUrl: string,
   topic?: string,
   serverTrustIdentity?: string,
-): Promise<{ decisions: any[] }> {
+): Promise<{ decisions: Decision[] }> {
   const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
-  const payload = await localServerRequest<{ decisions: any[] }>(
+  const payload = await localServerRequest<{ decisions: Decision[] }>(
     local,
     `/api/cubes/${local.cubeId}/decisions`,
     'PUT',
@@ -1352,7 +1353,8 @@ export async function regen(
   behind_by?: number;
   // gh#740: active ratified decisions for the cube, rendered by regen-format.
   // Local regen composes these via listDecisions.
-  decisions?: any[];
+  decisions?: Decision[];
+  decisions_error?: string;
 }> {
   const local = await localAuthorityContext(
     sessionToken,
@@ -1382,7 +1384,8 @@ export async function regen(
     ? await getLocalServerCursor(localCursorBinding(local))
     : await resolveLocalLogCursor(local, opts.since);
   const page = await localReadLogPage(local, { cursor, limit: 1 });
-  let decisions: any[] = [];
+  let decisions: Decision[] | undefined;
+  let decisionsError: string | undefined;
   try {
     decisions = (await listDecisions(
       sessionToken,
@@ -1391,8 +1394,12 @@ export async function regen(
       opts.serverTrustIdentity,
     )).decisions;
   } catch (error) {
+    const constructorName = error instanceof Error ? error.constructor.name : '';
+    decisionsError = /^[A-Za-z][A-Za-z0-9]*Error$/.test(constructorName)
+      ? constructorName
+      : 'UnknownError';
     console.warn(
-      `Local regen: failed to fetch ratified decisions (${error instanceof Error ? error.message : String(error)}); continuing without them.`,
+      `Local regen: failed to fetch ratified decisions (${decisionsError}); continuing without them.`,
     );
   }
   return {
@@ -1403,7 +1410,8 @@ export async function regen(
     drones: composed.drones,
     recentLog: [],
     behind_by: page.entries.length + page.behind_by,
-    decisions,
+    ...(decisions === undefined ? {} : { decisions }),
+    ...(decisionsError === undefined ? {} : { decisions_error: decisionsError }),
   };
 }