borgmcp 3.0.2 → 3.2.0

package/docs/EXTRACTION_PROVENANCE.md

@@ -1,5 +1,12 @@
 # Extraction Provenance
 
+**This file is a frozen historical record.** It documents the one-time
+extraction of this repository from the monorepo and the state of the client
+line as of that extraction and its immediate releases. Nothing appends to it,
+no release process touches it, and no statement in it describes the current
+version — the authoritative version is `package.json` and the npm registry.
+Facts below were true when recorded and are not maintained.
+
 The initial standalone source was extracted from `Byte-Ventures/borg-mcp` commit `17ff8ce14e12122a8cc9089f6b94174c02fa2a04` on branch `main`.
 
 The extraction copied the monorepo's `client/src/` production boundary and top-level `client/__tests__/*.test.ts` unit tests. It did not import monorepo Git history, worker or website source, deployment configuration, local state, credentials files, build output, or the live integration suite.
@@ -17,42 +24,20 @@ The extraction copied the monorepo's `client/src/` production boundary and top-l
 - Kept self-hosted `--host --enroll` preview-only while implementing the
   client-generated PENDING credential/retry tuple and capability-gated,
   repository-idempotent cube creation required for local dogfood.
-- Initially set the standalone package identity to `2.0.0`. **The current
-  release identity is `3.0.2`.** Extraction and versioning do not authorize
-  publication.
-
-  Spent versions — each burned an immutable tag and published nothing:
-
-  | Version | Failed at | Recovered by |
-  | --- | --- | --- |
-  | `2.0.0` | lightweight release tag, before packaging | `2.0.1` |
-  | `2.0.7` | before package creation or npm publication | — |
-  | `2.10.1` | before artifact creation or publication | — |
-  | `2.12.0` | before artifact creation or publication | `2.12.1` |
-  | `3.0.1` | publish job never scheduled; run cancelled after verify and approval | `3.0.2` |
-
-  Every other version in the `2.x` and `3.x` lines published and was
-  registry-verified.
-  Record spent versions here when they occur; do not append a clause to this
-  entry. To confirm the table is still complete, list the repository's version
-  tags and `npm view borgmcp versions` — a spent version is a tag whose version
-  never reached the registry, and the two sets should differ by exactly these
-  rows.
-
-## Review Holds
+## Review Holds Resolved at Extraction (historical)
 
 Google OAuth / Cloud sign-in has been fully removed from this local-only client.
 `src/auth.ts`, `src/device-auth.ts`, and all installed-application OAuth client
 material are deleted, along with the hosted API default and the Cloud
-subscription/billing/dashboard tools. `scripts/verify-public-source.mjs` now
+subscription/billing/dashboard tools. `scripts/verify-public-source.mjs`
 forbids ANY Google OAuth client ID or `GOCSPX` value anywhere in the source or
 packed artifact (zero tolerance), and a no-cloud egress guard asserts the packed
 artifact reaches no hosted authority.
 
-Local enrollment now uses the reviewed client-generated credential/retry
+At extraction, local enrollment used the reviewed client-generated credential/retry
 contract, with a pre-request `PENDING` record in the local 0600-permission seat
-store, exact-tuple ambiguous retry, and verified activation. The current client
-candidate resolves to the audited registry `borgmcp-shared@0.9.0` with integrity
+store, exact-tuple ambiguous retry, and verified activation. The client candidate
+at that time resolved to audited registry `borgmcp-shared` version `0.9.0` with integrity
 `sha512-bfZPP9JGgBQrCFoZetabqKHc8HLaUqHVR3GJLb/1F1oon7z/B4el4aeBHVvXlxN9+2G7kU/ymPZ/K25nVQapmQ==`.
 The coupled `borgmcp-server@0.9.0` release was published on 2026-08-02 for the
 client `borgmcp@2.10.0` line. Its annotated tag object
@@ -62,6 +47,7 @@ client `borgmcp@2.10.0` line. Its annotated tag object
 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. The immutable `v2.0.7` attempt failed before publication and remains
-preserved. The current release identity and publication gate remain governed by
-the reviewed `v3.0.2` source, a fresh annotated tag, and the exact-artifact and
-protected-publication gates.
+preserved. Each release's identity and publication gate are governed by its reviewed
+source at the annotated release tag and the exact-artifact and
+protected-publication gates; the authoritative version is `package.json` and
+the registry, not this document.

