@getmarrow/install 0.1.42 → 0.1.43

package/README.md

@@ -71,7 +71,7 @@ npx -y @getmarrow/install@latest activate
 npx -y @getmarrow/install@latest doctor
 
 # Measured API read health and local backlog
-npx -y @getmarrow/mcp@latest ping
+npx -y --package=@getmarrow/mcp@latest marrow-mcp ping
 
 # Use only when doctor reports drift
 npx -y @getmarrow/install@latest --repair
@@ -91,16 +91,21 @@ npx @getmarrow/install controller stop
 
 Persistent controller lifecycle is currently Linux-only. On macOS or Windows, activation still installs and verifies the supported hooks without starting or signaling a background process; 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.42
+## What's New in v0.1.43
 
-v0.1.42 keeps stale client detection and recovery deterministic even when other Marrow MCP clients are running on the installation host:
+v0.1.43 hardens the MCP control path and makes stale client recovery explicit:
 
-- `doctor` detects active stale, mixed, or version-unknown Marrow MCP processes, including direct `node_modules/.bin/marrow-mcp` launches, without exposing command lines or credentials;
-- when repair is needed, `doctor` reports the executable pinned setup command, the separate owning-harness restart requirement, and the executable verification command; it does not terminate harness processes itself;
-- certified hooks pin MCP `3.9.57` and SDK `3.7.56` so the installed runtime matches the advertised control contract;
+- `doctor` detects active and configured stale, mixed, or version-unknown Marrow MCP clients without exposing command lines, file paths, configuration contents, or credentials;
+- every generated MCP launch and hook uses the package-explicit `npx --package ... marrow-mcp` form so npm can resolve the executable reliably;
+- when repair is needed, `doctor` reports the pinned setup command, the separate owning-harness restart requirement, and a self-test verification command; it does not terminate harness processes itself;
+- certified hooks pin MCP `3.9.59` and SDK `3.7.56` so the installed runtime matches the advertised control contract;
 - existing harnesses retain their honest coverage level: native hooks where supported, MCP calls where available, and governed wrappers or event contracts elsewhere;
 - package upgrades remain operator-approved and never rotate keys or rewrite unrelated configuration.
 
+## Previous: v0.1.42
+
+v0.1.42 added deterministic active-process detection, including direct `node_modules/.bin/marrow-mcp` launches, while keeping repair operator-approved.
+
 ## Previous: v0.1.40
 
 v0.1.40 binds governed runs to a privacy-safe workspace fingerprint and separates observed execution from verified completion:
@@ -108,7 +113,7 @@ v0.1.40 binds governed runs to a privacy-safe workspace fingerprint and separate
 - ordinary prompts receive one compact context read; risky or mutating prompts receive one fresh runtime gate instead;
 - passive prompt telemetry is buffered locally rather than delaying the agent turn;
 - transient read failures can use clearly labeled owner-only last-known guidance, while authentication failures never use cache;
-- `doctor` prints the exact `npx -y @getmarrow/mcp@latest ping` command for measured current/p50/p99 latency, last success, and backlog health;
+- `doctor` prints the exact `npx -y --package=@getmarrow/mcp@latest marrow-mcp ping` command for measured current/p50/p99 latency, last success, and backlog health;
 - certified hook commands pin MCP `3.9.56` and SDK `3.7.55` so advertised behavior matches that release's deployed server contract;
 - governed runtime requests attach a stable privacy-safe project fingerprint and harness label without sending the raw working-directory path;
 - successful command exit remains observed execution, not verified business completion, unless a verification command or explicit proof file supplies evidence;

package/package.json

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

package/src/governed-runner.js

