@mutmutco/cli 4.3.50 → 4.3.52

package/dist/main.cjs

@@ -14756,7 +14756,7 @@ function deriveTrainFollowUpStatus(f) {
   return worst === "failure" ? "failed" : worst === "unresolved" ? "pending" : "complete";
 }
 function trainFollowUpExitCode(status) {
-  return status === "failed" ? 1 : status === "pending" ? 2 : 0;
+  return status === "failed" ? 1 : 0;
 }
 function trainFollowUpNote(status) {
   if (status === "complete") return void 0;
@@ -15858,10 +15858,10 @@ var rollout_plan_default = {
     note: "The v4.0.0 stamp happens at cut time (D6e #4463); until then the candidate is the origin/development head artifacts (built cli/dist + npm pack), identity proven by dist content hash (D6a)."
   },
   baseline: {
-    version: "4.3.50",
-    tag: "v4.3.50",
-    commit: "d24d7fd0aaca",
-    npm: "@mutmutco/cli@4.3.50"
+    version: "4.3.52",
+    tag: "v4.3.52",
+    commit: "6219f52caf87",
+    npm: "@mutmutco/cli@4.3.52"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15878,14 +15878,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.50"
+          v3Target: "v4.3.52"
         }
       ],
       rollbackTrigger: "Any red inside the post-contract soak window: `devops train gate` FAIL attributable to the v4 doors, Hub endpoint health probe failure, a pre-v4 client admitted instead of receiving actionable HTTP 426, or npm consumer install/doctor failure on the v4-only dist.",
       rollback: {
         independent: true,
-        mechanism: "npm dist-tag latest -> 4.3.50 and redeploy the Hub Lambda from tag v4.3.50 (d24d7fd0aaca); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.50 (@mutmutco/cli@4.3.50, tag commit d24d7fd0aaca \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.52 and redeploy the Hub Lambda from tag v4.3.52 (6219f52caf87); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.52 (@mutmutco/cli@4.3.52, tag commit 6219f52caf87 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -20543,6 +20543,9 @@ function validatePhaseRecord(phase, raw) {
       throw new ReleaseLedgerError("invalid-record", `release ledger: phase ${phase} has a malformed ${key}`);
     }
   }
+  if (rec.superseded !== void 0 && typeof rec.superseded !== "boolean") {
+    throw new ReleaseLedgerError("invalid-record", `release ledger: phase ${phase} has a malformed superseded marker`);
+  }
   if (rec.retries !== void 0 && (typeof rec.retries !== "number" || !Number.isSafeInteger(rec.retries) || rec.retries < 0 || rec.retries > 9)) {
     throw new ReleaseLedgerError("invalid-record", `release ledger: phase ${phase} has a malformed retries value`);
   }
@@ -21429,6 +21432,69 @@ async function healStaleAlignmentLeg(deps, cwd, expected) {
     return prior.tag;
   });
 }
