@getmarrow/install 0.1.55 → 0.1.57

package/README.md

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

package/package.json

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

package/src/installer.js

@@ -10,11 +10,11 @@ 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.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 MCP_ADAPTER_VERSION = '3.9.88';
+const MCP_ADAPTER_SOURCE_SHA = '2385f0554dd9455e6a7d2c0396058710ab56611a';
+const MCP_ADAPTER_INTEGRITY = 'sha512-1WQtVU8oT1XLGFa9aINm9Ypn/xhNh/mPLpK2bziPIxRURsAGrs8TAfb23JL7HXDcmpXFgMLd8R6gmltVbBbHIg==';
+const SDK_ADAPTER_VERSION = '3.7.63';
+const SDK_ADAPTER_INTEGRITY = 'sha512-5BiV1P0J1NMVdgjqxqULfM+zGrTjHBuWm1amKZWba4yW6C3t10VlhIlj/A+4YKbKqvyZe8gXgUwW+VrYDbVQrQ==';
 const SDK_ADAPTER_TARBALL = `https://registry.npmjs.org/@getmarrow/sdk/-/sdk-${SDK_ADAPTER_VERSION}.tgz`;
 const MCP_PACKAGE_SPEC = `@getmarrow/mcp@${MCP_ADAPTER_VERSION}`;
 const ADAPTER_PROVENANCE = Object.freeze({
@@ -23,7 +23,7 @@ const ADAPTER_PROVENANCE = Object.freeze({
     version: MCP_ADAPTER_VERSION,
     source_sha: MCP_ADAPTER_SOURCE_SHA,
     integrity: MCP_ADAPTER_INTEGRITY,
-    integrity_state: 'sealed_local_candidate',
+    integrity_state: 'verified_npm_registry_metadata',
   }),
   sdk: Object.freeze({
     package: '@getmarrow/sdk',
@@ -33,6 +33,9 @@ const ADAPTER_PROVENANCE = Object.freeze({
 });
 const MCP_REGISTRY_LATEST_URL = 'https://registry.npmjs.org/%40getmarrow%2Fmcp/latest';
 const MCP_REGISTRY_VERIFICATION_COMMAND = 'npm view @getmarrow/mcp@latest name version dist.integrity dist.tarball --json --registry=https://registry.npmjs.org';
+const INSTALLER_UPDATE_COMMAND = 'npx -y @getmarrow/install@latest update';
+const INSTALLER_DOCTOR_COMMAND = 'npx -y @getmarrow/install@latest doctor --self-test';
+const INSTALLER_RESTART_INSTRUCTION = 'After the update completes, restart the detected owning harnesses once. Running Marrow MCP processes remain unchanged until that restart.';
 const MCP_STABLE_VERSION_RE = /^(\d{1,6})\.(\d{1,6})\.(\d{1,9})$/;
 const SHA512_INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
 const VERIFIED_MCP_EXECUTABLE_TARGET = Symbol('verified_mcp_executable_target');
@@ -65,6 +68,13 @@ function compareMcpVersions(left, right) {
   return 0;
 }
 
+function declaredStableSdkLowerBound(spec) {
+  if (typeof spec !== 'string') return null;
+  const match = spec.trim().match(/^(v|\^|~|>=|>)?(\d{1,6}\.\d{1,6}\.\d{1,9})$/);
+  if (!match || !parsedStableMcpVersion(match[2])) return null;
+  return { version: match[2], exclusive: match[1] === '>' };
+}
+
 function compatibleMcpTargetVersion(value) {
   const candidate = parsedStableMcpVersion(value);
   const sealed = parsedStableMcpVersion(MCP_ADAPTER_VERSION);
@@ -79,10 +89,19 @@ function mcpVersionsInText(value) {
     .map((match) => match[1]);
 }
 
+function marrowManagedBlockInText(value) {
+  const content = String(value || '');
+  const start = content.indexOf(MARROW_BLOCK_START);
+  if (start < 0) return '';
+  const end = content.indexOf(MARROW_BLOCK_END, start + MARROW_BLOCK_START.length);
+  if (end < 0) return '';
+  return content.slice(start, end + MARROW_BLOCK_END.length);
+}
+
 function unverifiedAheadMcpVersions(versions, targetVersion = MCP_ADAPTER_VERSION) {
-  if (!compatibleMcpTargetVersion(targetVersion)) return [];
+  if (!parsedStableMcpVersion(targetVersion)) return [];
   return [...new Set((Array.isArray(versions) ? versions : [])
-    .filter((version) => compatibleMcpTargetVersion(version)
+    .filter((version) => parsedStableMcpVersion(version)
       && compareMcpVersions(version, targetVersion) > 0))].sort((left, right) => compareMcpVersions(left, right));
 }
 
@@ -554,7 +573,6 @@ function inspectMcpProcesses(options = {}) {
   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: expectedVersion,
@@ -570,21 +588,30 @@ function inspectMcpProcesses(options = {}) {
     registry_verification_required: aheadUnverified,
     exact_fix: automaticRepairSuppressed
       ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
-      : needsRepair ? repairCommand : null,
+      : needsRepair ? INSTALLER_UPDATE_COMMAND : null,
     restart_required: needsRepair && !automaticRepairSuppressed,
     restart_instruction: needsRepair && !automaticRepairSuppressed
-      ? 'Restart every owning harness to replace its active Marrow MCP process.'
+      ? INSTALLER_RESTART_INSTRUCTION
       : null,
-    verification_command: needsRepair ? 'npx -y @getmarrow/install@latest doctor --self-test' : null,
+    verification_command: needsRepair && !automaticRepairSuppressed ? INSTALLER_DOCTOR_COMMAND : null,
   };
 }
 
 function inspectMcpConfigurations(detection, options = {}) {
   const home = options.home || process.env.HOME || process.env.USERPROFILE || os.homedir();
   const configuredPaths = Array.isArray(options.paths) ? options.paths : [
+    detection?.paths?.agentsMd,
+    detection?.paths?.mcpJson,
     detection?.paths?.claudeSettings,
+    detection?.paths?.codexHooks,
+    detection?.paths?.cursorHooks,
     detection?.paths?.cursorMcp,
-    detection?.paths?.mcpJson,
+    detection?.paths?.clinePreToolUseHook,
+    detection?.paths?.clinePostToolUseHook,
+    detection?.paths?.clineTaskCancelHook,
+    detection?.paths?.windsurfHooks,
+    detection?.paths?.geminiSettings,
+    detection?.paths?.grokHooks,
     path.join(home, '.claude', 'settings.json'),
     path.join(home, '.claude.json'),
     path.join(home, '.cursor', 'mcp.json'),
@@ -601,9 +628,11 @@ function inspectMcpConfigurations(detection, options = {}) {
       if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024) continue;
       filesChecked += 1;
       const raw = fs.readFileSync(filePath, 'utf8');
-      const specs = [...raw.matchAll(/@getmarrow\/mcp@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/g)]
-        .map((match) => match[1]);
-      if (/@getmarrow\/mcp(?:@|["'\s])/.test(raw)) {
+      const inspected = path.basename(filePath) === 'AGENTS.md'
+        ? marrowManagedBlockInText(raw)
+        : raw;
+      const specs = mcpVersionsInText(inspected);
+      if (/@getmarrow\/mcp(?:@|["'\s])/.test(inspected)) {
         configurationsFound += 1;
         if (specs.length === 0) unknownVersionConfigurations += 1;
       }
@@ -639,8 +668,10 @@ function inspectMcpConfigurations(detection, options = {}) {
       ? 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',
+        : INSTALLER_UPDATE_COMMAND,
+    restart_required: !healthy && !aheadUnverified,
+    restart_instruction: !healthy && !aheadUnverified ? INSTALLER_RESTART_INSTRUCTION : null,
+    verification_command: !healthy && !aheadUnverified ? INSTALLER_DOCTOR_COMMAND : null,
   };
 }
 
@@ -1691,6 +1722,75 @@ function grokNativeHookFingerprint(settings) {
   })).digest('hex');
 }
 
+function grokMarrowHookSubcommand(command) {
+  const direct = marrowHookSubcommand(command);
+  if (direct) return direct;
+  if (typeof command !== 'string') return null;
+  const guarded = command.match(
+    /@getmarrow\/mcp@[^\s"',]+["'],["']marrow-mcp["'],["']grok-(pre-action-hook)["']/,
+  );
+  return guarded?.[1] || null;
+}
+
+function reconcileGrokHook(settings, eventName, subcommand, command, matcher, timeout) {
+  const original = Array.isArray(settings?.hooks?.[eventName]) ? settings.hooks[eventName] : [];
+  const retained = [];
+  let preferredHandler = null;
+  for (const entry of original) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !Array.isArray(entry.hooks)) {
+      retained.push(entry);
+      continue;
+    }
+    const remaining = [];
+    for (const handler of entry.hooks) {
+      const detected = handler && typeof handler === 'object' && !Array.isArray(handler)
+        && handler.type === 'command' ? grokMarrowHookSubcommand(handler.command) : null;
+      if (detected) {
+        if (detected === subcommand && !preferredHandler) preferredHandler = handler;
+        continue;
+      }
+      remaining.push(handler);
+    }
+    if (remaining.length > 0) retained.push({ ...entry, hooks: remaining });
+  }
+  if (!command) return retained;
+  const canonical = {
+    ...(matcher === undefined ? {} : { matcher }),
+    hooks: [{ ...preferredHandler, type: 'command', command, timeout }],
+  };
+  return [...retained, canonical];
+}
+
+function upsertGrokHooks(settingsPath) {
+  const settings = parseJsonObject(settingsPath);
+  const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+    ? settings.hooks
+    : {};
+  settings.hooks = {
+    ...hooks,
+    UserPromptSubmit: reconcileGrokHook(settings, 'UserPromptSubmit', 'context-hook', GROK_CONTEXT_HOOK_COMMAND, undefined, 5),
+    PreToolUse: reconcileGrokHook(settings, 'PreToolUse', 'pre-action-hook', GROK_PRE_ACTION_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 7),
+    PostToolUse: reconcileGrokHook(settings, 'PostToolUse', 'hook', GROK_ACTION_RESULT_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 5),
+    PostToolUseFailure: reconcileGrokHook(settings, 'PostToolUseFailure', 'hook', GROK_ACTION_RESULT_HOOK_COMMAND, GROK_NATIVE_HOOK_MATCHER, 5),
+    Stop: reconcileGrokHook(settings, 'Stop', 'session-hook', GROK_SESSION_END_HOOK_COMMAND, undefined, 3),
+    SessionEnd: reconcileGrokHook(settings, 'SessionEnd', 'session-hook', null, undefined, 3),
+  };
+  return JSON.stringify(settings, null, 2) + '\n';
+}
+
+function managedGrokHooksFile(filePath) {
+  if (!exists(filePath)) return false;
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) return true;
+    if (stat.size > 2 * 1024 * 1024) return true;
+    return /@getmarrow\/mcp@[^\s"']+[\s\S]{0,4096}marrow-mcp[\s\S]{0,512}grok-(?:context-hook|pre-action-hook|hook|session-hook)/
+      .test(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return true;
+  }
+}
+
 function upsertGeminiHooks(settingsPath) {
   const settings = parseJsonObject(settingsPath);
   const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
@@ -1938,7 +2038,9 @@ function activationProfile(detection, plan, changes, client) {
       ? 'Restart Grok, inspect the installed global hooks with /hooks, and confirm they are enabled. Configuration remains client-self-reported and does not verify observed coverage.'
       : null
     : capabilityLevel === 'sdk_passive_runtime' && !sdkDependency.present
-    ? `${sdkDependency.install_command} && npx @getmarrow/install --repair`
+    ? sdkDependency.install_command
+      ? `${sdkDependency.install_command} && npx @getmarrow/install --repair`
+      : sdkDependency.warning
     : capabilityLevel === 'governed_wrapper'
     ? `npx @getmarrow/install run --agent <agent-id> -- ${client}`
     : client === 'cline' && clineConflicts.length > 0
@@ -2057,10 +2159,12 @@ function inspectSdkDependency(detection) {
     || objectTargetsSdk(packageJson.resolutions)
     || objectTargetsSdk(packageJson.pnpm?.overrides);
   let lockVerified = false;
+  let lockedVersion = null;
   try {
     const lock = JSON.parse(safeRead(path.join(detection.root, 'package-lock.json')) || '{}');
     const rootLock = lock?.packages?.[''];
     const lockedSdk = lock?.packages?.['node_modules/@getmarrow/sdk'];
+    lockedVersion = typeof lockedSdk?.version === 'string' ? lockedSdk.version : null;
     const lockedDeclaration = [
       rootLock?.dependencies,
       rootLock?.devDependencies,
@@ -2090,9 +2194,16 @@ function inspectSdkDependency(detection) {
     installedVersion = null;
     installedName = null;
   }
-  const declarationTrusted = typeof declaredSpec === 'string'
-    && declaredSpec.trim().length > 0
-    && /^[v0-9xX*<>=~^|.\s-]+$/.test(declaredSpec.trim());
+  const declaredLowerBound = declaredStableSdkLowerBound(declaredSpec);
+  const declarationTrusted = declaredLowerBound !== null;
+  const unsupportedDeclaration = declaredSpec !== null && !declarationTrusted;
+  const declaredComparison = declaredLowerBound
+    ? compareMcpVersions(declaredLowerBound.version, SDK_ADAPTER_VERSION) : null;
+  const declaredAhead = declaredComparison !== null
+    && (declaredComparison > 0 || (declaredLowerBound.exclusive && declaredComparison === 0));
+  const aheadVersions = [installedVersion, lockedVersion]
+    .filter((version) => compareMcpVersions(version, SDK_ADAPTER_VERSION) > 0);
+  const aheadUnverified = aheadVersions.length > 0 || declaredAhead;
   const present = declarationTrusted
     && !overrideDetected
     && lockVerified
@@ -2108,8 +2219,15 @@ function inspectSdkDependency(detection) {
     lock_verified: lockVerified,
     installed_name: installedName,
     installed_version: installedVersion,
+    ahead_unverified: aheadUnverified,
     expected_version: SDK_ADAPTER_VERSION,
-    install_command: present ? null : `npm install @getmarrow/sdk@${SDK_ADAPTER_VERSION}`,
+    install_command: present || aheadUnverified || unsupportedDeclaration
+      ? null : `npm install @getmarrow/sdk@${SDK_ADAPTER_VERSION}`,
+    ...(aheadUnverified ? {
+      warning: 'A newer SDK version is configured or installed. Preserve it and verify its exact version and integrity against the official npm registry before changing it.',
+    } : unsupportedDeclaration ? {
+      warning: 'The configured SDK version range is unsupported or ambiguous. Preserve it and verify the intended version against the official npm registry before changing it.',
+    } : {}),
   };
 }
 
@@ -2303,6 +2421,15 @@ function buildPlan(detection, options) {
         transform: (filePath) => retarget(upsertGeminiHooks(filePath)),
       });
     }
+    if (options.update && detection.grok && managedGrokHooksFile(detection.paths.grokHooks)) {
+      writes.push({
+        type: 'json-transform',
+        path: detection.paths.grokHooks,
+        root: path.resolve(detection.paths.grokHooks, '..', '..', '..'),
+        label: 'Grok native hooks',
+        transform: (filePath) => retarget(upsertGrokHooks(filePath)),
+      });
+    }
     writes.push({
       type: 'json-transform',
       path: detection.paths.mcpJson,
@@ -2405,12 +2532,17 @@ function atomicWriteManagedFile(root, targetPath, contents) {
 function applyPlan(plan, options) {
   if (!Array.isArray(plan?.writes) || plan.writes.length === 0) return [];
   const root = path.resolve(plan.root || path.dirname(plan.writes[0].path));
-  for (const write of plan.writes) assertContainedManagedTarget(root, write.path);
+  for (const write of plan.writes) {
+    assertContainedManagedTarget(path.resolve(write.root || root), write.path);
+  }
   const prepared = plan.writes.map((write) => {
     const fileExists = exists(write.path);
     const before = safeRead(write.path);
+    const inspectedBefore = write.type === 'md-block'
+      ? marrowManagedBlockInText(before)
+      : before;
     const aheadUnverifiedVersions = unverifiedAheadMcpVersions(
-      mcpVersionsInText(before),
+      mcpVersionsInText(inspectedBefore),
       plan.mcp_target_version,
     );
     const automaticRepairSuppressed = aheadUnverifiedVersions.length > 0;
@@ -2481,10 +2613,10 @@ function applyPlan(plan, options) {
       ...(hookConflict ? { exact_fix: write.conflict_fix } : {}),
     });
     if (contentChanged && writeApplied) {
-      atomicWriteManagedFile(root, write.path, after);
+      atomicWriteManagedFile(path.resolve(write.root || root), write.path, after);
     }
     if (modeChanged && writeApplied) {
-      assertContainedManagedTarget(root, write.path);
+      assertContainedManagedTarget(path.resolve(write.root || root), write.path);
       fs.chmodSync(write.path, write.mode);
     }
   }
@@ -2997,12 +3129,12 @@ function printReport(report) {
     }
   }
 
-  if (report.harnessReload) {
+  if (report.harnessReload && report.writeMode !== 'doctor') {
     process.stdout.write('\nHarness reload:\n');
     process.stdout.write(`- required: ${report.harnessReload.required ? 'yes' : 'no'}\n`);
     process.stdout.write(`- live in this process: ${report.harnessReload.live_in_this_process ? 'yes' : 'no'}\n`);
-    if (report.harnessReload.instruction) process.stdout.write(`- restart: ${report.harnessReload.instruction}\n`);
-    if (report.harnessReload.prove_command) process.stdout.write(`- prove after restart: ${report.harnessReload.prove_command}\n`);
+    if (report.harnessReload.required && report.harnessReload.instruction) process.stdout.write(`- restart: ${report.harnessReload.instruction}\n`);
+    if (report.harnessReload.required && report.harnessReload.prove_command) process.stdout.write(`- prove after restart: ${report.harnessReload.prove_command}\n`);
   }
   if (report.firstCapture) {
     process.stdout.write('\nFirst capture:\n');
@@ -3038,7 +3170,7 @@ function printReport(report) {
 
   if (report.sdkDependency?.required) {
     process.stdout.write('\nSDK dependency:\n');
-    process.stdout.write(`- @getmarrow/sdk: ${report.sdkDependency.present ? 'present' : 'missing'}\n`);
+    process.stdout.write(`- @getmarrow/sdk: ${report.sdkDependency.present ? 'present' : report.sdkDependency.ahead_unverified ? 'newer version requires verification' : 'missing'}\n`);
     if (report.sdkDependency.install_command) process.stdout.write(`- exact fix: ${report.sdkDependency.install_command}\n`);
     if (report.sdkDependency.warning) process.stdout.write(`- warning: ${report.sdkDependency.warning}\n`);
   }
@@ -3049,7 +3181,9 @@ function printReport(report) {
   if (report.controller?.exact_fix) process.stdout.write(`- exact fix: ${report.controller.exact_fix}\n`);
 
   if (report.writeMode === 'doctor') {
-    const liveHere = !report.harnessReload?.required;
+    const liveHere = !report.harnessReload?.required
+      && report.doctor.mcpProcesses?.healthy !== false
+      && report.doctor.mcpConfigurations?.healthy !== false;
     const activeLabel = report.doctor.active && liveHere
       ? 'yes'
       : report.doctor.active
@@ -3066,8 +3200,6 @@ function printReport(report) {
       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`);
     }
     if (report.doctor.mcpConfigurations) {
       const configurations = report.doctor.mcpConfigurations;
@@ -3077,6 +3209,10 @@ function printReport(report) {
       if (configurations.automatic_repair_suppressed) process.stdout.write('- automatic MCP configuration repair: suppressed pending official registry verification\n');
     }
     if (report.doctor.recommendedFix) process.stdout.write(`- recommended fix: ${report.doctor.recommendedFix}\n`);
+    if (report.doctor.mcp_update_required) {
+      process.stdout.write(`- restart once after update: ${report.doctor.restart_instruction}\n`);
+      process.stdout.write(`- verify after restart: ${report.doctor.verification_command}\n`);
+    }
     process.stdout.write(`- live health: ${report.doctor.healthCommand}\n`);
   }
 
@@ -3176,6 +3312,8 @@ async function install(options) {
   const registryVerificationAction = automaticMcpRepairSuppressed
     ? mcpRegistryVerificationAction(aheadUnverifiedVersions)
     : null;
+  const mcpUpdateRequired = !automaticMcpRepairSuppressed
+    && (!mcpConfigurations.healthy || (!options.update && !mcpProcesses.healthy));
   if (automaticMcpRepairSuppressed) {
     profile = {
       ...profile,
@@ -3208,7 +3346,40 @@ async function install(options) {
   if (options.activate && !selfTest.activation_verified) {
     throw new Error('Marrow activation failed: server confirmation was not returned');
   }
-  const harnessReload = harnessReloadPlan(detection, changes);
+  const plannedHarnessReload = harnessReloadPlan(detection, options.doctor ? [] : changes);
+  const updateNeedsRestart = Boolean(options.update
+    && !automaticMcpRepairSuppressed
+    && (plannedHarnessReload.required || (mcpConfigurations.healthy && !mcpProcesses.healthy)));
+  const harnessReload = options.doctor && mcpUpdateRequired
+    ? {
+      ...plannedHarnessReload,
+      required: true,
+      live_in_this_process: false,
+      instruction: INSTALLER_RESTART_INSTRUCTION,
+      prove_command: INSTALLER_DOCTOR_COMMAND,
+    }
+    : updateNeedsRestart
+    ? {
+      ...plannedHarnessReload,
+      required: true,
+      live_in_this_process: false,
+      instruction: INSTALLER_RESTART_INSTRUCTION,
+      prove_command: INSTALLER_DOCTOR_COMMAND,
+    }
+    : plannedHarnessReload;
+  const updateAwaitingRestart = Boolean(options.update
+    && updateNeedsRestart
+    && mcpConfigurations.healthy
+    && !mcpProcesses.healthy
+    && !automaticMcpRepairSuppressed);
+  const reportedMcpProcesses = updateAwaitingRestart
+    ? {
+      ...mcpProcesses,
+      update_completed: true,
+      awaiting_restart: true,
+      exact_fix: null,
+    }
+    : mcpProcesses;
   if (harnessReload.required && selfTest.mcp_tool_profile) {
     selfTest.mcp_tool_profile = {
       ...selfTest.mcp_tool_profile,
@@ -3268,6 +3439,8 @@ async function install(options) {
       automaticMcpRepairSuppressed,
       message: automaticMcpRepairSuppressed
         ? registryVerificationAction
+        : options.update && harnessReload.required
+        ? 'Managed Marrow configuration is synchronized. Running MCP processes are unchanged; complete the Harness reload steps below before treating the update as live.'
         : selfTestPassed
         ? selfTest.health === 'healthy'
           ? 'I fixed Marrow passive config, one-call runtime is active, and self-test passed.'
@@ -3277,7 +3450,6 @@ async function install(options) {
         : `Config repair ran, but self-test failed: ${selfTest.error || 'unknown error'}.`,
     }
     : null;
-
   return {
     root: detection.root,
     adapterProvenance: adapterProvenanceForMcpTarget(mcpTarget),
@@ -3314,12 +3486,18 @@ async function install(options) {
       missingEnv: options.apiKey ? [] : ['MARROW_API_KEY'],
       envHints,
       missingHooks: changes.filter((change) => change.changed).map((change) => change.label),
-      mcpProcesses,
+      mcpProcesses: reportedMcpProcesses,
       mcpConfigurations,
       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
+      mcp_update_required: mcpUpdateRequired,
+      restart_required: mcpUpdateRequired || updateAwaitingRestart,
+      restart_instruction: mcpUpdateRequired || updateAwaitingRestart ? INSTALLER_RESTART_INSTRUCTION : null,
+      verification_command: mcpUpdateRequired || updateAwaitingRestart ? INSTALLER_DOCTOR_COMMAND : null,
+      recommendedFix: registryVerificationAction
+        || (updateAwaitingRestart ? INSTALLER_RESTART_INSTRUCTION : null)
+        || mcpProcesses.exact_fix || mcpConfigurations.exact_fix || configDiagnostics.npm_token.recommended_fix || (!options.apiKey
         ? envHints.length
           ? `MARROW_API_KEY was found in a likely env file at ${envHints[0]}. Load that key from trusted secret storage, export only MARROW_API_KEY, then run npx @getmarrow/install --repair.`
           : 'Set MARROW_API_KEY, then run npx @getmarrow/install --repair.'
@@ -3339,13 +3517,13 @@ async function install(options) {
         : []),
       ...(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.']
+        : !mcpProcesses.healthy && !options.update && !options.doctor
+        ? [`Stale, mixed, or version-unknown Marrow MCP clients are active. Run ${INSTALLER_UPDATE_COMMAND}; the installer will report the one required restart and later doctor verification.`]
         : []),
       ...(mcpConfigurations.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.']
+        : !mcpConfigurations.healthy && !options.update && !options.doctor
+        ? [`Stale, mixed, or version-unknown Marrow MCP versions remain in the detected workspace. Run ${INSTALLER_UPDATE_COMMAND} once to synchronize its managed surfaces.`]
         : []),
     ],
   };