@@ -1387,11 +1387,11 @@ const GENERIC_GOVERNED_COMMAND = 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/ins
 function localSupportedHarnesses() {
   const harnesses = [
     { display_name: 'OpenAI Codex', client_label: 'codex', category: 'agent_harness', support_level: 'governed_runner', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent codex-prod -- codex' },
-    { display_name: 'Claude Code', client_label: 'claude-code', category: 'agent_harness', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
-    { display_name: 'Cursor', client_label: 'cursor', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
-    { display_name: 'Cursor Composer', client_label: 'composer', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
-    { display_name: 'Windsurf', client_label: 'windsurf', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
-    { display_name: 'Cline', client_label: 'cline', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
+    { display_name: 'Claude Code', client_label: 'claude-code', category: 'agent_harness', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx -y --package=@getmarrow/mcp@latest marrow-mcp setup' },
+    { display_name: 'Cursor', client_label: 'cursor', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx -y --package=@getmarrow/mcp@latest marrow-mcp setup' },
+    { display_name: 'Cursor Composer', client_label: 'composer', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx -y --package=@getmarrow/mcp@latest marrow-mcp setup' },
+    { display_name: 'Windsurf', client_label: 'windsurf', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx -y --package=@getmarrow/mcp@latest marrow-mcp setup' },
+    { display_name: 'Cline', client_label: 'cline', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx -y --package=@getmarrow/mcp@latest marrow-mcp setup' },
     { display_name: 'OpenCode', client_label: 'opencode', category: 'agent_harness', support_level: 'governed_runner', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent opencode-prod -- opencode' },
     { display_name: 'Hermes Agent', client_label: 'hermes', category: 'agent_harness', support_level: 'first_class_addon', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install hermes' },
     { display_name: 'OpenClaw', client_label: 'openclaw', category: 'agent_harness', support_level: 'first_class_addon', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install openclaw' },
@@ -1402,7 +1402,7 @@ function localSupportedHarnesses() {
     { display_name: 'Kimi', client_label: 'kimi', category: 'model_cli', support_level: 'governed_runner', install_command: GENERIC_GOVERNED_COMMAND },
     { display_name: 'MiniMax', client_label: 'minimax', category: 'model_cli', support_level: 'governed_runner', install_command: GENERIC_GOVERNED_COMMAND },
     { display_name: 'GLM', client_label: 'glm', category: 'model_cli', support_level: 'governed_runner', install_command: GENERIC_GOVERNED_COMMAND },
-    { display_name: 'MCP-compatible clients', client_label: 'mcp', category: 'mcp_client', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
+    { display_name: 'MCP-compatible clients', client_label: 'mcp', category: 'mcp_client', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx -y --package=@getmarrow/mcp@latest marrow-mcp setup' },
     { display_name: 'CI scripts and deploy runners', client_label: 'ci', category: 'ci_runner', support_level: 'governed_runner', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent ci-release --profile production --policy enforce -- <ci-or-deploy-command>' },
     { display_name: 'Custom shell/API harness', client_label: 'custom', category: 'custom_runner', support_level: 'event_contract', install_command: 'POST /v1/agent/integrations/events with harness, event_type, agent_id, and action' },
   ];

package/src/installer.js

@@ -8,15 +8,15 @@ const { controllerStatus, controllerSupportedPlatform, ensureGovernanceControlle
 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.57';
+const MCP_ADAPTER_VERSION = '3.9.59';
 const SDK_ADAPTER_VERSION = '3.7.56';
 const SDK_ADAPTER_INTEGRITY = 'sha512-5htliY4wfn8a1mbLT9N4OWXqhp9fWzMHuAQgUetc3RUKjOes5mWB3t91/leRKFRRIgCnEczJN6jHXg7Aw489Mw==';
 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 MCP_CONTEXT_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} context-hook`;
-const MCP_PRE_ACTION_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} pre-action-hook`;
-const MCP_ACTION_RESULT_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} hook`;
-const MCP_SESSION_END_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} session-hook`;
+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`;
+const MCP_SESSION_END_HOOK_COMMAND = `npx -y --package=${MCP_PACKAGE_SPEC} marrow-mcp session-hook`;
 const NATIVE_HOOK_MATCHER = 'Bash|Edit|Write|MultiEdit|mcp__(?!marrow_).*';
 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']);
@@ -101,7 +101,7 @@ function isMcpProcessCommand(command) {
   const packageManagers = new Set(['bun', 'bunx', 'npm', 'npm-cli.js', 'npx', 'npx-cli.js', 'pnpm', 'pnpx', 'yarn']);
   const runner = executable === 'node' && args[1] ? path.basename(args[1]) : executable;
   return packageManagers.has(runner)
-    && args.some((arg) => /^@getmarrow\/mcp(?:@[^\s]+)?$/.test(arg));
+    && args.some((arg) => /^(?:--package=)?@getmarrow\/mcp(?:@[^\s]+)?$/.test(arg));
 }
 
 function readLinuxProcessCommands(procRoot = '/proc') {
@@ -135,7 +135,7 @@ function inspectMcpProcesses(options = {}) {
   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 @getmarrow/mcp@${MCP_ADAPTER_VERSION} setup`;
+  const repairCommand = `npx -y --package=@getmarrow/mcp@${MCP_ADAPTER_VERSION} marrow-mcp setup`;
   return {
     available: process.platform === 'linux' || Array.isArray(options.commands),
     expected_version: MCP_ADAPTER_VERSION,
@@ -148,7 +148,59 @@ function inspectMcpProcesses(options = {}) {
     exact_fix: needsRepair ? repairCommand : null,
     restart_required: needsRepair,
     restart_instruction: needsRepair ? 'Restart every owning harness to replace its active Marrow MCP process.' : null,
-    verification_command: needsRepair ? 'npx -y @getmarrow/install@latest doctor' : null,
+    verification_command: needsRepair ? 'npx -y @getmarrow/install@latest doctor --self-test' : 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?.claudeSettings,
+    detection?.paths?.cursorMcp,
+    detection?.paths?.mcpJson,
+    path.join(home, '.claude', 'settings.json'),
+    path.join(home, '.claude.json'),
+    path.join(home, '.cursor', 'mcp.json'),
+    path.join(home, '.mcp.json'),
+  ];
+  const versions = [];
+  let filesChecked = 0;
+  let configurationsFound = 0;
+  let unknownVersionConfigurations = 0;
+  for (const filePath of [...new Set(configuredPaths.filter(Boolean).map((entry) => path.resolve(String(entry))))]) {
+    try {
+      if (!fs.existsSync(filePath)) continue;
+      const stat = fs.lstatSync(filePath);
+      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)) {
+        configurationsFound += 1;
+        if (specs.length === 0) unknownVersionConfigurations += 1;
+      }
+      versions.push(...specs);
+    } catch {
+      // Doctor remains read-only and ignores inaccessible or malformed owner configuration.
+    }
+  }
+  const configuredVersions = [...new Set(versions)].sort();
+  const staleVersions = configuredVersions.filter((version) => version !== MCP_ADAPTER_VERSION);
+  const mixedVersions = configuredVersions.length > 1
+    || (configuredVersions.length > 0 && unknownVersionConfigurations > 0);
+  const healthy = staleVersions.length === 0 && !mixedVersions && unknownVersionConfigurations === 0;
+  return {
+    expected_version: MCP_ADAPTER_VERSION,
+    files_checked: filesChecked,
+    configurations_found: configurationsFound,
+    configured_versions: configuredVersions,
+    unknown_version_configurations: unknownVersionConfigurations,
+    stale_versions: staleVersions,
+    mixed_versions: mixedVersions,
+    healthy,
+    exact_fix: healthy ? null : `Run npx -y --package=@getmarrow/mcp@${MCP_ADAPTER_VERSION} marrow-mcp setup in each owning workspace, update its MCP launch to npx -y --package=@getmarrow/mcp@${MCP_ADAPTER_VERSION} marrow-mcp, then restart that harness.`,
+    verification_command: healthy ? null : 'npx -y @getmarrow/install@latest doctor --self-test',
   };
 }
 
@@ -549,7 +601,7 @@ function passiveInstructions() {
 
 Marrow should run passively after install:
 
-- Use MCP hooks when available: \`npx -y @getmarrow/mcp setup\`.
+- Use MCP hooks when available: \`npx -y --package=@getmarrow/mcp@latest marrow-mcp setup\`.
 - Use SDK passive runtime in owned Node processes: \`createPassiveRuntime().install()\`.
 - Keep passive token/model usage proof enabled so Marrow can show token, cost, latency, and workflow savings after real work completes.
 - Before risky work, use Marrow's decision brief or passive prompt hook.
@@ -674,7 +726,7 @@ function exactHookDescriptors(settings, eventName, command, matcher) {
 function marrowHookSubcommand(command) {
   if (typeof command !== 'string') return null;
   const match = command.trim().match(
-    /^npx\s+(?:-y\s+)?@getmarrow\/mcp(?:@[^\s]+)?\s+(context-hook|pre-action-hook|hook|session-hook)$/,
+    /^npx\s+(?:-y\s+)?(?:--package=@getmarrow\/mcp(?:@[^\s]+)?\s+marrow-mcp|@getmarrow\/mcp(?:@[^\s]+)?)\s+(context-hook|pre-action-hook|hook|session-hook)$/,
   );
   return match?.[1] || null;
 }
@@ -839,7 +891,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 ${MCP_PACKAGE_SPEC}`
+    && config.mcpServers.marrow.args.join(' ') === `-y --package=${MCP_PACKAGE_SPEC} marrow-mcp`
   ))) observedHooks.push('mcp_tool_calls');
   const fingerprintMaterial = changes
     .filter((change) => change.applied || change.already_present)
@@ -877,7 +929,7 @@ function upsertMcpServerConfig(filePath) {
     : {};
   servers.marrow = {
     command: 'npx',
-    args: ['-y', MCP_PACKAGE_SPEC],
+    args: ['-y', `--package=${MCP_PACKAGE_SPEC}`, 'marrow-mcp'],
     env: {
       MARROW_API_KEY: '${MARROW_API_KEY}',
       MARROW_BASE_URL: '${MARROW_BASE_URL}',
@@ -1647,6 +1699,11 @@ function printReport(report) {
       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;
+      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 (report.doctor.recommendedFix) process.stdout.write(`- recommended fix: ${report.doctor.recommendedFix}\n`);
     process.stdout.write(`- live health: ${report.doctor.healthCommand}\n`);
   }
@@ -1708,6 +1765,7 @@ async function install(options) {
     : [];
   const envHints = options.apiKey ? [] : findLikelyEnvFiles(detection);
   const mcpProcesses = inspectMcpProcesses({ commands: options.processCommands });
+  const mcpConfigurations = inspectMcpConfigurations(detection, { paths: options.mcpConfigPaths });
   let selfTest;
   try {
     selfTest = await runSelfTest(options);
@@ -1800,12 +1858,13 @@ async function install(options) {
       envHints,
       missingHooks: changes.filter((change) => change.changed).map((change) => change.label),
       mcpProcesses,
-      recommendedFix: mcpProcesses.exact_fix || configDiagnostics.npm_token.recommended_fix || (!options.apiKey
+      mcpConfigurations,
+      recommendedFix: 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.'
         : controller.exact_fix || selfTest.recommended_fix || null),
-      healthCommand: 'npx -y @getmarrow/mcp@latest ping',
+      healthCommand: 'npx -y --package=@getmarrow/mcp@latest marrow-mcp ping',
     },
     remediation,
     configDiagnostics,
@@ -1820,6 +1879,9 @@ async function install(options) {
       ...(!mcpProcesses.healthy
         ? ['Stale, mixed, or version-unknown Marrow MCP clients are active. Run the exact repair command, then restart every owning harness.']
         : []),
+      ...(!mcpConfigurations.healthy
+        ? ['Stale, mixed, or version-unknown Marrow MCP versions remain in owner configuration. Repair each owning workspace and restart its harness.']
+        : []),
     ],
   };
 }
@@ -1850,6 +1912,7 @@ module.exports = {
   inspectNpmTokenConfig,
   inspectSdkDependency,
   inspectMcpProcesses,
+  inspectMcpConfigurations,
   buildInstallValueMoment,
   buildTokenValueProof,
   stableAgentId,