@mutmutco/cli 2.14.1 → 2.16.0

package/dist/index.cjs

@@ -3393,7 +3393,7 @@ var program = new Command();
 
 // src/index.ts
 var import_promises2 = require("node:fs/promises");
-var import_node_fs6 = require("node:fs");
+var import_node_fs7 = require("node:fs");
 var import_node_crypto3 = require("node:crypto");
 
 // src/rules-sync.ts
@@ -3473,7 +3473,10 @@ function buildSessionStartPlan(verbs) {
     parallel: [
       { name: "rules sync", run: verbs.rulesSync },
       { name: "saga show", run: verbs.sagaShow },
-      { name: "saga health", run: verbs.sagaHealth }
+      { name: "saga health", run: verbs.sagaHealth },
+      // whoami (#879): the resolved human lands in the banner so agents act --for them without asking.
+      // Identity reads are memoized process-wide, so this adds no extra gh/Hub round-trip.
+      { name: "whoami", run: verbs.whoami }
     ],
     sequential: [{ name: "doctor", run: verbs.doctor }]
   };
@@ -3488,6 +3491,29 @@ function northstarPointer() {
   return "North Stars: run `mmi-cli northstar relevant` to load plans relevant to your task (`northstar list` for all).";
 }
 
+// src/whoami.ts
+async function resolveWhoami(deps) {
+  let session;
+  try {
+    session = await deps.hubSession();
+  } catch {
+    session = void 0;
+  }
+  if (session?.login) return { login: session.login, source: "hub-session", sessionExpiresAt: session.expiresAt };
+  let ghLogin;
+  try {
+    ghLogin = await deps.ghLogin();
+  } catch {
+    ghLogin = void 0;
+  }
+  if (ghLogin) return { login: ghLogin, source: "github", sessionExpiresAt: session?.expiresAt };
+  return { source: "unknown" };
+}
+function whoamiLine(report) {
+  if (!report.login) return null;
+  return `current human: ${report.login} (source: ${report.source}) \u2014 act for this login (e.g. claim --for ${report.login}); do not ask who the user is.`;
+}
+
 // src/saga-capture.ts
 function parseHookInput(stdin) {
   try {
@@ -3501,7 +3527,7 @@ function parseHookInput(stdin) {
 // src/index.ts
 var import_node_child_process6 = require("node:child_process");
 var import_node_util6 = require("node:util");
-var import_node_path7 = require("node:path");
+var import_node_path8 = require("node:path");
 var import_node_os3 = require("node:os");
 
 // src/saga-head-maintainer.ts
@@ -3823,6 +3849,49 @@ function defaultHubUrl() {
   return process.env.MMI_HUB_URL || DEFAULT_HUB_URL;
 }
 
+// src/client-version.ts
+var import_node_fs3 = require("node:fs");
+var import_node_path4 = require("node:path");
+
+// ../infra/compat.mjs
+var CLIENT_VERSION_HEADER = "x-client-version";
+function parseSemver(s) {
+  if (typeof s !== "string") return null;
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+]|$)/.exec(s.trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+function versionAtLeast(v, min) {
+  const a = parseSemver(v);
+  const b = parseSemver(min);
+  if (!a || !b) return false;
+  if (a.major !== b.major) return a.major > b.major;
+  if (a.minor !== b.minor) return a.minor > b.minor;
+  return a.patch >= b.patch;
+}
+
+// src/client-version.ts
+function resolveClientVersion() {
+  try {
+    const manifest = (0, import_node_path4.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
+    return JSON.parse((0, import_node_fs3.readFileSync)(manifest, "utf8")).version || "0.0.0";
+  } catch {
+    try {
+      const pkg = (0, import_node_path4.join)(__dirname, "..", "package.json");
+      return JSON.parse((0, import_node_fs3.readFileSync)(pkg, "utf8")).version || "0.0.0";
+    } catch {
+      return "0.0.0";
+    }
+  }
+}
+function clientVersionHeaders() {
+  return { [CLIENT_VERSION_HEADER]: resolveClientVersion() };
+}
+function upgradeRequiredError(res, body) {
+  const minVersion = body && typeof body === "object" && typeof body.minVersion === "string" ? body.minVersion : "a newer version";
+  return `Hub requires mmi-cli >= ${minVersion} \u2014 run mmi-cli doctor (installed ${resolveClientVersion()})`;
+}
+
 // src/saga-health.ts
 function buildHealth(i) {
   const problems = [];
@@ -3885,6 +3954,30 @@ async function fetchWithRetry(fetchImpl, url, init, opts = {}) {
   throw lastErr;
 }
 
+// src/clean-exit.ts
+function globalDispatcher() {
+  const g = globalThis;
+  const sym = Object.getOwnPropertySymbols(g).find(
+    (s) => s.description === "undici.globalDispatcher.1" || s.description?.startsWith("undici.globalDispatcher.")
+  );
+  return sym ? g[sym] : void 0;
+}
+function destroyHttpPool() {
+  try {
+    const dispatcher = globalDispatcher();
+    if (dispatcher?.destroy) {
+      void dispatcher.destroy();
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function hardExit(code) {
+  destroyHttpPool();
+  process.exit(code);
+}
+
 // src/saga-note.ts
 var AGENT_SURFACE_TOKENS = ["claude", "codex", "cursor", "gemini"];
 var ROUTE_LEVEL_403 = "saga API route-level 403 from HubSessionAuthorizer/session policy";
@@ -4301,6 +4394,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 +4769,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 +4791,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 +4833,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 +5455,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 +5464,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 +5546,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(", ");
@@ -5670,6 +5811,20 @@ function buildPluginConfigDriftCheck(input) {
 }
 var GITIGNORE_BLOCK_LABEL = "org .gitignore managed block (.playwright-mcp/, .claude/worktrees/, scratch *.png)";
 var GITIGNORE_BLOCK_FIX = "run `mmi-cli doctor` to auto-insert the `# >>> mmi-managed >>>` block (or copy it from MMI-Hub's .gitignore)";
+var GITIGNORE_BLOCK_DEFERRED_FIX = "run `mmi-cli doctor --apply` (without --no-repo-writes) after the release train to write the org-managed .gitignore block, then stage & commit .gitignore";
+function applyGitignoreRepoWritePolicy(check, repoWritesAllowed) {
+  if (repoWritesAllowed || check.ok || !check.contentToWrite) return check;
+  return { ...check, fix: GITIGNORE_BLOCK_DEFERRED_FIX };
+}
+function decideGitignoreRepair(check, flags) {
+  if (check.ok || !check.contentToWrite) return { action: "none", check };
+  if (!flags.repoWritesAllowed) {
+    if (!flags.repairFull) return { action: "none", check };
+    return { action: "suppress", check: applyGitignoreRepoWritePolicy(check, false) };
+  }
+  if (flags.repairFull) return { action: "write", check };
+  return { action: "none", check };
+}
 function buildGitignoreManagedBlockCheck(input) {
   const base = { ok: true, label: GITIGNORE_BLOCK_LABEL, fix: GITIGNORE_BLOCK_FIX };
   if (!input.isOrgRepo) return base;
@@ -5679,7 +5834,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 +5869,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)
@@ -5764,10 +5919,71 @@ function pluginRecoveryFix(surface) {
       return "npm install -g @mutmutco/cli@latest";
   }
 }
+var PLUGIN_UPDATE_RECIPES = {
+  claude: ["claude plugin update mmi@mmi"],
+  codex: ["codex plugin marketplace upgrade mmi", "codex plugin list   # verify mmi@mmi shows the new version"],
+  cli: ["npm install -g @mutmutco/cli@latest"]
+};
+function highestSemver(versions) {
+  return versions.reduce((best, v) => {
+    if (!isSemverVersion(v)) return best;
+    if (best === void 0) return v;
+    return compareVersions(v, best) > 0 ? v : best;
+  }, void 0);
+}
+function buildPluginUpdateReport(input) {
+  const claudePlugin = highestSemver(input.claudePluginVersions ?? []);
+  const codexMarketplace = highestSemver(input.codexPluginVersions ?? []);
+  const codexActiveCache = highestSemver(input.codexCacheVersions ?? []);
+  return {
+    versions: {
+      ...isSemverVersion(input.cliVersion) ? { cli: input.cliVersion } : {},
+      ...claudePlugin ? { claudePlugin } : {},
+      ...codexMarketplace ? { codexMarketplace } : {},
+      ...codexActiveCache ? { codexActiveCache } : {},
+      ...isSemverVersion(input.releasedVersion) ? { released: input.releasedVersion } : {}
+    },
+    recipes: PLUGIN_UPDATE_RECIPES
+  };
+}
+function renderPluginUpdateReport(report) {
+  const v = report.versions;
+  const show = (x) => x ?? "unknown";
+  return [
+    "MMI versions:",
+    `  CLI:                  ${show(v.cli)}`,
+    `  Claude plugin:        ${show(v.claudePlugin)}`,
+    `  Codex marketplace:    ${show(v.codexMarketplace)}`,
+    `  Codex active cache:   ${show(v.codexActiveCache)}`,
+    `  latest release:       ${show(v.released)}`,
+    "Update recipes (per surface):",
+    `  Claude:  ${report.recipes.claude.join(" ; ")}`,
+    `  Codex:   ${report.recipes.codex.join(" ; ")}`,
+    `  npm CLI: ${report.recipes.cli.join(" ; ")}`
+  ];
+}
+function buildDoctorJsonPayload(input) {
+  return {
+    ok: input.checks.every((c) => c.ok),
+    checks: input.checks,
+    updateReport: input.updateReport,
+    ...input.resources.length ? { resources: input.resources } : {}
+  };
+}
 var INSTALLED_PLUGIN_VERSION_LABEL = "installed MMI plugin version (vs latest release)";
 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,31 +5992,113 @@ 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 };
+}
+var HUB_COMPAT_FIX = "update mmi-cli (npm i -g @mutmutco/cli) / refresh the MMI plugin, then rerun doctor";
+function buildHubCompatCheck(input) {
+  const label = "Hub compatibility (client version vs Hub minimum)";
+  const min = input.versionInfo?.minClientVersion;
+  if (!input.isOrgRepo || !min || !parseSemver(min) || !parseSemver(input.installedVersion)) {
+    return { ok: true, label, fix: HUB_COMPAT_FIX };
+  }
+  return { ok: versionAtLeast(input.installedVersion, min), label: `${label}: requires >= ${min}`, fix: HUB_COMPAT_FIX };
+}
 
 // src/stage-runner.ts
 var import_node_child_process5 = require("node:child_process");
-var import_node_fs3 = require("node:fs");
-var import_node_path4 = require("node:path");
+var import_node_fs4 = require("node:fs");
+var import_node_path5 = require("node:path");
 var import_node_net = require("node:net");
 var import_node_util5 = require("node:util");
 var execFileP3 = (0, import_node_util5.promisify)(import_node_child_process5.execFile);
 function stageStatePath(cwd = process.cwd()) {
-  return (0, import_node_path4.join)(cwd, "tmp", "stage", "state.json");
+  return (0, import_node_path5.join)(cwd, "tmp", "stage", "state.json");
 }
 var POSIX_ONLY_VERBS = ["cp", "mv", "rm", "ln", "cat", "touch", "chmod", "export"];
 function posixOnlyShellProblems(command, field, platform = process.platform) {
@@ -5862,9 +6160,9 @@ async function shell(command, cwd, timeoutMs) {
   });
 }
 function readState(path2) {
-  if (!(0, import_node_fs3.existsSync)(path2)) return null;
+  if (!(0, import_node_fs4.existsSync)(path2)) return null;
   try {
-    return JSON.parse((0, import_node_fs3.readFileSync)(path2, "utf8"));
+    return JSON.parse((0, import_node_fs4.readFileSync)(path2, "utf8"));
   } catch {
     return null;
   }
@@ -5916,7 +6214,7 @@ async function stopStage(opts = {}) {
     return { ok: true, action: "stop", statePath, message: "no previous stage state found" };
   }
   await killTree(state.pid);
-  (0, import_node_fs3.rmSync)(statePath, { force: true });
+  (0, import_node_fs4.rmSync)(statePath, { force: true });
   return { ok: true, action: "stop", statePath, pid: state.pid, message: `stopped previous stage pid ${state.pid}` };
 }
 async function startStage(config = {}, opts = {}) {
@@ -5925,7 +6223,7 @@ async function startStage(config = {}, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const statePath = opts.statePath ?? stageStatePath(cwd);
   const dir = statePath.slice(0, Math.max(statePath.lastIndexOf("/"), statePath.lastIndexOf("\\")));
-  (0, import_node_fs3.mkdirSync)(dir, { recursive: true });
+  (0, import_node_fs4.mkdirSync)(dir, { recursive: true });
   let stagePort;
   if (config.portRange) {
     const [s, e] = config.portRange;
@@ -5935,9 +6233,9 @@ async function startStage(config = {}, opts = {}) {
   }
   const sub = (s) => s != null && stagePort != null ? s.replace(/\$\{?STAGE_PORT\}?/g, String(stagePort)) : s;
   if (config.ensureEnv) {
-    const target = (0, import_node_path4.join)(cwd, config.ensureEnv.target);
-    const example = (0, import_node_path4.join)(cwd, config.ensureEnv.example);
-    if (!(0, import_node_fs3.existsSync)(target) && (0, import_node_fs3.existsSync)(example)) (0, import_node_fs3.copyFileSync)(example, target);
+    const target = (0, import_node_path5.join)(cwd, config.ensureEnv.target);
+    const example = (0, import_node_path5.join)(cwd, config.ensureEnv.example);
+    if (!(0, import_node_fs4.existsSync)(target) && (0, import_node_fs4.existsSync)(example)) (0, import_node_fs4.copyFileSync)(example, target);
   }
   const extraEnv = {};
   for (const [k, v] of Object.entries(config.env ?? {})) extraEnv[k] = sub(v) ?? v;
@@ -5961,12 +6259,12 @@ async function startStage(config = {}, opts = {}) {
     healthUrl: sub(config.healthUrl?.trim()) || void 0,
     port: stagePort
   };
-  (0, import_node_fs3.writeFileSync)(statePath, JSON.stringify(state, null, 2), "utf8");
+  (0, import_node_fs4.writeFileSync)(statePath, JSON.stringify(state, null, 2), "utf8");
   try {
     if (state.healthUrl) await waitForHealth(state.healthUrl, opts.timeoutMs ?? 6e4, config.healthAnyStatus);
   } catch (e) {
     await killTree(state.pid);
-    (0, import_node_fs3.rmSync)(statePath, { force: true });
+    (0, import_node_fs4.rmSync)(statePath, { force: true });
     throw e;
   }
   const result = { ok: true, action: "start", statePath, pid: state.pid, port: stagePort, message: `started stage pid ${state.pid}${stagePort != null ? ` on port ${stagePort}` : ""}` };
@@ -6036,14 +6334,18 @@ function requireValue(value, label) {
   if (!value) throw new Error(`${label} could not be resolved`);
   return value;
 }
-function releaseTagFromRcTag(tag) {
-  return tag.replace(/-rc\.\d+$/, "");
-}
 async function verifyHubDistributionVersion(deps, model, releaseTag) {
   if (model !== "hub-serverless") return;
   await deps.run("node", ["scripts/release-distribution.mjs", "verify", releaseTag, "--skip-npm-view"]);
 }
-var ORG_SPINE_FILES = ["AGENTS.md", "CLAUDE.md", "GEMINI.md", ".claude/settings.json"];
+var ORG_SPINE_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".claude/settings.json",
+  ".claude/output-styles/mmi-plain.md",
+  ".cursor/rules/mmi-plain-language.mdc"
+];
 function isSpinePath(path2) {
   return ORG_SPINE_FILES.includes(path2);
 }
@@ -6060,9 +6362,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 +6373,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,9 +6417,10 @@ var HUB_REPO2 = "mutmutco/MMI-Hub";
 var CORRELATE_ATTEMPTS = 5;
 var CORRELATE_DELAY_MS = 1500;
 var CORRELATE_SKEW_SLACK_MS = 1e4;
-var TRAIN_REQUIRED_CHECKS = ["cli", "infra", "docs"];
-var TRAIN_REQUIRED_CHECK_SET = new Set(TRAIN_REQUIRED_CHECKS);
-var TRAIN_CHECKS_JQ = '[.check_runs[]|select(.name|test("^(cli|infra|docs)$"))|{(.name):.conclusion}]';
+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) {
@@ -6157,51 +6460,124 @@ async function watchTenantRun(deps, runId) {
     return "failure";
   }
 }
-function parseTrainCheckConclusions(out) {
+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("check-runs response was not an array");
-  const conclusions = /* @__PURE__ */ new Map();
-  for (const row of parsed) {
-    if (row == null || typeof row !== "object") continue;
-    for (const [name, raw] of Object.entries(row)) {
-      if (!TRAIN_REQUIRED_CHECK_SET.has(name)) continue;
-      conclusions.set(name, raw == null ? null : String(raw));
-    }
+  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 conclusions;
+  return [...contexts];
 }
-function describeTrainChecks(conclusions) {
-  return TRAIN_REQUIRED_CHECKS.map((name) => `${name}=${conclusions.get(name) ?? "missing"}`).join(", ");
+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) {
+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 conclusions;
+    let checkRuns;
+    let statuses;
     try {
-      const out = await deps.run("gh", ["api", `repos/${ctx.repo}/commits/${sha}/check-runs`, "--jq", TRAIN_CHECKS_JQ]);
-      conclusions = parseTrainCheckConclusions(out);
+      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;
     }
-    lastStatus = describeTrainChecks(conclusions);
-    const failed = TRAIN_REQUIRED_CHECKS.filter((name) => {
-      const conclusion = conclusions.get(name);
-      return conclusion != null && conclusion !== "success";
-    });
+    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 (TRAIN_REQUIRED_CHECKS.every((name) => conclusions.get(name) === "success")) return;
+    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 resolveRcResumeTag(deps, base, sha) {
+  const out = await deps.run("git", ["ls-remote", "--tags", "origin", `refs/tags/${base}-rc.*`]);
+  const onSha = clean(out).split("\n").map((line) => line.trim()).filter(Boolean).map((line) => line.split(/\s+/)).filter(([refSha]) => refSha === sha).map(([, ref]) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, "")).filter((ref) => new RegExp(`^${base.replace(/\./g, "\\.")}-rc\\.\\d+$`).test(ref));
+  const unique = [...new Set(onSha)];
+  if (unique.length === 0) return { tag: null };
+  const rcNum = (t) => Number.parseInt(t.replace(/^.*-rc\./, ""), 10);
+  const sorted = unique.sort((a, b) => rcNum(b) - rcNum(a));
+  const newest = sorted[0];
+  const leftovers = sorted.slice(1);
+  const note = leftovers.length > 0 ? `resuming existing RC tag ${newest} already on ${sha.slice(0, 7)} (newest of ${sorted.length}); harmless leftover tag(s) on the same SHA: ${leftovers.join(", ")}` : `resuming existing RC tag ${newest} already on ${sha.slice(0, 7)} instead of minting a fresh rc`;
+  return { tag: newest, note };
+}
 async function dispatchDeploy(deps, ctx, stage2, ref, model, watch) {
   if (model === "tenant-container") {
     const since = (deps.now ?? Date.now)();
@@ -6262,18 +6638,21 @@ async function runTrainApply(command, deps, options = {}) {
       "nothing to promote: origin/development is not ahead of origin/rc"
     );
     const deployModel2 = await preflight(deps, ctx, "rc");
-    const tag2 = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "rc"])), "rc tag");
-    await verifyHubDistributionVersion(deps, deployModel2, releaseTagFromRcTag(tag2));
+    const releaseBase = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "cycle"])), "release base");
+    await verifyHubDistributionVersion(deps, deployModel2, releaseBase);
     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]);
