borgmcp 3.1.0 → 3.3.0

package/src/config-utils.ts

@@ -15,7 +15,6 @@ import {
   withAgentRuntimeEnv,
 } from './agent-runtime.js';
 import {
-  resolveMcpBinaryPath,
   resolveRegenPath,
   resolveClearRewakePath,
   resolveLogAuditPath,
@@ -29,14 +28,14 @@ import type { LaunchAccessPaths } from './launch-access.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// gh#client#18: canonical hook commands stored in JSON are shell-escaped
-// absolute paths. Bare names and stale/other-install absolute paths are
-// migrated to this form on every hook write.
-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();
+// client#394: hook commands are stable npm bin names. They intentionally stay
+// unquoted: each is a fixed single shell token with no metacharacters. Legacy
+// quoted bare names and install-specific absolute paths migrate to this form.
+const HOOK_COMMAND = 'borg-regen';
+const CLEAR_REWAKE_HOOK_COMMAND = 'borg-clear-rewake';
+const AUDIT_HOOK_COMMAND = 'borg-log-audit';
+const FOREIGN_PATH_REMINDER_HOOK_COMMAND = 'borg-foreign-path-reminder';
+const MCP_COMMAND = 'borg-mcp';
 
 /**
  * Claude Code CLI config path. The CLI reads `mcpServers.<name>` from
@@ -235,8 +234,7 @@ function addSessionStartHookAt(settingsFile: string, includeClearRewake = false)
   return true;
 }
 
-// gh#client#18: match bare names (old configs), stale absolute paths (other
-// installations), shell-escaped canonical paths, and unescaped canonical paths.
+// Match stable bare names plus legacy install-specific absolute forms.
 function commandMatches(entryCommand: string, bareName: string, absolutePath: string): boolean {
   const escaped = shellEscape(absolutePath);
   if (entryCommand === escaped || entryCommand === absolutePath || entryCommand === bareName) return true;
@@ -255,7 +253,7 @@ function commandMatches(entryCommand: string, bareName: string, absolutePath: st
  *      absolute command — always owned, no marker required (fixes neutral-path
  *      false negatives that broke idempotency)
  *  (c) Foreign-install heuristic: absolute path ending in an owned basename
- *      AND containing a borg package marker (borgmcp|borg-mcp) in the path
+ *      immediately below an exact borgmcp|borg-mcp/dist package path
  *  This prevents false-positive ownership of unrelated scripts that happen
  *  to share a basename (e.g. /opt/custom-tool/regen.js). */
 function ownedCanonical(command: string): string | null {
@@ -274,9 +272,16 @@ function ownedCanonical(command: string): string | null {
   if (command === AUDIT_HOOK_COMMAND || stripped === resolveLogAuditPath()) return AUDIT_HOOK_COMMAND;
   if (command === FOREIGN_PATH_REMINDER_HOOK_COMMAND || stripped === resolveForeignPathReminderPath()) return FOREIGN_PATH_REMINDER_HOOK_COMMAND;
 
-  // (c) Foreign-install heuristic: absolute path + owned basename + borg marker
-  if (stripped.startsWith('/') && (stripped.includes('borgmcp') || stripped.includes('borg-mcp'))) {
-    const name = stripped.split('/').pop() ?? '';
+  // (c) Foreign-install heuristic: require exact path segments shaped like a
+  // package root. A substring such as /opt/borgmcp-tools/ is not ownership.
+  const segments = stripped.split('/');
+  const packageIndex = segments.length - 3;
+  const packageShaped = packageIndex >= 0 &&
+    (segments[packageIndex] === 'borgmcp' || segments[packageIndex] === 'borg-mcp') &&
+    segments[packageIndex + 1] === 'dist' &&
+    packageIndex + 2 === segments.length - 1;
+  if (stripped.startsWith('/') && packageShaped) {
+    const name = segments.at(-1) ?? '';
     if (name === 'regen.js') return HOOK_COMMAND;
     if (name === 'clear-rewake.js') return CLEAR_REWAKE_HOOK_COMMAND;
     if (name === 'log-audit.js') return AUDIT_HOOK_COMMAND;
@@ -312,6 +317,7 @@ function migrateAndDedupOwnedHooks(entries: any[]): boolean {
   // object across all entries. Remove only the duplicate hook objects, not
   // entire entries (preserving unrelated siblings and entry metadata).
   const seenCanonicals = new Set<string>();
+  const emptiedByOwnedDedup = new Set<any>();
   for (const entry of entries) {
     if (!Array.isArray(entry?.hooks)) continue;
     const before = entry.hooks.length;
@@ -327,11 +333,13 @@ function migrateAndDedupOwnedHooks(entries: any[]): boolean {
       return true;
     });
     if (entry.hooks.length !== before) changed = true;
+    if (before > 0 && entry.hooks.length === 0) emptiedByOwnedDedup.add(entry);
   }
 
-  // Phase 3: Remove entries that became empty after dedup
+  // Phase 3: remove only entries emptied by removal of duplicate Borg-owned
+  // hooks. Pre-existing empty or unusual operator entries remain byte-stable.
   for (let i = entries.length - 1; i >= 0; i--) {
-    if (!Array.isArray(entries[i]?.hooks) || entries[i].hooks.length === 0) {
+    if (emptiedByOwnedDedup.has(entries[i])) {
       entries.splice(i, 1);
       changed = true;
     }
@@ -340,9 +348,165 @@ function migrateAndDedupOwnedHooks(entries: any[]): boolean {
   return changed;
 }
 
-/** Strict canonical match: only the shell-escaped canonical form.
- *  gh#client#18: raw unescaped paths are NOT canonical — a path with spaces
- *  or metacharacters would break at shell-fire time if not escaped. */
+export interface RefreshManagedAgentHookConfigOptions {
+  homeDir?: string;
+}
+
+export interface ManagedAgentHookConfigHealth {
+  path: string;
+  status: 'absent' | 'ok' | 'stale' | 'invalid';
+  detail?: string;
+}
+
+function globalManagedAgentHookConfigPaths(homeDir: string): string[] {
+  return [
+    path.join(homeDir, '.claude', 'settings.json'),
+    path.join(homeDir, '.codex', 'hooks.json'),
+  ];
+}
+
+function realDirectory(pathname: string): boolean {
+  try {
+    const stat = fs.lstatSync(pathname);
+    return stat.isDirectory() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Enumerate only Borg's canonical two-level managed-worktree layout. Every
+ * traversed component must be a real directory; symlinks are never followed.
+ */
+export function managedAgentHookConfigPaths(homeDir: string = CONFIG_HOME): string[] {
+  const paths = globalManagedAgentHookConfigPaths(homeDir);
+  const borgDir = path.join(homeDir, '.borg');
+  if (!realDirectory(borgDir)) return paths;
+  const root = path.join(borgDir, 'worktrees');
+  if (!realDirectory(root)) return paths;
+
+  for (const repo of fs.readdirSync(root, { withFileTypes: true })) {
+    const repoPath = path.join(root, repo.name);
+    if (!repo.isDirectory() || !realDirectory(repoPath)) continue;
+    for (const worktree of fs.readdirSync(repoPath, { withFileTypes: true })) {
+      const worktreePath = path.join(repoPath, worktree.name);
+      if (!worktree.isDirectory() || !realDirectory(worktreePath)) continue;
+      const claudeDir = path.join(worktreePath, '.claude');
+      if (!realDirectory(claudeDir)) continue;
+      const settingsFile = path.join(claudeDir, 'settings.local.json');
+      try {
+        if (fs.lstatSync(settingsFile).isSymbolicLink()) continue;
+      } catch {
+        // No settings file in this canonical worktree; nothing to inventory.
+        continue;
+      }
+      paths.push(settingsFile);
+    }
+  }
+  return paths;
+}
+
+function refreshHookFile(configPath: string): boolean {
+  if (!fs.existsSync(configPath)) return false;
+  const config = readJsonFile(configPath);
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('top-level value is not an object');
+  }
+  const hooks = config.hooks;
+  if (hooks === undefined) return false;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) {
+    throw new Error('hooks is not an object');
+  }
+  let changed = false;
+  for (const entries of Object.values(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    changed = migrateAndDedupOwnedHooks(entries) || changed;
+  }
+  if (changed) writeJsonFile(configPath, config);
+  return changed;
+}
+
+/**
+ * Heal stale Borg-owned hook commands in global agent files and canonical
+ * managed worktrees. Non-Borg hooks and noncanonical worktree roots are left
+ * untouched. Later files are still attempted when one file is invalid.
+ */
+export function refreshManagedAgentHookConfigs(
+  options: RefreshManagedAgentHookConfigOptions = {},
+): string[] {
+  const homeDir = options.homeDir ?? CONFIG_HOME;
+  const refreshed: string[] = [];
+  const failures: string[] = [];
+  let configPaths = globalManagedAgentHookConfigPaths(homeDir);
+  try {
+    configPaths = managedAgentHookConfigPaths(homeDir);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    failures.push(`hook inventory ${path.join(homeDir, '.borg', 'worktrees')}: ${message}`);
+  }
+  for (const configPath of configPaths) {
+    try {
+      if (refreshHookFile(configPath)) refreshed.push(configPath);
+    } catch (error) {
+      const label = configPath.endsWith(path.join('.codex', 'hooks.json'))
+        ? 'Codex'
+        : 'Claude Code';
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`${label} ${configPath}: ${message}`);
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(`Could not refresh managed agent hooks: ${failures.join('; ')}`);
+  }
+  return refreshed;
+}
+
+/** Read-only mirror of the updater's stale-command predicate. */
+export function inspectManagedAgentHookConfigs(
+  homeDir: string = CONFIG_HOME,
+): ManagedAgentHookConfigHealth[] {
+  let configPaths = globalManagedAgentHookConfigPaths(homeDir);
+  let inventoryIssue: ManagedAgentHookConfigHealth | null = null;
+  try {
+    configPaths = managedAgentHookConfigPaths(homeDir);
+  } catch (error) {
+    inventoryIssue = {
+      path: path.join(homeDir, '.borg', 'worktrees'),
+      status: 'invalid',
+      detail: `inventory failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  const health = configPaths.map((configPath): ManagedAgentHookConfigHealth => {
+    if (!fs.existsSync(configPath)) return { path: configPath, status: 'absent' };
+    try {
+      const config = readJsonFile(configPath);
+      if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        return { path: configPath, status: 'invalid', detail: 'top-level value is not an object' };
+      }
+      if (config.hooks === undefined) return { path: configPath, status: 'ok' };
+      if (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)) {
+        return { path: configPath, status: 'invalid', detail: 'hooks is not an object' };
+      }
+      const copy = structuredClone(config.hooks);
+      let stale = false;
+      for (const entries of Object.values(copy)) {
+        if (Array.isArray(entries)) stale = migrateAndDedupOwnedHooks(entries) || stale;
+      }
+      return { path: configPath, status: stale ? 'stale' : 'ok' };
+    } catch (error) {
+      return {
+        path: configPath,
+        status: 'invalid',
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+  if (inventoryIssue) health.push(inventoryIssue);
+  return health;
+}
+
+/** Strict canonical match. Quoted bare and legacy path forms are owned but
+ * require migration before they count as the one current command form. */
 function isCanonicalCommand(entryCommand: string, canonical: string): boolean {
   return entryCommand === canonical;
 }
@@ -369,7 +533,7 @@ function hasCommandHook(entries: any[], command: string): boolean {
   );
 }
 
-/** Strict: only the shell-escaped canonical form (no bare-name fallback). */
+/** Strict: only the current unquoted bare canonical form. */
 function hasCanonicalCommandHook(entries: any[], command: string): boolean {
   return entries.some((entry: any) =>
     Array.isArray(entry?.hooks) &&
@@ -678,6 +842,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 +1011,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 +1042,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 +1051,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 +1270,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/index.ts

@@ -73,7 +73,7 @@ import {
   pinMcpSeatIdentity,
 } from './cubes.js';
 import { isEntryInvocation, monitorStateRootForWorktree } from './inbox-monitor.js';
-import { addSessionStartHook, addUserPromptSubmitHook } from './config-utils.js';
+import { addUserPromptSubmitHook } from './config-utils.js';
 import {
   humanAgo,
   formatLogEntryMarkdown,
@@ -282,12 +282,6 @@ export async function main() {
   const readinessProbe = isMcpReadinessProbe();
   const openCodeRuntime = resolveSessionAgentKind() === 'opencode';
   const startupServices = {
-    // Auto-register the SessionStart hook so existing users get borg-regen
-    // auto-orientation on session start without re-running borg setup. Idempotent.
-    sessionStartHook: () => {
-      addSessionStartHook();
-    },
-
     // Auto-register the UserPromptSubmit audit hook so the drone gets a
     // nudge if the previous assistant span used state-changing tools
     // without calling borg_log. Domain-agnostic — knows nothing about git

package/src/regen-format.ts

@@ -18,7 +18,6 @@ import {
   renderRuntimeMetadataLines,
 } from './roster-render.js';
 import { shellEscape } from './shell-escape.js';
-import { resolveInboxMonitorPath } from './self-path.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 import { isBorgSession } from './launch-gate.js';
 
@@ -112,10 +111,10 @@ export function wakePathArming(
   if (agentKind === 'opencode') {
     return OPENCODE_WAKE_PATH_GUIDANCE;
   }
-  // gh#client#18: use absolute path to THIS installation's borg-inbox-monitor
-  // so the orientation command always resolves to the same version as the
-  // running client — never a different one via PATH.
-  const monitorBin = shellEscape(resolveInboxMonitorPath());
+  // client#394: the stable npm bin survives Node/nvm install-path rotation.
+  // Launch-time health checks make a missing or version-skewed PATH target
+  // visible instead of silently embedding a stale installation path here.
+  const monitorBin = 'borg-inbox-monitor';
   const monitorCommand = monitorStateRoot
     ? `${monitorBin} --state-root ${shellEscape(monitorStateRoot)} ${shellEscape(inboxPath)}`
     : `${monitorBin} ${shellEscape(inboxPath)}`;

package/src/startup-services.ts

@@ -2,7 +2,6 @@ export type McpStartupTask = () => void | Promise<void>;
 
 /** Required named services: omission from index wiring is a type error. */
 export interface McpStartupServices {
-  sessionStartHook: McpStartupTask;
   auditHook: McpStartupTask;
   sseStream: McpStartupTask;
   openCode: McpStartupTask;
@@ -21,12 +20,10 @@ export async function runMcpStartupServices(
 ): Promise<void> {
   if (readinessProbe) return;
   const tasks = options.openCodeFirst ? [
-    services.sessionStartHook,
     services.auditHook,
     services.openCode,
     services.sseStream,
   ] : [
-    services.sessionStartHook,
     services.auditHook,
     services.sseStream,
     services.openCode,

package/src/unknown-subcommand.ts

@@ -15,6 +15,7 @@
 export const KNOWN_SUBCOMMANDS = [
   'setup',
   'update',
+  'doctor',
   'assimilate',
   'reset-local-connection',
   'recover-enrollment',

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 { refreshAndVerifyManagedAgentIntegrations } from './agent-integration-health.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>;
+  refreshAgentIntegrations(): Promise<void>;
   confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
   isTTY(): boolean;
   stdout(text: string): void;
@@ -695,6 +697,14 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   }
 
   if (!serverWasPresent) {
+    try {
+      await deps.refreshAgentIntegrations();
+    } catch (error) {
+      deps.stderr(
+        `Client updated, but agent integration refresh and health check failed: ${errorMessage(error, 'unknown failure')}.\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 +819,18 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       retryCommand = 'borg server status';
       await deps.verifyRunningProtocol(status.endpoint!);
     }
+    try {
+      await deps.refreshAgentIntegrations();
+    } catch (error) {
+      const verifiedOutcome = state === 'stopped'
+        ? 'prepared runtime verified; server remains stopped'
+        : 'running identities and protocol verified';
+      deps.stderr(
+        `Updated ${CLIENT_PACKAGE}@${pair.client.version} and ${SERVER_PACKAGE}@${pair.server.version}; ${verifiedOutcome}.\n` +
+        `Agent integration refresh and health check failed: ${errorMessage(error, 'unknown failure')}.\n`,
+      );
+      return signalExitCode(error) ?? 1;
+    }
     deps.stdout(
       state === 'stopped'
         ? (
@@ -1210,6 +1232,7 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
       const trust = await loadBorgServerTrust(origin);
       await preflightBorgServerTag(origin, trust.fetchImpl);
     },
+    refreshAgentIntegrations: async () => refreshAndVerifyManagedAgentIntegrations(),
     confirm: defaultConfirm,
     isTTY: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
     stdout: (text) => process.stdout.write(text),