@mutmutco/cli 4.4.5 → 4.4.7

package/dist/main.cjs

@@ -1112,6 +1112,7 @@ var init_cli_shared = __esm({
 // src/board-write.ts
 var board_write_exports = {};
 __export(board_write_exports, {
+  addIssueToProjectViaHub: () => addIssueToProjectViaHub,
   writeHubBoardField: () => writeHubBoardField
 });
 async function writeHubBoardField(request) {
@@ -1125,6 +1126,18 @@ async function writeHubBoardField(request) {
   const body = await res.json().catch(() => null);
   if (!res.ok || body?.updated !== true) throw new Error(`board field write HTTP ${res.status}: ${body?.error ?? "unconfirmed result"}`);
 }
+async function addIssueToProjectViaHub(cfg, contentNodeId) {
+  const config = await loadConfig();
+  const res = await fetch(`${config.sagaApiUrl?.replace(/\/$/, "")}/board/attach`, {
+    method: "POST",
+    headers: await hubHeaders({ "content-type": "application/json" }),
+    body: JSON.stringify({ projectId: cfg.projectId, contentNodeId }),
+    signal: AbortSignal.timeout(25e3)
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !body?.itemId) throw new Error(`board attach HTTP ${res.status}: ${body?.error ?? "unconfirmed result"}`);
+  return body.itemId;
+}
 var init_board_write = __esm({
   "src/board-write.ts"() {
     "use strict";
@@ -7288,37 +7301,71 @@ function pathWords(text) {
 function proseWords(text) {
   return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
 }
+function countWords(words) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const w of words) counts.set(w, (counts.get(w) ?? 0) + 1);
+  return counts;
+}
+var TITLE_WEIGHT = 3;
+var PATH_WEIGHT = 4;
+var BODY_WEIGHT = 1;
 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 ?? "")]);
+  const titleCounts = countWords(proseWords([context.title ?? "", context.type ?? ""].join(" ")));
+  const pathCounts = countWords(pathWords(context.body ?? ""));
+  const bodyCounts = countWords(proseWords(context.body ?? ""));
+  const scoreOf = (label) => {
+    let score = 0;
+    let fromPath = false;
+    let fromTitle = false;
+    for (const word of surfaceWords(label)) {
+      const title = titleCounts.get(word) ?? 0;
+      const path2 = pathCounts.get(word) ?? 0;
+      const body = bodyCounts.get(word) ?? 0;
+      if (title > 0) fromTitle = true;
+      if (path2 > 0) fromPath = true;
+      score += title * TITLE_WEIGHT + path2 * PATH_WEIGHT + body * BODY_WEIGHT;
+    }
+    return { score, fromPath, fromTitle };
+  };
   let best = sorted[0];
   let bestScore = 0;
   let bestFromPath = false;
+  let bestFromTitle = false;
+  const scores = /* @__PURE__ */ new Map();
   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;
+    const { score, fromPath, fromTitle } = scoreOf(label);
+    scores.set(label, score);
     if (score > bestScore) {
       bestScore = score;
       best = label;
-      bestFromPath = pathHits > 0;
+      bestFromPath = fromPath;
+      bestFromTitle = fromTitle;
     }
   }
-  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`
-    };
-  }
+  const tied = sorted.filter((label) => (scores.get(label) ?? 0) === bestScore);
+  const uncertain = bestScore === 0 || bestScore < TITLE_WEIGHT || tied.length > 1;
+  const alternatives = uncertain ? sorted.filter((label) => label !== best && (scores.get(label) ?? 0) > 0).sort((a, b) => (scores.get(b) ?? 0) - (scores.get(a) ?? 0) || (a < b ? -1 : a > b ? 1 : 0)).slice(0, 3) : [];
+  const reason = bestScore === 0 ? `no path or title/body word matched any of ${sorted.length} surface label(s) \u2014 defaulted to the alphabetically-first` : bestFromPath ? "matched a path mentioned in the issue body" : bestFromTitle ? "matched a word in the issue title/body" : "matched a word in the issue body";
   return {
     label: best,
-    reason: bestFromPath ? "matched a path mentioned in the issue body" : "matched a word in the issue title/body"
+    reason,
+    ...uncertain ? { uncertain: true } : {},
+    ...alternatives.length ? { alternatives } : {}
   };
 }
+function surfaceInferenceSuffix(inferred) {
+  if (!inferred.uncertain) return "";
+  const alts = inferred.alternatives?.length ? ` Other candidates: ${inferred.alternatives.join(", ")}.` : "";
+  return ` This pick is low-confidence \u2014 pass --surface <value> to choose explicitly.${alts}`;
+}
+function surfaceInferenceNote(inferred) {
+  const base = `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}).`;
+  return inferred.uncertain ? `${base}${surfaceInferenceSuffix(inferred)}
+` : `${base} Pass --surface to choose.
+`;
+}
 async function checkSurfaceRequirement(input, deps = {}) {
   if (input.waiver) {
     const reason = input.waiver.reason.trim();
@@ -7350,7 +7397,7 @@ async function checkSurfaceRequirement(input, deps = {}) {
   }
   if (known.length === 0) return { enforcing: false, taxonomyAbsent: true };
   if (labelsCarrySurface(input.labels)) return { enforcing: true };
-  return { enforcing: true, inferred: inferSurface(known, { title: input.title, body: input.body }) };
+  return { enforcing: true, inferred: inferSurface(known, { title: input.title, type: input.type, body: input.body }) };
 }
 function conflictingSurfaceInputs(surfaceFlag, labels) {
   if (!surfaceFlag) return void 0;
@@ -11114,11 +11161,24 @@ mutation($projectId: ID!, $itemId: ID!) {
 async function updateItemSingleSelect(client, projectId, itemId, fieldId, optionId) {
   try {
     await client.graphql(UPDATE_ITEM_FIELD_MUTATION, { projectId, itemId, fieldId, optionId });
+    return { credential: "user" };
   } catch (error) {
     const errors = error.graphqlErrors;
-    if (!errors?.length || !errors.every((entry) => entry.type === "INSUFFICIENT_SCOPES")) throw error;
-    const { writeHubBoardField: writeHubBoardField2 } = await Promise.resolve().then(() => (init_board_write(), board_write_exports));
-    await writeHubBoardField2({ projectId, itemId, fieldId, optionId });
+    if (errors?.length && errors.every((entry) => entry.type === "INSUFFICIENT_SCOPES")) {
+      const { writeHubBoardField: writeHubBoardField2 } = await Promise.resolve().then(() => (init_board_write(), board_write_exports));
+      await writeHubBoardField2({ projectId, itemId, fieldId, optionId });
+      return { credential: "app_installation" };
+    }
+    if (isGitHubRateLimitError(error)) {
+      const { writeHubBoardField: writeHubBoardField2 } = await Promise.resolve().then(() => (init_board_write(), board_write_exports));
+      try {
+        await writeHubBoardField2({ projectId, itemId, fieldId, optionId });
+        return { credential: "app_installation" };
+      } catch {
+        throw error;
+      }
+    }
+    throw error;
   }
 }
 function parseIssueSelector(selector, defaultRepo, expectedRepo) {
@@ -12361,8 +12421,9 @@ async function moveBoardItem(options, deps = {}) {
     throw boardNotFoundError(`${selector.repo}#${selector.number}`, { owner: cfg.projectOwner, number: cfg.projectNumber });
   }
   const optionId = cfg.statusOptions[options.status];
