@getmarrow/install 0.1.69 → 0.1.70

package/README.md

@@ -103,15 +103,23 @@ Persistent controller lifecycle is currently Linux-only. On macOS or Windows, ac
 
 The controller is not a boot service. After a host restart, or any exit that skips its shutdown handler, doctor reports it as `stale` until the next install, update, or `controller ensure`. Local control can be inspected and changed with `npx @getmarrow/install control status|disable --yes|enable`. While local control is disabled, the controller is not started, and doctor reports a stopped or stale controller as not required instead of recommending `controller ensure`; missing state means enabled, and an explicit owner disable is preserved. Unsafe controller state or an unverified or unresponsive controller process keeps its exact fix.
 
-## What's New in v0.1.69
+## Key handling at install
 
-v0.1.69 installs MCP `3.9.101`. In short (the full entry is in the [CHANGELOG](https://github.com/getmarrow/marrow-install/blob/master/CHANGELOG.md)):
+These behaviors shipped in v0.1.69 and still apply.
 
-- **No key, no half install.** With no API key, `activate` and every `--yes` run now stop, write nothing and print how to get a key. Before, they wrote hooks that blocked every commit.
-- **A blank key no longer hides a saved one.** An empty `MARROW_API_KEY` value no longer hides a valid key saved in `~/.marrow/env`.
+- **No key, no half install.** With no API key, `activate` and every `--yes` run stop, write nothing and print how to get a key.
+- **A blank key does not hide a saved one.** An empty `MARROW_API_KEY` value does not hide a valid key saved in `~/.marrow/env`.
 - **`MARROW_KEY` works on its own.** It is used when `MARROW_API_KEY` is absent.
-- **Key-file steps.** They now include `chmod 700 ~/.marrow` as well as `chmod 600 ~/.marrow/env`. See [Get started](#get-started).
-- **MCP 3.9.101.** The installer pins MCP `3.9.101`.
+- **Key-file steps.** They include `chmod 700 ~/.marrow` as well as `chmod 600 ~/.marrow/env`. See [Get started](#get-started).
+
+## What's New in v0.1.70
+
+v0.1.70 installs MCP `3.9.102`. In short (the full entry is in the [CHANGELOG](https://github.com/getmarrow/marrow-install/blob/master/CHANGELOG.md)):
+
+- **Own-tool names are exact.** Hook matchers and the Cursor guard skip the gate only for Marrow's registered tools on server `marrow`, by exact name. Look-alike servers or names go through the gate. Re-run `update` to refresh hooks written with the old matcher. See [Hooks the installer writes](#hooks-the-installer-writes).
+- **Hooks run only the verified local MCP runtime.** They no longer start `npx`; when the runtime is missing, they heal it from the pinned, integrity-checked package, and hold if they cannot. When npm or the network is down, pre-action hooks warn and let the action run; an integrity mismatch or any other failure holds. See [Local MCP runtime](#local-mcp-runtime).
+- **Fallback npm install protects your npm login.** It sends npm auth only when the network settings come from your own npm config, and installs exactly the pinned MCP and SDK.
+- **MCP 3.9.102.** A cloned project's `.env` can no longer point the MCP server at another account or server.
 
 Earlier release notes are in the [CHANGELOG](https://github.com/getmarrow/marrow-install/blob/master/CHANGELOG.md).
 
@@ -267,12 +275,12 @@ Never connect an agent to the email inbox that receives Marrow approval mail. An
 
 ### Hooks the installer writes
 
-These hooks are written with MCP `3.9.99` and later (`MCP_HOST_APPROVAL_HOOKS_SINCE` in `src/pins.js`). v0.1.69 installs MCP `3.9.101`, so `install` and `update` write them; with an older MCP the earlier layout stays. `update` also uses a registry-verified MCP at or above that version.
+These hooks are written with MCP `3.9.99` and later (`MCP_HOST_APPROVAL_HOOKS_SINCE` in `src/pins.js`). v0.1.70 installs MCP `3.9.102`, so `install` and `update` write them; with an older MCP the earlier layout stays. `update` also uses a registry-verified MCP at or above that version.
 
 | Host | Hooks for approvals | How the operator answers |
 | --- | --- | --- |
 | Claude Code | `PermissionRequest` → `claude-permission-request-hook` and `PostToolBatch` → `claude-hook`, both `async: true`, next to the existing hooks; the same entries `marrow-mcp setup` writes | In Claude Code's own permission dialog. The pass-through marker never answers or delays the dialog; a permission rejection is recorded as a decline, an interruption never is |
-| Cursor | `beforeShellExecution` → `cursor-pre-action-hook` and `beforeMCPExecution` → the same entrypoint through a small guard, both `failClosed: true` with a 15-second timeout; `afterShellExecution` and `afterMCPExecution` → `cursor-hook`; `sessionStart` → `cursor-session-hook`; `beforeSubmitPrompt` → `cursor-context-hook`. Shell calls leave the `preToolUse` matcher. MCP calls stay in it, because cloud agents never run `beforeMCPExecution`: there `preToolUse` holds them, and in a local interactive session it lets `beforeMCPExecution` ask. The guard answers Marrow's own `marrow_*` tools at once, as the old matcher exempted them | Cursor's own prompt for shell and MCP calls in a local interactive session; the typed reply the hook shows the user (`marrow approve CODE`) for its other tools there. Background and cloud agents hold quietly |
+| Cursor | `beforeShellExecution` → `cursor-pre-action-hook` and `beforeMCPExecution` → the same entrypoint through a small guard, both `failClosed: true` with a 15-second timeout; `afterShellExecution` and `afterMCPExecution` → `cursor-hook`; `sessionStart` → `cursor-session-hook`; `beforeSubmitPrompt` → `cursor-context-hook`. Shell calls leave the `preToolUse` matcher. MCP calls stay in it, because cloud agents never run `beforeMCPExecution`: there `preToolUse` holds them, and in a local interactive session it lets `beforeMCPExecution` ask. The guard answers at once only for Marrow's own tools: server exactly `marrow` and one of the 58 registered names (`src/marrow-own-tools.js`). Only the Claude Code matcher skips them, by the exact name `mcp__marrow__<name>`; Cursor (`MCP:<tool>`) and Gemini (`mcp_<server>_<tool>`) names do not prove the server, so every MCP call there reaches the hook, as does an unregistered `marrow_*` name, a case variant or a look-alike server | Cursor's own prompt for shell and MCP calls in a local interactive session; the typed reply the hook shows the user (`marrow approve CODE`) for its other tools there. Background and cloud agents hold quietly |
 | Gemini CLI | `BeforeAgent` → `gemini-context-hook`. The `BeforeTool` guard passes a denial that carries a code for the user only (`systemMessage`); any other output, a crash, or no answer within 4.5 seconds still blocks the call | The typed reply, in a local interactive session (`gemini`); `gemini -p` holds quietly |
 | Codex | `UserPromptSubmit` → `codex-context-hook` (unchanged). Codex is never configured to "ask", because Codex lets an asked call run | The typed reply, in a local interactive session; `codex exec` holds quietly |
 

package/package.json

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

package/src/governed-runner.js

@@ -3089,9 +3089,9 @@ async function sidecarOnly(parsed) {
     const detection = detectEnvironment(root, process.env);
     // Maintenance re-applies the controller's own configured agent id and base URL. A different
     // value found in managed MCP config is replaced unless the owner allowlisted it, and the
-    // divergence is reported. It never edits the owner's Hermes config. Hooks stay on the
-    // verified local MCP runtime when there is one (checked, never installed, here).
-    const mcpRuntime = maintenanceMcpRuntime(detection, { mcpLocalRuntime: process.env.MARROW_LOCAL_RUNTIME !== '0' });
+    // divergence is reported. It never edits the owner's Hermes config. Hooks are written in
+    // the local MCP runtime form (never npx); the copy is checked, never installed, here.
+    const mcpRuntime = maintenanceMcpRuntime(detection);
     const plan = buildPlan(detection, {
       mode: managedMode,
       agentId: options.agentId,

package/src/installer.js

@@ -20,11 +20,18 @@ const {
   planHermesMcpConfig,
 } = require('./hermes-config');
 const { ensureOwnerApiKey, readOwnerApiKey } = require('./owner-env');
+const { buildOwnToolMatchers, cursorOwnToolGuardCondition } = require('./marrow-own-tools');
 const {
   delocalizeHookCommand,
+  delocalizeHookScriptText,
   ensureMcpRuntime,
+  hookTextUsesNpx,
+  localizeHookScriptText,
   localizeHookSettingsText,
   mapHookCommands,
+  mcpServerLaunch,
+  mcpServerLaunchVersion,
+  mcpServerUsesNpx,
   removeMcpRuntime,
   verifyMcpRuntime,
 } = require('./mcp-runtime');
@@ -231,7 +238,8 @@ function adapterProvenanceForMcpTarget(target) {
 
 function retargetMcpPackageSpec(value, version) {
   const target = compatibleMcpTargetVersion(version) ? version : MCP_ADAPTER_VERSION;
-  return String(value).split(MCP_PACKAGE_SPEC).join(`@getmarrow/mcp@${target}`);
+  return String(value).split(MCP_PACKAGE_SPEC).join(`@getmarrow/mcp@${target}`)
+    .split(`/.marrow/runtime/mcp/${MCP_ADAPTER_VERSION}/`).join(`/.marrow/runtime/mcp/${target}/`);
 }
 
 function retargetMcpDowngradeRecommendation(value, targetVersion) {
@@ -280,8 +288,8 @@ const CURSOR_ACTION_RESULT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC}
 const CURSOR_SESSION_END_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cursor-session-hook`;
 const CURSOR_CONTEXT_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp cursor-context-hook`;
 // Cursor's beforeMCPExecution takes no matcher, so this guard answers allow at once for
-// Marrow's own tools (server "marrow", tools marrow_*), as the old preToolUse matcher exempted
-// them, without starting npx. Every other call goes to the MCP entrypoint with its input
+// Marrow's own tools (server exactly "marrow", tool one of the registered names in
+// marrow-own-tools.js; this event names the server) without starting npx. Every other call goes to the MCP entrypoint with its input
 // unchanged; a crash, a non-zero exit or output that is not a JSON object blocks (exit 2).
 const CURSOR_MCP_GUARD_FAILURE = 'Marrow governance adapter was unavailable; this MCP call is blocked.';
 const CURSOR_MCP_PRE_ACTION_GUARD_SOURCE = [
@@ -291,7 +299,7 @@ const CURSOR_MCP_PRE_ACTION_GUARD_SOURCE = [
   'process.stdin.on("error",fail);',
   'process.stdin.on("data",c=>{size+=c.length;if(size>16777216){over=true;return;}chunks.push(c);});',
   'process.stdin.on("end",()=>{if(over){fail();return;}const raw=Buffer.concat(chunks);let ev=null;try{ev=JSON.parse(raw.toString("utf8"));}catch{ev=null;}',
-  'if(ev&&typeof ev==="object"&&ev.mcp_server_name==="marrow"&&typeof ev.tool_name==="string"&&/^marrow_[a-z0-9_]{1,64}$/.test(ev.tool_name)){done=true;process.stdout.write("{\\"permission\\":\\"allow\\"}\\n");return;}',
+  `if(ev&&typeof ev==="object"&&${cursorOwnToolGuardCondition()}){done=true;process.stdout.write("{\\"permission\\":\\"allow\\"}\\n");return;}`,
   'let child;try{',
   `child=spawn(process.platform==="win32"?"npx.cmd":"npx",${JSON.stringify(['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp', 'cursor-pre-action-hook'])},{stdio:["pipe","pipe","ignore"]});`,
   '}catch{fail();return;}',
@@ -387,21 +395,22 @@ const GROK_PRE_ACTION_GUARD_SOURCE = [
   'child.stdin.end(Buffer.concat(input));}catch{fail();}});',
 ].join('');
 const GROK_PRE_ACTION_HOOK_COMMAND = `node -e '${GROK_PRE_ACTION_GUARD_SOURCE}'`;
-const NATIVE_HOOK_MATCHER = 'Bash|Edit|Write|MultiEdit|Read|Glob|Grep|Search|WebSearch|Task|functions\\.(?!mcp__marrow__marrow_).*|mcp__(?!marrow__marrow_).*';
-const CODEX_NATIVE_HOOK_MATCHER = 'Bash|apply_patch|Edit|Write|MultiEdit|mcp__(?!marrow__marrow_).*|functions\\.(?!marrow_).*';
-const CURSOR_NATIVE_HOOK_MATCHER = 'Shell|Write|Delete|Task|Read|Glob|Grep|Search|WebSearch|List|MCP:(?!marrow(?:_.*|:marrow_.*)$).*';
+const OWN_TOOL_MATCHERS = buildOwnToolMatchers();
+const NATIVE_HOOK_MATCHER = OWN_TOOL_MATCHERS.claude;
+const CODEX_NATIVE_HOOK_MATCHER = OWN_TOOL_MATCHERS.codex;
+const CURSOR_NATIVE_HOOK_MATCHER = OWN_TOOL_MATCHERS.cursor;
 // Host approvals: Cursor enforces an "ask" only on beforeShellExecution and beforeMCPExecution,
 // never on preToolUse. Shell calls move to beforeShellExecution (it runs in cloud agents too).
 // MCP calls stay in preToolUse as well, because cloud agents never run beforeMCPExecution: the
 // MCP hook defers there to beforeMCPExecution only in a local interactive session (sessionStart
 // evidence) and holds in cloud and background agents. The result hooks keep the full matcher.
-const CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER = 'Write|Delete|Task|Read|Glob|Grep|Search|WebSearch|List|MCP:(?!marrow(?:_.*|:marrow_.*)$).*';
+const CURSOR_PRE_TOOL_USE_HOST_APPROVAL_MATCHER = OWN_TOOL_MATCHERS.cursorPreToolUseHostApproval;
 // Cursor's gating hooks are failClosed: a cold npx start on a slow network must not block a
 // call, so they get room beyond the MCP hook's own 4-second budget.
 const CURSOR_GATE_HOOK_TIMEOUT_SECONDS = 15;
 const CURSOR_EXECUTION_PRE_EVENTS = Object.freeze(['beforeShellExecution', 'beforeMCPExecution']);
 const CURSOR_EXECUTION_POST_EVENTS = Object.freeze(['afterShellExecution', 'afterMCPExecution']);
-const GEMINI_NATIVE_HOOK_MATCHER = '^(?:run_shell_command|write_file|replace|edit_file|delete_file|read_file|read_many_files|glob|grep_search|list_directory|get_file_info|web_search|google_web_search|mcp_(?!marrow_marrow_)[A-Za-z0-9_]{1,192})$';
+const GEMINI_NATIVE_HOOK_MATCHER = OWN_TOOL_MATCHERS.gemini;
 const GROK_NATIVE_HOOK_MATCHER = 'run_terminal_command|search_replace|write|spawn_subagent|use_tool|workflow|image_gen|image_edit|image_to_video|reference_to_video';
 const CODEX_HOOK_TIMEOUT_SECONDS = 5;
 const CODEX_SESSION_TIMEOUT_SECONDS = 3;
@@ -644,6 +653,9 @@ function isMcpProcessCommand(command) {
   const executable = path.basename(args[0]);
   if (new Set(['bash', 'bwrap', 'dash', 'fish', 'sh', 'zsh']).has(executable)) return false;
   if (executable === 'marrow-mcp') return true;
+  // The verified local runtime: node on the inline loader with the pinned package spec.
+  if (executable === 'node' && args[1] === '-e' && args.includes('marrow-mcp')
+    && args.some((arg) => /^--package=@getmarrow\/mcp@\d+\.\d+\.\d+$/.test(arg))) return true;
 
   if (executable === 'node'
     && args[1]
@@ -862,9 +874,11 @@ function parseArgs(argv, env = process.env) {
     json: false,
     activate: false,
     controller: true,
-    // Hooks start a verified local copy of the pinned MCP (installed on write runs) instead of
-    // npx. MARROW_LOCAL_RUNTIME=0 or --no-local-runtime keeps them on npx.
-    mcpLocalRuntime: env.MARROW_LOCAL_RUNTIME !== '0',
+    // Hooks start only the verified local copy of the pinned MCP (installed on write runs); they
+    // never start npx, which resolves the package from the project directory first. The old
+    // opt-out (MARROW_LOCAL_RUNTIME=0, --no-local-runtime) is accepted and ignored.
+    mcpLocalRuntime: true,
+    ...(env.MARROW_LOCAL_RUNTIME === '0' ? { localRuntimeSwitchIgnored: true } : {}),
   };
   let explicitOperation = false;
 
@@ -905,6 +919,9 @@ function parseArgs(argv, env = process.env) {
       explicitOperation = true;
       options.uninstall = true;
     }
+    else if (arg === '--all') {
+      options.all = true;
+    }
     else if (arg === '--doctor' || arg === 'doctor' || arg === 'check') {
       explicitOperation = true;
       options.doctor = true;
@@ -917,7 +934,7 @@ function parseArgs(argv, env = process.env) {
       options.selfTestExplicitlyDisabled = true;
     }
     else if (arg === '--no-controller') options.controller = false;
-    else if (arg === '--no-local-runtime') options.mcpLocalRuntime = false;
+    else if (arg === '--no-local-runtime') options.localRuntimeSwitchIgnored = true;
     else if (arg === '--self-test') options.selfTest = true;
     else if (arg === '--cwd') options.cwd = path.resolve(optionValue() || options.cwd);
     else if (arg === '--mode') {
@@ -954,6 +971,9 @@ function parseArgs(argv, env = process.env) {
     }
   }
 
+  if (options.all && !options.uninstall) {
+    throw new Error('--all is only valid with uninstall');
+  }
   if (options.uninstall && (options.activate || options.repair || options.doctor)) {
     throw new Error('uninstall cannot be combined with activate, update, repair, or doctor');
   }
@@ -989,7 +1009,7 @@ function usage() {
   npx @getmarrow/install doctor --self-test
   npx @getmarrow/install --mcp --yes
   npx @getmarrow/install --sdk --yes
-  npx @getmarrow/install uninstall [--yes]
+  npx @getmarrow/install uninstall [--yes] [--all]
 
 Options:
   (no command)       Detect, install, self-test, and start the supported persistent controller
@@ -1004,12 +1024,12 @@ Options:
   --base-url <url>   Marrow API base URL
   --agent-id <id>    Agent/fleet id for self-test headers
   --no-controller    Do not start the local background controller during install/repair
-  --no-local-runtime Keep hooks on npx instead of the verified local MCP copy in ~/.marrow/runtime
+  --no-local-runtime Ignored: hooks always start the verified local MCP copy in ~/.marrow/runtime, never npx
   --no-self-test     Skip API smoke/self-test
   --verbose          Print the full report instead of the one-line summary and log file
-  uninstall          Preview removing only Marrow's own hooks, MCP server entries, instructions and
-                     the local MCP runtime; add --yes to remove them. Your own hooks and settings
-                     are kept.
+  uninstall          Preview removing only Marrow's own hooks, MCP server entries and instructions
+                     from this project; add --yes to remove them. Your own hooks and settings are
+                     kept, and so is the local MCP runtime other projects share; --all removes it.
 
 Get a key at https://getmarrow.ai/signup. Put it in the owner-only ~/.marrow/env as
 MARROW_API_KEY=your_key, then run chmod 700 ~/.marrow && chmod 600 ~/.marrow/env, or export MARROW_API_KEY. Keep it off the command line: command-line
@@ -2190,19 +2210,25 @@ function clineHookContract(detection) {
       stage: 'pre_action',
       path: detection.paths.clinePreToolUseHook,
       label: 'Cline PreToolUse native hook',
-      content: clinePreToolUseHookSource(),
+      content: localizeHookScriptText(clinePreToolUseHookSource(), MCP_ADAPTER_VERSION),
+      source: clinePreToolUseHookSource(),
+      legacyContent: clinePreToolUseHookSource(),
     },
     {
       stage: 'action_result',
       path: detection.paths.clinePostToolUseHook,
       label: 'Cline PostToolUse native hook',
-      content: clineTelemetryHookSource('cline-hook'),
+      content: localizeHookScriptText(clineTelemetryHookSource('cline-hook'), MCP_ADAPTER_VERSION),
+      source: clineTelemetryHookSource('cline-hook'),
+      legacyContent: clineTelemetryHookSource('cline-hook'),
     },
     {
       stage: 'cancel_closeout',
       path: detection.paths.clineTaskCancelHook,
       label: 'Cline TaskCancel native hook',
-      content: clineTelemetryHookSource('cline-session-hook'),
+      content: localizeHookScriptText(clineTelemetryHookSource('cline-session-hook'), MCP_ADAPTER_VERSION),
+      source: clineTelemetryHookSource('cline-session-hook'),
+      legacyContent: clineTelemetryHookSource('cline-session-hook'),
     },
   ];
 }
@@ -2348,9 +2374,7 @@ function activationProfile(detection, plan, changes, client) {
   const mcpConfigs = [detection.paths.mcpJson, detection.paths.cursorMcp]
     .map((filePath) => safeJsonObject(filePath));
   if (capabilityLevel === 'mcp' && mcpConfigs.some((config) => (
-    config?.mcpServers?.marrow?.command === 'npx'
-    && Array.isArray(config.mcpServers.marrow.args)
-    && config.mcpServers.marrow.args.join(' ') === `-y --package=@getmarrow/mcp@${mcpTargetVersion} marrow-mcp`
+    mcpServerLaunchVersion(config?.mcpServers?.marrow) === mcpTargetVersion
   ))) observedHooks.push('mcp_tool_calls');
   const fingerprintMaterial = changes
     .filter((change) => change.applied || change.already_present)
@@ -2522,9 +2546,15 @@ function upsertMcpServerConfig(filePath, options = {}) {
   const env = { MARROW_BASE_URL: baseUrl };
   if (keptAgentId) env.MARROW_FLEET_AGENT_ID = keptAgentId;
   if (configuredProfile !== 'unset') env.MARROW_TOOL_PROFILE = configuredProfile;
+  // The server starts the verified local runtime (it installs the pinned copy itself when it is
+  // missing), never npx from the project directory: a copy planted there would otherwise become
+  // the Marrow MCP server, whose own tools the hook matchers leave ungated.
+  const serverVersion = compatibleMcpTargetVersion(options.mcpVersion) ? options.mcpVersion : MCP_ADAPTER_VERSION;
   servers.marrow = {
-    command: 'npx',
-    args: ['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp'],
+    ...mcpServerLaunch(serverVersion, {
+      platform: options.hookPlatform || process.platform,
+      ...(options.mcpIntegrity && serverVersion === options.mcpVersion ? { integrity: options.mcpIntegrity } : {}),
+    }),
     env,
   };
   config.mcpServers = servers;
@@ -2827,15 +2857,25 @@ function buildPlan(detection, options) {
       write.identityDivergence = [];
       return retarget(upsertMcpServerConfig(target, {
         ...mcpConfigOptions,
+        mcpVersion: mcpTargetVersion,
+        mcpIntegrity: mcpTargetIntegrity,
+        hookPlatform,
         onDivergence: (divergence) => write.identityDivergence.push(divergence),
       }));
     };
     return write;
   };
   const mcpTargetVersion = executableMcpTarget(options).version;
-  // Hooks start the verified local MCP runtime for this exact version when there is one.
-  const runtimeVersion = options.mcpRuntime && options.mcpRuntime.version === mcpTargetVersion ? mcpTargetVersion : null;
-  const localize = (text) => (runtimeVersion ? localizeHookSettingsText(text, runtimeVersion) : text);
+  // Hooks always start the verified local MCP runtime for this exact version, never npx: when
+  // that copy is missing or changed, a pre-action hook holds the call until a repair installs it.
+  const hookPlatform = options.hookPlatform || process.platform;
+  const mcpTargetIntegrity = executableMcpTarget(options).integrity;
+  // A Marrow command already in the file with the same configuration is kept byte for byte.
+  const localize = (text, filePath) => localizeHookSettingsText(text, mcpTargetVersion, {
+    platform: hookPlatform,
+    integrity: mcpTargetIntegrity,
+    previousText: filePath ? safeRead(filePath) : null,
+  });
   const retarget = (value) => retargetMcpPackageSpec(value, mcpTargetVersion);
   // The host-approval hook layout only for an MCP that answers those hooks.
   const hostApprovals = hostApprovalHooksSupported(mcpTargetVersion);
@@ -2866,7 +2906,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.claudeSettings,
         label: 'Claude Code MCP passive hooks',
-        transform: (filePath) => localize(retarget(upsertClaudeHooks(filePath, { hostApprovals }))),
+        transform: (filePath) => localize(retarget(upsertClaudeHooks(filePath, { hostApprovals })), filePath),
       });
     }
     if (detection.codex) {
@@ -2874,7 +2914,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.codexHooks,
         label: 'Codex native hooks',
-        transform: (filePath) => localize(retarget(upsertCodexHooks(filePath))),
+        transform: (filePath) => localize(retarget(upsertCodexHooks(filePath)), filePath),
       });
     }
     if (detection.cline) {
@@ -2883,7 +2923,9 @@ function buildPlan(detection, options) {
           type: 'owned-executable',
           path: hook.path,
           label: hook.label,
-          content: retarget(hook.content),
+          content: localizeHookScriptText(retarget(hook.source), mcpTargetVersion, { integrity: mcpTargetIntegrity }),
+          // The npx script 0.1.68 and earlier wrote is Marrow's too, and is rewritten.
+          legacyContent: retarget(hook.legacyContent),
           mode: 0o755,
           conflict_fix: 'Move or remove the existing owner-managed Cline hook after owner review, then run npx @getmarrow/install --repair.',
         });
@@ -2894,7 +2936,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.windsurfHooks,
         label: 'Windsurf native hooks',
-        transform: (filePath) => localize(retarget(upsertWindsurfHooks(filePath))),
+        transform: (filePath) => localize(retarget(upsertWindsurfHooks(filePath)), filePath),
       });
     }
     if (detection.gemini) {
@@ -2902,7 +2944,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.geminiSettings,
         label: 'Gemini CLI native hooks',
-        transform: (filePath) => localize(retarget(upsertGeminiHooks(filePath, { hostApprovals }))),
+        transform: (filePath) => localize(retarget(upsertGeminiHooks(filePath, { hostApprovals })), filePath),
       });
     }
     if (detection.grok) {
@@ -2913,7 +2955,7 @@ function buildPlan(detection, options) {
         label: 'Grok native hooks',
         isManaged: managedGrokHooksFile,
         conflict_fix: 'Preserve or move the unmanaged owner Grok hook file after owner review, then rerun npx @getmarrow/install update.',
-        transform: (filePath) => localize(retarget(upsertGrokHooks(filePath))),
+        transform: (filePath) => localize(retarget(upsertGrokHooks(filePath)), filePath),
       });
     }
     writes.push(mcpConfigWrite(detection.paths.mcpJson, 'Project MCP server config'));
@@ -2937,7 +2979,7 @@ function buildPlan(detection, options) {
         type: 'json-transform',
         path: detection.paths.cursorHooks,
         label: 'Cursor native hooks',
-        transform: (filePath) => localize(retarget(upsertCursorHooks(filePath, { hostApprovals }))),
+        transform: (filePath) => localize(retarget(upsertCursorHooks(filePath, { hostApprovals })), filePath),
       });
       writes.push(mcpConfigWrite(detection.paths.cursorMcp, 'Cursor MCP server config'));
     }
@@ -3082,7 +3124,7 @@ function applyPlan(plan, options) {
     } else if (write.type === 'owned-executable') {
       // A file Marrow wrote for another pinned MCP version is still Marrow's and moves to this
       // pin; any other difference is the owner's edit and is never overwritten.
-      if (fileExists && before !== write.content && !sameMarrowFile(before, [write.content])) {
+      if (fileExists && before !== write.content && !sameMarrowFile(before, [write.content, write.legacyContent].filter(Boolean))) {
         after = before;
         hookConflict = true;
       } else {
@@ -3238,8 +3280,8 @@ function withoutMarrowMcpServer(config) {
   const entry = servers && typeof servers === 'object' && !Array.isArray(servers) ? servers.marrow : null;
   if (!entry) return { config, removed: 0, kept: 0, custom: false };
   const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
-  const ours = entry.command === 'npx' && args.includes('marrow-mcp')
-    && args.some((arg) => /^--package=@getmarrow\/mcp(?:@[^\s]+)?$/.test(arg));
+  const ours = Boolean(mcpServerLaunchVersion(entry)) || (entry.command === 'npx' && args.includes('marrow-mcp')
+    && args.some((arg) => /^--package=@getmarrow\/mcp(?:@[^\s]+)?$/.test(arg)));
   if (!ours) return { config, removed: 0, kept: 1, custom: true };
   const nextServers = { ...servers };
   delete nextServers.marrow;
@@ -3260,7 +3302,8 @@ function withoutMarrowInstructionBlock(content) {
 
 // Marrow-written files compare equal once the pinned MCP version is normalized.
 function sameMarrowFile(actual, candidates) {
-  const normalize = (value) => String(value).replace(/@getmarrow\/mcp@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g, '@getmarrow/mcp@<pinned>');
+  const normalize = (value) => delocalizeHookScriptText(String(value)).replace(/@getmarrow\/mcp@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g, '@getmarrow/mcp@<pinned>')
+    .replace(/\/\.marrow\/runtime\/mcp\/\d+\.\d+\.\d+\//g, '/.marrow/runtime/mcp/<pinned>/');
   const normalized = normalize(actual);
   return candidates.some((candidate) => normalize(candidate) === normalized);
 }
@@ -3289,7 +3332,7 @@ function buildUninstallPlan(detection) {
   const instructionVariants = [false, true].map((hostApprovals) => passiveInstructions({ hostApprovals }).replace(/<!--[^>]+-->/g, '').trim() + '\n');
   steps.push({ kind: 'owned-file', path: detection.paths.cursorRules, label: 'Cursor Marrow rule', candidates: instructionVariants });
   for (const hook of clineHookContract(detection)) {
-    steps.push({ kind: 'owned-file', path: hook.path, label: hook.label, candidates: [hook.content] });
+    steps.push({ kind: 'owned-file', path: hook.path, label: hook.label, candidates: [hook.content, hook.legacyContent] });
   }
   return steps;
 }
@@ -3406,8 +3449,12 @@ async function uninstall(options = {}) {
     hermesEntry = false;
   }
   if (hermesEntry) kept.push({ path: detection.paths.hermesConfig, reason: 'remove mcp_servers.marrow by hand; uninstall never rewrites the Hermes config, which holds other servers\' settings' });
-  // The local MCP runtime (~/.marrow/runtime) goes too; hooks elsewhere then start through npx.
-  const runtime = removeMcpRuntime(options.home || detection.home, { dryRun: !apply });
+  // The local MCP runtime (~/.marrow/runtime) is shared by every project on this machine, so a
+  // project uninstall keeps it. `uninstall --all` removes it too; hooks left in other projects
+  // then install it again on their next start (or hold when they cannot).
+  const runtime = options.all === true
+    ? removeMcpRuntime(options.home || detection.home, { dryRun: !apply })
+    : { removed: false, would_remove: false, kept: true, path: path.join(options.home || detection.home, '.marrow', 'runtime') };
   const removedEntries = changes.reduce((sum, change) => sum + change.removed_entries, 0);
   return {
     uninstall: {
@@ -3418,6 +3465,7 @@ async function uninstall(options = {}) {
       changes,
       kept,
       runtime: runtime.removed || runtime.would_remove ? runtime : null,
+      runtime_kept: runtime.kept === true && fs.existsSync(runtime.path) ? runtime.path : null,
       removed_entries: removedEntries,
       next_step: apply
         ? 'Restart the agent hosts so they stop loading the removed hooks and MCP server.'
@@ -3440,7 +3488,8 @@ function printUninstallReport(report, sink = (text) => process.stdout.write(text
     else if (change.action === 'kept' || change.action === 'skipped') sink(`- ${where(change.path)}: left unchanged (${change.reason}).\n`);
   }
   for (const entry of result.kept) sink(`- ${where(entry.path)}: left in place; ${entry.reason}.\n`);
-  if (result.runtime) sink(`- ${result.runtime.path}: ${result.applied ? 'removed' : 'would remove'} Marrow's local MCP runtime (other projects' hooks start through npx until the next install there).\n`);
+  if (result.runtime) sink(`- ${result.runtime.path}: ${result.applied ? 'removed' : 'would remove'} Marrow's local MCP runtime (Marrow hooks left in other projects install it again on their next start).\n`);
+  else if (result.runtime_kept) sink(`- ${result.runtime_kept}: kept; other projects on this machine may use Marrow's local MCP runtime. Add --all to remove it too.\n`);
   if (result.controller?.stopped) sink(`Stopped ${result.controller.stopped} Marrow controller${result.controller.stopped === 1 ? '' : 's'} for this project.\n`);
   sink(`${result.next_step}\n`);
 }
@@ -4144,7 +4193,10 @@ function printReport(report, sink) {
   if (report.mcp_runtime) {
     const runtime = report.mcp_runtime;
     out('\nMCP local runtime:\n');
-    out(`- hooks start: ${runtime.hooks_start === 'local_runtime' ? `the verified local copy of @getmarrow/mcp@${runtime.version} (${runtime.path})` : 'through npx'}\n`);
+    out(`- hooks start: ${runtime.hooks_start === 'local_runtime' ? `the verified local copy of @getmarrow/mcp@${runtime.version} (${runtime.path})` : 'no verified local copy yet: Marrow hooks install the pinned copy on their next start; if npm or the registry cannot be reached they warn and let the action run, and any other failure holds it'}\n`);
+    for (const filePath of runtime.legacy_npx_hooks || []) out(`- needs repair: ${filePath} still starts @getmarrow/mcp through npx\n`);
+    if (runtime.needs_repair) out('- repair: run npx -y @getmarrow/install@latest --repair (from a terminal outside the project, with --cwd <project folder>)\n');
+    if (runtime.local_runtime_switch === 'ignored') out('- note: MARROW_LOCAL_RUNTIME=0 / --no-local-runtime are ignored; hooks never start npx\n');
     out(`- state: ${runtime.state}${runtime.reason ? ` (${runtime.reason})` : ''}\n`);
     if (runtime.removed_versions?.length) out(`- removed older versions: ${runtime.removed_versions.join(', ')}\n`);
   }
@@ -4410,11 +4462,9 @@ function hermesWiringReport(detection, changes, options, planMode) {
 }
 
 // The local MCP runtime for the target version: installed (or kept) on a write run of the
-// command, otherwise only an existing verified copy is used. `mcpLocalRuntime: false` (or
-// MARROW_LOCAL_RUNTIME=0, --no-local-runtime) leaves every hook of this project on npx.
+// command, otherwise only an existing verified copy is used. Hooks start nothing else.
 function resolveMcpRuntime(detection, options, mcpTarget) {
   const home = options.home || detection.home;
-  if (options.mcpLocalRuntime === false) return { state: 'disabled' };
   const version = mcpTarget.version;
   const integrity = mcpTarget.integrity || (version === MCP_ADAPTER_VERSION ? MCP_ADAPTER_INTEGRITY : null);
   if (!integrity) return { state: 'skipped', reason: 'no_verified_integrity', version };
@@ -4425,6 +4475,7 @@ function resolveMcpRuntime(detection, options, mcpTarget) {
       version,
       integrity,
       sdk: { version: SDK_ADAPTER_VERSION, integrity: SDK_ADAPTER_INTEGRITY },
+      ...(options.hookPlatform ? { platform: options.hookPlatform } : {}),
       ...(typeof options.mcpRuntimeInstall === 'function' ? { npmInstall: options.mcpRuntimeInstall } : {}),
       ...(options.mcpRuntimeNode ? { nodePath: options.mcpRuntimeNode } : {}),
       // One line on stderr before npm runs, so the wait is never silent (stdout stays clean
@@ -4432,36 +4483,43 @@ function resolveMcpRuntime(detection, options, mcpTarget) {
       onProgress: typeof options.mcpRuntimeProgress === 'function' ? options.mcpRuntimeProgress : (text) => process.stderr.write(text),
     });
   }
-  return verifyMcpRuntime(home, version, integrity) || { state: 'absent', version };
+  return verifyMcpRuntime(home, version, integrity, options.hookPlatform ? { platform: options.hookPlatform } : {}) || { state: 'absent', version };
 }
 
-// Whether this project's managed hooks start the local runtime now, as its install chose.
-function projectHooksUseLocalRuntime(detection) {
+// Managed hook files that still start @getmarrow/mcp through npx (written by 0.1.68 or earlier,
+// or by hand): each needs a repair, which rewrites it in the local runtime form.
+function legacyNpxHookFiles(detection) {
   const paths = detection.paths || {};
-  return [paths.claudeSettings, paths.codexHooks, paths.cursorHooks, paths.windsurfHooks, paths.geminiSettings]
-    .some((filePath) => filePath && safeRead(filePath).includes('/.marrow/runtime/mcp/'));
+  return [paths.claudeSettings, paths.codexHooks, paths.cursorHooks, paths.windsurfHooks, paths.geminiSettings,
+    paths.grokHooks, paths.clinePreToolUseHook, paths.clinePostToolUseHook, paths.clineTaskCancelHook]
+    .filter((filePath, index, all) => filePath && all.indexOf(filePath) === index && hookTextUsesNpx(safeRead(filePath)))
+    // The Marrow MCP server entry too (F-I1): npx there would start a copy planted in the project.
+    .concat([paths.mcpJson, paths.cursorMcp].filter((filePath, index, all) => filePath && all.indexOf(filePath) === index
+      && mcpServerUsesNpx(safeJsonObject(filePath))));
 }
 
-// The controller's maintenance rewrites managed hooks for the pinned MCP and keeps each project
-// in the form its install chose: on the verified local runtime for that version when the
-// project's hooks start it (verify only: maintenance never installs), on npx otherwise. A
-// project installed with --no-local-runtime stays on npx even when another project's install
-// put a runtime on this machine.
+// The controller's maintenance rewrites managed hooks for the pinned MCP, always in the local
+// runtime form; it only verifies the copy (maintenance never installs one).
 function maintenanceMcpRuntime(detection, options = {}) {
-  if (options.mcpLocalRuntime === false || !projectHooksUseLocalRuntime(detection)) return null;
   const runtime = resolveMcpRuntime(detection, { ...options, maintenance: true, yes: false }, executableMcpTarget(options));
   return runtime.version && ['present', 'installed', 'verified'].includes(runtime.state) ? runtime : null;
 }
 
-function mcpRuntimeReport(runtime) {
+function mcpRuntimeReport(runtime, { legacyNpxHooks = [], switchIgnored = false } = {}) {
   if (!runtime) return null;
+  const verified = Boolean(runtime.directory && ['present', 'installed', 'verified'].includes(runtime.state));
   return {
     state: runtime.state,
     version: runtime.version || null,
     path: runtime.directory || null,
     ...(runtime.reason ? { reason: runtime.reason } : {}),
     ...(runtime.removed_versions?.length ? { removed_versions: runtime.removed_versions } : {}),
-    hooks_start: runtime.directory && ['present', 'installed', 'verified'].includes(runtime.state) ? 'local_runtime' : 'npx',
+    // Hooks never start npx: without a verified copy they install the pinned one themselves on
+    // their next start, and pre-action hooks hold the call only when that fails.
+    hooks_start: verified ? 'local_runtime' : 'self_heal_on_next_start',
+    ...(legacyNpxHooks.length ? { legacy_npx_hooks: legacyNpxHooks } : {}),
+    needs_repair: !verified || legacyNpxHooks.length > 0,
+    ...(switchIgnored ? { local_runtime_switch: 'ignored' } : {}),
   };
 }
 
@@ -4513,7 +4571,7 @@ async function install(options) {
   options.mcpTargetVersion = mcpTarget.version;
   // A maintenance pass keeps the project's hooks in the form its install chose.
   const mcpRuntime = options.maintenance === true
-    ? maintenanceMcpRuntime(detection, options) || { state: options.mcpLocalRuntime === false ? 'disabled' : 'absent', version: mcpTarget.version }
+    ? maintenanceMcpRuntime(detection, options) || { state: 'absent', version: mcpTarget.version }
     : resolveMcpRuntime(detection, options, mcpTarget);
   options.mcpRuntime = mcpRuntime.version && ['present', 'installed', 'verified'].includes(mcpRuntime.state) ? mcpRuntime : null;
   const plan = buildPlan(detection, options);
@@ -4775,7 +4833,7 @@ async function install(options) {
     harnessReload,
     firstCapture: firstCapturePath(detection),
     hermes,
-    mcp_runtime: mcpRuntimeReport(mcpRuntime),
+    mcp_runtime: mcpRuntimeReport(mcpRuntime, { legacyNpxHooks: legacyNpxHookFiles(detection), switchIgnored: options.localRuntimeSwitchIgnored === true }),
     changes,
     doctor: {
       active: Boolean(!selfTest.skipped && selfTest.active),