@getmarrow/install 0.1.39 → 0.1.41

package/README.md

@@ -91,15 +91,28 @@ 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.39
+## What's New in v0.1.41
 
-v0.1.39 installs the bounded one-call passive read contract from day one:
+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:
 
 - 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;
-- certified hook commands pin MCP `3.9.55` and SDK `3.7.54` 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.
 
 It preserves the intervention receipts introduced in v0.1.38.
 
@@ -280,12 +293,12 @@ These are integration surfaces for one Marrow product, not separate products.
 
 Run `npx @getmarrow/install integrations --json` for the machine-readable matrix. The table below intentionally distinguishes full automatic interception from MCP-routed, wrapper-bounded, and adapter-required coverage.
 
-| Harnesses | Pre-action | Result | Outcome closure | Proof enforcement | Safe repair |
-| --- | --- | --- | --- | --- | --- |
-| Claude Code | Automatic native hook | Automatic native hook | Correlated when determinable | Automatic for protected actions | Managed config after activation |
-| Cursor, Composer, Cline, Windsurf | MCP-routed | MCP-routed | MCP-routed | Explicit or governed runner | Managed config after activation |
-| Codex, OpenCode, Gemini, Grok, DeepSeek, Qwen, Kimi, MiniMax, GLM | Automatic inside governed runner | Automatic inside governed runner | Automatic when result is known | Automatic for protected actions | Managed config after activation |
-| Hermes, OpenClaw, custom harnesses | Adapter required | Adapter required | Adapter required | Adapter required | Adapter owned |
+| Harnesses | Prompt / pre-action / result | Closure and proof | Cached brief | Restart survival | Evidence adapter | Safe repair |
+| --- | --- | --- | --- | --- | --- | --- |
+| Claude Code | Automatic native hooks | Correlated when determinable; protected proof enforced | Owner-only bounded cache | Installed config and durable spool | Native hook evidence | Managed config after activation |
+| Cursor, Composer, Cline, Windsurf | MCP-routed only | MCP-routed; explicit or governed proof | Owner-only MCP cache | MCP config and durable spool | MCP lifecycle evidence | Managed config after activation |
+| Codex, OpenCode, Gemini, Grok, DeepSeek, Qwen, Kimi, MiniMax, GLM | Automatic only inside governed runner | Automatic when result is known; protected proof enforced | Runner/runtime cache | Activated controller and durable buffer | Command, test, deployment, or owner evidence | Managed config after activation |
+| Hermes, OpenClaw, custom harnesses | Lifecycle adapter required | Adapter or governed runner required | Adapter dependent | Adapter dependent | Adapter supplied | Adapter owned |
 
 For native hooks, a successful tool exit is not treated as a successful business outcome when proof is missing. MCP coverage includes only actions routed through that MCP client. Governed-runner coverage includes only commands launched through the runner. Event-contract integrations must emit the documented lifecycle themselves.
 

package/package.json

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

package/src/governed-runner.js

@@ -319,7 +319,7 @@ function detectProjectSignals(cwd = process.cwd()) {
     }
   }
 
