@getmarrow/install 0.1.53 → 0.1.55

package/README.md

@@ -64,6 +64,12 @@ export MARROW_API_KEY=mrw_live_...
 
 The bare command is the default-on path: it detects and byte-idempotently writes managed configuration, runs the authenticated activation self-test, and starts the supported persistent controller. The key stays process-only and is never written to generated configuration or controller state. Use `--dry-run` for a non-writing preview, `doctor` for a read-only health check, or `--no-controller` to install and self-test without starting the controller. The explicit `activate` command remains equivalent and supported.
 
+### MCP tool profiles
+
+Ordinary setup leaves `MARROW_TOOL_PROFILE` unset, which selects the documented 17-tool `primary` surface. Set `MARROW_TOOL_PROFILE=core` only for the legacy seven-tool minimal surface, or `MARROW_TOOL_PROFILE=full` for the complete advanced/legacy catalog. Explicit `primary`, `core`, and `full` values are accepted; any other value fails with an exact bounded repair and never falls back to a broader profile.
+
+Tool visibility is not authorization. Every visible call still reaches Marrow's backend authentication, tenant, key-permission, plan, proof, and policy enforcement. `doctor --self-test` reports the configured and effective profile, the expected visible count, reloaded MCP visible names/count, and non-authorizing backend entitlement/upgrade projection. Until the owning harness restarts and matching MCP status is observed, actual visibility stays unavailable and the profile remains not-live. The self-test reads backend availability status; it does not invoke paid write tools to discover access.
+
 ## Keeping Marrow Current
 
 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.
@@ -93,7 +99,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.53
+## 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`.
+
+## Previous: v0.1.53
 
 v0.1.53 pins the native-gate MCP candidate `3.9.75` and reconciles only Marrow-owned native hook surfaces. Codex uses `.codex/hooks.json`; Cursor and Composer use `.cursor/hooks.json`; Cline uses bounded executables under `.clinerules/hooks/`; Windsurf uses `.windsurf/hooks.json`; Gemini CLI receives named BeforeTool, AfterTool, and AfterAgent groups in `.gemini/settings.json`; Grok receives trusted global hooks in `~/.grok/hooks/marrow.json`. Grok PreToolUse validates strict private allow/deny JSON and fails closed with exit `2` when the child cannot provide an exact decision; PostToolUse/PostToolUseFailure emit compact results; one nonblocking Stop hook closes the turn with no duplicate SessionEnd hook. Grok hooks remain user-toggleable, so restart plus `/hooks` inspection is required and configuration never proves observed coverage.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/install",
-  "version": "0.1.53",
+  "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,8 +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.75';
-const MCP_ADAPTER_SOURCE_SHA = '7548a7ae2d7e95bb16c62470da41af06cb62c5c1';
+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`;
@@ -21,8 +22,8 @@ const ADAPTER_PROVENANCE = Object.freeze({
     package: '@getmarrow/mcp',
     version: MCP_ADAPTER_VERSION,
     source_sha: MCP_ADAPTER_SOURCE_SHA,
-    integrity: null,
-    integrity_state: 'registry_unavailable_until_publish',
+    integrity: MCP_ADAPTER_INTEGRITY,
+    integrity_state: 'sealed_local_candidate',
   }),
   sdk: Object.freeze({
     package: '@getmarrow/sdk',
@@ -30,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`;
@@ -91,6 +270,28 @@ const GEMINI_HOOK_TIMEOUT_MS = 5000;
 const GEMINI_CLOSEOUT_TIMEOUT_MS = 3000;
 const NATIVE_EXPECTED_HOOKS = ['prompt', 'pre_action', 'action_result', 'session_end'];
 const SOURCE_CLIENTS = new Set(['claude-code', 'cursor', 'composer', 'windsurf', 'openclaw', 'codex', 'gemini', 'grok', 'deepseek', 'qwen', 'kimi', 'minimax', 'cline', 'opencode', 'hermes', 'glm', 'mcp', 'ci', 'custom', 'unknown']);
