@mutmutco/cli 2.16.0 → 2.17.0

package/README.md

@@ -45,7 +45,7 @@ mmi-cli doctor --json
 - `mmi-cli board read|claim|show|move|done|backfill-priority` reads and moves GitHub Project work.
 - `mmi-cli tenant control <owner/repo> <stage> <status|start|stop|restart>` runs bounded dev/rc box control for project-admins through the Hub API; main remains master-only.
 - `mmi-cli stage`, `stage start`, `stage stop`, `stage run`, and `port-range <repo>` manage the local gitignored stage and its port block; `stage-live` explains that remote rc/live move only via `/rcand` · `/release` · `/hotfix`.
-- `mmi-cli rcand`, `release`, and `hotfix` render guarded train plans; the train triggers the Hub's central tenant deployer, so product repos carry no deploy file.
+- `mmi-cli rcand`, `release`, and `hotfix` render guarded train plans; product trains trigger the Hub's central tenant deployer, while MMI-Hub releases directly from `development` to `main`.
 - `mmi-cli bootstrap`, `bootstrap verify`, and `bootstrap apply` plan, audit, and seed repo onboarding.
 - `mmi-cli access audit` checks collaborator roles and train-branch allowlists.
 - `mmi-cli doctor` checks GitHub auth, repo config, CLI availability, plugin install/config/version state, and stale MMI plugin cache dirs, auto-repairing the safe gaps.

package/dist/index.cjs

@@ -5113,6 +5113,47 @@ function buildRemoteBranchCleanupReport(branch, input) {
   if (input.existsAfter === false) return { name: branch, status: "deleted" };
   return { name: branch, status: "not-attempted", reason: input.reason ?? "remote-check-unavailable" };
 }
