@getmarrow/install 0.1.35 → 0.1.37

package/src/installer.js

@@ -3,13 +3,14 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 const { version: INSTALLER_ADAPTER_VERSION } = require('../package.json');
+const { controllerStatus, controllerSupportedPlatform, ensureGovernanceController } = require('./controller-manager');
 
 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.51';
-const SDK_ADAPTER_VERSION = '3.7.50';
-const SDK_ADAPTER_INTEGRITY = 'sha512-TyCXUKZAaKRPdfVqXEuIvWnOt4GLcIUbwhpX+EopzdALNzq+t5wUGHrqJlkNSvopppPTTdFVLJ7O1vtwofqFqw==';
+const MCP_ADAPTER_VERSION = '3.9.53';
+const SDK_ADAPTER_VERSION = '3.7.52';
+const SDK_ADAPTER_INTEGRITY = 'sha512-dMo5rMXP5sFTRsiRI+Oe3SOWgSsi8TTt9VrYL9gC71EQFN2UTtuH914CkYEpcS627sb02jXrUDiXxznX/2fWgA==';
 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`;
@@ -18,7 +19,7 @@ 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 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', 'custom', 'unknown']);
+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']);
 const HARNESS_CAPABILITY_REGISTRY = Object.freeze([
   { client: 'claude-code', capability_level: 'native_hooks', automatic: ['prompt', 'pre_action', 'action_result', 'session_end'], install_surface: 'mcp' },
   { client: 'cursor', capability_level: 'mcp', automatic: ['mcp_tool_calls'], install_surface: 'mcp' },
@@ -36,6 +37,8 @@ const HARNESS_CAPABILITY_REGISTRY = Object.freeze([
   { client: 'kimi', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
   { client: 'minimax', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
   { client: 'glm', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
+  { client: 'mcp', capability_level: 'mcp', automatic: ['mcp_tool_calls'], install_surface: 'mcp' },
+  { client: 'ci', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
   { client: 'custom', capability_level: 'event_contract', automatic: [], install_surface: 'event_contract' },
 ]);
 
@@ -64,6 +67,9 @@ function sourceClient() {
     hermes: 'hermes',
     'hermes-agent': 'hermes',
     glm: 'glm',
+    mcp: 'mcp',
+    ci: 'ci',
+    'github-actions': 'ci',
   };
   return aliases[raw] || (SOURCE_CLIENTS.has(raw) ? raw : 'custom');
 }
@@ -83,6 +89,7 @@ function parseArgs(argv) {
     selfTestExplicitlyDisabled: false,
     json: false,
     activate: false,
+    controller: true,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -104,6 +111,7 @@ function parseArgs(argv) {
       options.selfTest = false;
       options.selfTestExplicitlyDisabled = true;
     }
+    else if (arg === '--no-controller') options.controller = false;
     else if (arg === '--self-test') options.selfTest = true;
     else if (arg === '--cwd') options.cwd = path.resolve(argv[++i] || options.cwd);
     else if (arg === '--mode') options.mode = argv[++i] || options.mode;
@@ -157,6 +165,7 @@ Options:
   --key <key>        Marrow API key for self-test. Prefer MARROW_API_KEY because CLI args can appear in process listings.
   --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-self-test     Skip API smoke/self-test
 `;
 }
