@mutmutco/cli 4.3.27 → 4.3.29

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) {
@@ -11867,7 +11896,10 @@ function laneResumeEvidence(evidence) {
   return `prior claim by lane ${describeClaimMarker(evidence.marker)} (@${evidence.markerBy}, ${formatClaimAge(evidence.markerAgeMs)} old) is verifiably not running on this host \u2014 its local session transcript is gone or stale${artifacts.length ? `; resuming over ${artifacts.join("; ")}` : ""}`;
 }
 async function checkLaneContest(client, item, actor = describeSessionIdentity(), viewerLogin) {
-  const evidence = await gatherClaimLiveness(client, item.repository, item.number, openPullsFetcher(client));
+  let evidence = await gatherClaimLiveness(client, item.repository, item.number, openPullsFetcher(client));
+  if (evidence.failed.some((channel) => channel !== "session")) {
+    evidence = await gatherClaimLiveness(client, item.repository, item.number, openPullsFetcher(client));
+  }
   const ownership = laneOwnership(evidence.marker, actor);
   const sameOwner = Boolean(viewerLogin && evidence.markerBy && evidence.markerBy.toLowerCase() === viewerLogin.toLowerCase());
   const resume = ownership !== "mine" && sameOwner ? laneResumeEvidence(evidence) : void 0;
@@ -13963,11 +13995,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];
@@ -13988,6 +14022,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}`);
@@ -14002,12 +14048,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}`;
@@ -15535,10 +15584,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.27",
-    tag: "v4.3.27",
-    commit: "924b5a7761c4",
-    npm: "@mutmutco/cli@4.3.27"
+    version: "4.3.29",
+    tag: "v4.3.29",
+    commit: "5a5b64c2d604",
+    npm: "@mutmutco/cli@4.3.29"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15555,14 +15604,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.27"
+          v3Target: "v4.3.29"
         }
       ],
       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.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)"
+        mechanism: "npm dist-tag latest -> 4.3.29 and redeploy the Hub Lambda from tag v4.3.29 (5a5b64c2d604); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.29 (@mutmutco/cli@4.3.29, tag commit 5a5b64c2d604 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -23598,6 +23647,12 @@ function refPatternCovers(pattern, ref) {
 function uncoveredTrackBranches(liveIncludes, trackBranches) {
   return trackBranches.filter((branch) => !liveIncludes.some((pattern) => refPatternCovers(pattern, `refs/heads/${branch}`)));
 }
+function unreachableTrackBranches(uncovered, requiredContexts, emittedByBranch) {
+  return uncovered.filter((branch) => {
+    const emitted = emittedByBranch[branch];
+    return emitted !== void 0 && !requiredContexts.every((context) => emitted.includes(context));
+  });
+}
 function rulesetCoversReleaseBranches(payload, track) {
   const conditions = payload.conditions;
   const include = conditions?.ref_name?.include;
@@ -23899,14 +23954,19 @@ async function auditRepoCi(repo, deps) {
       }
     }
     if (productRuleset != null) {
-      const missingTrackBranches = [];
+      const presentTrackBranches = [];
       for (const branch of uncoveredTrackBranches(liveBranchIncludes, branchesForTrack(resolveReleaseTrack(meta, void 0, repo)))) {
-        if (await branchPresence(deps, repo, branch) === true) missingTrackBranches.push(branch);
+        if (await branchPresence(deps, repo, branch) === true) presentTrackBranches.push(branch);
       }
+      const emittedByTrackBranch = {};
+      for (const branch of presentTrackBranches) emittedByTrackBranch[branch] = await resolveEmittedPrContexts(deps, repo, branch);
+      const toleratedTrackBranches = unreachableTrackBranches(presentTrackBranches, liveContexts, emittedByTrackBranch);
+      const missingTrackBranches = presentTrackBranches.filter((branch) => !toleratedTrackBranches.includes(branch));
+      const toleratedNote = toleratedTrackBranches.length ? ` (tolerated until first release: [${toleratedTrackBranches.join(", ")}] \u2014 their trees cannot emit every one of [${liveContexts.join(", ")}], #6385)` : "";
       checks.push({
         ok: missingTrackBranches.length === 0,
         label: RULESET_TRACK_SCOPE_LABEL,
-        detail: missingTrackBranches.length ? `live ${PRODUCT_RULESET_NAME} includes [${liveBranchIncludes.join(", ")}] but the release track also requires [${missingTrackBranches.join(", ")}] \u2014 those branches tag and merge with no required check` : void 0,
+        detail: missingTrackBranches.length ? `live ${PRODUCT_RULESET_NAME} includes [${liveBranchIncludes.join(", ")}] but the release track also requires [${missingTrackBranches.join(", ")}] \u2014 those branches tag and merge with no required check${toleratedNote}` : toleratedNote ? toleratedNote.trim().replace(/^\(|\)$/g, "") : void 0,
         remediation: missingTrackBranches.length ? `mmi-cli oracle org project set ${repo} --var requiredCheckBranches=${JSON.stringify(branchesForTrack(resolveReleaseTrack(meta, void 0, repo)))} then mmi-cli devops bootstrap apply ${repo} --execute` : void 0
       });
     }
@@ -28959,7 +29019,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 = {};
@@ -28973,14 +29033,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;
@@ -29180,7 +29248,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"]',
@@ -29652,6 +29720,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;
@@ -30017,6 +30130,36 @@ function stageComposeEnv(config, stagePort, vaultEnvMerge, cwd) {
     ...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);
@@ -30196,6 +30339,7 @@ async function startStage(config = {}, opts = {}) {
   if (!opts.envPrepared) await ensureStageRuntimeEnv(config, opts, cwd);
   if (stagePort != null && portGuard) await ensureStagePortAvailable(stagePort, cwd, portGuard);
   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);
@@ -30208,7 +30352,7 @@ async function startStage(config = {}, opts = {}) {
     detached: process.platform !== "win32",
     windowsHide: true,
     stdio: "ignore",
-    env: { ...process.env, ...composeEnv }
+    env: { ...process.env, ...upEnv }
   });
   const state = {
     pid: child2.pid ?? 0,
@@ -30222,6 +30366,9 @@ async function startStage(config = {}, opts = {}) {
     // #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);
@@ -30230,7 +30377,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, composeEnv);
+    await cleanupStageState(state, [statePath, globalStatePath], opts.timeoutMs ?? 6e4, cwd, upEnv);
     throw e;
   }
   const result = {
@@ -36001,7 +36148,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}`);
@@ -44293,11 +44450,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);
@@ -44305,7 +44506,7 @@ function envelopeAwareWriteErr(str) {
   const badChoice = parseInvalidChoiceError(plain);
   if (badChoice) {
     if (!argvWantsJson3()) {
-      process.stderr.write(str);
+      writeHumanParseError(str);
       return;
     }
     process.stderr.write(
@@ -44318,6 +44519,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];
@@ -44341,14 +44560,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.27",
+  "version": "4.3.29",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",