+  let credential = "user";
   try {
-    await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, optionId);
+    ({ credential } = await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, optionId));
   } catch (e) {
     if (options.status === "Done" && isArchivedItemRefusal(ghError(e))) {
       return {
@@ -12384,7 +12445,9 @@ async function moveBoardItem(options, deps = {}) {
     viewer: lookup.viewer,
     repo: currentRepo,
     status: options.status,
-    partial: false
+    partial: false,
+    credential
+    // #6834: which credential served the write — the user token or the Hub App leg.
   };
 }
 async function resolveClaimWritable(collected, client, snapshot, unscanned) {
@@ -12550,8 +12613,9 @@ async function claimOneBoardItem(ctx, selector, options) {
     throw new Error(`claim failed before board status changed: ${ghError(e)}`);
   }
   await postClaimMarkerComment(client, item, ctx.session);
+  let credential = "user";
   try {
-    await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, cfg.statusOptions["In Progress"]);
+    ({ credential } = await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, cfg.statusOptions["In Progress"]));
   } 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);
@@ -12568,6 +12632,7 @@ async function claimOneBoardItem(ctx, selector, options) {
     repo: report.repo,
     status: "In Progress",
     partial: false,
+    credential,
     ...claimedReceipt()
   };
 }
@@ -12601,7 +12666,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, reclaimedFrom: result.reclaimedFrom, alreadyClaimed: result.alreadyClaimed, renewed: result.renewed, 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, renewed: result.renewed, checked: result.checked, credential: result.credential };
       } catch (e) {
         results[index] = { ref, claimed: false, reason: e.message };
       }