@@ -291,6 +300,7 @@ function fingerprint(value) {
 function npmTokenPaths(env = process.env) {
   const home = env.HOME || env.USERPROFILE || os.homedir();
   return {
+    home,
     openclawEnv: path.join(home, '.openclaw', '.env'),
     credentialFile: path.join(home, '.openclaw', 'credentials', 'npm-getmarrow-token.txt'),
     npmrc: path.join(home, '.npmrc'),
@@ -301,7 +311,14 @@ function inspectNpmTokenConfig(env = process.env) {
   const paths = npmTokenPaths(env);
   const openclawToken = readEnvVar(paths.openclawEnv, 'NPM_TOKEN');
   const credentialToken = readFirstLineSecret(paths.credentialFile);
-  const npmrcToken = readNpmrcToken(paths.npmrc);
+  let npmrcToken = '';
+  let unsafeNpmrcPath = false;
+  try {
+    assertDirectOwnerFile(paths.home, paths.npmrc, { allowMissing: true });
+    npmrcToken = readNpmrcToken(paths.npmrc);
+  } catch {
+    unsafeNpmrcPath = true;
+  }
   const sourceToken = openclawToken || credentialToken;
   const mismatch = Boolean(sourceToken && npmrcToken && fingerprint(sourceToken) !== fingerprint(npmrcToken));
   const missingNpmrcToken = Boolean(sourceToken && !npmrcToken);
@@ -310,15 +327,18 @@ function inspectNpmTokenConfig(env = process.env) {
     safe: {
       npm_token: {
         checked: true,
-        repairable: Boolean(sourceToken && (mismatch || missingNpmrcToken)),
+        repairable: Boolean(sourceToken && (mismatch || missingNpmrcToken) && !unsafeNpmrcPath),
         mismatch,
         missing_npmrc_token: missingNpmrcToken,
+        unsafe_path: unsafeNpmrcPath,
         sources: {
           openclaw_env: { path: paths.openclawEnv, present: Boolean(openclawToken), fingerprint: fingerprint(openclawToken) },
           credential_file: { path: paths.credentialFile, present: Boolean(credentialToken), fingerprint: fingerprint(credentialToken) },
           npmrc: { path: paths.npmrc, present: Boolean(npmrcToken), fingerprint: fingerprint(npmrcToken) },
         },
-        recommended_fix: mismatch || missingNpmrcToken
+        recommended_fix: unsafeNpmrcPath
+          ? 'Refusing automatic npm token repair because ~/.npmrc or its home directory is not a direct, regular owner path.'
+          : mismatch || missingNpmrcToken
           ? 'Run npx @getmarrow/install --repair to sync ~/.npmrc from the active OpenClaw/getmarrow npm token source.'
           : null,
       },
@@ -327,7 +347,49 @@ function inspectNpmTokenConfig(env = process.env) {
   };
 }
 
-function upsertNpmrcToken(filePath, token) {
+function assertDirectOwnerFile(homePath, filePath, { allowMissing = false } = {}) {
+  const home = path.resolve(homePath);
+  const target = path.resolve(filePath);
+  if (target !== path.join(home, '.npmrc')) throw new Error('npm token repair target must be the direct owner ~/.npmrc');
+  if (!fs.existsSync(home)) throw new Error('npm token repair owner home does not exist');
+  const homeStat = fs.lstatSync(home);
+  if (!homeStat.isDirectory() || homeStat.isSymbolicLink() || fs.realpathSync(home) !== home) {
+    throw new Error('npm token repair owner home must be a direct, non-symbolic directory');
+  }
+  if (!fs.existsSync(target)) {
+    if (allowMissing) return;
+    throw new Error('npm token repair target does not exist');
+  }
+  const targetStat = fs.lstatSync(target);
+  if (targetStat.isSymbolicLink() || !targetStat.isFile()) {
+    throw new Error('npm token repair target must be a regular file, not a symbolic link');
+  }
+}
+
+function atomicWriteOwnerFile(homePath, filePath, contents) {
+  const home = path.resolve(homePath);
+  const target = path.resolve(filePath);
+  const allowMissing = !fs.existsSync(target);
+  assertDirectOwnerFile(home, target, { allowMissing });
+  const tempPath = path.join(home, `.npmrc.marrow-${process.pid}-${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(tempPath, 'wx', 0o600);
+    fs.writeFileSync(descriptor, contents, { encoding: 'utf8' });
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    assertDirectOwnerFile(home, target, { allowMissing });
+    fs.renameSync(tempPath, target);
+    fs.chmodSync(target, 0o600);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+  }
+}
+
+function upsertNpmrcToken(homePath, filePath, token) {
+  assertDirectOwnerFile(homePath, filePath, { allowMissing: true });
   const before = safeRead(filePath);
   const tokenLine = `//registry.npmjs.org/:_authToken=${token}`;
   let after;
@@ -338,14 +400,17 @@ function upsertNpmrcToken(filePath, token) {
     after = `${before}${separator}${tokenLine}\n`;
   }
   if (before !== after) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
     if (before) {
       const backupPath = `${filePath}.marrow-backup`;
-      fs.writeFileSync(backupPath, before, { mode: 0o600 });
+      if (fs.existsSync(backupPath) && fs.lstatSync(backupPath).isSymbolicLink()) {
+        throw new Error('npm token repair backup must not be a symbolic link');
+      }
+      const backupTemp = path.join(path.resolve(homePath), `.npmrc.marrow-backup-${process.pid}-${crypto.randomBytes(6).toString('hex')}.tmp`);
+      fs.writeFileSync(backupTemp, before, { mode: 0o600, flag: 'wx' });
+      fs.renameSync(backupTemp, backupPath);
       fs.chmodSync(backupPath, 0o600);
     }
-    fs.writeFileSync(filePath, after, { mode: 0o600 });
-    fs.chmodSync(filePath, 0o600);
+    atomicWriteOwnerFile(homePath, filePath, after);
   }
   return before !== after;
 }
@@ -355,7 +420,7 @@ function repairConfigDiagnostics(diagnostics, env = process.env) {
   const npm = diagnostics.npm_token;
   const repairs = [];
   if (npm?.repairable && inspection.raw.sourceToken) {
-    const changed = upsertNpmrcToken(inspection.raw.paths.npmrc, inspection.raw.sourceToken);
+    const changed = upsertNpmrcToken(inspection.raw.paths.home, inspection.raw.paths.npmrc, inspection.raw.sourceToken);
     repairs.push({
       type: 'npm_token_npmrc_sync',
       changed,
@@ -866,10 +931,69 @@ function buildPlan(detection, options) {
     });
   }
 
-  return { mode, writes };
+  return { mode, root: detection.root, writes };
+}
+
+function assertContainedManagedTarget(root, targetPath) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(targetPath);
+  if (resolvedTarget === resolvedRoot || !resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`Refusing installer write outside project root: ${resolvedTarget}`);
+  }
+  if (!fs.existsSync(resolvedRoot)) throw new Error(`Project root does not exist: ${resolvedRoot}`);
+  const rootStat = fs.lstatSync(resolvedRoot);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new Error(`Refusing installer write through unsafe project root: ${resolvedRoot}`);
+  }
+  const realRoot = fs.realpathSync(resolvedRoot);
+  const relativeParent = path.relative(resolvedRoot, path.dirname(resolvedTarget));
+  let current = resolvedRoot;
+  for (const segment of relativeParent.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`Refusing installer write through unsafe path component: ${current}`);
+    }
+    const realCurrent = fs.realpathSync(current);
+    if (realCurrent !== realRoot && !realCurrent.startsWith(`${realRoot}${path.sep}`)) {
+      throw new Error(`Refusing installer write outside resolved project root: ${current}`);
+    }
+  }
+  if (fs.existsSync(resolvedTarget)) {
+    const targetStat = fs.lstatSync(resolvedTarget);
+    if (targetStat.isSymbolicLink() || !targetStat.isFile()) {
+      throw new Error(`Refusing installer write to unsafe managed target: ${resolvedTarget}`);
+    }
+  }
+  return { resolvedRoot, resolvedTarget };
+}
+
+function atomicWriteManagedFile(root, targetPath, contents) {
+  const { resolvedTarget } = assertContainedManagedTarget(root, targetPath);
+  const parent = path.dirname(resolvedTarget);
+  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+  assertContainedManagedTarget(root, resolvedTarget);
+  const existingMode = fs.existsSync(resolvedTarget)
+    ? fs.lstatSync(resolvedTarget).mode & 0o777
+    : 0o600;
+  const tempPath = path.join(
+    parent,
+    `.${path.basename(resolvedTarget)}.marrow-${process.pid}-${crypto.randomBytes(6).toString('hex')}`,
+  );
+  try {
+    fs.writeFileSync(tempPath, contents, { flag: 'wx', mode: existingMode });
+    assertContainedManagedTarget(root, resolvedTarget);
+    fs.renameSync(tempPath, resolvedTarget);
+  } finally {
+    if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+  }
 }
 
 function applyPlan(plan, options) {
+  if (!Array.isArray(plan?.writes) || plan.writes.length === 0) return [];
+  const root = path.resolve(plan.root || path.dirname(plan.writes[0].path));
+  for (const write of plan.writes) assertContainedManagedTarget(root, write.path);
   const prepared = plan.writes.map((write) => {
     const before = safeRead(write.path);
     let after;
@@ -902,8 +1026,7 @@ function applyPlan(plan, options) {
       already_present: !changed,
     });
     if (changed && writeApplied) {
-      fs.mkdirSync(path.dirname(write.path), { recursive: true });
-      fs.writeFileSync(write.path, after);
+      atomicWriteManagedFile(root, write.path, after);
     }
   }
   return changes;
@@ -1149,8 +1272,13 @@ async function runSelfTest(options) {
       avoided_mistakes: performance.avoided_mistakes ?? performance.avoided_repeated_mistakes ?? 0,
       reused_winning_decisions: performance.reused_winning_decisions ?? 0,
       prevented_bad_actions: performance.prevented_bad_actions ?? 0,
-      estimated_tokens_saved: performance.token_time_saved_estimate?.estimated_tokens_saved ?? 0,
-      estimated_minutes_saved: performance.token_time_saved_estimate?.estimated_minutes_saved ?? 0,
+      estimated_tokens_saved: tokenValueProof?.savings?.estimated_tokens_saved ?? null,
+      estimated_minutes_saved: tokenValueProof?.savings?.estimated_minutes_saved ?? null,
+      token_savings_available: Number(tokenValueProof?.observed?.model_calls || 0) > 0
+        && Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0,
+      token_savings_source: 'agent_model_usage_events',
+      token_savings_method: tokenValueProof?.savings?.method || 'warming_up',
+      token_savings_confidence: tokenValueProof?.savings?.confidence || 'none',
       reliability_score: performance.agent_reliability_score ?? null,
     } : null,
   };
@@ -1173,10 +1301,22 @@ function buildTokenValueProof(valueProof = {}) {
   return modelUsage;
 }
 
+function tokenValueProofLine(tokenValueProof) {
+  const calls = Number(tokenValueProof?.observed?.model_calls || 0);
+  const saved = Number(tokenValueProof?.savings?.estimated_tokens_saved || 0);
+  if (calls > 0 && saved > 0) {
+    const method = tokenValueProof.savings?.method || 'unspecified';
+    const confidence = tokenValueProof.savings?.confidence || 'unknown';
+    return `Marrow observed ${calls} model call${calls === 1 ? '' : 's'} and estimates ~${saved} tokens saved (${method}, ${confidence} confidence)`;
+  }
+  return tokenValueProof?.proof_line || null;
+}
+
 function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {}, performance = {}, firstValue = {}, tokenValueProof = null) {
   if (firstValue && firstValue.ok !== false && firstValue.first_value) {
     const proof = Array.isArray(firstValue.first_value.proof) ? [...firstValue.first_value.proof] : [];
-    if (tokenValueProof?.proof_line && !proof.includes(tokenValueProof.proof_line)) proof.push(tokenValueProof.proof_line);
+    const tokenProofLine = tokenValueProofLine(tokenValueProof);
+    if (tokenProofLine && !proof.includes(tokenProofLine)) proof.push(tokenProofLine);
     return {
       headline: firstValue.headline || firstValue.first_value.headline || 'Your agent is no longer starting from zero.',
       proof,
@@ -1201,7 +1341,7 @@ function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {
       'Closed the outcome successfully',
       'Runtime gate is ' + (firstValueSignal.active ? 'active' : 'installed'),
       runtimeLesson ? 'Future risky work now gets a pre-action brief' : 'Future risky work now gets checked before action',
-      tokenValueProof?.proof_line || 'Token usage proof is active and warming up after the first model call',
+      tokenValueProofLine(tokenValueProof) || 'Token usage proof is active and warming up after the first model call',
     ],
     fleet_signal: hasFleetSignal
       ? 'Marrow already found signal: ' + proof.join('; ') + '.'
@@ -1220,9 +1360,8 @@ function buildFirstValueSignal(status, runtime, performance, firstValue = {}, to
     if (Number(proof.avoided_mistakes || 0) > 0) proofBits.push(`${proof.avoided_mistakes} avoided mistake(s)`);
     if (Number(proof.reused_winning_decisions || 0) > 0) proofBits.push(`${proof.reused_winning_decisions} reused winning decision(s)`);
     if (Number(proof.prevented_bad_actions || 0) > 0) proofBits.push(`${proof.prevented_bad_actions} prevented risky action(s)`);
-    if (Number(proof.estimated_tokens_saved || 0) > 0) proofBits.push(`~${proof.estimated_tokens_saved} tokens saved`);
-    if (Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0) proofBits.push(`~${tokenValueProof.savings.estimated_tokens_saved} measured model tokens saved`);
-    else if (tokenValueProof?.proof_line) proofBits.push(tokenValueProof.proof_line);
+    const tokenProofLine = tokenValueProofLine(tokenValueProof);
+    if (tokenProofLine) proofBits.push(tokenProofLine);
     return {
       active: Boolean(firstValue.active),
       headline: `Marrow active: ${(capture.surfaces || ['decisions']).join(', ')} captured.`,
@@ -1248,10 +1387,8 @@ function buildFirstValueSignal(status, runtime, performance, firstValue = {}, to
   if (Number(proof.avoided_mistakes || proof.avoided_repeated_mistakes || 0) > 0) proofBits.push(`${proof.avoided_mistakes || proof.avoided_repeated_mistakes} avoided mistake(s)`);
   if (Number(proof.reused_winning_decisions || 0) > 0) proofBits.push(`${proof.reused_winning_decisions} reused winning decision(s)`);
   if (Number(proof.prevented_bad_actions || 0) > 0) proofBits.push(`${proof.prevented_bad_actions} prevented risky action(s)`);
-  const tokens = proof.token_time_saved_estimate?.estimated_tokens_saved || 0;
-  if (tokens > 0) proofBits.push(`~${tokens} tokens saved`);
-  if (Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0) proofBits.push(`~${tokenValueProof.savings.estimated_tokens_saved} measured model tokens saved`);
-  else if (tokenValueProof?.proof_line) proofBits.push(tokenValueProof.proof_line);
+  const tokenProofLine = tokenValueProofLine(tokenValueProof);
+  if (tokenProofLine) proofBits.push(tokenProofLine);
 
   const firstLesson = runtime.before_you_act
     || runtime.before_you_act_injection?.message
@@ -1381,6 +1518,11 @@ function printReport(report) {
     if (report.sdkDependency.warning) process.stdout.write(`- warning: ${report.sdkDependency.warning}\n`);
   }
 
+  process.stdout.write('\nAutomatic controller:\n');
+  process.stdout.write(`- state: ${report.controller?.active ? 'active' : report.controller?.state || 'unavailable'}\n`);
+  if (report.controller?.started_at) process.stdout.write(`- started: ${report.controller.started_at}\n`);
+  if (report.controller?.exact_fix) process.stdout.write(`- exact fix: ${report.controller.exact_fix}\n`);
+
   if (report.writeMode === 'doctor') {
     process.stdout.write('\nDoctor:\n');
     process.stdout.write(`- Marrow active: ${report.doctor.active ? 'yes' : 'no'}\n`);
@@ -1459,6 +1601,43 @@ async function install(options) {
   }
   const changedConfig = changes.some((change) => change.applied) || configRepairs.some((repair) => repair.changed);
   const selfTestPassed = Boolean(!selfTest.skipped && selfTest.active && !selfTest.error);
+  const controllerPlatform = options.controllerPlatform || process.platform;
+  let controller = await controllerStatus({
+    root: detection.root,
+    agentId: options.agentId,
+    platform: controllerPlatform,
+  });
+  const shouldEnsureController = options.controller !== false
+    && controllerSupportedPlatform(controllerPlatform)
+    && Boolean(options.apiKey)
+    && selfTestPassed
+    && !options.dryRun
+    && !options.doctor
+    && (options.yes || options.activate || options.repair);
+  if (shouldEnsureController) {
+    try {
+      controller = await ensureGovernanceController({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        agentId: options.agentId,
+        client,
+        root: detection.root,
+        mode: plan.mode,
+        profile: options.governanceMode || 'default',
+        policy: options.governancePolicy || 'warn',
+        platform: controllerPlatform,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      controller = {
+        active: false,
+        state: 'error',
+        exact_fix: 'Run npx @getmarrow/install controller ensure after correcting the reported local controller error.',
+        error: message,
+      };
+      if (options.activate) throw new Error(`Marrow activation failed: local controller did not start: ${message}`);
+    }
+  }
   const remediation = options.repair
     ? {
       attempted: true,
@@ -1500,16 +1679,17 @@ 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 || selfTest.recommended_fix || (!options.apiKey
+      recommendedFix: 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.'
-        : null),
+        : controller.exact_fix || selfTest.recommended_fix || null),
     },
     remediation,
     configDiagnostics,
     configRepairs,
     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.']