package/docs/LOCAL_SERVER.md

@@ -204,7 +204,11 @@ stopped server remains stopped; matching controller and prepared runtime are
 reported as `prepared; still stopped` without inventing a live protocol check.
 An absent server is skipped rather than installed. Partial completion prints the
 safe retry command `borg update --yes`. Borg never starts a stopped server,
-daemonizes, or restarts agent processes.
+daemonizes, or restarts agent processes. After the package pair verifies, the
+command replaces stale absolute `borgmcp` package launch paths in Claude Code,
+Codex, and OpenCode MCP registrations with the version-stable `borg-mcp`
+command. It preserves each registration's other settings. It does not create
+absent registrations or modify a `borg` entry that points to another command.
 
 `borg server update` remains the server-runtime-only command. It verifies and
 activates the server artifact but deliberately does not rewrite the global
@@ -258,6 +262,6 @@ The default discovery endpoint is `https://127.0.0.1:7091`. Explicit `--host` va
 
 ## Release status
 
-This client candidate pins published `borgmcp-shared@0.9.0`. Its release remains
+This client candidate pins published `borgmcp-shared@0.10.1`. Its release remains
 coupled to a server artifact rebuilt against the same shared version, with both
 artifacts required to pass the complete process-level local dogfood gate.

package/docs/RELEASING.md