-  return {
+  const project = {
     name: packageJson?.name || path.basename(cwd),
     key: packageJson?.name || path.basename(cwd),
     type: packageJson ? 'node' : fs.existsSync(path.join(cwd, 'pyproject.toml')) ? 'python' : 'workspace',
@@ -328,6 +328,15 @@ function detectProjectSignals(cwd = process.cwd()) {
     package_scripts: packageScripts.slice(0, 30),
     config_files: configFiles.slice(0, 30),
   };
+  project.fingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    name: project.name,
+    type: project.type,
+    frameworks: [...project.frameworks].sort(),
+    signals: [...project.signals].sort(),
+    package_scripts: [...project.package_scripts].sort(),
+    config_files: [...project.config_files].sort(),
+  })).digest('hex');
+  return project;
 }
 
 function isRisky(text, type) {
@@ -525,12 +534,25 @@ function proofFromFile(filePath) {
 
 function defaultProof(input) {
   const proof = proofFromFile(input.options.proofFile) || {};
+  const command = redactedCommand(input.childCommand || []);
+  const verificationCommand = /\b(test|smoke|check|verify|lint|typecheck|audit)\b/i.test(command);
+  const suppliedChecks = Array.isArray(proof.checks) && proof.checks.length > 0;
+  const evidenceState = typeof proof.evidence_state === 'string'
+    ? proof.evidence_state
+    : input.success && (suppliedChecks || verificationCommand)
+    ? 'verified'
+    : input.success
+    ? 'observed_only'
+    : 'failed';
   return {
     summary: proof.summary || `Marrow governed runner completed ${input.action}.`,
-    checks: Array.isArray(proof.checks) ? proof.checks : ['marrow runtime gate', 'command exit captured'],
+    checks: suppliedChecks ? proof.checks : [`command_exit_code=${Number(input.exitCode)}`],
+    evidence_source: proof.evidence_source || (verificationCommand ? 'verification_command_result' : 'governed_command_result'),
+    evidence_state: evidenceState,
+    verified_completion: evidenceState === 'verified',
     outcome: proof.outcome || (input.success ? 'success' : 'failure'),
     blockers: Array.isArray(proof.blockers) ? proof.blockers : [],
-    command: redactedCommand(input.childCommand || []),
+    command,
     exit_code: input.exitCode,
     runner: '@getmarrow/install run',
     profile: input.options.profile,
@@ -544,11 +566,14 @@ async function preflightRuntime(options, action, type, commandText) {
   const target = options.target || commandText || action;
   const surfaces = inferSurfaces(commandText || action);
   const meta = sourceMeta(options, 'runtime', { action, command: commandText, action_type: type });
+  const project = detectProjectSignals(options.root || process.cwd());
   return requestJson(options, 'POST', '/v1/agent/runtime', {
     action,
     type,
     target,
     surfaces,
+    harness: sourceClient(options.client),
+    project: { ...project, harness: sourceClient(options.client) },
     source_meta: meta,
     context: {
       runner: '@getmarrow/install run',
@@ -1398,6 +1423,15 @@ function integrationCoverageMatrix() {
       harness: entry.client,
       capability_level: entry.capability_level,
       install_surface: entry.install_surface,
+      prompt_injection: native
+        ? 'automatic_native_hook'
+        : wrapper
+          ? 'automatic_in_governed_runner'
+          : sdk
+            ? 'automatic_in_sdk_runtime'
+            : routed
+              ? 'mcp_routed'
+              : 'adapter_required',
       pre_action: native
         ? 'automatic_native_hook'
         : wrapper
@@ -1429,6 +1463,15 @@ function integrationCoverageMatrix() {
           ? 'explicit_or_governed_wrapper'
           : 'adapter_required',
       automatic_repair: native || routed || sdk || wrapper ? 'installer_managed_config_only' : 'adapter_owned',
+      cached_brief: native || routed ? 'mcp_local_last_known' : wrapper || sdk ? 'server_cache_only' : 'adapter_owned',
+      restart_survival: native || routed || sdk || wrapper ? 'installer_managed_credentials_and_hooks' : 'adapter_owned',
+      evidence_adapter: native
+        ? 'tool_result_and_explicit_verification'
+        : routed
+          ? 'mcp_tool_and_explicit_verification'
+          : wrapper || sdk
+            ? 'command_exit_and_verification_command'
+            : 'adapter_owned',
       limitation: native
         ? 'A successful tool exit is not treated as a successful business outcome when the result cannot be proven.'
         : routed
@@ -2272,6 +2315,7 @@ module.exports = {
   commandForSelection,
   buildGovernState,
   detectProjectSignals,
+  defaultProof,
   recommendGovernanceMode,
   recordGovernanceModeSelection,
   gateDecision,

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.55';
-const SDK_ADAPTER_VERSION = '3.7.54';
-const SDK_ADAPTER_INTEGRITY = 'sha512-KMgZEZpKo0AVKimXi4/SmtyPDV3mfx9hrj5drCdZxdNP8P/FL7ciyvyAEGiiXIMemh5Z3D/PUUvVO4jhr16ozQ==';
+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,