-    await deps.run("git", ["push", "origin", tag2]);
     const rcSha = requireValue(clean(await deps.run("git", ["rev-parse", "rc"])), "rc sha");
-    await waitForRequiredTrainChecks(deps, ctx, rcSha);
+    const resume = await resolveRcResumeTag(deps, releaseBase, rcSha);
+    const tag2 = resume.tag ?? requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "rc"])), "rc tag");
+    const resumeNote = resume.tag ? resume.note : void 0;
+    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"]);
     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, resumeNote, dispatch: d2.note, runId: d2.runId, runUrl: d2.runUrl, deployStatus: d2.deployStatus };
   }
   await requireBranch(deps, "rc");
   ensurePositiveCount(
@@ -6294,22 +6673,24 @@ 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]);
-  await deps.run("git", ["push", "origin", tag]);
   const releaseSha = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
-  await waitForRequiredTrainChecks(deps, ctx, releaseSha);
+  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("gh", ["release", "create", tag, "--generate-notes", "--latest", "--repo", ctx.repo]);
+  const releaseUrl = clean(await deps.run("gh", ["release", "create", tag, "--generate-notes", "--latest", "--repo", ctx.repo])) || void 0;
+  const announceNote = deps.announce ? (await deps.announce({ repo: ctx.repo, tag, summaryFile: options.announceSummaryFile })).note : void 0;
   const d = await dispatchDeploy(deps, ctx, "main", "main", deployModel, watch);
   const retirement = await retireRcRuntime(deps, ctx, deployModel, d.deployStatus, releasedRcSha);
   await deps.run("git", ["checkout", "development"]);
   await deps.run("git", ["pull", "--ff-only", "origin", "development"]);
   await deps.run("git", ["merge", "main", "--no-edit"]);
   await deps.run("git", ["push", "origin", "development"]);
+  const environments = await buildEnvironments(deps, ctx, deployModel, d.deployStatus, retirement);
   return {
     ...ctx,
     command,
@@ -6318,14 +6699,50 @@ async function runTrainApply(command, deps, options = {}) {
     tag,
     deployModel,
     promoted: true,
+    checks,
     dispatch: d.note,
     runId: d.runId,
     runUrl: d.runUrl,
     deployStatus: d.deployStatus,
     rcRetirement: retirement.status,
-    rcRetirementNote: retirement.note
+    rcRetirementNote: retirement.note,
+    rcRetirementCategory: retirement.category,
+    announceNote,
+    release: { tag, url: releaseUrl, targetSha: releaseSha },
+    environments
   };
 }
