@mutmutco/cli 4.3.26 → 4.3.28

package/dist/main.cjs

@@ -3599,6 +3599,10 @@ var ERROR_CODES = {
   ERR_BAD_ENUM: "ERR_BAD_ENUM",
   /** An unknown flag or subcommand — usually a typo; carries a `did_you_mean`. */
   ERR_UNKNOWN_FLAG: "ERR_UNKNOWN_FLAG",
+  /** A positional argument was passed to a command that does not take it (e.g. `oracle board read 496`,
+   *  a whole-board read given an issue number). Carries a `corrected_command` when exactly one sibling
+   *  answers the same verb positionally (#6354). */
+  ERR_EXCESS_ARGUMENT: "ERR_EXCESS_ARGUMENT",
   /** A referenced resource (issue, repo, board item) does not exist. */
   ERR_NOT_FOUND: "ERR_NOT_FOUND",
   /** Missing / rejected credentials on a path that needs auth. */
@@ -3642,6 +3646,11 @@ var ERROR_CODE_REFERENCE = [
     meaning: "A flag or subcommand is not known to this CLI version.",
     typical_fix: "Check `did_you_mean`, route with `mmi-cli commands --json`, then inspect exact detail with `mmi-cli explain <command> --json`; update the CLI if it should exist."
   },
+  {
+    code: ERROR_CODES.ERR_EXCESS_ARGUMENT,
+    meaning: "A positional argument was supplied to a command that takes none (or fewer).",
+    typical_fix: "Run the command named by `corrected_command`; otherwise drop the extra argument and select the target with the flags in `mmi-cli explain <command> --json`."
+  },
   {
     code: ERROR_CODES.ERR_NOT_FOUND,
     meaning: "The referenced issue, PR, repo, board item, or other resource was not found.",
@@ -4329,8 +4338,8 @@ function fail(msg, payload) {
   if (payload && json) {
     console.error(formatErrorEnvelope(canonicalMsg, payload));
   } else {
-    console.error(`mmi-cli ${canonicalMsg}`);
     if (!json) console.error(`run: mmi-cli explain ${commandFromFailMessage(msg)}`);
+    console.error(`mmi-cli ${canonicalMsg}`);
   }
   hardExit(1);
 }
@@ -4755,6 +4764,26 @@ function synonymFlagFor(flag, ownFlags) {
 function unknownTargetFlagMessage(flag, positional) {
   return `unknown option '${flag}' \u2014 this command takes its target as a positional: ${positional}`;
 }
+function parseExcessArgumentsError(plain) {
+  const m = /too many arguments(?: for '[^']*')?\. Expected \d+ arguments? but got \d+: (.+?)\.\s*$/.exec(plain.trim());
+  if (!m) return void 0;
+  const extra = m[1].split(",").map((s) => s.trim()).filter(Boolean);
+  return extra.length ? { extra } : void 0;
+}
+function siblingTakingPositional(leaf, siblings) {
+  const hits = siblings.filter((s) => s.path && s.names.includes(leaf));
+  return hits.length === 1 ? hits[0] : void 0;
+}
+function correctedPositionalCommand(sibling, value, argv) {
+  const i = argv.indexOf(value);
+  const rest = i < 0 ? argv : [...argv.slice(0, i), ...argv.slice(i + 1)];
+  return [`mmi-cli ${sibling.path}`, value, ...survivingFlagArgs(rest, "", sibling.ownFlags)].join(" ");
+}
+function excessArgumentMessage(extra, corrected) {
+  const list = extra.map((t) => `'${t}'`).join(", ");
+  const head = `unexpected positional argument ${list} \u2014 this command does not take it`;
+  return corrected ? `${head}. Did you mean \`${corrected}\`?` : head;
+}
 
 // src/released-version-cache.ts
 var import_node_fs7 = require("node:fs");
@@ -9029,9 +9058,9 @@ async function secretsCopy(deps, opts) {
     deps.err("secrets copy: --from and --to must differ");
     return false;
   }
-  const keys = [...new Set(opts.keys.map((k) => k.trim()).filter(Boolean))];
+  const keys = [...new Set(opts.keys.flatMap((k) => k.split(/[,\s]+/)).filter(Boolean))];
   if (!keys.length) {
-    deps.err("secrets copy: --keys required (comma-separated allowlist)");
+    deps.err("secrets copy: --keys required (comma- or space-separated allowlist)");
     return false;
   }
   for (const key of keys) {
@@ -10939,9 +10968,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 +11099,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 +12212,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 +12251,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 +12312,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 +12358,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 };
       }
@@ -13954,11 +13992,13 @@ function expectedJsOrigins(cfg) {
   return uniq([...expectedHosts(cfg).map((h) => `https://${h}`), ...LOOPBACK]);
 }
 function expectedRedirectUris(cfg) {
-  const { callbackPath } = cfg;
-  return uniq([
-    ...expectedHosts(cfg).map((h) => `https://${h}${callbackPath}`),
-    ...LOOPBACK.map((l) => `${l}${callbackPath}`)
-  ]);
+  const paths = [cfg.callbackPath, ...cfg.extraCallbackPaths ?? []];
+  return uniq(
+    paths.flatMap((path2) => [
+      ...expectedHosts(cfg).map((h) => `https://${h}${path2}`),
+      ...LOOPBACK.map((l) => `${l}${path2}`)
+    ])
+  );
 }
 function oauthSsmKeys() {
   return [...SSM_NAMES];
@@ -13979,6 +14019,18 @@ function parseOauthClientJson(input) {
   }
   return { clientId, clientSecret };
 }
+function parseExtraCallbackPaths(raw) {
+  if (raw === void 0) return void 0;
+  if (!Array.isArray(raw) || raw.length === 0 || raw.some((p) => typeof p !== "string" || !p.trim())) {
+    throw new Error("oauth.extraCallbackPaths must be a non-empty array of callback path strings");
+  }
+  const paths = raw.map((p) => p.trim());
+  const bad = paths.find((p) => !p.startsWith("/"));
+  if (bad !== void 0) {
+    throw new Error(`oauth.extraCallbackPaths entries must start with "/" (got ${JSON.stringify(bad)})`);
+  }
+  return uniq(paths);
+}
 function parseOauthConfig(mmiConfig, slug) {
   const rawUnknown = mmiConfig?.oauth;
   if (rawUnknown === void 0) throw new Error(`oauth is not configured for ${slug}`);
@@ -13993,12 +14045,15 @@ function parseOauthConfig(mmiConfig, slug) {
     throw new Error(`oauth.callbackPath must start with "/" (got ${JSON.stringify(callbackPath)})`);
   }
   if (callbackPath !== DEFAULT_CALLBACK_PATH) {
-    throw new Error(`oauth.callbackPath must be "${DEFAULT_CALLBACK_PATH}" (got ${JSON.stringify(callbackPath)})`);
+    throw new Error(
+      `oauth.callbackPath is the app-login callback and must be "${DEFAULT_CALLBACK_PATH}" (got ${JSON.stringify(callbackPath)}) \u2014 a second callback on the same client (e.g. a Workspace connect endpoint) goes in oauth.extraCallbackPaths`
+    );
   }
+  const extraCallbackPaths = parseExtraCallbackPaths(raw.extraCallbackPaths);
   const meta = mmiConfig ?? {};
   const rawFofuSub = raw.fofuSubdomain;
   const fofuSubdomain = meta.fofuEnabled === true ? typeof rawFofuSub === "string" ? rawFofuSub : defaultSubdomain(slug) : void 0;
-  return { subdomains, domains, callbackPath, fofuSubdomain };
+  return { subdomains, domains, callbackPath, extraCallbackPaths, fofuSubdomain };
 }
 function probeRedirectUri(callbackPath, port = 9123) {
   return `http://localhost:${port}${callbackPath}`;
@@ -15526,10 +15581,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.26",
-    tag: "v4.3.26",
-    commit: "32a20f524697",
-    npm: "@mutmutco/cli@4.3.26"
+    version: "4.3.28",
+    tag: "v4.3.28",
+    commit: "9a58493b4404",
+    npm: "@mutmutco/cli@4.3.28"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15546,14 +15601,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.26"
+          v3Target: "v4.3.28"
         }
       ],
       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.26 and redeploy the Hub Lambda from tag v4.3.26 (32a20f524697); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.26 (@mutmutco/cli@4.3.26, tag commit 32a20f524697 \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.28 and redeploy the Hub Lambda from tag v4.3.28 (9a58493b4404); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.28 (@mutmutco/cli@4.3.28, tag commit 9a58493b4404 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -25575,11 +25630,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}`;
@@ -25589,12 +25645,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) {
@@ -28949,7 +29005,7 @@ function parseOauthVar(raw) {
     throw new Error(`org project set: oauth must be JSON, e.g. {"subdomains":["app"],"domains":["example.co"],"callbackPath":"${DEFAULT_CALLBACK_PATH}"}`);
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("org project set: oauth must be a {subdomains,domains,callbackPath,fofuSubdomain} object");
+    throw new Error("org project set: oauth must be a {subdomains,domains,callbackPath,extraCallbackPaths,fofuSubdomain} object");
   }
   const map = parsed;
   const out = {};
@@ -28963,14 +29019,22 @@ function parseOauthVar(raw) {
       if (typeof value !== "string" || !value.trim()) throw new Error("org project set: oauth.callbackPath must be a non-empty string");
       const callbackPath = value.trim();
       if (callbackPath !== DEFAULT_CALLBACK_PATH) {
-        throw new Error(`org project set: oauth.callbackPath must be "${DEFAULT_CALLBACK_PATH}" (got ${JSON.stringify(callbackPath)})`);
+        throw new Error(
+          `org project set: oauth.callbackPath is the app-login callback and must be "${DEFAULT_CALLBACK_PATH}" (got ${JSON.stringify(callbackPath)}) \u2014 a second callback on the same client (e.g. a Workspace connect endpoint) goes in oauth.extraCallbackPaths`
+        );
       }
       out.callbackPath = callbackPath;
+    } else if (key === "extraCallbackPaths") {
+      try {
+        out.extraCallbackPaths = parseExtraCallbackPaths(value);
+      } catch (e) {
+        throw new Error(`org project set: ${e.message}`);
+      }
     } else if (key === "fofuSubdomain") {
       if (typeof value !== "string") throw new Error('org project set: oauth.fofuSubdomain must be a string ("" selects the apex fofu.ai)');
       out.fofuSubdomain = value.trim();
     } else {
-      throw new Error(`org project set: oauth key "${key}" \u2014 expected only subdomains/domains/callbackPath/fofuSubdomain`);
+      throw new Error(`org project set: oauth key "${key}" \u2014 expected only subdomains/domains/callbackPath/extraCallbackPaths/fofuSubdomain`);
     }
   }
   return out;
@@ -29170,7 +29234,7 @@ var SETTABLE_VAR_HINTS = {
   runtimeVaultOnly: "true|false",
   seedCanary: "true|false",
   repos: 'JSON array, e.g. ["mutmutco/mm-foo"]',
-  oauth: "JSON {subdomains,domains,callbackPath,fofuSubdomain}",
+  oauth: "JSON {subdomains,domains,callbackPath,extraCallbackPaths,fofuSubdomain}",
   requiredGcpApis: "comma-string",
   requiredRuntimeSecrets: 'JSON stage map, e.g. {"dev":["KEY"],"rc":["KEY"],"main":["KEY"]}',
   requiredBuildSecrets: 'JSON flat array, e.g. ["NODE_AUTH_TOKEN=@github-packages-token"]',
@@ -29642,6 +29706,51 @@ function findEnvFiles(root) {
   return found.sort();
 }
 
+// src/stage-runtime-env.ts
+var SERVICE_NAME_RE = /^[A-Za-z0-9_.-]+$/;
+var ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var RUNTIME_ENV_OVERRIDE_RELPATH = "tmp/stage/runtime-env.override.yml";
+function labelsMarkRuntimeEnv(labels) {
+  if (Array.isArray(labels)) {
+    return labels.some((l) => typeof l === "string" && /^mmi\.runtime-env\s*=\s*["']?true["']?$/.test(l.trim()));
+  }
+  if (labels && typeof labels === "object") {
+    return String(labels["mmi.runtime-env"] ?? "") === "true";
+  }
+  return false;
+}
+function runtimeEnvMarkedServices(composeConfigJson) {
+  let parsed;
+  try {
+    parsed = JSON.parse(composeConfigJson);
+  } catch {
+    return [];
+  }
+  const services = parsed?.services;
+  if (!services || typeof services !== "object" || Array.isArray(services)) return [];
+  return Object.entries(services).filter(([name, svc]) => SERVICE_NAME_RE.test(name) && labelsMarkRuntimeEnv(svc?.labels)).map(([name]) => name).sort();
+}
+function renderRuntimeEnvOverride(services, keys) {
+  const safeServices = services.filter((s) => SERVICE_NAME_RE.test(s)).sort();
+  const safeKeys = [...new Set(keys.filter((k) => ENV_KEY_RE.test(k)))].sort();
+  if (!safeServices.length || !safeKeys.length) return null;
+  const lines2 = [
+    "# Generated by `mmi-cli stage` (#6345) \u2014 do not edit, do not commit.",
+    '# Passes the vault-resolved runtime env through to every service labelled mmi.runtime-env: "true",',
+    "# exactly as the box deploy does. KEY NAMES ONLY: the values live in the compose process env (#2655).",
+    "services:"
+  ];
+  for (const service of safeServices) {
+    lines2.push(`  ${service}:`, "    environment:");
+    for (const key of safeKeys) lines2.push(`      ${key}: \${${key}:?}`);
+  }
+  return `${lines2.join("\n")}
+`;
+}
+function stageComposeFileEnv(files) {
+  return { COMPOSE_PATH_SEPARATOR: ",", COMPOSE_FILE: files.join(",") };
+}
+
 // src/stage-runner.ts
 var execFileP3 = (0, import_node_util5.promisify)(import_node_child_process11.execFile);
 var DOCKER_TIMEOUT_MS = 15e3;
@@ -29994,6 +30103,49 @@ 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) } : {}
+  };
+}
+function stageComposeFiles(cwd) {
+  const files = ["docker-compose.yml"];
+  for (const conventional of ["docker-compose.override.yml", "docker-compose.override.yaml"]) {
+    if ((0, import_node_fs28.existsSync)((0, import_node_path27.join)(cwd, conventional))) files.push(conventional);
+  }
+  return [...files, RUNTIME_ENV_OVERRIDE_RELPATH];
+}
+async function prepareRuntimeEnvPassthrough(cwd, composeEnv, vaultEnvMerge) {
+  const keys = Object.keys(vaultEnvMerge ?? {});
+  if (!keys.length || !(0, import_node_fs28.existsSync)((0, import_node_path27.join)(cwd, "docker-compose.yml"))) return {};
+  let configJson;
+  try {
+    const { stdout } = await execFileP3("docker", ["compose", "config", "--format", "json"], {
+      cwd,
+      windowsHide: true,
+      timeout: DOCKER_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024 * 8,
+      env: { ...process.env, ...composeEnv }
+    });
+    configJson = stdout;
+  } catch {
+    return {};
+  }
+  const body = renderRuntimeEnvOverride(runtimeEnvMarkedServices(configJson), keys);
+  if (!body) return {};
+  const overridePath = (0, import_node_path27.join)(cwd, RUNTIME_ENV_OVERRIDE_RELPATH);
+  (0, import_node_fs28.mkdirSync)((0, import_node_path27.join)(cwd, "tmp", "stage"), { recursive: true });
+  (0, import_node_fs28.writeFileSync)(overridePath, body, "utf8");
+  return stageComposeFileEnv(stageComposeFiles(cwd));
+}
 async function ensureStageRuntimeEnv(config, opts, cwd) {
   if (!config.ensureEnv) return;
   const target = (0, import_node_path27.join)(cwd, config.ensureEnv.target);
@@ -30069,10 +30221,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 });
@@ -30130,13 +30291,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 = {}) {
@@ -30156,8 +30324,8 @@ 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);
+  const upEnv = { ...composeEnv, ...await prepareRuntimeEnvPassthrough(cwd, composeEnv, opts.vaultEnvMerge) };
   let up = sub(config.up.trim());
   if (opts.forceRecreate) up = appendForceRecreate(up);
   const identity = await resolveStageIdentity(cwd);
@@ -30170,8 +30338,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, ...upEnv }
   });
   const state = {
     pid: child2.pid ?? 0,
@@ -30182,7 +30349,13 @@ 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.
+    // #6345: the passthrough `COMPOSE_FILE` is omitted too. The override only ADDS container env to services
+    // the project file already declares, so `down` removes the same containers without it — and a later
+    // `stage stop` that resolved no secrets would otherwise die on the override's `${KEY:?}`.
+    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);
@@ -30190,7 +30363,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, upEnv);
     throw e;
   }
   const result = {
@@ -30221,7 +30394,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) {
@@ -30233,14 +30411,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 ?? {}
       });
     }
@@ -35957,7 +36134,17 @@ function registerStageCommands(program3) {
       return printLine(o.json ? JSON.stringify({ command: "stage stop", steps }, null, 2) : renderSteps("mmi-cli stage stop: dry-run plan", steps));
     }
     try {
-      const result = await stopStage({ cwd: process.cwd(), requiredIdentityCwd: process.cwd() });
+      let vaultEnvMerge;
+      try {
+        const { project: project2, cfg: stageCfg } = await resolveStage();
+        vaultEnvMerge = await fetchStageVaultEnvMerge(project2, stageCfg);
+      } catch {
+      }
+      const result = await stopStage({
+        cwd: process.cwd(),
+        requiredIdentityCwd: process.cwd(),
+        ...vaultEnvMerge ? { vaultEnvMerge } : {}
+      });
       printLine(o.json ? JSON.stringify(result) : `mmi-cli stage stop: ${result.message}`);
     } catch (e) {
       fail(`stage stop: ${e.message}`);
@@ -42461,6 +42648,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);
@@ -42494,6 +42705,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)) {
@@ -44223,11 +44436,55 @@ function resolveParseHint() {
     `Run \`mmi-cli ${path2} --help\` for its signature, \`mmi-cli explain ${path2} --json\` for exact detail, or \`mmi-cli commands\` for the task map.`
   ].join("\n");
 }