+const TOOL_PROFILES = new Set(['primary', 'core', 'full']);
+const TOOL_PROFILE_EXPECTED_COUNTS = Object.freeze({ primary: 17, core: 7, full: null });
+const TOOL_PROFILE_EXACT_FIX = 'Unset MARROW_TOOL_PROFILE to use primary, or set MARROW_TOOL_PROFILE=core or MARROW_TOOL_PROFILE=full, then restart the owning harness and run npx @getmarrow/install@latest doctor --self-test.';
+const PRIMARY_TOOL_NAMES = Object.freeze([
+  'marrow_agent_runtime',
+  'marrow_arbitrate',
+  'marrow_coordinate',
+  'marrow_replay_compare',
+  'marrow_decision_brief',
+  'marrow_think',
+  'marrow_commit',
+  'marrow_workflow_gate',
+  'marrow_completion_contracts',
+  'marrow_evaluate_completion_contract',
+  'marrow_agent_status',
+  'marrow_value_report',
+  'marrow_buyer_proof',
+  'marrow_governance_timeline',
+  'marrow_decision_trace',
+  'marrow_fleet_lessons',
+  'marrow_model_usage',
+]);
 const HARNESS_CAPABILITY_REGISTRY = Object.freeze([
   { client: 'claude-code', capability_level: 'native_hooks', automatic: ['prompt', 'pre_action', 'action_result', 'session_end'], install_surface: 'mcp' },
   { client: 'cursor', capability_level: 'native_hooks', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'mcp' },
@@ -118,6 +319,148 @@ function explicitMcpVersion(command) {
   return match ? match[1] : null;
 }
 
+function resolveToolProfile(value) {
+  const structured = value !== null && typeof value === 'object' && !Array.isArray(value);
+  const candidate = structured
+    ? value.configured_profile
+    : value;
+  const absent = !structured && candidate === undefined;
+  const structuredUnset = structured && candidate === 'unset';
+  const configuredProfile = absent || structuredUnset
+    ? 'unset'
+    : candidate;
+  if (!absent && !structuredUnset && !TOOL_PROFILES.has(configuredProfile)) {
+    throw new Error(`Invalid MARROW_TOOL_PROFILE. ${TOOL_PROFILE_EXACT_FIX}`);
+  }
+  const effectiveProfile = configuredProfile === 'unset' ? 'primary' : configuredProfile;
+  return {
+    configured_profile: configuredProfile,
+    effective_profile: effectiveProfile,
+    expected_visible_count: TOOL_PROFILE_EXPECTED_COUNTS[effectiveProfile],
+  };
+}
+
+function normalizePrimaryToolAvailability(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.profile !== 'primary') return null;
+  const evidence = value.entitlement_evidence;
+  const counts = value.counts;
+  const tools = Array.isArray(value.tools) ? value.tools : [];
+  if (!evidence || typeof evidence !== 'object' || evidence.authorizing !== false) return null;
+  if (!['available', 'unavailable'].includes(evidence.state)) return null;
+  if (!counts || counts.total !== 17 || !Number.isInteger(counts.entitled) || !Number.isInteger(counts.upgrade_required)) return null;
+  if (counts.entitled + counts.upgrade_required !== counts.total || tools.length !== counts.total) return null;
+  const normalizedTools = [];
+  const seen = new Set();
+  for (const tool of tools) {
+    if (!tool || typeof tool !== 'object' || !PRIMARY_TOOL_NAMES.includes(tool.name) || seen.has(tool.name)) return null;
+    if (!['entitled', 'upgrade_required'].includes(tool.state) || typeof tool.always_available !== 'boolean') return null;
+    seen.add(tool.name);
+    normalizedTools.push({
+      name: tool.name,
+      state: tool.state,
+      always_available: tool.always_available,
+      plan_feature: typeof tool.plan_feature === 'string' ? tool.plan_feature : null,
+      minimum_plan: typeof tool.minimum_plan === 'string' ? tool.minimum_plan : null,
+      owner_management_url: typeof tool.owner_management_url === 'string' ? tool.owner_management_url : '',
+    });
+  }
+  if (PRIMARY_TOOL_NAMES.some((name) => !seen.has(name))) return null;
+  const entitled = normalizedTools.filter((tool) => tool.state === 'entitled').length;
+  const upgradeRequired = normalizedTools.filter((tool) => tool.state === 'upgrade_required').length;
+  if (entitled !== counts.entitled || upgradeRequired !== counts.upgrade_required) return null;
+  return {
+    profile: 'primary',
+    current_plan: typeof value.current_plan === 'string' ? value.current_plan : null,
+    owner_management_url: typeof value.owner_management_url === 'string' ? value.owner_management_url : '',
+    entitlement_evidence: {
+      state: evidence.state,
+      source: typeof evidence.source === 'string' ? evidence.source : 'entitlement_read_unavailable',
+      authoritative: evidence.authoritative === true,
+      authorizing: false,
+    },
+    counts: { total: 17, entitled, upgrade_required: upgradeRequired },
+    tools: normalizedTools,
+  };
+}
+
+function backendEntitlementProjection(statusProfile, contextProjection) {
+  const freshProjection = normalizePrimaryToolAvailability(contextProjection);
+  if (freshProjection) {
+    return {
+      evidence_state: freshProjection.entitlement_evidence.state,
+      source: 'authenticated_backend',
+      authorizes_calls: false,
+      primary_tool_availability: freshProjection,
+    };
+  }
+  const envelope = statusProfile?.backend_entitlement_projection;
+  const projected = normalizePrimaryToolAvailability(envelope?.primary_tool_availability);
+  const source = ['authenticated_backend', 'cached_or_stale_status', 'backend_projection_not_provided'].includes(envelope?.source)
+    ? envelope.source
+    : 'backend_projection_not_provided';
+  const available = envelope?.authorizes_calls === false
+    && envelope?.evidence_state === 'available'
+    && source === 'authenticated_backend'
+    && projected?.entitlement_evidence.state === 'available';
+  return {
+    evidence_state: available ? 'available' : 'unavailable',
+    source,
+    authorizes_calls: false,
+    primary_tool_availability: projected,
+  };
+}
+
+function buildMcpToolProfileReport(value, statusProfile = null, contextProjection = null, forceReload = false) {
+  const expected = resolveToolProfile(value);
+  const reportedNames = Array.isArray(statusProfile?.visible_tool_names)
+    ? statusProfile.visible_tool_names.filter((name) => typeof name === 'string')
+    : [];
+  const reportedCount = statusProfile?.visible_tool_count;
+  const reportedConfigured = statusProfile?.configured_profile;
+  const reportedEffective = statusProfile?.effective_profile;
+  const uniqueNames = new Set(reportedNames);
+  const profileIdentityMatches = reportedConfigured === expected.configured_profile
+    && reportedEffective === expected.effective_profile;
+  const reportedCatalogIsConsistent = Number.isInteger(reportedCount)
+    && reportedCount >= 0
+    && reportedNames.length === reportedCount
+    && uniqueNames.size === reportedCount;
+  const expectedCount = expected.effective_profile === 'full'
+    && profileIdentityMatches
+    && reportedCatalogIsConsistent
+    ? reportedCount
+    : expected.expected_visible_count;
+  const expectedPrimaryNames = expected.effective_profile !== 'primary'
+    || (reportedNames.length === PRIMARY_TOOL_NAMES.length
+      && PRIMARY_TOOL_NAMES.every((name) => uniqueNames.has(name)));
+  const visibilityLive = !forceReload
+    && profileIdentityMatches
+    && statusProfile?.local_visibility_grants_entitlement === false
+    && reportedCatalogIsConsistent
+    && reportedCount === expectedCount
+    && expectedPrimaryNames;
+  return {
+    configured_profile: expected.configured_profile,
+    effective_profile: expected.effective_profile,
+    expected_visible_count: expectedCount,
+    visible_tool_count: visibilityLive ? reportedCount : null,
+    actual_visible_count: visibilityLive ? reportedCount : null,
+    visible_tool_names: visibilityLive ? reportedNames : [],
+    local_visibility_grants_entitlement: false,
+    visibility_live: visibilityLive,
+    reload_required: !visibilityLive,
+    reported_configured_profile: typeof reportedConfigured === 'string' ? reportedConfigured : null,
+    reported_effective_profile: typeof reportedEffective === 'string' ? reportedEffective : null,
+    backend_entitlement_projection: backendEntitlementProjection(statusProfile, contextProjection),
+  };
+}
+
+function initialToolProfileReport(value) {
+  return {
+    ...buildMcpToolProfileReport(value),
+  };
+}
+
 function readMcpPackageVersion(packageRoot) {
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
@@ -201,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,
   };
 }
