@mutmutco/cli 3.1.0 → 3.2.0

package/dist/main.cjs

@@ -4789,7 +4789,7 @@ mutation($projectId: ID!, $itemId: ID!) {
 async function updateItemSingleSelect(client, projectId, itemId, fieldId, optionId) {
   await client.graphql(UPDATE_ITEM_FIELD_MUTATION, { projectId, itemId, fieldId, optionId });
 }
-function resolveBoardConfig(cfg) {
+function missingBoardConfigFields(cfg) {
   const missing = [];
   if (!cfg.projectOwner) missing.push("projectOwner");
   if (!cfg.projectNumber) missing.push("projectNumber");
@@ -4799,9 +4799,20 @@ function resolveBoardConfig(cfg) {
   for (const status of BOARD_STATUSES) {
     if (!cfg.statusOptions?.[status]) missing.push(`statusOptions.${status}`);
   }
-  if (missing.length) {
-    throw new Error(
-      `Hub registry board META missing ${missing.join(", ")}; run \`gh auth login\`, then \`mmi-cli project get <owner/repo>\`, or ask a master-admin to register/backfill board coords`
+  return missing;
+}
+function diagnoseBoardConfigGap(cfg) {
+  const missing = missingBoardConfigFields(cfg);
+  if (!missing.length) return null;
+  return cfg.projectId ? { kind: "registry-meta-missing", missing } : { kind: "no-project-detected" };
+}
+function resolveBoardConfig(cfg) {
+  const gap = diagnoseBoardConfigGap(cfg);
+  if (gap) {
+    throw gap.kind === "no-project-detected" ? new Error(
+      "no MMI project detected for this workspace (no Hub registry match for this repo, or no git origin in this folder); run `mmi-cli board read --repo <owner/repo>` to target a specific registered repo, or `mmi-cli project get <owner/repo>` to check registration"
+    ) : new Error(
+      `Hub registry board META missing ${gap.missing.join(", ")}; run \`gh auth login\`, then \`mmi-cli project get <owner/repo>\`, or ask a master-admin to register/backfill board coords`
     );
   }
   return {
@@ -4864,6 +4875,11 @@ function detailCandidates(report) {
     ...report.secondary.claimable
   ].filter((item) => item.contentType === "Issue");
 }
+function boardNotFoundError(ref, board2, opts = {}) {
+  const verb = opts.verb ?? "is not on";
+  const remedy = opts.remedy ?? "if it lives on a different board, pass --repo <owner/repo> for the repo that owns it";
+  return new Error(`${ref} ${verb} the ${board2.owner} #${board2.number} board; ${remedy}`);
+}
 function findClaimableItem(report, selector) {
   const candidates = [...report.primary.claimable, ...report.secondary.claimable];
   const found = candidates.find((item) => item.repository.toLowerCase() === selector.repo.toLowerCase() && item.number === selector.number);
@@ -4882,7 +4898,10 @@ function findClaimableItem(report, selector) {
     if (existing.assignees.length) throw new Error(`${existing.ref} is already assigned to @${existing.assignees.join(", @")}`);
     throw new Error(`${existing.ref} is not claimable`);
   }
-  throw new Error(`${selector.repo}#${selector.number} is not on this project board`);
+  throw boardNotFoundError(`${selector.repo}#${selector.number}`, report.project, {
+    verb: "is not a claimable item on",
+    remedy: "it may already be Done (excluded from claim tracking), or it lives on a different board \u2014 pass --repo <owner/repo> for the repo that owns it"
+  });
 }
 function renderBoardItem(item) {
   const assignees = item.assignees.length ? `@${item.assignees.join(", @")}` : "unassigned";
@@ -5022,11 +5041,11 @@ async function readBoard(options, deps = {}) {
   }
   return report;
 }
-function findBoardItem(items, selector) {
+function findBoardItem(items, selector, board2) {
   const found = items.find(
     (candidate) => candidate.repository.toLowerCase() === selector.repo.toLowerCase() && candidate.number === selector.number
   );
-  if (!found) throw new Error(`${selector.repo}#${selector.number} is not on this project board`);
+  if (!found) throw boardNotFoundError(`${selector.repo}#${selector.number}`, board2);
   return found;
 }
 async function resolveCurrentRepo(options, deps) {
@@ -5045,7 +5064,9 @@ async function moveBoardItem(options, deps = {}) {
   const selector = parseIssueSelector(options.selector, currentRepo);
   const lookup = await fetchIssueProjectItem(client, cfg, selector);
   const item = lookup.item;
-  if (!item) throw new Error(`${selector.repo}#${selector.number} is not on this project board`);
+  if (!item) {
+    throw boardNotFoundError(`${selector.repo}#${selector.number}`, { owner: cfg.projectOwner, number: cfg.projectNumber });
+  }
   const optionId = cfg.statusOptions[options.status];
   try {
     await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, optionId);
@@ -5091,7 +5112,7 @@ async function showBoardItem(options, deps = {}) {
   const currentRepo = await resolveCurrentRepo(options, deps);
   const selector = parseIssueSelector(options.selector, currentRepo);
   const { item } = await fetchIssueProjectItem(client, cfg, selector);
-  if (!item) throw new Error(`${selector.repo}#${selector.number} is not on this project board`);
+  if (!item) throw boardNotFoundError(`${selector.repo}#${selector.number}`, { owner: cfg.projectOwner, number: cfg.projectNumber });
   if (item.contentType === "Issue") {
     try {
       item.details = await fetchIssueDetails(client, item.repository, item.number);
@@ -5104,9 +5125,10 @@ async function showBoardItem(options, deps = {}) {
 async function prepareClaimContext(options, selectors, deps, collected) {
   const cfg = resolveBoardConfig(options.config);
   const client = deps.client ?? defaultGitHubClient();
+  const board2 = { owner: cfg.projectOwner, number: cfg.projectNumber };
   for (const selector of selectors) {
     try {
-      findBoardItem(collected.items, selector);
+      findBoardItem(collected.items, selector, board2);
     } catch {
       const fallback = (await fetchIssueProjectItem(client, cfg, selector)).item;
       if (fallback) collected.items.push(fallback);
@@ -5132,7 +5154,7 @@ async function prepareClaimContext(options, selectors, deps, collected) {
 }
 async function claimOneBoardItem(ctx, selector, options) {
   const { cfg, client, report } = ctx;
-  const flatItem = findBoardItem(ctx.items, selector);
+  const flatItem = findBoardItem(ctx.items, selector, { owner: cfg.projectOwner, number: cfg.projectNumber });
   if (flatItem.status === "Todo" && flatItem.assignees.length === 0 && !ctx.writable.has(flatItem.repository.toLowerCase())) {
     throw new Error(`${flatItem.ref} is not claimable: viewer does not have write access to ${flatItem.repository}`);
   }
@@ -10423,25 +10445,113 @@ async function preflightMergeToMain(deps, deployModel, remoteRef, blockingPrefix
   }
   return { foldPaths, tolerated, predicted };
 }
-async function executeMergeToMain(deps, sourceRef, mergeLabel, tolerated, predicted) {
+async function executeMergeToMain(deps, sourceRef, mergeLabel, tolerated, predicted, preFold) {
   await deps.run("git", ["checkout", "main"]);
   await ffOnlyPull(deps, "main");
+  preFold.mainSha = clean(await deps.run("git", ["rev-parse", "main"]));
   if (predicted.length === 0) {
     await deps.run("git", ["merge", sourceRef, "--no-edit"]);
   } else {
     await mergeWithToleratedResolution(deps, sourceRef, mergeLabel, "theirs", tolerated);
   }
 }
-async function mergeSourceToMain(deps, deployModel, args) {
-  const { foldPaths, tolerated, predicted } = await preflightMergeToMain(
-    deps,
-    deployModel,
-    args.remoteRef,
-    args.blockingPrefix,
-    args.realignMessage
+async function probeFoldFailureState(deps) {
+  const branch = await currentBranch(deps);
+  const mergeInProgress = await deps.run("git", ["rev-parse", "-q", "--verify", "MERGE_HEAD"]).then(() => true).catch(() => false);
+  const dirty = porcelainHasBlockingChanges(await deps.run("git", ["status", "--porcelain"]).catch(() => ""));
+  const mainSha = await deps.run("git", ["rev-parse", "main"]).then(clean).catch(() => "");
+  const originMainSha = await deps.run("git", ["rev-parse", "origin/main"]).then(clean).catch(() => "");
+  const originIsAncestorOfMain = Boolean(mainSha) && Boolean(originMainSha) ? await deps.run("git", ["merge-base", "--is-ancestor", "origin/main", "main"]).then(() => true).catch(() => false) : false;
+  return { branch, mergeInProgress, dirty, mainSha, originMainSha, originIsAncestorOfMain };
+}
+function shaLabel(sha) {
+  return sha ? sha.slice(0, 7) : "(unknown)";
+}
+async function finishFoldAutoRestore(deps, causeMessage, startBranch, what) {
+  try {
+    await deps.run("git", ["checkout", startBranch]);
+  } catch (e) {
+    return new Error(
+      `${causeMessage}
+
+fold failed; ${what}, but returning to ${startBranch} afterwards failed: ${e instanceof Error ? e.message : String(e)}. Finish manually: git checkout ${startBranch}`
+    );
+  }
+  return new Error(
+    `${causeMessage}
+
+fold failed; ${what} and the checkout was returned to ${startBranch}. Nothing was pushed to origin and no tag was created \u2014 rerun the release once the fold issue above is fixed.`
   );
-  await executeMergeToMain(deps, args.sourceRef, args.mergeLabel, tolerated, predicted);
-  return { foldPaths };
+}
+function foldFailureGuidance(causeMessage, probe, startBranch, preFoldMainSha) {
+  const steps = preFoldMainSha ? [
+    `  1. git status                              # inspect what is actually there`,
+    `  2. git log --oneline ${preFoldMainSha}..main   # commits beyond the pre-fold main \u2014 confirm they are only this run's merge/fold attempt`,
+    `  3. git checkout main && git reset --hard ${preFoldMainSha}   # back to the exact commit the fold built on`,
+    `  4. git checkout ${startBranch}`
+  ] : [
+    `  1. git status                              # inspect what is actually there`,
+    `  2. git log --oneline origin/main..main     # this run never committed to main (it failed before the merge) \u2014 any commits here predate this run; preserve them`,
+    `  3. git checkout ${startBranch}`
+  ];
+  return new Error(
+    `${causeMessage}
+
+fold failed leaving the checkout in a state train --apply will not auto-restore (branch=${probe.branch || "(unknown)"}, dirty-working-tree=${probe.dirty}, main=${shaLabel(probe.mainSha)}, origin/main=${shaLabel(probe.originMainSha)}, pre-fold main=${preFoldMainSha ? shaLabel(preFoldMainSha) : "not captured"}, origin/main is${probe.originIsAncestorOfMain ? "" : " NOT"} an ancestor of main). Nothing was pushed to origin and no tag was created.
+Recovery sequence:
+${steps.join("\n")}`
+  );
+}
+async function recoverFailedFold(deps, cause, startBranch, preFoldMainSha) {
+  const causeMessage = cause instanceof Error ? cause.message : String(cause);
+  const probe = await probeFoldFailureState(deps);
+  if (probe.mergeInProgress) {
+    try {
+      await deps.run("git", ["merge", "--abort"]);
+    } catch (e) {
+      return new Error(
+        `${causeMessage}
+
+fold failed with an in-progress merge left on ${probe.branch || "(unknown branch)"}; automatic \`git merge --abort\` failed: ${e instanceof Error ? e.message : String(e)}. Nothing was pushed to origin and no tag was created.
+Recovery sequence:
+  1. git merge --abort
+  2. git checkout ${startBranch}`
+      );
+    }
+    return finishFoldAutoRestore(deps, causeMessage, startBranch, "the in-progress merge was aborted");
+  }
+  if (probe.branch === "main" && preFoldMainSha) {
+    const mainDescendsFromPreFold = await deps.run("git", ["merge-base", "--is-ancestor", preFoldMainSha, "main"]).then(() => true).catch(() => false);
+    if (mainDescendsFromPreFold) {
+      try {
+        await deps.run("git", ["reset", "--hard", preFoldMainSha]);
+      } catch (e) {
+        return new Error(
+          `${causeMessage}
+
+fold failed after this run's merge/fold committed locally on main (now ${shaLabel(probe.mainSha)}, unpushed, built on the pre-fold main ${shaLabel(preFoldMainSha)}); automatic \`git reset --hard ${shaLabel(preFoldMainSha)}\` failed: ${e instanceof Error ? e.message : String(e)}. Nothing was pushed to origin and no tag was created.
+Recovery sequence:
+  1. git reset --hard ${preFoldMainSha}
+  2. git checkout ${startBranch}`
+        );
+      }
+      const aheadNote = probe.originMainSha && preFoldMainSha !== probe.originMainSha ? `; local main carried commit(s) origin/main (${shaLabel(probe.originMainSha)}) does not have \u2014 they were preserved` : "";
+      return finishFoldAutoRestore(
+        deps,
+        causeMessage,
+        startBranch,
+        `local main was reset to its pre-fold state ${shaLabel(preFoldMainSha)} (discarding only this run's merge/fold commit(s) at ${shaLabel(probe.mainSha)})${aheadNote}`
+      );
+    }
+  }
+  return foldFailureGuidance(causeMessage, probe, startBranch, preFoldMainSha);
+}
+async function runFoldStage(deps, startBranch, preFold, fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    throw await recoverFailedFold(deps, e, startBranch, preFold.mainSha);
+  }
 }
 async function completeMainRelease(deps, ctx, meta, deployModel, watch, options, tag, releaseSha) {
   await ensureTagPushed(deps, tag, releaseSha);
@@ -10534,15 +10644,20 @@ async function runTrainApplyPipeline(mode, input) {
     const deployModel2 = await preflight(deps, ctx, "main", meta);
     const tag2 = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "cycle"])), "release tag");
     const rcShaAtRelease = !directTrack && hasRcBranch ? clean(await deps.run("git", ["rev-parse", "origin/rc"])) : "";
-    const { foldPaths: foldPaths2 } = await mergeSourceToMain(deps, deployModel2, {
-      sourceRef: "development",
-      remoteRef: "origin/development",
-      mergeLabel: "development -> main",
-      blockingPrefix: "development -> main merge would conflict on untolerated path(s)",
-      realignMessage: "The train is misaligned: reconcile main and development via an approved alignment PR, then rerun release."
+    const { foldPaths: foldPaths2, tolerated: tolerated2, predicted: predicted2 } = await preflightMergeToMain(
+      deps,
+      deployModel2,
+      "origin/development",
+      "development -> main merge would conflict on untolerated path(s)",
+      "The train is misaligned: reconcile main and development via an approved alignment PR, then rerun release."
+    );
+    const preFold2 = {};
+    const { versionFold: versionFold2, releaseSha: releaseSha2 } = await runFoldStage(deps, "development", preFold2, async () => {
+      await executeMergeToMain(deps, "development", "development -> main", tolerated2, predicted2, preFold2);
+      const versionFold3 = await foldReleaseVersion(deps, deployModel2, tag2, foldPaths2);
+      const releaseSha3 = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
+      return { versionFold: versionFold3, releaseSha: releaseSha3 };
     });
-    const versionFold2 = await foldReleaseVersion(deps, deployModel2, tag2, foldPaths2);
-    const releaseSha2 = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
     const { checks: checks2, releaseUrl: releaseUrl2, announceNote: announceNote2, dispatch: d2 } = await completeMainRelease(deps, ctx, meta, deployModel2, watch, options, tag2, releaseSha2);
     const devRollForward2 = await rollDevelopmentForward(deps, ctx, tag2);
     if (directTrack) {
@@ -10619,10 +10734,14 @@ async function runTrainApplyPipeline(mode, input) {
     );
   }
   const releasedRcSha = clean(await deps.run("git", ["rev-parse", "origin/rc"]));
-  await executeMergeToMain(deps, "rc", "rc -> main", tolerated, predicted);
-  const tag = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "release"])), "release tag");
-  const versionFold = await foldReleaseVersion(deps, deployModel, tag, foldPaths);
-  const releaseSha = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
+  const preFold = {};
+  const { tag, versionFold, releaseSha } = await runFoldStage(deps, "rc", preFold, async () => {
+    await executeMergeToMain(deps, "rc", "rc -> main", tolerated, predicted, preFold);
+    const tag2 = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "release"])), "release tag");
+    const versionFold2 = await foldReleaseVersion(deps, deployModel, tag2, foldPaths);
+    const releaseSha2 = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
+    return { tag: tag2, versionFold: versionFold2, releaseSha: releaseSha2 };
+  });
   const { checks, releaseUrl, announceNote, dispatch: d } = await completeMainRelease(deps, ctx, meta, deployModel, watch, options, tag, releaseSha);
   const retirement = await retireRcRuntime(deps, ctx, deployModel, d.deployStatus, releasedRcSha);
   const devRollForward = await rollDevelopmentForward(deps, ctx, tag);
@@ -14806,16 +14925,24 @@ function cursorPluginPinsNeedingSeed(pins, releasedVersion) {
     return false;
   });
 }
+function cursorPluginCacheSeedTargets(pins, releasedVersion, cacheRoot, cacheRootExists = false) {
+  const needing = cursorPluginPinsNeedingSeed(pins, releasedVersion);
+  if (needing.length > 0) return needing.map((pin) => pin.path);
+  if (pins.length === 0 && cacheRoot && cacheRootExists && isSemverVersion(releasedVersion)) {
+    return [(0, import_node_path15.join)(cacheRoot, `v${releasedVersion.replace(/^v/, "")}`)];
+  }
+  return [];
+}
 async function applyCursorPluginCacheSeed(input) {
   if (!isSemverVersion(input.releasedVersion)) return false;
-  const pinsToSeed = cursorPluginPinsNeedingSeed(input.pins, input.releasedVersion);
-  if (pinsToSeed.length === 0) return false;
+  const targets = cursorPluginCacheSeedTargets(input.pins, input.releasedVersion, input.cacheRoot, input.cacheRootExists);
+  if (targets.length === 0) return false;
   const tmpRoot = await input.mkdtemp("mmi-cursor-seed-");
   const source = await resolvePluginMmiSource(input.releasedVersion, input.hubCheckout, tmpRoot, input.execFileP);
   if (!source) return false;
   input.log(`  \u21BB seeding Cursor MMI plugin cache \u2192 ${input.releasedVersion}\u2026`);
-  for (const pin of pinsToSeed) {
-    syncDirContents(source, pin.path);
+  for (const dest of targets) {
+    syncDirContents(source, dest);
   }
   (0, import_node_fs14.rmSync)(tmpRoot, { recursive: true, force: true });
   return true;
@@ -15095,6 +15222,33 @@ function buildMmiPluginCacheCleanupCheck(input) {
     }))
   };
 }
+var CURSOR_PLUGIN_CACHE_CLEANUP_LABEL = "leftover older MMI plugin cache pins (Cursor)";
+var CURSOR_PLUGIN_CACHE_CLEANUP_FIX = "older Cursor MMI plugin cache pins can be removed manually after confirming in Cursor Settings \u2192 Plugins \u2192 Marketplace which pin is registered";
+function buildCursorPluginCacheCleanupCheck(input) {
+  const base = {
+    ok: true,
+    label: CURSOR_PLUGIN_CACHE_CLEANUP_LABEL,
+    fix: CURSOR_PLUGIN_CACHE_CLEANUP_FIX
+  };
+  if (!input.isOrgRepo || !isSemverVersion2(input.releasedVersion)) return base;
+  const semverPins = input.pins.filter((pin) => isSemverVersion2(pin.version));
+  if (semverPins.length === 0) return base;
+  const activeVersion = semverPins.map((pin) => pin.version).reduce((a, b) => compareVersions(a, b) >= 0 ? a : b);
+  const protectedVersions = new Set(
+    [normalizeVersion(input.releasedVersion), normalizeVersion(activeVersion)].filter((v) => Boolean(v))
+  );
+  const leftoverPins = semverPins.filter((pin) => !protectedVersions.has(normalizeVersion(pin.version)));
+  if (leftoverPins.length === 0) return base;
+  const leftovers = leftoverPins.map((pin) => ({ surface: "cursor", root: input.cacheRoot, name: pin.name, path: pin.path }));
+  const listed = leftoverPins.map((pin) => `${pin.name} (${pin.version})`).join(", ");
+  return {
+    ...base,
+    ok: false,
+    severityOverride: "advisory",
+    leftovers,
+    fix: `${leftoverPins.length} older Cursor MMI plugin cache pin(s) left behind by marketplace re-clones: ${listed}. Not auto-removed: which pin Cursor's Team Marketplace registration is bound to cannot be read programmatically (no per-user CLI, #2409), and the registration may still point at an older pin \u2014 after confirming in Cursor Settings \u2192 Plugins \u2192 Marketplace that the newer pin is the registered one, the older dir(s) can be removed manually`
+  };
+}
 var NESTED_PLUGIN_TREE_LABEL = "self-nested MMI plugin cache tree (#1126)";
 var NESTED_PLUGIN_TREE_FIX = "SessionStart and mmi-cli doctor auto-clear when possible; if this persists, run the MAX_PATH-safe robocopy cleanup for a self-nested MMI plugin cache tree (#1126)";
 function nestedPluginTreeCleanupCommand(paths, isWindows) {
@@ -15117,7 +15271,21 @@ function buildNestedPluginTreeCheck(input) {
     fix: `${nested.length} self-nested MMI plugin cache tree(s) (#1126) exceed MAX_PATH and can't self-clean \u2014 run: ${nestedPluginTreeCleanupCommand(nested.map((n) => n.path), input.isWindows)}`
   };
 }
+function nestedTreeReinstallGapFix(surfaces) {
+  const recoveries = surfaces.map((s) => PLUGIN_SURFACE_HEAL[s].recovery).join("   and   ");
+  return `self-nested MMI plugin cache tree(s) cleared, but the plugin was NOT reinstalled for ${surfaces.join(" + ")} (host CLI unavailable or reinstall failed) \u2014 run: ${recoveries}`;
+}
 var CODEX_ACTIVE_CACHE_LABEL = "Codex active plugin cache (vs latest release)";
+function codexEnabledPluginVersionFromList(jsonText, pluginId = MMI_PLUGIN_ID) {
+  try {
+    const parsed = JSON.parse(jsonText);
+    const rows = Array.isArray(parsed?.installed) ? parsed.installed : [];
+    const row = rows.find((r) => r?.pluginId === pluginId && r.installed === true && r.enabled === true);
+    return isSemverVersion2(row?.version) ? row.version.trim().replace(/^v/, "") : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function buildCodexActiveCacheCheck(input) {
   const base = {
     ok: true,
@@ -15125,6 +15293,18 @@ function buildCodexActiveCacheCheck(input) {
     fix: CODEX_PLUGIN_RECOVERY
   };
   if (!input.isOrgRepo || !isSemverVersion2(input.releasedVersion)) return base;
+  if (isSemverVersion2(input.codexActiveVersion)) {
+    if (compareVersions(input.codexActiveVersion, input.releasedVersion) < 0) {
+      return {
+        ...base,
+        ok: false,
+        activeCacheVersion: input.codexActiveVersion,
+        releasedVersion: input.releasedVersion,
+        fix: `\`codex plugin list\` reports mmi@mutmutco enabled at ${input.codexActiveVersion} < ${input.releasedVersion} (a newer cache dir or install record may also exist and mask it) \u2014 run \`mmi-cli doctor --apply\` (forces the Codex remove/re-add when \`codex\` is on PATH; restart Codex after), or manually: ${CODEX_PLUGIN_RECOVERY}`
+      };
+    }
+    return { ...base, activeCacheVersion: input.codexActiveVersion, releasedVersion: input.releasedVersion };
+  }
   if (isSemverVersion2(input.codexRecordVersion) && compareVersions(input.codexRecordVersion, input.releasedVersion) < 0) {
     return base;
   }
@@ -15172,6 +15352,55 @@ function reloadAction(surface) {
       return "restart Claude Code (or run /reload-plugins)";
   }
 }
+function restartAction(surface) {
+  switch (surface) {
+    case "claude-vscode":
+      return "fully restart VS Code";
+    case "codex":
+      return "fully restart Codex";
+    case "opencode":
+      return "fully restart OpenCode";
+    case "cursor":
+      return "fully restart Cursor";
+    case "claude-cli":
+    case "shell":
+    default:
+      return "fully restart Claude Code";
+  }
+}
+function parseSessionSkillRootVersion(pluginRoot) {
+  const trimmed = pluginRoot?.trim();
+  if (!trimmed) return void 0;
+  const segments = trimmed.split(/[\\/]+/).filter(Boolean);
+  const mmiIdx = segments.findIndex((seg, i) => seg === "mmi" && segments[i - 1] === "mutmutco");
+  if (mmiIdx < 0) return void 0;
+  const candidate = segments[mmiIdx + 1];
+  return candidate && /^v?\d+\.\d+\.\d+/.test(candidate) ? candidate.replace(/^v/, "") : void 0;
+}
+var SESSION_SKILL_ROOT_LABEL = "Session-loaded MMI skill roots (vs on-disk plugin cache)";
+function buildSessionSkillRootCheck(input) {
+  const base = {
+    ok: true,
+    label: SESSION_SKILL_ROOT_LABEL,
+    fix: `fully restart the host to load the current MMI skill roots \u2014 a running session does not hot-refresh them, and a plugin reload does not re-register them`
+  };
+  if (!input.isOrgRepo) return base;
+  const sessionVersion = parseSessionSkillRootVersion(input.pluginRoot);
+  if (!sessionVersion) return base;
+  const activeCacheVersion = highestSemver(input.cacheVersions ?? []);
+  if (!isSemverVersion2(activeCacheVersion)) return { ...base, sessionVersion };
+  if (compareVersions(sessionVersion, activeCacheVersion) >= 0) {
+    return { ...base, sessionVersion, activeCacheVersion };
+  }
+  return {
+    ...base,
+    ok: false,
+    severityOverride: "advisory",
+    sessionVersion,
+    activeCacheVersion,
+    fix: `This ${input.surface} session loaded MMI skill roots from ${sessionVersion} but the on-disk plugin cache is ${activeCacheVersion} \u2014 a running session does NOT hot-refresh skill roots and a plugin reload does not re-register them, so ${restartAction(input.surface)} to load ${activeCacheVersion}. Until then this session keeps executing the ${sessionVersion} skill bundle; halt autonomous /grind and /build first.`
+  };
+}
 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";
@@ -15703,6 +15932,9 @@ function cursorPluginInstallFix(input) {
   const localSeed = input.hubCheckout ? `temporary fallback: copy ${joinCachePath(input.hubCheckout, "plugins", "mmi")} to ${cacheDir}, then restart Cursor` : `temporary fallback: copy plugins/mmi from a local MMI-Hub checkout to ${cacheDir}, then restart Cursor`;
   return `Cursor plugin cache at ${cacheDir} is empty or missing ${CURSOR_PLUGIN_JSON_REL}, ${CURSOR_HOOKS_JSON_REL}, or the cursor-hook dispatcher script \u2014 ${autoSeed}; ${marketplaceRefresh}; ${authSteps}; ${localSeed}; ${logHint}; ${guide}`;
 }
+function cursorSeededFromNothingAdvisoryFix(releasedVersion) {
+  return `Cursor MMI plugin cache seeded from nothing${releasedVersion ? ` at ${releasedVersion}` : ""} \u2014 the cache is healthy, but the Team Marketplace pin REGISTRATION could not be verified (no per-user CLI, #2409): if MMI commands do not load after restarting Cursor, a master-admin must register/refresh the MMI Team Marketplace in Cursor Settings \u2192 Plugins \u2192 Marketplace (\xA76.8); ${CURSOR_MARKETPLACE_INSTALL_GUIDE}`;
+}
 function buildCursorPluginInstallCheck(input) {
   const base = {
     ok: true,
@@ -15820,9 +16052,7 @@ function buildHubDeployFreshnessCheck(input) {
   };
 }
 var PLAYWRIGHT_MCP_VISION_CAP_LABEL = "Playwright MCP vision caps (--caps=vision prohibited)";
-var PLAYWRIGHT_MCP_VISION_CAP_FIX = "remove --caps=vision (and vision-first defaults) from Playwright MCP args \u2014 use DOM-first tools; see skills/browser-automation/SKILL.md and bootstrap seed mcp-playwright.template.json";
 var PLAYWRIGHT_MCP_OUTPUT_DIR_LABEL = "Playwright MCP output dir (use tmp/playwright-mcp)";
-var PLAYWRIGHT_MCP_OUTPUT_DIR_FIX = "configure Playwright MCP args with --output-dir tmp/playwright-mcp; see skills/browser-automation/SKILL.md and bootstrap seed mcp-playwright.template.json";
 function textHasPlaywrightMcp(content) {
   const normalized = content.replace(/\r\n/g, "\n");
   return /@playwright\/mcp/.test(normalized) || /mcp_servers\.playwright/.test(normalized) || /"playwright"\s*:\s*\{/.test(normalized) || /\bmcpServers\b/.test(normalized);
@@ -15837,45 +16067,10 @@ function textHasPlaywrightVisionCap(content) {
   if (/\bvision[-_]?(?:first|only|mode)\b/i.test(normalized)) return true;
   return false;
 }
-function buildPlaywrightMcpVisionCapCheck(input) {
-  const base = {
-    ok: true,
-    label: PLAYWRIGHT_MCP_VISION_CAP_LABEL,
-    fix: PLAYWRIGHT_MCP_VISION_CAP_FIX
-  };
-  if (!input.isOrgRepo) return base;
-  const offending = input.configs.filter((c) => textHasPlaywrightVisionCap(c.content)).map((c) => c.path);
-  if (offending.length === 0) return base;
-  return {
-    ...base,
-    ok: false,
-    offendingPaths: offending,
-    fix: `${PLAYWRIGHT_MCP_VISION_CAP_FIX} \u2014 found in: ${offending.join(", ")}`
-  };
-}
 function textHasCanonicalPlaywrightOutputDir(content) {
   const normalized = content.replace(/\r\n/g, "\n");
   return /--output-dir(?:\s*=\s*|["'\s,]+)tmp\/playwright-mcp\b/.test(normalized);
 }
-function textNeedsPlaywrightOutputDir(content) {
-  return textHasPlaywrightMcp(content) && !textHasCanonicalPlaywrightOutputDir(content);
-}
-function buildPlaywrightMcpOutputDirCheck(input) {
-  const base = {
-    ok: true,
-    label: PLAYWRIGHT_MCP_OUTPUT_DIR_LABEL,
-    fix: PLAYWRIGHT_MCP_OUTPUT_DIR_FIX
-  };
-  if (!input.isOrgRepo) return base;
-  const offending = input.configs.filter((c) => textNeedsPlaywrightOutputDir(c.content)).map((c) => c.path);
-  if (offending.length === 0) return base;
-  return {
-    ...base,
-    ok: false,
-    offendingPaths: offending,
-    fix: `${PLAYWRIGHT_MCP_OUTPUT_DIR_FIX} \u2014 missing in: ${offending.join(", ")}`
-  };
-}
 var STRAY_BROWSER_ARTIFACT_DIRS = [".playwright-mcp", "playwright-report", "test-results"];
 var BROWSER_ARTIFACTS_LABEL = "browser MCP artifacts outside tmp/ (use tmp/playwright-mcp)";
 var BROWSER_ARTIFACTS_FIX = "move or delete stray Playwright output at repo root; re-run MCP with --output-dir tmp/playwright-mcp \u2014 see skills/browser-automation/SKILL.md";
@@ -15915,6 +16110,12 @@ function buildSelfUpdateHaltPayload(input) {
     checks: input.checks
   };
 }
+var DOCTOR_SELF_UPDATE_HALT_EXIT_CODE = 3;
+var DOCTOR_SELF_UPDATE_HALT_SENTINEL = "MMI_DOCTOR_SELF_UPDATE_HALT";
+function selfUpdateHaltSentinelLine(input) {
+  const to = input.report.releasedVersion ?? "latest";
+  return `${DOCTOR_SELF_UPDATE_HALT_SENTINEL} rerunRequired=true updatedTo=${to} rerun="mmi-cli ${input.rerunArgs.join(" ")}"`;
+}
 var DOCTOR_POST_SELF_UPDATE_ENV = "MMI_DOCTOR_POST_SELF_UPDATE";
 function buildSelfUpdateReexecArgs(opts) {
   const args = ["doctor"];
@@ -16102,6 +16303,262 @@ function buildPluginResolvabilityCheck(input) {
   }
 }
 
+// src/mcp-reconcile.ts
+var PLAYWRIGHT_MCP_SPEC = {
+  name: "playwright",
+  command: "npx",
+  args: ["-y", "@playwright/mcp@latest", "--output-dir", "tmp/playwright-mcp"],
+  legacyNames: []
+};
+var MCP_RECONCILE_LABEL = "MCP server registrations (org-managed Playwright)";
+var MCP_RECONCILE_FIX = "register/reconcile the org Playwright MCP server (npx -y @playwright/mcp@latest --output-dir tmp/playwright-mcp) \u2014 run `mmi-cli doctor --apply`; see skills/browser-automation/SKILL.md and bootstrap seed mcp-playwright.template.json";
+function extractServerBlock(content, format, spec) {
+  return format === "json" ? extractJsonServer(content, spec) : extractTomlServer(content, spec);
+}
+function extractJsonServer(content, spec) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { kind: "unparseable" };
+  }
+  if (parsed == null || typeof parsed !== "object") return { kind: "unparseable" };
+  const servers = parsed.mcpServers;
+  if (servers == null || typeof servers !== "object") return { kind: "absent" };
+  const bag = servers;
+  for (const name of [spec.name, ...spec.legacyNames]) {
+    if (Object.prototype.hasOwnProperty.call(bag, name)) {
+      return { kind: "found", matchedName: name, isLegacy: name !== spec.name, blockText: JSON.stringify(bag[name]) };
+    }
+  }
+  return { kind: "absent" };
+}
+function extractTomlServer(content, spec) {
+  const blocks = parseTomlBlocks(content.replace(/\r\n/g, "\n").split("\n"));
+  for (const name of [spec.name, ...spec.legacyNames]) {
+    const full = `mcp_servers.${name}`;
+    const block = blocks.find((b) => b.name === full && !b.isArrayTable);
+    if (block) {
+      const blockText = [block.headerRaw, ...block.body].filter((l) => l != null).join("\n");
+      return { kind: "found", matchedName: name, isLegacy: name !== spec.name, blockText };
+    }
+  }
+  return { kind: "absent" };
+}
+function detectMcpState(target, spec) {
+  if (!target.present) return { target, state: "skip", action: "skip", reasons: [] };
+  if (target.content == null) {
+    if (target.createWhenFileAbsent) return { target, state: "absent", action: "install", reasons: [] };
+    return { target, state: "skip", action: "skip", reasons: [] };
+  }
+  const extract = extractServerBlock(target.content, target.format, spec);
+  if (extract.kind === "unparseable") {
+    return { target, state: "drifted", action: "reconcile", reasons: ["unparseable"] };
+  }
+  if (extract.kind === "absent") {
+    return { target, state: "absent", action: "install", reasons: [] };
+  }
+  const reasons = [];
+  if (extract.isLegacy) reasons.push("legacy-name");
+  if (textHasPlaywrightVisionCap(extract.blockText)) reasons.push("vision-cap");
+  if (!textHasCanonicalPlaywrightOutputDir(extract.blockText)) reasons.push("output-dir");
+  if (reasons.length === 0) {
+    return { target, state: "healthy", action: "none", reasons: [], matchedName: extract.matchedName };
+  }
+  return { target, state: "drifted", action: "reconcile", reasons, matchedName: extract.matchedName };
+}
+function planMcpReconcile(targets, spec) {
+  return targets.map((t) => detectMcpState(t, spec));
+}
+function buildMcpReconcileCheck(plan) {
+  const base = {
+    ok: true,
+    label: MCP_RECONCILE_LABEL,
+    fix: MCP_RECONCILE_FIX,
+    severityOverride: "advisory"
+  };
+  const gaps = plan.filter((p) => p.action === "install" || p.action === "reconcile");
+  if (gaps.length === 0) return base;
+  const detail = gaps.map((g) => `${g.target.path} (${g.action === "install" ? "missing" : g.reasons.join("+") || "drifted"})`).join(", ");
+  return {
+    ...base,
+    ok: false,
+    fix: `${MCP_RECONCILE_FIX} \u2014 ${detail}`,
+    mcpGaps: gaps.map((g) => ({ path: g.target.path, action: g.action, reasons: g.reasons }))
+  };
+}
+function applyMcpReconcile(targets, spec, opts) {
+  const results = [];
+  for (const item of planMcpReconcile(targets, spec)) {
+    if (item.action !== "install" && item.action !== "reconcile") continue;
+    const t = item.target;
+    if (t.isRepoFile && !opts.repoWritesAllowed) {
+      results.push({ target: t, action: item.action, outcome: "skipped-repo-write" });
+      continue;
+    }
+    const next = t.format === "json" ? renderJsonMcpConfig(t.content, spec) : renderTomlMcpConfig(t.content, spec);
+    if (next == null) {
+      results.push({ target: t, action: item.action, outcome: "unparseable" });
+      continue;
+    }
+    results.push({ target: t, action: item.action, outcome: opts.write(t.path, next) ? "wrote" : "write-failed" });
+  }
+  return results;
+}
+function renderJsonMcpConfig(existing, spec) {
+  const canonicalEntry = { command: spec.command, args: [...spec.args] };
+  if (existing == null || existing.trim() === "") {
+    return `${JSON.stringify({ mcpServers: { [spec.name]: canonicalEntry } }, null, 2)}
+`;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return null;
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const obj = parsed;
+  const rawServers = obj.mcpServers;
+  if (rawServers != null && (typeof rawServers !== "object" || Array.isArray(rawServers))) return null;
+  const servers = rawServers ?? {};
+  const prior = servers[spec.name] ?? spec.legacyNames.map((n) => servers[n]).find((v) => v != null);
+  for (const legacy of spec.legacyNames) delete servers[legacy];
+  const priorObj = prior != null && typeof prior === "object" && !Array.isArray(prior) ? prior : {};
+  servers[spec.name] = { ...priorObj, ...canonicalEntry };
+  obj.mcpServers = servers;
+  const text = `${JSON.stringify(obj, null, 2)}
+`;
+  return existing.includes("\r\n") ? text.replace(/\n/g, "\r\n") : text;
+}
+function isTomlEscaped(line, i) {
+  let n = 0;
+  for (let j = i - 1; j >= 0 && line[j] === "\\"; j--) n += 1;
+  return n % 2 === 1;
+}
+function advanceTomlStringState(line, state) {
+  let multi = state;
+  let single = null;
+  let i = 0;
+  while (i < line.length) {
+    if (multi != null) {
+      if (line.startsWith(multi, i) && !(multi === '"""' && isTomlEscaped(line, i))) {
+        multi = null;
+        i += 3;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+    if (single != null) {
+      if (line[i] === single && !(single === '"' && isTomlEscaped(line, i))) single = null;
+      i += 1;
+      continue;
+    }
+    if (line[i] === "#") break;
+    if (line.startsWith('"""', i)) {
+      multi = '"""';
+      i += 3;
+      continue;
+    }
+    if (line.startsWith("'''", i)) {
+      multi = "'''";
+      i += 3;
+      continue;
+    }
+    if (line[i] === '"' || line[i] === "'") {
+      single = line[i];
+      i += 1;
+      continue;
+    }
+    i += 1;
+  }
+  return multi;
+}
+function parseTomlBlocks(lines) {
+  const blocks = [];
+  let current = { headerRaw: null, name: null, isArrayTable: false, body: [] };
+  let multi = null;
+  const tableRe = /^\s*\[\s*([^[\]]+?)\s*\]\s*$/;
+  const arrayTableRe = /^\s*\[\[\s*([^[\]]+?)\s*\]\]\s*$/;
+  for (const line of lines) {
+    if (multi == null) {
+      const am = arrayTableRe.exec(line);
+      const tm = am == null ? tableRe.exec(line) : null;
+      if (am != null || tm != null) {
+        blocks.push(current);
+        current = { headerRaw: line, name: (am ?? tm)[1].trim(), isArrayTable: am != null, body: [] };
+        continue;
+      }
+    }
+    multi = advanceTomlStringState(line, multi);
+    current.body.push(line);
+  }
+  blocks.push(current);
+  return blocks;
+}
+function mergeCanonicalTomlBody(body, commandLine, argsLine) {
+  const preserved = [];
+  for (let i = 0; i < body.length; i++) {
+    const line = body[i];
+    const trimmed = line.trim();
+    if (/^command\s*=/.test(trimmed)) continue;
+    if (/^args\s*=/.test(trimmed)) {
+      let open = (line.match(/\[/g) ?? []).length;
+      let close = (line.match(/\]/g) ?? []).length;
+      while (open > close && i + 1 < body.length) {
+        i += 1;
+        open += (body[i].match(/\[/g) ?? []).length;
+        close += (body[i].match(/\]/g) ?? []).length;
+      }
+      continue;
+    }
+    preserved.push(line);
+  }
+  return [commandLine, argsLine, ...preserved];
+}
+function renderTomlMcpConfig(existing, spec) {
+  const commandLine = `command = ${JSON.stringify(spec.command)}`;
+  const argsLine = `args = [${spec.args.map((a) => JSON.stringify(a)).join(", ")}]`;
+  const canonicalHeader = `[mcp_servers.${spec.name}]`;
+  const canonicalName = `mcp_servers.${spec.name}`;
+  if (existing == null || existing.trim() === "") {
+    return `${canonicalHeader}
+${commandLine}
+${argsLine}
+`;
+  }
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const lines = existing.replace(/\r\n/g, "\n").split("\n");
+  const legacyFull = new Set(spec.legacyNames.map((n) => `mcp_servers.${n}`));
+  const all = parseTomlBlocks(lines);
+  if (all.some((b) => b.isArrayTable && b.name != null && (b.name === canonicalName || legacyFull.has(b.name)))) return null;
+  const targetBlock = all.find((b) => !b.isArrayTable && b.name === canonicalName) ?? all.find((b) => !b.isArrayTable && b.name != null && legacyFull.has(b.name));
+  const out = [];
+  for (const b of all) {
+    if (b === targetBlock) {
+      out.push({ headerRaw: canonicalHeader, name: canonicalName, isArrayTable: false, body: mergeCanonicalTomlBody(b.body, commandLine, argsLine) });
+      continue;
+    }
+    if (targetBlock != null && !b.isArrayTable && b.name != null && legacyFull.has(b.name)) continue;
+    out.push(b);
+  }
+  if (targetBlock != null) {
+    const joined = out.flatMap((b) => b.headerRaw != null ? [b.headerRaw, ...b.body] : b.body).join("\n");
+    return eol === "\r\n" ? joined.replace(/\n/g, "\r\n") : joined;
+  }
+  const base = out.flatMap((b) => b.headerRaw != null ? [b.headerRaw, ...b.body] : b.body).join("\n").replace(/\n+$/, "");
+  const block = `${canonicalHeader}
+${commandLine}
+${argsLine}`;
+  const combined = base === "" ? `${block}
+` : `${base}
+
+${block}
+`;
+  return eol === "\r\n" ? combined.replace(/\n/g, "\r\n") : combined;
+}
+
 // src/cli-doctor-shared.ts
 var import_node_fs15 = require("node:fs");
 var import_node_path16 = require("node:path");
@@ -16358,7 +16815,20 @@ var CLAUDE_PLUGIN_TIMEOUT_MS = 12e4;
 function runHostBin(bin, args, opts) {
   return isWin ? execFileP2("cmd.exe", ["/c", bin, ...args], opts) : execFileP2(bin, args, opts);
 }
-function reexecMmiCli(args) {
+function reexecStrategies(input) {
+  const strategies = [
+    input.platform === "win32" ? { command: "cmd.exe", args: ["/c", "mmi-cli"], kind: "cmd-shim" } : { command: "mmi-cli", args: [], kind: "direct" }
+  ];
+  if (input.argv1) strategies.push({ command: input.execPath, args: [input.argv1], kind: "direct" });
+  return strategies;
+}
+var CMD_NOT_RECOGNIZED_EXIT_CODE = 9009;
+function reexecAttemptOutcome(strategy, code) {
+  if (code < 0) return "strategy-failed";
+  if (strategy.kind === "cmd-shim" && code === CMD_NOT_RECOGNIZED_EXIT_CODE) return "strategy-failed";
+  return "result";
+}
+function spawnReexecAttempt(command, args, env) {
   return new Promise((resolve6) => {
     let settled = false;
     const done = (code) => {
@@ -16367,12 +16837,20 @@ function reexecMmiCli(args) {
         resolve6(code);
       }
     };
-    const env = { ...process.env, [DOCTOR_POST_SELF_UPDATE_ENV]: "1" };
-    const child = isWin ? (0, import_node_child_process10.spawn)("cmd.exe", ["/c", "mmi-cli", ...args], { stdio: "inherit", env }) : (0, import_node_child_process10.spawn)("mmi-cli", args, { stdio: "inherit", env });
+    const child = (0, import_node_child_process10.spawn)(command, args, { stdio: "inherit", env });
     child.on("error", () => done(-1));
     child.on("exit", (code) => done(code ?? 0));
   });
 }
+async function reexecMmiCli(args) {
+  const strategies = reexecStrategies({ platform: process.platform, argv1: process.argv[1], execPath: process.execPath });
+  const env = { ...process.env, [DOCTOR_POST_SELF_UPDATE_ENV]: "1" };
+  for (const strategy of strategies) {
+    const code = await spawnReexecAttempt(strategy.command, [...strategy.args, ...args], env);
+    if (reexecAttemptOutcome(strategy, code) === "result") return code;
+  }
+  return -1;
+}
 function hostBinAvailable(bin) {
   return execFileP2(isWin ? "where" : "which", [bin]).then(() => true).catch(() => false);
 }
@@ -16392,6 +16870,15 @@ async function runCodexPlugin(args) {
     return false;
   }
 }
+async function codexEnabledMmiVersion() {
+  if (!await hostBinAvailable("codex")) return void 0;
+  try {
+    const { stdout } = await runHostBin("codex", ["plugin", "list", "--json"], { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
+    return codexEnabledPluginVersionFromList(stdout, MMI_PLUGIN_ID);
+  } catch {
+    return void 0;
+  }
+}
 async function marketplaceAddRefSupported(bin) {
   try {
     const { stdout, stderr } = await runHostBin(bin, ["plugin", "marketplace", "add", "--help"], {
@@ -16739,6 +17226,12 @@ function opencodeInstalledVersionForDoctor() {
     diskVersion: readOpencodeAdapterDiskVersion()
   });
 }
+function opencodePersistedVersionForDoctor() {
+  return pickOpencodeActiveVersion({
+    cacheVersion: readOpencodeLoadedCacheVersion(),
+    diskVersion: readOpencodeAdapterDiskVersion()
+  });
+}
 function opencodePluginVersionsForReport() {
   return [process.env.MMI_OPENCODE_PLUGIN_VERSION, readOpencodeAdapterDiskVersion()].filter((v) => Boolean(v));
 }
@@ -16856,8 +17349,8 @@ function hasNestedMmiChild(versionDir) {
   }
 }
 function nestedPluginTreeSnapshot() {
-  return mmiPluginCacheRootSnapshots().filter((root) => root.surface === "claude").flatMap(
-    (root) => root.entries.filter((e) => e.isDirectory && /^v?\d+\.\d+\.\d+/.test(e.name)).map((e) => ({ surface: "claude", path: e.path, nested: hasNestedMmiChild(e.path) }))
+  return mmiPluginCacheRootSnapshots().flatMap(
+    (root) => root.entries.filter((e) => e.isDirectory && /^v?\d+\.\d+\.\d+/.test(e.name)).map((e) => ({ surface: root.surface, path: e.path, nested: hasNestedMmiChild(e.path) }))
   );
 }
 function uniqueQuarantineTarget(path2) {
@@ -16933,21 +17426,95 @@ function readTextFile(path2) {
     return null;
   }
 }
-function playwrightMcpConfigSnapshots() {
+function mcpDirExists(path2) {
+  try {
+    return (0, import_node_fs17.existsSync)(path2);
+  } catch {
+    return false;
+  }
+}
+function mcpConfigTargets() {
   const cwd = process.cwd();
   const home = (0, import_node_os6.homedir)();
-  const candidates = [
-    (0, import_node_path17.join)(cwd, ".mcp.json"),
-    (0, import_node_path17.join)(cwd, ".cursor", "mcp.json"),
-    (0, import_node_path17.join)(home, ".cursor", "mcp.json"),
-    (0, import_node_path17.join)(home, ".codex", "config.toml")
+  const cursorProjectDir = (0, import_node_path17.join)(cwd, ".cursor");
+  const cursorUserDir = (0, import_node_path17.join)(home, ".cursor");
+  const codexDir = (0, import_node_path17.join)(home, ".codex");
+  return [
+    // Claude Code project MCP — reconciled if present, never conjured (org seeds .cursor/mcp.json, not this).
+    {
+      host: "claude-code",
+      label: "Claude Code project MCP",
+      path: (0, import_node_path17.join)(cwd, ".mcp.json"),
+      format: "json",
+      present: true,
+      // parent is the repo root (cwd); the caller gates the whole reconcile on isOrgRepo
+      isRepoFile: true,
+      createWhenFileAbsent: false,
+      content: readTextFile((0, import_node_path17.join)(cwd, ".mcp.json"))
+    },
+    // Cursor project MCP — the bootstrap-seeded surface; restored if its .cursor dir exists but the file is gone.
+    {
+      host: "cursor-project",
+      label: "Cursor project MCP",
+      path: (0, import_node_path17.join)(cursorProjectDir, "mcp.json"),
+      format: "json",
+      present: mcpDirExists(cursorProjectDir),
+      isRepoFile: true,
+      createWhenFileAbsent: true,
+      content: readTextFile((0, import_node_path17.join)(cursorProjectDir, "mcp.json"))
+    },
+    // Cursor user MCP — global; written only when Cursor is installed (~/.cursor exists).
+    {
+      host: "cursor-user",
+      label: "Cursor user MCP",
+      path: (0, import_node_path17.join)(cursorUserDir, "mcp.json"),
+      format: "json",
+      present: mcpDirExists(cursorUserDir),
+      isRepoFile: false,
+      createWhenFileAbsent: true,
+      content: readTextFile((0, import_node_path17.join)(cursorUserDir, "mcp.json"))
+    },
+    // Codex user config (TOML) — global; written only when Codex is installed (~/.codex exists).
+    {
+      host: "codex",
+      label: "Codex user config",
+      path: (0, import_node_path17.join)(codexDir, "config.toml"),
+      format: "toml",
+      present: mcpDirExists(codexDir),
+      isRepoFile: false,
+      createWhenFileAbsent: true,
+      content: readTextFile((0, import_node_path17.join)(codexDir, "config.toml"))
+    }
   ];
-  const out = [];
-  for (const path2 of candidates) {
-    const content = readTextFile(path2);
-    if (content != null) out.push({ path: path2, content });
+}
+function writeMcpConfigFile(path2, content) {
+  try {
+    (0, import_node_fs17.writeFileSync)(path2, content, "utf8");
+    return true;
+  } catch {
+    return false;
   }
-  return out;
+}
+async function reconcileMcpRegistrations(input) {
+  if (!input.isOrgRepo) return buildMcpReconcileCheck([]);
+  const targets = mcpConfigTargets();
+  if (!input.apply) return buildMcpReconcileCheck(planMcpReconcile(targets, PLAYWRIGHT_MCP_SPEC));
+  const results = applyMcpReconcile(targets, PLAYWRIGHT_MCP_SPEC, {
+    repoWritesAllowed: input.repoWritesAllowed,
+    write: writeMcpConfigFile
+  });
+  for (const r of results) {
+    if (r.outcome === "wrote") {
+      input.onHealed();
+      const verb = r.action === "install" ? "registered" : "reconciled";
+      input.log(`  \u21BB ${verb} Playwright MCP in ${r.target.path} \u2014 restart the host to load it`);
+    } else if (r.outcome === "unparseable") {
+      input.log(`  \u26A0 ${r.target.label}: could not safely patch ${r.target.path} (unparseable) \u2014 fix it by hand`);
+    } else if (r.outcome === "write-failed") {
+      input.log(`  \u26A0 ${r.target.label}: failed to write ${r.target.path}`);
+    }
+  }
+  return buildMcpReconcileCheck(planMcpReconcile(mcpConfigTargets(), PLAYWRIGHT_MCP_SPEC));
 }
 function strayBrowserArtifactPaths() {
   const cwd = process.cwd();
@@ -17071,13 +17638,19 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
   checks.push(versionReport);
   if (selfUpdatedCli) {
     if (!opts.json) io.err(selfUpdateReexecLine(versionReport));
-    const code = await reexecMmiCli(buildSelfUpdateReexecArgs(opts));
+    const reexecArgs = buildSelfUpdateReexecArgs(opts);
+    const code = await reexecMmiCli(reexecArgs);
     if (code >= 0) {
       if (code > 0) process.exitCode = code;
       return;
     }
-    if (opts.json) io.log(JSON.stringify(buildSelfUpdateHaltPayload({ checks, updatedTo: versionReport.releasedVersion }), null, 2));
-    else io.err(selfUpdateHaltLine(versionReport));
+    process.exitCode = DOCTOR_SELF_UPDATE_HALT_EXIT_CODE;
+    if (opts.json) {
+      io.log(JSON.stringify(buildSelfUpdateHaltPayload({ checks, updatedTo: versionReport.releasedVersion }), null, 2));
+    } else {
+      io.err(selfUpdateHaltLine(versionReport));
+      io.err(selfUpdateHaltSentinelLine({ report: versionReport, rerunArgs: reexecArgs }));
+    }
     return;
   }
   checks.push({ ok: Boolean(cfg.sagaApiUrl), label: "Hub API URL configured", fix: "set MMI_HUB_URL or use a current MMI CLI/plugin build" });
@@ -17278,10 +17851,20 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
       releasedVersion
     });
     if (!opencodeVersionCheck.ok && repairFull) {
-      const refreshed = await forceInstallOpencodeMmiPlugins(openCodeConfigSnapshot, (m) => io.err(m));
-      const quarantined = quarantineStaleOpencodePluginCaches(releasedVersion, (m) => io.err(m));
-      if (refreshed || quarantined) {
-        opencodeInstalledVersion = opencodeInstalledVersionForDoctor() ?? opencodeInstalledVersion;
+      const persistedCurrent = () => buildOpencodeVersionCheck({
+        isOrgRepo,
+        installedVersion: opencodePersistedVersionForDoctor(),
+        releasedVersion
+      }).ok;
+      let refreshed = false;
+      let quarantined = false;
+      if (!persistedCurrent()) {
+        refreshed = await forceInstallOpencodeMmiPlugins(openCodeConfigSnapshot, (m) => io.err(m));
+        quarantined = quarantineStaleOpencodePluginCaches(releasedVersion, (m) => io.err(m));
+      }
+      if (persistedCurrent()) {
+        const wasReinstalled = refreshed || quarantined;
+        opencodeInstalledVersion = opencodePersistedVersionForDoctor() ?? opencodeInstalledVersion;
         opencodeVersionCheck = buildOpencodeVersionCheck({
           isOrgRepo,
           installedVersion: opencodeInstalledVersion,
@@ -17290,7 +17873,8 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
         if (opencodeVersionCheck.ok) {
           markPluginReloadRequired();
           markHealed();
-          io.err(`  \u21BB force-refreshed OpenCode MMI plugin \u2192 ${opencodeInstalledVersion ?? releasedVersion ?? "latest"} \u2014 ${reloadAction("opencode")} to load it`);
+          const version = opencodeInstalledVersion ?? releasedVersion ?? "latest";
+          io.err(wasReinstalled ? `  \u21BB force-refreshed OpenCode MMI plugin \u2192 ${version} \u2014 ${reloadAction("opencode")} to load it` : `  \u21BB OpenCode MMI plugin is current on disk (${version}); the running session is stale \u2014 ${reloadAction("opencode")} to load it`);
         }
       }
     }
@@ -17361,6 +17945,7 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
     return versions.sort((a, b) => compareVersions(b, a))[0];
   };
   const codexCacheVersions = () => mmiPluginCacheRootSnapshots().filter((r) => r.surface === "codex").flatMap((r) => r.entries.filter((e) => e.isDirectory).map((e) => e.name));
+  const codexActiveVersion = () => isOrgRepo && releasedVersion ? codexEnabledMmiVersion() : Promise.resolve(void 0);
   let cacheCleanupCheck = buildMmiPluginCacheCleanupCheck({
     isOrgRepo,
     roots: mmiPluginCacheRootSnapshots(),
@@ -17397,7 +17982,8 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
     isOrgRepo,
     releasedVersion,
     codexCacheVersions: codexCacheVersions(),
-    codexRecordVersion: codexRecordVersion()
+    codexRecordVersion: codexRecordVersion(),
+    codexActiveVersion: await codexActiveVersion()
   });
   if (!codexActiveCacheCheck.ok && repairFull) {
     const canDriveCodex = surfaceToken(surface) === "codex" || await hostBinAvailable("codex");
@@ -17409,7 +17995,8 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
         isOrgRepo,
         releasedVersion,
         codexCacheVersions: codexCacheVersions(),
-        codexRecordVersion: codexRecordVersion()
+        codexRecordVersion: codexRecordVersion(),
+        codexActiveVersion: await codexActiveVersion()
       });
     }
   }
@@ -17420,7 +18007,8 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
     entries: nestedPluginTreeSnapshot()
   });
   if (!nestedPluginTreeCheck.ok && nestedPluginTreeCheck.nested?.length && repairLocal) {
-    const nestedPaths = nestedPluginTreeCheck.nested.map((n) => n.path);
+    const nestedEntries = nestedPluginTreeCheck.nested;
+    const nestedPaths = nestedEntries.map((n) => n.path);
     if (await applyNestedPluginTreeCleanup(nestedPaths, (m) => io.err(m))) {
       nestedPluginTreeCheck = buildNestedPluginTreeCheck({
         isOrgRepo,
@@ -17428,36 +18016,62 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
         entries: nestedPluginTreeSnapshot()
       });
       if (nestedPluginTreeCheck.ok) {
-        io.err(`  \u21BB cleared self-nested MMI plugin cache tree(s) \u2014 reinstalling plugin\u2026`);
+        io.err(`  \u21BB cleared self-nested MMI plugin cache tree(s)`);
+      }
+      let reinstalledAny = false;
+      const unreinstalled = [];
+      for (const token of [...new Set(nestedEntries.map((n) => n.surface))]) {
+        const bin = token === "codex" ? "codex" : "claude";
+        const canDrive = surfaceToken(surface) === token || await hostBinAvailable(bin);
+        if (canDrive && await applyPluginHeal(token, surface, (m) => io.err(m), { force: true })) {
+          reinstalledAny = true;
+          io.err(`  \u21BB reinstalled MMI plugin (${token}) after nested-cache cleanup \u2014 ${reloadAction(surface)} to load MMI commands`);
+        } else {
+          unreinstalled.push(token);
+        }
       }
-      if (await applyPluginHeal("claude", surface, (m) => io.err(m))) {
+      if (reinstalledAny) {
         markPluginReloadRequired();
         markHealed();
-        io.err(`  \u21BB reinstalled MMI plugin after nested-cache cleanup \u2014 ${reloadAction(surface)} to load MMI commands`);
         nestedPluginTreeCheck = buildNestedPluginTreeCheck({
           isOrgRepo,
           isWindows: isWin,
           entries: nestedPluginTreeSnapshot()
         });
       }
+      if (unreinstalled.length > 0 && nestedPluginTreeCheck.ok) {
+        nestedPluginTreeCheck = { ...nestedPluginTreeCheck, ok: false, fix: nestedTreeReinstallGapFix(unreinstalled) };
+      }
     }
   }
   checks.push(nestedPluginTreeCheck);
   const cursorCacheRoot = cursorPluginCacheRoot();
+  const cursorCacheRootExists = (0, import_node_fs17.existsSync)(cursorCacheRoot);
   let cursorPins = cursorPluginCachePinSnapshots() ?? [];
+  checks.push(
+    buildCursorPluginCacheCleanupCheck({
+      isOrgRepo,
+      cacheRoot: cursorCacheRoot,
+      pins: cursorPins,
+      releasedVersion
+    })
+  );
   let cursorPluginCheck = buildCursorPluginInstallCheck({
     isOrgRepo,
     surface,
     cacheRoot: cursorCacheRoot,
-    cacheRootExists: (0, import_node_fs17.existsSync)(cursorCacheRoot),
+    cacheRootExists: cursorCacheRootExists,
     pins: cursorPins,
     hubCheckout: hubCheckoutForCursorSeed(),
     releasedVersion
   });
   if (!cursorPluginCheck.ok && repairLocal) {
+    const seedingFromNothing = cursorPins.length === 0;
     const seeded = await applyCursorPluginCacheSeed({
       pins: cursorPins,
       releasedVersion,
+      cacheRoot: cursorCacheRoot,
+      cacheRootExists: cursorCacheRootExists,
       hubCheckout: hubCheckoutForCursorSeed(),
       execFileP: execFileP2,
       mkdtemp: (prefix) => (0, import_promises2.mkdtemp)((0, import_node_path17.join)((0, import_node_os6.tmpdir)(), prefix)),
@@ -17469,14 +18083,26 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
         isOrgRepo,
         surface,
         cacheRoot: cursorCacheRoot,
-        cacheRootExists: (0, import_node_fs17.existsSync)(cursorCacheRoot),
+        cacheRootExists: cursorCacheRootExists,
         pins: cursorPins,
         hubCheckout: hubCheckoutForCursorSeed(),
         releasedVersion
       });
       if (cursorPluginCheck.ok) {
         markHealed();
-        io.err(`  \u21BB seeded Cursor MMI plugin cache \u2192 ${releasedVersion ?? "latest"} \u2014 ${reloadAction(surface)}`);
+        if (seedingFromNothing) {
+          io.err(
+            `  \u21BB seeded Cursor MMI plugin cache from nothing \u2192 ${releasedVersion ?? "latest"} (cache only \u2014 Team Marketplace registration not verified, #2409) \u2014 ${reloadAction(surface)}`
+          );
+          cursorPluginCheck = {
+            ...cursorPluginCheck,
+            ok: false,
+            severityOverride: "advisory",
+            fix: cursorSeededFromNothingAdvisoryFix(releasedVersion)
+          };
+        } else {
+          io.err(`  \u21BB seeded Cursor MMI plugin cache \u2192 ${releasedVersion ?? "latest"} \u2014 ${reloadAction(surface)}`);
+        }
       }
     }
   }
@@ -17497,20 +18123,29 @@ async function runDoctor(opts, io = consoleIo, readOrigin) {
       mmiCliOnPath: onPath
     })
   );
-  if (runExtended) {
-    const playwrightMcpConfigs = playwrightMcpConfigSnapshots();
-    checks.push(
-      buildPlaywrightMcpVisionCapCheck({
-        isOrgRepo,
-        configs: playwrightMcpConfigs
-      })
-    );
+  if (!opts.banner) {
     checks.push(
-      buildPlaywrightMcpOutputDirCheck({
+      await reconcileMcpRegistrations({
         isOrgRepo,
-        configs: playwrightMcpConfigs
+        apply: Boolean(opts.apply),
+        repoWritesAllowed,
+        log: (m) => io.err(m),
+        onHealed: markHealed
       })
     );
+  }
+  const sessionPluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  const sessionCacheSurface = sessionPluginRoot?.includes(".codex") ? "codex" : sessionPluginRoot?.includes(".claude") ? "claude" : void 0;
+  const sessionCacheVersions = sessionCacheSurface ? mmiPluginCacheRootSnapshots().filter((r) => r.surface === sessionCacheSurface).flatMap((r) => r.entries.filter((e) => e.isDirectory).map((e) => e.name)) : [];
+  checks.push(
+    buildSessionSkillRootCheck({
+      isOrgRepo,
+      surface,
+      pluginRoot: sessionPluginRoot,
+      cacheVersions: sessionCacheVersions
+    })
+  );
+  if (runExtended) {
     checks.push(
       buildBrowserArtifactsCheck({
         isOrgRepo,
@@ -19606,7 +20241,7 @@ board.command("prune-priority-labels").description("remove retired priority:* la
 });
 board.command("done <issue>").description("set a board item's Status to Done (does not close the GitHub issue; use `gh issue close`)").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--allow-partial", "return success JSON if the item resolves but the status move fails").action(async (issueRef, o) => {
   try {
-    const result = await moveBoardItem({ config: await loadConfigOrDiscover(), selector: issueRef, status: "Done", repo: o.repo, allowPartial: o.allowPartial });
+    const result = await moveBoardItem({ config: await loadConfigForBoardSelector(issueRef, o.repo), selector: issueRef, status: "Done", repo: o.repo, allowPartial: o.allowPartial });
     if (o.json) return console.log(JSON.stringify(result));
     console.log(result.partial ? `Partially moved ${result.item.ref}: ${result.warning}` : `Moved ${result.item.ref} -> Done`);
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "3.1.0",
+  "version": "3.2.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",