@@ -19,11 +19,11 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.9.0` remains locked to
+- the exact audited registry dependency `borgmcp-shared@0.10.1` remains locked to
   its canonical tarball and integrity
-  `sha512-bfZPP9JGgBQrCFoZetabqKHc8HLaUqHVR3GJLb/1F1oon7z/B4el4aeBHVvXlxN9+2G7kU/ymPZ/K25nVQapmQ==`;
+  `sha512-IAESc6+VpUGECNabFkO60agvga0B8Fx0hk2RMUkSDCnlIjMvDodMFKlqw+TOzdXtjf0Uk9LJi9ZCU4HfRYRRhw==`;
 - the coupled client/server release is published only after the server artifact
-  is rebuilt against `borgmcp-shared@0.9.0` and both pass the complete local
+  is rebuilt against `borgmcp-shared@0.10.1` and both pass the complete local
   dogfood gate;
 - the selected stable client version is unused and the exact release commit is
   on protected `main`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -71,7 +71,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.9.0",
+    "borgmcp-shared": "0.10.1",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/cli-help.ts

@@ -129,7 +129,11 @@ export function updateHelpText(version: string): string {
     `provenance fail closed with manual-update guidance.\n\n` +
     `If no local server is installed, the server phase is skipped. A failure after the client\n` +
     `succeeds is reported as partial completion with the safe retry command. Borg never starts a\n` +
-    `stopped server and never restarts agent processes; restart active agent sessions yourself.\n`
+    `stopped server. After package verification, Borg replaces stale borgmcp package launch paths\n` +
+    `in Claude Code, Codex, and OpenCode registrations while preserving their other settings. It\n` +
+    `leaves absent registrations and borg entries that point to another command unchanged. Borg\n` +
+    `never restarts agent processes;\n` +
+    `restart active agent sessions yourself.\n`
   );
 }
 

package/src/config-utils.ts

@@ -15,7 +15,6 @@ import {
   withAgentRuntimeEnv,
 } from './agent-runtime.js';
 import {
-  resolveMcpBinaryPath,
   resolveRegenPath,
   resolveClearRewakePath,
   resolveLogAuditPath,
@@ -36,7 +35,7 @@ const HOOK_COMMAND = shellEscape(resolveRegenPath());
 const CLEAR_REWAKE_HOOK_COMMAND = shellEscape(resolveClearRewakePath());
 const AUDIT_HOOK_COMMAND = shellEscape(resolveLogAuditPath());
 const FOREIGN_PATH_REMINDER_HOOK_COMMAND = shellEscape(resolveForeignPathReminderPath());
-const MCP_BINARY = resolveMcpBinaryPath();
+const MCP_COMMAND = 'borg-mcp';
 
 /**
  * Claude Code CLI config path. The CLI reads `mcpServers.<name>` from
@@ -678,6 +677,150 @@ export function isCodexMcpServerConfigured(
   }
 }
 
+function configuredMcpCommand(value: unknown): string | null {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value) && value.length === 1 && typeof value[0] === 'string') {
+    return value[0];
+  }
+  return null;
+}
+
+function isStaleBorgMcpCommand(value: unknown): boolean {
+  const command = configuredMcpCommand(value);
+  if (!command || command === MCP_COMMAND || !path.isAbsolute(command)) return false;
+  const normalized = command.replace(/\\/g, '/');
+  return /\/(?:node_modules\/borgmcp|borg-mcp-client)\/dist\/index\.js$/.test(normalized);
+}
+
+function readClaudeMcpCommand(configPath: string): unknown {
+  try {
+    return readJsonFile(configPath)?.mcpServers?.[MCP_SERVER_NAME]?.command;
+  } catch {
+    return undefined;
+  }
+}
+
+function readCodexMcpCommand(configPath: string): unknown {
+  try {
+    const text = fs.readFileSync(configPath, 'utf-8');
+    if (!isCodexMcpServerConfigured(configPath)) return undefined;
+    const header = /^\s*\[mcp_servers\.borg\]\s*$/m.exec(text);
+    if (!header) return undefined;
+    const tail = text.slice(header.index + header[0].length);
+    const nextHeader = /^\s*\[/m.exec(tail);
+    const section = nextHeader ? tail.slice(0, nextHeader.index) : tail;
+    return section?.match(/^\s*command\s*=\s*"([^"]+)"\s*$/m)?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+function readOpenCodeMcpCommand(configPath: string): unknown {
+  try {
+    const borgServer = readJsonFile(configPath)?.mcp?.[MCP_SERVER_NAME];
+    if (!borgServer || borgServer.type !== 'local') return undefined;
+    const environment = borgServer.environment ?? borgServer.env;
+    if (environment?.BORG_AGENT_KIND !== 'opencode' && environment?.BORG_OPENCODE !== '1') {
+      return undefined;
+    }
+    return borgServer.command;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface RefreshManagedAgentMcpConfigOptions {
+  claudeConfigPath?: string;
+  codexConfigPath?: string;
+  openCodeConfigPath?: string;
+  refreshClaude?: () => void;
+  refreshCodex?: () => void;
+  refreshOpenCode?: () => void;
+}
+
+function refreshClaudeMcpCommand(configPath: string): void {
+  const config = readJsonFile(configPath);
+  config.mcpServers[MCP_SERVER_NAME].command = MCP_COMMAND;
+  writeJsonFile(configPath, config);
+}
+
+function refreshCodexMcpCommand(configPath: string): void {
+  const text = fs.readFileSync(configPath, 'utf-8');
+  const header = /^\s*\[mcp_servers\.borg\]\s*$/m.exec(text);
+  if (!header) return;
+  const sectionStart = header.index + header[0].length;
+  const tail = text.slice(sectionStart);
+  const nextHeader = /^\s*\[/m.exec(tail);
+  const sectionEnd = nextHeader ? sectionStart + nextHeader.index : text.length;
+  const section = text.slice(sectionStart, sectionEnd);
+  const updatedSection = section.replace(
+    /^(\s*command\s*=\s*)"[^"]+"(\s*)$/m,
+    `$1"${MCP_COMMAND}"$2`,
+  );
+  fs.writeFileSync(
+    configPath,
+    text.slice(0, sectionStart) + updatedSection + text.slice(sectionEnd),
+    'utf-8',
+  );
+}
+
+function refreshOpenCodeMcpCommand(configPath: string): void {
+  const config = readJsonFile(configPath);
+  const borgServer = config.mcp[MCP_SERVER_NAME];
+  borgServer.command = Array.isArray(borgServer.command) ? [MCP_COMMAND] : MCP_COMMAND;
+  writeJsonFile(configPath, config);
+}
+
+/**
+ * Replace only the command in stale Borg registrations. Other entry fields are
+ * preserved, and a `borg` entry that points at another command is not changed.
+ */
+export function refreshManagedAgentMcpConfigs(
+  options: RefreshManagedAgentMcpConfigOptions = {},
+): Array<'claude' | 'codex' | 'opencode'> {
+  const refreshed: Array<'claude' | 'codex' | 'opencode'> = [];
+  const failures: string[] = [];
+  const claudeConfigPath = options.claudeConfigPath ?? CLAUDE_CONFIG_PATH;
+  const codexConfigPath = options.codexConfigPath ?? CODEX_CONFIG_PATH;
+  const openCodeConfigPath = options.openCodeConfigPath ?? OPENCODE_CONFIG_PATH;
+  const agents = [
+    {
+      kind: 'claude' as const,
+      label: 'Claude Code',
+      command: readClaudeMcpCommand(claudeConfigPath),
+      refresh: options.refreshClaude ?? (() => refreshClaudeMcpCommand(claudeConfigPath)),
+    },
+    {
+      kind: 'codex' as const,
+      label: 'Codex',
+      command: readCodexMcpCommand(codexConfigPath),
+      refresh: options.refreshCodex ?? (() => refreshCodexMcpCommand(codexConfigPath)),
+    },
+    {
+      kind: 'opencode' as const,
+      label: 'OpenCode',
+      command: readOpenCodeMcpCommand(openCodeConfigPath),
+      refresh: options.refreshOpenCode ?? (() => refreshOpenCodeMcpCommand(openCodeConfigPath)),
+    },
+  ];
+
+  for (const agent of agents) {
+    if (!isStaleBorgMcpCommand(agent.command)) continue;
+    try {
+      agent.refresh();
+      refreshed.push(agent.kind);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`${agent.label}: ${message}`);
+    }
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`Could not refresh agent MCP configs: ${failures.join('; ')}`);
+  }
+  return refreshed;
+}
+
 /**
  * Get absolute path to borg index.js
  * Returns the actual index.js file, not the npm symlink
@@ -703,9 +846,7 @@ export function addMcpServer(): void {
       // Ignore - server might not exist yet
     }
 
-    // gh#client#18: use absolute path to THIS installation's binary so the
-    // registered server always matches the running client version.
-    const command = `claude mcp add --scope user borg ${shellQuote(MCP_BINARY)}`;
+    const command = `claude mcp add --scope user borg ${shellQuote(MCP_COMMAND)}`;
 
     execSync(command, {
       stdio: 'inherit', // Show output to user
@@ -736,7 +877,6 @@ export function addCodexMcpServer(): void {
     // Identity is durable configuration; remote wake is a per-launch
     // transport capability. Do not persist a transport marker here: a future
     // Codex child may launch without a live --remote socket.
-    // gh#client#18: use absolute path to THIS installation's binary.
     const apiUrlEnvArg = apiUrl ? ` --env BORG_API_URL=${shellQuote(apiUrl)}` : '';
     const stateRoot = process.env[BORG_STATE_ROOT_ENV];
     const stateRootEnvArg = stateRoot
@@ -746,7 +886,7 @@ export function addCodexMcpServer(): void {
       apiUrlEnvArg +
       stateRootEnvArg +
       ` --env ${BORG_AGENT_KIND_ENV}=codex` +
-      ` -- ${shellQuote(MCP_BINARY)}`, {
+      ` -- ${shellQuote(MCP_COMMAND)}`, {
       stdio: 'inherit',
       env: codexConfigEnv,
     });
@@ -965,9 +1105,8 @@ export function addOpenCodeMcpServer(): void {
     const stateRootEnvArg = stateRoot
       ? ` --env ${BORG_STATE_ROOT_ENV}=${shellQuote(stateRoot)}`
       : '';
-    // gh#client#18: use absolute path to THIS installation's binary.
     execSync(
-      `opencode mcp add borg --env BORG_SESSION=1 --env BORG_AGENT_KIND=opencode --env BORG_OPENCODE=1${apiUrlEnvArg}${stateRootEnvArg} -- ${shellQuote(MCP_BINARY)}`,
+      `opencode mcp add borg --env BORG_SESSION=1 --env BORG_AGENT_KIND=opencode --env BORG_OPENCODE=1${apiUrlEnvArg}${stateRootEnvArg} -- ${shellQuote(MCP_COMMAND)}`,
       { stdio: 'inherit', env: borgAgentConfigEnv(process.env) }
     );
   } catch (error: any) {

package/src/launch-all-cmd.ts

@@ -66,7 +66,7 @@ async function resolveTargetCube(
       return {
         error:
           `'${args.cubeName}' is ambiguous — ${matches.length} saved connections on this machine share that name:\n${list}\n` +
-          'cd into the intended project and re-run without --cube-name (resolves the active cube), ' +
+          'cd into the intended project and re-run as `borg launch-all` without the positional cube name (resolves the active cube), ' +
           'or clear the stale connection(s) by running `borg reset-local-connection` from the worktree that holds each.',
       };
     }

package/src/remote-client.ts

@@ -17,17 +17,23 @@ import { randomUUID } from 'node:crypto';
 import {
   createProtocolEnvelope,
   decodeDeleteCubeResponse,
+  decodeDeleteRoleRequest,
+  decodeDeleteRoleResult,
   decodeDroneRuntimeMetadataState,
   decodeEvictDroneResult,
   decodeProtocolEnvelope,
   decodeProtocolErrorEnvelope,
   decodeReassignDroneResult,
+  decodeRoleRationaleRequest,
+  decodeRoleRationaleResult,
   decodeUpdateDroneRuntimeMetadataResponse,
   ErrorCode,
   ProtocolContractError,
   type AgentKind,
+  type DeleteRoleResult,
   type EvictDroneResult,
   type ReassignDroneResult,
+  type RoleRationaleResult,
 } from 'borgmcp-shared/protocol';
 import { consolePrefix } from './console-prefix.js';
 import { debugLog } from './debug.js';
@@ -301,7 +307,10 @@ async function localServerRequest<T>(
   path: string,
   method: 'GET' | 'POST' | 'PUT' | 'PATCH',
   payload?: Record<string, unknown>,
-  options: { retryMode?: AuthedFetchRetryMode } = {},
+  options: {
+    retryMode?: AuthedFetchRetryMode;
+    decodePayload?: (value: unknown) => T;
+  } = {},
 ): Promise<T | null> {
   return decodeLocalProtocolResponse<T>((signal) => authedFetch(path, {
       method,
@@ -318,7 +327,7 @@ async function localServerRequest<T>(
           body: JSON.stringify(createProtocolEnvelope(randomUUID(), payload)),
         }),
       retryMode: options.retryMode,
-    }), true);
+    }), true, options.decodePayload);
 }
 
 export interface LocalManageOperation {
@@ -1253,12 +1262,21 @@ export async function roleRationale(
   section: string,
   serverTrustIdentity?: string,
 ): Promise<{ role: string; section: string; body: string }> {
-  void sessionToken;
-  void apiUrl;
-  void role;
-  void section;
-  void serverTrustIdentity;
-  localUnsupported('role rationale sections');
+  const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
+  const request = decodeRoleRationaleRequest({ role, section });
+  const result = await localServerRequest<RoleRationaleResult>(
+    local,
+    `/api/cubes/${local.cubeId}/role-rationale`,
+    'POST',
+    { ...request },
+    { decodePayload: decodeRoleRationaleResult },
+  );
+  if (!result) throw new Error('Local Borg server returned an empty role rationale response');
+  return {
+    role: result.role_name,
+    section: result.section.heading,
+    body: result.section.body,
+  };
 }
 
 /**
@@ -1662,8 +1680,26 @@ export async function patchRoleSection(
  * (reassign or evict those drones first).
  */
 export async function deleteRole(roleId: string): Promise<void> {
-  void roleId;
-  localUnsupported('role deletion');
+  assertUuidShape(roleId, 'role_id');
+  const active = await getActiveCube();
+  if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');
+  assertUuidShape(active.cubeId, 'cube_id');
+  const result = await localManageRequest<DeleteRoleResult>(
+    active,
+    `/api/cubes/${active.cubeId}/roles/${roleId}`,
+    'DELETE',
+    {
+      operation: `delete role ${manageCopyValue(roleId)} from cube ${manageCopyValue(active.name)}`,
+      cubeName: active.name,
+      noMutation: 'No role was deleted.',
+    },
+    decodeDeleteRoleRequest({}),
+    decodeDeleteRoleResult,
+  );
+  if (!result) throw new Error('Local Borg server returned an empty role deletion response');
+  if (result.role_id !== roleId) {
+    throw new Error('Local Borg server returned a deletion response for an unexpected role');
+  }
 }
 
 /**

package/src/server-handshake.ts

@@ -214,7 +214,7 @@ export interface ServerAttachResult {
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v7.
+ * Attach an enrolled client principal to one granted cube/role over protocol v8.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * OS keychain (keyed by the stable per-seat identity) BEFORE this request, so an
  * interrupted/lost response is recovered by re-sending the exact same bearer —

package/src/tool-manifest.ts

@@ -154,8 +154,8 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_role-rationale',
           description:
-            "Fetch an on-demand rationale/case-study section for a role playbook. " +
-            "Pass a role name/id and a plain-label section key to read the rationale without expanding every context refresh.",
+            "Fetch exactly one named section from a role's detailed playbook using the current drone session. " +
+            "Pass a role name/UUID and a plain-label section key. Role names and section keys match case-insensitively; UUIDs match exactly. Malformed selectors, ambiguous role names, and unknown roles/sections refuse. Returns the server's canonical role name, role_id, section heading, and the section body in full, refusing rather than truncating when it exceeds the server's role-text size limit, so a drone can read one section on demand instead of carrying the whole playbook in every borg_regen.",
           inputSchema: {
             type: 'object',
             properties: {
@@ -481,7 +481,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         },
         {
           name: 'borg_delete-role',
-          description: 'Delete a role. Refuses if any drone is still assigned — reassign them with borg_reassign-drone or remove them with borg_evict-drone first.',
+          description: 'Delete a role using the selected local client\'s cube-management grant. Unknown or inaccessible roles refuse. Also refuses for the default, mandatory, or human-seat role; a role referenced by message-taxonomy routing; or a role assigned to an active drone. Reassign active drones with borg_reassign-drone or remove them with borg_evict-drone first. Evicted drones that held the deleted role are reassigned to the cube\'s default role; their activity-log attribution is unaffected.',
           inputSchema: {
             type: 'object',
             properties: {

package/src/update-cmd.ts

@@ -8,6 +8,7 @@ import { updateHelpText } from './cli-help.js';
 import { preflightBorgServerTag } from './server-handshake.js';
 import { loadBorgServerTrust } from './server-trust.js';
 import { shellEscape } from './shell-escape.js';
+import { refreshManagedAgentMcpConfigs } from './config-utils.js';
 
 const CLIENT_PACKAGE = 'borgmcp';
 const SERVER_PACKAGE = 'borgmcp-server';
@@ -64,6 +65,7 @@ export interface UpdateDeps {
   reenter(binPath: string, args: readonly string[]): Promise<number>;
   serverJson(binPath: string, command: 'update' | 'status'): Promise<unknown>;
   verifyRunningProtocol(origin: string): Promise<void>;
+  refreshAgentMcpConfigs(): Promise<Array<'claude' | 'codex' | 'opencode'>>;
   confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
   isTTY(): boolean;
   stdout(text: string): void;
@@ -113,7 +115,8 @@ type ServerUpdateFailureStage =
   | 'final server state verification'
   | 'final package verification'
   | 'managed service continuity check'
-  | 'running server protocol verification';
+  | 'running server protocol verification'
+  | 'agent MCP config refresh';
 
 interface NpmContext {
   commandPath: string;
@@ -695,6 +698,15 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   }
 
   if (!serverWasPresent) {
+    try {
+      await deps.refreshAgentMcpConfigs();
+    } catch (error) {
+      deps.stderr(
+        `Client updated, but agent MCP config refresh failed: ${errorMessage(error, 'unknown failure')}.\n` +
+        `Run borg setup to repair Borg-written agent registrations. Configurations that use another command are not changed.\n`,
+      );
+      return 1;
+    }
     deps.stdout(
       `Updated ${CLIENT_PACKAGE}@${pair.client.version}. Local server: skipped (not installed).\n` +
       `Restart active agent sessions to load the updated client.\n`,
@@ -809,6 +821,9 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       retryCommand = 'borg server status';
       await deps.verifyRunningProtocol(status.endpoint!);
     }
+    failureStage = 'agent MCP config refresh';
+    retryCommand = 'borg update --yes';
+    await deps.refreshAgentMcpConfigs();
     deps.stdout(
       state === 'stopped'
         ? (
@@ -1210,6 +1225,7 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
       const trust = await loadBorgServerTrust(origin);
       await preflightBorgServerTag(origin, trust.fetchImpl);
     },
+    refreshAgentMcpConfigs: async () => refreshManagedAgentMcpConfigs(),
     confirm: defaultConfirm,
     isTTY: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
     stdout: (text) => process.stdout.write(text),