@mutmutco/cli 4.3.25 → 4.3.27

package/dist/main.cjs

@@ -10939,9 +10939,15 @@ function boardNotFoundError(ref, board, opts = {}) {
 function evaluateClaim(item, login) {
   const others = item.assignees.filter((a) => a.toLowerCase() !== login.toLowerCase());
   const mine = item.assignees.some((a) => a.toLowerCase() === login.toLowerCase());
+  if (others.length && item.status === "In Review") {
+    return {
+      ok: false,
+      reason: `${item.ref} is not claimable: In Review and held by @${others.join(", @")} \u2014 ask the holder, or wait for the review to land`
+    };
+  }
   if (others.length) return { ok: false, reason: `${item.ref} is already assigned to @${others.join(", @")}` };
   if (item.status === "In Progress" && mine) return { ok: true, alreadyClaimed: true };
-  if (item.status !== "Todo" && item.status !== "In Progress") {
+  if (item.status !== "Todo" && item.status !== "In Progress" && item.status !== "In Review") {
     return { ok: false, reason: `${item.ref} is not claimable: Status is ${item.status}` };
   }
   return { ok: true, alreadyClaimed: false };
@@ -11064,7 +11070,7 @@ async function repoCanPush(repo, client) {
   }
 }
 async function resolveWritableReposForClaimables(items, client) {
-  const candidateRepos = [...new Set(items.filter((item) => (item.status === "Todo" || item.status === "In Progress") && item.assignees.length === 0).map((item) => item.repository))];
+  const candidateRepos = [...new Set(items.filter((item) => (item.status === "Todo" || item.status === "In Progress" || item.status === "In Review") && item.assignees.length === 0).map((item) => item.repository))];
   const repos = /* @__PURE__ */ new Set();
   const unknown = /* @__PURE__ */ new Set();
   const warnings = [];
@@ -12177,7 +12183,7 @@ async function prepareClaimContext(options, selectors, deps, collected, snapshot
 async function claimOneBoardItem(ctx, selector, options) {
   const { cfg, client, report } = ctx;
   const flatItem = findBoardItem(ctx.items, selector, { owner: cfg.projectOwner, number: cfg.projectNumber });
-  const wouldWrite = flatItem.assignees.length === 0 && (flatItem.status === "Todo" || flatItem.status === "In Progress");
+  const wouldWrite = flatItem.assignees.length === 0 && (flatItem.status === "Todo" || flatItem.status === "In Progress" || flatItem.status === "In Review");
   if (wouldWrite && !ctx.writable.has(flatItem.repository.toLowerCase())) {
     throw new Error(
       `${flatItem.ref} is not claimable: the token from ${describeTokenSource()} reports no write access to ${flatItem.repository}`
@@ -12216,7 +12222,10 @@ async function claimOneBoardItem(ctx, selector, options) {
   };
   let previousHolder;
   let resumeEvidence;
-  const claimedReceipt = () => previousHolder ? resumeEvidence ? { outcome: "resumed", holder, previousHolder, resumeEvidence } : { outcome: "took-over", holder, previousHolder } : { outcome: "claimed", holder };
+  const claimedReceipt = () => ({
+    ...item.status === "In Review" ? { reclaimedFrom: "In Review" } : {},
+    ...previousHolder ? resumeEvidence ? { outcome: "resumed", holder, previousHolder, resumeEvidence } : { outcome: "took-over", holder, previousHolder } : { outcome: "claimed", holder }
+  });
   const heldReceipt = () => previousHolder ? resumeEvidence ? { outcome: "resumed", holder, previousHolder, resumeEvidence } : { outcome: "took-over", holder, previousHolder } : { outcome: "held", holder };
   if (flatItem.contentType !== "Issue") throw new Error(`${flatItem.ref} is not an issue`);
   const pre = evaluateClaim(flatItem, assignedLogin);
@@ -12274,7 +12283,7 @@ async function claimOneBoardItem(ctx, selector, options) {
   } catch (e) {
     const warning = `partial claim: ${item.ref} was assigned to @${assignedLogin}, but Status was not moved to In Progress (${ghError(e)})`;
     if (!options.allowPartial) throw new Error(warning);
-    return { item, viewer: report.viewer, repo: report.repo, status: "Todo", partial: true, warning, ...claimedReceipt() };
+    return { item, viewer: report.viewer, repo: report.repo, status: item.status, partial: true, warning, ...claimedReceipt() };
   }
   return {
     item: {
@@ -12320,7 +12329,7 @@ async function claimBoardIssues(options, deps = {}) {
       const ref = `${selector.repo}#${selector.number}`;
       try {
         const result = await claimOneBoardItem(ctx, selector, { ...options, bulk: true });
-        results[index] = { ref: result.item.ref, claimed: true, item: result.item, status: result.status, partial: result.partial, warning: result.warning, outcome: result.outcome, holder: result.holder, previousHolder: result.previousHolder, resumeEvidence: result.resumeEvidence, alreadyClaimed: result.alreadyClaimed, checked: result.checked };
+        results[index] = { ref: result.item.ref, claimed: true, item: result.item, status: result.status, partial: result.partial, warning: result.warning, outcome: result.outcome, holder: result.holder, previousHolder: result.previousHolder, resumeEvidence: result.resumeEvidence, reclaimedFrom: result.reclaimedFrom, alreadyClaimed: result.alreadyClaimed, checked: result.checked };
       } catch (e) {
         results[index] = { ref, claimed: false, reason: e.message };
       }
@@ -14074,7 +14083,7 @@ var GATE_RUNTIME_DEFAULTS = {
   node: { cmd: DEFAULT_GATE_CMD, install: "npm ci" },
   python: { cmd: "pytest", install: 'pip install -e ".[dev]"' }
 };
-function gateSeedVars(cls, releaseTrack, runtime = "node", requiredCheckBranches) {
+function gateSeedVars(cls, releaseTrack, runtime = "node", requiredCheckBranches, requiredChecks) {
   const rt = GATE_RUNTIME_DEFAULTS[runtime] ?? GATE_RUNTIME_DEFAULTS.node;
   const runtimeVars = {
     GATE_RUNTIME: runtime,
@@ -14094,12 +14103,14 @@ function gateSeedVars(cls, releaseTrack, runtime = "node", requiredCheckBranches
   const trackBranches = track === "trunk" ? ["main"] : track === "direct" ? ["development", "main"] : ["development", "rc", "main"];
   const rulesetBranches = requiredCheckBranches?.length ? [...requiredCheckBranches] : trackBranches;
   const rulesetRefs = JSON.stringify(rulesetBranches.map((branch) => `refs/heads/${branch}`));
+  const rulesetContexts = JSON.stringify((requiredChecks?.length ? requiredChecks : ["gate"]).map((context) => ({ context })));
   if (track === "trunk") {
     return {
       ...runtimeVars,
       GATE_PUSH_BRANCHES_YAML: "[main]",
       GATE_FULL_RUN_BRANCH: "main",
-      GATE_RULESET_BRANCH_REFS_JSON: rulesetRefs
+      GATE_RULESET_BRANCH_REFS_JSON: rulesetRefs,
+      GATE_RULESET_CONTEXTS_JSON: rulesetContexts
     };
   }
   if (track === "direct") {
@@ -14107,17 +14118,19 @@ function gateSeedVars(cls, releaseTrack, runtime = "node", requiredCheckBranches
       ...runtimeVars,
       GATE_PUSH_BRANCHES_YAML: "[development, main]",
       GATE_FULL_RUN_BRANCH: "development",
-      GATE_RULESET_BRANCH_REFS_JSON: rulesetRefs
+      GATE_RULESET_BRANCH_REFS_JSON: rulesetRefs,
+      GATE_RULESET_CONTEXTS_JSON: rulesetContexts
     };
   }
   return {
     ...runtimeVars,
     GATE_PUSH_BRANCHES_YAML: "[development, rc, main]",
     GATE_FULL_RUN_BRANCH: "development",
-    GATE_RULESET_BRANCH_REFS_JSON: rulesetRefs
+    GATE_RULESET_BRANCH_REFS_JSON: rulesetRefs,
+    GATE_RULESET_CONTEXTS_JSON: rulesetContexts
   };
 }
-function withDerivedRepoVars(vars, parsed, cls, releaseTrack, requiredCheckBranches) {
+function withDerivedRepoVars(vars, parsed, cls, releaseTrack, requiredCheckBranches, requiredChecks) {
   const out = { ...vars };
   out.REPO_NAME ??= parsed.name;
   out.REPO_SLUG ??= parsed.slug;
@@ -14125,7 +14138,7 @@ function withDerivedRepoVars(vars, parsed, cls, releaseTrack, requiredCheckBranc
   out.PROJECT_OWNER ??= parsed.owner;
   const track = releaseTrack ?? resolveBootstrapReleaseTrack(cls);
   const runtime = out.GATE_RUNTIME === "python" ? "python" : "node";
-  for (const [key, value] of Object.entries(gateSeedVars(cls, track, runtime, requiredCheckBranches))) {
+  for (const [key, value] of Object.entries(gateSeedVars(cls, track, runtime, requiredCheckBranches, requiredChecks))) {
     out[key] ??= value;
   }
   if (!out.GATE_AFFECTED_CMD.trim()) out.GATE_AFFECTED_CMD = out.GATE_CMD;
@@ -15522,10 +15535,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.25",
-    tag: "v4.3.25",
-    commit: "fc9a141cca17",
-    npm: "@mutmutco/cli@4.3.25"
+    version: "4.3.27",
+    tag: "v4.3.27",
+    commit: "924b5a7761c4",
+    npm: "@mutmutco/cli@4.3.27"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15542,14 +15555,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.25"
+          v3Target: "v4.3.27"
         }
       ],
       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.25 and redeploy the Hub Lambda from tag v4.3.25 (fc9a141cca17); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.25 (@mutmutco/cli@4.3.25, tag commit fc9a141cca17 \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.27 and redeploy the Hub Lambda from tag v4.3.27 (924b5a7761c4); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.27 (@mutmutco/cli@4.3.27, tag commit 924b5a7761c4 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -24213,7 +24226,8 @@ async function seedGateYml(repo, deps, meta, result) {
     parsed,
     "deployable",
     releaseTrack,
-    meta?.requiredCheckBranches
+    meta?.requiredCheckBranches,
+    registryRequiredContexts(meta) ?? void 0
   );
   if (await contentExists(deps, repo, baseBranch, PRODUCT_GATE_PATH)) {
     return await seedRulesetRefIfMissing(repo, deps, refOnlyVars(), baseBranch, result);
@@ -24240,7 +24254,8 @@ async function seedGateYml(repo, deps, meta, result) {
     parsed,
     "deployable",
     releaseTrack,
-    meta?.requiredCheckBranches
+    meta?.requiredCheckBranches,
+    registryRequiredContexts(meta) ?? void 0
   );
   const rendered = renderSeedBody(deps, GATE_TEMPLATE_SEED, PRODUCT_GATE_PATH, derivedVars);
   if (rendered == null) {
@@ -25569,11 +25584,12 @@ function registerBoardCommands(program3) {
   function claimVerdict(ref, result) {
     const holder = formatClaimHolder(result.holder);
     const previousHolder = result.previousHolder ? formatClaimHolder(result.previousHolder) : "another lane";
+    const reclaimed = result.reclaimedFrom ? ` (reclaimed from ${result.reclaimedFrom})` : "";
     if (result.checked) {
       if (result.outcome === "held") return `Check ${ref}: held by ${holder} - claim would renew the lease (nothing written)`;
       if (result.outcome === "took-over") return `Check ${ref}: held by ${previousHolder} - --force claim would take it over for ${holder} (nothing written)`;
       if (result.outcome === "resumed") return `Check ${ref}: prior lane ${previousHolder} is verifiably dead - claim would resume its work for ${holder} (nothing written; ${result.resumeEvidence})`;
-      return `Check ${ref}: free - claim would proceed for ${holder} (nothing written)`;
+      return `Check ${ref}: free - claim would proceed for ${holder}${reclaimed} (nothing written)`;
     }
     if (result.partial) {
       if (result.outcome === "took-over") return `Partially took over ${ref} from ${previousHolder}: ${result.warning}`;
@@ -25583,12 +25599,12 @@ function registerBoardCommands(program3) {
     if (result.outcome === "took-over") return `Took over ${ref} from ${previousHolder} for ${holder} - In Progress`;
     if (result.outcome === "resumed") return `Resumed ${ref} from ${previousHolder} for ${holder} - In Progress (${result.resumeEvidence})`;
     if (result.outcome === "held") return `${ref} is held by ${holder} - In Progress`;
-    return `Claimed ${ref} for ${holder} - In Progress`;
+    return `Claimed ${ref} for ${holder} - In Progress${reclaimed}`;
   }
   const board = program3.command("board").description("read, claim, show, and move Project v2 work items for the current repo");
   board.command("read", { isDefault: true }).alias("list").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("--direct", "bypass the Hub snapshot and read the live board through direct GitHub GraphQL").option("--bundle-details", "fetch body/comments only for user-owned and claimable issues").option("--bodies", "fetch body/comments for EVERY scoped row, including taken and unowned in-flight ones \u2014 for consumers that scope by Status rather than ownership (#4861); implies --bundle-details and costs one extra read per row").option("--allow-partial", "return partial board results when later page/detail reads fail").option("--out <path>", "write the output to this file as UTF-8 (no BOM) instead of stdout \u2014 the shell-free receipt path (#5802)").addHelpText("after", "\nread is always the authoritative live GitHub Project v2 board (#4926).\n--direct skips the Hub snapshot and uses the existing direct GitHub GraphQL read immediately.\n--allow-partial applies to the paginated path and detail reads.\n\nNever capture the JSON with a shell redirect on Windows: PowerShell 5.1's `> file.json` is Out-File,\nwhich writes UTF-16LE with a BOM, and Node reading it as 'utf8' then fails JSON.parse at position 1\n(#5802). Use --out instead \u2014 the CLI writes the file itself as UTF-8:\n  mmi-cli oracle board read --json --out .jerv/tmp/board.json\n").action((o) => runBoardRead(o));
   withExamples(mutating(
-    board.command("claim <issues...>").description("claim issues: assign them and move their Project v2 Status to In Progress \u2014 idempotent, so an item already yours and In Progress succeeds unchanged (one or more refs); the board scan rides the Hub snapshot, same as board read").addHelpText("after", "\nclaim reads the board through the same Hub snapshot leg as `board read` (the App-installation\ncredential, never your personal GraphQL pool); the direct user-auth read is an emergency fallback\nand is named in a Warning line after the verdict (#6162).\n\nevery claim stamps a lane-identity marker comment on the issue (`<!-- mmi-claim: \u2026 -->`,\nsurface/session@host) so other agents can attribute the hold (#3727). The session is the\nhost-exported id when the surface provides one, otherwise a per-process `synth-` fallback \u2014\na claim is never anonymous (#5245). `board show`, doctor and unclaim read the latest marker.\n\nsame-owner resume (#6035): when the prior marker was posted by YOUR login on THIS host and its\nlocal session is verifiably dead (transcript probe), the claim proceeds as a resume without\n--force and names the evidence. A live, foreign-host, or unprobeable prior lane still refuses.\n").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("--force", "take an item already claimed by another lane that shows live evidence of active work (#3727)").option("--check", "read-only: run every claim gate and report the verdict, writing nothing \u2014 exits 1 with the same refusal a real claim would raise (#4511)").option("--allow-partial", "return success JSON if assignment succeeds but the status move fails"),
+    board.command("claim <issues...>").description("claim issues: assign them and move their Project v2 Status to In Progress \u2014 idempotent, so an item already yours and In Progress succeeds unchanged (one or more refs); the board scan rides the Hub snapshot, same as board read").addHelpText("after", "\nclaim reads the board through the same Hub snapshot leg as `board read` (the App-installation\ncredential, never your personal GraphQL pool); the direct user-auth read is an emergency fallback\nand is named in a Warning line after the verdict (#6162).\n\nevery claim stamps a lane-identity marker comment on the issue (`<!-- mmi-claim: \u2026 -->`,\nsurface/session@host) so other agents can attribute the hold (#3727). The session is the\nhost-exported id when the surface provides one, otherwise a per-process `synth-` fallback \u2014\na claim is never anonymous (#5245). `board show`, doctor and unclaim read the latest marker.\n\nsame-owner resume (#6035): when the prior marker was posted by YOUR login on THIS host and its\nlocal session is verifiably dead (transcript probe), the claim proceeds as a resume without\n--force and names the evidence. A live, foreign-host, or unprobeable prior lane still refuses.\n\nreclaim from In Review (#6339): an In Review item with no holder, or one held by the claiming\nlogin, is claimable \u2014 it moves back to In Progress and the receipt names the status it came from.\nAn In Review item another login holds is refused (ask the holder, or wait for the review to land),\nand Done stays refused. The board status is the authority; no PR state is consulted.\n").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("--force", "take an item already claimed by another lane that shows live evidence of active work (#3727)").option("--check", "read-only: run every claim gate and report the verdict, writing nothing \u2014 exits 1 with the same refusal a real claim would raise (#4511)").option("--allow-partial", "return success JSON if assignment succeeds but the status move fails"),
     (_opts, args) => ({ command: "board claim", issues: args[0] ?? [] })
   ).action(async (issueRefs, o) => {
     if (issueRefs.length === 1) {
@@ -26590,8 +26606,9 @@ function deployStagesForBootstrap(deployModel, track) {
   return branchesForTrack(track).map((branch) => branch === "development" ? "dev" : branch);
 }
 var missingBaseDetail = (base) => `${base} is missing; no source ref exists from which bootstrap can create the train lanes`;
-function productRulesetMatches(fact, branches) {
-  if (fact?.enforcement !== "active" || !fact.contexts.includes("gate")) return false;
+function productRulesetMatches(fact, branches, contexts) {
+  const wantedContexts = contexts?.length ? contexts : ["gate"];
+  if (fact?.enforcement !== "active" || !sameNames(fact.contexts, wantedContexts)) return false;
   const wanted = branches.map((branch) => branch.startsWith("refs/") ? branch : `refs/heads/${branch}`);
   return sameNames(fact.branches, wanted);
 }
@@ -26627,7 +26644,7 @@ function planBootstrapControlPlane(input) {
         code: "bootstrap-gap",
         detail: [input.github.gateError, input.github.rulesetError].filter(Boolean).join("; ")
       });
-    } else if (productRulesetMatches(input.github.productRuleset, input.requiredCheckBranches)) {
+    } else if (productRulesetMatches(input.github.productRuleset, input.requiredCheckBranches, input.requiredChecks)) {
       rows.push({ kind: "product-ruleset", target: "mmi-product-required-checks", action: "skip", detail: "active gate context and branch scope already match the seeded authority" });
     } else if (!input.github.gateExists) {
       rows.push({ kind: "product-ruleset", target: "mmi-product-required-checks", action: "park", detail: `${PRODUCT_GATE_PATH2} is not present on ${base}; install disabled and activate on the next apply after the seed lands` });
@@ -27639,6 +27656,7 @@ function registerBootstrapCommands(program3) {
         repoClass: cls,
         releaseTrack: track,
         requiredCheckBranches: resolveRequiredCheckBranches(metaWithDeclaredClass(meta, cls), repo),
+        requiredChecks: meta?.requiredChecks ?? void 0,
         deployModel: meta?.deployModel,
         owners: controlOwners,
         github,
@@ -27778,7 +27796,7 @@ function registerBootstrapCommands(program3) {
       for (const [k, v] of Object.entries(gateConfigToVars(meta?.gate))) if (rawVars[k] == null) rawVars[k] = v;
     } catch {
     }
-    const vars = withDerivedRepoVars(rawVars, parsedRepo, o.class, bootstrapReleaseTrack, registryRequiredCheckBranches);
+    const vars = withDerivedRepoVars(rawVars, parsedRepo, o.class, bootstrapReleaseTrack, registryRequiredCheckBranches, registryMeta?.requiredChecks);
     if (!vars.PROJECT_ID) {
       try {
         const r = await gh(linkedProjectsQueryArgs(parsedRepo.owner, parsedRepo.name));
@@ -27837,6 +27855,7 @@ function registerBootstrapCommands(program3) {
         repoClass: o.class,
         releaseTrack: effectiveTrack,
         requiredCheckBranches: resolveRequiredCheckBranches(metaWithDeclaredClass(registryMeta, o.class), repo),
+        requiredChecks: registryMeta?.requiredChecks ?? void 0,
         deployModel: applyDeployModel,
         owners: controlOwners,
         github,
@@ -28186,6 +28205,7 @@ ${onlyManagedBlock ? `Only the marker-bounded Hub-managed block inside repo-owne
         repoClass: o.class,
         releaseTrack: effectiveTrack,
         requiredCheckBranches: resolveRequiredCheckBranches(metaWithDeclaredClass(registryMeta, o.class), repo),
+        requiredChecks: registryMeta?.requiredChecks ?? void 0,
         deployModel: applyDeployModel,
         owners: controlOwners,
         github,
@@ -28296,7 +28316,7 @@ LIVE apply to ${repo}:
       if (seed.source.startsWith("seed:")) {
         const project2 = projects.find((p) => (p.repos ?? []).some((repo) => repo.toLowerCase() === r.repo.toLowerCase()));
         const track = resolveReleaseTrack(project2, void 0, r.repo);
-        const vars = withDerivedRepoVars({}, parseOwnerRepo(r.repo), repoClass, track, project2?.requiredCheckBranches);
+        const vars = withDerivedRepoVars({}, parseOwnerRepo(r.repo), repoClass, track, project2?.requiredCheckBranches, project2?.requiredChecks);
         const resolved = resolveSeedWriteContent(seed, vars, readSeedFile2, content);
         if (!resolved.ok || resolved.content == null) {
           return fail(`bootstrap propagate: ${r.repo} ${seed.target}: ${resolved.ok ? "rendered no content" : resolved.reason} \u2014 refusing an incomplete per-repo render`);
@@ -29984,6 +30004,19 @@ function stageExtraEnv(config, stagePort) {
 function stageProcessEnv(stagePort, extraEnv) {
   return { ...stagePort != null ? { STAGE_PORT: String(stagePort) } : {}, ...extraEnv };
 }
+function composeResolvesPort(cwd) {
+  if (process.env.PORT) return true;
+  const envFile = (0, import_node_path27.join)(cwd, ".env");
+  return (0, import_node_fs28.existsSync)(envFile) && envFileKeys((0, import_node_fs28.readFileSync)(envFile, "utf8")).has("PORT");
+}
+function stageComposeEnv(config, stagePort, vaultEnvMerge, cwd) {
+  return {
+    // Vault secrets first so the stage-selection contract (MMI_STAGE/MMI_PORT/…) always wins on any collision.
+    ...vaultEnvMerge ?? {},
+    ...stageProcessEnv(stagePort, stageExtraEnv(config, stagePort)),
+    ...stagePort != null && !composeResolvesPort(cwd) ? { PORT: String(stagePort) } : {}
+  };
+}
 async function ensureStageRuntimeEnv(config, opts, cwd) {
   if (!config.ensureEnv) return;
   const target = (0, import_node_path27.join)(cwd, config.ensureEnv.target);
@@ -30059,10 +30092,19 @@ function writeStagePortReservation(port, cwd, statePath, globalStatePath, now) {
   writeState(statePath, reservation);
   if (globalStatePath && globalStatePath !== statePath) writeState(globalStatePath, reservation);
 }
-async function cleanupStageState(state, paths, timeoutMs, fallbackCwd) {
+function teardownEnv(state, currentEnv) {
+  const env = { ...state.teardown?.env ?? {}, ...currentEnv ?? {} };
+  return Object.keys(env).length ? env : void 0;
+}
+async function cleanupStageState(state, paths, timeoutMs, fallbackCwd, currentEnv) {
   await killTree(state.pid);
   if (state.teardown?.command.trim()) {
-    await shell(state.teardown.command.trim(), state.teardown.cwd || state.cwd || fallbackCwd, Math.max(timeoutMs, 1e4));
+    await shell(
+      state.teardown.command.trim(),
+      state.teardown.cwd || state.cwd || fallbackCwd,
+      Math.max(timeoutMs, 1e4),
+      teardownEnv(state, currentEnv)
+    );
   }
   for (const path2 of [...new Set(paths.filter((p) => Boolean(p)))]) {
     (0, import_node_fs28.rmSync)(path2, { force: true });
@@ -30120,13 +30162,20 @@ async function stopStage(opts = {}) {
   }
   const usingGlobalState = state === globalState;
   const recordedStatePath = state.statePath ?? statePath;
-  await cleanupStageState(state, [statePath, recordedStatePath, usingGlobalState || !opts.requiredIdentityCwd ? globalStatePath : void 0], opts.timeoutMs ?? 6e4, cwd);
+  const recordedTeardownEnv = Boolean(state.teardown?.env);
+  await cleanupStageState(
+    state,
+    [statePath, recordedStatePath, usingGlobalState || !opts.requiredIdentityCwd ? globalStatePath : void 0],
+    opts.timeoutMs ?? 6e4,
+    cwd,
+    opts.vaultEnvMerge
+  );
   return {
     ok: true,
     action: "stop",
     statePath: recordedStatePath,
     pid: state.pid,
-    message: `stopped previous stage pid ${state.pid}${state.teardown?.command.trim() ? " and ran teardown" : ""}`
+    message: `stopped previous stage pid ${state.pid}` + (state.teardown?.command.trim() ? ` and ran teardown${recordedTeardownEnv ? "" : " (no recorded teardown env \u2014 used the current environment)"}` : "")
   };
 }
 async function startStage(config = {}, opts = {}) {
@@ -30146,8 +30195,7 @@ async function startStage(config = {}, opts = {}) {
   const sub = (s) => substituteStagePort(s, stagePort);
   if (!opts.envPrepared) await ensureStageRuntimeEnv(config, opts, cwd);
   if (stagePort != null && portGuard) await ensureStagePortAvailable(stagePort, cwd, portGuard);
-  const extraEnv = stageExtraEnv(config, stagePort);
-  const vaultProcessEnv = opts.vaultEnvMerge ?? {};
+  const composeEnv = stageComposeEnv(config, stagePort, opts.vaultEnvMerge, cwd);
   let up = sub(config.up.trim());
   if (opts.forceRecreate) up = appendForceRecreate(up);
   const identity = await resolveStageIdentity(cwd);
@@ -30160,8 +30208,7 @@ async function startStage(config = {}, opts = {}) {
     detached: process.platform !== "win32",
     windowsHide: true,
     stdio: "ignore",
-    // Vault secrets first so the stage-selection contract (MMI_STAGE/MMI_PORT/…) always wins on any collision.
-    env: { ...process.env, ...vaultProcessEnv, ...stageProcessEnv(stagePort, extraEnv) }
+    env: { ...process.env, ...composeEnv }
   });
   const state = {
     pid: child2.pid ?? 0,
@@ -30172,7 +30219,10 @@ async function startStage(config = {}, opts = {}) {
     healthUrl: sub(config.healthUrl?.trim()) || void 0,
     port: stagePort,
     identity,
-    teardown: config.teardown?.trim() ? { command: sub(config.teardown.trim()), cwd } : void 0
+    // #6343: record the non-secret half of the interpolation env so a LATER `stage stop` can run
+    // `docker compose down` against the same file. `vaultEnvMerge` is omitted deliberately — no secret
+    // value ever reaches disk (#2655); the stopping invocation re-fetches them.
+    teardown: config.teardown?.trim() ? { command: sub(config.teardown.trim()), cwd, env: stageComposeEnv(config, stagePort, void 0, cwd) } : void 0
   };
   writeState(statePath, state);
   if (globalStatePath && globalStatePath !== statePath) writeState(globalStatePath, state);
@@ -30180,7 +30230,7 @@ async function startStage(config = {}, opts = {}) {
     if (state.healthUrl) await waitForHealth(state.healthUrl, opts.timeoutMs ?? 6e4, config.healthAnyStatus);
     else await waitForProcessStability(child2);
   } catch (e) {
-    await cleanupStageState(state, [statePath, globalStatePath], opts.timeoutMs ?? 6e4, cwd);
+    await cleanupStageState(state, [statePath, globalStatePath], opts.timeoutMs ?? 6e4, cwd, composeEnv);
     throw e;
   }
   const result = {
@@ -30211,7 +30261,12 @@ async function runStage(config = {}, opts = {}) {
   const statePath = opts.statePath ?? stageStatePath(cwd);
   const globalStatePath = await resolveGlobalStatePath(cwd, opts.globalStatePath);
   const portGuard = resolveStagePortGuard(opts);
-  await stopStage({ ...opts, cwd, requiredIdentityCwd: opts.requiredIdentityCwd ?? cwd });
+  await stopStage({
+    ...opts,
+    cwd,
+    requiredIdentityCwd: opts.requiredIdentityCwd ?? cwd,
+    vaultEnvMerge: stageComposeEnv(config, opts.stagePort, opts.vaultEnvMerge, cwd)
+  });
   const reserved = await reservedPortsForWorktree(cwd);
   let stagePort = opts.stagePort;
   if (stagePort != null) {
@@ -30223,14 +30278,13 @@ async function runStage(config = {}, opts = {}) {
   if (stagePort != null) {
     writeStagePortReservation(stagePort, cwd, statePath, globalStatePath, opts.now ?? (() => /* @__PURE__ */ new Date()));
   }
-  const extraEnv = stageExtraEnv(config, stagePort);
   const build = config.build?.trim();
   const ranBuild = Boolean(build);
   try {
     await ensureStageRuntimeEnv(config, opts, cwd);
     if (build) {
       await shell(sub(build), cwd, timeoutMs, {
-        ...stageProcessEnv(stagePort, extraEnv),
+        ...stageComposeEnv(config, stagePort, opts.vaultEnvMerge, cwd),
         ...opts.buildEnvMerge ?? {}
       });
     }
@@ -42451,6 +42505,30 @@ ${recovery.note}; the full required-check wall did not revalidate`);
   }, `the immutable ${anchors.tag} pushed at ${mergedSha.slice(0, 12)}`);
   return checks;
 }
+async function assertConsumerBomLineage(deps, mergedSha, tag) {
+  let bomText;
+  try {
+    bomText = await deps.run("git", ["show", `${mergedSha}:distribution-bom.json`]);
+  } catch {
+    return;
+  }
+  let stamp;
+  try {
+    stamp = JSON.parse(bomText).sourceCommit;
+  } catch (e) {
+    throw new Error(`hotfix ${tag}: distribution-bom.json at ${mergedSha.slice(0, 12)} is unparseable (${e.message}) \u2014 the updater would refuse this release; fix the BOM on development and rerun from a fresh port`);
+  }
+  if (typeof stamp !== "string" || !/^[0-9a-f]{40}$/.test(stamp)) {
+    throw new Error(`hotfix ${tag}: distribution-bom.json at ${mergedSha.slice(0, 12)} carries no 40-hex sourceCommit \u2014 the updater would refuse this release`);
+  }
+  try {
+    await deps.run("git", ["merge-base", "--is-ancestor", stamp, mergedSha]);
+  } catch {
+    throw new Error(
+      `hotfix ${tag}: distribution-bom.json at ${mergedSha.slice(0, 12)} stamps sourceCommit ${stamp.slice(0, 12)}, which the merged main commit does not contain \u2014 every updater would reject ${tag} (gateCandidate ancestry). The fold was stamped on the hotfix branch and squash-merged away: make the consumer stamp a durable merge-base (Jerv-Hub#1084), land that on development, and port it with the fix \u2014 see docs/Guides/train-troubleshooting.md#hotfix-bom-lineage`
+    );
+  }
+}
 async function runHotfixRelease(deps, versionInput, options = {}, doctor = runTrainDoctor) {
   await doctor({ lane: "hotfix", heal: true, train: deps, refuse: true });
   const ctx = await buildTrainApplyContext(deps);
@@ -42484,6 +42562,8 @@ async function runHotfixRelease(deps, versionInput, options = {}, doctor = runTr
   assertTagAddressableRequiredContexts(deps, required, ctx.repo);
   if (deployModel === "hub-serverless") {
     await deps.run("node", ["scripts/release-distribution.mjs", "assert-release-lineage", version, "--release-commit", mergedSha]);
+  } else {
+    await assertConsumerBomLineage(deps, mergedSha, tag);
   }
   const releaseExists = await hotfixReleaseExists(deps, ctx, tag);
   if (!releaseExists && isHubControlRepo(ctx.repo)) {

package/package.json

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