@mutmutco/cli 4.3.38 → 4.3.40

package/README.md

@@ -6,21 +6,23 @@ This package is published from [mutmutco/MMI-Hub](https://github.com/mutmutco/MM
 
 The CLI carries the org **Hub endpoint** intrinsically (override with the `MMI_HUB_URL` env var), so a product repo needs **no committed control-plane config** to reach the Hub — board coords, deploy coordinates, OAuth, and the secrets layout are all discovered from the Hub registry at runtime.
 
+Local stage recipes and printed plans use Bash on every platform. Windows requires Git Bash in its standard system or user installation, or `SHELL` set to the absolute `bash.exe` path. A missing Bash installation fails explicitly. Native Windows administration helpers remain independent of the stage shell.
+
 ## Install
 
-```powershell
+```bash
 npm install -g @mutmutco/cli
 ```
 
 Authenticate GitHub once for Hub session issuance and Project board operations:
 
-```powershell
+```bash
 gh auth login --hostname github.com --git-protocol https --web --scopes "project"
 ```
 
 Then verify the installed command:
 
-```powershell
+```bash
 mmi-cli --version
 mmi-cli doctor --json
 ```
@@ -79,7 +81,7 @@ they don't get re-derived or re-litigated per session:
 
 When working inside an `MMI-Hub` checkout before npm is available, use the committed bundle directly:
 
-```powershell
+```bash
 node cli/dist/index.cjs --version
 node cli/dist/index.cjs doctor --json
 ```

package/dist/main.cjs

@@ -4149,6 +4149,20 @@ var HOUSE_MAP = {
   onboard: "core"
   // repo-readiness orientation (front door — torn toward oracle, kept core)
 };
+var HOUSE_ALIASES = {
+  issue: ["devops"],
+  // filing/managing issues is oracle, but reads as shipping work
+  "issue create": ["devops"]
+};
+function isDeclaredHouseAlias(houseToken, lookupPath) {
+  const segments = lookupPath.split(" ");
+  for (let end = segments.length; end > 0; end -= 1) {
+    const key = segments.slice(0, end).join(" ");
+    const aliases = HOUSE_ALIASES[key];
+    if (aliases) return aliases.includes(houseToken);
+  }
+  return false;
+}
 function houseForPath(path2) {
   if (path2 === "") return "core";
   const segments = path2.split(" ");
@@ -5256,6 +5270,39 @@ function unknownCommandDomainGuide(parentPath, token) {
   return GUIDES.get(`${parentPath}:${token}`);
 }
 
+// src/verb-alias.ts
+var VERB_ALIAS_TABLE = [
+  // #6489: `board` has no `status` leaf (read|claim|show|move|done|doctor only); the read that
+  // answers "what is this issue/PR's board column" is `board show <ref>`.
+  { typed: ["oracle", "board", "status"], canonical: ["oracle", "board", "show"] },
+  { typed: ["board", "status"], canonical: ["board", "show"] },
+  // #6494: there is no top-level or housed `registry` command; org/registry project metadata is
+  // `oracle org project get`.
+  { typed: ["registry"], canonical: ["oracle", "org", "project", "get"] },
+  // #6486: filing/managing an issue reads as devops work (it ships something) but issues are oracle's
+  // live truth; the real command is `oracle issue create`. (A narrower house-token-only reroute for
+  // this same case may also exist elsewhere — this entry keeps the general table a complete answer on
+  // its own, not dependent on that mechanism landing.)
+  { typed: ["devops", "issue", "create"], canonical: ["oracle", "issue", "create"] }
+];
+var TABLE_BY_LENGTH = [...VERB_ALIAS_TABLE].sort((a, b) => b.typed.length - a.typed.length);
+function matchesAt(argv, start, tokens2) {
+  if (start + tokens2.length > argv.length) return false;
+  return tokens2.every((tok, i) => argv[start + i] === tok);
+}
+function applyVerbAlias(argv) {
+  const entry = TABLE_BY_LENGTH.find((e) => matchesAt(argv, 2, e.typed));
+  if (!entry) return void 0;
+  argv.splice(2, entry.typed.length, ...entry.canonical);
+  return { typed: entry.typed.join(" "), canonical: entry.canonical.join(" ") };
+}
+function resolveVerbAliasShim(argv) {
+  const hit = applyVerbAlias(argv);
+  if (!hit) return;
+  process.stderr.write(`mmi-cli: '${hit.typed}' is '${hit.canonical}' \u2014 ran it for you
+`);
+}
+
 // src/command-composition.ts
 var import_node_os22 = require("node:os");
 var import_node_path47 = require("node:path");
@@ -7195,6 +7242,50 @@ async function readRepoSurfaceLabels(repo, deps = {}) {
     return void 0;
   }
 }
+function surfaceWords(label) {
+  return label.slice(SURFACE_PREFIX.length).toLowerCase().split(/[-_]+/).filter(Boolean);
+}
+function pathWords(text) {
+  const words = [];
+  for (const hit of text.match(/[\w.-]+(?:\/[\w.-]+)+/g) ?? []) {
+    for (const segment of hit.split("/")) words.push(...segment.toLowerCase().split(/[-_.]+/).filter(Boolean));
+  }
+  return words;
+}
+function proseWords(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+function inferSurface(candidates, context = {}) {
+  const sorted = [...candidates].sort();
+  if (sorted.length === 0) throw new Error("inferSurface: no surface:* candidates to choose from");
+  const pWords = new Set(pathWords(context.body ?? ""));
+  const tWords = /* @__PURE__ */ new Set([...proseWords(context.title ?? ""), ...proseWords(context.body ?? "")]);
+  let best = sorted[0];
+  let bestScore = 0;
+  let bestFromPath = false;
+  for (const label of sorted) {
+    const words = surfaceWords(label);
+    if (!words.length) continue;
+    const pathHits = words.filter((w) => pWords.has(w)).length;
+    const proseHits = words.filter((w) => tWords.has(w)).length;
+    const score = pathHits * 2 + proseHits;
+    if (score > bestScore) {
+      bestScore = score;
+      best = label;
+      bestFromPath = pathHits > 0;
+    }
+  }
+  if (bestScore === 0) {
+    return {
+      label: sorted[0],
+      reason: `no path or title/body word matched any of ${sorted.length} surface label(s) \u2014 defaulted to the alphabetically-first`
+    };
+  }
+  return {
+    label: best,
+    reason: bestFromPath ? "matched a path mentioned in the issue body" : "matched a word in the issue title/body"
+  };
+}
 async function checkSurfaceRequirement(input, deps = {}) {
   if (input.waiver) {
     const reason = input.waiver.reason.trim();
@@ -7226,20 +7317,7 @@ async function checkSurfaceRequirement(input, deps = {}) {
   }
   if (known.length === 0) return { enforcing: false, taxonomyAbsent: true };
   if (labelsCarrySurface(input.labels)) return { enforcing: true };
-  const command = input.command ?? "issue create";
-  const where = input.rowLabel ? `${input.rowLabel}: ` : "";
-  return {
-    enforcing: true,
-    refusal: {
-      message: `${command}: ${where}${input.repo} requires every open issue to carry exactly one surface:* label, and this one sets none \u2014 filing it unlabeled reds the board check on every open PR in that repo. Pass --surface <value>, or --no-surface if this filing is genuinely exempt`,
-      payload: {
-        code: ERROR_CODES.ERR_MISSING_FLAG,
-        offending_flag: "--surface",
-        // Advisory, not a closed enum: the board rule is "exactly one surface:* label", whatever its value.
-        expected: [...known].sort()
-      }
-    }
-  };
+  return { enforcing: true, inferred: inferSurface(known, { title: input.title, body: input.body }) };
 }
 function conflictingSurfaceInputs(surfaceFlag, labels) {
   if (!surfaceFlag) return void 0;
@@ -12120,10 +12198,9 @@ async function postIssueComment(client, input) {
 
 // src/board-claim-move.ts
 var CLAIM_CONCURRENCY = 5;
-function withPowerShellChainHint(message2, platform2 = process.platform) {
-  if (platform2 !== "win32") return message2;
+function withGatedWriteChainHint(message2) {
   return `${message2}
-note: in PowerShell a ';' chain runs every statement regardless of the previous exit code, so the chain ran past this refusal \u2014 rerun the refused write solo or chain gated writes with '&&'`;
+note: run refused writes separately or join dependent commands with '&&'; a ';' chain continues after failure`;
 }
 function isArchivedItemRefusal(message2) {
   return /The item is archived and cannot be updated/i.test(message2);
@@ -12309,7 +12386,7 @@ async function claimOneBoardItem(ctx, selector, options) {
     }
     if (!options.force) {
       const refusal = laneContestMessage(item.ref, contest, "claim");
-      throw new Error(options.bulk ? refusal : withPowerShellChainHint(refusal));
+      throw new Error(options.bulk ? refusal : withGatedWriteChainHint(refusal));
     }
     previousHolder = displaced();
   };
@@ -12493,7 +12570,7 @@ async function unclaimBoardIssue(options, deps = {}) {
   const toStatus = options.toStatus ?? "Todo";
   if (!options.force && item.contentType === "Issue") {
     const contest = await checkLaneContest(client, item);
-    if (contest.contested) throw new Error(withPowerShellChainHint(laneContestMessage(item.ref, contest, "unclaim")));
+    if (contest.contested) throw new Error(withGatedWriteChainHint(laneContestMessage(item.ref, contest, "unclaim")));
   }
   try {
     await client.rest("DELETE", `repos/${item.repository}/issues/${item.number}/assignees`, {
@@ -15617,10 +15694,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.38",
-    tag: "v4.3.38",
-    commit: "da4541fdb81e",
-    npm: "@mutmutco/cli@4.3.38"
+    version: "4.3.40",
+    tag: "v4.3.40",
+    commit: "487948fabf28",
+    npm: "@mutmutco/cli@4.3.40"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15637,14 +15714,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.38"
+          v3Target: "v4.3.40"
         }
       ],
       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.38 and redeploy the Hub Lambda from tag v4.3.38 (da4541fdb81e); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.38 (@mutmutco/cli@4.3.38, tag commit da4541fdb81e \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.40 and redeploy the Hub Lambda from tag v4.3.40 (487948fabf28); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.40 (@mutmutco/cli@4.3.40, tag commit 487948fabf28 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -21645,13 +21722,9 @@ async function runTrainDoctor(input) {
     add(linked ? { code: "worktree-isolated", severity: "blocker", source: "local", title: `this is a linked worktree on ${currentBranch2 || "(detached)"}, not the lane's start branch ${startBranch} (#2770)`, remedy: `run the ${lane} lane from the primary checkout on ${startBranch}; a linked worktree never carries the train` } : { code: "branch-mismatch", severity: "blocker", source: "local", title: `on ${currentBranch2 || "(detached)"}; the ${lane} lane starts from ${startBranch}`, remedy: `git checkout ${startBranch}, then rerun; --heal never switches branches \u2014 the branch you stand on names the lane you meant, and healing it would run the train off a branch you did not pick (#6432)` });
   }
   const stage = laneStage(lane);
-  const workflowsRef = `origin/${startBranch ?? "main"}`;
-  const workflows = deps.readWorkflows(cwd, workflowsRef);
-  if (workflows === null) {
-    add({ code: "workflows-unreadable", severity: "blocker", source: "local", title: `.github/workflows at ${workflowsRef} could not be read from ${cwd} \u2014 the tag-addressability (#5428) and npm-major (#5666) preflights did not run`, remedy: `run from a checkout whose git can read ${workflowsRef} (fetch origin first), then rerun; an unread workflow set is unverified, not green` });
-  }
+  let missing = [];
   if (hints) {
-    const missing = [
+    missing = [
       ...!hints.hasDevelopmentBranch && lane !== "hotfix" ? ["development"] : [],
       ...!hints.hasMainBranch ? ["main"] : [],
       // #6318: a `--dev` release never reads, merges or tags rc — a missing rc branch cannot block it.
@@ -21659,30 +21732,38 @@ async function runTrainDoctor(input) {
     ];
     if (missing.length) add({ code: "bootstrap-gap", severity: "blocker", source: "origin", title: `train branch(es) missing on origin: ${missing.join(", ")}`, remedy: `bootstrap the repo train: \`mmi-cli devops bootstrap apply ${repo} --execute\` (from the MMI-Hub root), then rerun` });
   }
-  try {
-    const required = await discoverRequiredCheckContexts(train, ctx, stage);
-    if (required.length === 0) {
-      add({ code: "bootstrap-gap", severity: "warning", source: "origin", title: `no ruleset requires a status check on ${stage} \u2014 the train tags without a check wait (the GitHub push gate is the backstop)`, remedy: `activate the product ruleset: \`mmi-cli devops bootstrap apply ${repo} --execute\` (from the MMI-Hub root), or \`mmi-cli devops ci audit --repo ${repo}\`` });
-    } else {
-      try {
-        assertTagAddressableRequiredContexts({ readWorkflows: () => workflows }, required, repo);
-      } catch (e) {
-        add({ code: "contexts-not-tag-addressable", severity: "blocker", source: "local", title: `required ${stage} check(s) cannot materialize on a tag push (#5428)`, remedy: message(e) });
-      }
-      if (startBranch) {
-        const tip = await git3(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${startBranch}`]);
-        const checkRuns = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/check-runs`, "--jq", TRAIN_CHECK_RUNS_JQ]));
-        const statuses = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/status`, "--jq", TRAIN_COMMIT_STATUS_JQ]));
-        const observed = required.filter((c) => checkRuns.some((r) => r.name === c) || statuses.some((s) => s.context === c));
-        const red = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "failed");
-        const inFlight = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "pending");
-        const at = `${startBranch}@${tip.slice(0, 12)}`;
-        if (red.length) add({ code: "required-check-red", severity: "blocker", source: "origin", title: `required ${stage} check(s) failed on the lane's start branch tip: ${red.join(", ")} at ${at}`, remedy: `--heal never clears this one \u2014 a red trunk needs a fix, not a heal: land the failure's fix on ${startBranch} through a CI-gated PR, then rerun once its run is green (#6461)` });
-        else if (inFlight.length) add({ code: "required-check-red", severity: "warning", source: "origin", title: `required ${stage} check(s) still in flight on the lane's start branch tip: ${inFlight.join(", ")} at ${at}`, remedy: `wait for the run to conclude and rerun \u2014 the tip's verdict is not known yet, and the train would tag before it is` });
+  const startBranchMissing = startBranch != null && missing.includes(startBranch);
+  const workflowsRef = `origin/${startBranch ?? "main"}`;
+  const workflows = startBranchMissing ? null : deps.readWorkflows(cwd, workflowsRef);
+  if (workflows === null && !startBranchMissing) {
+    add({ code: "workflows-unreadable", severity: "blocker", source: "local", title: `.github/workflows at ${workflowsRef} could not be read from ${cwd} \u2014 the tag-addressability (#5428) and npm-major (#5666) preflights did not run`, remedy: `run from a checkout whose git can read ${workflowsRef} (fetch origin first), then rerun; an unread workflow set is unverified, not green` });
+  }
+  if (!startBranchMissing) {
+    try {
+      const required = await discoverRequiredCheckContexts(train, ctx, stage);
+      if (required.length === 0) {
+        add({ code: "bootstrap-gap", severity: "warning", source: "origin", title: `no ruleset requires a status check on ${stage} \u2014 the train tags without a check wait (the GitHub push gate is the backstop)`, remedy: `activate the product ruleset: \`mmi-cli devops bootstrap apply ${repo} --execute\` (from the MMI-Hub root), or \`mmi-cli devops ci audit --repo ${repo}\`` });
+      } else {
+        try {
+          assertTagAddressableRequiredContexts({ readWorkflows: () => workflows }, required, repo);
+        } catch (e) {
+          add({ code: "contexts-not-tag-addressable", severity: "blocker", source: "local", title: `required ${stage} check(s) cannot materialize on a tag push (#5428)`, remedy: message(e) });
+        }
+        if (startBranch) {
+          const tip = await git3(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${startBranch}`]);
+          const checkRuns = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/check-runs`, "--jq", TRAIN_CHECK_RUNS_JQ]));
+          const statuses = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/status`, "--jq", TRAIN_COMMIT_STATUS_JQ]));
+          const observed = required.filter((c) => checkRuns.some((r) => r.name === c) || statuses.some((s) => s.context === c));
+          const red = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "failed");
+          const inFlight = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "pending");
+          const at = `${startBranch}@${tip.slice(0, 12)}`;
+          if (red.length) add({ code: "required-check-red", severity: "blocker", source: "origin", title: `required ${stage} check(s) failed on the lane's start branch tip: ${red.join(", ")} at ${at}`, remedy: `--heal never clears this one \u2014 a red trunk needs a fix, not a heal: land the failure's fix on ${startBranch} through a CI-gated PR, then rerun once its run is green (#6461)` });
+          else if (inFlight.length) add({ code: "required-check-red", severity: "warning", source: "origin", title: `required ${stage} check(s) still in flight on the lane's start branch tip: ${inFlight.join(", ")} at ${at}`, remedy: `wait for the run to conclude and rerun \u2014 the tip's verdict is not known yet, and the train would tag before it is` });
+        }
       }
+    } catch (e) {
+      unverified(`required status checks on ${stage}`, e);
     }
-  } catch (e) {
-    unverified(`required status checks on ${stage}`, e);
   }
   let ledgerTag;
   let ledgerPath;
@@ -24606,7 +24687,7 @@ function ciReconcileExitFailed(input) {
   }
   return input.applyResults.some((result) => result.errors.length > 0 || result.postApply == null || result.postApply.state !== "clean" && result.postApply.state !== "repaired");
 }
-async function authoritativeSafetyHold(authority, deps, repo, baseBranch) {
+async function authoritativeSafetyHold(authority, deps, repo, baseBranch, meta) {
   if (authority.coversReleaseBranches) {
     const prOnly = authority.contexts.filter((context) => TRAIN_PR_ONLY_CONTEXTS.has(context));
     if (prOnly.length > 0) {
@@ -24620,6 +24701,22 @@ async function authoritativeSafetyHold(authority, deps, repo, baseBranch) {
   if (missing.length > 0) {
     return `${authority.source} requires context(s) with no pull_request workflow emitter [${missing.join(", ")}]; no source or live mutation was made`;
   }
+  if (authority.coversReleaseBranches) {
+    const track = resolveReleaseTrack(meta, void 0, repo);
+    const releaseBranches = branchesForTrack(track).filter((b) => b !== baseBranch);
+    const ignore = /* @__PURE__ */ new Set([...AGENT_PR_BOOKKEEPING_CONTEXTS, ...TRAIN_PR_ONLY_CONTEXTS]);
+    const requiredForReleaseBranches = authority.contexts.filter((context) => !ignore.has(context));
+    for (const branch of releaseBranches) {
+      if (await branchPresence(deps, repo, branch) !== true) continue;
+      const emittedThere = await resolveEmittedPrContexts(deps, repo, branch);
+      if (emittedThere === void 0) continue;
+      const emittedThereSet = new Set(emittedThere);
+      const unreachable = requiredForReleaseBranches.filter((context) => !emittedThereSet.has(context));
+      if (unreachable.length > 0) {
+        return `${authority.source} requires context(s) [${unreachable.join(", ")}] on ${branch}, but ${branch}'s own workflows emit none of them \u2014 a base-${branch} PR (e.g. a hotfix) could never satisfy the gate; no source or live mutation was made. Remove [${unreachable.join(", ")}] from ${branch} requirements, or add the emitting workflow to ${branch}`;
+      }
+    }
+  }
   return null;
 }
 async function applyCiReconcileRepo(repo, deps) {
@@ -24636,7 +24733,7 @@ async function applyCiReconcileRepo(repo, deps) {
       empty.errors.push(`${PRODUCT_RULESET_REF} is not parseable: ${e.message}`);
       return finalizeCiReconcile(repo, deps, empty, report);
     }
-    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch);
+    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch, meta);
     if (hold) {
       empty.skipped.push(hold);
       return finalizeCiReconcile(repo, deps, empty, report, hold);
@@ -24644,7 +24741,7 @@ async function applyCiReconcileRepo(repo, deps) {
   } else if (report.class === "deployable" && !report.explicitNoCi) {
     const registryAuthority = registryAuthorityWithoutReference(meta, repo);
     if (registryAuthority) {
-      const hold = await authoritativeSafetyHold(registryAuthority, deps, repo, baseBranch);
+      const hold = await authoritativeSafetyHold(registryAuthority, deps, repo, baseBranch, meta);
       if (hold) {
         empty.skipped.push(hold);
         return finalizeCiReconcile(repo, deps, empty, report, hold);
@@ -24673,7 +24770,7 @@ async function applyCiReconcileRepo(repo, deps) {
       result.errors.push(`${PRODUCT_RULESET_REF} is not parseable: ${e.message}`);
       return finalizeCiReconcile(repo, deps, result, report);
     }
-    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch);
+    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch, meta);
     if (hold) {
       result.skipped.push(hold);
       return finalizeCiReconcile(repo, deps, result, report, hold);
@@ -25859,7 +25956,7 @@ function registerBoardCommands(program3) {
     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));
+  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\nWhen using Windows PowerShell 5.1, avoid shell redirects: 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\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: "oracle board claim", issues: args[0] ?? [] })
@@ -29253,8 +29350,11 @@ function parseOauthVar(raw) {
   const out = {};
   for (const [key, value] of Object.entries(map)) {
     if (key === "subdomains" || key === "domains") {
-      if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || !v.trim())) {
-        throw new Error(`org project set: oauth.${key} must be an array of non-empty strings`);
+      const allowEmpty = key === "subdomains";
+      if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || v.trim() === "" && !(allowEmpty && v === ""))) {
+        throw new Error(
+          allowEmpty ? `org project set: oauth.${key} must be an array of strings ("" selects the apex \u2014 the domain itself)` : `org project set: oauth.${key} must be an array of non-empty strings`
+        );
       }
       out[key] = value.map((v) => v.trim());
     } else if (key === "callbackPath") {
@@ -29996,6 +30096,18 @@ function stageComposeFileEnv(files) {
 // src/stage-runner.ts
 var execFileP3 = (0, import_node_util5.promisify)(import_node_child_process11.execFile);
 var DOCKER_TIMEOUT_MS = 15e3;
+function stageBash() {
+  if (process.platform !== "win32") return "bash";
+  const configured = process.env.SHELL;
+  if (configured && (0, import_node_path27.isAbsolute)(configured) && /[/\\]bash(?:\.exe)?$/i.test(configured) && !/[/\\](?:System32|Sysnative)[/\\]bash(?:\.exe)?$/i.test(configured) && (0, import_node_fs28.existsSync)(configured)) return configured;
+  const candidates = [
+    (0, import_node_path27.join)(process.env.ProgramFiles || "C:\\Program Files", "Git", "bin", "bash.exe"),
+    ...process.env.LOCALAPPDATA ? [(0, import_node_path27.join)(process.env.LOCALAPPDATA, "Programs", "Git", "bin", "bash.exe")] : []
+  ];
+  const bash = candidates.find((path2) => (0, import_node_fs28.existsSync)(path2));
+  if (!bash) throw new Error("Local stages require Git Bash on Windows. Install Git for Windows or set SHELL to its absolute bash.exe path.");
+  return bash;
+}
 var EARLY_EXIT_GRACE_MS = 2e3;
 function earlyExitGraceMs() {
   if (process.env.NODE_ENV === "test") {
@@ -30186,24 +30298,6 @@ function mergeEnvSecretsIntoFile(content, secrets) {
   return body.endsWith("\n") ? body : `${body}
 `;
 }
-var POSIX_ONLY_VERBS = ["cp", "mv", "rm", "ln", "cat", "touch", "chmod", "export"];
-function posixOnlyShellProblems(command, field, platform2 = process.platform) {
-  if (platform2 !== "win32" || !command?.trim()) return [];
-  const problems = [];
-  if (/(^|&&|\||;)\s*[A-Za-z_][A-Za-z0-9_]*=\S/.test(command)) {
-    problems.push(
-      `stage.${field} uses POSIX inline env assignment (VAR=value command) which fails in cmd.exe on Windows; use 'set VAR=value && command' or a cross-platform launcher`
-    );
-  }
-  for (const verb of POSIX_ONLY_VERBS) {
-    if (new RegExp(`(^|&&|\\||;|\\()\\s*${verb}\\b`).test(command)) {
-      problems.push(
-        `stage.${field} calls POSIX '${verb}' which does not exist in cmd.exe on Windows; use the cmd/PowerShell equivalent or a cross-platform script`
-      );
-    }
-  }
-  return problems;
-}
 function validateStageConfig(config = {}, action) {
   const problems = [];
   if (action === "run" && !config.build?.trim() && !config.ensureEnv) problems.push("stage.build is required for stage run");
@@ -30211,8 +30305,6 @@ function validateStageConfig(config = {}, action) {
   if (config.healthUrl != null && config.healthUrl.trim() && !/^https?:\/\//.test(config.healthUrl.trim())) {
     problems.push("stage.healthUrl must be an http(s) URL");
   }
-  if (action === "run") problems.push(...posixOnlyShellProblems(config.build, "build"));
-  problems.push(...posixOnlyShellProblems(config.up, "up"));
   if (config.portRange != null) {
     const r = config.portRange;
     const ok = Array.isArray(r) && r.length === 2 && r.every((n) => Number.isInteger(n) && n >= 1024 && n <= 65535) && r[0] <= r[1];
@@ -30237,14 +30329,27 @@ function isPortFree(port) {
   });
 }
 async function shell(command, cwd, timeoutMs, env) {
-  await execFileP3(command, [], {
+  const execution = execFileP3(stageBash(), ["-c", command], {
     cwd,
-    shell: true,
-    timeout: timeoutMs,
+    timeout: process.platform === "win32" ? timeoutMs + 5e3 : timeoutMs,
     windowsHide: true,
     maxBuffer: 1024 * 1024 * 4,
     ...env ? { env: { ...process.env, ...env } } : {}
   });
+  let cleanup;
+  const timer = process.platform === "win32" ? setTimeout(() => {
+    cleanup = killTree(execution.child.pid ?? 0);
+  }, timeoutMs) : void 0;
+  try {
+    await execution;
+    if (cleanup) throw new Error(`stage command timed out after ${timeoutMs}ms`);
+  } catch (error) {
+    if (cleanup) throw new Error(`stage command timed out after ${timeoutMs}ms`, { cause: error });
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    await cleanup;
+  }
 }
 async function listDockerContainers() {
   const { stdout } = await execFileP3("docker", ["container", "ls", "--format", "{{json .}}"], {
@@ -30484,7 +30589,7 @@ async function cleanupStageState(state, paths, timeoutMs, fallbackCwd, currentEn
 async function killTree(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return;
   if (process.platform === "win32") {
-    await execFileP3("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }).catch(() => void 0);
+    await execFileP3("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: 5e3 }).catch(() => void 0);
     return;
   }
   try {
@@ -30550,6 +30655,7 @@ async function stopStage(opts = {}) {
   };
 }
 async function startStage(config = {}, opts = {}) {
+  const bash = stageBash();
   const problems = validateStageConfig(config, "start");
   if (problems.length) throw new Error(problems.join("; "));
   const cwd = opts.cwd ?? process.cwd();
@@ -30571,9 +30677,8 @@ async function startStage(config = {}, opts = {}) {
   let up = sub(config.up.trim());
   if (opts.forceRecreate) up = appendForceRecreate(up);
   const identity = await resolveStageIdentity(cwd);
-  const child2 = (0, import_node_child_process11.spawn)(up, {
+  const child2 = (0, import_node_child_process11.spawn)(bash, ["-c", up], {
     cwd,
-    shell: true,
     // POSIX-only: the process group exists for the group-kill in stopStage. On win32 teardown is
     // `taskkill /T /F` (no group needed), and detached+shell defeats windowsHide — every spawn would
     // flash a Windows Terminal window (0x800700e8) on dev machines.
@@ -30627,6 +30732,7 @@ function stageEnvRefusal(cwd) {
   return `stage refuses to run: .env file(s) present in the repo (${envFiles.join(", ")}) \u2014 secrets belong in the Hub vault; delete the file(s) and re-run (#5908)`;
 }
 async function runStage(config = {}, opts = {}) {
+  stageBash();
   const problems = validateStageConfig(config, "run");
   if (problems.length) throw new Error(problems.join("; "));
   const cwd = opts.cwd ?? process.cwd();
@@ -33492,18 +33598,33 @@ async function preflightBatchSurfaces(validated, rowRepo, options) {
   }
   if (options.noSurface) return [];
   const errors = [];
-  const cache = /* @__PURE__ */ new Map();
+  const censusCache = /* @__PURE__ */ new Map();
+  const censusFor = (repo) => {
+    let pending = censusCache.get(repo);
+    if (!pending) {
+      pending = readRepoSurfaceLabels(repo);
+      censusCache.set(repo, pending);
+    }
+    return pending;
+  };
   for (const { row, spec } of validated) {
+    if (labelsCarrySurface(spec.labels)) continue;
     const repo = rowRepo(spec);
-    const key = [repo, labelsCarrySurface(spec.labels) ? "has" : "none"].join("::");
-    let verdict = cache.get(key);
-    if (!verdict) {
-      verdict = await checkSurfaceRequirement({ repo, labels: spec.labels, command: "issue create --batch" });
-      cache.set(key, verdict);
-      if (verdict.warn) process.stderr.write(`${verdict.warn}
-`);
+    const known = await censusFor(repo);
+    if (known === void 0) {
+      process.stderr.write(
+        `warning: could not read ${repo}'s labels, so row ${row}'s surface-label requirement was not checked; if that board enforces one surface:* label per open issue, add one with \`mmi-cli oracle issue edit <n> --add-label surface:<value>\`
+`
+      );
+      continue;
     }
-    if (verdict.refusal) errors.push({ row, error: verdict.refusal.message });
+    if (known.length === 0) continue;
+    const inferred = inferSurface(known, { title: spec.title, body: spec.body });
+    spec.labels = [...spec.labels ?? [], inferred.label];
+    process.stderr.write(
+      `mmi-cli: no --surface given \u2014 row ${row} filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
+`
+    );
   }
   return errors;
 }
@@ -35597,8 +35718,8 @@ function registerSecretsCommands(program3) {
   const secrets = program3.command("secrets").description("project vault \u2014 project-admins self-serve their own repo's full tree (stageless + dev/rc/main); org-infra namespaces are master-gated");
   secrets.command("where").description("print where this repo's secrets live \u2014 the two-tier vault layout + well-known keys (no values)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((o) => withSecrets((d) => secretsWhere(d, o)));
   secrets.command("list").description("list secret NAMES + tier for THIS repo (never values). To locate a key you cannot place \u2014 including org-infra (_org) \u2014 use the cross-slug view: `mmi-cli oracle org access capabilities` (#3436)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((o) => withSecrets((d) => secretsList(d, o)));
-  secrets.command("find <intent>").description("resolve a plain-language intent to canonical secret names + the exact keyless-use command (master-only, #2244)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((intent, o) => withSecrets(async (d) => {
-    if (!await secretsFind(d, intent, o)) process.exitCode = 1;
+  secrets.command("find <intent...>").description("resolve a plain-language intent to canonical secret names + the exact keyless-use command (master-only, #2244); an unquoted multi-word intent is joined with spaces (#6495)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((intentWords, o) => withSecrets(async (d) => {
+    if (!await secretsFind(d, intentWords.join(" "), o)) process.exitCode = 1;
   }));
   secrets.command("catalog").description("the secret catalog \u2014 grouped, with each secret's exact keyless-use command (master-only, #2244)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--drift", "include the bidirectional reconciler drift report").option("--json", "machine-readable output").action((o) => withSecrets((d) => secretsCatalog(d, o)));
   secrets.command("doctor").description("vault drift report \u2014 declared-missing / orphan / off-scheme / duplicate (master-only, #2244)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((o) => withSecrets(async (d) => {
@@ -35922,8 +36043,8 @@ var import_node_fs34 = require("node:fs");
 var import_node_path31 = require("node:path");
 
 // src/stage-default.ts
-function shellFor(platform2 = process.platform) {
-  return platform2 === "win32" ? "powershell" : "bash";
+function shellFor() {
+  return "bash";
 }
 function isCentralContainerModel(model) {
   return model === "tenant-container" || model === "solo-container";
@@ -36394,7 +36515,7 @@ function registerStageCommands(program3) {
       fail(`stage stop: ${e.message}`);
     }
   });
-  stage.command("start").description("start the configured local stage process and optionally wait for health").option("--json", "machine-readable output").option("--apply", "start the configured stage.up process").option("--port <port>", "loopback port for this worktree stage (1024..65535)").option("--timeout-ms <ms>", "bounded health timeout", "60000").option("--allow-stale-env", "start despite a stale ensureEnv target file").action(async () => {
+  stage.command("start").description("start the configured local stage process and optionally wait for health").option("--json", "machine-readable output").option("--apply", "start the configured stage.up process in Bash (Git Bash on Windows)").option("--port <port>", "loopback port for this worktree stage (1024..65535)").option("--timeout-ms <ms>", "bounded health timeout", "60000").option("--allow-stale-env", "start despite a stale ensureEnv target file").action(async () => {
     const o = { json: rawFlag("--json"), apply: rawFlag("--apply"), timeoutMs: rawValue("--timeout-ms", "60000"), allowStaleEnv: rawFlag("--allow-stale-env") };
     const { resolution: res, project: project2, cfg: stageCfg } = await resolveStage();
     if (!o.apply) {
@@ -37080,8 +37201,20 @@ function matchedMandatoryGlobs(paths, mandatory) {
     return list.some((path2) => re.test(path2));
   });
 }
-function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, override = null, addedPaths = [] } = {}) {
+function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, override = null, addedPaths = [], structuralRefusal = false } = {}) {
   const configuredMandatoryCount = mandatoryGlobList(mandatory).length;
+  if (structuralRefusal) {
+    return {
+      configuredMandatoryCount,
+      matchedMandatoryGlobs: [],
+      matchedMandatoryCount: 0,
+      testCommandsAllowed: false,
+      editsExistingTest: false,
+      reasonId: "test-command-outside-mandatory-zone",
+      testCommandNote: null,
+      commandClasses: { allowed: [], refused: [TEST_COMMAND_CLASS] }
+    };
+  }
   if (!regulated) {
     return {
       configuredMandatoryCount: 0,
@@ -37090,25 +37223,30 @@ function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, overrid
       testCommandsAllowed: true,
       editsExistingTest: false,
       reasonId: null,
+      testCommandNote: null,
       commandClasses: { allowed: [TEST_COMMAND_CLASS], refused: [] }
     };
   }
   const matched = matchedMandatoryGlobs(paths, mandatory);
   const overrideAuthorizes = Array.isArray(override?.kinds) && override.kinds.includes(TEST_WORK_KIND);
   const existingTestEdited = editsExistingTest(paths, addedPaths);
-  const testCommandsAllowed = matched.length > 0 || overrideAuthorizes || existingTestEdited;
+  const inMandatoryZone = matched.length > 0 || overrideAuthorizes || existingTestEdited;
+  const testCommandsAllowed = true;
   return {
     configuredMandatoryCount,
     matchedMandatoryGlobs: matched,
     matchedMandatoryCount: matched.length,
     testCommandsAllowed,
-    /** #5842: true when the diff edits a test file that already existed — one of the facts that can
-     *  authorize the class, named so a refusal can say what was missing. */
+    /** #5842: true when the diff edits a test file that already existed — one of the facts that used
+     *  to authorize the class, kept for callers that still branch on it. */
     editsExistingTest: existingTestEdited,
-    reasonId: testCommandsAllowed ? null : "test-command-outside-mandatory-zone",
+    reasonId: null,
+    /** Informational only (#1166): set when the diff is outside the mandatory zone, so a caller can
+     *  note that CI does not require a test here — never a reason to refuse the run. */
+    testCommandNote: inMandatoryZone ? null : "test-command-outside-mandatory-zone",
     commandClasses: {
-      allowed: testCommandsAllowed ? [TEST_COMMAND_CLASS] : [],
-      refused: testCommandsAllowed ? [] : [TEST_COMMAND_CLASS]
+      allowed: [TEST_COMMAND_CLASS],
+      refused: []
     }
   };
 }
@@ -37778,7 +37916,12 @@ function runTestPolicy(root, deps = {}) {
     addedPaths: changed.filter((f) => f.status === "A" || f.status === "R").map((f) => f.path),
     mandatory: policy.mandatory,
     regulated: policy.declared !== false || policyRefusals.length > 0,
-    override: override && lookup.refusals.length === 0 ? { kinds: override.kinds } : null
+    override: override && lookup.refusals.length === 0 ? { kinds: override.kinds } : null,
+    // #1166: a still-blocking pre-diff finding (untrusted range, unresolvable base, a missing policy
+    // on the hotfix lane, a malformed trailer, an unwaived stale entry) means the diff itself was
+    // never evaluated — the mandatory-zone question this evaluator now answers permissively was
+    // never reached, so the refusal stands exactly as before.
+    structuralRefusal: blocking.length > 0
   });
   const result = {
     ok: findings.length === 0,
@@ -37792,6 +37935,7 @@ function runTestPolicy(root, deps = {}) {
     matchedMandatoryCount: commandPolicy.matchedMandatoryCount,
     testCommandsAllowed: commandPolicy.testCommandsAllowed,
     testCommandReasonId: commandPolicy.reasonId,
+    testCommandNote: commandPolicy.testCommandNote,
     commandClasses: commandPolicy.commandClasses
   };
   if (override) {
@@ -39808,7 +39952,7 @@ function registerCollaborationCommands(program3) {
   }
   const issue = program3.command("issue").description("issues \u2014 create and view with structured JSON (view; show, get and read alias view for board-verb/gh-shaped callers). Claims are board mutations: use `oracle board claim`, never `oracle issue claim` or the flat `board claim`");
   withExamples(mutating(
-    issue.command("create").description("create an issue (type \u2014 label) and print {number,url,label} JSON").addOption(new Option("--type <type>", "bug | feature | task (sets the matching label; required unless --batch)").choices([...ISSUE_TYPES])).option("--title <title>", "issue title").option("--title-file <path|->", "read the issue title from a UTF-8 file, or from stdin with -").option("--body <body>", "issue body (markdown)").option("--body-file <path|->", "read issue body from a UTF-8 file. `-` (stdin) needs a heredoc, which the agent inline-body guard denies (#1473/#2125) \u2014 prefer a real path; a title with backticks needs --title-file for the same reason (#3381)").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only \u2014 never a priority:* label, #416)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--label <label...>", "extra label(s) to attach (repeatable; auto-created if missing)").option("--surface <surface>", "issue surface, with or without the surface: prefix (#3789). Required when the target repo runs the one-surface-label board rule; any value satisfies it, so this is not a closed enum").option("--no-surface", "file without a surface label on a repo that requires one \u2014 for a genuinely exempt filing (e.g. a coop proof issue that spans every surface)").option("--parent <ref>", "file as a native sub-issue of this parent (#123, owner/repo#123, or URL)").option("--no-related", "skip the auto related-issues comment"),
+    issue.command("create").description("create an issue (type \u2014 label) and print {number,url,label} JSON").addOption(new Option("--type <type>", "bug | feature | task (sets the matching label; required unless --batch)").choices([...ISSUE_TYPES])).option("--title <title>", "issue title").option("--title-file <path|->", "read the issue title from a UTF-8 file, or from stdin with -").option("--body <body>", "issue body (markdown)").option("--body-file <path|->", "read issue body from a UTF-8 file. `-` (stdin) needs a heredoc, which the agent inline-body guard denies (#1473/#2125) \u2014 prefer a real path; a title with backticks needs --title-file for the same reason (#3381)").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only \u2014 never a priority:* label, #416)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--label <label...>", "extra label(s) to attach (repeatable; auto-created if missing)").option("--surface <surface>", "issue surface, with or without the surface: prefix (#3789). Any value satisfies the one-surface-label board rule, so this is not a closed enum. Omit it on an enforcing repo and one is inferred from the title/body (#1164) \u2014 the pick is printed and included in --json as surface_inferred/surface/surface_reason").option("--no-surface", "file without a surface label on a repo that requires one \u2014 for a genuinely exempt filing (e.g. a coop proof issue that spans every surface). Suppresses inference too").option("--parent <ref>", "file as a native sub-issue of this parent (#123, owner/repo#123, or URL)").option("--no-related", "skip the auto related-issues comment"),
     // --dry-run/--validate-only plan: resolve the same title source and validate the same type, priority,
     // and surface contract as the real action. A plan that echoes the title-file PATH instead of its value
     // is not a plan of the mutation that will run (#3914).
@@ -39832,14 +39976,24 @@ function registerCollaborationCommands(program3) {
       if (clash) fail(clash.message, clash.payload);
       const planRepo = opts.batch || surfaceWaived() ? void 0 : await resolveRepo(opts.repo);
       const surface = resolveCreateSurface(opts);
+      let planInferred;
       if (planRepo) {
-        const { refusal, warn } = await checkSurfaceRequirement({
+        const { refusal, warn, inferred } = await checkSurfaceRequirement({
           repo: planRepo,
-          labels: [...planLabels, ...surface ? [surface] : []]
+          labels: [...planLabels, ...surface ? [surface] : []],
+          title,
+          body: opts.body
         });
         if (warn) process.stderr.write(`${warn}
 `);
         if (refusal) fail(refusal.message, refusal.payload);
+        if (inferred && !surface) {
+          planInferred = inferred;
+          process.stderr.write(
+            `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
+`
+          );
+        }
       }
       return {
         command: "issue create",
@@ -39847,7 +40001,8 @@ function registerCollaborationCommands(program3) {
         title,
         priority,
         repo: opts.repo,
-        ...surface ? { surface } : {}
+        ...surface ? { surface } : {},
+        ...planInferred ? { surface_inferred: true, surface: planInferred.label, surface_reason: planInferred.reason } : {}
       };
     }
   ).action(async (o) => {
@@ -39859,6 +40014,7 @@ function registerCollaborationCommands(program3) {
     let extraLabels = [];
     let targetRepo2;
     let surfaceFlagLabel;
+    let surfaceInferred;
     try {
       issueType = resolveCreateType(o.type, "issue create", o.label);
       title = await resolveIssueTitle({ title: o.title, titleFile: o.titleFile }, { readFile: import_promises7.readFile, readStdin });
@@ -39890,8 +40046,8 @@ function registerCollaborationCommands(program3) {
       return fail(`issue create: ${e.message}`, e instanceof TextArgError ? { code: e.code, offending_flag: e.offendingFlag } : void 0);
     }
     {
-      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels });
-      const { refusal, warn } = surfaceCheck;
+      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels, title, body });
+      const { refusal, warn, inferred } = surfaceCheck;
       if (warn) process.stderr.write(`${warn}
 `);
       if (shouldWithdrawSurfaceFlag(surfaceCheck) && surfaceFlagLabel) {
@@ -39906,6 +40062,22 @@ function registerCollaborationCommands(program3) {
         });
         process.stderr.write(
           `warning: --surface ${surfaceFlagLabel} was dropped \u2014 ${targetRepo2} defines no surface:* labels, and creating one here would switch the one-surface-label rule on for every later filing in it. Use --label ${surfaceFlagLabel} if you really mean to start that taxonomy.
+`
+        );
+      }
+      if (inferred && !surfaceFlagLabel && !surfaceWaived()) {
+        extraLabels = [...extraLabels, inferred.label];
+        args = buildIssueArgs({
+          type: issueType,
+          title,
+          body,
+          priority,
+          repo: targetRepo2,
+          labels: extraLabels.length ? extraLabels : void 0
+        });
+        surfaceInferred = inferred;
+        process.stderr.write(
+          `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
 `
         );
       }
@@ -39946,7 +40118,9 @@ function registerCollaborationCommands(program3) {
         ...attached.resetAt ? { resetAt: attached.resetAt } : {},
         ...attached.resetEpochSeconds !== void 0 ? { resetEpochSeconds: attached.resetEpochSeconds } : {}
       } : {},
-      ...parentLinkFields(parent, parentLinkError)
+      ...parentLinkFields(parent, parentLinkError),
+      // #1164: surfaced so a caller can see (and override with --surface) a pick it never asked for.
+      ...surfaceInferred ? { surface_inferred: true, surface: surfaceInferred.label, surface_reason: surfaceInferred.reason } : {}
     }));
   }), [
     'mmi-cli oracle issue create --type task --title "Wire the schema"',
@@ -42091,7 +42265,7 @@ function registerDeveloperCommands(program3) {
     }
   });
   const tests = program3.command("tests").description("a repo's test-policy.json \u2014 the opt-in test contract and its enforcement");
-  tests.command("policy").description("enforce this repo's test-policy.json against the diff: a mandatory-zone change must carry a test, an unrequested new test file is refused, a `protected` test file may not be deleted or renamed away, and a `protected` entry naming a missing file is refused. Override any of them with a `Test-Policy-Override: <reason>` commit trailer (#3605)").option("--json", "machine-readable result: { ok, base, policySource: { ref, sha, path }, root, changedCount, mandatoryCount, matchedMandatoryCount, matchedMandatoryGlobs, testCommandsAllowed, commandClasses, findings[] }").option("--base <ref>", "comparison base (default: TEST_POLICY_BASE, then origin/development, then origin/main)").option("--policy-ref <commit>", "load test-policy.json from the exact fetched origin/development commit and audit its protected/satisfiedBy paths against that commit's tree, not this checkout; valid only with --base origin/main").addOption(new Option("--repo <owner/repo>", "not accepted \u2014 tests policy reads the current checkout").hideHelp()).action(async (o) => {
+  tests.command("policy").description("enforce this repo's test-policy.json against the diff: a mandatory-zone change must carry a test, an unrequested new test file is refused, a `protected` test file may not be deleted or renamed away, and a `protected` entry naming a missing file is refused. Override any of them with a `Test-Policy-Override: <reason>` commit trailer (#3605)").option("--json", "machine-readable result: { ok, base, policySource: { ref, sha, path }, root, changedCount, mandatoryCount, matchedMandatoryCount, matchedMandatoryGlobs, testCommandsAllowed, testCommandNote, commandClasses, findings[] }").option("--base <ref>", "comparison base (default: TEST_POLICY_BASE, then origin/development, then origin/main)").option("--policy-ref <commit>", "load test-policy.json from the exact fetched origin/development commit and audit its protected/satisfiedBy paths against that commit's tree, not this checkout; valid only with --base origin/main").addOption(new Option("--repo <owner/repo>", "not accepted \u2014 tests policy reads the current checkout").hideHelp()).action(async (o) => {
     try {
       if (o.repo) {
         const rerun = `mmi-cli tests policy${o.base ? ` --base ${o.base}` : ""}${o.policyRef ? ` --policy-ref ${o.policyRef}` : ""}${o.json ? " --json" : ""}`;
@@ -42114,7 +42288,7 @@ function registerDeveloperCommands(program3) {
         return;
       }
       if (result.ok) {
-        const commandVerdict = result.testCommandsAllowed ? "test commands: allowed" : `test commands: refused [${result.testCommandReasonId}] \u2014 resolved repo: ${result.root}; if that is not the repo under test, start the command with a literal Set-Location "<your worktree>"`;
+        const commandVerdict = result.testCommandsAllowed ? result.testCommandNote ? `test commands: allowed (informational [${result.testCommandNote}] \u2014 CI does not require a test here)` : "test commands: allowed" : `test commands: refused [${result.testCommandReasonId}] \u2014 resolved repo: ${result.root}; if that is not the repo under test, start the command with a literal Set-Location "<your worktree>"`;
         console.log(
           `tests policy: OK (${result.changedCount} changed file(s); ${result.matchedMandatoryCount} of ${result.mandatoryCount} mandatory glob(s) matched, ${result.protectedCount} protected file(s); ${commandVerdict}).`
         );
@@ -45050,8 +45224,7 @@ project.command("sync-info [owner/repo]").description("synchronize the owning Gi
     return failGraceful(e.message);
   }
 });
-var projectDeploy = project.command("deploy").description("read nonsecret DEPLOY# facts (domain, port, deploy path, substrate, host presence)");
-projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# facts for one project; defaults to the current repo").addOption(new Option("--stage <stage>", "dev | rc | main").choices(["dev", "rc", "main"])).option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+async function runProjectDeployGet(repoOrSlug, o) {
   const cfg = await loadConfig();
   let target;
   try {
@@ -45065,7 +45238,9 @@ projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# fa
   if (stage && !["dev", "rc", "main"].includes(stage)) return fail("org project deploy get: --stage must be dev, rc, or main");
   const payload = stage ? { slug: out.slug, stage, deploy: out.stages[stage] ?? null } : out;
   console.log(JSON.stringify(payload));
-});
+}
+var projectDeploy = project.command("deploy").description("read nonsecret DEPLOY# facts (domain, port, deploy path, substrate, host presence)").argument("[ownerRepo]", "shorthand for `get <owner/repo>`").addOption(new Option("--stage <stage>", "dev | rc | main").choices(["dev", "rc", "main"])).option("--json", "machine-readable output").action(async (ownerRepo, o) => runProjectDeployGet(ownerRepo, o));
+projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# facts for one project; defaults to the current repo").addOption(new Option("--stage <stage>", "dev | rc | main").choices(["dev", "rc", "main"])).option("--json", "machine-readable output").action(async (repoOrSlug, o) => runProjectDeployGet(repoOrSlug, o));
 projectDeploy.command("doctor").description("read-only estate scan for duplicate Hetzner (sshHost, port) DEPLOY# coordinates (#5431); master-only; never auto-reassigns ports").option("--json", "machine-readable output").action(async (o) => {
   const cfg = await loadConfig();
   const report = await fetchDeployPortCollisions(registryClientDeps(cfg));
@@ -45313,11 +45488,13 @@ oauth.command("plan", { isDefault: true }).description("print the canonical JS o
     oc = parseOauthConfig(meta ?? {}, slug);
   } catch (e) {
     const message2 = e.message;
+    const declareCommand = `mmi-cli oracle org project set ${o.repo ?? `mutmutco/${slug}`} --var 'oauth={"subdomains":["${defaultSubdomain(slug)}"],"callbackPath":"${DEFAULT_CALLBACK_PATH}"}'`;
     if (/^oauth is not configured for /.test(message2)) {
-      return failGraceful(
+      return failGracefulEnvelope(
         `org oauth plan: ${message2}. Declare it in the registry META first:
-  mmi-cli oracle org project set ${o.repo ?? `mutmutco/${slug}`} --var 'oauth={"subdomains":["${defaultSubdomain(slug)}"],"callbackPath":"${DEFAULT_CALLBACK_PATH}"}'
-  New repo? The GCP project and its Google Auth Platform consent screen must exist too \u2014 docs/Guides/oauth-provision.md \u2014 New repo.`
+  ${declareCommand}
+  New repo? The GCP project and its Google Auth Platform consent screen must exist too \u2014 docs/Guides/oauth-provision.md \u2014 New repo.`,
+        { code: ERROR_CODES.ERR_STATE_CONFLICT, corrected_command: declareCommand }
       );
     }
     return failGraceful(`org oauth plan: ${message2}`);
@@ -45704,6 +45881,14 @@ function resolveHouseShim(argv) {
     argv.splice(2, 1);
     return;
   }
+  if (actual && isDeclaredHouseAlias(houseToken, lookupPath)) {
+    process.stderr.write(
+      `mmi-cli: '${lookupPath}' lives in house '${actual}', not '${houseToken}' \u2014 routed to \`mmi-cli ${canonicalPathFor(lookupPath)}\`
+`
+    );
+    argv.splice(2, 1);
+    return;
+  }
   if (actual) {
     refuseHouseShim(
       lookupPath,
@@ -45732,6 +45917,7 @@ function printHouseRootHelp(house) {
   );
   consoleIo.log(lines2.join("\n"));
 }
+resolveVerbAliasShim(process.argv);
 resolveHouseShim(process.argv);
 program2.parseAsync(process.argv).then(() => finishCliRun()).catch((e) => failGraceful(e.message));
 // Annotate the CommonJS export names for ESM import in node:

package/package.json

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