@@ -12661,13 +12726,14 @@ async function moveBoardIssues(options, deps = {}) {
       const idx = next++;
       const { item, ref, index: resultIdx } = resolvedList[idx];
       try {
-        await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, statusOptionId);
+        const { credential } = await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, statusOptionId);
         results[resultIdx] = {
           ref,
           moved: true,
           item: { ...item, status: options.status, statusOptionId },
           status: options.status,
-          partial: false
+          partial: false,
+          credential
         };
       } catch (e) {
         const warning = `partial move: ${ref} status was not changed to ${options.status} (${ghError(e)})`;
@@ -12734,8 +12800,9 @@ async function unclaimBoardIssue(options, deps = {}) {
     return { item, viewer, repo: currentRepo, status: item.status, partial: true, warning };
   }
   const optionId = cfg.statusOptions[toStatus];
+  let unclaimCredential = "user";
   try {
-    await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, optionId);
+    ({ credential: unclaimCredential } = await updateItemSingleSelect(client, cfg.projectId, item.itemId, cfg.statusFieldId, optionId));
   } catch (e) {
     const warning = `partial unclaim: ${item.ref} status was not changed to ${toStatus} (${ghError(e)})`;
     if (!options.allowPartial) throw new Error(warning);
@@ -12746,7 +12813,8 @@ async function unclaimBoardIssue(options, deps = {}) {
     viewer,
     repo: currentRepo,
     status: toStatus,
-    partial: false
+    partial: false,
+    credential: unclaimCredential
   };
 }
 async function setBoardItemPriority(client, cfg, itemId, priority) {
@@ -15870,10 +15938,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.4.5",
-    tag: "v4.4.5",
-    commit: "202cb38f947b",
-    npm: "@mutmutco/cli@4.4.5"
+    version: "4.4.7",
+    tag: "v4.4.7",
+    commit: "f0781ed0cbda",
+    npm: "@mutmutco/cli@4.4.7"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15890,14 +15958,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.4.5"
+          v3Target: "v4.4.7"
         }
       ],
       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.4.5 and redeploy the Hub Lambda from tag v4.4.5 (202cb38f947b); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.4.5 (@mutmutco/cli@4.4.5, tag commit 202cb38f947b \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.4.7 and redeploy the Hub Lambda from tag v4.4.7 (f0781ed0cbda); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.4.7 (@mutmutco/cli@4.4.7, tag commit f0781ed0cbda \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -22814,6 +22882,62 @@ async function waitForFoldIndexLock(deps, startBranch, resumeCommand) {
     await sleep2(Math.min(GIT_INDEX_LOCK_POLL_MS, Math.max(1, deadline - now())));
   }
 }
+function isIndexLockFailure(message2) {
+  return /index\.lock/i.test(message2) && /File exists/i.test(message2);
+}
+async function clearFoldChildIndexLock(deps) {
+  const lockPath = requireValue(
+    clean2(await deps.run("git", ["rev-parse", "--git-path", "index.lock"])),
+    "git index lock path"
+  );
+  try {
+    await (0, import_promises3.unlink)(lockPath);
+  } catch (e) {
+    if (e.code === "ENOENT") return void 0;
+    throw e;
+  }
+  return lockPath;
+}
+async function resetFoldMainWithStaleLockRetry(deps, preFoldMainSha, killedCause) {
+  try {
+    await deps.run("git", ["reset", "--hard", preFoldMainSha]);
+    return { ok: true, lockNote: "" };
+  } catch (firstError) {
+    const firstMessage = firstError instanceof Error ? firstError.message : String(firstError);
+    if (!isIndexLockFailure(firstMessage)) return { ok: false, error: firstError, lockNote: "" };
+    if (!foldChildWasKilled(killedCause)) {
+      return {
+        ok: false,
+        error: firstError,
+        lockNote: "the git index lock was NOT removed \u2014 no killed fold child is attributable, so its holder may still be alive (resolve or wait it out, then retry)"
+      };
+    }
+    let clearedLockPath;
+    try {
+      clearedLockPath = await clearFoldChildIndexLock(deps);
+    } catch (e) {
+      return {
+        ok: false,
+        error: firstError,
+        lockNote: `the fold child's stale git index lock could not be removed: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+    if (!clearedLockPath) return { ok: false, error: firstError, lockNote: "" };
+    try {
+      await deps.run("git", ["reset", "--hard", preFoldMainSha]);
+      return {
+        ok: true,
+        lockNote: `removed the stale git index lock ${clearedLockPath} left by the fold child the train killed (signal), then retried the reset`
+      };
+    } catch (retryError) {
+      return {
+        ok: false,
+        error: retryError,
+        lockNote: `removed the stale git index lock ${clearedLockPath} left by the fold child the train killed (signal) and retried the reset once, which failed again`
+      };
+    }
+  }
+}
 async function recoverFailedRcand(deps, cause, preRcSha) {
   const causeMessage = cause instanceof Error ? cause.message : String(cause);
   const branch = await currentBranch(deps).catch(() => "");
@@ -22857,10 +22981,13 @@ Recovery sequence:
   3. mmi-cli devops rcand --apply`
   );
 }
+function foldChildWasKilled(causeMessage) {
+  return /\bSIGTERM\b|was killed \(signal/.test(causeMessage);
+}
 function foldFailureAnchor(causeMessage) {
-  if (/\bSIGTERM\b|was killed \(signal/.test(causeMessage)) return "docs/Guides/train-troubleshooting.md#fold-npm-ci-sigterm";
-  if (/\bEPERM\b|\bEBUSY\b/.test(causeMessage)) return "docs/Guides/train-troubleshooting.md#fold-eperm-ebusy";
-  if (/^(?:npm|node) .* failed\b/.test(causeMessage)) return "docs/Guides/train-troubleshooting.md#fold-lifecycle-script";
+  if (foldChildWasKilled(causeMessage)) return troubleshootingAnchor("fold-npm-ci-sigterm");
+  if (/\bEPERM\b|\bEBUSY\b/.test(causeMessage)) return troubleshootingAnchor("fold-eperm-ebusy");
+  if (/^(?:npm|node) .* failed\b/.test(causeMessage)) return troubleshootingAnchor("fold-lifecycle-script");
   return void 0;
 }
 async function recoverFailedFold(deps, cause, startBranch, preFoldMainSha, resumeCommand) {
@@ -22889,13 +23016,12 @@ fold failed with an in-progress merge; automatic \`git merge --abort\` failed: $
   if (probe.branch === "main" && preFoldMainSha) {
     const mainDescendsFromPreFold = await deps.run("git", ["merge-base", "--is-ancestor", preFoldMainSha, "main"]).then(() => true).catch(() => false);
     if (mainDescendsFromPreFold) {
-      try {
-        await deps.run("git", ["reset", "--hard", preFoldMainSha]);
-      } catch (e) {
+      const attempt = await resetFoldMainWithStaleLockRetry(deps, preFoldMainSha, rawCause);
+      if (!attempt.ok) {
         return foldFailureGuidance(
           `${causeMessage}
 
-fold failed after this run's merge/fold committed locally on main; automatic \`git reset --hard ${shaLabel(preFoldMainSha)}\` failed: ${e instanceof Error ? e.message : String(e)}.`,
+fold failed after this run's merge/fold committed locally on main; automatic \`git reset --hard ${shaLabel(preFoldMainSha)}\` failed: ${attempt.error instanceof Error ? attempt.error.message : String(attempt.error)}${attempt.lockNote ? `; ${attempt.lockNote}` : ""}.`,
           await probeFoldFailureState(deps),
           startBranch,
           preFoldMainSha,
@@ -22910,7 +23036,7 @@ fold failed after this run's merge/fold committed locally on main; automatic \`g
         startBranch,
         preFoldMainSha,
         resumeCommand,
-        `local main was reset to its pre-fold state ${shaLabel(preFoldMainSha)} (discarding only this run's merge/fold commit(s) at ${shaLabel(probe.mainSha)})${aheadNote}`
+        `local main was reset to its pre-fold state ${shaLabel(preFoldMainSha)} (discarding only this run's merge/fold commit(s) at ${shaLabel(probe.mainSha)})${attempt.lockNote ? `; ${attempt.lockNote}` : ""}${aheadNote}`
       );
     }
   }
@@ -33529,10 +33655,10 @@ function formatOwnDetail(cmd) {
     }
     lines2.push("");
   }
-  const ownOptions = cmd.options.filter((opt) => opt.flags !== "--help" && opt.flags !== "-V, --version");
-  if (ownOptions.length) {
+  const ownOptions2 = cmd.options.filter((opt) => opt.flags !== "--help" && opt.flags !== "-V, --version");
+  if (ownOptions2.length) {
     lines2.push("Options:");
-    for (const opt of ownOptions) {
+    for (const opt of ownOptions2) {
       const tags = [];
       if (opt.mandatory) tags.push("required");
       if (opt.default !== void 0) tags.push(`default: ${JSON.stringify(opt.default)}`);
@@ -33594,6 +33720,56 @@ function formatExplainLoop(playbook) {
   }
   return lines2.join("\n");
 }
+function ownOptions(cmd) {
+  return cmd.options.filter((opt) => opt.flags !== "--help" && opt.flags !== "-V, --version");
+}
+function briefCommand(cmd) {
+  return {
+    path: cmd.path,
+    ...cmd.description ? { description: cmd.description } : {},
+    arguments: cmd.arguments.map((arg) => ({
+      name: arg.name,
+      required: arg.required,
+      ...arg.variadic ? { variadic: true } : {},
+      ...arg.description ? { description: arg.description } : {}
+    })),
+    options: ownOptions(cmd).map((opt) => ({
+      flags: opt.flags,
+      takesValue: opt.takesValue,
+      ...opt.mandatory ? { required: true } : {},
+      ...opt.description ? { description: opt.description } : {}
+    }))
+  };
+}
+function explainBriefManifest(manifest, command) {
+  return {
+    schema_version: 1,
+    scope: "command",
+    brief: true,
+    name: manifest.name,
+    ...manifest.version ? { version: manifest.version } : {},
+    command: briefCommand(command),
+    ...command.subcommands.length ? { children: command.subcommands.map(briefCommand) } : {}
+  };
+}
+function formatExplainBrief(cmd, rootName) {
+  const lines2 = [`${rootName} ${cmd.path}${cmd.description ? ` \u2014 ${cmd.description}` : ""}`];
+  for (const arg of cmd.arguments) {
+    const flag = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+    lines2.push(`  ${flag}  ${arg.required ? "required" : "optional"}${arg.description ? `  ${arg.description}` : ""}`);
+  }
+  for (const opt of ownOptions(cmd)) {
+    lines2.push(`  ${opt.flags}  ${opt.takesValue ? "takes-value" : "flag"}${opt.mandatory ? " required" : ""}${opt.description ? `  ${opt.description}` : ""}`);
+  }
+  for (const child2 of cmd.subcommands) {
+    const args = child2.arguments.map((arg) => arg.required ? `<${arg.name}>` : `[${arg.name}]`).join(" ");
+    lines2.push(`${child2.path}${args ? ` ${args}` : ""}${child2.description ? ` \u2014 ${child2.description}` : ""}`);
+    for (const opt of ownOptions(child2)) {
+      lines2.push(`  ${opt.flags}  ${opt.takesValue ? "takes-value" : "flag"}${opt.mandatory ? " required" : ""}${opt.description ? `  ${opt.description}` : ""}`);
+    }
+  }
+  return lines2.join("\n");
+}
 function catalogCommandPaths(manifest) {
   const acc = [];
   const walk2 = (command) => {
@@ -33728,7 +33904,7 @@ function findCommandInManifest(manifest, commandPath3) {
   return visit(manifest.tree);
 }
 function registerExplainCommand(program3) {
-  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).option("--json", "machine-readable focused command, route, or loop detail").option("--out <path>", "write the output to a UTF-8 file instead of stdout (#5802 byte contract)").option("--recursive", "include full schemas for immediate children (default: compact child index)").option("--full", "alias for --recursive").action((commandArgs, opts) => {
+  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).option("--json", "machine-readable focused command, route, or loop detail").option("--brief", "compact per-verb flags, value requirements, and one-line descriptions (no schemas or prose)").option("--out <path>", "write the output to a UTF-8 file instead of stdout (#5802 byte contract)").option("--recursive", "include full schemas for immediate children (default: compact child index)").option("--full", "alias for --recursive").action((commandArgs, opts) => {
     const emit = (output) => {
       if (!opts.out) console.log(output);
       else console.log(`Wrote explain output to ${opts.out} (UTF-8, ${writeUtf8Receipt(opts.out, output)} bytes)`);
@@ -33767,6 +33943,10 @@ function registerExplainCommand(program3) {
       return;
     }
     const recursive = Boolean(opts.recursive || opts.full);
+    if (opts.brief) {
+      emit(opts.json ? JSON.stringify(explainBriefManifest(manifest, command), null, 2) : formatExplainBrief(command, manifest.name));
+      return;
+    }
     emit(opts.json ? JSON.stringify(explainCommandManifest(manifest, command, { recursive }), null, 2) : command.subcommands.length ? formatExplainGroup(command, manifest.name) : formatExplainCommand(command, manifest.name));
   });
 }
@@ -34438,10 +34618,10 @@ async function preflightBatchSurfaces(validated, rowRepo, options) {
       continue;
     }
     if (known.length === 0) continue;
-    const inferred = inferSurface(known, { title: spec.title, body: spec.body });
+    const inferred = inferSurface(known, { title: spec.title, type: spec.type, 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.
+      `mmi-cli: no --surface given \u2014 row ${row} filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.${surfaceInferenceSuffix(inferred)}
 `
     );
   }
@@ -37583,6 +37763,10 @@ function spawnDetachedSelf(args, deps, opts = {}) {
 var import_node_path39 = require("node:path");
 
 // src/attach-to-project.ts
+async function attachViaHubApp(cfg, contentNodeId) {
+  const { addIssueToProjectViaHub: addIssueToProjectViaHub2 } = await Promise.resolve().then(() => (init_board_write(), board_write_exports));
+  return addIssueToProjectViaHub2(cfg, contentNodeId);
+}
 function boardAttachRateLimitedReceipt(resetEpochSeconds) {
   return {
     onBoard: false,
@@ -40625,7 +40809,7 @@ async function attachToProject(issueNumber, repo, priority) {
         }
       }
     }
-    return { projectItemId, onBoard: true };
+    return { projectItemId, onBoard: true, credential: "user" };
   } catch (e) {
     const err = e;
     const detail = (err.stderr || err.message || String(e)).trim();
@@ -40637,11 +40821,33 @@ async function attachToProject(issueNumber, repo, priority) {
           { repo: targetRepo2, number: issueNumber },
           priority
         );
-        return { projectItemId, onBoard: true };
+        return { projectItemId, onBoard: true, credential: "user" };
       }
       return { onBoard: true };
     }
     if (isRateLimitText(detail)) {
+      if (targetRepo2) {
+        try {
+          const boardCfg = await loadConfigForRepo(targetRepo2);
+          const viewArgs2 = ["issue", "view", String(issueNumber), "--json", "id", "--jq", ".id"];
+          if (targetRepo2) viewArgs2.push("--repo", targetRepo2);
+          const contentId2 = (await execFileP("gh", viewArgs2, { timeout: 1e4 })).stdout.trim();
+          if (contentId2 && boardCfg.projectId) {
+            const projectItemId = await attachViaHubApp(boardCfg, contentId2);
+            if (priority) {
+              try {
+                await setBoardItemPriority(defaultGitHubClient(), boardCfg, projectItemId, priority);
+              } catch (e2) {
+                const err2 = e2;
+                process.stderr.write(`warning: issue #${issueNumber} board Priority not set: ${(err2.stderr || err2.message || String(e2)).trim()}
+`);
+              }
+            }
+            return { projectItemId, onBoard: true, credential: "app_installation" };
+          }
+        } catch {
+        }
+      }
       process.stderr.write(`warning: issue #${issueNumber} created but board attach rate-limited: ${detail}
 `);
       let resetEpochSeconds;
@@ -40750,6 +40956,7 @@ function registerCollaborationCommands(program3) {
           repo: planRepo,
           labels: [...planLabels, ...surface ? [surface] : []],
           title,
+          type,
           body: opts.body
         });
         if (warn) process.stderr.write(`${warn}
@@ -40757,10 +40964,7 @@ function registerCollaborationCommands(program3) {
         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.
-`
-          );
+          process.stderr.write(surfaceInferenceNote(inferred));
         }
       }
       return {
@@ -40770,7 +40974,9 @@ function registerCollaborationCommands(program3) {
         priority,
         repo: opts.repo,
         ...surface ? { surface } : {},
-        ...planInferred ? { surface_inferred: true, surface: planInferred.label, surface_reason: planInferred.reason } : {}
+        ...planInferred ? { surface_inferred: true, surface: planInferred.label, surface_reason: planInferred.reason } : {},
+        ...planInferred?.uncertain ? { surface_uncertain: true } : {},
+        ...planInferred?.alternatives?.length ? { surface_alternatives: planInferred.alternatives } : {}
       };
     }
   ).action(async (o) => {
@@ -40814,7 +41020,7 @@ 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, title, body });
+      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels, title, type: issueType, body });
       const { refusal, warn, inferred } = surfaceCheck;
       if (warn) process.stderr.write(`${warn}
 `);
@@ -40844,10 +41050,7 @@ function registerCollaborationCommands(program3) {
           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.
-`
-        );
+        process.stderr.write(surfaceInferenceNote(inferred));
       }
       if (refusal && !surfaceWaived()) return fail(refusal.message, refusal.payload);
     }
@@ -40859,7 +41062,7 @@ function registerCollaborationCommands(program3) {
       return;
     }
     const attached = await attachToProject(created.number, targetRepo2, priority);
-    const { projectItemId, onBoard } = attached;
+    const { projectItemId, onBoard, credential: attachCredential } = attached;
     let parent;
     let parentLinkError;
     if (o.parent !== void 0) {
@@ -40879,6 +41082,7 @@ function registerCollaborationCommands(program3) {
       priority,
       projectItemId,
       onBoard,
+      ...attachCredential ? { credential: attachCredential } : {},
       // #5489: partial receipt when the GitHub issue landed but Project v2 attach hit GraphQL quota.
       ...attached.boardAttach ? {
         boardAttach: attached.boardAttach,
@@ -40887,7 +41091,10 @@ function registerCollaborationCommands(program3) {
       } : {},
       ...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 } : {}
+      ...surfaceInferred ? { surface_inferred: true, surface: surfaceInferred.label, surface_reason: surfaceInferred.reason } : {},
+      // #6818: a weak/ambiguous pick says so, with its runner-ups, so the caller can pass --surface.
+      ...surfaceInferred?.uncertain ? { surface_uncertain: true } : {},
+      ...surfaceInferred?.alternatives?.length ? { surface_alternatives: surfaceInferred.alternatives } : {}
     }));
   }), [
     'mmi-cli oracle issue create --type task --title "Wire the schema"',
@@ -41511,10 +41718,21 @@ ${list}`);
     return cwdRepo?.toLowerCase() === repo.split("/").slice(-2).join("/").toLowerCase();
   }
   async function prLandUpdateBranch(prNumber, repo, explicitRepo) {
-    const viewed = JSON.parse((await execFileP("gh", ["pr", "view", prNumber, "--repo", repo, "--json", "headRefName,baseRefName"], { timeout: GC_GH_TIMEOUT_MS4 })).stdout);
-    const localCheckedOut = await prHeadCheckedOutHere(viewed.headRefName, repo, explicitRepo);
-    console.warn(`pr land: PR #${prNumber} is BEHIND ${viewed.baseRefName} \u2014 updating ${viewed.headRefName} from the base (${localCheckedOut ? "local merge commit + push" : "GitHub update-branch"}) and re-waiting the checks once (#6263).`);
-    return updatePrHeadForMerge({ prNumber, repo, head: viewed.headRefName, base: viewed.baseRefName, localCheckedOut });
+    let head = "";
+    let base = "";
+    const rested = await fetchRestPrSnapshot(prNumber, repo).catch(() => void 0);
+    if (rested && rested.headRef && rested.baseRef) {
+      console.warn("pr land: PR head/base read via REST (App-capable poll identity) instead of gh GraphQL (#6834).");
+      head = rested.headRef;
+      base = rested.baseRef;
+    } else {
+      const viewed = JSON.parse((await execFileP("gh", ["pr", "view", prNumber, "--repo", repo, "--json", "headRefName,baseRefName"], { timeout: GC_GH_TIMEOUT_MS4 })).stdout);
+      head = viewed.headRefName;
+      base = viewed.baseRefName;
+    }
+    const localCheckedOut = await prHeadCheckedOutHere(head, repo, explicitRepo);
+    console.warn(`pr land: PR #${prNumber} is BEHIND ${base} \u2014 updating ${head} from the base (${localCheckedOut ? "local merge commit + push" : "GitHub update-branch"}) and re-waiting the checks once (#6263).`);
+    return updatePrHeadForMerge({ prNumber, repo, head, base, localCheckedOut });
   }
   class PrHeadBehindBaseError extends Error {
   }
@@ -41555,9 +41773,22 @@ ${list}`);
     if (landClosingGuardVerdict.message) console.warn(landClosingGuardVerdict.message);
     const result = await runPrLand(number, { repo: o.repo, requireTrain: o.requireTrain !== false }, {
       resolveRepo: async (prNumber, repoOpt) => {
-        const args = repoOpt ? ["--repo", repoOpt] : repoArgs;
-        const viewed = (await execFileP("gh", ["pr", "view", prNumber, ...args, "--json", "headRepository,baseRefName", "--jq", '.headRepository.nameWithOwner + " " + .baseRefName'], { timeout: GC_GH_TIMEOUT_MS4 })).stdout.trim();
-        const [repoFromGh, base] = viewed.split(/\s+/);
+        const knownRepo = repoOpt ?? await resolveRepo(o.repo).catch(() => void 0) ?? o.repo;
+        let repoFromGh = "";
+        let base = "";
+        if (knownRepo) {
+          const rested = await fetchRestPrSnapshot(prNumber, knownRepo).catch(() => void 0);
+          if (rested) {
+            console.warn("pr land: PR repo/base read via REST (App-capable poll identity) instead of gh GraphQL (#6834).");
+            repoFromGh = knownRepo;
+            base = rested.baseRef;
+          }
+        }
+        if (!repoFromGh || !base) {
+          const args = repoOpt ? ["--repo", repoOpt] : repoArgs;
+          const viewed = (await execFileP("gh", ["pr", "view", prNumber, ...args, "--json", "headRepository,baseRefName", "--jq", '.headRepository.nameWithOwner + " " + .baseRefName'], { timeout: GC_GH_TIMEOUT_MS4 })).stdout.trim();
+          [repoFromGh, base] = viewed.split(/\s+/);
+        }
         const repo = repoOpt ?? repoFromGh;
         if (!repo) throw new Error("pr land: could not resolve PR repo");
         let track;
@@ -41683,8 +41914,9 @@ ${list}`);
         console.error(line);
       }
     }
