@mutmutco/cli 4.3.49 → 4.3.51

package/dist/main.cjs

@@ -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.49",
-    tag: "v4.3.49",
-    commit: "cf2de106fc7f",
-    npm: "@mutmutco/cli@4.3.49"
+    version: "4.3.51",
+    tag: "v4.3.51",
+    commit: "268f45101c3b",
+    npm: "@mutmutco/cli@4.3.51"
   },
   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.49"
+          v3Target: "v4.3.51"
         }
       ],
       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.49 and redeploy the Hub Lambda from tag v4.3.49 (cf2de106fc7f); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.49 (@mutmutco/cli@4.3.49, tag commit cf2de106fc7f \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.51 and redeploy the Hub Lambda from tag v4.3.51 (268f45101c3b); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.51 (@mutmutco/cli@4.3.51, tag commit 268f45101c3b \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");
@@ -43991,6 +44083,7 @@ var GH_RUN_WATCH_TIMEOUT_MS = 20 * 6e4;
 var NODE_PREPARE_TIMEOUT_MS = 10 * 6e4;
 var NODE_VERIFY_TIMEOUT_MS = 5 * 6e4;
 var NPM_TRAIN_TIMEOUT_MS = 6e4;
+var NPM_FOLD_TIMEOUT_MS = NODE_PREPARE_TIMEOUT_MS;
 var JERV_GATEWAY_DEPLOY_TIMEOUT_MS = 20 * 6e4;
 async function announceSummaryRefusal(path2) {
   let lines2;
@@ -44007,7 +44100,7 @@ async function announceSummaryRefusal(path2) {
 function trainApplyDeps() {
   return {
     run: async (file, args) => {
-      const timeout = file === "node" && args[1] === "prepare" ? NODE_PREPARE_TIMEOUT_MS : file === "node" && args[1] === "verify" ? NODE_VERIFY_TIMEOUT_MS : file === "npm" ? NPM_TRAIN_TIMEOUT_MS : file === "bash" && args[0] === "scripts/jerv-gateway-release-deploy.sh" ? JERV_GATEWAY_DEPLOY_TIMEOUT_MS : 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 === "node" && args[1] === "verify" ? NODE_VERIFY_TIMEOUT_MS : file === "npm" && (args[0] === "version" || args[0] === "ci" || args[0] === "install") ? NPM_FOLD_TIMEOUT_MS : file === "npm" ? NPM_TRAIN_TIMEOUT_MS : file === "bash" && args[0] === "scripts/jerv-gateway-release-deploy.sh" ? JERV_GATEWAY_DEPLOY_TIMEOUT_MS : file !== "gh" ? GIT_TIMEOUT_MS : args[0] === "run" && args[1] === "watch" ? GH_RUN_WATCH_TIMEOUT_MS : GH_TRAIN_TIMEOUT_MS;
       try {
         return isWin3 && file === "npm" ? (await execFileP("cmd.exe", ["/c", "npm", ...args], { timeout })).stdout : (await execFileP(file, args, { timeout })).stdout;
       } catch (e) {
@@ -44137,6 +44230,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}`;
 }
@@ -44330,6 +44426,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) {
@@ -44357,6 +44454,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`);
       }
@@ -44404,6 +44504,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.49",
+  "version": "4.3.51",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",