@mutmutco/cli 4.3.16 → 4.3.17

package/dist/main.cjs

@@ -12917,6 +12917,18 @@ function rulesetRequiredContexts(ruleset) {
   }
   return contexts;
 }
+function rulesetStrictPolicy(ruleset) {
+  const rules = (ruleset.rules ?? []).filter((rule) => rule.type === "required_status_checks");
+  return rules.length > 0 && rules.every((rule) => rule.parameters?.strict_required_status_checks_policy === true);
+}
+function patchRulesetStrictPolicy(body) {
+  const rules = (body.rules ?? []).map((rule) => {
+    const r = rule;
+    if (r.type !== "required_status_checks") return rule;
+    return { ...r, parameters: { ...r.parameters, strict_required_status_checks_policy: true } };
+  });
+  return { ...body, rules };
+}
 function rulesetBranchIncludes(ruleset) {
   const raw = ruleset.conditions?.ref_name?.include;
   return Array.isArray(raw) ? [...new Set(raw.filter((ref) => typeof ref === "string" && ref.length > 0))].sort((a, b) => a.localeCompare(b)) : [];
@@ -12936,7 +12948,8 @@ function patchRulesetRequiredContexts(body, contexts) {
       ...r,
       parameters: {
         ...r.parameters,
-        strict_required_status_checks_policy: r.parameters?.strict_required_status_checks_policy ?? false,
+        strict_required_status_checks_policy: true,
+        // #6263: org policy — see patchRulesetStrictPolicy
         required_status_checks: sorted.map((context) => ({ context }))
       }
     };
@@ -13023,6 +13036,7 @@ async function gateIsProvenGreen(repo, client, baseBranch, gateFiles = DEFAULT_G
 }
 async function activateProductRuleset(repo, rulesetBody, client, enforcement = "active") {
   const want = new Set(rulesetRequiredContexts({ rules: rulesetBody.rules }));
+  const wantStrict = rulesetStrictPolicy({ rules: rulesetBody.rules });
   const wantBranches = rulesetBranchIncludes(rulesetBody);
   const list = await client.rest("GET", `repos/${repo}/rulesets`, { timeoutMs: 2e4 });
   const existing = findProductRuleset(list ?? []);
@@ -13034,8 +13048,9 @@ async function activateProductRuleset(repo, rulesetBody, client, enforcement = "
     const have = new Set(rulesetRequiredContexts(detail));
     const haveBranches = rulesetBranchIncludes(detail);
     const branchesMatch = haveBranches.length === wantBranches.length && wantBranches.every((ref, index) => ref === haveBranches[index]);
-    if (detail.enforcement === effective && branchesMatch && have.size === want.size && [...want].every((c) => have.has(c))) {
-      return { action: "skipped", enforcement: effective, detail: `${effective} ruleset already matches required contexts and branches${kept}` };
+    const strictMatch = rulesetStrictPolicy(detail) === wantStrict;
+    if (detail.enforcement === effective && branchesMatch && strictMatch && have.size === want.size && [...want].every((c) => have.has(c))) {
+      return { action: "skipped", enforcement: effective, detail: `${effective} ruleset already matches required contexts, branches and up-to-date policy${kept}` };
     }
     await client.rest("PUT", `repos/${repo}/rulesets/${existing.id}`, { body: { ...rulesetBody, enforcement: effective }, timeoutMs: 2e4 });
     return { action: "updated", enforcement: effective, detail: `ruleset ${existing.id}${kept}` };
@@ -15487,10 +15502,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.16",
-    tag: "v4.3.16",
-    commit: "5a4b8e29fd1a",
-    npm: "@mutmutco/cli@4.3.16"
+    version: "4.3.17",
+    tag: "v4.3.17",
+    commit: "3b07c941910b",
+    npm: "@mutmutco/cli@4.3.17"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15507,14 +15522,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.16"
+          v3Target: "v4.3.17"
         }
       ],
       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.16 and redeploy the Hub Lambda from tag v4.3.16 (5a4b8e29fd1a); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.16 (@mutmutco/cli@4.3.16, tag commit 5a4b8e29fd1a \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.17 and redeploy the Hub Lambda from tag v4.3.17 (3b07c941910b); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.17 (@mutmutco/cli@4.3.17, tag commit 3b07c941910b \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -23511,12 +23526,13 @@ function parseAuthoritativeRuleset(raw, meta, repo) {
   const registryContexts = registryRequiredContexts(meta);
   const contexts = sortedUnique(registryContexts ?? committedContexts);
   const explicitBranches = Array.isArray(meta?.requiredCheckBranches) && meta.requiredCheckBranches.length > 0 ? resolveRequiredCheckBranches(meta, repo) : null;
-  let apiPayload = registryContexts == null ? committedPayload : patchRulesetRequiredContexts(committedPayload, contexts);
+  const committedStrict = rulesetStrictPolicy(committedPayload);
+  let apiPayload = patchRulesetStrictPolicy(registryContexts == null ? committedPayload : patchRulesetRequiredContexts(committedPayload, contexts));
   if (explicitBranches) apiPayload = patchRulesetBranchIncludes(apiPayload, explicitBranches);
   const branchIncludes = rulesetBranchIncludes(apiPayload);
   const authoritativeFilePayload = {
     ...filePayload,
-    ...registryContexts == null ? {} : { rules: apiPayload.rules },
+    ...registryContexts == null && committedStrict ? {} : { rules: apiPayload.rules },
     ...explicitBranches == null ? {} : { conditions: apiPayload.conditions }
   };
   return {
@@ -23526,6 +23542,7 @@ function parseAuthoritativeRuleset(raw, meta, repo) {
     contexts,
     branchIncludes,
     committedBranchIncludes,
+    committedStrict,
     branchSource: explicitBranches ? "registry META requiredCheckBranches" : "committed ruleset reference",
     source: registryContexts == null ? "committed ruleset reference" : "registry META requiredChecks",
     coversReleaseBranches: rulesetCoversReleaseBranches(apiPayload, resolveReleaseTrack(meta, void 0, repo))
@@ -23537,8 +23554,9 @@ function sameContexts(left, right) {
 function resolveProductRulesetReconcilePlan(input) {
   const liveNeedsContextConvergence = !sameContexts(input.liveContexts, input.authorityContexts);
   const liveNeedsBranchConvergence = input.liveBranchIncludes !== void 0 && input.authorityBranchIncludes !== void 0 && !sameContexts(input.liveBranchIncludes, input.authorityBranchIncludes);
+  const liveNeedsStrictConvergence = input.liveStrict === false;
   const liveIsActive = input.liveEnforcement === "active";
-  if (liveIsActive && !liveNeedsContextConvergence && !liveNeedsBranchConvergence) {
+  if (liveIsActive && !liveNeedsContextConvergence && !liveNeedsBranchConvergence && !liveNeedsStrictConvergence) {
     return { shouldActivate: false, targetEnforcement: "active" };
   }
   if (input.unsafeContexts.length > 0) {
@@ -23726,6 +23744,7 @@ async function auditRepoCi(repo, deps) {
     const productRuleset = rulesets.find((r) => r.name === PRODUCT_RULESET_NAME);
     const liveContexts = productRuleset == null ? [] : sortedUnique(rulesetRequiredContexts(productRuleset));
     const liveBranchIncludes = productRuleset == null ? [] : rulesetBranchIncludes(productRuleset);
+    const liveStrict = productRuleset != null && rulesetStrictPolicy(productRuleset);
     const hasRequiredChecks = productRuleset?.enforcement === "active" && liveContexts.length > 0;
     checks.push({
       ok: hasRequiredChecks,
@@ -23746,11 +23765,12 @@ async function auditRepoCi(repo, deps) {
         const liveContextsAligned = sameContexts(liveContexts, authoritativeRuleset.contexts);
         const fileBranchesAligned = sameContexts(authoritativeRuleset.committedBranchIncludes, authoritativeRuleset.branchIncludes);
         const liveBranchesAligned = sameContexts(liveBranchIncludes, authoritativeRuleset.branchIncludes);
-        const aligned = fileContextsAligned && liveContextsAligned && fileBranchesAligned && liveBranchesAligned;
+        const strictAligned = authoritativeRuleset.committedStrict && liveStrict;
+        const aligned = fileContextsAligned && liveContextsAligned && fileBranchesAligned && liveBranchesAligned && strictAligned;
         checks.push({
           ok: aligned,
           label: RULESET_REFERENCE_MATCH_LABEL,
-          detail: aligned ? `contexts [${authoritativeRuleset.contexts.join(", ")}] and branches [${authoritativeRuleset.branchIncludes.join(", ")}] match declared authority` : `${authoritativeRuleset.source} requires contexts [${authoritativeRuleset.contexts.join(", ")}]; ${authoritativeRuleset.branchSource} requires branches [${authoritativeRuleset.branchIncludes.join(", ")}]; ${PRODUCT_RULESET_REF} declares contexts [${authoritativeRuleset.committedContexts.join(", ")}] / branches [${authoritativeRuleset.committedBranchIncludes.join(", ")}] and live ${PRODUCT_RULESET_NAME} has contexts [${liveContexts.join(", ")}] / branches [${liveBranchIncludes.join(", ")}]`,
+          detail: aligned ? `contexts [${authoritativeRuleset.contexts.join(", ")}], branches [${authoritativeRuleset.branchIncludes.join(", ")}] and the up-to-date policy match declared authority` : `${authoritativeRuleset.source} requires contexts [${authoritativeRuleset.contexts.join(", ")}]; ${authoritativeRuleset.branchSource} requires branches [${authoritativeRuleset.branchIncludes.join(", ")}]; ${PRODUCT_RULESET_REF} declares contexts [${authoritativeRuleset.committedContexts.join(", ")}] / branches [${authoritativeRuleset.committedBranchIncludes.join(", ")}] and live ${PRODUCT_RULESET_NAME} has contexts [${liveContexts.join(", ")}] / branches [${liveBranchIncludes.join(", ")}]` + (strictAligned ? "" : `; strict_required_status_checks_policy must be true (require branches to be up to date before merging, #6263) \u2014 ${PRODUCT_RULESET_REF} declares ${authoritativeRuleset.committedStrict}, live ${PRODUCT_RULESET_NAME} has ${liveStrict}`),
           remediation: aligned ? void 0 : `mmi-cli devops ci reconcile --repo ${repo} --apply`
         });
       }
@@ -24284,7 +24304,7 @@ async function applyCiReconcileRepo(repo, deps) {
     result.errors.push(`${authority.source} declares no required contexts`);
     return finalizeCiReconcile(repo, deps, result, report);
   }
-  const sourceNeedsConvergence = !sameContexts(authority.committedContexts, authority.contexts) || !sameContexts(authority.committedBranchIncludes, authority.branchIncludes);
+  const sourceNeedsConvergence = !sameContexts(authority.committedContexts, authority.contexts) || !sameContexts(authority.committedBranchIncludes, authority.branchIncludes) || !authority.committedStrict;
   if (sourceNeedsConvergence) {
     try {
       const delivery = await deliverSeedFile(
@@ -24339,6 +24359,7 @@ async function applyCiReconcileRepo(repo, deps) {
     authorityContexts: authority.contexts,
     liveBranchIncludes,
     authorityBranchIncludes: authority.branchIncludes,
+    liveStrict: live == null ? void 0 : rulesetStrictPolicy(live),
     gateProvenGreen: await gateIsProvenGreen(repo, deps.client, baseBranch, gateFiles),
     unsafeContexts: unsafe
   });
@@ -24347,7 +24368,7 @@ async function applyCiReconcileRepo(repo, deps) {
       result.skipped.push(plan.holdReason);
       return finalizeCiReconcile(repo, deps, result, report, plan.holdReason);
     }
-    result.skipped.push(`live ${PRODUCT_RULESET_NAME} contexts and branches already match declared authority`);
+    result.skipped.push(`live ${PRODUCT_RULESET_NAME} contexts, branches and up-to-date policy already match declared authority`);
     return finalizeCiReconcile(repo, deps, result, report);
   }
   try {
@@ -27146,6 +27167,11 @@ async function verifyBootstrap(repo, repoClass, deps, releaseTrack) {
       label: "product required-check ruleset enforcement active",
       detail: productRuleset?.enforcement !== "active" ? `${PRODUCT_RULESET_NAME} is ${productRuleset?.enforcement ?? "missing"} \u2014 run mmi-cli devops ci reconcile --apply --repo ${repo} once the gate is green` : void 0
     });
+    checks.push({
+      ok: productRuleset != null && rulesetStrictPolicy(productRuleset),
+      label: "product required-check ruleset requires an up-to-date branch",
+      detail: productRuleset != null && rulesetStrictPolicy(productRuleset) ? void 0 : `${PRODUCT_RULESET_NAME} ${productRuleset == null ? "is missing" : "has strict_required_status_checks_policy=false"} \u2014 run mmi-cli devops ci reconcile --apply --repo ${repo} (#6263)`
+    });
     const statusChecks = rulesetStatusChecks2(rulesets.filter((r) => r.target === "branch" && r.enforcement === "active"));
     const missing = requiredProductStatusChecks.filter((check) => !statusChecks.has(check));
     checks.push({
@@ -36010,6 +36036,47 @@ function applyChecklistCheck(body, query, checked) {
 }
 
 // src/pr-land.ts
+function prHeadBehindBase(input) {
+  if ((input.mergeStateStatus ?? "").toUpperCase() === "BEHIND") return true;
+  return /out[- ]of[- ]date|not up to date|up to date with the base|update (?:the|your) branch/i.test(input.message ?? "");
+}
+function prHeadUpdateRemedy(head, base) {
+  return `git fetch origin ${base} && git merge origin/${base} (on ${head}), resolve the conflicts, push, then rerun \u2014 docs/Guides/train-troubleshooting.md#head-behind-base`;
+}
+var PR_HEAD_UPDATE_API_READ_RETRIES = 5;
+var PR_HEAD_UPDATE_API_READ_DELAY_MS = 2e3;
+async function updatePrHeadFromBase(input) {
+  const remedy = prHeadUpdateRemedy(input.head, input.base);
+  if (input.localCheckedOut) {
+    const from2 = (await input.git(["rev-parse", "HEAD"])).trim();
+    await input.git(["fetch", "origin", input.base]);
+    try {
+      await input.git(["merge", "--no-ff", "--no-edit", `origin/${input.base}`]);
+    } catch (e) {
+      await input.git(["merge", "--abort"]).catch(() => {
+      });
+      throw new Error(`updating ${input.head} from ${input.base} conflicted (${e.message.trim()}) \u2014 ${remedy}`);
+    }
+    await input.git(["push", "origin", input.head]);
+    const to = (await input.git(["rev-parse", "HEAD"])).trim();
+    return { from: from2, to, base: input.base, via: "local-merge" };
+  }
+  const pullPath = `repos/${input.repo}/pulls/${input.prNumber}`;
+  const readHead2 = async () => (await input.rest("GET", pullPath)).head?.sha ?? "";
+  const from = await readHead2();
+  try {
+    await input.rest("PUT", `${pullPath}/update-branch`, from ? { expected_head_sha: from } : void 0);
+  } catch (e) {
+    throw new Error(`GitHub could not update ${input.head} from ${input.base} (${e.message.trim()}) \u2014 ${remedy}`);
+  }
+  const sleep2 = input.sleep ?? ((ms) => new Promise((resolve7) => setTimeout(resolve7, ms)));
+  for (let attempt = 0; attempt < PR_HEAD_UPDATE_API_READ_RETRIES; attempt++) {
+    const to = await readHead2();
+    if (to && to !== from) return { from, to, base: input.base, via: "update-branch-api" };
+    await sleep2(PR_HEAD_UPDATE_API_READ_DELAY_MS);
+  }
+  throw new Error(`GitHub accepted the update of ${input.head} from ${input.base} but the head did not move \u2014 check the PR, then rerun`);
+}
 var PR_LAND_POLL_MS = 3e4;
 var PR_LAND_ENQUEUE_TIMEOUT_MS = 10 * 6e4;
 var PR_LAND_STATE_READ_RETRIES = 3;
@@ -36080,21 +36147,30 @@ async function runPrLand(prNumber, options, deps) {
   }
   const ciPolicy = await deps.resolveCiPolicy(repo);
   base.ciPolicy = ciPolicy;
-  const checksWait = await deps.waitForChecks(prNumber, repo);
-  base.checksWait = checksWait;
-  if (checksWait.status === "conflicting") {
-    return {
-      ...base,
-      error: `checks-wait conflicting: ${checksWait.reason ?? "PR is conflicting with the base branch"}`
-    };
-  }
-  if (checksWait.status === "failure" || checksWait.status === "timeout" || checksWait.status === "rate-limited") {
-    return {
-      ...base,
-      error: `checks-wait ${checksWait.status}${checksWait.detail ? `: ${checksWait.detail}` : ""}`
-    };
+  const checksWaitError = (checksWait) => {
+    if (checksWait.status === "conflicting") {
+      return `checks-wait conflicting: ${checksWait.reason ?? "PR is conflicting with the base branch"}`;
+    }
+    if (checksWait.status === "failure" || checksWait.status === "timeout" || checksWait.status === "rate-limited") {
+      return `checks-wait ${checksWait.status}${checksWait.detail ? `: ${checksWait.detail}` : ""}`;
+    }
+    return void 0;
+  };
+  base.checksWait = await deps.waitForChecks(prNumber, repo);
+  const waitError = checksWaitError(base.checksWait);
+  if (waitError) return { ...base, error: waitError };
+  let prState = await deps.readPrState(prNumber, repo);
+  if (prState.mergeStateStatus === "BEHIND" && deps.updateBranch) {
+    try {
+      base.branchUpdated = await deps.updateBranch(prNumber, repo);
+    } catch (e) {
+      return { ...base, error: `pr land #${prNumber}: ${e.message}` };
+    }
+    base.checksWait = await deps.waitForChecks(prNumber, repo);
+    const reWaitError = checksWaitError(base.checksWait);
+    if (reWaitError) return { ...base, error: reWaitError };
+    prState = await deps.readPrState(prNumber, repo);
   }
-  const prState = await deps.readPrState(prNumber, repo);
   if (prState.mergeStateStatus === "DIRTY" || prState.mergeable === "CONFLICTING") {
     return {
       ...base,
@@ -39739,6 +39815,27 @@ ${list}`);
     }
     printLine(JSON.stringify({ number: Number(number), repo: o.repo, verdict, patch, head, commentUrl }));
   });
+  async function updatePrHeadForMerge(input) {
+    return updatePrHeadFromBase({
+      ...input,
+      git: async (args) => (await execFileP("git", args, { timeout: GIT_TIMEOUT_MS })).stdout,
+      rest: (method, path2, body) => defaultGitHubClient().rest(method, path2, { ...body ? { body } : {}, timeoutMs: GH_MUTATION_TIMEOUT_MS })
+    });
+  }
+  async function prHeadCheckedOutHere(head, repo, explicitRepo) {
+    if (await gitOut(["branch", "--show-current"]) !== head) return false;
+    if (!explicitRepo || !repo) return true;
+    const cwdRepo = repoFromRemoteUrl(await gitOut(["remote", "get-url", "origin"]));
+    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 });
+  }
+  class PrHeadBehindBaseError extends Error {
+  }
   pr.command("land <number>").description("agent merge path (#1440): train probe \u2014 checks-wait \u2014 merge --auto \u2014 poll enqueued \u2014 development PRs only").option("--json", "machine-readable output").option("--repo <owner/repo>", "target repo (defaults to the PR repo)").option("--no-require-train", "skip train-authority preflight (not recommended for autonomous agents)").option("--force", "acknowledge and land 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>", "land without a review verdict (#6255): posts a `zeroci-review-waived` comment carrying the reason and actor, then proceeds").action(async (number, o) => {
     if (/^(?:[^/]+\/[^/]+)?#\d+$/.test(number.trim())) {
       try {
@@ -39857,6 +39954,7 @@ ${list}`);
         allowedClosing: landClosingGuardInput?.closing,
         bodyText: landSquashBody
       }),
+      updateBranch: (prNumber, repo) => prLandUpdateBranch(prNumber, repo, Boolean(o.repo)),
       pollMerged: async (prNumber, repo, deadlineMs) => {
         let lastFailure;
         while (Date.now() < deadlineMs) {
@@ -40008,7 +40106,7 @@ ${list}`);
     }
     const ciHeadRef = repoForPostCleanup ? await prHeadRefForCiProbe(number, repoForPostCleanup) : void 0;
     const ciPolicy = await resolveMergeCiPolicyForCheckout(o.repo, ciHeadRef);
-    if (o.wait) {
+    const runWaitGate = async () => {
       console.warn(`pr merge: --wait can hold the shell up to the full ${PR_CHECKS_TIMEOUT_MS / 6e4}m budget plus the merge \u2014 run under a shell timeout above that budget or as a background/monitor task (#6027)`);
       const repo = await requireRepo(o.repo);
       const budgetMs = PR_CHECKS_TIMEOUT_MS;
@@ -40020,7 +40118,7 @@ ${list}`);
       if (snapshotRead.state === "failed") {
         console.error(`pr merge: cannot resolve PR #${number}'s base branch \u2014 ${snapshotRead.error}. Refusing to wait against an assumed base; retry when the API answers.`);
         process.exitCode = 1;
-        return;
+        return false;
       }
       const baseBranch = snapshotRead.snapshot.baseRef;
       const requiredContexts = await fetchRequiredCheckContexts(repo, baseBranch).catch(() => null);
@@ -40055,9 +40153,11 @@ ${list}`);
         console.warn(`pr merge: --wait stopped before merge \u2014 ${wait.status}${wait.reason ? `: ${wait.reason}` : ""}${wait.detail ? ` (${wait.detail})` : ""}`);
         for (const line of failedChecksReceiptLines("pr merge", wait)) console.warn(line);
         process.exitCode = wait.status === "timeout" || wait.status === "rate-limited" ? PR_CHECKS_TIMEOUT_EXIT_CODE : 1;
-        return;
+        return false;
       }
-    }
+      return true;
+    };
+    if (o.wait && !await runWaitGate()) return;
     if (ciPolicy.policy === "no-ci") {
       const guard = decidePrMergeNoCiGuard(await pollGhPrChecks(number, repoArgs), ciPolicy.reason);
       if (guard.action === "refuse") throw new Error(`gh pr merge ${number}: ${guard.message}`);
@@ -40073,73 +40173,90 @@ ${list}`);
       { allowedClosing: method === "--squash" ? closingGuardInput?.closing : void 0 }
     );
     const bodyFile = overrideBody?.path;
-    try {
-      await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: o.auto, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch(async (e) => {
-        const message2 = String(e.message || "");
-        if (/already been merged/i.test(message2)) {
-          remoteNotAttemptedReason = "pr-already-merged";
-          return;
+    let branchUpdated;
+    const mergeOnce = () => execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: o.auto, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch(async (e) => {
+      const message2 = String(e.message || "");
+      if (/already been merged/i.test(message2)) {
+        remoteNotAttemptedReason = "pr-already-merged";
+        return;
+      }
+      const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
+      if (note) throw new Error(`gh pr merge ${number}: ${note}`);
+      if (!o.auto && !branchUpdated) {
+        const mergeState = prHeadBehindBase({ message: message2 }) ? "BEHIND" : (await execFileP("gh", ["pr", "view", number, ...repoArgs, "--json", "mergeStateStatus", "--jq", ".mergeStateStatus"], { timeout: GC_GH_TIMEOUT_MS4 }).catch(() => ({ stdout: "" }))).stdout.trim();
+        if (prHeadBehindBase({ mergeStateStatus: mergeState })) throw new PrHeadBehindBaseError(message2);
+      }
+      if (isGitHubRateLimitError(e)) {
+        if (o.auto) {
+          throw new Error(`gh pr merge ${number}: GraphQL rate limit exhausted, and enabling auto-merge has no REST equivalent \u2014 retry without --auto to merge now via REST, or retry --auto after the pool resets. (${message2.trim()})`);
         }
-        const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
-        if (note) throw new Error(`gh pr merge ${number}: ${note}`);
-        if (isGitHubRateLimitError(e)) {
-          if (o.auto) {
-            throw new Error(`gh pr merge ${number}: GraphQL rate limit exhausted, and enabling auto-merge has no REST equivalent \u2014 retry without --auto to merge now via REST, or retry --auto after the pool resets. (${message2.trim()})`);
+        if (!repoForPostCleanup) throw e;
+        console.warn(`pr merge: gh GraphQL rate-limited \u2014 merging PR #${number} via REST PUT instead (#4588).`);
+        const commitMessage = bodyFile ? (0, import_node_fs43.readFileSync)(bodyFile, "utf8") : void 0;
+        await defaultGitHubClient().rest("PUT", `repos/${repoForPostCleanup}/pulls/${number}/merge`, {
+          body: { merge_method: method.slice(2), ...commitMessage ? { commit_message: commitMessage } : {} },
+          timeoutMs: GH_MUTATION_TIMEOUT_MS
+        });
+        return;
+      }
+      if (!o.auto && mergeRejectedBaseBranchModified(message2)) {
+        console.warn(`pr merge: the base branch was modified by a concurrent merge \u2014 waiting ${PR_MERGE_BASE_RACE_RETRY_DELAY_MS / 1e3}s and retrying PR #${number}'s merge once (#6052).`);
+        await new Promise((resolve7) => setTimeout(resolve7, PR_MERGE_BASE_RACE_RETRY_DELAY_MS));
+        await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: false, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e2) => {
+          const m2 = String(e2.message || "");
+          if (/already been merged/i.test(m2)) {
+            remoteNotAttemptedReason = "pr-already-merged";
+            return;
           }
-          if (!repoForPostCleanup) throw e;
-          console.warn(`pr merge: gh GraphQL rate-limited \u2014 merging PR #${number} via REST PUT instead (#4588).`);
-          const commitMessage = bodyFile ? (0, import_node_fs43.readFileSync)(bodyFile, "utf8") : void 0;
-          await defaultGitHubClient().rest("PUT", `repos/${repoForPostCleanup}/pulls/${number}/merge`, {
-            body: { merge_method: method.slice(2), ...commitMessage ? { commit_message: commitMessage } : {} },
-            timeoutMs: GH_MUTATION_TIMEOUT_MS
-          });
-          return;
-        }
-        if (!o.auto && mergeRejectedBaseBranchModified(message2)) {
-          console.warn(`pr merge: the base branch was modified by a concurrent merge \u2014 waiting ${PR_MERGE_BASE_RACE_RETRY_DELAY_MS / 1e3}s and retrying PR #${number}'s merge once (#6052).`);
-          await new Promise((resolve7) => setTimeout(resolve7, PR_MERGE_BASE_RACE_RETRY_DELAY_MS));
-          await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: false, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e2) => {
-            const m2 = String(e2.message || "");
-            if (/already been merged/i.test(m2)) {
-              remoteNotAttemptedReason = "pr-already-merged";
-              return;
-            }
-            const note2 = timeoutKillNote(e2, GH_MUTATION_TIMEOUT_MS);
-            if (note2) throw new Error(`gh pr merge ${number}: ${note2}`);
-            if (!ghPrMergeLocalBranchDeleteWarning(m2)) throw e2;
-          });
-          return;
-        }
-        if (o.auto && mergeAutoRejectedPrAlreadyClean(message2)) {
-          await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: false, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e2) => {
-            const m2 = String(e2.message || "");
-            if (/already been merged/i.test(m2)) {
-              remoteNotAttemptedReason = "pr-already-merged";
-              return;
-            }
-            const note2 = timeoutKillNote(e2, GH_MUTATION_TIMEOUT_MS);
-            if (note2) throw new Error(`gh pr merge ${number}: ${note2}`);
-            if (!ghPrMergeLocalBranchDeleteWarning(m2)) throw e2;
-          });
-          return;
-        }
-        if (!o.auto && basePolicyBlocksImmediateMerge(message2)) {
-          console.warn(`pr merge: the base-branch policy blocks an immediate merge \u2014 upgrading to --auto (merges once required checks pass).`);
-          upgradedToAuto = true;
-          await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: true, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e2) => {
-            const m2 = String(e2.message || "");
-            if (/already been merged/i.test(m2)) {
-              remoteNotAttemptedReason = "pr-already-merged";
-              return;
-            }
-            const note2 = timeoutKillNote(e2, GH_MUTATION_TIMEOUT_MS);
-            if (note2) throw new Error(`gh pr merge ${number}: ${note2}`);
-            if (!ghPrMergeLocalBranchDeleteWarning(m2)) throw e2;
-          });
-          return;
-        }
-        if (!ghPrMergeLocalBranchDeleteWarning(message2)) throw e;
-      });
+          const note2 = timeoutKillNote(e2, GH_MUTATION_TIMEOUT_MS);
+          if (note2) throw new Error(`gh pr merge ${number}: ${note2}`);
+          if (!ghPrMergeLocalBranchDeleteWarning(m2)) throw e2;
+        });
+        return;
+      }
+      if (o.auto && mergeAutoRejectedPrAlreadyClean(message2)) {
+        await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: false, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e2) => {
+          const m2 = String(e2.message || "");
+          if (/already been merged/i.test(m2)) {
+            remoteNotAttemptedReason = "pr-already-merged";
+            return;
+          }
+          const note2 = timeoutKillNote(e2, GH_MUTATION_TIMEOUT_MS);
+          if (note2) throw new Error(`gh pr merge ${number}: ${note2}`);
+          if (!ghPrMergeLocalBranchDeleteWarning(m2)) throw e2;
+        });
+        return;
+      }
+      if (!o.auto && basePolicyBlocksImmediateMerge(message2)) {
+        console.warn(`pr merge: the base-branch policy blocks an immediate merge \u2014 upgrading to --auto (merges once required checks pass).`);
+        upgradedToAuto = true;
+        await execFileP("gh", buildPrMergeArgs({ number, repoArgs, method, auto: true, deleteBranch: false, bodyFile }), { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e2) => {
+          const m2 = String(e2.message || "");
+          if (/already been merged/i.test(m2)) {
+            remoteNotAttemptedReason = "pr-already-merged";
+            return;
+          }
+          const note2 = timeoutKillNote(e2, GH_MUTATION_TIMEOUT_MS);
+          if (note2) throw new Error(`gh pr merge ${number}: ${note2}`);
+          if (!ghPrMergeLocalBranchDeleteWarning(m2)) throw e2;
+        });
+        return;
+      }
+      if (!ghPrMergeLocalBranchDeleteWarning(message2)) throw e;
+    });
+    try {
+      try {
+        await mergeOnce();
+      } catch (e) {
+        if (!(e instanceof PrHeadBehindBaseError)) throw e;
+        const localCheckedOut = !foreignCwd && await prHeadCheckedOutHere(headRef, targetRepo2, Boolean(o.repo));
+        console.warn(`pr merge: GitHub refused the merge \u2014 PR #${number}'s head is BEHIND ${baseRef} \u2014 updating ${headRef} from the base (${localCheckedOut ? "local merge commit + push" : "GitHub update-branch"}) and retrying once (#6263).`);
+        branchUpdated = await updatePrHeadForMerge({ prNumber: number, repo: await requireRepo(o.repo), head: headRef, base: baseRef, localCheckedOut }).catch((e2) => {
+          throw new Error(`pr merge: ${e2.message}`);
+        });
+        if (o.wait && !await runWaitGate()) return;
+        await mergeOnce();
+      }
     } finally {
       overrideBody?.cleanup();
     }
@@ -40174,7 +40291,8 @@ ${list}`);
         pr: number,
         branch: headRef,
         state: stateRead.ok ? stateRead.state : "unknown",
-        cleanupStatus: "skipped"
+        cleanupStatus: "skipped",
+        ...branchUpdated ? { branchUpdated } : {}
       }));
       console.error(`pr merge: ${gate.message}. Nothing was deleted \u2014 re-check the PR and retry.`);
       process.exitCode = 1;
@@ -40285,6 +40403,7 @@ ${list}`);
       ...methodField ? { method: methodField } : {},
       remoteBranch,
       housekeeping,
+      ...branchUpdated ? { branchUpdated } : {},
       ...foreignCwd ? { foreignCwd: true, ...foreignCheckout ? { foreignCheckout } : {} } : {},
       ...partialCleanup.length ? { cleanupStatus: "partial", partialCleanup } : {},
       ...localCleanup?.worktree ? { worktree: localCleanup.worktree } : {},

package/package.json

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