@getmarrow/install 0.1.54 → 0.1.56

package/README.md

@@ -75,17 +75,19 @@ Tool visibility is not authorization. Every visible call still reaches Marrow's
 Marrow's hosted API, website, and dashboard update automatically; local SDK dependencies, generated runtime files, MCP hooks/configuration, and pinned package versions do not silently rewrite themselves. Keeping them current delivers new client-side features, compatibility improvements, and any published security fixes. Supported clients report their package version during authenticated status/runtime activity, and Marrow returns a `client_update` notice with the exact action when the version is behind or unknown.
 
 ```bash
-npx -y @getmarrow/install@latest activate
-npx -y @getmarrow/install@latest doctor
+# When doctor reports stale or mixed MCP configuration
+npx -y @getmarrow/install@latest update
+
+# Restart the detected owning harnesses once, then verify
+npx -y @getmarrow/install@latest doctor --self-test
 
 # Measured API read health and local backlog
 npx -y --package=@getmarrow/mcp@latest marrow-mcp ping
-
-# Use only when doctor reports drift
-npx -y @getmarrow/install@latest --repair
 ```
 
-`activate` reconciles Marrow-managed entries while retaining unrelated user hooks and configuration. After that explicit activation, the local controller can restore drifted Marrow-managed hooks and configuration. Package upgrades, owner policy, credentials, and unrelated local files remain explicit and subject to the operator's normal change policy.
+`update` resolves official npm metadata once, selects one exact verified MCP target, and synchronizes every Marrow-managed surface in the detected owning workspace while retaining unrelated user hooks and configuration. Restart the detected owning harnesses once after it completes; running processes do not change before that restart. Run the doctor verification once after restart. Do not run separate `marrow-mcp setup` and restart cycles for the same detected workspace.
+
+`activate` remains available for initial activation. After explicit activation, the local controller can restore drifted Marrow-managed hooks and configuration. Package upgrades, owner policy, credentials, explicitly disabled hooks, and unrelated local files remain explicit and subject to the operator's normal change policy.
 
 ## Automatic Controller
 
@@ -99,7 +101,15 @@ npx @getmarrow/install controller stop
 
 Persistent controller lifecycle is currently Linux-only. On macOS or Windows, activation still writes supported configuration and verifies one server-side install self-test without certifying that hooks continuously ran; run `npx @getmarrow/install sidecar` under an owner-managed service and pass `--no-controller`. The controller does not silently upgrade packages, change governance policy, rotate credentials, or modify unrelated project configuration.
 
-## What's New in v0.1.54
+## What's New in v0.1.56
+
+v0.1.56 pins the officially verified MCP `3.9.80` release from source `ee1eda3f201965a6530256accbdf175660dd8ad6` with registry integrity `sha512-uou3X18pESV39EMmddDrYN7yd6MrZzosrnQ1eRtvK5j3yuBLAlupj5kQVrrKEWAL6xwuLebXq2isivK2O/2WrA==`; SDK remains `3.7.62`. Doctor now directs stale, mixed, or version-unknown MCP installations through one `npx -y @getmarrow/install@latest update`, followed by one owning-harness restart and one `doctor --self-test` verification. The update resolves one official target and applies it consistently across detected Marrow-managed instructions, MCP launch configuration, and supported native hooks without claiming that already-running processes changed.
+
+## Previous: v0.1.55
+
+v0.1.55 pins sealed MCP candidate `3.9.79` from source `11f00049043d0aba90704ecbf69f32d2278a4573` for ordinary setup, generated launch configuration, and native hooks. Doctor, update, and repair retain exact-version resolution and never propagate a newer local version unless official registry metadata verifies it; offline operation preserves unverified-ahead owner surfaces and uses the sealed candidate for new managed targets.
+
+## Previous: v0.1.54
 
 v0.1.54 pins sealed MCP candidate `3.9.77` from source `1e782d8ba6bbb54bfaa322f0300565c7176f1969` and makes ordinary setup use the primary tool surface without writing a profile variable. Explicit `core` and `full` selections remain preserved, invalid values fail closed with a bounded repair, and human/JSON self-test output distinguishes configured/effective profile, expected visibility, actual post-reload visibility, and backend-projected entitlement state. Backend projections are status evidence only and always report `authorizes_calls: false`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/install",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "Universal installer and governed runner for Marrow agent fleets.",
   "bin": {
     "marrow-install": "bin/marrow-install.js"

package/src/installer.js

@@ -10,9 +10,9 @@ const { evidence: localControlEvidence } = require('./control-state');
 const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
 const MARROW_BLOCK_START = '<!-- marrow:passive-start -->';
 const MARROW_BLOCK_END = '<!-- marrow:passive-end -->';
-const MCP_ADAPTER_VERSION = '3.9.77';
-const MCP_ADAPTER_SOURCE_SHA = '1e782d8ba6bbb54bfaa322f0300565c7176f1969';
-const MCP_ADAPTER_INTEGRITY = 'sha512-4SVvnyTaDh/mhVUry1LaGCYKXSB/mt5NCHijIOLP336jILSqe7ezjZ5/EwEOMTQ2JvLm6w0QE/jmGbcksqe86w==';
+const MCP_ADAPTER_VERSION = '3.9.80';
+const MCP_ADAPTER_SOURCE_SHA = 'ee1eda3f201965a6530256accbdf175660dd8ad6';
+const MCP_ADAPTER_INTEGRITY = 'sha512-uou3X18pESV39EMmddDrYN7yd6MrZzosrnQ1eRtvK5j3yuBLAlupj5kQVrrKEWAL6xwuLebXq2isivK2O/2WrA==';
 const SDK_ADAPTER_VERSION = '3.7.62';
 const SDK_ADAPTER_INTEGRITY = 'sha512-n1i6Be09TpAQ9BPNRKY7aCvA2iSUPpJfw8djw2MELwpNbBCtKiZ29Jji77BK/6EFLUpSIcTW/Gmdf/ccf0JRYQ==';
 const SDK_ADAPTER_TARBALL = `https://registry.npmjs.org/@getmarrow/sdk/-/sdk-${SDK_ADAPTER_VERSION}.tgz`;
@@ -31,6 +31,196 @@ const ADAPTER_PROVENANCE = Object.freeze({
     integrity: SDK_ADAPTER_INTEGRITY,
   }),
 });
