@getmarrow/install 0.1.54 → 0.1.55

package/README.md

@@ -99,7 +99,11 @@ 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.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.55",
   "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.79';
+const MCP_ADAPTER_SOURCE_SHA = '11f00049043d0aba90704ecbf69f32d2278a4573';
+const MCP_ADAPTER_INTEGRITY = 'sha512-LWfBWGot2PnluRbS5Hm3WA2DJCIkf2qVJfthGcCaZx8AoRXFKeg1pUO3rMVFqrOIWOB4nYZw6UgSL+7hDY1wuA==';
 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,184 @@ 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 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 unverifiedAheadMcpVersions(versions, targetVersion = MCP_ADAPTER_VERSION) {
+  if (!compatibleMcpTargetVersion(targetVersion)) return [];
+  return [...new Set((Array.isArray(versions) ? versions : [])
+    .filter((version) => compatibleMcpTargetVersion(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,24 +544,37 @@ 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;
+  const repairCommand = `npx -y --package=@getmarrow/mcp@${expectedVersion} marrow-mcp setup`;
   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,
+    automatic_repair_suppressed: automaticRepairSuppressed,
+    registry_verification_required: aheadUnverified,
+    exact_fix: automaticRepairSuppressed
+      ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
+      : needsRepair ? repairCommand : null,
+    restart_required: needsRepair && !automaticRepairSuppressed,
+    restart_instruction: needsRepair && !automaticRepairSuppressed
+      ? 'Restart every owning harness to replace its active Marrow MCP process.'
+      : null,
     verification_command: needsRepair ? 'npx -y @getmarrow/install@latest doctor --self-test' : null,
   };
 }
@@ -422,20 +613,33 @@ 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.`,
+    automatic_repair_suppressed: aheadUnverified,
+    registry_verification_required: aheadUnverified,
+    exact_fix: healthy
+      ? null
+      : aheadUnverified
+        ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
+        : `Run npx -y --package=@getmarrow/mcp@${expectedVersion} marrow-mcp setup in each owning workspace, update its MCP launch to npx -y --package=@getmarrow/mcp@${expectedVersion} marrow-mcp, then restart that harness.`,
     verification_command: healthy ? null : 'npx -y @getmarrow/install@latest doctor --self-test',
   };
 }
@@ -575,6 +779,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;
 }
@@ -1603,8 +1808,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 +1825,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 +1905,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 +1946,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 +2235,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 +2264,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 +2272,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 +2281,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 +2292,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 +2300,27 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.geminiSettings,
         label: 'Gemini CLI native hooks',
-        transform: upsertGeminiHooks,
+        transform: (filePath) => retarget(upsertGeminiHooks(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 +2330,7 @@ function buildPlan(detection, options) {
       type: 'md-block',
       path: detection.paths.agentsMd,
       label: 'Agent instructions',
-      block: passiveInstructions(),
+      block: retarget(passiveInstructions()),
     });
   }
 
@@ -2128,11 +2339,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) {
@@ -2198,9 +2409,16 @@ function applyPlan(plan, options) {
   const prepared = plan.writes.map((write) => {
     const fileExists = exists(write.path);
     const before = safeRead(write.path);
+    const aheadUnverifiedVersions = unverifiedAheadMcpVersions(
+      mcpVersionsInText(before),
+      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,21 +2441,43 @@ 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) {
@@ -2303,7 +2543,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 +2908,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');
@@ -2819,6 +3064,8 @@ 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.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 (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`);
     }
@@ -2826,6 +3073,8 @@ function printReport(report) {
       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`);
     process.stdout.write(`- live health: ${report.doctor.healthCommand}\n`);
@@ -2863,10 +3112,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 +3159,33 @@ 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;
+  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,6 +3199,12 @@ 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');
   }
@@ -2972,7 +3265,10 @@ async function install(options) {
       attempted: true,
       fixedConfig: changedConfig,
       selfTestPassed,
-      message: selfTestPassed
+      automaticMcpRepairSuppressed,
+      message: automaticMcpRepairSuppressed
+        ? registryVerificationAction
+        : 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}` : ''}.`
@@ -2984,7 +3280,7 @@ async function install(options) {
 
   return {
     root: detection.root,
-    adapterProvenance: ADAPTER_PROVENANCE,
+    adapterProvenance: adapterProvenanceForMcpTarget(mcpTarget),
     mode: plan.mode,
     writeMode,
     toolProfile: selfTest.mcp_tool_profile || initialToolProfileReport(options.toolProfile),
@@ -3020,7 +3316,10 @@ async function install(options) {
       missingHooks: changes.filter((change) => change.changed).map((change) => change.label),
       mcpProcesses,
       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,
+      recommendedFix: registryVerificationAction || 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,10 +3337,14 @@ 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
+      ...(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
         ? ['Stale, mixed, or version-unknown Marrow MCP clients are active. Run the exact repair command, then restart every owning harness.']
         : []),
-      ...(!mcpConfigurations.healthy
+      ...(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
         ? ['Stale, mixed, or version-unknown Marrow MCP versions remain in owner configuration. Repair each owning workspace and restart its harness.']
         : []),
     ],
@@ -3093,6 +3396,7 @@ module.exports = {
   GROK_NATIVE_HOOK_MATCHER,
   printReport,
   buildMcpToolProfileReport,
+  resolveMcpTargetVersion,
   resolveToolProfile,
   PRIMARY_TOOL_NAMES,
   ADAPTER_PROVENANCE,