+async function buildEnvironments(deps, ctx, model, deployStatus, retirement) {
+  if (model !== "tenant-container") return void 0;
+  const domains = deps.fetchEdgeDomains ? await deps.fetchEdgeDomains(ctx.slug).catch(() => null) : null;
+  const mainDomains = domains?.main;
+  const rcDomains = domains?.rc;
+  const healthStatus = deployStatus === "success" ? "success" : deployStatus === "failure" ? "failure" : "pending";
+  const main = { healthStatus };
+  if (mainDomains?.length) {
+    main.domains = mainDomains;
+    main.healthUrl = `https://${mainDomains[0]}/`;
+  }
+  const rc = { retirement: retirement.status };
+  if (retirement.category) rc.retirementCategory = retirement.category;
+  if (rcDomains?.length) rc.domains = rcDomains;
+  return { main, rc };
+}
+var RETIRE_CATEGORIES = /* @__PURE__ */ new Set([
+  "retired",
+  "retired-edge-pending",
+  "ssm-command-failed",
+  "wait-timeout",
+  "transport-failed"
+]);
+function retireCategoryFrom(text) {
+  try {
+    const c = JSON.parse(text).category;
+    return typeof c === "string" && RETIRE_CATEGORIES.has(c) ? c : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function retireRcRuntime(deps, ctx, model, deployStatus, releasedRcSha) {
   if (model !== "tenant-container") {
     return { status: "not-applicable", note: `${model} has no co-resident rc runtime to retire` };
@@ -6350,16 +6767,28 @@ async function retireRcRuntime(deps, ctx, model, deployStatus, releasedRcSha) {
     }
     const out = await deps.runSelf(["tenant", "control", ctx.repo, "rc", "retire"]);
     let commandId = "";
+    let category = retireCategoryFrom(out);
     try {
       commandId = String(JSON.parse(out).commandId ?? "");
     } catch {
     }
+    if (category === "retired-edge-pending") {
+      return {
+        status: "retired",
+        category,
+        note: `rc runtime retired; edge vhost reconcile pending (tenant control retire${commandId ? `, command ${commandId}` : ""}) \u2014 registry coords kept`
+      };
+    }
+    category = category ?? "retired";
     return {
       status: "retired",
+      category,
       note: `rc runtime retired (tenant control retire${commandId ? `, command ${commandId}` : ""}) \u2014 registry coords kept; /rcand or tenant redeploy recreates rc next cycle`
     };
   } catch (e) {
-    return { status: "failed", note: `rc retirement failed (the release itself succeeded): ${e.message}` };
+    const err = e;
+    const category = retireCategoryFrom(err.stdout ?? "") ?? "transport-failed";
+    return { status: "failed", category, note: `rc retirement failed (the release itself succeeded): ${err.message}` };
   }
 }
 async function runTenantRedeploy(deps, options) {
@@ -6388,8 +6817,458 @@ 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, options = {}) {
+  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 {
+  }
+  let announceNote;
+  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)})`;
+    if (deps.announce) {
+      announceNote = (await deps.announce({ repo: ctx.repo, tag, summaryFile: options.announceSummaryFile })).note;
+    }
+  }
+  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, announceNote };
+}
+function versionAtLeast2(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: versionAtLeast2(devVersion, version) };
+  return { tag, version, branchExists, pr: pr2 ? { number: pr2.number, state: pr2.state, url: pr2.url } : null, tagPushed, releaseExists, runs, npmVersion, devDistribution };
+}
+
+// src/release-announce.ts
+var ANNOUNCE_REPO = "mutmutco/MMI-Hub";
+var SSM_REGION = "eu-central-1";
+var SSM_TOKEN_PARAM = "/mmi-future/shared/SLACK_BOT_TOKEN";
+var SSM_CHANNEL_PARAM = "/mmi-future/shared/SLACK_ALERTS_CHANNEL";
+var SLACK_TIMEOUT_MS = 1e4;
+var MAX_BULLETS = 6;
+var MAX_SUMMARY_LINES = 8;
+function escapeMrkdwn(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function bulletToLine(raw) {
+  const m = /^[*-]\s+(.*)$/.exec(raw.trim());
+  if (!m) return null;
+  let text = m[1].trim();
+  const tail = /\s+by\s+@([\w[\]-]+)\s+in\s+(\S+)\s*$/.exec(text);
+  let link = "";
+  if (tail) {
+    const author = tail[1].toLowerCase();
+    if (author.includes("dependabot") || author.includes("[bot]") || author === "github-actions") return null;
+    const url = tail[2];
+    const pr2 = /\/pull\/(\d+)$/.exec(url);
+    link = pr2 ? ` (<${url}|#${pr2[1]}>)` : "";
+    text = text.slice(0, tail.index).trim();
+  }
+  if (!text) return null;
+  return `\u2022 ${escapeMrkdwn(text)}${link}`;
+}
+function curateReleaseNotes(notesMd, maxBullets = MAX_BULLETS) {
+  const lines = [];
+  let bullets = 0;
+  let dropped = 0;
+  let section = "";
+  let pendingHeader = "";
+  for (const raw of notesMd.split("\n")) {
+    const header = /^(#{2,3})\s+(.*)$/.exec(raw.trim());
+    if (header) {
+      section = header[2].trim();
+      if (/what's changed/i.test(section) || /new contributors/i.test(section)) {
+        pendingHeader = "";
+        continue;
+      }
+      pendingHeader = `*${escapeMrkdwn(section)}*`;
+      continue;
+    }
+    if (/new contributors/i.test(section)) continue;
+    const line = bulletToLine(raw);
+    if (!line) continue;
+    if (bullets >= maxBullets) {
+      dropped += 1;
+      continue;
+    }
+    if (pendingHeader) {
+      lines.push(pendingHeader);
+      pendingHeader = "";
+    }
+    lines.push(line);
+    bullets += 1;
+  }
+  if (dropped > 0) lines.push(`\u2026and ${dropped} more`);
+  return lines;
+}
+function formatAnnouncement(args) {
+  const name = args.repo.split("/")[1] ?? args.repo;
+  return [
+    `:rocket: *${name} ${args.tag} released*`,
+    "",
+    ...args.lines,
+    "",
+    `<${args.releaseUrl}|Release notes>`
+  ].join("\n");
+}
+function summaryFileLines(content) {
+  return content.split("\n").map((l) => l.trim()).filter(Boolean).slice(0, MAX_SUMMARY_LINES).map((l) => escapeMrkdwn(l.replace(/^[•*-]\s*/, ""))).filter(Boolean).map((l) => `\u2022 ${l}`);
+}
+async function ssmParameter(deps, name, decrypt) {
+  const args = [
+    "ssm",
+    "get-parameter",
+    "--region",
+    SSM_REGION,
+    "--name",
+    name,
+    "--query",
+    "Parameter.Value",
+    "--output",
+    "text",
+    ...decrypt ? ["--with-decryption"] : []
+  ];
+  const value = (await deps.run("aws", args)).trim();
+  if (!value || value === "None") throw new Error(`SSM parameter ${name} is empty`);
+  return value;
+}
+async function announceRelease(deps, args) {
+  if (args.repo !== ANNOUNCE_REPO) {
+    return { status: "skipped", note: `announce is Hub-only \u2014 ${args.repo} skipped` };
+  }
+  try {
+    const viewRaw = await deps.run("gh", ["release", "view", args.tag, "--repo", args.repo, "--json", "body,url"]);
+    const view = JSON.parse(viewRaw);
+    const releaseUrl = view.url ?? `https://github.com/${args.repo}/releases/tag/${args.tag}`;
+    let lines = [];
+    if (args.summaryFile) {
+      if (!deps.readFile) throw new Error("summary file given but deps.readFile is missing");
+      lines = summaryFileLines(await deps.readFile(args.summaryFile));
+    }
+    if (lines.length === 0) lines = curateReleaseNotes(view.body ?? "");
+    if (lines.length === 0) lines = ["\u2022 maintenance release \u2014 see the notes for details"];
+    const token = await ssmParameter(deps, SSM_TOKEN_PARAM, true);
+    const channel = await ssmParameter(deps, SSM_CHANNEL_PARAM, false);
+    const text = formatAnnouncement({ repo: args.repo, tag: args.tag, lines, releaseUrl });
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const res = await fetchImpl("https://slack.com/api/chat.postMessage", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json; charset=utf-8" },
+      body: JSON.stringify({ channel, text, unfurl_links: false }),
+      signal: AbortSignal.timeout(SLACK_TIMEOUT_MS)
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!json.ok) throw new Error(`slack postMessage failed: ${json.error ?? `http ${res.status}`}`);
+    return { status: "announced", note: `announced ${args.tag} to the alerts channel` };
+  } catch (e) {
+    return { status: "failed", note: `announce failed (release unaffected): ${e.message}` };
+  }
+}
+
 // src/port-registry.ts
-var import_node_fs4 = require("node:fs");
+var import_node_fs5 = require("node:fs");
 
 // ../infra/port-geometry.mjs
 var PORT_BLOCK = 100;
@@ -6403,8 +7282,8 @@ function nextPortBlock(registry2) {
   return [base, base + PORT_SPAN];
 }
 function loadPortRegistry(path2) {
-  if (!(0, import_node_fs4.existsSync)(path2)) return {};
-  const raw = JSON.parse((0, import_node_fs4.readFileSync)(path2, "utf8"));
+  if (!(0, import_node_fs5.existsSync)(path2)) return {};
+  const raw = JSON.parse((0, import_node_fs5.readFileSync)(path2, "utf8"));
   const out = {};
   for (const [key, value] of Object.entries(raw)) {
     if (Array.isArray(value) && value.length === 2 && value.every((n) => typeof n === "number")) {
@@ -6418,9 +7297,9 @@ function ensurePortRange(repo, path2) {
   const existing = registry2[repo];
   if (existing) return existing;
   const range = nextPortBlock(registry2);
-  const raw = (0, import_node_fs4.existsSync)(path2) ? JSON.parse((0, import_node_fs4.readFileSync)(path2, "utf8")) : {};
+  const raw = (0, import_node_fs5.existsSync)(path2) ? JSON.parse((0, import_node_fs5.readFileSync)(path2, "utf8")) : {};
   raw[repo] = range;
-  (0, import_node_fs4.writeFileSync)(path2, JSON.stringify(raw, null, 2) + "\n", "utf8");
+  (0, import_node_fs5.writeFileSync)(path2, JSON.stringify(raw, null, 2) + "\n", "utf8");
   return range;
 }
 function portCursorSeed(registry2) {
@@ -7004,8 +7883,8 @@ function renderBootstrapVerifyReport(report) {
 
 // src/hub-auth.ts
 var import_node_crypto2 = require("node:crypto");
-var import_node_fs5 = require("node:fs");
-var import_node_path5 = require("node:path");
+var import_node_fs6 = require("node:fs");
+var import_node_path6 = require("node:path");
 var import_node_os2 = require("node:os");
 var REFRESH_WINDOW_MS = 10 * 60 * 1e3;
 var EXCHANGE_TIMEOUT_MS = 8e3;
@@ -7019,15 +7898,15 @@ function tokenFingerprint(token) {
 function defaultHubSessionCachePath(env = process.env) {
   if (env.MMI_HUB_SESSION_CACHE) return env.MMI_HUB_SESSION_CACHE;
   if (process.platform === "win32") {
-    const base2 = env.LOCALAPPDATA || (0, import_node_path5.join)((0, import_node_os2.homedir)(), "AppData", "Local");
-    return (0, import_node_path5.join)(base2, "MMI Future", "mmi-cli", "hub-session.json");
+    const base2 = env.LOCALAPPDATA || (0, import_node_path6.join)((0, import_node_os2.homedir)(), "AppData", "Local");
+    return (0, import_node_path6.join)(base2, "MMI Future", "mmi-cli", "hub-session.json");
   }
-  const base = env.XDG_STATE_HOME || (0, import_node_path5.join)((0, import_node_os2.homedir)(), ".mmi");
-  return (0, import_node_path5.join)(base, "mmi-cli", "hub-session.json");
+  const base = env.XDG_STATE_HOME || (0, import_node_path6.join)((0, import_node_os2.homedir)(), ".mmi");
+  return (0, import_node_path6.join)(base, "mmi-cli", "hub-session.json");
 }
 function readCache(path2, apiUrl, now, githubTokenFingerprint) {
   try {
-    const session = JSON.parse((0, import_node_fs5.readFileSync)(path2, "utf8"));
+    const session = JSON.parse((0, import_node_fs6.readFileSync)(path2, "utf8"));
     if (!session.token || !session.expiresAt || session.apiUrl !== apiUrl) return null;
     if (session.githubTokenFingerprint !== githubTokenFingerprint) return null;
     if (new Date(session.expiresAt).getTime() <= now.getTime() + REFRESH_WINDOW_MS) return null;
@@ -7037,16 +7916,16 @@ function readCache(path2, apiUrl, now, githubTokenFingerprint) {
   }
 }
 function writeCache(path2, session) {
-  (0, import_node_fs5.mkdirSync)((0, import_node_path5.dirname)(path2), { recursive: true });
+  (0, import_node_fs6.mkdirSync)((0, import_node_path6.dirname)(path2), { recursive: true });
   const tmp = `${path2}.${process.pid}.${Date.now()}.tmp`;
-  (0, import_node_fs5.writeFileSync)(tmp, JSON.stringify(session, null, 2) + "\n", { encoding: "utf8", mode: 384 });
+  (0, import_node_fs6.writeFileSync)(tmp, JSON.stringify(session, null, 2) + "\n", { encoding: "utf8", mode: 384 });
   try {
-    (0, import_node_fs5.chmodSync)(tmp, 384);
+    (0, import_node_fs6.chmodSync)(tmp, 384);
   } catch {
   }
-  (0, import_node_fs5.renameSync)(tmp, path2);
+  (0, import_node_fs6.renameSync)(tmp, path2);
   try {
-    (0, import_node_fs5.chmodSync)(path2, 384);
+    (0, import_node_fs6.chmodSync)(path2, 384);
   } catch {
   }
 }
@@ -7064,7 +7943,7 @@ async function hubAuthSession(deps) {
     const res = await fetchWithRetry(
       deps.fetch ?? fetch,
       `${apiUrl}/auth/session`,
-      { method: "POST", headers: { Authorization: `Bearer ${ghToken}` } },
+      { method: "POST", headers: { ...clientVersionHeaders(), Authorization: `Bearer ${ghToken}` } },
       { attempts: EXCHANGE_ATTEMPTS, timeoutMs: EXCHANGE_TIMEOUT_MS }
     );
     if (!res.ok) return void 0;
@@ -7219,9 +8098,11 @@ var PROJECTS_ENVELOPE_KEY = "projects";
 
 // src/registry-client.ts
 var DEFAULT_TIMEOUT_MS2 = 8e3;
+var WAITED_TENANT_CONTROL_TIMEOUT_MS = 13e3;
 var RETRY_ATTEMPTS = 3;
 function retriedFetch(deps, url, init) {
-  return fetchWithRetry(deps.fetch ?? fetch, url, init, {
+  const headers = { ...clientVersionHeaders(), ...init.headers };
+  return fetchWithRetry(deps.fetch ?? fetch, url, { ...init, headers }, {
     attempts: RETRY_ATTEMPTS,
     timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2
   });
@@ -7235,6 +8116,7 @@ async function fetchTrainAuthority(repo, deps) {
       method: "GET",
       headers: { Authorization: `Bearer ${token}` }
     });
+    if (res.status === 426) return { ok: false, error: upgradeRequiredError(res, await res.json().catch(() => null)) };
     if (!res.ok) return { ok: false, error: `train-authority HTTP ${res.status}` };
     const body = await res.json();
     if (typeof body?.train !== "boolean" || !body.role) return { ok: false, error: "malformed train-authority response" };
@@ -7275,6 +8157,7 @@ async function fetchProjectBySlugChecked(slug, deps) {
       headers: { Authorization: `Bearer ${token}` }
     });
     if (res.status === 404) return { ok: true, project: null };
+    if (res.status === 426) return { ok: false, error: upgradeRequiredError(res, await res.json().catch(() => null)) };
     if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
     return { ok: true, project: await res.json() };
   } catch (e) {
@@ -7317,14 +8200,17 @@ async function fetchOrgConfig(deps) {
     return null;
   }
 }
-async function postJson(pathSuffix, payload, deps, method = "POST") {
+async function postJson(pathSuffix, payload, deps, method = "POST", opts = {}) {
   if (!deps.baseUrl) return { ok: false, status: 0, body: null, error: "no Hub API URL (set MMI_HUB_URL or use a current MMI CLI/plugin build)" };
   const token = await deps.token();
   if (!token) return { ok: false, status: 0, body: null, error: "no Hub session token (run `gh auth login`)" };
+  const timeoutMs = opts.timeoutMs ?? deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const sendOnce = (url, init) => fetchWithRetry(deps.fetch ?? fetch, url, init, { attempts: 1, timeoutMs });
+  const send = opts.noRetry ? sendOnce : (url, init) => fetchWithRetry(deps.fetch ?? fetch, url, init, { attempts: RETRY_ATTEMPTS, timeoutMs });
   try {
-    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}${pathSuffix}`, {
+    const res = await send(`${deps.baseUrl.replace(/\/$/, "")}${pathSuffix}`, {
       method,
-      headers: { Authorization: `Bearer ${token}`, "content-type": "application/json" },
+      headers: { ...clientVersionHeaders(), Authorization: `Bearer ${token}`, "content-type": "application/json" },
       body: JSON.stringify(payload)
     });
     let body = null;
@@ -7347,10 +8233,15 @@ async function attestAppGaps(slug, repo, deps) {
   return postJson(`/projects/${encodeURIComponent(slug)}/attest-app`, { repo }, deps);
 }
 async function tenantControl(payload, deps) {
-  return postJson("/tenant-control", payload, deps);
+  const noRetry = payload.action === "retire";
+  const timeoutMs = payload.wait ? WAITED_TENANT_CONTROL_TIMEOUT_MS : void 0;
+  return postJson("/tenant-control", payload, deps, "POST", { noRetry, timeoutMs });
 }
 
 // src/project-readiness.ts
+function dnsErrorToResolution(code) {
+  return code === "ENOTFOUND" || code === "EAI_NONAME" ? false : void 0;
+}
 var STAGES = ["dev", "rc", "main"];
 var DEFAULT_RUNTIME_SECRET_NAMES = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
 function slugOfRepo(repoOrSlug) {
@@ -7368,8 +8259,17 @@ function projectRequiresGoogleOAuth(meta, model) {
   if (projectType !== "web-app") return false;
   return Boolean(meta.oauth && typeof meta.oauth === "object");
 }
-function projectRequiresDeployCoords(model) {
-  return model === "tenant-container";
+function declaresNoPublicEdge(meta) {
+  const ed = meta?.edgeDomains;
+  return Boolean(ed && typeof ed === "object" && !Array.isArray(ed) && Object.keys(ed).length === 0);
+}
+function isNoEdgeTenantWorker(meta, model) {
+  return model === "tenant-container" && declaresNoPublicEdge(meta);
+}
+function projectRequiresDeployCoords(model, stage2, meta) {
+  if (model !== "tenant-container") return false;
+  if (stage2 && isNoEdgeTenantWorker(meta, model)) return stage2 === "main";
+  return true;
 }
 function projectRequiresDeployState(model, stage2) {
   return model === "hub-serverless" && stage2 !== "dev";
@@ -7378,6 +8278,7 @@ function stageRequiredSecrets(stage2, meta) {
   const contract = meta.requiredRuntimeSecrets;
   const extra = !Array.isArray(contract) && Array.isArray(contract?.[stage2]) ? contract[stage2] ?? [] : [];
   const model = resolveDeployModel(meta, meta.repos?.[0] ?? "");
+  if (isNoEdgeTenantWorker(meta, model) && stage2 !== "main") return [];
   const defaults = projectRequiresGoogleOAuth(meta, model) ? DEFAULT_RUNTIME_SECRET_NAMES : [];
   return [.../* @__PURE__ */ new Set([...defaults, ...extra])];
 }
@@ -7433,6 +8334,9 @@ function appGapsFor(meta, model, slug, projectType) {
     "Make app config fail clearly for missing required env in prod/rc instead of relying on hidden defaults.",
     "Keep app-owned README.md and architecture.md aligned with v2 central deploy/secrets reality."
   ];
+  if (isNoEdgeTenantWorker(meta, model)) {
+    gaps.unshift("No public edge declared (`edgeDomains: {}`): worker/outbound-only tenant; skip Cloudflare edge auto-heal, OAuth defaults, and dev/rc remote deploy coords unless META explicitly adds them.");
+  }
   if (contractUndeclared) {
     gaps.unshift(CONTRACT_UNDECLARED_LINE);
   }
@@ -7442,6 +8346,31 @@ function appGapsFor(meta, model, slug, projectType) {
   if (!meta) gaps.unshift("No app-owned repo changes can be planned precisely until Hub registry META exists.");
   return gaps;
 }
+function edgeDomainsByStage(meta) {
+  const ed = meta?.edgeDomains;
+  if (!ed || typeof ed !== "object" || Array.isArray(ed)) return {};
+  const out = {};
+  for (const stage2 of STAGES) {
+    const v = ed[stage2];
+    if (typeof v === "string" && v.trim()) out[stage2] = v.trim();
+  }
+  return out;
+}
+async function probeEdgeDomains(meta, resolveDns) {
+  const byStage = edgeDomainsByStage(meta);
+  const results = await Promise.all(
+    Object.entries(byStage).map(async ([stage2, host]) => {
+      let resolved;
+      try {
+        resolved = await resolveDns(host);
+      } catch {
+        resolved = void 0;
+      }
+      return resolved === false ? { stage: stage2, host } : void 0;
+    })
+  );
+  return results.filter((r) => r !== void 0);
+}
 function contractByStage(contract) {
   return contract && !Array.isArray(contract) ? contract : {};
 }
@@ -7572,7 +8501,7 @@ async function buildV2Doctor(repoOrSlug, deps) {
     secretsError = e?.message || "secrets list failed";
   }
   const deployCoords = Object.fromEntries(await Promise.all(STAGES.map(async (stage2) => {
-    const required = projectRequiresDeployCoords(model);
+    const required = projectRequiresDeployCoords(model, stage2, meta);
     return [stage2, { required, ok: required ? await deps.hasDeployCoords(slug, stage2) : true }];
   })));
   const deployState = Object.fromEntries(await Promise.all(STAGES.map(async (stage2) => {
@@ -7587,6 +8516,7 @@ async function buildV2Doctor(repoOrSlug, deps) {
   }));
   const metaMissing = ["class", "projectType", "deployModel", "vaultPath", "kbPointer"].filter((key) => meta[key] === void 0);
   const ok = !secretsError && metaMissing.length === 0 && Object.values(deployCoords).every((v) => v.ok) && Object.values(secrets2).every((v) => v.missing.length === 0);
+  const edgeDomainWarnings = deps.resolveDns ? await probeEdgeDomains(meta, deps.resolveDns) : [];
   return {
     ok,
     repo,
@@ -7598,6 +8528,7 @@ async function buildV2Doctor(repoOrSlug, deps) {
     secretsError,
     autoHealAvailable: Object.keys(autoHeal.patch),
     appOwnedGaps: autoHeal.appOwnedGaps,
+    ...edgeDomainWarnings.length ? { edgeDomainWarnings } : {},
     appAttested: appAttestationOf(meta) ?? void 0
   };
 }
@@ -7625,6 +8556,9 @@ function renderReadinessIssueBody(existingBody, report, opts = {}) {
     `- META: ${report.hubOwned.meta.ok ? "ok" : `missing ${report.hubOwned.meta.missing.join(", ")}`}`,
     ...stageLines,
     ...report.secretsError ? [`- secrets UNVERIFIED (treated as not ready): ${report.secretsError}`] : [],
+    ...(report.edgeDomainWarnings ?? []).map(
+      (w) => `- \u26A0 edge domain does not resolve in DNS (advisory): ${w.stage} \u2192 ${w.host}; verify the registry edgeDomains value against the live public host`
+    ),
     "",
     "### Auto-heal applied / available",
     ...opts.healed?.length ? opts.healed.map((x) => `- ${x}`) : report.autoHealAvailable.map((x) => `- ${x}`),
@@ -7666,6 +8600,29 @@ function parseRuntimeSecretsVar(raw) {
   }
   return out;
 }
+function parseEdgeDomainsVar(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('project set: edgeDomains must be JSON, e.g. {"dev":"dev.example.co","rc":"rc.example.co","main":"example.co"}');
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("project set: edgeDomains must be a {dev,rc,main} map of domain strings");
+  }
+  const map = parsed;
+  const out = {};
+  for (const [stage2, domain] of Object.entries(map)) {
+    if (!RUNTIME_SECRET_STAGES.includes(stage2)) {
+      throw new Error(`project set: edgeDomains stage "${stage2}" \u2014 expected only ${RUNTIME_SECRET_STAGES.join("/")}`);
+    }
+    if (typeof domain !== "string" || !domain.trim()) {
+      throw new Error(`project set: edgeDomains.${stage2} must be a non-empty domain string`);
+    }
+    out[stage2] = domain.trim();
+  }
+  return out;
+}
 function buildProjectSetPatch(input) {
   const patch = {};
   if (input.class) {
@@ -7697,6 +8654,8 @@ function buildProjectSetPatch(input) {
         patch[key] = n;
       } else if (key === "requiredRuntimeSecrets") {
         patch[key] = parseRuntimeSecretsVar(raw);
+      } else if (key === "edgeDomains") {
+        patch[key] = parseEdgeDomainsVar(raw);
       } else {
         patch[key] = raw;
       }
@@ -7738,8 +8697,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`];
@@ -7756,7 +8715,7 @@ function parseKbTree(stdout, prefix) {
 }
 
 // src/plan.ts
-var import_node_path6 = require("node:path");
+var import_node_path7 = require("node:path");
 
 // src/frontmatter.ts
 function splitFrontmatter(content) {
@@ -7839,8 +8798,8 @@ function rankPlansByRelevance(plans, signals, opts = {}) {
 
 // src/plan.ts
 var PLANS_DIR = "plans";
-var META_FILE = (0, import_node_path6.join)(PLANS_DIR, ".plan-meta.json");
-var planPath = (slug) => (0, import_node_path6.join)(PLANS_DIR, `${slug}.md`);
+var META_FILE = (0, import_node_path7.join)(PLANS_DIR, ".plan-meta.json");
+var planPath = (slug) => (0, import_node_path7.join)(PLANS_DIR, `${slug}.md`);
 var metaKey = (project2, slug) => `${project2}/${slug}`;
 function parseMeta(raw) {
   if (!raw) return {};
@@ -7888,6 +8847,10 @@ ${next.join("\n")}
 ---
 ${body.replace(/^\n+/, "")}`;
 }
+async function httpFailMessage(op, res) {
+  if (res.status === 426) return upgradeRequiredError(res, await res.json().catch(() => null));
+  return `plan ${op} failed: HTTP ${res.status}`;
+}
 async function planPush(deps, slug, opts = {}) {
   const raw = deps.readLocal(slug);
   if (raw == null) {
@@ -7919,7 +8882,7 @@ async function planPush(deps, slug, opts = {}) {
     deps.err(staleHint(slug));
     return false;
   } else {
-    deps.err(`plan push failed: HTTP ${res.status}`);
+    deps.err(await httpFailMessage("push", res));
     return false;
   }
 }
@@ -7943,7 +8906,7 @@ async function planPull(deps, slug, opts = {}) {
     return false;
   }
   if (!res.ok) {
-    deps.err(`plan pull failed: HTTP ${res.status}`);
+    deps.err(await httpFailMessage("pull", res));
     return false;
   }
   const doc = await res.json();
@@ -7961,6 +8924,7 @@ async function fetchPlanList(deps, project2) {
     headers: await deps.headers(),
     signal: AbortSignal.timeout(TIMEOUT_MS)
   });
+  if (res.status === 426) throw new Error(upgradeRequiredError(res, await res.json().catch(() => null)));
   if (!res.ok) throw new Error(`HTTP ${res.status}`);
   const { plans } = await res.json();
   return plans ?? [];
@@ -8016,7 +8980,7 @@ async function planDelete(deps, slug, opts = {}) {
     signal: AbortSignal.timeout(TIMEOUT_MS)
   });
   if (!res.ok) {
-    deps.err(`plan delete failed: HTTP ${res.status}`);
+    deps.err(await httpFailMessage("delete", res));
     return;
   }
   deps.removeLocal(slug);
@@ -8103,6 +9067,52 @@ function formatVaultPointer(p) {
 }
 var TIMEOUT_MS2 = 8e3;
 var repoOf = (slug) => `${OWNER2}/${slug}`;
+var RECALL_REGIONS = ["us-east-1", "us-west-2", "eu-central-1", "ap-northeast-1"];
+var PROVIDER_VERIFY_TIMEOUT_MS = 8e3;
+function secretLeafName(key) {
+  return key.split("/").pop() ?? key;
+}
+function providerForSecretKey(key) {
+  return secretLeafName(key) === "RECALL_API_KEY" ? "recall" : void 0;
+}
+function recallUsageUrl(region) {
+  const end = /* @__PURE__ */ new Date();
+  const start = new Date(end.getTime() - 60 * 60 * 1e3);
+  const qs = new URLSearchParams({ start: start.toISOString(), end: end.toISOString() });
+  return `https://${region}.recall.ai/api/v1/billing/usage/?${qs.toString()}`;
+}
+async function verifyRecallApiKey(deps, value) {
+  const checked = [];
+  for (const region of RECALL_REGIONS) {
+    try {
+      const res = await deps.fetch(recallUsageUrl(region), {
+        method: "GET",
+        headers: { Authorization: `Token ${value}` },
+        signal: AbortSignal.timeout(PROVIDER_VERIFY_TIMEOUT_MS)
+      });
+      if (res.ok) {
+        return { ok: true, provider: "recall", message: `validated RECALL_API_KEY with Recall (${region})`, checked };
+      }
+      checked.push(`${region}: HTTP ${res.status}`);
+    } catch (e) {
+      checked.push(`${region}: ${e.message}`);
+    }
+  }
+  return {
+    ok: false,
+    provider: "recall",
+    message: `Recall rejected the key in all configured regions (${checked.join("; ")})`,
+    checked
+  };
+}
+async function verifySecretValue(deps, key, value, _opts) {
+  const provider = providerForSecretKey(key);
+  if (!provider) {
+    return { ok: false, message: `no provider verifier configured for ${secretLeafName(key)}`, checked: [] };
+  }
+  if (provider === "recall") return verifyRecallApiKey(deps, value);
+  return { ok: false, provider, message: `no provider verifier configured for ${secretLeafName(key)}`, checked: [] };
+}
 async function vaultSlug(deps, opts) {
   return (opts.repo ? opts.repo.split("/").pop() : await deps.slug()).toLowerCase();
 }
@@ -8132,6 +9142,10 @@ function errorDetail(body) {
   const error = typeof body.error === "string" ? body.error : "";
   return error ? `: ${error}` : "";
 }
+async function upgradeMessage(res, body) {
+  if (res.status !== 426) return null;
+  return upgradeRequiredError(res, body ?? await readJsonBody(res));
+}
 async function fetchSecretValue(deps, key, opts) {
   if (!isValidSecretKey(key)) return null;
   const repo = await targetRepo(deps, opts);
@@ -8164,7 +9178,7 @@ async function secretsList(deps, opts) {
     return;
   }
   if (!res.ok) {
-    deps.err(`secrets list failed: HTTP ${res.status}${await readErr(res)}`);
+    deps.err(await upgradeMessage(res) ?? `secrets list failed: HTTP ${res.status}${await readErr(res)}`);
     return;
   }
   const { secrets: secrets2 } = await res.json();
@@ -8197,7 +9211,7 @@ async function secretsPreflight(deps, opts) {
     return false;
   }
   if (!res.ok) {
-    deps.err(`secrets preflight failed: HTTP ${res.status}${await readErr(res)}`);
+    deps.err(await upgradeMessage(res) ?? `secrets preflight failed: HTTP ${res.status}${await readErr(res)}`);
     return false;
   }
   const { secrets: secrets2 } = await res.json();
@@ -8232,7 +9246,7 @@ async function secretsGet(deps, key, opts) {
       return false;
     }
     deps.err(
-      res.status === 403 ? `secrets get: not authorized for ${key} (HTTP 403)${errorDetail(body)}` : `secrets get failed: HTTP ${res.status}${errorDetail(body)}`
+      await upgradeMessage(res, body) ?? (res.status === 403 ? `secrets get: not authorized for ${key} (HTTP 403)${errorDetail(body)}` : `secrets get failed: HTTP ${res.status}${errorDetail(body)}`)
     );
     return false;
   }
@@ -8240,6 +9254,28 @@ async function secretsGet(deps, key, opts) {
   deps.log(value ?? "");
   return true;
 }
+async function secretsVerify(deps, key, opts) {
+  if (!isValidSecretKey(key)) {
+    deps.err(`invalid secret key ${JSON.stringify(key)}`);
+    return false;
+  }
+  if (!providerForSecretKey(key)) {
+    deps.err(`no provider verifier configured for ${secretLeafName(key)}`);
+    return false;
+  }
+  const value = await fetchSecretValue(deps, key, opts);
+  if (!value) {
+    deps.err(`secrets verify: could not read ${key}; no value was printed`);
+    return false;
+  }
+  const result = await verifySecretValue(deps, key, value, opts);
+  if (result.ok) {
+    deps.log(result.message);
+    return true;
+  }
+  deps.err(result.message);
+  return false;
+}
 async function secretsRequest(deps, key, opts) {
   if (!isValidSecretKey(key)) {
     deps.err(`invalid secret key ${JSON.stringify(key)}`);
@@ -8260,7 +9296,7 @@ async function secretsRequest(deps, key, opts) {
   });
   const body = await readJsonBody(res);
   if (!res.ok) {
-    deps.err(`secrets request failed: HTTP ${res.status}${errorDetail(body)}`);
+    deps.err(await upgradeMessage(res, body) ?? `secrets request failed: HTTP ${res.status}${errorDetail(body)}`);
     return false;
   }
   if (opts.json) {
@@ -8290,21 +9326,34 @@ async function putSecret(deps, key, value, opts) {
   });
   if (!res.ok) {
     deps.err(
-      res.status === 403 ? `secrets set: not authorized to write ${key} (HTTP 403)${await readErr(res)}` : `secrets set failed: HTTP ${res.status}${await readErr(res)}`
+      await upgradeMessage(res) ?? (res.status === 403 ? `secrets set: not authorized to write ${key} (HTTP 403)${await readErr(res)}` : `secrets set failed: HTTP ${res.status}${await readErr(res)}`)
     );
     return false;
   }
+  const provider = providerForSecretKey(key);
+  if (provider) {
+    const result = await verifySecretValue(deps, key, value, opts);
+    if (!result.ok) {
+      deps.err(`set ${key} (${classifyTier(await vaultSlug(deps, opts), key)} tier), but ${result.message}`);
+      return false;
+    }
+    deps.log(`set ${key} (${classifyTier(await vaultSlug(deps, opts), key)} tier); ${result.message}`);
+    return true;
+  }
   deps.log(`set ${key} (${classifyTier(await vaultSlug(deps, opts), key)} tier)`);
   return true;
 }
 async function secretsSet(deps, key, opts) {
-  if (!isValidSecretKey(key)) return deps.err(`invalid secret key ${JSON.stringify(key)}`);
+  if (!isValidSecretKey(key)) {
+    deps.err(`invalid secret key ${JSON.stringify(key)}`);
+    return false;
+  }
   const value = await deps.readSecretValue(`value for ${key} (input hidden; will not be echoed): `);
   if (!value) {
     deps.err("secrets set: empty value \u2014 aborted (nothing written)");
-    return;
+    return false;
   }
-  await putSecret(deps, key, value, opts);
+  return putSecret(deps, key, value, opts);
 }
 async function secretsEdit(deps, key, opts) {
   return secretsSet(deps, key, opts);
@@ -8320,7 +9369,7 @@ async function secretsRemove(deps, key, opts) {
   });
   if (!res.ok) {
     deps.err(
-      res.status === 403 ? `secrets rm: not authorized to remove ${key} (HTTP 403)${await readErr(res)}` : `secrets rm failed: HTTP ${res.status}${await readErr(res)}`
+      await upgradeMessage(res) ?? (res.status === 403 ? `secrets rm: not authorized to remove ${key} (HTTP 403)${await readErr(res)}` : `secrets rm failed: HTTP ${res.status}${await readErr(res)}`)
     );
     return;
   }
@@ -8335,7 +9384,7 @@ async function secretsGrant(deps, repo, login, key, _opts) {
   });
   if (!res.ok) {
     deps.err(
-      res.status === 403 ? `secrets grant: master-admin only (HTTP 403)${await readErr(res)}` : `secrets grant failed: HTTP ${res.status}${await readErr(res)}`
+      await upgradeMessage(res) ?? (res.status === 403 ? `secrets grant: master-admin only (HTTP 403)${await readErr(res)}` : `secrets grant failed: HTTP ${res.status}${await readErr(res)}`)
     );
     return;
   }
@@ -8350,7 +9399,7 @@ async function secretsRevoke(deps, repo, login, key, _opts) {
   });
   if (!res.ok) {
     deps.err(
-      res.status === 403 ? `secrets revoke: master-admin only (HTTP 403)${await readErr(res)}` : `secrets revoke failed: HTTP ${res.status}${await readErr(res)}`
+      await upgradeMessage(res) ?? (res.status === 403 ? `secrets revoke: master-admin only (HTTP 403)${await readErr(res)}` : `secrets revoke failed: HTTP ${res.status}${await readErr(res)}`)
     );
     return;
   }
@@ -8487,7 +9536,8 @@ async function awsCallerArn() {
 async function hubHeaders(extra = {}) {
   const cfg = await loadConfig();
   const t = await hubAuthToken({ baseUrl: cfg.sagaApiUrl ?? defaultHubUrl(), githubToken });
-  return t ? { ...extra, Authorization: `Bearer ${t}` } : extra;
+  const base = { ...clientVersionHeaders(), ...extra };
+  return t ? { ...base, Authorization: `Bearer ${t}` } : base;
 }
 async function loadConfig() {
   let file = {};
@@ -8550,7 +9600,7 @@ function sessionDeps() {
     env: process.env,
     readPersisted: () => {
       try {
-        return (0, import_node_fs6.readFileSync)(SESSION_FILE, "utf8");
+        return (0, import_node_fs7.readFileSync)(SESSION_FILE, "utf8");
       } catch {
         return null;
       }
@@ -8563,8 +9613,8 @@ function sessionDeps() {
 var resolveSessionId = () => resolveSession(sessionDeps());
 function persistSession(id) {
   try {
-    (0, import_node_fs6.mkdirSync)(".mmi", { recursive: true });
-    (0, import_node_fs6.writeFileSync)(SESSION_FILE, id, "utf8");
+    (0, import_node_fs7.mkdirSync)(".mmi", { recursive: true });
+    (0, import_node_fs7.writeFileSync)(SESSION_FILE, id, "utf8");
   } catch {
   }
 }
@@ -8683,22 +9733,20 @@ async function applyGcPlan(plan2, remote) {
   }
   return result;
 }
-function resolveVersion() {
+async function fetchHubVersionInfo(baseUrl) {
+  if (!baseUrl) return null;
   try {
-    const manifest = (0, import_node_path7.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
-    return JSON.parse((0, import_node_fs6.readFileSync)(manifest, "utf8")).version || "0.0.0";
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/version`, { signal: AbortSignal.timeout(4e3) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body && typeof body === "object" ? body : null;
   } catch {
-    try {
-      const pkg = (0, import_node_path7.join)(__dirname, "..", "package.json");
-      return JSON.parse((0, import_node_fs6.readFileSync)(pkg, "utf8")).version || "0.0.0";
-    } catch {
-      return "0.0.0";
-    }
+    return null;
   }
 }
 function readRepoVersion() {
   try {
-    return JSON.parse((0, import_node_fs6.readFileSync)((0, import_node_path7.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
+    return JSON.parse((0, import_node_fs7.readFileSync)((0, import_node_path8.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
   } catch {
     return void 0;
   }
@@ -8737,7 +9785,7 @@ async function applyVersionAutoUpdate(report, log) {
 }
 async function requireFreshTrainCli(commandName) {
   const report = buildVersionLagReport({
-    currentVersion: resolveVersion(),
+    currentVersion: resolveClientVersion(),
     repoVersion: readRepoVersion(),
     releasedVersion: await fetchReleasedVersion()
   });
@@ -8767,7 +9815,7 @@ async function applyClaudePluginHeal(surface, log) {
   return true;
 }
 var program2 = new Command();
-program2.name("mmi-cli").description("MMI Future CLI \u2014 org rules delivery, saga, KB. The engine the plugin SessionStart hook drives.").version(resolveVersion());
+program2.name("mmi-cli").description("MMI Future CLI \u2014 org rules delivery, saga, KB. The engine the plugin SessionStart hook drives.").version(resolveClientVersion());
 async function runRulesSync(opts, io = consoleIo) {
   const cfg = await loadConfig();
   if (isRulesSource(cfg.orgRulesSource)) {
@@ -8777,7 +9825,13 @@ async function runRulesSync(opts, io = consoleIo) {
   const base = resolveRulesBase(cfg.orgRulesSource, DEFAULT_RULES_SOURCE);
   const token = await githubToken();
   let changed = 0;
-  const files = ["AGENTS.md", "CLAUDE.md", ".claude/settings.json"];
+  const files = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".claude/settings.json",
+    ".claude/output-styles/mmi-plain.md",
+    ".cursor/rules/mmi-plain-language.mdc"
+  ];
   const fetched = await Promise.all(files.map(async (file) => {
     try {
       const url = `${base}/${file}`;
@@ -8795,10 +9849,10 @@ async function runRulesSync(opts, io = consoleIo) {
   for (const entry of fetched) {
     if ("error" in entry) continue;
     const { file, source } = entry;
-    const current = (0, import_node_fs6.existsSync)(file) ? await (0, import_promises2.readFile)(file, "utf8") : null;
+    const current = (0, import_node_fs7.existsSync)(file) ? await (0, import_promises2.readFile)(file, "utf8") : null;
     if (needsUpdate(source, current)) {
       const slash = file.lastIndexOf("/");
-      if (slash > 0) (0, import_node_fs6.mkdirSync)(file.slice(0, slash), { recursive: true });
+      if (slash > 0) (0, import_node_fs7.mkdirSync)(file.slice(0, slash), { recursive: true });
       await (0, import_promises2.writeFile)(file, normalizeEol(source), "utf8");
       changed++;
       if (!opts.quiet) io.log(`mmi-cli rules: updated ${file}`);
@@ -8808,7 +9862,7 @@ async function runRulesSync(opts, io = consoleIo) {
   return failures.length === 0;
 }
 var rules = program2.command("rules").description("org rules delivery");
-rules.command("sync").option("--quiet", "stay silent unless something changed or errored").description("fetch AGENTS.md / CLAUDE.md / .claude/settings.json from MMI-Hub and write them verbatim (org-owned, whole-file)").action(async (opts) => {
+rules.command("sync").option("--quiet", "stay silent unless something changed or errored").description("fetch the org-delivered files (AGENTS.md / CLAUDE.md / .claude/settings.json / output style / Cursor rule) from MMI-Hub and write them verbatim (org-owned, whole-file)").action(async (opts) => {
   if (!await runRulesSync(opts)) process.exitCode = 1;
 });
 async function runDocsSync(opts, io = consoleIo) {
@@ -8824,7 +9878,7 @@ async function runDocsSync(opts, io = consoleIo) {
         return null;
       }
     },
-    localContent: async (f) => (0, import_node_fs6.existsSync)(f) ? await (0, import_promises2.readFile)(f, "utf8") : null,
+    localContent: async (f) => (0, import_node_fs7.existsSync)(f) ? await (0, import_promises2.readFile)(f, "utf8") : null,
     writeDoc: async (f, c) => {
       await (0, import_promises2.writeFile)(f, c, "utf8");
     }
@@ -8972,6 +10026,18 @@ async function runSagaHealth(o, io = consoleIo) {
   io.log(`saga health: ${report.ok ? "OK" : "NOT OK"}`);
   if (report.problems.length) io.log(report.problems.map((p) => ` - ${p}`).join("\n"));
 }
+async function runWhoami(io = consoleIo) {
+  const cfg = await loadConfig();
+  const report = await resolveWhoami({
+    hubSession: () => hubAuthSession({ baseUrl: cfg.sagaApiUrl ?? defaultHubUrl(), githubToken }),
+    ghLogin: githubLogin
+  });
+  io.log(JSON.stringify(report));
+  return report;
+}
+program2.command("whoami").description('resolve the logged-in human: {login, source, sessionExpiresAt} JSON; source "unknown" (exit 0) when neither the Hub session nor gh can name them').action(async () => {
+  await runWhoami();
+});
 saga.command("health").option("--json", "machine-readable output").option("--banner", "one-line SessionStart banner; silent when healthy").option("--quiet", "suppress detail output").description("zero-write health check: auth, backend reachability, resolved key").action((o) => runSagaHealth(o));
 program2.command("gc").description("dry-run cleanup for merged/closed PR branches and stale tracking refs").option("--dry-run", "show what would be deleted (default)").option("--apply", "delete only the listed clean merged/closed PR branches and stale tracking refs").option("--json", "machine-readable output").option("--remote <name>", "remote name", "origin").option("--limit <n>", "PRs to inspect per state", "200").action(async (o) => {
   if (o.apply && o.dryRun) return fail("gc: choose either --dry-run or --apply");
@@ -9100,7 +10166,7 @@ function scheduleRelatedDiscovery(o) {
   }
 }
 function makePlanDeps(cfg, io = consoleIo) {
-  const ensureDir = () => (0, import_node_fs6.mkdirSync)(PLANS_DIR, { recursive: true });
+  const ensureDir = () => (0, import_node_fs7.mkdirSync)(PLANS_DIR, { recursive: true });
   return {
     apiUrl: cfg.sagaApiUrl,
     fetch: (url, init = {}) => fetch(url, { ...init, signal: init.signal ?? AbortSignal.timeout(1e4) }),
@@ -9108,31 +10174,31 @@ function makePlanDeps(cfg, io = consoleIo) {
     project: async () => (await sagaKey(cfg)).project,
     readLocal: (slug) => {
       try {
-        return (0, import_node_fs6.readFileSync)(planPath(slug), "utf8");
+        return (0, import_node_fs7.readFileSync)(planPath(slug), "utf8");
       } catch {
         return null;
       }
     },
     writeLocal: (slug, content) => {
       ensureDir();
-      (0, import_node_fs6.writeFileSync)(planPath(slug), content, "utf8");
+      (0, import_node_fs7.writeFileSync)(planPath(slug), content, "utf8");
     },
     removeLocal: (slug) => {
       try {
-        (0, import_node_fs6.rmSync)(planPath(slug));
+        (0, import_node_fs7.rmSync)(planPath(slug));
       } catch {
       }
     },
     readMetaRaw: () => {
       try {
-        return (0, import_node_fs6.readFileSync)(META_FILE, "utf8");
+        return (0, import_node_fs7.readFileSync)(META_FILE, "utf8");
       } catch {
         return null;
       }
     },
     writeMetaRaw: (raw) => {
       ensureDir();
-      (0, import_node_fs6.writeFileSync)(META_FILE, raw, "utf8");
+      (0, import_node_fs7.writeFileSync)(META_FILE, raw, "utf8");
     },
     log: (m) => io.log(m),
     err: (m) => io.err(m),
@@ -9273,8 +10339,18 @@ secrets.command("request <key>").description("approved escalation: create a Hub
   const ok = await secretsRequest(d, key, o);
   if (!ok) process.exitCode = 1;
 }));
-secrets.command("set <key>").description("write/rotate a secret; value is read from stdin (never an argument)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsSet(d, key, o)));
-secrets.command("edit <key>").description("alias for set \u2014 replace a secret value (read from stdin)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsEdit(d, key, o)));
+secrets.command("verify <key>").description("validate a known provider secret without printing its value").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets(async (d) => {
+  const ok = await secretsVerify(d, key, o);
+  if (!ok) process.exitCode = 1;
+}));
+secrets.command("set <key>").description("write/rotate a secret; value is read from stdin (never an argument)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets(async (d) => {
+  const ok = await secretsSet(d, key, o);
+  if (!ok) process.exitCode = 1;
+}));
+secrets.command("edit <key>").description("alias for set \u2014 replace a secret value (read from stdin)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets(async (d) => {
+  const ok = await secretsEdit(d, key, o);
+  if (!ok) process.exitCode = 1;
+}));
 secrets.command("rm <key>").description("remove a secret (project tier self-serve; org tier needs a grant)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsRemove(d, key, o)));
 secrets.command("use <key>").description("print guidance on consuming a secret without committing it (no value)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsUse(d, key, o)));
 secrets.command("grant <repo> <login> <key>").description("MASTER-ONLY: grant a project-admin standing access to a specific org-tier secret").action((repo, login, key) => withSecrets((d) => secretsGrant(d, repo, login, key, {})));
@@ -9297,7 +10373,13 @@ function reportWrite(label, res) {
 var tenant = program2.command("tenant").description("tenant runtime control through Hub authority");
 tenant.command("control <owner/repo> <stage> <action>").description("run bounded service control (status/start/stop/restart, plus rc-only retire) for a tenant; project-admin dev/rc, master main").option("--json", "machine-readable output").action(async (repo, stage2, action) => {
   const cfg = await loadConfig();
-  const res = await tenantControl({ repo, stage: stage2, action }, registryClientDeps(cfg));
+  const wait = action === "status" || action === "retire";
+  const res = await tenantControl({ repo, stage: stage2, action, wait }, registryClientDeps(cfg));
+  const body = res.body;
+  if (!res.ok && body?.category) {
+    console.log(JSON.stringify(body));
+    return fail(`tenant control ${stage2} ${action}: ${body.category}`);
+  }
   reportWrite("tenant control", res);
 });
 tenant.command("redeploy <owner/repo> <stage>").description("re-dispatch the central tenant-deploy.yml for an already-promoted ref (no re-tag/merge); train-authority gated").option("--ref <ref>", "ref to deploy (defaults to the stage branch rc/main \u2014 the promoted ref)").option("--watch", "block on the dispatched run and report its outcome (gh run watch --exit-status)").option("--json", "machine-readable output").action(async (repo, stage2, o) => {
@@ -9309,9 +10391,18 @@ tenant.command("redeploy <owner/repo> <stage>").description("re-dispatch the cen
     return fail(`tenant redeploy: ${e.message}`);
   }
 });
+async function resolveDnsBounded(host, timeoutMs = 3e3) {
+  const { lookup } = await import("node:dns/promises");
+  const probe = lookup(host).then(() => true).catch((e) => dnsErrorToResolution(e?.code));
+  const timeout = new Promise((resolve) => {
+    setTimeout(() => resolve(void 0), timeoutMs).unref?.();
+  });
+  return Promise.race([probe, timeout]);
+}
 async function v2ReadinessDeps(cfg) {
   const reg = registryClientDeps(cfg);
   return {
+    resolveDns: (host) => resolveDnsBounded(host),
     // Checked read (#727/#733): the doctor distinguishes a FAILED read (degraded report) from a 404.
     getProject: (slug) => fetchProjectBySlugChecked(slug, reg),
     hasDeployCoords: async (slug, stage2) => {
@@ -9753,7 +10844,7 @@ async function remoteBranchExists(branch) {
 var COMPOSE_TIMEOUT_MS = 12e4;
 function teardownWorktreeStage(worktreePath) {
   return runWorktreeStageTeardown(worktreePath, {
-    hasStageState: (wt) => (0, import_node_fs6.existsSync)(stageStatePath(wt)),
+    hasStageState: (wt) => (0, import_node_fs7.existsSync)(stageStatePath(wt)),
     stopRecordedStage: async (wt) => (await stopStage({ cwd: wt })).pid,
     listComposeProjects: async () => {
       const { stdout } = await execFileP4("docker", ["compose", "ls", "--all", "--format", "json"], { timeout: GC_GH_TIMEOUT_MS });
@@ -9827,17 +10918,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}`);
   }
@@ -9917,7 +11031,7 @@ function rawValues(flag) {
   return out;
 }
 function printLine(value) {
-  (0, import_node_fs6.writeSync)(1, `${value}
+  (0, import_node_fs7.writeSync)(1, `${value}
 `);
 }
 function stageKeepAlive() {
@@ -9934,8 +11048,8 @@ async function resolveStage() {
     local,
     shell: shellFor(),
     registry: { deployModel: project2?.deployModel, portRange, error: read.ok ? void 0 : read.error },
-    hasCompose: (0, import_node_fs6.existsSync)((0, import_node_path7.join)(process.cwd(), "docker-compose.yml")),
-    hasEnvExample: (0, import_node_fs6.existsSync)((0, import_node_path7.join)(process.cwd(), ".env.example"))
+    hasCompose: (0, import_node_fs7.existsSync)((0, import_node_path8.join)(process.cwd(), "docker-compose.yml")),
+    hasEnvExample: (0, import_node_fs7.existsSync)((0, import_node_path8.join)(process.cwd(), ".env.example"))
   });
 }
 function stageStepsFor(res, stops = true) {
@@ -9958,9 +11072,9 @@ function reportedStageUrl(res, result) {
   return result.port != null ? stageUrlForPort(result.port) : res.derived.url;
 }
 program2.command("port-range <repo>").description("assign (idempotently) + print the repo's local stage port block via the atomic ORG#config.portCursor allocator (committed-file fallback)").option("--json", "machine-readable output").action(async (repo, o) => {
-  const path2 = (0, import_node_path7.join)(process.cwd(), "infra", "port-ranges.json");
+  const path2 = (0, import_node_path8.join)(process.cwd(), "infra", "port-ranges.json");
   const allocate = async (seed) => {
-    const { stdout } = await execFileP4("node", [(0, import_node_path7.join)(process.cwd(), "infra", "port-ddb.mjs"), String(seed)], { timeout: 15e3 });
+    const { stdout } = await execFileP4("node", [(0, import_node_path8.join)(process.cwd(), "infra", "port-ddb.mjs"), String(seed)], { timeout: 15e3 });
     const parsed = JSON.parse(stdout);
     if (!Array.isArray(parsed.range) || parsed.range.length !== 2) throw new Error("port-ddb: no range in output");
     return parsed.range;
@@ -10078,16 +11192,29 @@ 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,
     trainAuthority: async (repo) => {
       const verdict = await fetchTrainAuthority(repo, registryClientDeps(await loadConfig()));
       return verdict.ok ? { ok: true, role: verdict.authority.role, train: verdict.authority.train } : verdict;
+    },
+    // Slack release announcement (#883): Hub-only + best-effort inside announceRelease itself.
+    announce: (args) => announceRelease({
+      run: async (file, cmdArgs) => (await execFileP4(file, cmdArgs, { timeout: GH_TRAIN_TIMEOUT_MS })).stdout,
+      readFile: (path2) => (0, import_promises2.readFile)(path2, "utf8")
+    }, args),
+    fetchEdgeDomains: async (slug) => {
+      const proj = await fetchProjectBySlug(slug, registryClientDeps(await loadConfig()));
+      const ed = proj?.edgeDomains;
+      if (!ed) return null;
+      const toArr = (v) => v ? [v] : void 0;
+      return { rc: toArr(ed.rc), main: toArr(ed.main) };
     }
   };
 }
@@ -10100,23 +11227,24 @@ function renderDeployLine(d) {
   return parts.join("; ");
 }
 function renderTrainApply(commandName, r) {
-  const base = `mmi-cli ${commandName}: promoted ${r.repo} \u2192 ${r.stage} at ${r.tag} [${r.deployModel}]; ${renderDeployLine(r)}`;
-  return r.rcRetirement ? `${base}; rc retirement: ${r.rcRetirement.toUpperCase()} (${r.rcRetirementNote ?? ""})` : base;
+  let base = `mmi-cli ${commandName}: promoted ${r.repo} \u2192 ${r.stage} at ${r.tag} [${r.deployModel}]; ${renderDeployLine(r)}`;
+  if (r.resumeNote) base = `${base}; ${r.resumeNote}`;
+  if (r.rcRetirement) base = `${base}; rc retirement: ${r.rcRetirement.toUpperCase()} (${r.rcRetirementNote ?? ""})`;
+  return r.announceNote ? `${base}; announce: ${r.announceNote}` : base;
 }
 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").option("--announce-summary-file <path>", "release only: agent-curated summary lines for the Hub Slack announcement (#883)").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 });
+        const result = await runTrainApply(commandName, trainApplyDeps(), { watch: o.watch, announceSummaryFile: o.announceSummaryFile });
         return printLine(o.json ? JSON.stringify(result, null, 2) : renderTrainApply(commandName, result));
       } catch (e) {
         return fail(`${commandName}: ${e.message}`);
@@ -10126,6 +11254,52 @@ 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}`,
+    ...r.announceNote ? [`  - announce: ${r.announceNote}`] : [],
+    `  - 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").option("--announce-summary-file <path>", "agent-curated summary lines for the Hub Slack announcement (#883)").action(async (version, o) => runHotfixSub("release", () => runHotfixRelease(trainApplyDeps(), version, { announceSummaryFile: o.announceSummaryFile }), 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");
@@ -10144,7 +11318,7 @@ bootstrap.command("verify <repo>").description("audit whether an existing repo i
   const report = await verifyBootstrap(repo, o.class, {
     client: defaultGitHubClient(),
     projectMeta: meta,
-    readLocalFile: (path2) => path2 === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs6.existsSync)(path2) ? (0, import_node_fs6.readFileSync)(path2, "utf8") : null,
+    readLocalFile: (path2) => path2 === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs7.existsSync)(path2) ? (0, import_node_fs7.readFileSync)(path2, "utf8") : null,
     // requiredGcpApis is stored as an array by a JSON write, but `project set --var KEY=VALUE` stores a raw
     // comma-string — accept either so the seeded value verifies regardless of how it was written.
     requiredGcpApis: (() => {
@@ -10185,12 +11359,12 @@ bootstrap.command("apply <repo>").description("idempotent seed apply from skills
     return fail(`bootstrap apply: ${e.message}`);
   }
   const manifestPath = "skills/bootstrap/seeds/manifest.json";
-  if (!(0, import_node_fs6.existsSync)(manifestPath)) return fail(`bootstrap apply: ${manifestPath} not found; run from the MMI-Hub repo root`);
-  const manifest = loadBootstrapSeeds((0, import_node_fs6.readFileSync)(manifestPath, "utf8"));
+  if (!(0, import_node_fs7.existsSync)(manifestPath)) return fail(`bootstrap apply: ${manifestPath} not found; run from the MMI-Hub repo root`);
+  const manifest = loadBootstrapSeeds((0, import_node_fs7.readFileSync)(manifestPath, "utf8"));
   const baseBranch = o.class === "content" ? "main" : "development";
   const slug = parsedRepo.slug;
   const gh = async (args) => execFileP4("gh", args, { timeout: 2e4 });
-  const readFile2 = (p) => (0, import_node_fs6.existsSync)(p) ? (0, import_node_fs6.readFileSync)(p, "utf8") : null;
+  const readFile2 = (p) => (0, import_node_fs7.existsSync)(p) ? (0, import_node_fs7.readFileSync)(p, "utf8") : null;
   const enc = (p) => p.split("/").map(encodeURIComponent).join("/");
   const vars = {};
   for (const value of rawValues("--var")) {
@@ -10314,16 +11488,16 @@ access.command("audit").description("audit collaborator roles + train-branch pus
     if (o.class !== "deployable" && o.class !== "content") return fail("access audit: --class must be deployable or content");
     targets = [{ repo: o.repo, class: o.class }];
   } else {
-    const projectsJson = registryProjects ? JSON.stringify({ projects: registryProjects }) : (0, import_node_fs6.existsSync)("projects.json") ? (0, import_node_fs6.readFileSync)("projects.json", "utf8") : null;
+    const projectsJson = registryProjects ? JSON.stringify({ projects: registryProjects }) : (0, import_node_fs7.existsSync)("projects.json") ? (0, import_node_fs7.readFileSync)("projects.json", "utf8") : null;
     if (!projectsJson) return fail("access audit: no project registry \u2014 Hub API unreachable and projects.json not found; run from the MMI-Hub repo root or pass --repo <owner/repo>");
-    const fanoutJson = (0, import_node_fs6.existsSync)(".github/fanout-targets.json") ? (0, import_node_fs6.readFileSync)(".github/fanout-targets.json", "utf8") : null;
+    const fanoutJson = (0, import_node_fs7.existsSync)(".github/fanout-targets.json") ? (0, import_node_fs7.readFileSync)(".github/fanout-targets.json", "utf8") : null;
     targets = loadAccessTargets(projectsJson, fanoutJson);
   }
   const derivedMatrix = registryProjects ? accessMatrixFromProjects(registryProjects) : {};
-  const fileMatrix = (0, import_node_fs6.existsSync)("access-matrix.json") ? loadAccessMatrix((0, import_node_fs6.readFileSync)("access-matrix.json", "utf8")) : {};
+  const fileMatrix = (0, import_node_fs7.existsSync)("access-matrix.json") ? loadAccessMatrix((0, import_node_fs7.readFileSync)("access-matrix.json", "utf8")) : {};
   const matrix = mergeAccessMatrix(fileMatrix, derivedMatrix);
   const derivedContracts = registryProjects ? dataAccessContractsFromProjects(registryProjects) : { consumers: {} };
-  const fileContracts = (0, import_node_fs6.existsSync)("data-access-contracts.json") ? loadDataAccessContracts((0, import_node_fs6.readFileSync)("data-access-contracts.json", "utf8")) : { consumers: {} };
+  const fileContracts = (0, import_node_fs7.existsSync)("data-access-contracts.json") ? loadDataAccessContracts((0, import_node_fs7.readFileSync)("data-access-contracts.json", "utf8")) : { consumers: {} };
   const dataAccess = mergeDataAccessContracts(fileContracts, derivedContracts);
   const report = await auditOrgAccess(targets, deps, matrix, dataAccess);
   console.log(o.json ? JSON.stringify(report, null, 2) : renderAccessReport(report));
@@ -10332,18 +11506,28 @@ access.command("audit").description("audit collaborator roles + train-branch pus
 var isWin = process.platform === "win32";
 var installedPluginsPath = (surface = detectSurface(process.env)) => {
   const homeDir = surface === "codex" ? ".codex" : ".claude";
-  return (0, import_node_path7.join)((0, import_node_os3.homedir)(), homeDir, "plugins", "installed_plugins.json");
+  return (0, import_node_path8.join)((0, import_node_os3.homedir)(), homeDir, "plugins", "installed_plugins.json");
 };
 function readInstalledPlugins() {
   try {
-    return JSON.parse((0, import_node_fs6.readFileSync)(installedPluginsPath(), "utf8"));
+    return JSON.parse((0, import_node_fs7.readFileSync)(installedPluginsPath(), "utf8"));
   } catch {
     return null;
   }
 }
+function installedPluginSources() {
+  return ["claude", "codex"].map((surface) => {
+    const recordPath = (0, import_node_path8.join)((0, import_node_os3.homedir)(), `.${surface}`, "plugins", "installed_plugins.json");
+    try {
+      return { surface, installed: JSON.parse((0, import_node_fs7.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"));
+    return JSON.parse((0, import_node_fs7.readFileSync)((0, import_node_path8.join)(process.cwd(), ".claude", "settings.json"), "utf8"));
   } catch {
     return null;
   }
@@ -10365,7 +11549,7 @@ function writeProjectInstallRecord(record) {
     const list = file.plugins[MMI_PLUGIN_ID] ?? [];
     list.push(record);
     file.plugins[MMI_PLUGIN_ID] = list;
-    (0, import_node_fs6.writeFileSync)(installedPluginsPath(), `${JSON.stringify(file, null, 2)}
+    (0, import_node_fs7.writeFileSync)(installedPluginsPath(), `${JSON.stringify(file, null, 2)}
 `, "utf8");
     return true;
   } catch {
@@ -10378,25 +11562,57 @@ function backupAndWriteInstalledPlugins(records, pluginId) {
     if (!file) return false;
     if (!file.plugins) file.plugins = {};
     const path2 = installedPluginsPath();
-    (0, import_node_fs6.copyFileSync)(path2, `${path2}.bak`);
+    (0, import_node_fs7.copyFileSync)(path2, `${path2}.bak`);
     file.plugins[pluginId] = records;
-    (0, import_node_fs6.writeFileSync)(path2, `${JSON.stringify(file, null, 2)}
+    (0, import_node_fs7.writeFileSync)(path2, `${JSON.stringify(file, null, 2)}
 `, "utf8");
     return true;
   } catch {
     return false;
   }
 }
+function cursorPluginCacheRoot() {
+  return (0, import_node_path8.join)((0, import_node_os3.homedir)(), ".cursor", "plugins", "cache", "mmi", "mmi");
+}
+function cursorPluginCachePinSnapshots() {
+  const root = cursorPluginCacheRoot();
+  try {
+    return (0, import_node_fs7.readdirSync)(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => {
+      const path2 = (0, import_node_path8.join)(root, entry.name);
+      const pluginJson = (0, import_node_path8.join)(path2, ".cursor-plugin", "plugin.json");
+      const hooksJson = (0, import_node_path8.join)(path2, "hooks", "hooks.json");
+      let isEmpty = true;
+      try {
+        isEmpty = (0, import_node_fs7.readdirSync)(path2).length === 0;
+      } catch {
+        isEmpty = true;
+      }
+      return {
+        name: entry.name,
+        path: path2,
+        hasPluginJson: (0, import_node_fs7.existsSync)(pluginJson),
+        hasHooksJson: (0, import_node_fs7.existsSync)(hooksJson),
+        isEmpty
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+function hubCheckoutForCursorSeed() {
+  const manifest = (0, import_node_path8.join)(process.cwd(), "plugins", "mmi", ".cursor-plugin", "plugin.json");
+  return (0, import_node_fs7.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") },
-    { surface: "codex", root: (0, import_node_path7.join)((0, import_node_os3.homedir)(), ".codex", "plugins", "cache", "mmi", "mmi") }
+    { surface: "claude", root: (0, import_node_path8.join)((0, import_node_os3.homedir)(), ".claude", "plugins", "cache", "mmi", "mmi") },
+    { surface: "codex", root: (0, import_node_path8.join)((0, import_node_os3.homedir)(), ".codex", "plugins", "cache", "mmi", "mmi") }
   ];
   return roots.flatMap(({ surface, root }) => {
     try {
-      const entries = (0, import_node_fs6.readdirSync)(root, { withFileTypes: true }).map((entry) => ({
+      const entries = (0, import_node_fs7.readdirSync)(root, { withFileTypes: true }).map((entry) => ({
         name: entry.name,
-        path: (0, import_node_path7.join)(root, entry.name),
+        path: (0, import_node_path8.join)(root, entry.name),
         isDirectory: entry.isDirectory()
       }));
       return [{ surface, root, entries }];
@@ -10406,10 +11622,10 @@ function mmiPluginCacheRootSnapshots() {
   });
 }
 function uniqueQuarantineTarget(path2) {
-  if (!(0, import_node_fs6.existsSync)(path2)) return path2;
+  if (!(0, import_node_fs7.existsSync)(path2)) return path2;
   for (let i = 1; i < 100; i += 1) {
     const candidate = `${path2}-${i}`;
-    if (!(0, import_node_fs6.existsSync)(candidate)) return candidate;
+    if (!(0, import_node_fs7.existsSync)(candidate)) return candidate;
   }
   return `${path2}-${Date.now()}`;
 }
@@ -10417,27 +11633,27 @@ function quarantinePluginCacheDirs(plan2) {
   let moved = 0;
   for (const move of plan2) {
     try {
-      if (!(0, import_node_fs6.existsSync)(move.from)) continue;
+      if (!(0, import_node_fs7.existsSync)(move.from)) continue;
       const target = uniqueQuarantineTarget(move.to);
-      (0, import_node_fs6.mkdirSync)((0, import_node_path7.dirname)(target), { recursive: true });
-      (0, import_node_fs6.renameSync)(move.from, target);
+      (0, import_node_fs7.mkdirSync)((0, import_node_path8.dirname)(target), { recursive: true });
+      (0, import_node_fs7.renameSync)(move.from, target);
       moved += 1;
     } catch {
     }
   }
   return moved;
 }
-var gitignorePath = () => (0, import_node_path7.join)(process.cwd(), ".gitignore");
+var gitignorePath = () => (0, import_node_path8.join)(process.cwd(), ".gitignore");
 function readGitignore() {
   try {
-    return (0, import_node_fs6.readFileSync)(gitignorePath(), "utf8");
+    return (0, import_node_fs7.readFileSync)(gitignorePath(), "utf8");
   } catch {
     return null;
   }
 }
 function writeGitignore(content) {
   try {
-    (0, import_node_fs6.writeFileSync)(gitignorePath(), content, "utf8");
+    (0, import_node_fs7.writeFileSync)(gitignorePath(), content, "utf8");
     return true;
   } catch {
     return false;
@@ -10449,6 +11665,9 @@ 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 repoWritesAllowed = !opts.noRepoWrites;
   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:"';
@@ -10473,23 +11692,30 @@ async function runDoctor(opts, io = consoleIo) {
   let onPath = pathProbe;
   if (!onPath) {
     const root = process.env.CLAUDE_PLUGIN_ROOT;
-    if (root && (0, import_node_fs6.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
+    if (root && (0, import_node_fs7.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
   }
   checks.push({ ok: onPath, label: "mmi-cli on PATH", fix: "auto-provisioned at session start \u2014 reopen the session, or install the MMI plugin" });
   const surface = detectSurface(process.env);
   const reloadHint = reloadAction(surface);
   let versionReport = buildVersionLagReport({
-    currentVersion: resolveVersion(),
+    currentVersion: resolveClientVersion(),
     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(
+    buildHubCompatCheck({
+      isOrgRepo: Boolean(cfg.sagaApiUrl),
+      versionInfo: await fetchHubVersionInfo(cfg.sagaApiUrl),
+      installedVersion: resolveClientVersion()
+    })
+  );
   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;
@@ -10507,7 +11733,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`);
@@ -10515,20 +11741,25 @@ 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) {
+  const gitignoreDecision = decideGitignoreRepair(gitignoreCheck, { repoWritesAllowed, repairFull });
+  gitignoreCheck = gitignoreDecision.check;
+  if (gitignoreDecision.action === "suppress") {
+    io.err("  \u23F8 skipped (--no-repo-writes): org-managed .gitignore block repair would dirty the working tree");
+    io.err(`     apply it after the release train: ${gitignoreCheck.fix}`);
+  } else if (gitignoreDecision.action === "write") {
     if (writeGitignore(gitignoreCheck.contentToWrite)) {
-      gitignoreCheck = { ...gitignoreCheck, ok: true };
       const drift = gitignoreCheck.seeded ? "inserted the org-managed block" : [
         gitignoreCheck.added?.length ? `added ${gitignoreCheck.added.join(", ")}` : "",
         gitignoreCheck.removed?.length ? `removed ${gitignoreCheck.removed.join(", ")}` : ""
       ].filter(Boolean).join("; ") || "normalized the block";
+      gitignoreCheck = { ...gitignoreCheck, ok: true };
       io.err(`  \u21BB repaired: org-managed .gitignore block \u2014 ${drift}`);
       io.err("     this is an org-managed update (not unrelated churn) \u2014 stage & commit .gitignore so it stops recurring");
     }
   }
   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`);
@@ -10537,15 +11768,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
       });
@@ -10559,43 +11791,72 @@ async function runDoctor(opts, io = consoleIo) {
   let cacheCleanupCheck = buildMmiPluginCacheCleanupCheck({
     isOrgRepo: Boolean(cfg.sagaApiUrl),
     roots: mmiPluginCacheRootSnapshots(),
-    activeVersion: resolveVersion(),
+    activeVersion: resolveClientVersion(),
     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: resolveClientVersion(),
+        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_fs7.existsSync)(cursorCacheRoot),
+      pins: cursorPluginCachePinSnapshots() ?? [],
+      hubCheckout: hubCheckoutForCursorSeed()
+    })
+  );
   const gaps = checks.filter((c) => !c.ok);
-  const resources = doctorResourcesForGaps(gaps);
-  if (opts.json) {
-    io.log(JSON.stringify({ ok: gaps.length === 0, checks, ...resources.length ? { resources } : {} }, null, 2));
-    return;
-  }
   if (opts.banner) {
     if (gaps.length) io.log(`\u26A0 MMI setup needed \u2014 ${gaps.map((g) => g.fix).join(" \xB7 ")} \xB7 guide: ${MMI_AGENTIC_ONBOARDING_GUIDE.url}`);
     return;
   }
+  const cacheRoots = mmiPluginCacheRootSnapshots();
+  const cacheVersionsFor = (s) => cacheRoots.filter((r) => r.surface === s).flatMap((r) => r.entries.filter((e) => e.isDirectory).map((e) => e.name));
+  const sourceVersions = (s) => installedPluginVersions(installedPluginSources().find((src) => src.surface === s)?.installed ?? null);
+  const updateReport = buildPluginUpdateReport({
+    cliVersion: resolveClientVersion(),
+    claudePluginVersions: sourceVersions("claude"),
+    codexPluginVersions: sourceVersions("codex"),
+    codexCacheVersions: cacheVersionsFor("codex"),
+    releasedVersion
+  });
+  const resources = doctorResourcesForGaps(gaps);
+  if (opts.json) {
+    io.log(JSON.stringify(buildDoctorJsonPayload({ checks, updateReport, resources }), null, 2));
+    return;
+  }
   for (const c of checks) io.log(c.ok ? `\u2713 ${c.label}` : `\u2717 ${c.label}
    \u2192 ${c.fix}`);
   for (const r of resources) io.log(`Resource: ${r.label} \u2014 ${r.url}`);
+  io.log("");
+  for (const line of renderPluginUpdateReport(updateReport)) io.log(line);
   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("session-start").description("run the SessionStart verbs (rules sync, saga session+show, saga health, doctor) in one process; docs sync runs detached").action(async () => {
+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), print fixes, and report per-surface versions + update recipes").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)").option("--no-repo-writes", "env/plugin repairs only \u2014 never mutate the repo working tree; report pending managed .gitignore repairs with the follow-up command (for release-train prep)").action((opts) => (
+  // Commander maps `--no-repo-writes` to `repoWrites: false`; translate to the explicit `noRepoWrites` flag.
+  runDoctor({ ...opts, noRepoWrites: opts.repoWrites === false })
+));
+program2.command("session-start").description("run the SessionStart verbs (rules sync, saga session+show, saga health, whoami, doctor) in one process; docs sync runs detached").action(async () => {
   try {
     const hook = parseHookInput(await readStdin());
     if (hook.session_id) persistSession(hook.session_id);
@@ -10607,6 +11868,16 @@ program2.command("session-start").description("run the SessionStart verbs (rules
     rulesSync: (io) => runRulesSync({ quiet: true }, io),
     sagaShow: (io) => runSagaShow({ quiet: true }, io),
     sagaHealth: (io) => runSagaHealth({ banner: true, quiet: true }, io),
+    // whoami (#879): surface the resolved human so agents act --for them without asking. Silent
+    // when unknown — a missing gh login must not noise or fail the banner.
+    whoami: async (io) => {
+      const report = await resolveWhoami({
+        hubSession: async () => hubAuthSession({ baseUrl: (await loadConfig()).sagaApiUrl ?? defaultHubUrl(), githubToken }),
+        ghLogin: githubLogin
+      });
+      const line = whoamiLine(report);
+      if (line) io.log(line);
+    },
     doctor: (io) => runDoctor({ banner: true }, io)
   });
   await runSessionStart(parallel, sequential, consoleIo);
@@ -10614,7 +11885,7 @@ program2.command("session-start").description("run the SessionStart verbs (rules
 });
 function fail(msg) {
   console.error(`mmi-cli ${msg}`);
-  process.exit(1);
+  hardExit(1);
 }
 process.on("unhandledRejection", (reason) => fail(reason instanceof Error ? reason.message : String(reason)));
 process.on("uncaughtException", (err) => fail(err instanceof Error ? err.message : String(err)));