+const MCP_REGISTRY_LATEST_URL = 'https://registry.npmjs.org/%40getmarrow%2Fmcp/latest';
+const MCP_REGISTRY_VERIFICATION_COMMAND = 'npm view @getmarrow/mcp@latest name version dist.integrity dist.tarball --json --registry=https://registry.npmjs.org';
+const INSTALLER_UPDATE_COMMAND = 'npx -y @getmarrow/install@latest update';
+const INSTALLER_DOCTOR_COMMAND = 'npx -y @getmarrow/install@latest doctor --self-test';
+const INSTALLER_RESTART_INSTRUCTION = 'After the update completes, restart the detected owning harnesses once. Running Marrow MCP processes remain unchanged until that restart.';
+const MCP_STABLE_VERSION_RE = /^(\d{1,6})\.(\d{1,6})\.(\d{1,9})$/;
+const SHA512_INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
+const VERIFIED_MCP_EXECUTABLE_TARGET = Symbol('verified_mcp_executable_target');
+
+function validSha512Integrity(value) {
+  if (!SHA512_INTEGRITY_RE.test(value)) return false;
+  const encoded = value.slice('sha512-'.length);
+  try {
+    const digest = Buffer.from(encoded, 'base64');
+    return digest.length === 64 && digest.toString('base64') === encoded;
+  } catch {
+    return false;
+  }
+}
+
+function parsedStableMcpVersion(value) {
+  const match = String(value || '').match(MCP_STABLE_VERSION_RE);
+  if (!match) return null;
+  const parts = match.slice(1).map(Number);
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+function compareMcpVersions(left, right) {
+  const leftParts = parsedStableMcpVersion(left);
+  const rightParts = parsedStableMcpVersion(right);
+  if (!leftParts || !rightParts) return null;
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+function compatibleMcpTargetVersion(value) {
+  const candidate = parsedStableMcpVersion(value);
+  const sealed = parsedStableMcpVersion(MCP_ADAPTER_VERSION);
+  return Boolean(candidate && sealed
+    && candidate[0] === sealed[0]
+    && candidate[1] === sealed[1]
+    && compareMcpVersions(value, MCP_ADAPTER_VERSION) >= 0);
+}
+
+function mcpVersionsInText(value) {
+  return [...String(value || '').matchAll(/@getmarrow\/mcp@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/g)]
+    .map((match) => match[1]);
+}
+
+function marrowManagedBlockInText(value) {
+  const content = String(value || '');
+  const start = content.indexOf(MARROW_BLOCK_START);
+  if (start < 0) return '';
+  const end = content.indexOf(MARROW_BLOCK_END, start + MARROW_BLOCK_START.length);
+  if (end < 0) return '';
+  return content.slice(start, end + MARROW_BLOCK_END.length);
+}
+
+function unverifiedAheadMcpVersions(versions, targetVersion = MCP_ADAPTER_VERSION) {
+  if (!parsedStableMcpVersion(targetVersion)) return [];
+  return [...new Set((Array.isArray(versions) ? versions : [])
+    .filter((version) => parsedStableMcpVersion(version)
+      && compareMcpVersions(version, targetVersion) > 0))].sort((left, right) => compareMcpVersions(left, right));
+}
+
+function mcpRegistryVerificationAction(versions) {
+  const ahead = [...new Set(Array.isArray(versions) ? versions : [])].sort((left, right) => compareMcpVersions(left, right));
+  const targets = ahead.map((version) => `@getmarrow/mcp@${version}`).join(', ');
+  return `Run ${MCP_REGISTRY_VERIFICATION_COMMAND} with official npm registry access, then rerun npx -y @getmarrow/install@latest doctor --self-test. Automatic repair is suppressed${targets ? ` for ${targets}` : ''}; preserve each existing surface until registry metadata verifies it or the owner chooses the sealed or verified version.`;
+}
+
+function verifiedMcpRegistryMetadata(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const version = typeof value.version === 'string' ? value.version : '';
+  const integrity = typeof value.dist?.integrity === 'string' ? value.dist.integrity : '';
+  const tarball = typeof value.dist?.tarball === 'string' ? value.dist.tarball : '';
+  const expectedTarball = `https://registry.npmjs.org/@getmarrow/mcp/-/mcp-${version}.tgz`;
+  if (value.name !== '@getmarrow/mcp'
+    || !compatibleMcpTargetVersion(version)
+    || !validSha512Integrity(integrity)
+    || tarball !== expectedTarball) return null;
+  return { version, integrity, tarball };
+}
+
+function resolveMcpTargetVersion(options = {}) {
+  const registry = verifiedMcpRegistryMetadata(options.registryMetadata);
+  if (registry) {
+    const target = {
+      version: registry.version,
+      source: 'verified_npm_registry',
+      integrity: registry.integrity,
+      source_sha: null,
+    };
+    Object.defineProperty(target, VERIFIED_MCP_EXECUTABLE_TARGET, { value: true });
+    return target;
+  }
+  return {
+    version: MCP_ADAPTER_VERSION,
+    source: 'sealed_installer',
+    integrity: MCP_ADAPTER_INTEGRITY,
+    source_sha: MCP_ADAPTER_SOURCE_SHA,
+  };
+}
+
+function executableMcpTarget(options = {}) {
+  const target = options.mcpTarget;
+  if (target?.[VERIFIED_MCP_EXECUTABLE_TARGET] === true
+    && target.source === 'verified_npm_registry'
+    && compatibleMcpTargetVersion(target.version)
+    && validSha512Integrity(target.integrity)
+    && target.source_sha === null) return target;
+  return resolveMcpTargetVersion();
+}
+
+function expectedMcpInspectionVersion(options = {}) {
+  if (options.expectedVersion === MCP_ADAPTER_VERSION) return MCP_ADAPTER_VERSION;
+  return executableMcpTarget({ mcpTarget: options.expectedTarget }).version;
+}
+
+async function readMcpRegistryMetadata(options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, 'mcpRegistryMetadata')) {
+    return options.mcpRegistryMetadata;
+  }
+  if (options.resolveMcpRegistry !== true) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 2500);
+  try {
+    const fetcher = typeof options.registryFetch === 'function' ? options.registryFetch : fetch;
+    const response = await fetcher(MCP_REGISTRY_LATEST_URL, {
+      headers: { accept: 'application/json' },
+      redirect: 'error',
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function adapterProvenanceForMcpTarget(target) {
+  if (!target || target.version === MCP_ADAPTER_VERSION) return ADAPTER_PROVENANCE;
+  return {
+    mcp: {
+      package: '@getmarrow/mcp',
+      version: target.version,
+      source_sha: target.source_sha,
+      integrity: target.integrity,
+      integrity_state: target.source === 'verified_npm_registry'
+        ? 'verified_npm_registry_metadata'
+        : 'exact_current_configuration',
+    },
+    sdk: ADAPTER_PROVENANCE.sdk,
+  };
+}
+
+function retargetMcpPackageSpec(value, version) {
+  const target = compatibleMcpTargetVersion(version) ? version : MCP_ADAPTER_VERSION;
+  return String(value).split(MCP_PACKAGE_SPEC).join(`@getmarrow/mcp@${target}`);
+}
+
+function retargetMcpDowngradeRecommendation(value, targetVersion) {
+  if (typeof value !== 'string' || !compatibleMcpTargetVersion(targetVersion)) return value;
+  return value.replace(/@getmarrow\/mcp@(\d+\.\d+\.\d+)/g, (match, version) => (
+    parsedStableMcpVersion(version) && version !== targetVersion
+      ? `@getmarrow/mcp@${targetVersion}`
+      : match
+  ));
+}
+
+function alignMcpRecommendationVersions(value, targetVersion, key = '', verificationAction = null) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => alignMcpRecommendationVersions(entry, targetVersion, key, verificationAction));
+  }
+  if (!value || typeof value !== 'object') {
+    return /(?:command|fix|instruction|next_action|notice)$/i.test(key)
+      ? verificationAction && typeof value === 'string' && /@getmarrow\/mcp@\d+\.\d+\.\d+/.test(value)
+        ? verificationAction
+        : retargetMcpDowngradeRecommendation(value, targetVersion)
+      : value;
+  }
+  return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [
+    entryKey,
+    alignMcpRecommendationVersions(entryValue, targetVersion, entryKey, verificationAction),
+  ]));
+}
 const MCP_CONTEXT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp context-hook`;
 const MCP_PRE_ACTION_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp pre-action-hook`;
 const MCP_ACTION_RESULT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp hook`;
@@ -366,34 +556,55 @@ function inspectMcpProcesses(options = {}) {
     .filter(isMcpProcessCommand)
     .map((command) => explicitMcpVersion(command) || packageMcpVersion(command) || 'unknown');
   const versions = [...new Set(active.filter((version) => version !== 'unknown'))].sort();
+  const expectedVersion = expectedMcpInspectionVersion(options);
   const unknownVersionProcesses = active.filter((version) => version === 'unknown').length;
-  const staleVersions = versions.filter((version) => version !== MCP_ADAPTER_VERSION);
+  const aheadUnverifiedVersions = unverifiedAheadMcpVersions(versions, expectedVersion);
+  const staleVersions = versions.filter((version) => version !== expectedVersion
+    && !aheadUnverifiedVersions.includes(version));
   const mixedVersions = versions.length > 1 || (versions.length > 0 && unknownVersionProcesses > 0);
   const stale = staleVersions.length > 0;
-  const needsRepair = stale || mixedVersions || unknownVersionProcesses > 0;
-  const repairCommand = `npx -y --package=@getmarrow/mcp@${MCP_ADAPTER_VERSION} marrow-mcp setup`;
+  const aheadUnverified = aheadUnverifiedVersions.length > 0;
+  const needsRepair = stale || mixedVersions || unknownVersionProcesses > 0 || aheadUnverified;
+  const automaticRepairSuppressed = aheadUnverified;
   return {
     available: process.platform === 'linux' || Array.isArray(options.commands),
-    expected_version: MCP_ADAPTER_VERSION,
+    expected_version: expectedVersion,
     active_processes: active.length,
     active_versions: versions,
     unknown_version_processes: unknownVersionProcesses,
     stale_versions: staleVersions,
+    ahead_unverified: aheadUnverified,
+    ahead_unverified_versions: aheadUnverifiedVersions,
     mixed_versions: mixedVersions,
     healthy: !needsRepair,
-    exact_fix: needsRepair ? repairCommand : null,
-    restart_required: needsRepair,
-    restart_instruction: needsRepair ? 'Restart every owning harness to replace its active Marrow MCP process.' : null,
-    verification_command: needsRepair ? 'npx -y @getmarrow/install@latest doctor --self-test' : null,
+    automatic_repair_suppressed: automaticRepairSuppressed,
+    registry_verification_required: aheadUnverified,
+    exact_fix: automaticRepairSuppressed
+      ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
+      : needsRepair ? INSTALLER_UPDATE_COMMAND : null,
+    restart_required: needsRepair && !automaticRepairSuppressed,
+    restart_instruction: needsRepair && !automaticRepairSuppressed
+      ? INSTALLER_RESTART_INSTRUCTION
+      : null,
+    verification_command: needsRepair && !automaticRepairSuppressed ? INSTALLER_DOCTOR_COMMAND : null,
   };
 }
 
 function inspectMcpConfigurations(detection, options = {}) {
   const home = options.home || process.env.HOME || process.env.USERPROFILE || os.homedir();
   const configuredPaths = Array.isArray(options.paths) ? options.paths : [
+    detection?.paths?.agentsMd,
+    detection?.paths?.mcpJson,
     detection?.paths?.claudeSettings,
+    detection?.paths?.codexHooks,
+    detection?.paths?.cursorHooks,
     detection?.paths?.cursorMcp,
-    detection?.paths?.mcpJson,
+    detection?.paths?.clinePreToolUseHook,
+    detection?.paths?.clinePostToolUseHook,
+    detection?.paths?.clineTaskCancelHook,
+    detection?.paths?.windsurfHooks,
+    detection?.paths?.geminiSettings,
+    detection?.paths?.grokHooks,
     path.join(home, '.claude', 'settings.json'),
     path.join(home, '.claude.json'),
     path.join(home, '.cursor', 'mcp.json'),
@@ -410,9 +621,11 @@ function inspectMcpConfigurations(detection, options = {}) {
       if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024) continue;
       filesChecked += 1;
       const raw = fs.readFileSync(filePath, 'utf8');
-      const specs = [...raw.matchAll(/@getmarrow\/mcp@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/g)]
-        .map((match) => match[1]);
-      if (/@getmarrow\/mcp(?:@|["'\s])/.test(raw)) {
+      const inspected = path.basename(filePath) === 'AGENTS.md'
+        ? marrowManagedBlockInText(raw)
+        : raw;
+      const specs = mcpVersionsInText(inspected);
+      if (/@getmarrow\/mcp(?:@|["'\s])/.test(inspected)) {
         configurationsFound += 1;
         if (specs.length === 0) unknownVersionConfigurations += 1;
       }
@@ -422,21 +635,36 @@ function inspectMcpConfigurations(detection, options = {}) {
     }
   }
   const configuredVersions = [...new Set(versions)].sort();
-  const staleVersions = configuredVersions.filter((version) => version !== MCP_ADAPTER_VERSION);
+  const expectedVersion = expectedMcpInspectionVersion(options);
+  const aheadUnverifiedVersions = unverifiedAheadMcpVersions(configuredVersions, expectedVersion);
+  const staleVersions = configuredVersions.filter((version) => version !== expectedVersion
+    && !aheadUnverifiedVersions.includes(version));
   const mixedVersions = configuredVersions.length > 1
     || (configuredVersions.length > 0 && unknownVersionConfigurations > 0);
-  const healthy = staleVersions.length === 0 && !mixedVersions && unknownVersionConfigurations === 0;
+  const aheadUnverified = aheadUnverifiedVersions.length > 0;
+  const healthy = staleVersions.length === 0 && !mixedVersions
+    && unknownVersionConfigurations === 0 && !aheadUnverified;
   return {
-    expected_version: MCP_ADAPTER_VERSION,
+    expected_version: expectedVersion,
     files_checked: filesChecked,
     configurations_found: configurationsFound,
     configured_versions: configuredVersions,
     unknown_version_configurations: unknownVersionConfigurations,
     stale_versions: staleVersions,
+    ahead_unverified: aheadUnverified,
+    ahead_unverified_versions: aheadUnverifiedVersions,
     mixed_versions: mixedVersions,
     healthy,
-    exact_fix: healthy ? null : `Run npx -y --package=@getmarrow/mcp@${MCP_ADAPTER_VERSION} marrow-mcp setup in each owning workspace, update its MCP launch to npx -y --package=@getmarrow/mcp@${MCP_ADAPTER_VERSION} marrow-mcp, then restart that harness.`,
-    verification_command: healthy ? null : 'npx -y @getmarrow/install@latest doctor --self-test',
+    automatic_repair_suppressed: aheadUnverified,
+    registry_verification_required: aheadUnverified,
+    exact_fix: healthy
+      ? null
+      : aheadUnverified
+        ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
+        : INSTALLER_UPDATE_COMMAND,
+    restart_required: !healthy && !aheadUnverified,
+    restart_instruction: !healthy && !aheadUnverified ? INSTALLER_RESTART_INSTRUCTION : null,
+    verification_command: !healthy && !aheadUnverified ? INSTALLER_DOCTOR_COMMAND : null,
   };
 }
 
@@ -575,6 +803,7 @@ function parseArgs(argv, env = process.env) {
   if (options.activate && options.dryRun) {
     throw new Error('activate cannot be combined with --dry-run; use --dry-run without activate to preview changes');
   }
+  options.resolveMcpRegistry = Boolean(options.doctor || options.repair || options.update);
 
   return options;
 }
@@ -1486,6 +1715,75 @@ function grokNativeHookFingerprint(settings) {
   })).digest('hex');
 }
 
+function grokMarrowHookSubcommand(command) {
+  const direct = marrowHookSubcommand(command);
+  if (direct) return direct;
+  if (typeof command !== 'string') return null;
+  const guarded = command.match(
+    /@getmarrow\/mcp@[^\s"',]+["'],["']marrow-mcp["'],["']grok-(pre-action-hook)["']/,
+  );
+  return guarded?.[1] || null;
+}
+
+function reconcileGrokHook(settings, eventName, subcommand, command, matcher, timeout) {
+  const original = Array.isArray(settings?.hooks?.[eventName]) ? settings.hooks[eventName] : [];
+  const retained = [];
+  let preferredHandler = null;
+  for (const entry of original) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !Array.isArray(entry.hooks)) {
+      retained.push(entry);
+      continue;
+    }
+    const remaining = [];
+    for (const handler of entry.hooks) {
+      const detected = handler && typeof handler === 'object' && !Array.isArray(handler)
+        && handler.type === 'command' ? grokMarrowHookSubcommand(handler.command) : null;
+      if (detected) {
+        if (detected === subcommand && !preferredHandler) preferredHandler = handler;
+        continue;
+      }
+      remaining.push(handler);
+    }
+    if (remaining.length > 0) retained.push({ ...entry, hooks: remaining });
+  }
+  if (!command) return retained;
+  const canonical = {
+    ...(matcher === undefined ? {} : { matcher }),
+    hooks: [{ ...preferredHandler, type: 'command', command, timeout }],
+  };
+  return [...retained, canonical];
+}
+
+function upsertGrokHooks(settingsPath) {
+  const settings = parseJsonObject(settingsPath);
+  const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+    ? settings.hooks
+    : {};
+  settings.hooks = {
+    ...hooks,
+    UserPromptSubmit: reconcileGrokHook(settings, 'UserPromptSubmit', 'context-hook', GROK_CONTEXT_HOOK_COMMAND, undefined, 5),
+    PreToolUse: reconcileGrokHook(settings, 'PreToolUse', 'pre-action-hook', GROK_PRE_ACTION_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 7),
+    PostToolUse: reconcileGrokHook(settings, 'PostToolUse', 'hook', GROK_ACTION_RESULT_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 5),
+    PostToolUseFailure: reconcileGrokHook(settings, 'PostToolUseFailure', 'hook', GROK_ACTION_RESULT_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 5),
+    Stop: reconcileGrokHook(settings, 'Stop', 'session-hook', GROK_SESSION_END_HOOK_COMMAND, undefined, 3),
+    SessionEnd: reconcileGrokHook(settings, 'SessionEnd', 'session-hook', null, undefined, 3),
+  };
+  return JSON.stringify(settings, null, 2) + '\n';
+}
+
+function managedGrokHooksFile(filePath) {
+  if (!exists(filePath)) return false;
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) return true;
+    if (stat.size > 2 * 1024 * 1024) return true;
+    return /@getmarrow\/mcp@[^\s"']+[\s\S]{0,4096}marrow-mcp[\s\S]{0,512}grok-(?:context-hook|pre-action-hook|hook|session-hook)/
+      .test(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return true;
+  }
+}
+
 function upsertGeminiHooks(settingsPath) {
   const settings = parseJsonObject(settingsPath);
   const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
@@ -1603,8 +1901,12 @@ function activationProfile(detection, plan, changes, client) {
   const expectedHooks = capabilityLevel === 'sdk_passive_runtime'
     ? ['pre_action', 'action_result', 'outcome_closure']
     : [...registry.automatic];
+  const mcpTargetVersion = compatibleMcpTargetVersion(plan.mcp_target_version)
+    ? plan.mcp_target_version
+    : MCP_ADAPTER_VERSION;
+  const targetCommand = (command) => retargetMcpPackageSpec(command, mcpTargetVersion);
   const adapterVersion = capabilityLevel === 'native_hooks' || capabilityLevel === 'mcp'
-    ? MCP_ADAPTER_VERSION
+    ? mcpTargetVersion
     : capabilityLevel === 'sdk_passive_runtime'
     ? SDK_ADAPTER_VERSION
     : INSTALLER_ADAPTER_VERSION;
@@ -1616,71 +1918,71 @@ function activationProfile(detection, plan, changes, client) {
   const geminiSettings = safeJsonObject(detection.paths.geminiSettings);
   const grokSettings = safeJsonObject(detection.paths.grokHooks);
   if (client === 'codex') {
-    if (exactHookConfigured(codexSettings, 'UserPromptSubmit', CODEX_CONTEXT_HOOK_COMMAND)) observedHooks.push('prompt');
-    if (exactHookConfigured(codexSettings, 'PreToolUse', CODEX_PRE_ACTION_HOOK_COMMAND, CODEX_NATIVE_HOOK_MATCHER)) observedHooks.push('pre_action');
-    if (exactHookConfigured(codexSettings, 'PostToolUse', CODEX_ACTION_RESULT_HOOK_COMMAND, CODEX_NATIVE_HOOK_MATCHER)) observedHooks.push('action_result');
-    if (exactHookConfigured(codexSettings, 'SessionEnd', CODEX_SESSION_END_HOOK_COMMAND)) observedHooks.push('session_end');
+    if (exactHookConfigured(codexSettings, 'UserPromptSubmit', targetCommand(CODEX_CONTEXT_HOOK_COMMAND))) observedHooks.push('prompt');
+    if (exactHookConfigured(codexSettings, 'PreToolUse', targetCommand(CODEX_PRE_ACTION_HOOK_COMMAND), CODEX_NATIVE_HOOK_MATCHER)) observedHooks.push('pre_action');
+    if (exactHookConfigured(codexSettings, 'PostToolUse', targetCommand(CODEX_ACTION_RESULT_HOOK_COMMAND), CODEX_NATIVE_HOOK_MATCHER)) observedHooks.push('action_result');
+    if (exactHookConfigured(codexSettings, 'SessionEnd', targetCommand(CODEX_SESSION_END_HOOK_COMMAND))) observedHooks.push('session_end');
   } else if (client === 'cursor' || client === 'composer') {
-    if (exactCursorHookConfigured(cursorSettings, 'preToolUse', CURSOR_PRE_ACTION_HOOK_COMMAND, CURSOR_NATIVE_HOOK_MATCHER, {
+    if (exactCursorHookConfigured(cursorSettings, 'preToolUse', targetCommand(CURSOR_PRE_ACTION_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
       timeout: CODEX_HOOK_TIMEOUT_SECONDS, failClosed: true, async: false,
     })) observedHooks.push('pre_action');
-    if (exactCursorHookConfigured(cursorSettings, 'postToolUse', CURSOR_ACTION_RESULT_HOOK_COMMAND, CURSOR_NATIVE_HOOK_MATCHER, {
+    if (exactCursorHookConfigured(cursorSettings, 'postToolUse', targetCommand(CURSOR_ACTION_RESULT_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
       timeout: CODEX_HOOK_TIMEOUT_SECONDS,
-    }) && exactCursorHookConfigured(cursorSettings, 'postToolUseFailure', CURSOR_ACTION_RESULT_HOOK_COMMAND, CURSOR_NATIVE_HOOK_MATCHER, {
+    }) && exactCursorHookConfigured(cursorSettings, 'postToolUseFailure', targetCommand(CURSOR_ACTION_RESULT_HOOK_COMMAND), CURSOR_NATIVE_HOOK_MATCHER, {
       timeout: CODEX_HOOK_TIMEOUT_SECONDS,
     })) observedHooks.push('action_result');
-    if (exactCursorHookConfigured(cursorSettings, 'stop', CURSOR_SESSION_END_HOOK_COMMAND, undefined, {
+    if (exactCursorHookConfigured(cursorSettings, 'stop', targetCommand(CURSOR_SESSION_END_HOOK_COMMAND), undefined, {
       timeout: CODEX_SESSION_TIMEOUT_SECONDS,
     })) observedHooks.push('outcome_closure');
   } else if (client === 'cline') {
     for (const hook of clineHookContract(detection)) {
-      if (exactExecutableFile(hook.path, hook.content)) observedHooks.push(hook.stage);
+      if (exactExecutableFile(hook.path, targetCommand(hook.content))) observedHooks.push(hook.stage);
     }
   } else if (client === 'windsurf') {
     if (WINDSURF_PRE_EVENTS.every((event) => exactWindsurfHookConfigured(
-      windsurfSettings, event, WINDSURF_PRE_ACTION_HOOK_COMMAND,
+      windsurfSettings, event, targetCommand(WINDSURF_PRE_ACTION_HOOK_COMMAND),
     ))) observedHooks.push('pre_action');
     if (WINDSURF_POST_EVENTS.every((event) => exactWindsurfHookConfigured(
-      windsurfSettings, event, WINDSURF_ACTION_RESULT_HOOK_COMMAND,
+      windsurfSettings, event, targetCommand(WINDSURF_ACTION_RESULT_HOOK_COMMAND),
     ))) observedHooks.push('action_result');
     if (exactWindsurfHookConfigured(
-      windsurfSettings, 'post_cascade_response', WINDSURF_SESSION_END_HOOK_COMMAND,
+      windsurfSettings, 'post_cascade_response', targetCommand(WINDSURF_SESSION_END_HOOK_COMMAND),
     )) observedHooks.push('response_closeout');
   } else if (client === 'gemini' && !geminiHooksExplicitlyDisabled(geminiSettings)) {
     if (exactGeminiHookConfigured(
-      geminiSettings, 'BeforeTool', 'marrow-before-tool', GEMINI_PRE_ACTION_HOOK_COMMAND,
+      geminiSettings, 'BeforeTool', 'marrow-before-tool', targetCommand(GEMINI_PRE_ACTION_HOOK_COMMAND),
       GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
     )) observedHooks.push('pre_action');
     if (exactGeminiHookConfigured(
-      geminiSettings, 'AfterTool', 'marrow-after-tool', GEMINI_ACTION_RESULT_HOOK_COMMAND,
+      geminiSettings, 'AfterTool', 'marrow-after-tool', targetCommand(GEMINI_ACTION_RESULT_HOOK_COMMAND),
       GEMINI_NATIVE_HOOK_MATCHER, GEMINI_HOOK_TIMEOUT_MS,
     )) observedHooks.push('action_result');
     if (exactGeminiHookConfigured(
-      geminiSettings, 'AfterAgent', 'marrow-after-agent', GEMINI_SESSION_END_HOOK_COMMAND,
+      geminiSettings, 'AfterAgent', 'marrow-after-agent', targetCommand(GEMINI_SESSION_END_HOOK_COMMAND),
       undefined, GEMINI_CLOSEOUT_TIMEOUT_MS,
     )) observedHooks.push('turn_closeout');
   } else if (client === 'grok') {
     if (exactGrokHookConfigured(
-      grokSettings, 'PreToolUse', GROK_PRE_ACTION_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 7,
+      grokSettings, 'PreToolUse', targetCommand(GROK_PRE_ACTION_HOOK_COMMAND), GROK_NATIVE_HOOK_MATCHER, 7,
     )) observedHooks.push('pre_action');
     if (exactGrokHookConfigured(
-      grokSettings, 'PostToolUse', GROK_ACTION_RESULT_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 5,
+      grokSettings, 'PostToolUse', targetCommand(GROK_ACTION_RESULT_HOOK_COMMAND), GROK_NATIVE_HOOK_MATCHER, 5,
     ) && exactGrokHookConfigured(
-      grokSettings, 'PostToolUseFailure', GROK_ACTION_RESULT_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 5,
+      grokSettings, 'PostToolUseFailure', targetCommand(GROK_ACTION_RESULT_HOOK_COMMAND), GROK_NATIVE_HOOK_MATCHER, 5,
     )) observedHooks.push('action_result');
     if (exactGrokHookConfigured(
-      grokSettings, 'Stop', GROK_SESSION_END_HOOK_COMMAND, undefined, 3,
+      grokSettings, 'Stop', targetCommand(GROK_SESSION_END_HOOK_COMMAND), undefined, 3,
     ) && !grokHasDuplicateSessionEnd(grokSettings)) observedHooks.push('turn_closeout');
   } else {
     if (capabilityLevel === 'native_hooks'
-      && exactHookConfigured(claudeSettings, 'UserPromptSubmit', MCP_CONTEXT_HOOK_COMMAND)) observedHooks.push('prompt');
+      && exactHookConfigured(claudeSettings, 'UserPromptSubmit', targetCommand(MCP_CONTEXT_HOOK_COMMAND))) observedHooks.push('prompt');
     if (capabilityLevel === 'native_hooks'
-      && exactHookConfigured(claudeSettings, 'PreToolUse', MCP_PRE_ACTION_HOOK_COMMAND, NATIVE_HOOK_MATCHER)) observedHooks.push('pre_action');
+      && exactHookConfigured(claudeSettings, 'PreToolUse', targetCommand(MCP_PRE_ACTION_HOOK_COMMAND), NATIVE_HOOK_MATCHER)) observedHooks.push('pre_action');
     if (capabilityLevel === 'native_hooks'
-      && exactHookConfigured(claudeSettings, 'PostToolUse', MCP_ACTION_RESULT_HOOK_COMMAND, NATIVE_HOOK_MATCHER)
-      && exactHookConfigured(claudeSettings, 'PostToolUseFailure', MCP_ACTION_RESULT_HOOK_COMMAND, NATIVE_HOOK_MATCHER)) observedHooks.push('action_result');
+      && exactHookConfigured(claudeSettings, 'PostToolUse', targetCommand(MCP_ACTION_RESULT_HOOK_COMMAND), NATIVE_HOOK_MATCHER)
+      && exactHookConfigured(claudeSettings, 'PostToolUseFailure', targetCommand(MCP_ACTION_RESULT_HOOK_COMMAND), NATIVE_HOOK_MATCHER)) observedHooks.push('action_result');
     if (capabilityLevel === 'native_hooks'
-      && exactHookConfigured(claudeSettings, 'Stop', MCP_SESSION_END_HOOK_COMMAND)) observedHooks.push('session_end');
+      && exactHookConfigured(claudeSettings, 'Stop', targetCommand(MCP_SESSION_END_HOOK_COMMAND))) observedHooks.push('session_end');
   }
   const passiveRuntime = safeRead(detection.paths.passiveRuntime);
   if (capabilityLevel === 'sdk_passive_runtime'
@@ -1696,7 +1998,7 @@ function activationProfile(detection, plan, changes, client) {
   if (capabilityLevel === 'mcp' && mcpConfigs.some((config) => (
     config?.mcpServers?.marrow?.command === 'npx'
     && Array.isArray(config.mcpServers.marrow.args)
-    && config.mcpServers.marrow.args.join(' ') === `-y --package=${MCP_PACKAGE_SPEC} marrow-mcp`
+    && config.mcpServers.marrow.args.join(' ') === `-y --package=@getmarrow/mcp@${mcpTargetVersion} marrow-mcp`
   ))) observedHooks.push('mcp_tool_calls');
   const fingerprintMaterial = changes
     .filter((change) => change.applied || change.already_present)
@@ -1737,7 +2039,7 @@ function activationProfile(detection, plan, changes, client) {
     : client === 'gemini' && geminiHooksExplicitlyDisabled(geminiSettings)
     ? 'Hooks are explicitly disabled. After owner review, run /hooks enable-all, open /hooks panel, review and approve the project hook fingerprints, then restart Gemini CLI.'
     : client === 'grok'
-    ? `Run npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp setup, restart Grok, then inspect /hooks and confirm the global hooks are enabled.`
+    ? `Run npx -y --package=@getmarrow/mcp@${mcpTargetVersion} marrow-mcp setup, restart Grok, then inspect /hooks and confirm the global hooks are enabled.`
     : 'npx @getmarrow/install --repair';
   return {
     adapter_version: adapterVersion,
@@ -2026,6 +2328,8 @@ function buildPlan(detection, options) {
   const client = options.client || detectedClient(detection);
   const agentId = String(options.agentId || '').trim() || stableAgentId(detection.root, client);
   const baseUrl = String(options.baseUrl || DEFAULT_BASE_URL).trim() || DEFAULT_BASE_URL;
+  const mcpTargetVersion = executableMcpTarget(options).version;
+  const retarget = (value) => retargetMcpPackageSpec(value, mcpTargetVersion);
   const mode = options.mode === 'auto'
     ? detection.node ? 'both' : 'mcp'
     : options.mode;
@@ -2053,7 +2357,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.claudeSettings,
         label: 'Claude Code MCP passive hooks',
-        transform: upsertClaudeHooks,
+        transform: (filePath) => retarget(upsertClaudeHooks(filePath)),
       });
     }
     if (detection.codex) {
@@ -2061,7 +2365,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.codexHooks,
         label: 'Codex native hooks',
-        transform: upsertCodexHooks,
+        transform: (filePath) => retarget(upsertCodexHooks(filePath)),
       });
     }
     if (detection.cline) {
@@ -2070,7 +2374,7 @@ function buildPlan(detection, options) {
           type: 'owned-executable',
           path: hook.path,
           label: hook.label,
-          content: hook.content,
+          content: retarget(hook.content),
           mode: 0o755,
           conflict_fix: 'Move or remove the existing owner-managed Cline hook after owner review, then run npx @getmarrow/install --repair.',
         });
@@ -2081,7 +2385,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.windsurfHooks,
         label: 'Windsurf native hooks',
-        transform: upsertWindsurfHooks,
+        transform: (filePath) => retarget(upsertWindsurfHooks(filePath)),
       });
     }
     if (detection.gemini) {
@@ -2089,27 +2393,36 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.geminiSettings,
         label: 'Gemini CLI native hooks',
-        transform: upsertGeminiHooks,
+        transform: (filePath) => retarget(upsertGeminiHooks(filePath)),
+      });
+    }
+    if (options.update && detection.grok && managedGrokHooksFile(detection.paths.grokHooks)) {
+      writes.push({
+        type: 'json-transform',
+        path: detection.paths.grokHooks,
+        root: path.resolve(detection.paths.grokHooks, '..', '..', '..'),
+        label: 'Grok native hooks',
+        transform: (filePath) => retarget(upsertGrokHooks(filePath)),
       });
     }
     writes.push({
       type: 'json-transform',
       path: detection.paths.mcpJson,
       label: 'Project MCP server config',
-      transform: (filePath) => upsertMcpServerConfig(filePath, { agentId, baseUrl, toolProfile: options.toolProfile }),
+      transform: (filePath) => retarget(upsertMcpServerConfig(filePath, { agentId, baseUrl, toolProfile: options.toolProfile })),
     });
     if (detection.cursor) {
       writes.push({
         type: 'json-transform',
         path: detection.paths.cursorHooks,
         label: 'Cursor native hooks',
-        transform: upsertCursorHooks,
+        transform: (filePath) => retarget(upsertCursorHooks(filePath)),
       });
       writes.push({
         type: 'json-transform',
         path: detection.paths.cursorMcp,
         label: 'Cursor MCP server config',
-        transform: (filePath) => upsertMcpServerConfig(filePath, { agentId, baseUrl, toolProfile: options.toolProfile }),
+        transform: (filePath) => retarget(upsertMcpServerConfig(filePath, { agentId, baseUrl, toolProfile: options.toolProfile })),
       });
     }
   }
@@ -2119,7 +2432,7 @@ function buildPlan(detection, options) {
       type: 'md-block',
       path: detection.paths.agentsMd,
       label: 'Agent instructions',
-      block: passiveInstructions(),
+      block: retarget(passiveInstructions()),
     });
   }
 
@@ -2128,11 +2441,11 @@ function buildPlan(detection, options) {
       type: 'file',
       path: detection.paths.cursorRules,
       label: 'Cursor Marrow rule',
-      content: passiveInstructions().replace(/<!--[^>]+-->/g, '').trim() + '\n',
+      content: retarget(passiveInstructions()).replace(/<!--[^>]+-->/g, '').trim() + '\n',
     });
   }
 
-  return { mode, root: detection.root, writes };
+  return { mode, root: detection.root, writes, mcp_target_version: mcpTargetVersion };
 }
 
 function assertContainedManagedTarget(root, targetPath) {
@@ -2194,13 +2507,25 @@ function atomicWriteManagedFile(root, targetPath, contents) {
 function applyPlan(plan, options) {
   if (!Array.isArray(plan?.writes) || plan.writes.length === 0) return [];
   const root = path.resolve(plan.root || path.dirname(plan.writes[0].path));
-  for (const write of plan.writes) assertContainedManagedTarget(root, write.path);
+  for (const write of plan.writes) {
+    assertContainedManagedTarget(path.resolve(write.root || root), write.path);
+  }
   const prepared = plan.writes.map((write) => {
     const fileExists = exists(write.path);
     const before = safeRead(write.path);
+    const inspectedBefore = write.type === 'md-block'
+      ? marrowManagedBlockInText(before)
+      : before;
+    const aheadUnverifiedVersions = unverifiedAheadMcpVersions(
+      mcpVersionsInText(inspectedBefore),
+      plan.mcp_target_version,
+    );
+    const automaticRepairSuppressed = aheadUnverifiedVersions.length > 0;
     let after;
     let hookConflict = false;
-    if (write.type === 'file') {
+    if (automaticRepairSuppressed) {
+      after = before;
+    } else if (write.type === 'file') {
       if (write.overwrite === false && before) {
         after = before;
       } else {
@@ -2223,28 +2548,50 @@ function applyPlan(plan, options) {
 
     const beforeMode = fileExists ? fs.lstatSync(write.path).mode & 0o777 : null;
     const modeChanged = !hookConflict && typeof write.mode === 'number' && beforeMode !== write.mode;
-    return { write, before, after, hookConflict, modeChanged };
+    return {
+      write,
+      before,
+      after,
+      hookConflict,
+      modeChanged,
+      automaticRepairSuppressed,
+      aheadUnverifiedVersions,
+    };
   });
 
   const changes = [];
-  for (const { write, before, after, hookConflict, modeChanged } of prepared) {
+  for (const {
+    write,
+    before,
+    after,
+    hookConflict,
+    modeChanged,
+    automaticRepairSuppressed,
+    aheadUnverifiedVersions,
+  } of prepared) {
     const contentChanged = before !== after;
-    const changed = !hookConflict && (contentChanged || modeChanged);
-    const writeApplied = Boolean(options.yes && !options.dryRun && !options.doctor && !hookConflict);
+    const changed = !automaticRepairSuppressed && !hookConflict && (contentChanged || modeChanged);
+    const writeApplied = Boolean(options.yes && !options.dryRun && !options.doctor
+      && !hookConflict && !automaticRepairSuppressed);
     changes.push({
       path: write.path,
       label: write.label,
       changed,
       applied: changed && writeApplied,
-      already_present: !changed && !hookConflict,
+      already_present: !changed && !hookConflict && !automaticRepairSuppressed,
       hook_conflict: hookConflict,
+      automatic_repair_suppressed: automaticRepairSuppressed,
+      ...(automaticRepairSuppressed ? {
+        ahead_unverified_versions: aheadUnverifiedVersions,
+        exact_fix: mcpRegistryVerificationAction(aheadUnverifiedVersions),
+      } : {}),
       ...(hookConflict ? { exact_fix: write.conflict_fix } : {}),
     });
     if (contentChanged && writeApplied) {
-      atomicWriteManagedFile(root, write.path, after);
+      atomicWriteManagedFile(path.resolve(write.root || root), write.path, after);
     }
     if (modeChanged && writeApplied) {
-      assertContainedManagedTarget(root, write.path);
+      assertContainedManagedTarget(path.resolve(write.root || root), write.path);
       fs.chmodSync(write.path, write.mode);
     }
   }
@@ -2303,7 +2650,7 @@ async function runSelfTest(options) {
     'x-marrow-package-version': INSTALLER_ADAPTER_VERSION,
     'x-marrow-install-version': INSTALLER_ADAPTER_VERSION,
     'x-marrow-sdk-version': SDK_ADAPTER_VERSION,
-    'x-marrow-mcp-version': MCP_ADAPTER_VERSION,
+    'x-marrow-mcp-version': executableMcpTarget(options).version,
   };
   if (options.agentId) headers['x-marrow-agent-id'] = options.agentId;
 
@@ -2668,8 +3015,13 @@ function printReport(report) {
 
   process.stdout.write('\nPlanned changes:\n');
   for (const change of report.changes) {
-    const marker = change.applied ? 'wrote' : change.changed ? 'would write' : 'unchanged';
+    const marker = change.automatic_repair_suppressed
+      ? 'preserved unverified-ahead surface; repair suppressed'
+      : change.applied ? 'wrote' : change.changed ? 'would write' : 'unchanged';
     process.stdout.write(`- ${marker}: ${change.label} (${change.path})\n`);
+    if (change.automatic_repair_suppressed && change.exact_fix) {
+      process.stdout.write(`  exact verification: ${change.exact_fix}\n`);
+    }
   }
 
   process.stdout.write('\nSelf-test:\n');
@@ -2752,12 +3104,12 @@ function printReport(report) {
     }
   }
 
-  if (report.harnessReload) {
+  if (report.harnessReload && report.writeMode !== 'doctor') {
     process.stdout.write('\nHarness reload:\n');
     process.stdout.write(`- required: ${report.harnessReload.required ? 'yes' : 'no'}\n`);
     process.stdout.write(`- live in this process: ${report.harnessReload.live_in_this_process ? 'yes' : 'no'}\n`);
-    if (report.harnessReload.instruction) process.stdout.write(`- restart: ${report.harnessReload.instruction}\n`);
-    if (report.harnessReload.prove_command) process.stdout.write(`- prove after restart: ${report.harnessReload.prove_command}\n`);
+    if (report.harnessReload.required && report.harnessReload.instruction) process.stdout.write(`- restart: ${report.harnessReload.instruction}\n`);
+    if (report.harnessReload.required && report.harnessReload.prove_command) process.stdout.write(`- prove after restart: ${report.harnessReload.prove_command}\n`);
   }
   if (report.firstCapture) {
     process.stdout.write('\nFirst capture:\n');
@@ -2804,7 +3156,9 @@ function printReport(report) {
   if (report.controller?.exact_fix) process.stdout.write(`- exact fix: ${report.controller.exact_fix}\n`);
 
   if (report.writeMode === 'doctor') {
-    const liveHere = !report.harnessReload?.required;
+    const liveHere = !report.harnessReload?.required
+      && report.doctor.mcpProcesses?.healthy !== false
+      && report.doctor.mcpConfigurations?.healthy !== false;
     const activeLabel = report.doctor.active && liveHere
       ? 'yes'
       : report.doctor.active
@@ -2819,15 +3173,21 @@ function printReport(report) {
       const processes = report.doctor.mcpProcesses;
       process.stdout.write(`- MCP process versions: ${processes.active_versions.length ? processes.active_versions.join(', ') : processes.active_processes ? 'unknown' : 'none'}\n`);
       process.stdout.write(`- stale/mixed/version-unknown MCP clients: ${processes.healthy ? 'no' : 'yes'}\n`);
-      if (processes.restart_instruction) process.stdout.write(`- restart required: ${processes.restart_instruction}\n`);
-      if (processes.verification_command) process.stdout.write(`- verify repair: ${processes.verification_command}\n`);
+      if (processes.ahead_unverified_versions.length) process.stdout.write(`- unverified-ahead MCP clients: ${processes.ahead_unverified_versions.join(', ')}\n`);
+      if (processes.automatic_repair_suppressed) process.stdout.write('- automatic MCP process repair: suppressed pending official registry verification\n');
     }
     if (report.doctor.mcpConfigurations) {
       const configurations = report.doctor.mcpConfigurations;
       process.stdout.write(`- configured MCP versions: ${configurations.configured_versions.length ? configurations.configured_versions.join(', ') : 'none pinned'}\n`);
       process.stdout.write(`- stale/mixed/version-unknown MCP configuration: ${configurations.healthy ? 'no' : 'yes'}\n`);
+      if (configurations.ahead_unverified_versions.length) process.stdout.write(`- unverified-ahead MCP configuration: ${configurations.ahead_unverified_versions.join(', ')}\n`);
+      if (configurations.automatic_repair_suppressed) process.stdout.write('- automatic MCP configuration repair: suppressed pending official registry verification\n');
     }
     if (report.doctor.recommendedFix) process.stdout.write(`- recommended fix: ${report.doctor.recommendedFix}\n`);
+    if (report.doctor.mcp_update_required) {
+      process.stdout.write(`- restart once after update: ${report.doctor.restart_instruction}\n`);
+      process.stdout.write(`- verify after restart: ${report.doctor.verification_command}\n`);
+    }
     process.stdout.write(`- live health: ${report.doctor.healthCommand}\n`);
   }
 
@@ -2863,10 +3223,23 @@ async function install(options) {
   const client = detectedClient(detection);
   options.client = client;
   options.agentId = String(options.agentId || '').trim() || stableAgentId(detection.root, client);
+  const observedMcpProcesses = inspectMcpProcesses({ commands: options.processCommands });
+  const observedMcpConfigurations = inspectMcpConfigurations(detection, { paths: options.mcpConfigPaths });
+  const registryMetadata = await readMcpRegistryMetadata(options);
+  const latestTargetOperation = Boolean(options.doctor || options.repair || options.update);
+  const mcpTarget = resolveMcpTargetVersion({
+    currentVersions: latestTargetOperation ? [
+      ...observedMcpProcesses.active_versions,
+      ...observedMcpConfigurations.configured_versions,
+    ] : [],
+    registryMetadata: latestTargetOperation ? registryMetadata : null,
+  });
+  options.mcpTarget = mcpTarget;
+  options.mcpTargetVersion = mcpTarget.version;
   const plan = buildPlan(detection, options);
   const writeMode = options.doctor ? 'doctor' : options.dryRun ? 'dry-run' : options.repair ? 'repair' : options.yes ? 'write' : 'dry-run';
   const changes = applyPlan(plan, options);
-  const profile = activationProfile(detection, plan, changes, client);
+  let profile = activationProfile(detection, plan, changes, client);
   options.activation = options.activate ? {
     harness: client,
     agent_id: options.agentId,
@@ -2897,8 +3270,35 @@ async function install(options) {
     ? repairConfigDiagnostics(configDiagnostics)
     : [];
   const envHints = options.apiKey ? [] : findLikelyEnvFiles(detection);
-  const mcpProcesses = inspectMcpProcesses({ commands: options.processCommands });
-  const mcpConfigurations = inspectMcpConfigurations(detection, { paths: options.mcpConfigPaths });
+  const mcpProcesses = inspectMcpProcesses({
+    commands: options.processCommands,
+    expectedTarget: mcpTarget,
+  });
+  const mcpConfigurations = inspectMcpConfigurations(detection, {
+    paths: options.mcpConfigPaths,
+    expectedTarget: mcpTarget,
+  });
+  const aheadUnverifiedVersions = [...new Set([
+    ...mcpProcesses.ahead_unverified_versions,
+    ...mcpConfigurations.ahead_unverified_versions,
+    ...changes.flatMap((change) => change.ahead_unverified_versions || []),
+  ])].sort((left, right) => compareMcpVersions(left, right));
+  const automaticMcpRepairSuppressed = aheadUnverifiedVersions.length > 0;
+  const registryVerificationAction = automaticMcpRepairSuppressed
+    ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
+    : null;
+  const mcpUpdateRequired = !automaticMcpRepairSuppressed
+    && (!mcpConfigurations.healthy || (!options.update && !mcpProcesses.healthy));
+  if (automaticMcpRepairSuppressed) {
+    profile = {
+      ...profile,
+      configuration_complete: false,
+      complete: false,
+      automatic_repair_suppressed: true,
+      ahead_unverified_versions: aheadUnverifiedVersions,
+      exact_fix: registryVerificationAction,
+    };
+  }
   let selfTest;
   try {
     selfTest = await runSelfTest(options);
@@ -2912,10 +3312,49 @@ async function install(options) {
       mcp_tool_profile: initialToolProfileReport(options.toolProfile),
     };
   }
+  selfTest = alignMcpRecommendationVersions(
+    selfTest,
+    mcpTarget.version,
+    '',
+    registryVerificationAction,
+  );
   if (options.activate && !selfTest.activation_verified) {
     throw new Error('Marrow activation failed: server confirmation was not returned');
   }
-  const harnessReload = harnessReloadPlan(detection, changes);
+  const plannedHarnessReload = harnessReloadPlan(detection, options.doctor ? [] : changes);
+  const updateNeedsRestart = Boolean(options.update
+    && !automaticMcpRepairSuppressed
+    && (plannedHarnessReload.required || (mcpConfigurations.healthy && !mcpProcesses.healthy)));
+  const harnessReload = options.doctor && mcpUpdateRequired
+    ? {
+      ...plannedHarnessReload,
+      required: true,
+      live_in_this_process: false,
+      instruction: INSTALLER_RESTART_INSTRUCTION,
+      prove_command: INSTALLER_DOCTOR_COMMAND,
+    }
+    : updateNeedsRestart
+    ? {
+      ...plannedHarnessReload,
+      required: true,
+      live_in_this_process: false,
+      instruction: INSTALLER_RESTART_INSTRUCTION,
+      prove_command: INSTALLER_DOCTOR_COMMAND,
+    }
+    : plannedHarnessReload;
+  const updateAwaitingRestart = Boolean(options.update
+    && updateNeedsRestart
+    && mcpConfigurations.healthy
+    && !mcpProcesses.healthy
+    && !automaticMcpRepairSuppressed);
+  const reportedMcpProcesses = updateAwaitingRestart
+    ? {
+      ...mcpProcesses,
+      update_completed: true,
+      awaiting_restart: true,
+      exact_fix: null,
+    }
+    : mcpProcesses;
   if (harnessReload.required && selfTest.mcp_tool_profile) {
     selfTest.mcp_tool_profile = {
       ...selfTest.mcp_tool_profile,
@@ -2972,7 +3411,12 @@ async function install(options) {
       attempted: true,
       fixedConfig: changedConfig,
       selfTestPassed,
-      message: selfTestPassed
+      automaticMcpRepairSuppressed,
+      message: automaticMcpRepairSuppressed
+        ? registryVerificationAction
+        : options.update && harnessReload.required
+        ? 'Managed Marrow configuration is synchronized. Running MCP processes are unchanged; complete the Harness reload steps below before treating the update as live.'
+        : selfTestPassed
         ? selfTest.health === 'healthy'
           ? 'I fixed Marrow passive config, one-call runtime is active, and self-test passed.'
           : `I fixed Marrow passive config and self-test passed; status is ${selfTest.health || 'unknown'}${selfTest.next_action ? `. Next action: ${selfTest.next_action}` : ''}.`
@@ -2981,10 +3425,9 @@ async function install(options) {
         : `Config repair ran, but self-test failed: ${selfTest.error || 'unknown error'}.`,
     }
     : null;
-
   return {
     root: detection.root,
-    adapterProvenance: ADAPTER_PROVENANCE,
+    adapterProvenance: adapterProvenanceForMcpTarget(mcpTarget),
     mode: plan.mode,
     writeMode,
     toolProfile: selfTest.mcp_tool_profile || initialToolProfileReport(options.toolProfile),
@@ -3018,9 +3461,18 @@ async function install(options) {
       missingEnv: options.apiKey ? [] : ['MARROW_API_KEY'],
       envHints,
       missingHooks: changes.filter((change) => change.changed).map((change) => change.label),
-      mcpProcesses,
+      mcpProcesses: reportedMcpProcesses,
       mcpConfigurations,
-      recommendedFix: mcpProcesses.exact_fix || mcpConfigurations.exact_fix || configDiagnostics.npm_token.recommended_fix || (!options.apiKey
+      ahead_unverified_versions: aheadUnverifiedVersions,
+      automatic_mcp_repair_suppressed: automaticMcpRepairSuppressed,
+      registry_verification_action: registryVerificationAction,
+      mcp_update_required: mcpUpdateRequired,
+      restart_required: mcpUpdateRequired || updateAwaitingRestart,
+      restart_instruction: mcpUpdateRequired || updateAwaitingRestart ? INSTALLER_RESTART_INSTRUCTION : null,
+      verification_command: mcpUpdateRequired || updateAwaitingRestart ? INSTALLER_DOCTOR_COMMAND : null,
+      recommendedFix: registryVerificationAction
+        || (updateAwaitingRestart ? INSTALLER_RESTART_INSTRUCTION : null)
+        || mcpProcesses.exact_fix || mcpConfigurations.exact_fix || configDiagnostics.npm_token.recommended_fix || (!options.apiKey
         ? envHints.length
           ? `MARROW_API_KEY was found in a likely env file at ${envHints[0]}. Load that key from trusted secret storage, export only MARROW_API_KEY, then run npx @getmarrow/install --repair.`
           : 'Set MARROW_API_KEY, then run npx @getmarrow/install --repair.'
@@ -3038,11 +3490,15 @@ async function install(options) {
       ...(options.keyFromArg
         ? ['Avoid --key in shared shells because command-line arguments can be visible in process listings. Prefer MARROW_API_KEY in your environment or secret manager.']
         : []),
-      ...(!mcpProcesses.healthy
-        ? ['Stale, mixed, or version-unknown Marrow MCP clients are active. Run the exact repair command, then restart every owning harness.']
+      ...(mcpProcesses.ahead_unverified
+        ? ['Registry-unverified ahead Marrow MCP clients are active. Automatic repair is suppressed; run the exact registry verification action before owner-directed replacement.']
+        : !mcpProcesses.healthy && !options.update && !options.doctor
+        ? [`Stale, mixed, or version-unknown Marrow MCP clients are active. Run ${INSTALLER_UPDATE_COMMAND}; the installer will report the one required restart and later doctor verification.`]
         : []),
-      ...(!mcpConfigurations.healthy
-        ? ['Stale, mixed, or version-unknown Marrow MCP versions remain in owner configuration. Repair each owning workspace and restart its harness.']
+      ...(mcpConfigurations.ahead_unverified || changes.some((change) => change.automatic_repair_suppressed)
+        ? ['Registry-unverified ahead Marrow MCP configuration was preserved. It was not copied into other managed targets, and automatic repair is suppressed for that surface.']
+        : !mcpConfigurations.healthy && !options.update && !options.doctor
+        ? [`Stale, mixed, or version-unknown Marrow MCP versions remain in the detected workspace. Run ${INSTALLER_UPDATE_COMMAND} once to synchronize its managed surfaces.`]
         : []),
     ],
   };
@@ -3093,6 +3549,7 @@ module.exports = {
   GROK_NATIVE_HOOK_MATCHER,
   printReport,
   buildMcpToolProfileReport,
+  resolveMcpTargetVersion,
   resolveToolProfile,
   PRIMARY_TOOL_NAMES,
   ADAPTER_PROVENANCE,