@mutmutco/cli 2.14.0 → 2.15.0

package/dist/index.cjs

@@ -4301,6 +4301,7 @@ var BOARD_STATUSES = ["Todo", "In Progress", "In Review", "Done"];
 var rawExecFileP2 = (0, import_node_util4.promisify)(import_node_child_process4.execFile);
 var BOARD_GIT_TIMEOUT_MS = 1e4;
 var WRITE_PROBE_CONCURRENCY = 8;
+var CLAIM_CONCURRENCY = 5;
 var execFileP2 = (file, args, options = {}) => (
   // encoding 'utf8' guarantees string output at runtime; the cast pins the type (promisify's
   // overloads widen to string|Buffer when options is spread in).
@@ -4675,17 +4676,16 @@ async function showBoardItem(options, deps = {}) {
   }
   return item;
 }
-async function claimBoardIssue(options, deps = {}) {
+async function prepareClaimContext(options, selectors, deps, collected) {
   const cfg = resolveBoardConfig(options.config);
   const client = deps.client ?? defaultGitHubClient();
-  const collected = await collectBoardItems(cfg, { repo: options.repo, allowPartial: options.allowPartial }, deps);
-  const selector = parseIssueSelector(options.selector, collected.repo);
-  try {
-    findBoardItem(collected.items, selector);
-  } catch (e) {
-    const fallback = (await fetchIssueProjectItem(client, cfg, selector)).item;
-    if (!fallback) throw e;
-    collected.items.push(fallback);
+  for (const selector of selectors) {
+    try {
+      findBoardItem(collected.items, selector);
+    } catch {
+      const fallback = (await fetchIssueProjectItem(client, cfg, selector)).item;
+      if (fallback) collected.items.push(fallback);
+    }
   }
   const writable = await resolveWritableReposForClaimables(collected.items, client, options.allowPartial ?? false);
   collected.warnings.push(...writable.warnings);
@@ -4698,8 +4698,12 @@ async function claimBoardIssue(options, deps = {}) {
     warnings: collected.warnings,
     partial: collected.partial
   };
-  const flatItem = findBoardItem(collected.items, selector);
-  if (flatItem.status === "Todo" && flatItem.assignees.length === 0 && !writable.repos.has(flatItem.repository.toLowerCase())) {
+  return { cfg, client, items: collected.items, writable: writable.repos, report };
+}
+async function claimOneBoardItem(ctx, selector, options) {
+  const { cfg, client, report } = ctx;
+  const flatItem = findBoardItem(ctx.items, selector);
+  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}`);
   }
   let item = findClaimableItem(report, selector);
@@ -4736,6 +4740,49 @@ async function claimBoardIssue(options, deps = {}) {
     partial: false
   };
 }
+async function claimBoardIssue(options, deps = {}) {
+  const cfg = resolveBoardConfig(options.config);
+  const collected = await collectBoardItems(cfg, { repo: options.repo, allowPartial: options.allowPartial }, deps);
+  const selector = parseIssueSelector(options.selector, collected.repo);
+  const ctx = await prepareClaimContext(options, [selector], deps, collected);
+  return claimOneBoardItem(ctx, selector, options);
+}
+async function claimBoardIssues(options, deps = {}) {
+  const cfg = resolveBoardConfig(options.config);
+  const collected = await collectBoardItems(cfg, { repo: options.repo, allowPartial: options.allowPartial }, deps);
+  const selectors = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of options.selectors) {
+    const selector = parseIssueSelector(raw, collected.repo);
+    const key = `${selector.repo.toLowerCase()}#${selector.number}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    selectors.push(selector);
+  }
+  const ctx = await prepareClaimContext(options, selectors, deps, collected);
+  const results = new Array(selectors.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < selectors.length) {
+      const index = next++;
+      const selector = selectors[index];
+      const ref = `${selector.repo}#${selector.number}`;
+      try {
+        const result = await claimOneBoardItem(ctx, selector, options);
+        results[index] = { ref: result.item.ref, claimed: true, item: result.item, status: result.status, partial: result.partial, warning: result.warning };
+      } catch (e) {
+        results[index] = { ref, claimed: false, reason: e.message };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CLAIM_CONCURRENCY, selectors.length) }, () => worker()));
+  return {
+    viewer: ctx.report.viewer,
+    repo: ctx.report.repo,
+    results,
+    failed: results.filter((result) => !result.claimed).length
+  };
+}
 async function setBoardItemPriority(client, cfg, itemId, priority) {
   if (!isPriorityFieldConfigured(cfg)) return void 0;
   const optionId = resolvePriorityOptionId(cfg, priority);
@@ -5315,6 +5362,7 @@ function trainPlan(command) {
       { label: "verify current branch is rc", gated: true },
       { label: "verify registry META for this project", command: "mmi-cli project get <owner/repo>", gated: true },
       { label: "preflight required main secret names", command: "mmi-cli secrets preflight --stage main --repo <owner/repo>", gated: true },
+      { label: "verify every main-only hotfix commit is covered by the rc candidate", command: "node scripts/hotfix-coverage.mjs", gated: true },
       { label: "merge rc to main", gated: true },
       { label: "for Hub distribution changes, verify the promoted SHA carries the release bump", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view", gated: true },
       { label: "tag release and publish GitHub Release", gated: true },
@@ -5323,10 +5371,10 @@ function trainPlan(command) {
     ];
   }
   return [
-    { label: "branch hotfix from main", gated: true },
-    { label: "apply approved fix", gated: true },
-    { label: "deploy prod", gated: true },
-    { label: "back-merge to rc and development", gated: true }
+    { label: "verify the fix is merged on development (the only hotfix origin)", gated: true },
+    { label: "branch hotfix from main and cherry-pick the dev commits", command: "git cherry-pick -x <dev-sha>", gated: true },
+    { label: "land on main via PR, tag, deploy prod", gated: true },
+    { label: "forward-bump development distribution manifests (Hub only; no back-merge)", gated: true }
   ];
 }
 function bootstrapPlan(repo, repoClass) {
@@ -5405,9 +5453,9 @@ function stalePosixFields(config, shell2) {
 }
 function sanitizeLocalStage(local, stale) {
   if (!stale.length) return local;
-  const clean2 = { ...local };
-  for (const field of stale) delete clean2[field];
-  return clean2;
+  const clean3 = { ...local };
+  for (const field of stale) delete clean3[field];
+  return clean3;
 }
 function staleNote(staleFields, outcome) {
   const list = staleFields.join(", ");
@@ -5679,7 +5727,7 @@ function buildGitignoreManagedBlockCheck(input) {
   return { ...base, ok: false, contentToWrite: content, added, removed, seeded };
 }
 var MMI_PLUGIN_CACHE_CLEANUP_LABEL = "stale MMI plugin cache dirs (Claude/Codex)";
-var MMI_PLUGIN_CACHE_CLEANUP_FIX = "run `mmi-cli doctor` to quarantine stale MMI-only plugin cache dirs, then reload the affected agent surface";
+var MMI_PLUGIN_CACHE_CLEANUP_FIX = "run `mmi-cli doctor` (or `mmi-cli doctor --apply --json` for machine callers) to quarantine stale MMI-only plugin cache dirs, then reload the affected agent surface";
 function normalizeVersion(v) {
   return v?.trim().replace(/^v/, "");
 }
@@ -5714,7 +5762,7 @@ function buildMmiPluginCacheCleanupCheck(input) {
     ...base,
     ok: false,
     leftovers,
-    cleanedCount: leftovers.length,
+    plannedCount: leftovers.length,
     quarantinePlan: leftovers.map((entry) => ({
       from: entry.path,
       to: cachePathJoin(entry.root, ".mmi-quarantine", stamp, entry.name)
@@ -5768,6 +5816,16 @@ var INSTALLED_PLUGIN_VERSION_LABEL = "installed MMI plugin version (vs latest re
 function isSemverVersion(v) {
   return typeof v === "string" && /^v?\d+\.\d+\.\d+/.test(v.trim());
 }
+function staleRecordCommand(surface) {
+  return surface === "codex" ? "codex plugin marketplace upgrade mmi && codex plugin add mmi@mmi" : "claude plugin marketplace update mmi && claude plugin update mmi@mmi";
+}
+function staleSurfacesFix(stale, releasedVersion) {
+  const parts = stale.map((s) => {
+    const at = s.recordPath ? ` (${s.recordPath})` : "";
+    return `${s.surface} record${at} is at ${s.installedVersion}${releasedVersion ? ` < ${releasedVersion}` : ""} \u2014 run: ${staleRecordCommand(s.surface)}`;
+  });
+  return `stale installed-plugin record on ${stale.map((s) => s.surface).join(" + ")}: ${parts.join("; ")}`;
+}
 function buildInstalledPluginVersionCheck(input) {
   const pluginId = input.pluginId ?? MMI_PLUGIN_ID;
   const base = {
@@ -5776,20 +5834,93 @@ function buildInstalledPluginVersionCheck(input) {
     fix: pluginRecoveryFix(input.surface),
     pluginId
   };
-  if (!input.isOrgRepo) return base;
-  const records = input.installed?.plugins?.[pluginId];
-  if (!Array.isArray(records) || records.length === 0) return base;
-  const installedVersion = bestRecord(records).version;
-  if (!isSemverVersion(installedVersion) || !isSemverVersion(input.releasedVersion)) return base;
-  if (compareVersions(installedVersion, input.releasedVersion) >= 0) {
-    return { ...base, installedVersion, releasedVersion: input.releasedVersion };
+  if (!input.isOrgRepo || !isSemverVersion(input.releasedVersion)) return base;
+  const stale = [];
+  let sawRecord = false;
+  let currentVersion;
+  for (const source of input.sources) {
+    const records = source.installed?.plugins?.[pluginId];
+    if (!Array.isArray(records) || records.length === 0) continue;
+    sawRecord = true;
+    const installedVersion = bestRecord(records).version;
+    if (!isSemverVersion(installedVersion)) continue;
+    if (compareVersions(installedVersion, input.releasedVersion) >= 0) {
+      currentVersion = currentVersion ?? installedVersion;
+    } else {
+      stale.push({ surface: source.surface, installedVersion, ...source.recordPath ? { recordPath: source.recordPath } : {} });
+    }
+  }
+  if (!sawRecord) return base;
+  if (stale.length === 0) {
+    return { ...base, ...currentVersion ? { installedVersion: currentVersion } : {}, releasedVersion: input.releasedVersion };
   }
   return {
     ...base,
     ok: false,
-    installedVersion,
-    releasedVersion: input.releasedVersion
+    fix: staleSurfacesFix(stale, input.releasedVersion),
+    installedVersion: stale[0].installedVersion,
+    releasedVersion: input.releasedVersion,
+    staleSurfaces: stale
+  };
+}
+var CURSOR_PLUGIN_INSTALL_LABEL = "Cursor Team Marketplace plugin install";
+var CURSOR_MARKETPLACE_INSTALL_GUIDE = "https://github.com/mutmutco/MMI-Hub/blob/development/docs/Guides/cursor-marketplace-install.md";
+var CURSOR_PLUGIN_JSON_REL = ".cursor-plugin/plugin.json";
+var CURSOR_HOOKS_JSON_REL = "hooks/hooks.json";
+function joinCachePath(root, ...parts) {
+  const sep = root.includes("\\") ? "\\" : "/";
+  return [root.replace(/[\\/]+$/, ""), ...parts].join(sep);
+}
+function cursorPluginInstallFix(input) {
+  const logHint = "check %APPDATA%\\Cursor\\logs\\<session>\\window*\\exthost\\anysphere.cursor-agent-exec\\Cursor Plugins.*.log for `unable to get password from user`";
+  const authSteps = "ensure GitHub SSH auth works for Cursor's background git (start ssh-agent, add your GitHub key, verify `ssh -T git@github.com`) \u2014 Cursor disables credential.helper during marketplace clone";
+  const marketplaceRefresh = "in Cursor Dashboard \u2192 Settings \u2192 Plugins, click Update next to the MMI Team Marketplace, enable MMI, then restart Cursor";
+  const guide = `full recovery: ${CURSOR_MARKETPLACE_INSTALL_GUIDE}`;
+  if (input.reason === "missing-cache") {
+    return `${marketplaceRefresh}; ${authSteps}; ${guide}`;
+  }
+  const pin = input.pinName ?? "<commit-pin>";
+  const cacheDir = joinCachePath(input.cacheRoot, pin);
+  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} or ${CURSOR_HOOKS_JSON_REL} \u2014 ${marketplaceRefresh}; ${authSteps}; ${localSeed}; ${logHint}; ${guide}`;
+}
+function buildCursorPluginInstallCheck(input) {
+  const base = {
+    ok: true,
+    label: CURSOR_PLUGIN_INSTALL_LABEL,
+    fix: cursorPluginInstallFix({ reason: "missing-cache", cacheRoot: input.cacheRoot })
   };
+  if (!input.isOrgRepo) return base;
+  const shouldCheck = input.surface === "cursor" || input.cacheRootExists;
+  if (!shouldCheck) return base;
+  if (input.surface === "cursor" && input.pins.length === 0) {
+    return {
+      ...base,
+      ok: false,
+      cacheRoot: input.cacheRoot,
+      pins: [],
+      reason: "missing-cache",
+      fix: cursorPluginInstallFix({ reason: "missing-cache", cacheRoot: input.cacheRoot, hubCheckout: input.hubCheckout })
+    };
+  }
+  for (const pin of input.pins) {
+    if (!pin.hasPluginJson || !pin.hasHooksJson || pin.isEmpty) {
+      return {
+        ...base,
+        ok: false,
+        cacheRoot: input.cacheRoot,
+        pins: input.pins,
+        reason: "incomplete-cache",
+        fix: cursorPluginInstallFix({
+          reason: "incomplete-cache",
+          cacheRoot: input.cacheRoot,
+          pinName: pin.name,
+          hubCheckout: input.hubCheckout
+        })
+      };
+    }
+  }
+  return { ...base, cacheRoot: input.cacheRoot, pins: input.pins };
 }
 
 // src/stage-runner.ts
@@ -6060,9 +6191,9 @@ async function predictMergeConflicts(deps, ours, theirs) {
     return files;
   }
 }
-async function mergeRcWithSpineResolution(deps) {
+async function mergeWithSpineResolution(deps, sourceRef, label, resolve) {
   try {
-    await deps.run("git", ["merge", "rc", "--no-edit"]);
+    await deps.run("git", ["merge", sourceRef, "--no-edit"]);
     return;
   } catch {
   }
@@ -6071,10 +6202,10 @@ async function mergeRcWithSpineResolution(deps) {
   if (unmerged.length === 0 || nonSpine.length > 0) {
     await deps.run("git", ["merge", "--abort"]);
     throw new Error(
-      unmerged.length === 0 ? "rc -> main merge failed without conflicted paths \u2014 merge aborted; inspect the repo state and rerun" : `rc -> main merge conflicts on non-spine path(s): ${nonSpine.join(", ")} \u2014 merge aborted (the train is misaligned; reconcile main and rc via an approved alignment PR, then rerun release)`
+      unmerged.length === 0 ? `${label} merge failed without conflicted paths \u2014 merge aborted; inspect the repo state and rerun` : `${label} merge conflicts on non-spine path(s): ${nonSpine.join(", ")} \u2014 merge aborted (the train is misaligned; reconcile the branches via an approved alignment PR, then rerun)`
     );
   }
-  await deps.run("git", ["checkout", "--theirs", "--", ...unmerged]);
+  await deps.run("git", ["checkout", `--${resolve}`, "--", ...unmerged]);
   await deps.run("git", ["add", "--", ...unmerged]);
   await deps.run("git", ["commit", "--no-edit"]);
 }
@@ -6115,6 +6246,12 @@ var HUB_REPO2 = "mutmutco/MMI-Hub";
 var CORRELATE_ATTEMPTS = 5;
 var CORRELATE_DELAY_MS = 1500;
 var CORRELATE_SKEW_SLACK_MS = 1e4;
+var TRAIN_CHECK_RUNS_JQ = "[.check_runs[]|{name:.name,status:.status,conclusion:.conclusion}]";
+var TRAIN_COMMIT_STATUS_JQ = "[.statuses[]|{context:.context,state:.state}]";
+var TRAIN_PROTECTION_CONTEXTS_JQ = "[.contexts[]]";
+var TRAIN_RULES_CONTEXTS_JQ = '[.[]|select(.type=="required_status_checks")|.parameters.required_status_checks[].context]';
+var TRAIN_CHECK_ATTEMPTS = 40;
+var TRAIN_CHECK_DELAY_MS = 15e3;
 async function correlateTenantRun(deps, since) {
   const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const threshold = since - CORRELATE_SKEW_SLACK_MS;
@@ -6152,6 +6289,112 @@ async function watchTenantRun(deps, runId) {
     return "failure";
   }
 }
+function isNotFoundError(e) {
+  const msg = `${e.message ?? e} ${String(e.stderr ?? "")}`;
+  return /HTTP 404|Not Found|\(404\)/i.test(msg);
+}
+function parseStringArray(out, label) {
+  const parsed = JSON.parse(out);
+  if (!Array.isArray(parsed)) throw new Error(`${label} response was not an array`);
+  return parsed.filter((v) => typeof v === "string");
+}
+async function discoverRequiredCheckContexts(deps, ctx, branch) {
+  const contexts = /* @__PURE__ */ new Set();
+  try {
+    const out = await deps.run("gh", ["api", `repos/${ctx.repo}/branches/${branch}/protection/required_status_checks`, "--jq", TRAIN_PROTECTION_CONTEXTS_JQ]);
+    for (const c of parseStringArray(out, "branch protection required_status_checks")) contexts.add(c);
+  } catch (e) {
+    if (!isNotFoundError(e)) throw new Error(`could not read branch protection for ${ctx.repo}@${branch}: ${e.message ?? e}`);
+  }
+  try {
+    const out = await deps.run("gh", ["api", `repos/${ctx.repo}/rules/branches/${branch}`, "--jq", TRAIN_RULES_CONTEXTS_JQ]);
+    for (const c of parseStringArray(out, "branch rules required_status_checks")) contexts.add(c);
+  } catch (e) {
+    if (!isNotFoundError(e)) throw new Error(`could not read branch rules for ${ctx.repo}@${branch}: ${e.message ?? e}`);
+  }
+  return [...contexts];
+}
+function resolveContextState(context, checkRuns, statuses) {
+  let sawFailure = false;
+  for (const r of checkRuns) {
+    if (r.name !== context) continue;
+    if (r.status === "completed") {
+      if (r.conclusion === "success") return "success";
+      sawFailure = true;
+    }
+  }
+  for (const s of statuses) {
+    if (s.context !== context) continue;
+    if (s.state === "success") return "success";
+    if (s.state === "failure" || s.state === "error") sawFailure = true;
+  }
+  return sawFailure ? "failed" : "pending";
+}
+async function waitForRequiredTrainChecks(deps, ctx, sha, required) {
+  if (required.length === 0) {
+    return "no required status checks configured on the target branch \u2014 check wait skipped (GitHub push gate is the backstop)";
+  }
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastStatus = "not checked";
+  let lastError;
+  for (let attempt = 0; attempt < TRAIN_CHECK_ATTEMPTS; attempt++) {
+    if (attempt > 0) await sleep(TRAIN_CHECK_DELAY_MS);
+    let checkRuns;
+    let statuses;
+    try {
+      const runsOut = await deps.run("gh", ["api", `repos/${ctx.repo}/commits/${sha}/check-runs`, "--jq", TRAIN_CHECK_RUNS_JQ]);
+      const parsedRuns = JSON.parse(runsOut);
+      if (!Array.isArray(parsedRuns)) throw new Error("check-runs response was not an array");
+      checkRuns = parsedRuns;
+      const statusOut = await deps.run("gh", ["api", `repos/${ctx.repo}/commits/${sha}/status`, "--jq", TRAIN_COMMIT_STATUS_JQ]);
+      const parsedStatuses = JSON.parse(statusOut);
+      if (!Array.isArray(parsedStatuses)) throw new Error("commit status response was not an array");
+      statuses = parsedStatuses;
+      lastError = void 0;
+    } catch (e) {
+      lastError = e.message || String(e);
+      continue;
+    }
+    const states = required.map((c) => [c, resolveContextState(c, checkRuns, statuses)]);
+    lastStatus = states.map(([c, s]) => `${c}=${s}`).join(", ");
+    const failed = states.filter(([, s]) => s === "failed").map(([c]) => c);
+    if (failed.length > 0) {
+      throw new Error(`required train check failed: ${failed.join(", ")} (${lastStatus})`);
+    }
+    if (states.every(([, s]) => s === "success")) {
+      return `required checks passed: ${required.join(", ")}`;
+    }
+  }
+  throw new Error(
+    `timed out waiting for required train checks on ${sha}: ${lastError ? `last error: ${lastError}` : lastStatus}`
+  );
+}
+async function ensureTagPushed(deps, tag, sha) {
+  const remoteOut = await deps.run("git", ["ls-remote", "origin", `refs/tags/${tag}`]);
+  const remoteSha = clean(remoteOut).split(/\s+/)[0] || "";
+  let localSha = "";
+  try {
+    localSha = clean(await deps.run("git", ["rev-parse", "--verify", `refs/tags/${tag}^{commit}`]));
+  } catch {
+  }
+  if (remoteSha) {
+    if (remoteSha !== sha) {
+      throw new Error(
+        `tag ${tag} already exists on origin at ${remoteSha}, but this run intends ${sha} \u2014 refusing to touch a pushed tag. Repair manually: either release the existing tagged commit (reset the local branch to ${remoteSha} and rerun), or mint the next candidate version so a fresh tag is used. Never force-move or delete a pushed tag.`
+      );
+    }
+    if (localSha && localSha !== sha) {
+      throw new Error(`local tag ${tag} points at ${localSha} but origin has it at ${sha} \u2014 delete the stale local tag (git tag -d ${tag}) and rerun`);
+    }
+    return `tag ${tag} already on origin at ${sha.slice(0, 7)} \u2014 resumed without re-pushing`;
+  }
+  if (localSha && localSha !== sha) {
+    throw new Error(`local tag ${tag} already points at ${localSha}, not the intended ${sha} \u2014 delete the stale local tag (git tag -d ${tag}) and rerun`);
+  }
+  if (!localSha) await deps.run("git", ["tag", tag, sha]);
+  await deps.run("git", ["push", "origin", tag]);
+  return `tag ${tag} pushed at ${sha.slice(0, 7)}`;
+}
 async function dispatchDeploy(deps, ctx, stage2, ref, model, watch) {
   if (model === "tenant-container") {
     const since = (deps.now ?? Date.now)();
@@ -6217,11 +6460,13 @@ async function runTrainApply(command, deps, options = {}) {
     await deps.run("git", ["checkout", "rc"]);
     await deps.run("git", ["pull", "--ff-only", "origin", "rc"]);
     await deps.run("git", ["merge", "development", "--no-edit"]);
-    await deps.run("git", ["tag", tag2]);
+    const rcSha = requireValue(clean(await deps.run("git", ["rev-parse", "rc"])), "rc sha");
+    await ensureTagPushed(deps, tag2, rcSha);
+    const requiredChecks2 = await discoverRequiredCheckContexts(deps, ctx, "rc");
+    const checks2 = await waitForRequiredTrainChecks(deps, ctx, rcSha, requiredChecks2);
     await deps.run("git", ["push", "origin", "rc"]);
-    await deps.run("git", ["push", "origin", tag2]);
     const d2 = await dispatchDeploy(deps, ctx, "rc", "rc", deployModel2, watch);
-    return { ...ctx, command, stage: "rc", ref: "rc", tag: tag2, deployModel: deployModel2, promoted: true, dispatch: d2.note, runId: d2.runId, runUrl: d2.runUrl, deployStatus: d2.deployStatus };
+    return { ...ctx, command, stage: "rc", ref: "rc", tag: tag2, deployModel: deployModel2, promoted: true, checks: checks2, dispatch: d2.note, runId: d2.runId, runUrl: d2.runUrl, deployStatus: d2.deployStatus };
   }
   await requireBranch(deps, "rc");
   ensurePositiveCount(
@@ -6242,13 +6487,15 @@ async function runTrainApply(command, deps, options = {}) {
   if (predicted.length === 0) {
     await deps.run("git", ["merge", "rc", "--no-edit"]);
   } else {
-    await mergeRcWithSpineResolution(deps);
+    await mergeWithSpineResolution(deps, "rc", "rc -> main", "theirs");
   }
   const tag = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "release"])), "release tag");
   await verifyHubDistributionVersion(deps, deployModel, tag);
-  await deps.run("git", ["tag", tag]);
+  const releaseSha = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
+  await ensureTagPushed(deps, tag, releaseSha);
+  const requiredChecks = await discoverRequiredCheckContexts(deps, ctx, "main");
+  const checks = await waitForRequiredTrainChecks(deps, ctx, releaseSha, requiredChecks);
   await deps.run("git", ["push", "origin", "main"]);
-  await deps.run("git", ["push", "origin", tag]);
   await deps.run("gh", ["release", "create", tag, "--generate-notes", "--latest", "--repo", ctx.repo]);
   const d = await dispatchDeploy(deps, ctx, "main", "main", deployModel, watch);
   const retirement = await retireRcRuntime(deps, ctx, deployModel, d.deployStatus, releasedRcSha);
@@ -6264,6 +6511,7 @@ async function runTrainApply(command, deps, options = {}) {
     tag,
     deployModel,
     promoted: true,
+    checks,
     dispatch: d.note,
     runId: d.runId,
     runUrl: d.runUrl,
@@ -6334,6 +6582,326 @@ async function runTenantRedeploy(deps, options) {
   return { ...ctx, command: "tenant-redeploy", stage: stage2, ref, deployModel, dispatch: d.note, runId: d.runId, runUrl: d.runUrl, deployStatus: d.deployStatus };
 }
 
+// src/hotfix-apply.ts
+var HOTFIX_RELEASE_WORKFLOWS = ["deploy.yml", "publish.yml"];
+var HOTFIX_RUN_FIND_ATTEMPTS = 10;
+var HOTFIX_RUN_FIND_DELAY_MS = 15e3;
+function clean2(out) {
+  return out.trim();
+}
+function sleeper(deps) {
+  return deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+}
+function normalizeHotfixVersion(input) {
+  const m = /^v?(\d+\.\d+\.\d+)$/.exec(input.trim());
+  if (!m) throw new Error(`hotfix version must be vX.Y.Z (PATCH release), got "${input}"`);
+  return { tag: `v${m[1]}`, version: m[1] };
+}
+async function deriveHotfixVersion(deps) {
+  const out = await deps.run("git", ["tag", "--list", "v[0-9]*.[0-9]*.[0-9]*", "--merged", "origin/main", "--sort=-v:refname"]);
+  const baseTag = out.split("\n").map((s) => s.trim()).find((t) => /^v\d+\.\d+\.\d+$/.test(t));
+  if (!baseTag) throw new Error("no vX.Y.Z release tag found on origin/main \u2014 cannot derive the hotfix PATCH version");
+  const [major, minor, patch] = baseTag.slice(1).split(".").map(Number);
+  const version = `${major}.${minor}.${patch + 1}`;
+  return { tag: `v${version}`, version, baseTag };
+}
+function hotfixBranch(tag) {
+  return `hotfix/${tag}`;
+}
+async function findHotfixPr(deps, ctx, tag) {
+  const out = await deps.run("gh", [
+    "pr",
+    "list",
+    "--repo",
+    ctx.repo,
+    "--head",
+    hotfixBranch(tag),
+    "--base",
+    "main",
+    "--state",
+    "all",
+    "--limit",
+    "1",
+    "--json",
+    "number,state,url,mergeCommit"
+  ]);
+  const rows = JSON.parse(out || "[]");
+  return rows[0] ?? null;
+}
+async function resolveHotfixSource(deps, ctx, from) {
+  const prMatch = /^#?(\d+)$/.exec(from.trim());
+  if (prMatch) {
+    const num = prMatch[1];
+    const out = await deps.run("gh", ["pr", "view", num, "--repo", ctx.repo, "--json", "state,baseRefName,mergeCommit"]);
+    const pr2 = JSON.parse(out);
+    if (pr2.state !== "MERGED") throw new Error(`PR #${num} is ${pr2.state ?? "unknown"}, not MERGED \u2014 hotfix start cherry-picks an already-merged development fix`);
+    if (pr2.baseRefName !== "development") throw new Error(`PR #${num} merged into ${pr2.baseRefName ?? "unknown"}, not development \u2014 name the commit SHA explicitly if this is intentional`);
+    const sha2 = pr2.mergeCommit?.oid;
+    if (!sha2) throw new Error(`PR #${num} has no merge commit recorded \u2014 name the commit SHA explicitly`);
+    return { sha: sha2, label: `PR #${num} (${sha2.slice(0, 7)})` };
+  }
+  const sha = clean2(await deps.run("git", ["rev-parse", "--verify", `${from}^{commit}`]));
+  if (!sha) throw new Error(`could not resolve commit ${from}`);
+  return { sha, label: sha.slice(0, 7) };
+}
+async function runHotfixStart(deps, options) {
+  const ctx = await buildTrainApplyContext(deps);
+  const status = await deps.run("git", ["status", "--porcelain"]);
+  if (status.trim()) throw new Error("working tree must be clean before hotfix start");
+  await deps.run("git", ["fetch", "origin", "--tags"]);
+  const { tag, version } = await deriveHotfixVersion(deps);
+  const branch = hotfixBranch(tag);
+  const notes = [];
+  const existingPr = await findHotfixPr(deps, ctx, tag);
+  if (existingPr) {
+    return {
+      ...ctx,
+      command: "hotfix-start",
+      tag,
+      version,
+      branch,
+      source: options.from,
+      prUrl: existingPr.url,
+      reused: true,
+      notes: [`hotfix PR for ${tag} already exists (#${existingPr.number}, ${existingPr.state}) \u2014 reused; next: merge it, then mmi-cli hotfix release ${tag}`]
+    };
+  }
+  const { sha, label } = await resolveHotfixSource(deps, ctx, options.from);
+  const remoteBranch = clean2(await deps.run("git", ["ls-remote", "origin", `refs/heads/${branch}`]));
+  if (remoteBranch) {
+    await deps.run("git", ["checkout", branch]);
+    await deps.run("git", ["pull", "--ff-only", "origin", branch]);
+    notes.push(`branch ${branch} already on origin \u2014 reused (cherry-pick/bump assumed present; PR step resumes)`);
+  } else {
+    await deps.run("git", ["checkout", "-B", branch, "origin/main"]);
+    try {
+      await deps.run("git", ["cherry-pick", "-x", sha]);
+    } catch (e) {
+      await deps.run("git", ["cherry-pick", "--abort"]);
+      throw new Error(`cherry-pick of ${label} onto ${branch} conflicted \u2014 aborted; resolve by hand on a manual hotfix branch, keeping the -x trailer (${e.message ?? e})`);
+    }
+    notes.push(`cherry-picked ${label} onto ${branch} (from origin/main, -x trailer recorded)`);
+    await deps.run("node", ["scripts/release-distribution.mjs", "prepare", version]);
+    const changedFiles = (await deps.run("node", ["scripts/release-distribution.mjs", "changed-files"])).split("\n").map((s) => s.trim()).filter(Boolean);
+    await deps.run("git", ["add", "--", ...changedFiles]);
+    const staged = await deps.run("git", ["diff", "--cached", "--name-only"]);
+    if (staged.trim()) {
+      await deps.run("git", ["commit", "-m", `hotfix ${tag}: lock plugin set + @mutmutco/cli distribution to ${version}`]);
+      notes.push(`distribution prepared + committed for ${version} (${changedFiles.length} locked paths)`);
+    } else {
+      notes.push("distribution prepare produced no changes \u2014 nothing extra committed");
+    }
+    await deps.run("git", ["push", "-u", "origin", branch]);
+  }
+  const prUrl = clean2(await deps.run("gh", [
+    "pr",
+    "create",
+    "--repo",
+    ctx.repo,
+    "--base",
+    "main",
+    "--head",
+    branch,
+    "--title",
+    `[hotfix] ${tag}`,
+    "--body",
+    `Hotfix ${tag}: cherry-pick of ${label} onto origin/main with the locked distribution bump.
+
+Merge this PR (human-initiated), then run \`mmi-cli hotfix release ${tag}\`.`
+  ]));
+  notes.push(`opened hotfix PR ${prUrl} \u2014 merge it (human-initiated), then: mmi-cli hotfix release ${tag}`);
+  return { ...ctx, command: "hotfix-start", tag, version, branch, source: label, prUrl, reused: Boolean(remoteBranch), notes };
+}
+async function watchReleaseRun(deps, ctx, workflow, sha) {
+  const sleep = sleeper(deps);
+  for (let attempt = 0; attempt < HOTFIX_RUN_FIND_ATTEMPTS; attempt++) {
+    if (attempt > 0) await sleep(HOTFIX_RUN_FIND_DELAY_MS);
+    let rows;
+    try {
+      const out = await deps.run("gh", [
+        "run",
+        "list",
+        "--repo",
+        ctx.repo,
+        "--workflow",
+        workflow,
+        "--event",
+        "release",
+        "--limit",
+        "10",
+        "--json",
+        "databaseId,url,headSha,status,conclusion"
+      ]);
+      rows = JSON.parse(out);
+    } catch {
+      continue;
+    }
+    const run = rows.find((r) => r.headSha === sha && typeof r.databaseId === "number");
+    if (!run) continue;
+    if (run.status === "completed") return { workflow, url: run.url, conclusion: run.conclusion ?? "unknown" };
+    try {
+      await deps.run("gh", ["run", "watch", String(run.databaseId), "--repo", ctx.repo, "--exit-status"]);
+      return { workflow, url: run.url, conclusion: "success" };
+    } catch {
+      return { workflow, url: run.url, conclusion: "failure" };
+    }
+  }
+  return { workflow, conclusion: "not-found" };
+}
+async function runHotfixRelease(deps, versionInput) {
+  const ctx = await buildTrainApplyContext(deps);
+  const { tag, version } = normalizeHotfixVersion(versionInput);
+  const status = await deps.run("git", ["status", "--porcelain"]);
+  if (status.trim()) throw new Error("working tree must be clean before hotfix release");
+  await deps.run("git", ["fetch", "origin", "--tags"]);
+  const pr2 = await findHotfixPr(deps, ctx, tag);
+  if (!pr2) throw new Error(`no hotfix PR found for ${tag} (head ${hotfixBranch(tag)}, base main) \u2014 run mmi-cli hotfix start first`);
+  if (pr2.state !== "MERGED") throw new Error(`hotfix PR #${pr2.number} for ${tag} is ${pr2.state}, not MERGED \u2014 merge it (human-initiated), then rerun`);
+  const mergedSha = pr2.mergeCommit?.oid ?? "";
+  if (!mergedSha) throw new Error(`hotfix PR #${pr2.number} reports no merge commit \u2014 cannot pin the release SHA`);
+  await deps.run("git", ["merge-base", "--is-ancestor", mergedSha, "origin/main"]).catch(() => {
+    throw new Error(`merged hotfix SHA ${mergedSha.slice(0, 7)} is not on origin/main \u2014 refusing to tag`);
+  });
+  const required = await discoverRequiredCheckContexts(deps, ctx, "main");
+  const checks = await waitForRequiredTrainChecks(deps, ctx, mergedSha, required);
+  const tagNote = await ensureTagPushed(deps, tag, mergedSha);
+  let releaseNote;
+  let releaseExists = false;
+  try {
+    await deps.run("gh", ["release", "view", tag, "--repo", ctx.repo, "--json", "tagName"]);
+    releaseExists = true;
+  } catch {
+  }
+  if (releaseExists) {
+    releaseNote = `Release ${tag} already exists \u2014 resumed without recreating`;
+  } else {
+    const tagCommit = clean2(await deps.run("git", ["rev-parse", `${tag}^{commit}`]));
+    await deps.run("gh", ["release", "create", tag, "--repo", ctx.repo, "--target", tagCommit, "--generate-notes", "--latest"]);
+    releaseNote = `Release ${tag} created (target ${tagCommit.slice(0, 7)})`;
+  }
+  const runs = [];
+  for (const workflow of HOTFIX_RELEASE_WORKFLOWS) {
+    runs.push(await watchReleaseRun(deps, ctx, workflow, mergedSha));
+  }
+  const previousRef = clean2(await deps.run("git", ["rev-parse", "--abbrev-ref", "HEAD"]));
+  let verifyNote;
+  const publishSucceeded = runs.find((r) => r.workflow === "publish.yml")?.conclusion === "success";
+  try {
+    await deps.run("git", ["-c", "advice.detachedHead=false", "checkout", tag]);
+    const verifyArgs = ["scripts/release-distribution.mjs", "verify", version, ...publishSucceeded ? [] : ["--skip-npm-view"]];
+    await deps.run("node", verifyArgs);
+    verifyNote = `distribution verified at ${tag}${publishSucceeded ? " (npm included)" : " (npm view skipped \u2014 publish run not confirmed)"}`;
+  } finally {
+    if (previousRef && previousRef !== "HEAD") await deps.run("git", ["checkout", previousRef]);
+  }
+  return { ...ctx, command: "hotfix-release", tag, mergedSha, checks, tagNote, releaseNote, runs, verifyNote };
+}
+function versionAtLeast(actual, wanted) {
+  const pa = actual.split(".").map(Number);
+  const pw = wanted.split(".").map(Number);
+  if (pa.length < 3 || pa.some(Number.isNaN) || pw.length < 3 || pw.some(Number.isNaN)) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pw[i]) return pa[i] > pw[i];
+  }
+  return true;
+}
+function deriveHotfixState(f) {
+  if (!f.branchExists && !f.pr && !f.tagPushed && !f.releaseExists) {
+    return { state: "not-started", next: `mmi-cli hotfix start --from <pr#|sha> (would mint ${f.tag})` };
+  }
+  if (!f.pr) {
+    return { state: "branch-pushed (no PR)", next: `mmi-cli hotfix start --from <pr#|sha> (resumes at the PR step for ${f.tag})` };
+  }
+  if (f.pr.state === "OPEN") {
+    return { state: "pr-open", next: `merge hotfix PR #${f.pr.number} (human-initiated), then mmi-cli hotfix release ${f.tag}` };
+  }
+  if (f.pr.state !== "MERGED") {
+    return { state: `pr-${(f.pr.state ?? "unknown").toLowerCase()}`, next: `hotfix PR #${f.pr.number} is ${f.pr.state} \u2014 restart with mmi-cli hotfix start if the fix is still needed` };
+  }
+  if (!f.tagPushed || !f.releaseExists) {
+    return { state: "pr-merged (not released)", next: `mmi-cli hotfix release ${f.tag}` };
+  }
+  if (!f.devDistribution.aligned) {
+    return {
+      state: `UNFINISHED \u2014 released but development distribution manifests behind (dev ${f.devDistribution.version} < ${f.version})`,
+      next: `forward-bump development (never a back-merge): branch from origin/development, node scripts/release-distribution.mjs prepare ${f.version}, land by PR (/hotfix Step 5)`
+    };
+  }
+  return { state: "complete", next: "nothing \u2014 pipeline complete (rc absorbs the fix at the next /rcand; /release guards coverage)" };
+}
+async function runHotfixStatus(deps, versionInput) {
+  const ctx = await buildTrainApplyContext(deps);
+  await deps.run("git", ["fetch", "origin", "--tags"]);
+  let tag;
+  let version;
+  if (versionInput) {
+    ({ tag, version } = normalizeHotfixVersion(versionInput));
+  } else {
+    const latest = await deps.run("git", ["tag", "--list", "v[0-9]*.[0-9]*.[0-9]*", "--merged", "origin/main", "--sort=-v:refname"]).then((out) => out.split("\n").map((s) => s.trim()).find((t) => /^v\d+\.\d+\.\d+$/.test(t)));
+    if (latest) {
+      const latestFacts = await gatherHotfixFacts(deps, ctx, latest, latest.slice(1));
+      const latestDerived = deriveHotfixState(latestFacts);
+      if (latestDerived.state !== "complete") {
+        return { ...ctx, command: "hotfix-status", ...latestFacts, ...latestDerived };
+      }
+    }
+    ({ tag, version } = await deriveHotfixVersion(deps));
+  }
+  const facts = await gatherHotfixFacts(deps, ctx, tag, version);
+  return { ...ctx, command: "hotfix-status", ...facts, ...deriveHotfixState(facts) };
+}
+async function gatherHotfixFacts(deps, ctx, tag, version) {
+  const branchExists = Boolean(clean2(await deps.run("git", ["ls-remote", "origin", `refs/heads/${hotfixBranch(tag)}`])));
+  const pr2 = await findHotfixPr(deps, ctx, tag);
+  const remoteTag = clean2(await deps.run("git", ["ls-remote", "origin", `refs/tags/${tag}`]));
+  const tagPushed = Boolean(remoteTag);
+  const tagSha = remoteTag.split(/\s+/)[0] || "";
+  let releaseExists = false;
+  try {
+    await deps.run("gh", ["release", "view", tag, "--repo", ctx.repo, "--json", "tagName"]);
+    releaseExists = true;
+  } catch {
+  }
+  const runs = [];
+  if (releaseExists && tagSha) {
+    for (const workflow of HOTFIX_RELEASE_WORKFLOWS) {
+      try {
+        const out = await deps.run("gh", [
+          "run",
+          "list",
+          "--repo",
+          ctx.repo,
+          "--workflow",
+          workflow,
+          "--event",
+          "release",
+          "--limit",
+          "10",
+          "--json",
+          "databaseId,url,headSha,status,conclusion"
+        ]);
+        const run = JSON.parse(out).find((r) => r.headSha === tagSha);
+        runs.push(run ? { workflow, url: run.url, conclusion: run.status === "completed" ? run.conclusion ?? "unknown" : run.status ?? "unknown" } : { workflow, conclusion: "not-found" });
+      } catch {
+        runs.push({ workflow, conclusion: "unknown" });
+      }
+    }
+  }
+  const npmVersion = await deps.run("npm", ["view", "@mutmutco/cli", "version", "--silent"]).then(clean2, () => "unknown");
+  const devVersion = await deps.run("git", ["show", "origin/development:cli/package.json"]).then(
+    (out) => {
+      try {
+        return JSON.parse(out).version ?? "unknown";
+      } catch {
+        return "unknown";
+      }
+    },
+    () => "unknown"
+  );
+  const devDistribution = { version: devVersion, aligned: versionAtLeast(devVersion, version) };
+  return { tag, version, branchExists, pr: pr2 ? { number: pr2.number, state: pr2.state, url: pr2.url } : null, tagPushed, releaseExists, runs, npmVersion, devDistribution };
+}
+
 // src/port-registry.ts
 var import_node_fs4 = require("node:fs");
 
@@ -7684,8 +8252,8 @@ function resolveKbSource(rawBase) {
   return { owner: m[1], repo: m[2], ref: m[3] };
 }
 function buildKbGetArgs(src, path2) {
-  const clean2 = path2.replace(/^\/+/, "");
-  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean2}?ref=${src.ref}`, "-H", "Accept: application/vnd.github.raw"];
+  const clean3 = path2.replace(/^\/+/, "");
+  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean3}?ref=${src.ref}`, "-H", "Accept: application/vnd.github.raw"];
 }
 function buildKbTreeArgs(src) {
   return ["api", `repos/${src.owner}/${src.repo}/git/trees/${src.ref}?recursive=1`];
@@ -9773,17 +10341,40 @@ async function runBoardRead(o) {
 }
 var board = program2.command("board").description("read, claim, show, and move Project v2 work items for the current repo");
 board.command("read", { isDefault: true }).description("read the board and print user-owned, claimable, and taken items").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo (defaults to git origin)").option("--bundle-details", "fetch body/comments only for user-owned and claimable issues").option("--allow-partial", "return partial board results when later page/detail reads fail").action((o) => runBoardRead(o));
-board.command("claim <issue>").description("assign a Todo issue and move its Project v2 Status to In Progress").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--for <login>", "assign to this login instead of @me \u2014 agent claims on behalf of the master").option("--allow-partial", "return success JSON if assignment succeeds but the status move fails").action(async (issueRef, o) => {
+board.command("claim <issues...>").description("assign Todo issues and move their Project v2 Status to In Progress (one or more refs)").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--for <login>", "assign to this login instead of @me \u2014 agent claims on behalf of the master").option("--allow-partial", "return success JSON if assignment succeeds but the status move fails").action(async (issueRefs, o) => {
+  if (issueRefs.length === 1) {
+    const issueRef = issueRefs[0];
+    try {
+      const result = await claimBoardIssue({
+        config: await loadConfigForBoardSelector(issueRef, o.repo),
+        selector: issueRef,
+        repo: o.repo,
+        assignee: o.for,
+        allowPartial: o.allowPartial
+      });
+      if (o.json) return console.log(JSON.stringify(result));
+      console.log(result.partial ? `Partially claimed ${result.item.ref}: ${result.warning}` : `Claimed ${result.item.ref} - In Progress`);
+    } catch (e) {
+      fail(`board claim failed: ${e.message}`);
+    }
+    return;
+  }
   try {
-    const result = await claimBoardIssue({
-      config: await loadConfigForBoardSelector(issueRef, o.repo),
-      selector: issueRef,
+    const bulk = await claimBoardIssues({
+      config: await loadConfigForBoardSelector(issueRefs[0], o.repo),
+      selectors: issueRefs,
       repo: o.repo,
       assignee: o.for,
       allowPartial: o.allowPartial
     });
-    if (o.json) return console.log(JSON.stringify(result));
-    console.log(result.partial ? `Partially claimed ${result.item.ref}: ${result.warning}` : `Claimed ${result.item.ref} - In Progress`);
+    if (o.json) {
+      console.log(JSON.stringify(bulk.results));
+    } else {
+      for (const result of bulk.results) {
+        console.log(result.claimed ? result.partial ? `Partially claimed ${result.ref}: ${result.warning}` : `Claimed ${result.ref} - In Progress` : `Skipped ${result.ref}: ${result.reason}`);
+      }
+    }
+    if (bulk.failed > 0) process.exitCode = 1;
   } catch (e) {
     fail(`board claim failed: ${e.message}`);
   }
@@ -10024,10 +10615,11 @@ program2.command("stage-live").description("explain that remote rc/live environm
 });
 var GH_TRAIN_TIMEOUT_MS = 3e4;
 var GH_RUN_WATCH_TIMEOUT_MS = 20 * 6e4;
+var NODE_PREPARE_TIMEOUT_MS = 10 * 6e4;
 function trainApplyDeps() {
   return {
     run: async (file, args) => {
-      const timeout = file !== "gh" ? GIT_TIMEOUT_MS : args[0] === "run" && args[1] === "watch" ? GH_RUN_WATCH_TIMEOUT_MS : GH_TRAIN_TIMEOUT_MS;
+      const timeout = file === "node" && args[1] === "prepare" ? NODE_PREPARE_TIMEOUT_MS : file !== "gh" ? GIT_TIMEOUT_MS : args[0] === "run" && args[1] === "watch" ? GH_RUN_WATCH_TIMEOUT_MS : GH_TRAIN_TIMEOUT_MS;
       return (await execFileP4(file, args, { timeout })).stdout;
     },
     runSelf: async (args) => (await execFileP4(process.execPath, [process.argv[1], ...args], { timeout: 3e4 })).stdout,
@@ -10052,15 +10644,14 @@ function renderTrainApply(commandName, r) {
 function renderTenantRedeploy(r) {
   return `mmi-cli tenant redeploy: ${r.repo} ${r.stage} (ref=${r.ref}) [${r.deployModel}]; ${renderDeployLine(r)}`;
 }
-for (const commandName of ["rcand", "release", "hotfix"]) {
-  program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--watch", "block on the dispatched tenant-deploy.yml run and report its outcome (tenant-container)").option("--apply", commandName === "hotfix" ? "reserved; hotfix uses the /hotfix skill PR path" : "execute the guarded master-only train after explicit approval").action(async (o) => {
+for (const commandName of ["rcand", "release"]) {
+  program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--watch", "block on the dispatched tenant-deploy.yml run and report its outcome (tenant-container)").option("--apply", "execute the guarded master-only train after explicit approval").action(async (o) => {
     try {
       await requireFreshTrainCli(commandName);
     } catch (e) {
       return fail(`${commandName}: ${e.message}`);
     }
     if (o.apply) {
-      if (commandName === "hotfix") return fail("hotfix: CLI apply is reserved; use the /hotfix skill PR path after explicit master-admin approval");
       try {
         const result = await runTrainApply(commandName, trainApplyDeps(), { watch: o.watch });
         return printLine(o.json ? JSON.stringify(result, null, 2) : renderTrainApply(commandName, result));
@@ -10072,6 +10663,51 @@ for (const commandName of ["rcand", "release", "hotfix"]) {
     console.log(o.json ? JSON.stringify({ command: commandName, steps }, null, 2) : renderSteps(`mmi-cli ${commandName}: dry-run plan`, steps));
   });
 }
+function renderHotfixStart(r) {
+  return [`mmi-cli hotfix start: ${r.tag} (${r.branch}, from ${r.source})${r.reused ? " [reused]" : ""}`, ...r.notes.map((n) => `  - ${n}`)].join("\n");
+}
+function renderHotfixRelease(r) {
+  return [
+    `mmi-cli hotfix release: ${r.tag} at ${r.mergedSha.slice(0, 7)} on ${r.repo}`,
+    `  - checks: ${r.checks}`,
+    `  - ${r.tagNote}`,
+    `  - ${r.releaseNote}`,
+    ...r.runs.map((run) => `  - ${run.workflow}: ${run.conclusion}${run.url ? ` (${run.url})` : ""}`),
+    `  - ${r.verifyNote}`,
+    `  - next: mmi-cli hotfix status ${r.tag} (no back-merge \u2014 development already has the fix; align its distribution manifests by PR if status says behind)`
+  ].join("\n");
+}
+function renderHotfixStatus(r) {
+  return [
+    `mmi-cli hotfix status: ${r.tag} on ${r.repo} \u2014 ${r.state}`,
+    `  - branch: ${r.branchExists ? "pushed" : "absent"} \xB7 PR: ${r.pr ? `#${r.pr.number} ${r.pr.state}` : "none"} \xB7 tag: ${r.tagPushed ? "pushed" : "absent"} \xB7 Release: ${r.releaseExists ? "exists" : "absent"}`,
+    ...r.runs.map((run) => `  - ${run.workflow}: ${run.conclusion}${run.url ? ` (${run.url})` : ""}`),
+    `  - npm @mutmutco/cli: ${r.npmVersion} \xB7 development manifests: ${r.devDistribution.version}${r.devDistribution.aligned ? " (aligned)" : " (behind)"}`,
+    `  - next: ${r.next}`
+  ].join("\n");
+}
+async function runHotfixSub(sub, body, json, render) {
+  try {
+    await requireFreshTrainCli("hotfix");
+    const result = await body();
+    printLine(json ? JSON.stringify(result, null, 2) : render(result));
+  } catch (e) {
+    fail(`hotfix ${sub}: ${e.message}`);
+  }
+}
+var hotfixCmd = program2.command("hotfix").description("stepwise hotfix orchestrator: start \u2192 release, with status (bare command prints the dry-run plan; no back-merge \u2014 #839)").option("--json", "machine-readable output").option("--apply", "not a verb; use the hotfix subcommands (start/release/status)").action(async (o) => {
+  try {
+    await requireFreshTrainCli("hotfix");
+  } catch (e) {
+    return fail(`hotfix: ${e.message}`);
+  }
+  if (o.apply) return fail("hotfix: use the stepwise subcommands \u2014 mmi-cli hotfix start --from <pr#|sha> \xB7 release <vX.Y.Z> \xB7 status [vX.Y.Z]");
+  const steps = trainPlan("hotfix");
+  console.log(o.json ? JSON.stringify({ command: "hotfix", steps }, null, 2) : renderSteps("mmi-cli hotfix: dry-run plan", steps));
+});
+hotfixCmd.command("start").description("cherry-pick a merged development PR (or SHA) onto hotfix/vX.Y.Z from origin/main, bump the distribution, open the main-base PR").requiredOption("--from <pr#|sha>", "merged development PR number or commit SHA to cherry-pick").option("--json", "machine-readable output").action(async (o) => runHotfixSub("start", () => runHotfixStart(trainApplyDeps(), { from: o.from }), o.json, renderHotfixStart));
+hotfixCmd.command("release <version>").description("after the hotfix PR is merged + checks green: tag, GitHub Release, watch deploy/publish, verify distribution (idempotent)").option("--json", "machine-readable output").action(async (version, o) => runHotfixSub("release", () => runHotfixRelease(trainApplyDeps(), version), o.json, renderHotfixRelease));
+hotfixCmd.command("status [version]").description("derive the full hotfix pipeline state from live git/gh reads and name the exact next subcommand").option("--json", "machine-readable output").action(async (version, o) => runHotfixSub("status", () => runHotfixStatus(trainApplyDeps(), version), o.json, renderHotfixStatus));
 var bootstrap = program2.command("bootstrap").description("plan repo bootstrap operations; mutations require master-admin approval").option("--repo <owner/repo>", "target repo").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").option("--apply", "reserved for future bootstrap execution after explicit master-admin approval").action((o) => {
   if (!o.repo) return fail("bootstrap: required option --repo <owner/repo> not specified");
   if (o.apply) return fail("bootstrap: execution is not implemented yet; use the dry-run plan and the existing /bootstrap skill");
@@ -10287,6 +10923,16 @@ function readInstalledPlugins() {
     return null;
   }
 }
+function installedPluginSources() {
+  return ["claude", "codex"].map((surface) => {
+    const recordPath = (0, import_node_path7.join)((0, import_node_os3.homedir)(), `.${surface}`, "plugins", "installed_plugins.json");
+    try {
+      return { surface, installed: JSON.parse((0, import_node_fs6.readFileSync)(recordPath, "utf8")), recordPath };
+    } catch {
+      return { surface, installed: null, recordPath };
+    }
+  });
+}
 function readClaudeSettings() {
   try {
     return JSON.parse((0, import_node_fs6.readFileSync)((0, import_node_path7.join)(process.cwd(), ".claude", "settings.json"), "utf8"));
@@ -10333,6 +10979,38 @@ function backupAndWriteInstalledPlugins(records, pluginId) {
     return false;
   }
 }
+function cursorPluginCacheRoot() {
+  return (0, import_node_path7.join)((0, import_node_os3.homedir)(), ".cursor", "plugins", "cache", "mmi", "mmi");
+}
+function cursorPluginCachePinSnapshots() {
+  const root = cursorPluginCacheRoot();
+  try {
+    return (0, import_node_fs6.readdirSync)(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => {
+      const path2 = (0, import_node_path7.join)(root, entry.name);
+      const pluginJson = (0, import_node_path7.join)(path2, ".cursor-plugin", "plugin.json");
+      const hooksJson = (0, import_node_path7.join)(path2, "hooks", "hooks.json");
+      let isEmpty = true;
+      try {
+        isEmpty = (0, import_node_fs6.readdirSync)(path2).length === 0;
+      } catch {
+        isEmpty = true;
+      }
+      return {
+        name: entry.name,
+        path: path2,
+        hasPluginJson: (0, import_node_fs6.existsSync)(pluginJson),
+        hasHooksJson: (0, import_node_fs6.existsSync)(hooksJson),
+        isEmpty
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+function hubCheckoutForCursorSeed() {
+  const manifest = (0, import_node_path7.join)(process.cwd(), "plugins", "mmi", ".cursor-plugin", "plugin.json");
+  return (0, import_node_fs6.existsSync)(manifest) ? process.cwd() : void 0;
+}
 function mmiPluginCacheRootSnapshots() {
   const roots = [
     { surface: "claude", root: (0, import_node_path7.join)((0, import_node_os3.homedir)(), ".claude", "plugins", "cache", "mmi", "mmi") },
@@ -10395,6 +11073,8 @@ async function runDoctor(opts, io = consoleIo) {
     else io.log(MMI_AGENTIC_ONBOARDING_GUIDE.url);
     return;
   }
+  const repairLocal = !opts.json || Boolean(opts.apply);
+  const repairFull = !opts.json && !opts.banner || Boolean(opts.apply);
   const checks = [];
   const REWRITE_KEY = "url.https://github.com/.insteadOf";
   const CLONE_FIX = 'run: git config --global url."https://github.com/".insteadOf "git@github.com:"';
@@ -10429,13 +11109,13 @@ async function runDoctor(opts, io = consoleIo) {
     repoVersion: readRepoVersion(),
     releasedVersion
   });
-  if (!opts.json && !opts.banner) versionReport = await applyVersionAutoUpdate(versionReport, (m) => io.err(m));
+  if (repairFull) versionReport = await applyVersionAutoUpdate(versionReport, (m) => io.err(m));
   if (!versionReport.ok) versionReport = { ...versionReport, fix: pluginRecoveryFix(surface) };
   checks.push(versionReport);
   checks.push({ ok: Boolean(cfg.sagaApiUrl), label: "Hub API URL configured", fix: "set MMI_HUB_URL or use a current MMI CLI/plugin build" });
   checks.push(buildAwsCrossAccountCheck({ callerArn }));
   let cloneOk = cloneProbe;
-  if (!cloneOk && !opts.banner && !opts.json) {
+  if (!cloneOk && repairFull) {
     try {
       await execFileP4("git", ["config", "--global", "--add", REWRITE_KEY, "git@github.com:"]);
       cloneOk = true;
@@ -10453,7 +11133,7 @@ async function runDoctor(opts, io = consoleIo) {
     mirrorFrom: existingMirrorRecord(installed),
     surface
   });
-  if (!pluginCheck.ok && pluginCheck.recordToInsert && !opts.json) {
+  if (!pluginCheck.ok && pluginCheck.recordToInsert && repairLocal) {
     if (writeProjectInstallRecord(pluginCheck.recordToInsert)) {
       pluginCheck = { ...pluginCheck, ok: true };
       io.err(`  \u21BB repaired: registered mmi@mmi project install record \u2014 ${reloadHint} to load MMI commands`);
@@ -10461,7 +11141,7 @@ async function runDoctor(opts, io = consoleIo) {
   }
   checks.push(pluginCheck);
   let gitignoreCheck = buildGitignoreManagedBlockCheck({ isOrgRepo: Boolean(cfg.sagaApiUrl), content: readGitignore() });
-  if (!gitignoreCheck.ok && gitignoreCheck.contentToWrite && !opts.json && !opts.banner) {
+  if (!gitignoreCheck.ok && gitignoreCheck.contentToWrite && repairFull) {
     if (writeGitignore(gitignoreCheck.contentToWrite)) {
       gitignoreCheck = { ...gitignoreCheck, ok: true };
       const drift = gitignoreCheck.seeded ? "inserted the org-managed block" : [
@@ -10474,7 +11154,7 @@ async function runDoctor(opts, io = consoleIo) {
   }
   checks.push(gitignoreCheck);
   let driftCheck = buildPluginConfigDriftCheck({ isOrgRepo: Boolean(cfg.sagaApiUrl), installed, surface });
-  if (!driftCheck.ok && driftCheck.recordsToWrite && !opts.json) {
+  if (!driftCheck.ok && driftCheck.recordsToWrite && repairLocal) {
     if (backupAndWriteInstalledPlugins(driftCheck.recordsToWrite, driftCheck.pluginId)) {
       driftCheck = { ...driftCheck, ok: true };
       io.err(`  \u21BB repaired: collapsed mmi@mmi to one user-scope entry (backup at installed_plugins.json.bak) \u2014 ${reloadHint} to load MMI commands`);
@@ -10483,15 +11163,16 @@ async function runDoctor(opts, io = consoleIo) {
   checks.push(driftCheck);
   let installedVersionCheck = buildInstalledPluginVersionCheck({
     isOrgRepo: Boolean(cfg.sagaApiUrl),
-    installed,
+    sources: installedPluginSources(),
     releasedVersion,
     surface
   });
-  if (!installedVersionCheck.ok && !opts.json && !opts.banner) {
-    if (await applyClaudePluginHeal(surface, (m) => io.err(m))) {
+  if (!installedVersionCheck.ok && repairFull) {
+    const claudeStale = installedVersionCheck.staleSurfaces?.some((s) => s.surface === "claude") ?? false;
+    if (claudeStale && await applyClaudePluginHeal(surface, (m) => io.err(m))) {
       const healed = buildInstalledPluginVersionCheck({
         isOrgRepo: Boolean(cfg.sagaApiUrl),
-        installed: readInstalledPlugins(),
+        sources: installedPluginSources(),
         releasedVersion,
         surface
       });
@@ -10509,21 +11190,35 @@ async function runDoctor(opts, io = consoleIo) {
     releasedVersion,
     installedVersions: installedPluginVersions(installed)
   });
-  if (!cacheCleanupCheck.ok && cacheCleanupCheck.quarantinePlan && !opts.json) {
+  if (!cacheCleanupCheck.ok && cacheCleanupCheck.quarantinePlan && repairLocal) {
     const moved = quarantinePluginCacheDirs(cacheCleanupCheck.quarantinePlan);
     if (moved > 0) {
       const surfaces = [...new Set(cacheCleanupCheck.leftovers?.map((entry) => entry.surface) ?? [])].join("/");
       const names = cacheCleanupCheck.leftovers?.map((entry) => entry.name).join(", ");
       io.err(`  \u21BB quarantined ${moved} stale MMI plugin cache dir(s) for ${surfaces || "agent surfaces"}: ${names} \u2014 ${reloadHint} to load MMI commands`);
     }
-    cacheCleanupCheck = buildMmiPluginCacheCleanupCheck({
-      isOrgRepo: Boolean(cfg.sagaApiUrl),
-      roots: mmiPluginCacheRootSnapshots(),
-      activeVersion: resolveVersion(),
-      releasedVersion
-    });
+    cacheCleanupCheck = {
+      ...buildMmiPluginCacheCleanupCheck({
+        isOrgRepo: Boolean(cfg.sagaApiUrl),
+        roots: mmiPluginCacheRootSnapshots(),
+        activeVersion: resolveVersion(),
+        releasedVersion
+      }),
+      ...moved > 0 ? { cleanedCount: moved } : {}
+    };
   }
   checks.push(cacheCleanupCheck);
+  const cursorCacheRoot = cursorPluginCacheRoot();
+  checks.push(
+    buildCursorPluginInstallCheck({
+      isOrgRepo: Boolean(cfg.sagaApiUrl),
+      surface,
+      cacheRoot: cursorCacheRoot,
+      cacheRootExists: (0, import_node_fs6.existsSync)(cursorCacheRoot),
+      pins: cursorPluginCachePinSnapshots() ?? [],
+      hubCheckout: hubCheckoutForCursorSeed()
+    })
+  );
   const gaps = checks.filter((c) => !c.ok);
   const resources = doctorResourcesForGaps(gaps);
   if (opts.json) {
@@ -10540,7 +11235,7 @@ async function runDoctor(opts, io = consoleIo) {
   io.log(gaps.length ? `
 ${gaps.length} item(s) need attention.` : "\nAll set \u2014 you are ready.");
 }
-program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, Hub API default, plugin git clone, plugin install record, .gitignore managed block, plugin config drift, installed plugin version) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--guide", "print the MMI Agentic Onboarding guide URL").option("--json", "machine-readable output").action((opts) => runDoctor(opts));
+program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, Hub API default, plugin git clone, plugin install record, .gitignore managed block, plugin config drift, installed plugin version, Cursor Team Marketplace plugin install) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--guide", "print the MMI Agentic Onboarding guide URL").option("--json", "machine-readable output (read-only inspection \u2014 performs no repairs)").option("--apply", "perform the same auto-repairs as the interactive run (combine with --json for a machine-readable repair run)").action((opts) => runDoctor(opts));
 program2.command("session-start").description("run the SessionStart verbs (rules sync, saga session+show, saga health, doctor) in one process; docs sync runs detached").action(async () => {
   try {
     const hook = parseHookInput(await readStdin());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "MMI Future CLI — delivers the org rules (whole-file), plus saga and KB access. The cross-IDE engine the plugin's SessionStart hook drives.",
   "type": "module",
   "license": "UNLICENSED",