borgmcp 3.2.0 → 3.3.0

package/src/config-utils.ts

@@ -28,13 +28,13 @@ 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());
+// 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';
 
 /**
@@ -234,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;
@@ -254,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 {
@@ -273,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;
@@ -311,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;
@@ -326,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;
     }
@@ -339,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;
 }
@@ -368,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) &&

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,7 +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';
+import { refreshAndVerifyManagedAgentIntegrations } from './agent-integration-health.js';
 
 const CLIENT_PACKAGE = 'borgmcp';
 const SERVER_PACKAGE = 'borgmcp-server';
@@ -65,7 +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'>>;
+  refreshAgentIntegrations(): Promise<void>;
   confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
   isTTY(): boolean;
   stdout(text: string): void;
@@ -115,8 +115,7 @@ type ServerUpdateFailureStage =
   | 'final server state verification'
   | 'final package verification'
   | 'managed service continuity check'
-  | 'running server protocol verification'
-  | 'agent MCP config refresh';
+  | 'running server protocol verification';
 
 interface NpmContext {
   commandPath: string;
@@ -699,11 +698,10 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
 
   if (!serverWasPresent) {
     try {
-      await deps.refreshAgentMcpConfigs();
+      await deps.refreshAgentIntegrations();
     } 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`,
+        `Client updated, but agent integration refresh and health check failed: ${errorMessage(error, 'unknown failure')}.\n`,
       );
       return 1;
     }
@@ -821,9 +819,18 @@ 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();
+    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'
         ? (
@@ -1225,7 +1232,7 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
       const trust = await loadBorgServerTrust(origin);
       await preflightBorgServerTag(origin, trust.fetchImpl);
     },
-    refreshAgentMcpConfigs: async () => refreshManagedAgentMcpConfigs(),
+    refreshAgentIntegrations: async () => refreshAndVerifyManagedAgentIntegrations(),
     confirm: defaultConfirm,
     isTTY: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
     stdout: (text) => process.stdout.write(text),