@mutmutco/cli 3.17.0 → 3.18.0

package/dist/main.cjs

@@ -12252,6 +12252,7 @@ async function executeMergeToMain(deps, sourceRef, mergeLabel, tolerated, predic
   await deps.run("git", ["checkout", "main"]);
   await ffOnlyPull(deps, "main");
   preFold.mainSha = clean2(await deps.run("git", ["rev-parse", "main"]));
+  preFold.isTrueMerge = !await deps.run("git", ["merge-base", "--is-ancestor", preFold.mainSha, sourceRef]).then(() => true).catch(() => false);
   if (predicted.length === 0) {
     await deps.run("git", ["merge", sourceRef, "--no-edit"]);
   } else {
@@ -12411,12 +12412,69 @@ async function verifyPublishDryRun(deps, ctx, meta, deployModel) {
     );
   }
 }
+var TRUE_MERGE_GATE_BRANCH_PREFIX = "train/check/";
+function trueMergeGateBranchName(tag, sha) {
+  return `${TRUE_MERGE_GATE_BRANCH_PREFIX}${tag.replace(/^v/, "")}-${sha.slice(0, 8)}`;
+}
+async function gateTrueMergeCommit(deps, ctx, tag, releaseSha, requiredChecks) {
+  if (requiredChecks.length === 0) {
+    return "true merge commit: target branch requires no status checks \u2014 throwaway-PR gate skipped";
+  }
+  const branch = trueMergeGateBranchName(tag, releaseSha);
+  await deps.run("git", ["push", "origin", "--delete", branch]).catch(() => void 0);
+  await deps.run("git", ["push", "origin", `${releaseSha}:refs/heads/${branch}`]);
+  let prNumber;
+  try {
+    const url = clean2(await deps.run("gh", [
+      "pr",
+      "create",
+      "--repo",
+      ctx.repo,
+      "--base",
+      "main",
+      "--head",
+      branch,
+      "--draft",
+      "--title",
+      `chore(train): gate ${tag} merge commit (auto, #2790)`,
+      "--body",
+      `Throwaway PR opened by the release train to earn required status checks (${requiredChecks.join(", ")}) on a true (non-fast-forward) merge commit before its tag is pushed (#2790). Auto-closed once the checks resolve \u2014 never merge this PR; the train pushes \`main\` directly once the gate is satisfied.`
+    ]));
+    prNumber = parsePrNumber(url);
+    const checksNote = await waitForRequiredTrainChecks(deps, ctx, releaseSha, requiredChecks);
+    return `true merge commit: gated via throwaway PR ${url || "(url unavailable)"} \u2014 ${checksNote}`;
+  } finally {
+    if (prNumber !== void 0) {
+      await deps.run("gh", ["pr", "close", String(prNumber), "--repo", ctx.repo, "--delete-branch"]).catch((e) => {
+        deps.warn?.(`throwaway train-gate PR #${prNumber} close/branch-delete failed (${e instanceof Error ? e.message : String(e)}) \u2014 clean up '${branch}' manually`);
+      });
+    } else {
+      await deps.run("git", ["push", "origin", "--delete", branch]).catch((e) => {
+        deps.warn?.(`throwaway train-gate branch '${branch}' delete failed (${e instanceof Error ? e.message : String(e)}) \u2014 clean up manually`);
+      });
+    }
+  }
+}
 async function completeMainRelease(deps, ctx, meta, deployModel, watch, options, tag, releaseSha, startBranch, preFold, tagProbe) {
   try {
     await verifyPublishDryRun(deps, ctx, meta, deployModel);
   } catch (e) {
     throw await recoverFailedFold(deps, e, startBranch, preFold.mainSha);
   }
+  let requiredChecks;
+  try {
+    requiredChecks = await discoverRequiredCheckContexts(deps, ctx, "main");
+  } catch (e) {
+    throw await recoverFailedFold(deps, e, startBranch, preFold.mainSha);
+  }
+  let trueMergeGateNote;
+  if (preFold.isTrueMerge) {
+    try {
+      trueMergeGateNote = await gateTrueMergeCommit(deps, ctx, tag, releaseSha, requiredChecks);
+    } catch (e) {
+      throw await recoverFailedFold(deps, e, startBranch, preFold.mainSha);
+    }
+  }
   let tagPush;
   try {
     tagPush = await ensureTagPushed(deps, tag, releaseSha, tagProbe, ctx.repo);
@@ -12424,13 +12482,13 @@ async function completeMainRelease(deps, ctx, meta, deployModel, watch, options,
     throw await recoverFailedFold(deps, e, startBranch, preFold.mainSha);
   }
   const tagPushSince = (deps.now ?? Date.now)();
-  const requiredChecks = await discoverRequiredCheckContexts(deps, ctx, "main");
   let checks;
   try {
     checks = await waitForRequiredTrainChecks(deps, ctx, releaseSha, requiredChecks, tagPush.pushed ? tagPushSince : void 0);
   } catch (e) {
     throw partialTrainRecoveryError(e, { repo: ctx.repo, tag, stage: "main" });
   }
+  if (trueMergeGateNote) checks = `${trueMergeGateNote}; ${checks}`;
   await runGitPush(deps, ["push", "origin", "main"]);
   const releaseUrl = clean2(await deps.run("gh", ["release", "create", tag, "--target", "main", "--generate-notes", "--latest", "--repo", ctx.repo])) || void 0;
   await verifyPublishedRelease(deps, ctx.repo, tag, "main", releaseSha);
@@ -13688,6 +13746,7 @@ async function ensurePortRangeAtomic(repo, path2, allocate, opts = {}) {
 // src/access.ts
 var OWNER2 = "mutmutco";
 var LOCKED_APP = "mmi-github-app";
+var PLUGIN_READ_REPO = "mutmutco/MMI-Hub";
 var OVERGRANT_ROLES = /* @__PURE__ */ new Set(["admin", "maintain"]);
 var REQUIRED_DATA_ACCESS = {};
 function lockedBranches(repoClass, releaseTrack) {
@@ -13842,9 +13901,32 @@ async function auditOrgBasePermission(deps) {
   }
   return [];
 }
+async function auditPluginReadAccess(owners, projectAdmins, deps) {
+  const findings = [];
+  for (const login of projectAdmins) {
+    if (owners.has(login)) continue;
+    const perm = (await restJson2(deps, `repos/${PLUGIN_READ_REPO}/collaborators/${login}/permission`, {})).permission;
+    if (!perm || perm === "none") {
+      findings.push({
+        repo: PLUGIN_READ_REPO,
+        kind: "plugin-read-missing",
+        severity: "medium",
+        actor: login,
+        detail: `project-admin @${login} lacks read on ${PLUGIN_READ_REPO}; the MMI plugin marketplace add will 404 for them until granted`,
+        remediation: `gh api -X PUT repos/${PLUGIN_READ_REPO}/collaborators/${login} -f permission=pull`
+      });
+    }
+  }
+  return findings;
+}
 async function auditOrgAccess(targets, deps, matrix = {}, dataAccess) {
   const owners = new Set(await resolveOwners(deps));
   const orgFindings = await auditOrgBasePermission(deps);
+  const allProjectAdmins = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    for (const login of entriesValueByCanonicalRepo(matrix, target.repo) ?? []) allProjectAdmins.add(login);
+  }
+  orgFindings.push(...await auditPluginReadAccess(owners, allProjectAdmins, deps));
   const repos = [];
   for (const target of targets) {
     repos.push(await auditRepoAccess(target.repo, target.class, owners, deps, new Set(entriesValueByCanonicalRepo(matrix, target.repo) ?? []), dataAccess, target.releaseTrack));
@@ -15929,6 +16011,62 @@ function requireProjectTarget(commandName, explicitTarget, currentRepo) {
   return target;
 }
 
+// src/deploy-guards.ts
+var GIT_SHOW_TIMEOUT_MS = 1e4;
+async function readStageBranchCompose(branch) {
+  for (const ref of [`origin/${branch}`, branch]) {
+    try {
+      return (await execFileP2("git", ["show", `${ref}:docker-compose.yml`], { timeout: GIT_SHOW_TIMEOUT_MS })).stdout;
+    } catch {
+    }
+  }
+  return null;
+}
+function composeMarksRuntimeEnvTrue(composeText) {
+  return composeText.split(/\r?\n/).some((raw) => {
+    const line = raw.replace(/(^|\s)#.*$/, "$1");
+    if (/(^|[\s"'])mmi\.runtime-env\s*:\s*["']?true["']?\s*$/.test(line)) return true;
+    if (/mmi\.runtime-env\s*=\s*["']?true["']?\s*$/.test(line)) return true;
+    return false;
+  });
+}
+function promotionSourceBranch(stage2, releaseTrack) {
+  if (stage2 === "main") return releaseTrack === "direct" ? "development" : "rc";
+  return "development";
+}
+function evaluatePromotionFilelessGuard(input) {
+  const { branch, stage: stage2 } = input;
+  if (input.force) {
+    return { ok: true, warn: `--skip-compose-guard: skipping the fileless-compose \u2194 DEPLOY#${stage2}.noEnvFile guard (#2813)` };
+  }
+  if (!input.sameRepo) {
+    return { ok: true, warn: `fileless-compose guard skipped \u2014 run from the target repo checkout to verify the ${branch} compose against DEPLOY#${stage2}.noEnvFile (#2813).` };
+  }
+  if (input.composeText === null) {
+    return { ok: true, warn: `could not read docker-compose.yml on ${branch} \u2014 skipping the fileless-compose guard (#2813).` };
+  }
+  if (input.fact === null || input.fact.present === false) {
+    return { ok: true };
+  }
+  const noEnvFile = input.fact.noEnvFile === true;
+  if (composeMarksRuntimeEnvTrue(input.composeText) && !noEnvFile) {
+    return {
+      ok: false,
+      reason: `the ${branch} docker-compose.yml marks a service fileless (mmi.runtime-env: "true") but DEPLOY#${stage2}.noEnvFile is not true \u2014 the ${stage2} deploy would fail exit-78 ("compose is fileless but DEPLOY#${stage2} noEnvFile is not true"). Fix BEFORE promoting, then re-run:
+  mmi-cli project set-deploy --stage ${stage2} --no-env-file true   # register the fileless flag
+  gh workflow run tenant-reconcile.yml --repo mutmutco/MMI-Hub     # re-render the box control script (#1056)
+  (or pass --skip-compose-guard to override this preflight)`
+    };
+  }
+  if (noEnvFile && composeDeclaresEnvFile(input.composeText)) {
+    return {
+      ok: false,
+      reason: `DEPLOY#${stage2}.noEnvFile is true but the ${branch} docker-compose.yml still declares env_file: \u2014 the box writes no .env, so docker compose dies on the missing file. Land the fileless compose (drop env_file:, add the mmi.runtime-env label) on ${branch}, or set-deploy --no-env-file false (or --skip-compose-guard to override).`
+    };
+  }
+  return { ok: true };
+}
+
 // src/project-retire.ts
 function retireSlugOf(repoOrSlug) {
   return (repoOrSlug.includes("/") ? repoOrSlug.split("/").pop() : repoOrSlug).toLowerCase();
@@ -16215,7 +16353,7 @@ function registerSecretsCommands(program3) {
     }
     if (!await secretsOrgCatalogSet(d, body)) process.exitCode = 1;
   }));
-  secrets.command("preflight").description("check required stage secret names for a deploy/train without reading values").requiredOption("--stage <dev|rc|main>", "stage to check").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--required <KEY...>", "required keys; bare keys are scoped under --stage").option("--json", "machine-readable output").action(async (o) => {
+  secrets.command("preflight").description("check required stage secret names for a deploy/train without reading values").requiredOption("--stage <dev|rc|main>", "stage to check").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--required <KEY...>", "required keys; bare keys are scoped under --stage").option("--skip-compose-guard", "skip the #2813 fileless-compose \u2194 DEPLOY#.noEnvFile promotion guard").option("--json", "machine-readable output").action(async (o) => {
     if (!["dev", "rc", "main"].includes(o.stage)) {
       return fail("secrets preflight: --stage must be dev, rc, or main");
     }
@@ -16236,8 +16374,26 @@ function registerSecretsCommands(program3) {
     if (!o.required?.length && centralContainer && meta && !hasRuntimeSecretContract(meta.requiredRuntimeSecrets)) {
       d.err('secrets preflight: requiredRuntimeSecrets is unset: treating as an empty contract (no required keys). Declare an explicit {"dev":[],"rc":[],"main":[]} in registry META to silence this warning.');
     }
+    let filelessOk = true;
+    if (meta && centralContainer && !o.skipComposeGuard) {
+      const stage2 = o.stage;
+      const branch = promotionSourceBranch(stage2, resolveReleaseTrack(meta, void 0, repo));
+      const cwdRepo = repoFromRemoteUrl((await execFileP2("git", ["remote", "get-url", "origin"]).catch(() => ({ stdout: "" }))).stdout);
+      const targetRepo2 = o.repo ? o.repo.includes("/") ? o.repo : `mutmutco/${o.repo}` : cwdRepo;
+      const sameRepo = !o.repo || Boolean(cwdRepo) && Boolean(targetRepo2) && cwdRepo.toLowerCase() === targetRepo2.toLowerCase();
+      const facts = await fetchDeployFactsBySlug(slug, regDeps);
+      const fact = facts?.stages?.[stage2] ?? null;
+      const composeText = sameRepo ? await readStageBranchCompose(branch) : null;
+      const verdict = evaluatePromotionFilelessGuard({ composeText, branch, stage: stage2, fact, sameRepo: Boolean(sameRepo), force: false });
+      if (!verdict.ok) {
+        d.err(`secrets preflight: ${verdict.reason}`);
+        filelessOk = false;
+      } else if (verdict.warn) {
+        d.err(`secrets preflight: ${verdict.warn}`);
+      }
+    }
     const ok = await secretsPreflight(d, { repo: o.repo, stage: o.stage, required, json: o.json, declaredSecrets: meta?.secrets });
-    if (!ok) process.exitCode = 1;
+    if (!ok || !filelessOk) process.exitCode = 1;
   });
   secrets.command("get <key>").description("print one secret value, RAW \u2014 MASTER-ONLY (WS6 #2184); non-master: `secrets use` to consume keyless or `secrets verify` to validate").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--slug <slug>", "vault slug override for org-infra namespaces (cloudflare, shared, \u2026) \u2014 master-gated").action((key, o) => withSecrets(async (d) => {
     const ok = await secretsGet(d, key, o);
@@ -16674,7 +16830,7 @@ async function runIssueList(deps, opts) {
   return shapeIssueList(rows);
 }
 function childrenGraphqlArgs(owner, name, number) {
-  const query = "query($owner:String!,$name:String!){repository(owner:$owner,name:$name){issue(number:" + number + "){number subIssues(first:100){nodes{number title state url assignees(first:10){nodes{login}} repository{nameWithOwner} projectItems(first:5){nodes{project{id name} fieldValues(first:20){nodes{... on ProjectV2ItemFieldSingleSelectValue{name field{...on ProjectV2SingleSelectField{name}}}}}}} timelineItems(first:30,itemTypes:[CROSS_REFERENCED_EVENT]){nodes{...on CrossReferencedEvent{source{...on PullRequest{number title state url}}}}}}}}}}";
+  const query = "query($owner:String!,$name:String!){repository(owner:$owner,name:$name){issue(number:" + number + "){number subIssues(first:100){nodes{number title state url assignees(first:10){nodes{login}} repository{nameWithOwner} projectItems(first:5){nodes{project{id} fieldValues(first:20){nodes{... on ProjectV2ItemFieldSingleSelectValue{name field{...on ProjectV2SingleSelectField{name}}}}}}} timelineItems(first:30,itemTypes:[CROSS_REFERENCED_EVENT]){nodes{...on CrossReferencedEvent{source{...on PullRequest{number title state url}}}}}}}}}}";
   return ["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`];
 }
 function shapeChildNode(node, depth, boardProjectId) {
@@ -17940,10 +18096,6 @@ function reloadAction(surface) {
   }
 }
 var CLAUDE_RECOVERY = `claude plugin marketplace remove ${LEGACY_MMI_MARKETPLACE} && claude plugin marketplace remove mutmutco && claude plugin marketplace add mutmutco/MMI-Hub --ref main && claude plugin install mmi@mutmutco`;
-var CODEX_RECOVERY = `codex plugin marketplace remove ${LEGACY_MMI_MARKETPLACE} && codex plugin marketplace remove mutmutco && codex plugin marketplace add mutmutco/MMI-Hub --ref main && codex plugin add mmi@mutmutco`;
-var CURSOR_RECOVERY = "in Cursor Dashboard \u2192 Settings \u2192 Plugins, click Update next to the MMI Team Marketplace";
-var OPENCODE_PLUGIN_INSTALL_COMMAND = "mmi-cli doctor --apply";
-var OPENCODE_RECOVERY = `${OPENCODE_PLUGIN_INSTALL_COMMAND}   # then restart OpenCode to load MMI commands`;
 var PLUGIN_SURFACE_HEAL = {
   claude: {
     delivery: "plugin-cli",
@@ -17955,43 +18107,15 @@ var PLUGIN_SURFACE_HEAL = {
       { args: ["plugin", "install", "mmi@mutmutco"], gated: true },
       { args: ["plugin", "enable", "mmi@mutmutco"], gated: false }
     ],
-    pluginRunner: "claude",
     fix: (surface) => `${CLAUDE_RECOVERY}   # then ${reloadAction(surface)} to reload MMI commands`,
     updateRecipe: [CLAUDE_RECOVERY]
-  },
-  codex: {
-    delivery: "plugin-cli",
-    recovery: CODEX_RECOVERY,
-    healSteps: [
-      { args: ["plugin", "marketplace", "remove", LEGACY_MMI_MARKETPLACE], gated: false },
-      { args: ["plugin", "marketplace", "remove", "mutmutco"], gated: false },
-      { args: ["plugin", "marketplace", "add", "mutmutco/MMI-Hub", "--ref", "main"], gated: true },
-      { args: ["plugin", "add", "mmi@mutmutco"], gated: true }
-    ],
-    pluginRunner: "codex",
-    fix: (surface) => `${CODEX_RECOVERY}   # then ${reloadAction(surface)}`,
-    updateRecipe: [CODEX_RECOVERY, "codex plugin list   # verify mmi@mutmutco shows the released version"],
-    guardRecovery: "$env:MMI_AGENT_SURFACE='codex'; mmi-cli plugin-heal"
-  },
-  cursor: {
-    delivery: "cursor-cache",
-    recovery: CURSOR_RECOVERY,
-    healSteps: null,
-    fix: (surface) => `${CURSOR_RECOVERY}; then ${reloadAction(surface)} to reload MMI skills + hooks`,
-    updateRecipe: [CURSOR_RECOVERY]
-  },
-  opencode: {
-    delivery: "npm",
-    recovery: OPENCODE_RECOVERY,
-    healSteps: null,
-    fix: () => OPENCODE_RECOVERY,
-    updateRecipe: [OPENCODE_RECOVERY, "restart OpenCode, then run mmi-cli doctor to verify OpenCode plugin reports the released version"]
   }
 };
 var CLAUDE_PLUGIN_RECOVERY = PLUGIN_SURFACE_HEAL.claude.recovery;
 var CLAUDE_PLUGIN_HEAL_STEPS = PLUGIN_SURFACE_HEAL.claude.healSteps;
-var CODEX_PLUGIN_RECOVERY = PLUGIN_SURFACE_HEAL.codex.recovery;
-var CODEX_PLUGIN_HEAL_STEPS = PLUGIN_SURFACE_HEAL.codex.healSteps;
+function nonClaudeSurfaceHealMessage() {
+  return "No Hub-shipped MMI plugin on this host \u2014 the Hub is Claude-only since #2741.\n  Update the CLI instead: npm i -g @mutmutco/cli   (org rules ride an AGENTS.md authored outside the Hub)";
+}
 function healStepAborts(step, ok) {
   return !ok && step.gated;
 }
@@ -18070,6 +18194,9 @@ function snapshotPluginGuardInput(surface = detectSurface(process.env), isOrgRep
     pluginCachePresent: (0, import_node_fs21.existsSync)((0, import_node_path20.join)((0, import_node_os6.homedir)(), homeDir, "plugins", "cache", "mutmutco", "mmi"))
   };
 }
+function claudePluginGuardState(isOrgRepo) {
+  return buildPluginGuardDecision(snapshotPluginGuardInput(detectSurface(process.env), isOrgRepo)).state;
+}
 async function runClaudePlugin(args) {
   try {
     await runHostBin("claude", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
@@ -18078,14 +18205,6 @@ async function runClaudePlugin(args) {
     return false;
   }
 }
-async function runCodexPlugin(args) {
-  try {
-    await runHostBin("codex", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
-    return true;
-  } catch {
-    return false;
-  }
-}
 async function marketplaceAddRefSupported(bin) {
   try {
     const { stdout, stderr } = await runHostBin(bin, ["plugin", "marketplace", "add", "--help"], {
@@ -18105,33 +18224,36 @@ function refAbsenceNote(bin, refSupported) {
   return refSupported ? "" : `
   Note: \`${bin}\` has no \`--ref\` option; the marketplace manifest pins the released branch, so none is needed (#2516).`;
 }
-async function applyPluginHeal(token, surface, log, opts) {
-  if (!opts?.force && surfaceToken(surface) !== token) return false;
-  const descriptor = PLUGIN_SURFACE_HEAL[token];
-  const tableSteps = descriptor.healSteps;
+var PLUGIN_READ_REPO2 = "mutmutco/MMI-Hub";
+function pluginReadGrantNote(login = "<your-github-login>") {
+  return `
+  If the reinstall 404s on ${PLUGIN_READ_REPO2}, you lack read on it. An org owner must grant it (idempotent):
+  gh api -X PUT repos/${PLUGIN_READ_REPO2}/collaborators/${login} -f permission=pull`;
+}
+async function applyPluginHeal(surface, log, opts) {
+  if (!opts?.force && surfaceToken(surface) !== "claude") return false;
+  const tableSteps = PLUGIN_SURFACE_HEAL.claude.healSteps;
   if (!tableSteps) return false;
-  const bin = descriptor.pluginRunner === "codex" ? "codex" : "claude";
-  const runner = descriptor.pluginRunner === "codex" ? runCodexPlugin : runClaudePlugin;
-  const refSupported = await marketplaceAddRefSupported(bin);
+  const refSupported = await marketplaceAddRefSupported("claude");
   const { steps } = adaptHealStepsForRefSupport(tableSteps, refSupported);
-  log(healBannerLine(bin, token, refSupported));
+  log(healBannerLine("claude", "claude", refSupported));
   for (const step of steps) {
-    if (healStepAborts(step, await runner([...step.args]))) return false;
+    if (healStepAborts(step, await runClaudePlugin([...step.args]))) return false;
   }
   return true;
 }
-function guardRecoveryCommand(surface) {
-  const token = surfaceToken(surface);
-  return token ? PLUGIN_SURFACE_HEAL[token]?.guardRecovery : void 0;
-}
 async function runGuard(opts = {}, readOrigin) {
   void opts;
   try {
     const surface = detectSurface(process.env);
+    if (surfaceToken(surface) !== "claude") {
+      process.exitCode = 0;
+      return;
+    }
     const isOrgRepo = readOrigin ? await isOrgRepoRoot(readOrigin) : await isOrgRepoRoot();
     const input = snapshotPluginGuardInput(surface, isOrgRepo);
     const { state } = buildPluginGuardDecision(input);
-    const { line, exitCode } = buildGuardSessionStartLine(state, { recovery: guardRecoveryCommand(surface) });
+    const { line, exitCode } = buildGuardSessionStartLine(state);
     if (line) console.error(line);
     process.exitCode = exitCode;
   } catch {
@@ -18139,24 +18261,20 @@ async function runGuard(opts = {}, readOrigin) {
   }
 }
 async function runPluginHeal(surface = detectSurface(process.env)) {
-  const token = surface === "codex" ? "codex" : "claude";
-  const tableKey = surfaceToken(surface) ?? "claude";
-  const descriptor = PLUGIN_SURFACE_HEAL[tableKey];
-  if (!descriptor.healSteps) {
-    console.log(descriptor.recovery);
-    console.log(`Then: ${reloadAction(surface)}`);
+  if (surfaceToken(surface) !== "claude") {
+    console.log(nonClaudeSurfaceHealMessage());
     return;
   }
-  const healed = await applyPluginHeal(token, surface, console.log, { force: true });
+  const descriptor = PLUGIN_SURFACE_HEAL.claude;
+  const healed = await applyPluginHeal(surface, console.log, { force: true });
   if (healed) {
     console.log(`  \u2713 MMI plugin reinstalled \u2014 ${reloadAction(surface)} to load MMI commands`);
   } else {
-    const bin = descriptor.pluginRunner === "codex" ? "codex" : "claude";
-    const refSupported = await marketplaceAddRefSupported(bin);
+    const refSupported = await marketplaceAddRefSupported("claude");
     const recovery = refSupported ? descriptor.recovery : recoveryWithoutRef(descriptor.recovery);
-    const note = refAbsenceNote(bin, refSupported);
+    const note = refAbsenceNote("claude", refSupported);
     console.log(`  \u2717 Auto-heal failed or was skipped. Run manually:
-  ${recovery}${note}`);
+  ${recovery}${note}${pluginReadGrantNote()}`);
   }
 }
 var USER_SCOPE_GUARD_MARKER = "mmi-guard:v1";
@@ -19229,7 +19347,14 @@ function checkRepoWorktrees(probe) {
   };
 }
 function checkClaudePlugin(probe) {
-  const { installed, released } = probe;
+  const { installed, released, guardState } = probe;
+  if (guardState === "no-install" || guardState === "unresolved") {
+    return {
+      ok: false,
+      label: guardState === "no-install" ? "Claude plugin \u2014 not installed" : "Claude plugin \u2014 unresolved (marketplace/cache missing)",
+      fix: "run `mmi-cli plugin-heal` to reinstall the MMI marketplace + plugin, then restart Claude"
+    };
+  }
   const behind = Boolean(installed && released) && compareVersions(installed, released) < 0;
   if (behind) {
     return {
@@ -19240,6 +19365,16 @@ function checkClaudePlugin(probe) {
   }
   return { ok: true, label: installed ? `Claude plugin ${installed}` : "Claude plugin" };
 }
+function checkCliVersion(input) {
+  const report = buildVersionLagReport(input);
+  if (!report.releasedVersion) return { ok: true, label: `mmi-cli ${report.currentVersion}` };
+  if (report.ok) return { ok: true, label: `mmi-cli ${report.currentVersion}` };
+  return {
+    ok: false,
+    label: `mmi-cli ${report.currentVersion} \u2192 ${report.releasedVersion}`,
+    fix: report.fix
+  };
+}
 function checkTrainSync(result) {
   const problems = result.branches.filter((b) => b.status === "skipped" && (b.reason === "diverged" || b.reason === "ff-failed"));
   if (problems.length) {
@@ -19286,9 +19421,10 @@ async function runDoctorClean(opts, io, deps) {
       checks.push({ ok: false, label: "gitignore block", fix: "run `mmi-cli doctor --apply` to write the org-managed .gitignore block" });
     }
   }
-  const plugin = checkClaudePlugin({ installed, released });
+  const plugin = checkClaudePlugin({ installed, released, guardState: deps.pluginGuardState(isOrgRepo) });
   checks.push(plugin);
   if (!plugin.ok) restartPending = true;
+  checks.push(checkCliVersion({ currentVersion: deps.currentCliVersion(), releasedVersion: released }));
   if (isOrgRepo && !opts.fast && !opts.banner) {
     try {
       checks.push(checkTrainSync(await deps.syncTrain()));
@@ -19566,7 +19702,9 @@ function mmiDoctorDeps() {
     awsCallerArn,
     isOrgRepo: () => isOrgRepoRoot(),
     installedPluginVersion: installedClaudePluginVersion,
+    pluginGuardState: claudePluginGuardState,
     releasedVersion: fetchNpmReleasedVersion,
+    currentCliVersion: resolveClientVersion,
     readGitignore,
     writeGitignore,
     hasRepoLocalWorktrees,
@@ -20449,15 +20587,6 @@ fullTrack.command("readiness <owner/repo>").description("aggregate branch topolo
   console.log(JSON.stringify(report, null, 2));
   if (!report.rcand.canApply) process.exitCode = 1;
 });
-async function readStageBranchCompose(branch) {
-  for (const ref of [`origin/${branch}`, branch]) {
-    try {
-      return (await execFileP2("git", ["show", `${ref}:docker-compose.yml`], { timeout: GIT_TIMEOUT_MS })).stdout;
-    } catch {
-    }
-  }
-  return null;
-}
 project.command("set-deploy [owner/repo]").description("write the DEPLOY#<stage> Hetzner deploy coords for a tenant (master-only) \u2014 the explicit-coords path that seeds a freshly-bootstrapped tenant; defaults to the current repo").requiredOption("--stage <stage>", "dev | rc | main").option("--ssh-host <host>", "the box address the deploy ssh-es into (required for hetzner-ssh)").option("--ssh-user <user>", "ssh user (default root)").option("--port <port>", "loopback port the container binds / Caddy upstream (1..65535)").option("--substrate <substrate>", "hetzner-ssh (default)").option("--deploy-path <path>", "on-box per-stage release root (default /opt/mmi/<slug>/<stage>)").option("--service <name>", "systemd/compose service name (default the slug)").option("--domain <domain>", "canonical serving host (default the project edgeDomains[stage])").option("--alias <domain...>", "extra serving hostname the box Caddy answers (repeatable)").option("--no-env-file <bool>", "set the DEPLOY# fileless flag (true|false) \u2014 true = #2662 env passthrough, no .env symlink; omit to leave the row unchanged").option("--force", "skip the #2748 fileless-compose guard (flip noEnvFile=true even if the stage branch compose still declares env_file:)").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   let target;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "description": "MMI Future CLI — the org dev toolbox (board, registry, keyless secrets, release train, bootstrap, doctor) and the cross-IDE engine the plugin's session-start hook drives.",
   "type": "module",
   "license": "UNLICENSED",