-    if (o.json) printLine(JSON.stringify(result));
-    else printLine(`pr land: ${result.status}${result.error ? ` \u2014 ${result.error}` : ""}`);
+    const credential = await pollToken().catch(() => void 0) ? "app_installation" : "user";
+    if (o.json) printLine(JSON.stringify({ ...result, credential }));
+    else printLine(`pr land: ${result.status}${result.error ? ` \u2014 ${result.error}` : ""} (credential: ${credential})`);
     if (result.status === "failed") process.exitCode = 1;
   });
   jsonParity(pr.command("merge <number>").description("merge a PR (squash by default); archives gitignored tmp/** before worktree teardown; on no-ci repos run pr ci-policy / checks-wait first (#1432, #5679)").option("--squash", "squash merge (default)").option("--merge", "create a merge commit").option("--rebase", "rebase merge").option("--repo <owner/repo>", "target repo (defaults to the current repo); from a foreign checkout the remote probe/delete address this repo and local cleanup runs only in the verified sibling checkout ../<repo>, else localBranch reports skipped-foreign-cwd and the receipt carries foreignCwd: true (#6148)").option("--auto", "enable auto-merge \u2014 merge once the base-branch policy is satisfied (use for policy-gated repos)").addOption(new Option("--disable-auto", "disable a queued auto-merge without merging").conflicts(["auto", "wait", "squash", "merge", "rebase", "preserveWorktree", "gc", "squashBodyFile", "force"])).option("--wait", `wait for checks to reach a terminal passing verdict before merging (default budget ${PR_CHECKS_TIMEOUT_MS / 6e4}m) \u2014 run as a background/monitor task or under a shell timeout above that budget; a short foreground timeout (e.g. 120s) kills it after checks pass and leaves the PR open (#6027)`).option("--preserve-worktree", "after merge, keep the local PR worktree/branch for an active batch (#1888); also the merge settings-proof bypass when delete_branch_on_merge cannot be proven (#6210)").option("--gc", "acknowledge deleting unarchived gitignored tmp/** evidence newer than the branch base (#5679)").option("--squash-body-file <path>", "squash commit body (overrides GitHub COMMIT_MESSAGES); use when a pushed commit mentions close/fix/resolve + #N that must not close (#5723)").option("--force", "acknowledge and merge past a remaining prunable/severe scratch housekeeping block (advisory kept plans/ never blocks, #3012) or a negated-closing-keyword (#3718) or ambiguous-cross-repo-closing (#4279) refusal").option("--without-review <reason>", "compatibility option; shared merge helpers do not require a review verdict")).action(async (number, o) => {

package/package.json

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