+function positionalCommandEntries(house) {
+  const acc = [];
+  const walk2 = (node) => {
+    if (commandMetadata(node)?.category !== "internal") {
+      const args = node.registeredArguments ?? [];
+      const path2 = commandPath2(node);
+      const canonical = path2 ? canonicalPathFor(path2) ?? path2 : "";
+      if (args[0] && canonical && (house === void 0 || houseForPath(canonical) === house)) {
+        acc.push({
+          path: canonical,
+          names: [node.name(), ...node.aliases()],
+          argName: args[0].name(),
+          ownFlags: commandOwnLongFlags(node)
+        });
+      }
+    }
+    for (const child2 of node.commands) walk2(child2);
+  };
+  for (const child2 of program2.commands) walk2(child2);
+  return acc;
+}
+function excessArgumentCorrection(extra, argv) {
+  const invoked = resolveCommandFromArgv(program2, [...argv]);
+  if (!invoked || extra.length !== 1) return void 0;
+  const canonical = canonicalPathFor(commandPath2(invoked)) ?? commandPath2(invoked);
+  const entries = positionalCommandEntries(houseForPath(canonical)).filter((e) => e.path !== canonical);
+  const sibling = siblingTakingPositional(invoked.name(), entries);
+  return sibling ? correctedPositionalCommand(sibling, extra[0], argv) : void 0;
+}
+var pendingHumanParseError;
+function writeHumanParseError(str) {
+  pendingHumanParseError = str;
+}
 function envelopeAwareWriteErr(str) {
   const plain = str.replace(/\[[0-9;]*m/g, "");
   if (plain.includes(PARSE_HINT_SENTINEL)) {
-    if (unknownFlagJsonHandled && argvWantsJson3()) return;
-    process.stderr.write(str.replace(PARSE_HINT_SENTINEL, resolveParseHint()));
+    if (unknownFlagJsonHandled && argvWantsJson3()) {
+      pendingHumanParseError = void 0;
+      return;
+    }
+    const hint = str.replace(PARSE_HINT_SENTINEL, resolveParseHint());
+    if (lastParseErrorKind === "bad-arguments") {
+      process.stderr.write(hint);
+      if (pendingHumanParseError) process.stderr.write(pendingHumanParseError);
+    } else {
+      if (pendingHumanParseError) process.stderr.write(pendingHumanParseError);
+      process.stderr.write(hint);
+    }
+    pendingHumanParseError = void 0;
     return;
   }
   lastParseErrorKind = classifyParseError(plain);
@@ -44235,7 +44492,7 @@ function envelopeAwareWriteErr(str) {
   const badChoice = parseInvalidChoiceError(plain);
   if (badChoice) {
     if (!argvWantsJson3()) {
-      process.stderr.write(str);
+      writeHumanParseError(str);
       return;
     }
     process.stderr.write(
@@ -44248,6 +44505,24 @@ function envelopeAwareWriteErr(str) {
     unknownFlagJsonHandled = true;
     return;
   }
+  const excess = parseExcessArgumentsError(plain);
+  if (excess) {
+    const argv = process.argv.slice(2);
+    const corrected = excessArgumentCorrection(excess.extra, argv);
+    const message2 = excessArgumentMessage(excess.extra, corrected);
+    if (argvWantsJson3()) {
+      process.stderr.write(
+        formatErrorEnvelope(message2, {
+          code: ERROR_CODES.ERR_EXCESS_ARGUMENT,
+          ...corrected ? { corrected_command: corrected } : {}
+        }) + "\n"
+      );
+      unknownFlagJsonHandled = true;
+      return;
+    }
+    writeHumanParseError(str.replace(/error: too many arguments[^\n]*/, `error: ${message2}`));
+    return;
+  }
   const match = /unknown option '([^']+)'/.exec(plain);
   if (match) {
     const flag = match[1];
@@ -44271,14 +44546,18 @@ function envelopeAwareWriteErr(str) {
       return;
     }
     if (positional) {
-      process.stderr.write(str.replace(/unknown option '[^']+'/, unknownTargetFlagMessage(flag, positional)));
+      writeHumanParseError(str.replace(/unknown option '[^']+'/, unknownTargetFlagMessage(flag, positional)));
       return;
     }
-    process.stderr.write(str);
+    writeHumanParseError(str);
     return;
   }
   if (unknownFlagJsonHandled && argvWantsJson3()) return;
-  process.stderr.write(str);
+  if (argvWantsJson3()) {
+    process.stderr.write(str);
+    return;
+  }
+  writeHumanParseError(str);
 }
 var INVOKED_ARGV3 = process.argv.slice(2);
 var program2 = new Command();

package/package.json

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