@mutmutco/cli 4.5.163 → 4.5.164

package/dist/main.cjs

@@ -19051,10 +19051,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.5.163",
-    tag: "v4.5.163",
-    commit: "0d3f3c9549d7",
-    npm: "@mutmutco/cli@4.5.163"
+    version: "4.5.164",
+    tag: "v4.5.164",
+    commit: "a5f70231e564",
+    npm: "@mutmutco/cli@4.5.164"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -19071,14 +19071,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.5.163"
+          v3Target: "v4.5.164"
         }
       ],
       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.5.163 and redeploy the Hub Lambda from tag v4.5.163 (0d3f3c9549d7); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.5.163 (@mutmutco/cli@4.5.163, tag commit 0d3f3c9549d7 \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.5.164 and redeploy the Hub Lambda from tag v4.5.164 (a5f70231e564); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.5.164 (@mutmutco/cli@4.5.164, tag commit a5f70231e564 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -40963,6 +40963,22 @@ async function runPrLand(prNumber, options, deps) {
   }
   const ciPolicy = await deps.resolveCiPolicy(repo);
   base.ciPolicy = ciPolicy;
+  const pinned = options.expectHead;
+  if (pinned) base.pinnedHead = { expected: pinned };
+  const headDrift = async (stage) => {
+    if (!pinned) return void 0;
+    if (!deps.readHeadSha) throw new Error("pinned head reader unavailable");
+    const observed = await deps.readHeadSha(prNumber, repo);
+    base.pinnedHead = { expected: pinned, observed };
+    if (observed === pinned) return void 0;
+    return {
+      ...base,
+      pinnedHead: { ...base.pinnedHead, refused: "drift" },
+      error: `pr land #${prNumber}: head ${observed} is not the pinned ${pinned} (${stage}) \u2014 refusing to land a head that was not checked (--expect-head)`
+    };
+  };
+  const drift = await headDrift("before landing");
+  if (drift) return drift;
   const hasQueue = await deps.hasMergeQueue?.(repo, resolved.base) ?? false;
   let queueSnapshot;
   if (hasQueue) {
@@ -40986,7 +41002,16 @@ async function runPrLand(prNumber, options, deps) {
   base.checksWait = await deps.waitForChecks(prNumber, repo);
   const waitError = checksWaitError(base.checksWait);
   if (waitError) return { ...base, error: waitError };
+  const driftAfterChecks = await headDrift("after checks");
+  if (driftAfterChecks) return driftAfterChecks;
   let prState = await deps.readPrState(prNumber, repo);
+  if (pinned && prState.mergeStateStatus === "BEHIND") {
+    return {
+      ...base,
+      pinnedHead: { ...base.pinnedHead, refused: "behind" },
+      error: `pr land #${prNumber}: head is BEHIND ${resolved.base} and pinned by --expect-head \u2014 refusing to update it. Update and re-check the head yourself, then land with the new SHA`
+    };
+  }
   if (prState.mergeStateStatus === "BEHIND" && deps.updateBranch) {
     try {
       base.branchUpdated = await deps.updateBranch(prNumber, repo);
@@ -41080,6 +41105,7 @@ async function pollPrMergeQueue(pr, options, deps, base, snapshot, deadlineMs) {
       const result2 = {
         ...base,
         mergeQueue: { ...base.mergeQueue, state: "ejected", ...run ? { ejectedRun: run } : {} },
+        ...base.pinnedHead ? { pinnedHead: { ...base.pinnedHead, refused: "ejected" } } : {},
         error: `merge queue ejected PR #${pr} \u2014 ${run ? `merge_group run ${run.id} ${run.conclusion} ${run.url}` : "merge_group run not found"}`
       };
       deps.queueProgress?.(result2);
@@ -41105,7 +41131,7 @@ async function landMany(prs, landOne, cleanup, hooks) {
   const safe = async (pr) => landOne(pr).catch((e) => ({ status: "failed", repo: "", pr, base: "", error: e.message }));
   return Promise.all(prs.map(async (pr) => {
     let result = await safe(pr);
-    if (prLandOutcome(result) === "ejected") {
+    if (prLandOutcome(result) === "ejected" && !result.pinnedHead) {
       hooks?.onRetry?.(pr, result);
       result = { ...await safe(pr), retriedAfterEjection: true };
     }
@@ -41985,6 +42011,7 @@ function buildPrMergeArgs(input) {
   const args = ["pr", "merge", input.number, ...input.repoArgs, input.method];
   if (input.deleteBranch !== false) args.push("--delete-branch");
   if (input.bodyFile) args.push("--body-file", input.bodyFile);
+  if (input.matchHeadCommit) args.push("--match-head-commit", input.matchHeadCommit);
   if (input.auto) args.push("--auto");
   return args;
 }
@@ -42226,12 +42253,12 @@ async function ghMergeAutoEnqueue(prNumber, repo, method, extra) {
     bodyText: method === "--squash" ? extra?.bodyText : void 0
   });
   try {
-    return await mergeAutoEnqueueWithBody(prNumber, args, method, io, overrideBody?.path, extra?.mergeQueue);
+    return await mergeAutoEnqueueWithBody(prNumber, args, method, io, overrideBody?.path, extra?.mergeQueue, extra?.matchHeadCommit);
   } finally {
     overrideBody?.cleanup();
   }
 }
-async function mergeAutoEnqueueWithBody(prNumber, args, method, io, bodyFile, mergeQueue = false) {
+async function mergeAutoEnqueueWithBody(prNumber, args, method, io, bodyFile, mergeQueue = false, matchHeadCommit) {
   const headRef = (await io.gh(["pr", "view", prNumber, ...args, "--json", "headRefName", "--jq", ".headRefName"], GC_GH_TIMEOUT_MS).catch(() => "")).trim();
   const deleteBranch = !mergeQueue && !isProtectedBranch(headRef);
   const readMergeState = () => readGhPrStateWithRetry(
@@ -42251,7 +42278,7 @@ async function mergeAutoEnqueueWithBody(prNumber, args, method, io, bodyFile, me
         return s.ok && s.state === "MERGED";
       },
       reEnqueue: async () => {
-        await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: true, deleteBranch, bodyFile }), GH_MUTATION_TIMEOUT_MS);
+        await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: true, deleteBranch, bodyFile, matchHeadCommit }), GH_MUTATION_TIMEOUT_MS);
       }
     });
     if (confirmation === "merged") return { mergeStatus: "merged" };
@@ -42259,7 +42286,7 @@ async function mergeAutoEnqueueWithBody(prNumber, args, method, io, bodyFile, me
     return { mergeStatus: "failed", error: "auto-merge did not stick \u2014 GitHub reported no autoMergeRequest after enqueue; retry once the PR has a pending check" };
   };
   try {
-    await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: true, deleteBranch, bodyFile }), GH_MUTATION_TIMEOUT_MS);
+    await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: true, deleteBranch, bodyFile, matchHeadCommit }), GH_MUTATION_TIMEOUT_MS);
   } catch (e) {
     const message2 = String(e.message || "");
     if (/already been merged/i.test(message2)) return { mergeStatus: "merged" };
@@ -42267,7 +42294,7 @@ async function mergeAutoEnqueueWithBody(prNumber, args, method, io, bodyFile, me
     if (note) return { mergeStatus: "failed", error: note };
     if (mergeAutoRejectedPrAlreadyClean(message2)) {
       try {
-        await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: false, deleteBranch, bodyFile }), GH_MUTATION_TIMEOUT_MS);
+        await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: false, deleteBranch, bodyFile, matchHeadCommit }), GH_MUTATION_TIMEOUT_MS);
       } catch (e2) {
         const m2 = String(e2.message || "");
         if (/already been merged/i.test(m2)) return { mergeStatus: "merged" };
@@ -42278,7 +42305,7 @@ async function mergeAutoEnqueueWithBody(prNumber, args, method, io, bodyFile, me
             return { mergeStatus: "failed", error: `could not confirm PR state after clean-status fallback: ${afterDirect.error}` };
           }
           try {
-            await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: true, deleteBranch, bodyFile }), GH_MUTATION_TIMEOUT_MS);
+            await io.gh(buildPrMergeArgs({ number: prNumber, repoArgs: args, method, auto: true, deleteBranch, bodyFile, matchHeadCommit }), GH_MUTATION_TIMEOUT_MS);
           } catch (e3) {
             const m3 = String(e3.message || "");
             if (/already been merged/i.test(m3)) return { mergeStatus: "merged" };
@@ -47844,9 +47871,14 @@ ${list}`);
   }
   class PrHeadBehindBaseError extends Error {
   }
-  pr.command("land <numbers...>").description("agent merge path (#1440): train probe \u2014 checks-wait \u2014 merge --auto \u2014 poll enqueued \u2014 development PRs only. Several PR numbers land together (#8322): all are enqueued, waited on together, a queue-ejected PR is updated and re-enqueued once, a queue merge is followed by worktree/branch cleanup and board Done, and one table (or --json) reports each outcome").option("--json", "machine-readable output").option("--repo <owner/repo>", "target repo (defaults to the PR repo)").option("--enqueue-only", "return once queue membership is confirmed; without a merge queue, land normally").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>", "compatibility option; shared merge helpers do not require a review verdict").option("--timeout <minutes>", `merge-queue wait per PR (default ${PR_LAND_QUEUE_TIMEOUT_MS / 6e4} minutes, one window per ${PR_LAND_QUEUE_BATCH_SIZE} PRs \u2014 the queue's own check timeout is 60)`).option("--preserve-worktree", "after a queue merge keep the local worktree and branch (skips the post-merge cleanup)").action(async (numbers, opts) => {
+  pr.command("land <numbers...>").description("agent merge path (#1440): train probe \u2014 checks-wait \u2014 merge --auto \u2014 poll enqueued \u2014 development PRs only. Several PR numbers land together (#8322): all are enqueued, waited on together, a queue-ejected PR is updated and re-enqueued once, a queue merge is followed by worktree/branch cleanup and board Done, and one table (or --json) reports each outcome").option("--json", "machine-readable output").option("--repo <owner/repo>", "target repo (defaults to the PR repo)").option("--enqueue-only", "return once queue membership is confirmed; without a merge queue, land normally").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>", "compatibility option; shared merge helpers do not require a review verdict").option("--timeout <minutes>", `merge-queue wait per PR (default ${PR_LAND_QUEUE_TIMEOUT_MS / 6e4} minutes, one window per ${PR_LAND_QUEUE_BATCH_SIZE} PRs \u2014 the queue's own check timeout is 60)`).option("--preserve-worktree", "after a queue merge keep the local worktree and branch (skips the post-merge cleanup)").option("--expect-head <sha>", "pin the PR head to this full 40-hex SHA (#8456): checked before landing, after checks and by GitHub at enqueue (--match-head-commit); never updates a BEHIND head and never retries an ejection \u2014 it stops with pinnedHead.refused instead. One PR only").action(async (numbers, opts) => {
     const timeoutMinutes = opts.timeout === void 0 ? void 0 : Number(opts.timeout);
     if (timeoutMinutes !== void 0 && !(timeoutMinutes > 0)) return fail("pr land: --timeout must be a positive number of minutes");
+    if (opts.expectHead !== void 0) {
+      if (!/^[0-9a-f]{40}$/i.test(opts.expectHead)) return fail("pr land: --expect-head needs the full 40-hex head SHA");
+      if (numbers.length !== 1) return fail("pr land: --expect-head pins one PR head; land one PR per call");
+      opts.expectHead = opts.expectHead.toLowerCase();
+    }
     const queueTimeoutMs = timeoutMinutes !== void 0 ? Math.round(timeoutMinutes * 6e4) : PR_LAND_QUEUE_TIMEOUT_MS * Math.ceil(numbers.length / PR_LAND_QUEUE_BATCH_SIZE);
     let inFlight = numbers.length;
     const landOne = async (numberArg) => {
@@ -47887,7 +47919,12 @@ ${list}`);
       }
       if (landClosingGuardVerdict.message) console.warn(landClosingGuardVerdict.message);
       let mergeQueueEnabled = false;
-      const result = await runPrLand(number, { repo: o.repo, requireTrain: o.requireTrain !== false, enqueueOnly: o.enqueueOnly, queueTimeoutMs }, {
+      const result = await runPrLand(number, { repo: o.repo, requireTrain: o.requireTrain !== false, enqueueOnly: o.enqueueOnly, queueTimeoutMs, expectHead: o.expectHead }, {
+        readHeadSha: async (prNumber, repo) => {
+          const sha = (await fetchRestPrSnapshot(prNumber, repo)).headSha;
+          if (!sha) throw new Error(`pr land: could not read the head SHA of PR #${prNumber}`);
+          return sha.toLowerCase();
+        },
         pollDelayMs: (attempt) => prLandPollDelayMs(attempt, inFlight),
         hasMergeQueue: async (repo, base) => mergeQueueEnabled = await hasPrMergeQueue(repo, base),
         readMergeQueue: readPrMergeQueue,
@@ -47985,9 +48022,11 @@ ${list}`);
         mergeAuto: (prNumber, repo) => ghMergeAutoEnqueue(prNumber, repo, "--squash", {
           allowedClosing: landClosingGuardInput?.closing,
           bodyText: landSquashBody,
-          mergeQueue: mergeQueueEnabled
+          mergeQueue: mergeQueueEnabled,
+          matchHeadCommit: o.expectHead
         }),
-        updateBranch: (prNumber, repo) => prLandUpdateBranch(prNumber, repo, Boolean(o.repo)),
+        // #8456: a pinned land has no update lane at all.
+        ...o.expectHead ? {} : { updateBranch: (prNumber, repo) => prLandUpdateBranch(prNumber, repo, Boolean(o.repo)) },
         pollMerged: async (prNumber, repo, deadlineMs) => {
           let lastFailure;
           while (Date.now() < deadlineMs) {

package/package.json

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