+function supersedeableDeployLegShape(rec) {
+  return rec.state === "failed" || rec.state === "pending" && rec.runId == null;
+}
+async function supersedeContentCausedDeployLeg(deps, cwd) {
+  const path2 = releaseLedgerPath(cwd);
+  return withFileLock(`${path2}.lock`, { label: "release ledger" }, async () => {
+    let prior;
+    try {
+      prior = parseReleaseLedger((0, import_node_fs21.readFileSync)(path2, "utf8"));
+    } catch (e) {
+      throw new ReleaseLedgerError(
+        "unreadable",
+        `release --supersede-deploy: the active release ledger at ${path2} could not be read (${e instanceof Error ? e.message : String(e)}) \u2014 resolve it by hand before any train; nothing was written (#6553)`
+      );
+    }
+    if (prior.phases.deploy.superseded === true) {
+      throw new Error(`release --supersede-deploy: the ${prior.tag} deploy leg is already superseded \u2014 nothing to do; the next train runs normally`);
+    }
+    if (!supersedeableDeployLegShape(prior.phases.deploy)) {
+      throw new Error(
+        `release --supersede-deploy: the ${prior.tag} deploy leg is ${prior.phases.deploy.state}` + (prior.phases.deploy.runId != null ? ` with run ${prior.phases.deploy.runId} \u2014 a run-backed leg is resolved by watching/reverifying its run, never superseded` : "") + "; the supersession closes only a FAILED deploy leg, or a PENDING one no run correlates (the uncorrelatable historical shape); nothing was written (#6553)"
+      );
+    }
+    const phases = { ...prior.phases };
+    if (phases.alignment.state === "pending") {
+      const closed = await alignmentLegClosedLive(deps, prior);
+      if (closed) phases.alignment = closed;
+    }
+    const unresolved = ["promotion", "ordinaryCi", "githubRelease", "publish", "alignment"].filter((phase) => phases[phase].state === "pending" || phases[phase].state === "failed");
+    if (unresolved.length > 0) {
+      throw new Error(
+        `release --supersede-deploy: ${prior.tag} has unresolved legs besides deploy (${unresolved.map((p) => `${p}=${phases[p].state}`).join(", ")}) \u2014 the supersession closes only the deploy leg of an otherwise-complete release; resolve those first, nothing was written (#6553)`
+      );
+    }
+    let liveSha = "";
+    try {
+      liveSha = (await deps.run("git", ["ls-remote", "origin", `refs/tags/${prior.tag}`])).trim().split(/\s+/)[0] ?? "";
+    } catch (e) {
+      throw new Error(`release --supersede-deploy: could not prove ${prior.tag} live on origin (${e instanceof Error ? e.message : String(e)}) \u2014 refusing to close the leg on an unproven state; retry when origin answers (#6553)`);
+    }
+    if (liveSha.toLowerCase() !== prior.tagSha.toLowerCase()) {
+      throw new Error(
+        `release --supersede-deploy: origin reports ${prior.tag} at ${liveSha.slice(0, 12) || "no tag"} but the ledger anchors ${prior.tagSha.slice(0, 12)} \u2014 an absent or divergent release is NOT supersedeable (release --abort --apply is the unpublished candidate's own exit); nothing was written (#6553)`
+      );
+    }
+    const note = `superseded: content-caused deploy failure on the immutable promoted ${prior.tag} \u2014 the cause fix rides the next patch train (master-approved closure, #6553)`;
+    atomicWriteJson(path2, {
+      ...prior,
+      phases: {
+        ...phases,
+        deploy: { state: "skipped", sha: prior.tagSha, superseded: true, note, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }
+      },
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return {
+      command: "release-supersede-deploy",
+      repo: prior.repo,
+      tag: prior.tag,
+      tagSha: prior.tagSha,
+      note: `closed the ${prior.tag} deploy leg as superseded (skipped) \u2014 the ledger is phases-green; rerun the train doctor to confirm, then run the next patch train (hotfix or release) to carry the cause fix`
+    };
+  });
+}
 async function reverifyPriorRunLegs(deps, path2, targetTag) {
   let prior;
   try {
@@ -21895,10 +21961,12 @@ async function runTrainDoctor(input) {
     ledgerTag = void 0;
   }
   let remoteTags;
+  let newestRemoteReleaseTag;
   try {
     remoteTags = tagNames(await runGitRemoteRead(train, ["ls-remote", "--tags", "origin", "refs/tags/v*"]));
     const releaseTags = await listRemoteReleaseTags(train);
     const latest = releaseTags[releaseTags.length - 1];
+    newestRemoteReleaseTag = latest;
     if (latest) {
       const remoteSha = await probeRemoteTag(train, latest);
       if (remoteSha && await isStrayUnreleasedTag(train, latest, remoteSha, repo)) {
@@ -22007,8 +22075,11 @@ async function runTrainDoctor(input) {
         }
       }
       if (derived.phaseStatus !== "phases-green") {
-        const open2 = derived.legs.filter((l) => l.state === "pending" || l.state === "failed").map((l) => `${l.phase}=${l.state}`).join(", ");
+        const openLegs = derived.legs.filter((l) => l.state === "pending" || l.state === "failed");
+        const open2 = openLegs.map((l) => `${l.phase}=${l.state}`).join(", ");
         const failed = derived.phaseStatus === "phases-failed";
+        const deployOnlyDeadlock = openLegs.length > 0 && openLegs.every((l) => l.phase === "deploy" && supersedeableDeployLegShape(l));
+        const supersession = deployOnlyDeadlock ? `; when the deploy failure is content-caused on the already-published ${ledger.tag} (the immutable tag can never deploy green), the sanctioned exit is \`mmi-cli devops release --supersede-deploy --apply\` after explicit master approval \u2014 the next patch train carries the cause fix (#6553)` : "";
         add({
           code: failed ? "ledger-failed" : "ledger-pending",
           severity: "blocker",
@@ -22016,7 +22087,15 @@ async function runTrainDoctor(input) {
           // #6429: each lane finishes its own run (#6068) — an rcand-lane ledger named as a release
           // ledger, with `release --resume` as its remedy, sends the operator to a verb that refuses it.
           title: `a prior ${ledger.lane ?? "release"} ledger for ${ledger.tag} is ${derived.phaseStatus} (${open2}) \u2014 a new train must not stack on it (#5987)`,
-          remedy: failed ? `diagnose the failed leg, then ${ledgerLaneResumeCommand(ledger)} once its cause is fixed (an abort only with fresh approval)` : `finish it first: ${ledgerLaneResumeCommand(ledger)} (alignment-only pending legs close themselves with \`train doctor --heal\` once the PR merges)`
+          remedy: failed ? `diagnose the failed leg, then ${ledgerLaneResumeCommand(ledger)} once its cause is fixed (an abort only with fresh approval)${supersession}` : `finish it first: ${ledgerLaneResumeCommand(ledger)} (alignment-only pending legs close themselves with \`train doctor --heal\` once the PR merges)${supersession}`
+        });
+      } else if (newestRemoteReleaseTag && newestRemoteReleaseTag !== ledger.tag) {
+        add({
+          code: "ledger-stale",
+          severity: "info",
+          source: "origin",
+          title: `the active ledger describes the PRIOR release ${ledger.tag} \u2014 origin's newest release tag is ${newestRemoteReleaseTag}`,
+          remedy: "nothing \u2014 the next train live-proves and archives it aside; never cite a prior-release ledger or its runs as the current release's deploy state \u2014 a clearance cites runs proven to belong to the active tag"
         });
       }
     } catch (e) {
@@ -23185,7 +23264,9 @@ Nothing was written. Inspect ${ledger.path} (or clear it only after proving the
     });
     if (persisted) {
       const phaseInputs = phaseInputsFromRunRows(deployModel, dispatch2.workflowRuns ?? historicalRows, tagSha, { repo: ctx.repo });
-      await recordPhase(ledger, deps, anchors, "deploy", phaseEntry(phaseInputs.deploy), { strict: true, landed: "the verified GitHub Release and origin/main at the immutable tag SHA" });
+      if (persisted.phases.deploy.superseded !== true) {
+        await recordPhase(ledger, deps, anchors, "deploy", phaseEntry(phaseInputs.deploy), { strict: true, landed: "the verified GitHub Release and origin/main at the immutable tag SHA" });
+      }
       await recordPhase(ledger, deps, anchors, "publish", phaseEntry(phaseInputs.publish), { strict: true, landed: "the verified GitHub Release and origin/main at the immutable tag SHA" });
       await recordPhase(ledger, deps, anchors, "githubRelease", phaseEntry({ state: "complete", sha: tagSha, note: "re-verified live: the GitHub Release exists at the immutable tag SHA" }), { strict: true, landed: "the promotion (verified live)" });
       await recordPhase(ledger, deps, anchors, "promotion", phaseEntry({ state: "complete", sha: tagSha, note: "re-verified live: origin/main contains the immutable tag SHA" }), { strict: true, landed: "nothing beyond the already-public release" });
@@ -23437,6 +23518,17 @@ async function runReleaseAbort(deps, options = {}) {
     note: `removed the unpublished ${tag} candidate and restored local main; repair development before recutting` + (clearedLedgerNote ? `; ${clearedLedgerNote}` : "")
   };
 }
+async function runReleaseSupersedeDeploy(deps, options = {}) {
+  if (!options.approved) {
+    throw new Error("release --supersede-deploy requires --apply after explicit master approval; nothing was written");
+  }
+  try {
+    return await supersedeContentCausedDeployLeg(deps, process.cwd());
+  } catch (e) {
+    const message2 = e instanceof Error ? e.message : String(e);
+    throw new Error(message2.includes("nothing was written") || message2.includes("nothing to do") ? message2 : `${message2}; nothing was written`);
+  }
+}
 async function runReleasePublishRetry(deps, runId, options = {}) {
   if (!options.approved) {
     throw new Error("release --retry-publish requires --apply after explicit approval; nothing was written");
@@ -43888,7 +43980,7 @@ function readRepoVersion() {
 }
 function registerTrainCommands(program3, trainDeps) {
   const train = program3.command("train").description("release-train observability \u2014 track position, version lag, and the shared preflight-and-heal doctor (#2688, #6067)");
-  train.command("doctor").description("one shared preflight-and-heal verdict for the release, rcand and hotfix lanes; read-only unless --heal (#6067)").addOption(new Option("--lane <lane>", "train lane to check (defaults from the release track: direct \u2192 release)").choices([...TRAIN_LANES])).option("--dev", "judge the `release --dev` lane (development -> main, skipping rc): the lane starts from development and is read on development's workflows (#6318)").option("--heal", "repair safe local reconstructible state (scratch gitignore, churn, stray local tags, ff-only branch lag, finished scratch branches, stale alignment ledger leg); it never clears a ledger-pending, ledger-failed or branch-mismatch blocker (#6404, #6401, #6399) \u2014 those need `mmi-cli devops release --resume` (or, with fresh approval, `--abort --apply`) and `git checkout <start branch>`, so exit 1 after --heal is the gate working, not a failed heal").option("--repo <owner/repo>", "target repo (defaults to the current checkout)").option("--json", "machine-readable output").addHelpText("after", "\nExit codes:\n  0  ready \u2014 no blocker and origin verified\n  1  a blocker remains, or origin could not be verified (never green on an unread origin)\n\nEvery finding carries code, severity (blocker|warning|healed|info), source (local|origin), remedy and a\ndocs/Guides/train-troubleshooting.md#<code> anchor. `release --apply` and `rcand --apply` run this at step 0 with --heal.\n").action(async (o) => {
+  train.command("doctor").description("one shared preflight-and-heal verdict for the release, rcand and hotfix lanes; read-only unless --heal (#6067)").addOption(new Option("--lane <lane>", "train lane to check (defaults from the release track: direct \u2192 release)").choices([...TRAIN_LANES])).option("--dev", "judge the `release --dev` lane (development -> main, skipping rc): the lane starts from development and is read on development's workflows (#6318)").option("--heal", "repair safe local reconstructible state (scratch gitignore, churn, stray local tags, ff-only branch lag, finished scratch branches, stale alignment ledger leg); it never clears a ledger-pending, ledger-failed or branch-mismatch blocker (#6404, #6401, #6399) \u2014 those need `mmi-cli devops release --resume` (or, with fresh approval, `--abort --apply`) and `git checkout <start branch>`, so exit 1 after --heal is the gate working, not a failed heal").option("--repo <owner/repo>", "target repo (defaults to the current checkout)").option("--json", "machine-readable output").option("--out <path>", "write the verdict to this file as UTF-8 (no BOM) instead of stdout \u2014 the shell-free receipt path (#5802/#6563); pair with --json for a machine-readable file (e.g. `--json --out .jerv/tmp/train-doctor.json`); the file is written even when the verdict is NOT READY").addHelpText("after", "\nExit codes:\n  0  ready \u2014 no blocker and origin verified\n  1  a blocker remains, or origin could not be verified (never green on an unread origin)\n\nEvery finding carries code, severity (blocker|warning|healed|info), source (local|origin), remedy and a\ndocs/Guides/train-troubleshooting.md#<code> anchor. `release --apply` and `rcand --apply` run this at step 0 with --heal.\n").action(async (o) => {
     try {
       if (o.dev && o.lane && o.lane !== "release") {
         return failGraceful(`train doctor: --dev applies only to the release lane \u2014 it names the development -> main variant that skips rc, which the ${o.lane} lane does not have`);
@@ -43912,7 +44004,9 @@ function registerTrainCommands(program3, trainDeps) {
       };
       const verdict = await runTrainDoctor({ lane: o.lane, dev: o.dev === true, heal: o.heal === true, train: deps, repo: o.repo, cwd: root, argv: INVOKED_ARGV });
       if (verdict.reexecCode !== void 0) return process.exit(verdict.reexecCode);
-      console.log(o.json ? JSON.stringify(verdict, null, 2) : formatTrainDoctor(verdict));
+      const output = o.json ? JSON.stringify(verdict, null, 2) : formatTrainDoctor(verdict);
+      if (!o.out) console.log(output);
+      else console.log(`Wrote train doctor verdict to ${o.out} (UTF-8, ${writeUtf8Receipt(o.out, output)} bytes)`);
       if (!verdict.ready) process.exitCode = 1;
     } catch (e) {
       return failGraceful(`train doctor: ${e.message}`);
@@ -44138,6 +44232,9 @@ function renderReleaseResume(r) {
 function renderReleaseAbort(r) {
   return `mmi-cli devops release --abort --apply: ${r.repo} ${r.tag} (${r.tagSha.slice(0, 12)}) \u2014 ${r.note}`;
 }
+function renderReleaseSupersedeDeploy(r) {
+  return `mmi-cli devops release --supersede-deploy --apply: ${r.repo} ${r.tag} (${r.tagSha.slice(0, 12)}) \u2014 ${r.note}`;
+}
 function renderReleasePublishRetry(r) {
   return `mmi-cli devops release --retry-publish: ${r.repo} ${r.tag} (${r.tagSha.slice(0, 12)}) \u2014 ${r.note}; ${r.runUrl}`;
 }
@@ -44331,6 +44428,7 @@ function registerTrainOperationsCommands(program3, runProjectInfoSyncCallback) {
       { flags: "--ack <shas>", description: "comma-separated dev shas a human verified are in the candidate, overriding the hotfix-coverage guard for a conflicted port whose -x trailer was lost (#958)" },
       { flags: "--dev", description: "full-track repos release development -> main directly, skipping rc (refuses if rc carries content not in development; no-op on direct-track repos) (#1062)" },
       { flags: "--abort", description: "with --apply, delete only a proven unpublished failed release candidate on any registered deploy model and restore local main for a same-version recut (#3944/#5650/#5657)" },
+      { flags: "--supersede-deploy", description: "with --apply, master-approved closure of a content-caused failed deploy leg on a PUBLISHED release whose immutable tag can never deploy green \u2014 the next patch train then carries the fix (#6553)" },
       { flags: "--retry-publish <run-id>", description: "with --apply, retry one proven failed or cancelled Hub publish release run (#3949/#5797)" }
     ];
     for (const f of RELEASE_ONLY_FLAGS) {
@@ -44358,6 +44456,9 @@ function registerTrainOperationsCommands(program3, runProjectInfoSyncCallback) {
       if (o.abort && commandName !== "release") {
         return fail(`${commandName}: --abort applies only to release \u2014 it rolls back a proven unpublished release tag. Run: mmi-cli devops release --abort --apply`);
       }
+      if (o.supersedeDeploy && commandName !== "release") {
+        return fail(`${commandName}: --supersede-deploy applies only to release \u2014 it closes a content-caused failed deploy leg on a published release's ledger. Run: mmi-cli devops release --supersede-deploy --apply`);
+      }
       if (o.retryPublish && commandName !== "release") {
         return fail(`${commandName}: --retry-publish applies only to release. Run: mmi-cli devops release --retry-publish <run-id> --apply --watch`);
       }
@@ -44405,6 +44506,25 @@ function registerTrainOperationsCommands(program3, runProjectInfoSyncCallback) {
           return failGraceful(`release --abort: ${e.message}`);
         }
       }
+      if (o.supersedeDeploy) {
+        if (o.resume) return fail("release: --supersede-deploy and --resume are mutually exclusive \u2014 the closure settles the ledger so a NEW train can run, resume re-derives the very leg it closes");
+        if (o.abort) return fail("release: --supersede-deploy and --abort are mutually exclusive \u2014 the closure is for a PUBLISHED release, abort only ever deletes a proven unpublished candidate");
+        if (o.retryPublish) return fail("release: --supersede-deploy cannot be combined with --retry-publish");
+        if (!o.apply) return fail("release: --supersede-deploy requires --apply after explicit master approval; nothing was written");
+        if (o.watch || o.announceSummaryFile || o.ack || o.dev) {
+          return fail("release: --supersede-deploy accepts only --apply, --repo, --json and --out; it closes a ledger leg and dispatches nothing");
+        }
+        if (o.repo) {
+          const guard = planTrainApplyRepoGuard(o.repo, await resolveRepo(), "mmi-cli devops release --supersede-deploy --apply");
+          if (!guard.ok) return fail(`release: ${guard.message}`);
+        }
+        try {
+          const result = await runReleaseSupersedeDeploy(trainApplyDeps(), { approved: true });
+          return emitTrainResult("release --supersede-deploy", o.json ? JSON.stringify(result, null, 2) : renderReleaseSupersedeDeploy(result), o.out);
+        } catch (e) {
+          return failGraceful(`release --supersede-deploy: ${e.message}`);
+        }
+      }
       if (o.resume) {
         if (o.apply) return fail(`${commandName}: --resume and --apply are mutually exclusive \u2014 --apply cuts the NEXT version, --resume finishes the immutable tag already on origin`);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.3.50",
+  "version": "4.3.52",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",