@getmarrow/install 0.1.40 → 0.1.41

package/README.md

@@ -91,7 +91,17 @@ 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.40
+## What's New in v0.1.41
+
+v0.1.41 makes stale client detection and recovery part of normal installation health:
+
+- `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;
+- 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.40
 
 v0.1.40 binds governed runs to a privacy-safe workspace fingerprint and separates observed execution from verified completion:
 
@@ -99,7 +109,7 @@ v0.1.40 binds governed runs to a privacy-safe workspace fingerprint and separate
 - 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;
-- certified hook commands pin MCP `3.9.56` and SDK `3.7.55` so advertised behavior matches the deployed server contract;
+- 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;
 - the integration matrix now reports prompt injection, pre-action, action result, closure, proof, cached brief, restart survival, evidence adapter, and safe repair separately.

package/package.json

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

package/src/installer.js

@@ -8,9 +8,9 @@ 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.56';
-const SDK_ADAPTER_VERSION = '3.7.55';
-const SDK_ADAPTER_INTEGRITY = 'sha512-aq8g3srJ9EFZVvskSQVE9MLUS8SSkvx3xY3Mr9G0ZkpKxiiDBQaa3r2pb/u74BYGVvJRP6EP/oV/D9jbKb2lBA==';
+const MCP_ADAPTER_VERSION = '3.9.57';
+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`;
@@ -42,6 +42,116 @@ const HARNESS_CAPABILITY_REGISTRY = Object.freeze([
   { client: 'custom', capability_level: 'event_contract', automatic: [], install_surface: 'event_contract' },
 ]);
 
+function explicitMcpVersion(command) {
+  const match = String(command || '').match(/@getmarrow\/mcp@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+  return match ? match[1] : null;
+}
+
+function readMcpPackageVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(pkg.version)
+      ? pkg.version
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function packageMcpVersion(command) {
+  const normalized = String(command || '').replace(/\0/g, ' ');
+  const packageRoots = [];
+  for (const match of normalized.matchAll(/(\/[^\s]+\/node_modules\/@getmarrow\/mcp)(?:\/|\s|$)/g)) {
+    packageRoots.push(match[1]);
+  }
+  for (const match of normalized.matchAll(/(\/[^\s]+\/node_modules\/\.bin\/marrow-mcp)(?:\s|$)/g)) {
+    const binPath = match[1];
+    packageRoots.push(path.resolve(path.dirname(binPath), '..', '@getmarrow', 'mcp'));
+    try {
+      const resolved = fs.realpathSync(binPath);
+      const marker = `${path.sep}node_modules${path.sep}@getmarrow${path.sep}mcp${path.sep}`;
+      const markerIndex = resolved.indexOf(marker);
+      if (markerIndex >= 0) packageRoots.push(resolved.slice(0, markerIndex + marker.length - 1));
+    } catch {
+      // The derived package root still gives a deterministic best-effort lookup.
+    }
+  }
+  for (const packageRoot of [...new Set(packageRoots)]) {
+    const version = readMcpPackageVersion(packageRoot);
+    if (version) return version;
+  }
+  return null;
+}
+
+function isMcpProcessCommand(command) {
+  const raw = String(command || '');
+  const args = (raw.includes('\0') ? raw.split('\0') : raw.trim().split(/\s+/)).filter(Boolean);
+  if (!args.length) return false;
+
+  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;
+
+  if (executable === 'node'
+    && args[1]
+    && /(?:^|\/)node_modules\/(?:@getmarrow\/mcp(?:\/|$)|\.bin\/marrow-mcp$)/.test(args[1])) {
+    return true;
+  }
+
+  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));
+}
+
+function readLinuxProcessCommands(procRoot = '/proc') {
+  if (process.platform !== 'linux') return [];
+  try {
+    return fs.readdirSync(procRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && /^\d+$/.test(entry.name))
+      .map((entry) => {
+        try {
+          return fs.readFileSync(path.join(procRoot, entry.name, 'cmdline'), 'utf8');
+        } catch {
+          return '';
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function inspectMcpProcesses(options = {}) {
+  const commands = Array.isArray(options.commands)
+    ? options.commands.map(String)
+    : readLinuxProcessCommands(options.procRoot);
+  const active = commands
+    .filter(isMcpProcessCommand)
+    .map((command) => explicitMcpVersion(command) || packageMcpVersion(command) || 'unknown');
+  const versions = [...new Set(active.filter((version) => version !== 'unknown'))].sort();
+  const unknownVersionProcesses = active.filter((version) => version === 'unknown').length;
+  const staleVersions = versions.filter((version) => version !== MCP_ADAPTER_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 @getmarrow/mcp@${MCP_ADAPTER_VERSION} setup`;
+  return {
+    available: process.platform === 'linux' || Array.isArray(options.commands),
+    expected_version: MCP_ADAPTER_VERSION,
+    active_processes: active.length,
+    active_versions: versions,
+    unknown_version_processes: unknownVersionProcesses,
+    stale_versions: staleVersions,
+    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,
+    verification_command: needsRepair ? 'npx -y @getmarrow/install@latest doctor' : null,
+  };
+}
+
 function sourceClient() {
   const raw = String(process.env.MARROW_CLIENT || process.env.MARROW_HARNESS || process.env.MARROW_AGENT_CLIENT || '').trim().toLowerCase().replace(/\s+/g, '-').replace(/^@/, '');
   const aliases = {
@@ -1530,6 +1640,13 @@ function printReport(report) {
     process.stdout.write(`- missing env: ${report.doctor.missingEnv.length ? report.doctor.missingEnv.join(', ') : 'none'}\n`);
     if (report.doctor.envHints.length) process.stdout.write(`- possible env files: ${report.doctor.envHints.join(', ')}\n`);
     process.stdout.write(`- missing hooks/config: ${report.doctor.missingHooks.length ? report.doctor.missingHooks.join('; ') : 'none'}\n`);
+    if (report.doctor.mcpProcesses?.available) {
+      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.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.recommendedFix) process.stdout.write(`- recommended fix: ${report.doctor.recommendedFix}\n`);
     process.stdout.write(`- live health: ${report.doctor.healthCommand}\n`);
   }
@@ -1590,6 +1707,7 @@ async function install(options) {
     ? repairConfigDiagnostics(configDiagnostics)
     : [];
   const envHints = options.apiKey ? [] : findLikelyEnvFiles(detection);
+  const mcpProcesses = inspectMcpProcesses({ commands: options.processCommands });
   let selfTest;
   try {
     selfTest = await runSelfTest(options);
@@ -1681,7 +1799,8 @@ async function install(options) {
       missingEnv: options.apiKey ? [] : ['MARROW_API_KEY'],
       envHints,
       missingHooks: changes.filter((change) => change.changed).map((change) => change.label),
-      recommendedFix: configDiagnostics.npm_token.recommended_fix || (!options.apiKey
+      mcpProcesses,
+      recommendedFix: mcpProcesses.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.'
@@ -1694,9 +1813,14 @@ async function install(options) {
     sdkDependency,
     controller,
     selfTest,
-    warnings: 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.']
-      : [],
+    warnings: [
+      ...(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
+        ? ['Stale, mixed, or version-unknown Marrow MCP clients are active. Run the exact repair command, then restart every owning harness.']
+        : []),
+    ],
   };
 }
 
@@ -1725,6 +1849,7 @@ module.exports = {
   passiveRuntimeSource,
   inspectNpmTokenConfig,
   inspectSdkDependency,
+  inspectMcpProcesses,
   buildInstallValueMoment,
   buildTokenValueProof,
   stableAgentId,