@@ -257,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',
   };
 }
@@ -307,7 +676,7 @@ function sourceClient() {
   return aliases[raw] || (SOURCE_CLIENTS.has(raw) ? raw : 'custom');
 }
 
-function parseArgs(argv) {
+function parseArgs(argv, env = process.env) {
   const options = {
     cwd: process.cwd(),
     yes: false,
@@ -315,9 +684,10 @@ function parseArgs(argv) {
     doctor: false,
     repair: false,
     mode: 'auto',
-    apiKey: process.env.MARROW_API_KEY || '',
-    baseUrl: process.env.MARROW_BASE_URL || DEFAULT_BASE_URL,
-    agentId: process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID || '',
+    apiKey: env.MARROW_API_KEY || '',
+    baseUrl: env.MARROW_BASE_URL || DEFAULT_BASE_URL,
+    agentId: env.MARROW_FLEET_AGENT_ID || env.MARROW_AGENT_ID || '',
+    toolProfile: resolveToolProfile(env.MARROW_TOOL_PROFILE),
     selfTest: true,
     selfTestExplicitlyDisabled: false,
     json: false,
@@ -409,6 +779,7 @@ function parseArgs(argv) {
   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;
 }
@@ -439,6 +810,10 @@ Options:
   --agent-id <id>    Agent/fleet id for self-test headers
   --no-controller    Do not start the local background controller during install/repair
   --no-self-test     Skip API smoke/self-test
+
+Environment:
+  MARROW_TOOL_PROFILE  Leave unset for primary (17 tools), or explicitly set primary, core, or full.
+                       Visibility never grants entitlement; backend plans and permissions authorize calls.
 `;
 }
 
@@ -727,6 +1102,7 @@ function passiveInstructions() {
 Marrow should run passively after install:
 
 - Use MCP plus these instructions in every workspace: \`npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp setup\`.
+- Leave \`MARROW_TOOL_PROFILE\` unset for the 17-tool primary surface. Set \`MARROW_TOOL_PROFILE=core\` or \`MARROW_TOOL_PROFILE=full\` only as an explicit opt-in; backend plans and permissions still enforce access to every visible tool.
 - Use SDK passive runtime in owned Node processes: \`createPassiveRuntime().install()\`.
 - Native Claude hooks install only when \`.claude\` is present. Codex native hooks install into \`.codex/hooks.json\`; Cursor and Composer use \`.cursor/hooks.json\`; Cline uses non-overwriting executable files under \`.clinerules/hooks/\`; Windsurf uses \`.windsurf/hooks.json\`; Gemini CLI uses \`.gemini/settings.json\`; Grok uses trusted global \`~/.grok/hooks/marrow.json\`. Restart the host, enable/review hooks, disable Windsurf Restricted Mode where native hooks are required, and trust the workspace before claiming runtime coverage. The governed wrapper remains an explicit bounded fallback. Hermes, OpenClaw, and custom hosts need a bounded event adapter.
 - Keep passive token/model usage proof enabled. Empty savings stay zero until observed model usage lands. Do not invent token, cost, or time savings.
@@ -790,6 +1166,7 @@ function envExample(options = {}) {
 MARROW_BASE_URL=${JSON.stringify(baseUrl)}
 MARROW_FLEET_AGENT_ID=${JSON.stringify(agentId)}
 MARROW_CLIENT=${JSON.stringify(client)}
+# MARROW_TOOL_PROFILE is intentionally unset: ordinary setup uses primary. Set core or full only as an explicit opt-in.
 MARROW_ENFORCEMENT_MODE=auto
 MARROW_PASSIVE_BRIEF=auto
 MARROW_PASSIVE_VALUE_REPORT=true
@@ -1431,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;
@@ -1444,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'
@@ -1524,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)
@@ -1565,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,
@@ -1622,13 +2003,18 @@ function upsertMcpServerConfig(filePath, options = {}) {
   const servers = config.mcpServers && typeof config.mcpServers === 'object' && !Array.isArray(config.mcpServers)
     ? config.mcpServers
     : {};
+  const existingProfile = resolveToolProfile(servers.marrow?.env?.MARROW_TOOL_PROFILE).configured_profile;
+  const requestedProfile = resolveToolProfile(options.toolProfile).configured_profile;
+  const configuredProfile = requestedProfile === 'unset' ? existingProfile : requestedProfile;
+  const env = {
+    MARROW_BASE_URL: baseUrl,
+    MARROW_FLEET_AGENT_ID: agentId,
+  };
+  if (configuredProfile !== 'unset') env.MARROW_TOOL_PROFILE = configuredProfile;
   servers.marrow = {
     command: 'npx',
     args: ['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp'],
-    env: {
-      MARROW_BASE_URL: baseUrl,
-      MARROW_FLEET_AGENT_ID: agentId,
-    },
+    env,
   };
   config.mcpServers = servers;
   return JSON.stringify(config, null, 2) + '\n';
@@ -1849,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;
@@ -1876,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) {
@@ -1884,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) {
@@ -1893,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.',
         });
@@ -1904,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) {
@@ -1912,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 }),
+      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 }),
+        transform: (filePath) => retarget(upsertMcpServerConfig(filePath, { agentId, baseUrl, toolProfile: options.toolProfile })),
       });
     }
   }
@@ -1942,7 +2330,7 @@ function buildPlan(detection, options) {
       type: 'md-block',
       path: detection.paths.agentsMd,
       label: 'Agent instructions',
-      block: passiveInstructions(),
+      block: retarget(passiveInstructions()),
     });
   }
 
@@ -1951,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) {
@@ -2021,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 {
@@ -2046,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) {
@@ -2106,12 +2523,14 @@ function runtimeGateVerified(runtime) {
 }
 
 async function runSelfTest(options) {
-  if (!options.selfTest) return { skipped: true, reason: 'disabled' };
+  const initialProfile = initialToolProfileReport(options.toolProfile);
+  if (!options.selfTest) return { skipped: true, reason: 'disabled', mcp_tool_profile: initialProfile };
   if (!options.apiKey) {
     return {
       skipped: true,
       reason: 'missing MARROW_API_KEY',
       exact_fix: 'export MARROW_API_KEY=mrw_live_... && npx @getmarrow/install --repair',
+      mcp_tool_profile: initialProfile,
     };
   }
 
@@ -2124,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;
 
@@ -2157,6 +2576,14 @@ async function runSelfTest(options) {
   });
 
   const status = await requestJson(`${baseUrl}/v1/agent/status`, { headers });
+  const context = await requestJson(`${baseUrl}/v1/agent/context`, { headers })
+    .catch(() => null);
+  const toolProfile = buildMcpToolProfileReport(
+    options.toolProfile,
+    status.mcp_tool_profile,
+    context?.primary_tool_availability,
+    Boolean(options.activation),
+  );
   const runtime = await requestJson(`${baseUrl}/v1/agent/runtime`, {
     method: 'POST',
     headers,
@@ -2291,6 +2718,7 @@ async function runSelfTest(options) {
   }
   return {
     skipped: false,
+    mcp_tool_profile: toolProfile,
     decision_id: decisionId,
     active: Boolean(status.enabled ?? status.ok),
     health: status.health || null,
@@ -2480,11 +2908,34 @@ 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');
+  const toolProfile = report.selfTest.mcp_tool_profile || report.toolProfile;
+  if (toolProfile) {
+    process.stdout.write(`- configured tool profile: ${toolProfile.configured_profile}\n`);
+    process.stdout.write(`- effective tool profile: ${toolProfile.effective_profile}\n`);
+    process.stdout.write(`- expected visible tools: ${toolProfile.expected_visible_count == null ? 'complete catalog (awaiting reloaded MCP count)' : toolProfile.expected_visible_count}\n`);
+    process.stdout.write(`- actual visible tools: ${toolProfile.actual_visible_count == null ? 'unavailable until process reload' : toolProfile.actual_visible_count}\n`);
+    process.stdout.write(`- visible tool names: ${toolProfile.visibility_live ? toolProfile.visible_tool_names.join(', ') : 'unavailable until process reload'}\n`);
+    process.stdout.write(`- profile live: ${toolProfile.visibility_live ? 'yes' : 'no'}\n`);
+    const projection = toolProfile.backend_entitlement_projection;
+    const availability = projection?.primary_tool_availability;
+    if (projection?.evidence_state === 'available' && availability?.entitlement_evidence?.state === 'available') {
+      process.stdout.write(`- backend-projected entitled tools: ${availability.counts.entitled}\n`);
+      process.stdout.write(`- backend-projected upgrade-required tools: ${availability.counts.upgrade_required}\n`);
+      process.stdout.write(`- backend projection source: ${projection.source}; authorizes calls: no\n`);
+    } else {
+      process.stdout.write(`- backend-projected entitlements: unavailable (source: ${projection?.source || 'backend_projection_not_provided'}; non-authorizing)\n`);
+    }
+  }
   if (report.selfTest.skipped) {
     process.stdout.write(`- skipped: ${report.selfTest.reason}\n`);
     if (report.selfTest.exact_fix) process.stdout.write(`- exact fix: ${report.selfTest.exact_fix}\n`);
@@ -2613,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`);
     }
@@ -2620,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`);
@@ -2650,14 +3105,30 @@ async function install(options) {
   if (options.repair && options.yes !== true && !options.dryRun && !options.doctor) {
     throw new Error('repair requires explicit write authorization (--yes)');
   }
+  options.toolProfile = resolveToolProfile(options.toolProfile === undefined
+    ? process.env.MARROW_TOOL_PROFILE
+    : options.toolProfile);
   const detection = detectEnvironment(options.cwd);
   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,
@@ -2688,19 +3159,66 @@ 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);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (options.activate) throw new Error(`Marrow activation failed: ${message}`);
-    selfTest = { skipped: false, active: false, error: message };
+    selfTest = {
+      skipped: false,
+      active: false,
+      error: message,
+      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);
+  if (harnessReload.required && selfTest.mcp_tool_profile) {
+    selfTest.mcp_tool_profile = {
+      ...selfTest.mcp_tool_profile,
+      visible_tool_count: null,
+      actual_visible_count: null,
+      visible_tool_names: [],
+      visibility_live: false,
+      reload_required: true,
+    };
+  }
   const changedConfig = changes.some((change) => change.applied) || configRepairs.some((repair) => repair.changed);
   const selfTestPassed = Boolean(!selfTest.skipped && selfTest.active && !selfTest.error);
   const controllerPlatform = options.controllerPlatform || process.platform;
@@ -2747,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}` : ''}.`
@@ -2759,9 +3280,10 @@ 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),
     detected: {
       node: detection.node,
       python: detection.python,
@@ -2784,7 +3306,7 @@ async function install(options) {
       receipt: selfTest.activation_receipt || null,
       profile,
     },
-    harnessReload: harnessReloadPlan(detection, changes),
+    harnessReload,
     firstCapture: firstCapturePath(detection, options.agentId),
     changes,
     doctor: {
@@ -2794,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.'
@@ -2812,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.']
         : []),
     ],
@@ -2866,6 +3395,10 @@ module.exports = {
   GROK_SESSION_END_HOOK_COMMAND,
   GROK_NATIVE_HOOK_MATCHER,
   printReport,
+  buildMcpToolProfileReport,
+  resolveMcpTargetVersion,
+  resolveToolProfile,
+  PRIMARY_TOOL_NAMES,
   ADAPTER_PROVENANCE,
   HARNESS_CAPABILITY_REGISTRY,
   defaultHarnessInstallMatrix,