+async function buildPrMergeRemoteBranchCleanupReport(branch, deps, input) {
+  const existsAfter = input.attempted ? await deps.exists(branch, { prune: true }) : void 0;
+  return buildRemoteBranchCleanupReport(branch, {
+    attempted: input.attempted,
+    existedBefore: input.existedBefore,
+    existsAfter,
+    reason: input.reason
+  });
+}
+function summarizePrMergeCleanupStatus(input) {
+  if (input.remoteBranch.status === "failed") return "warnings";
+  if (input.localBranch.status === "failed") return "warnings";
+  if (input.localBranch.reason === "worktree-removal-failed") return "warnings";
+  if (input.worktree?.status === "failed") return "warnings";
+  return "clean";
+}
+function buildPrMergeResultPayload(input) {
+  return {
+    mergeStatus: "merged",
+    merged: input.number,
+    branch: input.branch,
+    method: input.method,
+    cleanupStatus: summarizePrMergeCleanupStatus({
+      remoteBranch: input.remoteBranch,
+      localBranch: input.localCleanup.localBranch,
+      worktree: input.localCleanup.worktree
+    }),
+    remoteBranch: input.remoteBranch,
+    localBranch: input.localCleanup.localBranch,
+    worktree: input.localCleanup.worktree
+  };
+}
+async function checkRemoteBranchExists(branch, deps, options = {}) {
+  if (!branch) return void 0;
+  try {
+    if (options.prune) await deps.execGit(["fetch", "origin", "--prune"]).catch(() => void 0);
+    return (await deps.execGit(["ls-remote", "--heads", "origin", branch])).trim().length > 0;
+  } catch {
+    return void 0;
+  }
+}
 var DEFAULT_PROTECTED = /* @__PURE__ */ new Set(["development", "main", "master", "rc"]);
 function groupedPrs(prs) {
   const out = /* @__PURE__ */ new Map();
@@ -5314,7 +5355,7 @@ function branchMissingFromList(branch, stdout) {
   return !names.includes(branch);
 }
 function shellQuote(value) {
-  return `"${value.replace(/(["\\])/g, "\\$1")}"`;
+  return `'${value.replace(/'/g, "''")}'`;
 }
 function safeWorktreeRemoveCommand(safeCwd, targetPath) {
   const prefix = safeCwd ? `git -C ${shellQuote(safeCwd)}` : "git";
@@ -5340,7 +5381,11 @@ async function cleanupPrMergeLocalBranch(branch, options) {
   const wtPath = selectPrMergeCleanupWorktree(branch, beforeWorktrees, afterWorktrees, options.startingPath);
   const safeCwd = selectSafeWorktreeCwd([...afterWorktrees, ...beforeWorktrees], wtPath);
   const git = (args) => safeCwd ? options.execGit(["-C", safeCwd, ...args]) : options.execGit(args);
-  if (wtPath) {
+  const mainWorktreePath = beforeWorktrees[0]?.path ?? afterWorktrees[0]?.path;
+  const mainWorktreeTarget = Boolean(wtPath && mainWorktreePath && samePath(wtPath, mainWorktreePath));
+  if (wtPath && mainWorktreeTarget) {
+    report.worktree = { path: wtPath, status: "not-attempted", reason: "main-worktree" };
+  } else if (wtPath) {
     let stageTeardown;
     if (options.teardownWorktreeStage) {
       try {
@@ -5408,6 +5453,43 @@ function formatGcPlan(plan2, apply) {
 }
 
 // src/command-plans.ts
+function parseTrainTag(tag) {
+  const m = /^v(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?$/.exec(tag);
+  return m ? { major: +m[1], minor: +m[2], patch: +m[3], rc: m[4] ? +m[4] : null } : null;
+}
+function cmpTrainRelease(a, b) {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+function trainPlanTargetsFromTags(tags, explicitRaw) {
+  const all = tags.map(parseTrainTag).filter((v) => Boolean(v));
+  const release = all.find((v) => v.rc === null) ?? { major: 0, minor: 0, patch: 0, rc: null };
+  const targets = {};
+  let explicit = null;
+  if (explicitRaw) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(explicitRaw).trim());
+    if (!m) {
+      targets.plannedReleaseError = `MMI_RELEASE_VERSION must be X.Y.Z (got ${explicitRaw})`;
+    } else {
+      explicit = { major: +m[1], minor: +m[2], patch: +m[3], rc: null };
+      if (cmpTrainRelease(explicit, release) <= 0) {
+        targets.plannedReleaseError = `MMI_RELEASE_VERSION ${explicitRaw} must be ahead of the latest release v${release.major}.${release.minor}.${release.patch}`;
+      }
+    }
+  }
+  if (!targets.plannedReleaseError) {
+    const planned = explicit ?? { major: release.major, minor: release.minor + 1, patch: 0, rc: null };
+    targets.plannedRelease = `v${planned.major}.${planned.minor}.${planned.patch}`;
+  }
+  let rcs = all.filter((v) => v.rc !== null);
+  if (explicit) rcs = rcs.filter((v) => v.major === explicit.major && v.minor === explicit.minor && v.patch === explicit.patch);
+  rcs.sort((a, b) => cmpTrainRelease(b, a) || (b.rc ?? 0) - (a.rc ?? 0));
+  if (rcs[0]) {
+    targets.existingRcRelease = `v${rcs[0].major}.${rcs[0].minor}.${rcs[0].patch}`;
+  } else {
+    targets.existingRcReleaseError = explicit ? `no rc tag for ${explicit.major}.${explicit.minor}.${explicit.patch} to release` : "no rc tag to release";
+  }
+  return targets;
+}
 function stagePlan(stage2 = {}, stops = true) {
   return [
     ...stops ? [{ label: "force-kill previous local stage", command: "mmi-cli stage stop --apply" }] : [],
@@ -5436,20 +5518,49 @@ function stageLivePlan() {
     { label: "remote rc/live environments move through the gated promotion train", command: "mmi-cli rcand && mmi-cli release && mmi-cli hotfix", gated: true }
   ];
 }
-function trainPlan(command) {
+function rcandVersionStep(targets) {
+  const planned = targets.plannedRelease ? `plannedRelease=${targets.plannedRelease}` : "plannedRelease=(unresolved)";
+  const existing = targets.existingRcRelease ? `existingRcRelease=${targets.existingRcRelease}` : "existingRcRelease=(none resolved yet)";
+  return {
+    label: `resolve train version targets (${planned}; ${existing})`,
+    command: "plannedRelease: node scripts/next-version.mjs cycle; existing rc release only: node scripts/next-version.mjs release",
+    gated: true
+  };
+}
+function trainPlan(command, options = {}) {
+  const isHub = options.repo?.toLowerCase() === "mutmutco/mmi-hub";
   if (command === "rcand") {
+    if (isHub) {
+      return [
+        { label: "MMI-Hub releases skip rc; use /release from development instead", command: "mmi-cli release --apply", gated: true }
+      ];
+    }
     return [
       { label: "verify operator is a master-admin org owner", command: "gh api orgs/<owner>/memberships/<login> --jq .role", gated: true },
       { label: "verify current branch is development", gated: true },
+      rcandVersionStep(options),
       { label: "verify registry META for this project", command: "mmi-cli project get <owner/repo>", gated: true },
       { label: "preflight required rc secret names", command: "mmi-cli secrets preflight --stage rc --repo <owner/repo>", gated: true },
-      { label: "for Hub distribution changes, verify the release bump is already landed before touching rc", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view", gated: true },
+      { label: "for Hub distribution changes, verify the release bump is already landed before touching rc", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view; if missing: mmi-cli train prep --apply", gated: true },
       { label: "merge development to rc", gated: true },
-      { label: "trigger the deploy path for this repo model, returning the Hub Actions run id/url (and, with --watch, its outcome)", command: "tenant-container: gh workflow run tenant-deploy.yml ... then gh run list/watch; hub-serverless: no manual dispatch, deploy.yml auto-fires on rc push", gated: true },
+      { label: "trigger the deploy path for this repo model, returning Hub Actions run id/url data (and, with --watch, its outcome)", command: "tenant-container: gh workflow run tenant-deploy.yml ... then gh run list/watch; hub-serverless: no manual dispatch, deploy.yml auto-fires on rc push, correlate/watch that run", gated: true },
       { label: "after a failed deploy, retry the existing rc ref (no re-tag/merge)", command: "mmi-cli tenant redeploy <owner/repo> rc --watch", gated: true }
     ];
   }
   if (command === "release") {
+    if (isHub) {
+      return [
+        { label: "verify operator is a master-admin org owner", command: "gh api orgs/<owner>/memberships/<login> --jq .role", gated: true },
+        { label: "verify current branch is development", 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: "Hub releases skip rc; verify the distribution bump is already landed on development", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view", gated: true },
+        { label: "merge development to main", gated: true },
+        { label: "tag release and publish GitHub Release", gated: true },
+        { label: "trigger the Hub deploy path from the release event", command: "hub-serverless: deploy.yml + publish.yml auto-fire on the release", gated: true },
+        { label: "roll development forward", gated: true }
+      ];
+    }
     return [
       { label: "verify operator is a master-admin org owner", command: "gh api orgs/<owner>/memberships/<login> --jq .role", gated: true },
       { label: "verify current branch is rc", gated: true },
@@ -5457,9 +5568,9 @@ function trainPlan(command) {
       { 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: "for Hub distribution changes, verify the promoted SHA carries the release bump", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view; if missing: mmi-cli train prep --apply", gated: true },
       { label: "tag release and publish GitHub Release", gated: true },
-      { label: "trigger the deploy path for this repo model, returning the Hub Actions run id/url (and, with --watch, its outcome)", command: "tenant-container: gh workflow run tenant-deploy.yml ... then gh run list/watch; hub-serverless: no manual dispatch, deploy.yml + publish.yml auto-fire on the release", gated: true },
+      { label: "trigger the deploy path for this repo model, returning Hub Actions run id/url data (and, with --watch, its outcome)", command: "tenant-container: gh workflow run tenant-deploy.yml ... then gh run list/watch; hub-serverless: no manual dispatch, deploy.yml + publish.yml auto-fire on the release, correlate/watch those runs", gated: true },
       { label: "roll development forward", gated: true }
     ];
   }
@@ -5546,9 +5657,9 @@ function stalePosixFields(config, shell2) {
 }
 function sanitizeLocalStage(local, stale) {
   if (!stale.length) return local;
-  const clean3 = { ...local };
-  for (const field of stale) delete clean3[field];
-  return clean3;
+  const clean4 = { ...local };
+  for (const field of stale) delete clean4[field];
+  return clean4;
 }
 function staleNote(staleFields, outcome) {
   const list = staleFields.join(", ");
@@ -6338,6 +6449,30 @@ async function verifyHubDistributionVersion(deps, model, releaseTag) {
   if (model !== "hub-serverless") return;
   await deps.run("node", ["scripts/release-distribution.mjs", "verify", releaseTag, "--skip-npm-view"]);
 }
+async function verifyPublishedRelease(deps, repo, tag, expectedTarget, expectedSha) {
+  const out = await deps.run("gh", ["release", "view", tag, "--repo", repo, "--json", "tagName,targetCommitish"]);
+  let release;
+  try {
+    release = JSON.parse(out);
+  } catch {
+    throw new Error(`Release ${tag} metadata was not valid JSON`);
+  }
+  if (release.tagName !== tag) {
+    throw new Error(`Release metadata tag is ${String(release.tagName || "(missing)")}, expected ${tag}`);
+  }
+  if (release.targetCommitish !== expectedTarget) {
+    throw new Error(`Release ${tag} targetCommitish is ${String(release.targetCommitish || "(missing)")}, expected ${expectedTarget}`);
+  }
+  const tagSha = requireValue(clean(await deps.run("git", ["rev-parse", `${tag}^{commit}`])), "release tag sha");
+  if (tagSha !== expectedSha) {
+    throw new Error(`Release ${tag} tag points at ${tagSha}, expected ${expectedSha}`);
+  }
+  const branchOut = clean(await deps.run("git", ["ls-remote", "origin", `refs/heads/${expectedTarget}`]));
+  const branchSha = requireValue(branchOut.split(/\s+/)[0] ?? "", `origin/${expectedTarget} sha`);
+  if (branchSha !== expectedSha) {
+    throw new Error(`origin/${expectedTarget} points at ${branchSha}, expected ${expectedSha}`);
+  }
+}
 var ORG_SPINE_FILES = [
   "AGENTS.md",
   "CLAUDE.md",
@@ -6414,6 +6549,9 @@ async function requireBranch(deps, branch) {
   if (current !== branch) throw new Error(`must run from ${branch}, currently on ${current || "(unknown)"}`);
 }
 var HUB_REPO2 = "mutmutco/MMI-Hub";
+function isHubControlRepo(repo) {
+  return repo.toLowerCase() === HUB_REPO2.toLowerCase();
+}
 var CORRELATE_ATTEMPTS = 5;
 var CORRELATE_DELAY_MS = 1500;
 var CORRELATE_SKEW_SLACK_MS = 1e4;
@@ -6451,6 +6589,42 @@ async function correlateTenantRun(deps, since) {
   }
   return {};
 }
+async function correlateWorkflowRun(deps, args) {
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const threshold = args.since - CORRELATE_SKEW_SLACK_MS;
+  let lastError;
+  let parsedAnyResponse = false;
+  for (let attempt = 0; attempt < CORRELATE_ATTEMPTS; attempt++) {
+    if (attempt > 0) await sleep(CORRELATE_DELAY_MS);
+    const listArgs = [
+      "run",
+      "list",
+      "--repo",
+      HUB_REPO2,
+      "--workflow",
+      args.workflow,
+      "--event",
+      args.event,
+      ...args.branch ? ["--branch", args.branch] : [],
+      "--limit",
+      "10",
+      "--json",
+      "databaseId,url,event,createdAt,status,conclusion,headSha"
+    ];
+    let rows;
+    try {
+      rows = JSON.parse(await deps.run("gh", listArgs));
+      parsedAnyResponse = true;
+    } catch {
+      lastError = new Error(`could not list ${args.workflow} runs`);
+      continue;
+    }
+    const match = rows.filter((r) => r.event === args.event && r.headSha === args.headSha && typeof r.databaseId === "number").map((r) => ({ row: r, created: Date.parse(r.createdAt ?? "") })).filter((c) => Number.isFinite(c.created) && c.created >= threshold).sort((a, b) => b.created - a.created)[0];
+    if (match) return { runId: match.row.databaseId, runUrl: match.row.url };
+  }
+  if (!parsedAnyResponse && lastError) throw lastError;
+  return {};
+}
 async function watchTenantRun(deps, runId) {
   if (runId == null) return "pending";
   try {
@@ -6460,6 +6634,16 @@ async function watchTenantRun(deps, runId) {
     return "failure";
   }
 }
+async function watchWorkflowRun(deps, workflow, run) {
+  if (run.runId == null) return { workflow, conclusion: "pending" };
+  const conclusion = await watchTenantRun(deps, run.runId);
+  return { workflow, runId: run.runId, runUrl: run.runUrl, conclusion };
+}
+function aggregateWorkflowRuns(runs) {
+  if (runs.some((r) => r.conclusion === "failure")) return "failure";
+  if (runs.some((r) => r.conclusion === "pending")) return "pending";
+  return "success";
+}
 function isNotFoundError(e) {
   const msg = `${e.message ?? e} ${String(e.stderr ?? "")}`;
   return /HTTP 404|Not Found|\(404\)/i.test(msg);
@@ -6578,7 +6762,7 @@ async function resolveRcResumeTag(deps, base, sha) {
   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) {
+async function dispatchDeploy(deps, ctx, stage2, ref, model, watch, autoRunSince, autoRunHeadSha) {
   if (model === "tenant-container") {
     const since = (deps.now ?? Date.now)();
     await deps.run("gh", [
@@ -6601,9 +6785,30 @@ async function dispatchDeploy(deps, ctx, stage2, ref, model, watch) {
     return { note: `dispatched tenant-deploy.yml (slug=${ctx.slug}, ref=${ref}, stage=${stage2})`, runId, runUrl, deployStatus };
   }
   if (model === "hub-serverless") {
+    const note = ref === "rc" ? "no manual dispatch: deploy.yml auto-fires on the rc push (rc stage)" : "no manual dispatch: deploy.yml + publish.yml auto-fire on the published Release (prod)";
+    if (!watch) return { note, deployStatus: "pending" };
+    if (!autoRunHeadSha) return { note, deployStatus: "pending" };
+    const since = autoRunSince ?? (deps.now ?? Date.now)();
+    const targets = ref === "rc" ? [{ workflow: "deploy.yml", event: "push", branch: "rc" }] : [
+      { workflow: "deploy.yml", event: "release" },
+      { workflow: "publish.yml", event: "release" }
+    ];
+    const workflowRuns = [];
+    for (const target of targets) {
+      try {
+        const run = await correlateWorkflowRun(deps, { ...target, since, headSha: autoRunHeadSha });
+        workflowRuns.push(await watchWorkflowRun(deps, target.workflow, run));
+      } catch {
+        workflowRuns.push({ workflow: target.workflow, conclusion: "failure" });
+      }
+    }
+    const primary = workflowRuns[0];
     return {
-      note: ref === "rc" ? "no manual dispatch: deploy.yml auto-fires on the rc push (rc stage)" : "no manual dispatch: deploy.yml + publish.yml auto-fire on the published Release (prod)",
-      deployStatus: "pending"
+      note,
+      runId: primary?.runId,
+      runUrl: primary?.runUrl,
+      workflowRuns,
+      deployStatus: aggregateWorkflowRuns(workflowRuns)
     };
   }
   return { note: `no manual dispatch: ${model} repo deploys via its own push-triggered workflow`, deployStatus: "pending" };
@@ -6638,6 +6843,9 @@ async function runTrainApply(command, deps, options = {}) {
       "nothing to promote: origin/development is not ahead of origin/rc"
     );
     const deployModel2 = await preflight(deps, ctx, "rc");
+    if (isHubControlRepo(ctx.repo) && deployModel2 === "hub-serverless") {
+      throw new Error("MMI-Hub releases directly from development to main; run mmi-cli release --apply from development instead of rcand");
+    }
     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"]);
@@ -6650,9 +6858,70 @@ async function runTrainApply(command, deps, options = {}) {
     await ensureTagPushed(deps, tag2, rcSha);
     const requiredChecks2 = await discoverRequiredCheckContexts(deps, ctx, "rc");
     const checks2 = await waitForRequiredTrainChecks(deps, ctx, rcSha, requiredChecks2);
+    const autoRunSince2 = (deps.now ?? Date.now)();
     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, checks: checks2, resumeNote, dispatch: d2.note, runId: d2.runId, runUrl: d2.runUrl, deployStatus: d2.deployStatus };
+    const d2 = await dispatchDeploy(deps, ctx, "rc", "rc", deployModel2, watch, autoRunSince2, rcSha);
+    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, workflowRuns: d2.workflowRuns, deployStatus: d2.deployStatus };
+  }
+  if (isHubControlRepo(ctx.repo)) {
+    await requireBranch(deps, "development");
+    await deps.run("git", ["pull", "--ff-only", "origin", "development"]);
+    ensurePositiveCount(
+      await deps.run("git", ["rev-list", "--count", "origin/main..origin/development"]),
+      "nothing to release: origin/development is not ahead of origin/main"
+    );
+    const deployModel2 = await preflight(deps, ctx, "main");
+    if (deployModel2 !== "hub-serverless") {
+      throw new Error(`MMI-Hub direct release requires deployModel=hub-serverless, got ${deployModel2}`);
+    }
+    const tag2 = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "cycle"])), "release tag");
+    await verifyHubDistributionVersion(deps, deployModel2, tag2);
+    const predicted2 = await predictMergeConflicts(deps, "origin/main", "origin/development");
+    const predictedNonSpine2 = predicted2.filter((f) => !isSpinePath(f));
+    if (predictedNonSpine2.length > 0) {
+      throw new Error(
+        `development -> main merge would conflict on non-spine path(s): ${predictedNonSpine2.join(", ")} \u2014 no merge was started. The train is misaligned: reconcile main and development via an approved alignment PR, then rerun release.`
+      );
+    }
+    await deps.run("git", ["checkout", "main"]);
+    await deps.run("git", ["pull", "--ff-only", "origin", "main"]);
+    if (predicted2.length === 0) {
+      await deps.run("git", ["merge", "development", "--no-edit"]);
+    } else {
+      await mergeWithSpineResolution(deps, "development", "development -> main", "theirs");
+    }
+    const releaseSha2 = requireValue(clean(await deps.run("git", ["rev-parse", "main"])), "release sha");
+    await ensureTagPushed(deps, tag2, releaseSha2);
+    const requiredChecks2 = await discoverRequiredCheckContexts(deps, ctx, "main");
+    const checks2 = await waitForRequiredTrainChecks(deps, ctx, releaseSha2, requiredChecks2);
+    await deps.run("git", ["push", "origin", "main"]);
+    const releaseUrl2 = clean(await deps.run("gh", ["release", "create", tag2, "--generate-notes", "--latest", "--repo", ctx.repo])) || void 0;
+    const announceNote2 = deps.announce ? (await deps.announce({ repo: ctx.repo, tag: tag2, summaryFile: options.announceSummaryFile })).note : void 0;
+    const autoRunSince2 = (deps.now ?? Date.now)();
+    const d2 = await dispatchDeploy(deps, ctx, "main", "main", deployModel2, watch, autoRunSince2, releaseSha2);
+    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"]);
+    return {
+      ...ctx,
+      command,
+      stage: "main",
+      ref: "main",
+      tag: tag2,
+      deployModel: deployModel2,
+      promoted: true,
+      checks: checks2,
+      dispatch: d2.note,
+      runId: d2.runId,
+      runUrl: d2.runUrl,
+      workflowRuns: d2.workflowRuns,
+      deployStatus: d2.deployStatus,
+      rcRetirement: "not-applicable",
+      rcRetirementNote: "Hub releases skip rc; no rc runtime to retire",
+      announceNote: announceNote2,
+      release: { tag: tag2, url: releaseUrl2, targetSha: releaseSha2 }
+    };
   }
   await requireBranch(deps, "rc");
   ensurePositiveCount(
@@ -6682,9 +6951,11 @@ async function runTrainApply(command, deps, options = {}) {
   const requiredChecks = await discoverRequiredCheckContexts(deps, ctx, "main");
   const checks = await waitForRequiredTrainChecks(deps, ctx, releaseSha, requiredChecks);
   await deps.run("git", ["push", "origin", "main"]);
-  const releaseUrl = clean(await deps.run("gh", ["release", "create", tag, "--generate-notes", "--latest", "--repo", ctx.repo])) || void 0;
+  const autoRunSince = (deps.now ?? Date.now)();
+  const releaseUrl = clean(await deps.run("gh", ["release", "create", tag, "--target", "main", "--generate-notes", "--latest", "--repo", ctx.repo])) || void 0;
+  await verifyPublishedRelease(deps, ctx.repo, tag, "main", releaseSha);
   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 d = await dispatchDeploy(deps, ctx, "main", "main", deployModel, watch, autoRunSince, releaseSha);
   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"]);
@@ -6703,6 +6974,7 @@ async function runTrainApply(command, deps, options = {}) {
     dispatch: d.note,
     runId: d.runId,
     runUrl: d.runUrl,
+    workflowRuns: d.workflowRuns,
     deployStatus: d.deployStatus,
     rcRetirement: retirement.status,
     rcRetirementNote: retirement.note,
@@ -6814,14 +7086,42 @@ async function runTenantRedeploy(deps, options) {
     throw new Error(`${repo} is ${deployModel}, not tenant-container \u2014 there is no central tenant-deploy run to retry (its deploy fires from its own workflow)`);
   }
   const d = await dispatchDeploy(deps, ctx, stage2, ref, deployModel, watch);
-  return { ...ctx, command: "tenant-redeploy", stage: stage2, ref, deployModel, dispatch: d.note, runId: d.runId, runUrl: d.runUrl, deployStatus: d.deployStatus };
+  return { ...ctx, command: "tenant-redeploy", stage: stage2, ref, deployModel, dispatch: d.note, runId: d.runId, runUrl: d.runUrl, workflowRuns: d.workflowRuns, deployStatus: d.deployStatus };
+}
+
+// src/train-prep.ts
+function clean2(text) {
+  return text.trim();
+}
+function normalizeVersion2(target) {
+  const version = target.replace(/^v/, "");
+  if (!/^\d+\.\d+\.\d+$/.test(version)) {
+    throw new Error(`invalid train prep target ${target || "(empty)"}`);
+  }
+  return version;
+}
+function parseChangedFiles(out) {
+  return out.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+async function runTrainPrep(deps, options = {}) {
+  const target = clean2(await deps.run("node", ["scripts/next-version.mjs", "cycle"]));
+  const version = normalizeVersion2(target);
+  if (!options.apply) {
+    return { target, version, applied: false, command: "mmi-cli train prep --apply", stagedFiles: [] };
+  }
+  await deps.run("node", ["scripts/release-distribution.mjs", "prepare", target]);
+  const stagedFiles = parseChangedFiles(await deps.run("node", ["scripts/release-distribution.mjs", "changed-files"]));
+  if (stagedFiles.length === 0) throw new Error("no locked distribution files returned by release-distribution changed-files");
+  await deps.run("git", ["add", "--", ...stagedFiles]);
+  await deps.run("node", ["scripts/release-distribution.mjs", "verify", target, "--skip-npm-view"]);
+  return { target, version, applied: true, command: "mmi-cli pr create --base development --head <current-branch>", stagedFiles };
 }
 
 // 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) {
+function clean3(out) {
   return out.trim();
 }
 function sleeper(deps) {
@@ -6875,7 +7175,7 @@ async function resolveHotfixSource(deps, ctx, from) {
     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}`]));
+  const sha = clean3(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) };
 }
@@ -6902,7 +7202,7 @@ async function runHotfixStart(deps, options) {
     };
   }
   const { sha, label } = await resolveHotfixSource(deps, ctx, options.from);
-  const remoteBranch = clean2(await deps.run("git", ["ls-remote", "origin", `refs/heads/${branch}`]));
+  const remoteBranch = clean3(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]);
@@ -6928,7 +7228,7 @@ async function runHotfixStart(deps, options) {
     }
     await deps.run("git", ["push", "-u", "origin", branch]);
   }
-  const prUrl = clean2(await deps.run("gh", [
+  const prUrl = clean3(await deps.run("gh", [
     "pr",
     "create",
     "--repo",
@@ -7011,7 +7311,7 @@ async function runHotfixRelease(deps, versionInput, options = {}) {
   if (releaseExists) {
     releaseNote = `Release ${tag} already exists \u2014 resumed without recreating`;
   } else {
-    const tagCommit = clean2(await deps.run("git", ["rev-parse", `${tag}^{commit}`]));
+    const tagCommit = clean3(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) {
@@ -7022,7 +7322,7 @@ async function runHotfixRelease(deps, versionInput, options = {}) {
   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"]));
+  const previousRef = clean3(await deps.run("git", ["rev-parse", "--abbrev-ref", "HEAD"]));
   let verifyNote;
   const publishSucceeded = runs.find((r) => r.workflow === "publish.yml")?.conclusion === "success";
   try {
@@ -7090,9 +7390,9 @@ async function runHotfixStatus(deps, versionInput) {
   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 branchExists = Boolean(clean3(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 remoteTag = clean3(await deps.run("git", ["ls-remote", "origin", `refs/tags/${tag}`]));
   const tagPushed = Boolean(remoteTag);
   const tagSha = remoteTag.split(/\s+/)[0] || "";
   let releaseExists = false;
@@ -7126,7 +7426,7 @@ async function gatherHotfixFacts(deps, ctx, tag, version) {
       }
     }
   }
-  const npmVersion = await deps.run("npm", ["view", "@mutmutco/cli", "version", "--silent"]).then(clean2, () => "unknown");
+  const npmVersion = await deps.run("npm", ["view", "@mutmutco/cli", "version", "--silent"]).then(clean3, () => "unknown");
   const devVersion = await deps.run("git", ["show", "origin/development:cli/package.json"]).then(
     (out) => {
       try {
@@ -8697,8 +8997,8 @@ function resolveKbSource(rawBase) {
   return { owner: m[1], repo: m[2], ref: m[3] };
 }
 function buildKbGetArgs(src, path2) {
-  const clean3 = path2.replace(/^\/+/, "");
-  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean3}?ref=${src.ref}`, "-H", "Accept: application/vnd.github.raw"];
+  const clean4 = path2.replace(/^\/+/, "");
+  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean4}?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`];
@@ -10832,14 +11132,10 @@ pr.command("create").description("create a PR and print {number,url} JSON").requ
   const created = await ghCreate(buildPrArgs({ title: o.title, body, base: o.base, head: o.head, repo: o.repo }));
   console.log(JSON.stringify(created));
 });
-async function remoteBranchExists(branch) {
-  if (!branch) return void 0;
-  try {
-    const { stdout } = await execFileP4("git", ["ls-remote", "--heads", "origin", branch], { timeout: GIT_TIMEOUT_MS });
-    return stdout.trim().length > 0;
-  } catch {
-    return void 0;
-  }
+async function remoteBranchExists(branch, options = {}) {
+  return checkRemoteBranchExists(branch, {
+    execGit: async (args) => (await execFileP4("git", args, { timeout: GIT_TIMEOUT_MS })).stdout
+  }, options);
 }
 var COMPOSE_TIMEOUT_MS = 12e4;
 function teardownWorktreeStage(worktreePath) {
@@ -10877,11 +11173,14 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
     if (!/used by worktree|cannot delete branch/i.test(message)) throw e;
   });
   if (!remoteNotAttemptedReason) remoteDeleteAttempted = true;
-  const remoteAfter = repoArgs.length ? void 0 : await remoteBranchExists(headRef);
-  const remoteBranch = buildRemoteBranchCleanupReport(headRef, {
+  const remoteBranch = repoArgs.length ? buildRemoteBranchCleanupReport(headRef, {
+    attempted: false,
+    reason: remoteNotAttemptedReason
+  }) : await buildPrMergeRemoteBranchCleanupReport(headRef, {
+    exists: remoteBranchExists
+  }, {
     attempted: remoteDeleteAttempted,
     existedBefore: remoteBefore,
-    existsAfter: remoteAfter,
     reason: remoteNotAttemptedReason
   });
   const localCleanup = repoArgs.length ? {
@@ -10894,14 +11193,13 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
     execGit: async (args) => (await execFileP4("git", args, { timeout: GIT_TIMEOUT_MS })).stdout,
     teardownWorktreeStage
   });
-  console.log(JSON.stringify({
-    merged: number,
+  console.log(JSON.stringify(buildPrMergeResultPayload({
+    number,
     branch: headRef,
     method: method.slice(2),
     remoteBranch,
-    localBranch: localCleanup.localBranch,
-    worktree: localCleanup.worktree
-  }));
+    localCleanup
+  })));
 });
 async function runBoardRead(o) {
   try {
@@ -11218,9 +11516,22 @@ function trainApplyDeps() {
     }
   };
 }
+function trainPrepDeps() {
+  return {
+    run: async (file, args) => {
+      const timeout = file === "node" && args[1] === "prepare" ? NODE_PREPARE_TIMEOUT_MS : GIT_TIMEOUT_MS;
+      return (await execFileP4(file, args, { timeout })).stdout;
+    }
+  };
+}
+function formatWorkflowRun(r) {
+  const ref = r.runUrl ?? (r.runId != null ? String(r.runId) : "unresolved");
+  return `${r.workflow} ${ref} ${r.conclusion.toUpperCase()}`;
+}
 function renderDeployLine(d) {
   const parts = [d.dispatch];
-  if (d.runUrl) parts.push(`run ${d.runUrl}`);
+  if (d.workflowRuns?.length) parts.push(`runs: ${d.workflowRuns.map(formatWorkflowRun).join(", ")}`);
+  else if (d.runUrl) parts.push(`run ${d.runUrl}`);
   if (d.deployStatus === "success") parts.push("deploy: SUCCEEDED");
   else if (d.deployStatus === "failure") parts.push("deploy: FAILED (promotion stands; retry the deploy, do not re-tag)");
   else if (d.runId != null) parts.push(`deploy: dispatched (watch: gh run watch ${d.runId} --repo mutmutco/MMI-Hub --exit-status)`);
@@ -11235,8 +11546,37 @@ function renderTrainApply(commandName, r) {
 function renderTenantRedeploy(r) {
   return `mmi-cli tenant redeploy: ${r.repo} ${r.stage} (ref=${r.ref}) [${r.deployModel}]; ${renderDeployLine(r)}`;
 }
+async function resolveRcandPlanTargets() {
+  try {
+    const tags = (await execFileP4("git", ["tag", "--list", "v*", "--sort=-v:refname"], { timeout: 1e4 })).stdout.trim().split("\n").filter(Boolean);
+    return trainPlanTargetsFromTags(tags, process.env.MMI_RELEASE_VERSION);
+  } catch (e) {
+    return { plannedReleaseError: e.message, existingRcReleaseError: e.message };
+  }
+}
+function renderTrainPrep(r) {
+  if (!r.applied) {
+    return `mmi-cli train prep: target ${r.target}; run ${r.command} to prepare and stage locked distribution files`;
+  }
+  return [
+    `mmi-cli train prep: prepared ${r.target}`,
+    `  - staged locked files: ${r.stagedFiles.join(", ")}`,
+    "  - stopped before promotion; no push, merge, tag, release, or deploy was run",
+    `  - next: ${r.command}`
+  ].join("\n");
+}
+var trainCmd = program2.command("train").description("release train helpers that stop before promotion");
+trainCmd.command("prep").description("prepare and stage the Hub distribution bump for the next release train").option("--json", "machine-readable output").option("--apply", "run release-distribution prepare, exact-file stage, verify, then stop").action(async (o) => {
+  try {
+    await requireFreshTrainCli("train prep");
+    const result = await runTrainPrep(trainPrepDeps(), { apply: o.apply });
+    printLine(o.json ? JSON.stringify(result, null, 2) : renderTrainPrep(result));
+  } catch (e) {
+    fail(`train prep: ${e.message}`);
+  }
+});
 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) => {
+  program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--watch", "block on the deploy/publish workflow runs and report their outcomes").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) {
@@ -11250,8 +11590,12 @@ for (const commandName of ["rcand", "release"]) {
         return fail(`${commandName}: ${e.message}`);
       }
     }
-    const steps = trainPlan(commandName);
-    console.log(o.json ? JSON.stringify({ command: commandName, steps }, null, 2) : renderSteps(`mmi-cli ${commandName}: dry-run plan`, steps));
+    const repo = await resolveRepo();
+    const targets = commandName === "rcand" ? await resolveRcandPlanTargets() : void 0;
+    const steps = trainPlan(commandName, { ...targets ?? {}, repo });
+    console.log(
+      o.json ? JSON.stringify({ command: commandName, ...targets ?? {}, repo, steps }, null, 2) : renderSteps(`mmi-cli ${commandName}: dry-run plan`, steps)
+    );
   });
 }
 function renderHotfixStart(r) {

package/package.json

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