@mutmutco/cli 4.6.31 → 4.6.32

package/dist/main.cjs

@@ -28301,10 +28301,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.6.31",
-    tag: "v4.6.31",
-    commit: "53e22eaf158d",
-    npm: "@mutmutco/cli@4.6.31"
+    version: "4.6.32",
+    tag: "v4.6.32",
+    commit: "0e477e5e2765",
+    npm: "@mutmutco/cli@4.6.32"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -28321,14 +28321,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.6.31"
+          v3Target: "v4.6.32"
         }
       ],
       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.6.31 and redeploy the Hub Lambda from tag v4.6.31 (53e22eaf158d); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.6.31 (@mutmutco/cli@4.6.31, tag commit 53e22eaf158d \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.6.32 and redeploy the Hub Lambda from tag v4.6.32 (0e477e5e2765); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.6.32 (@mutmutco/cli@4.6.32, tag commit 0e477e5e2765 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -42556,6 +42556,9 @@ async function runPrLandOnce(prNumber, options, deps) {
   base.mergeStatus = merge.mergeStatus;
   if (merge.credential) base.credential = merge.credential;
   if (merge.credentialRole) base.credentialRole = merge.credentialRole;
+  if (merge.ejectedThenReenqueued) base.ejectedThenReenqueued = true;
+  if (merge.reconcileNeeded) base.reconcileNeeded = true;
+  if (merge.queueRemovalEvidence) base.queueRemovalEvidence = merge.queueRemovalEvidence;
   if (merge.mergeStatus === "queue-admission-pending") {
     return { ...base, status: "queue-admission-pending", outcomeUnknown: true, queueAdmission: merge.queueAdmission, error: merge.error };
   }
@@ -43727,6 +43730,7 @@ var autoMergeApi = async (pr, repo, head) => {
 };
 var ASYNC_HEADERS = ["-H", "Accept: application/vnd.github+json", "-H", "X-GitHub-Api-Version: 2026-03-10"];
 var UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+var UNWITNESSED_EJECTION_GRACE_MS = 6e4;
 function admissionJournal(repo, pr, root) {
   const stateRoot = root ?? (process.platform === "win32" ? (0, import_node_path31.join)(process.env.LOCALAPPDATA || (0, import_node_path31.join)((0, import_node_os18.homedir)(), "AppData", "Local"), "MMI Future", "mmi-cli", "queue-admissions") : (0, import_node_path31.join)(process.env.XDG_STATE_HOME || (0, import_node_path31.join)((0, import_node_os18.homedir)(), ".local", "state"), "mmi-cli", "queue-admissions"));
   const directory = (0, import_node_path31.join)(stateRoot, (0, import_node_crypto12.createHash)("sha256").update(`${repo.toLowerCase()}#${pr}`).digest("hex"));
@@ -43740,12 +43744,12 @@ function admissionJournal(repo, pr, root) {
   const path2 = (number) => (0, import_node_path31.join)(directory, `${number}.jsonl`);
   const validate = (value, previous) => {
     const row = value;
-    if (!row || row.version !== 1 || row.repo !== repo.toLowerCase() || row.pr !== pr || !/^[a-f0-9]{40}$/i.test(row.head) || !UUID.test(row.intentId) || !Number.isSafeInteger(row.createdAt) || row.createdAt <= 0 || !Number.isSafeInteger(row.observedAt) || row.observedAt < row.createdAt || !["dispatching", "pending", "enqueued", "merged", "failed", "ejected"].includes(row.state) || row.credential !== void 0 && !["app_installation", "user"].includes(row.credential) || row.queueWitnessed !== void 0 && typeof row.queueWitnessed !== "boolean" || row.uuid !== void 0 && !UUID.test(row.uuid) || row.state === "pending" && !row.uuid || row.queueEntry !== void 0 && (!row.queueEntry || typeof row.queueEntry.headCommitOid !== "string" || !/^[a-f0-9]{40}$/i.test(row.queueEntry.headCommitOid) || typeof row.queueEntry.enqueuedAt !== "string" || !Number.isFinite(Date.parse(row.queueEntry.enqueuedAt)))) {
+    if (!row || row.version !== 1 || row.repo !== repo.toLowerCase() || row.pr !== pr || !/^[a-f0-9]{40}$/i.test(row.head) || !UUID.test(row.intentId) || !Number.isSafeInteger(row.createdAt) || row.createdAt <= 0 || !Number.isSafeInteger(row.observedAt) || row.observedAt < row.createdAt || !["dispatching", "pending", "enqueued", "merged", "failed", "ejected", "abandoned"].includes(row.state) || row.credential !== void 0 && !["app_installation", "user"].includes(row.credential) || row.queueWitnessed !== void 0 && typeof row.queueWitnessed !== "boolean" || row.uuid !== void 0 && !UUID.test(row.uuid) || row.state === "pending" && !row.uuid || row.queueEntry !== void 0 && (!row.queueEntry || typeof row.queueEntry.headCommitOid !== "string" || !/^[a-f0-9]{40}$/i.test(row.queueEntry.headCommitOid) || typeof row.queueEntry.enqueuedAt !== "string" || !Number.isFinite(Date.parse(row.queueEntry.enqueuedAt)))) {
       throw new Error("queue admission receipt is invalid; preserve it and reconcile the prior request");
     }
     if (!previous) {
       if (row.state !== "dispatching" || row.uuid || row.queueEntry || row.observedAt !== row.createdAt) throw new Error("queue admission intent record is invalid");
-    } else if (row.head !== previous.head || row.intentId !== previous.intentId || row.createdAt !== previous.createdAt || row.observedAt < previous.observedAt || row.state === "dispatching" || previous.uuid && row.uuid !== previous.uuid || previous.credential !== void 0 && row.credential !== previous.credential || ["enqueued", "merged", "failed", "ejected"].includes(previous.state) && (row.state !== previous.state || row.uuid !== previous.uuid) && !(previous.state === "enqueued" && row.state === "ejected" && row.uuid === previous.uuid)) {
+    } else if (row.head !== previous.head || row.intentId !== previous.intentId || row.createdAt !== previous.createdAt || row.observedAt < previous.observedAt || row.state === "dispatching" || previous.uuid && row.uuid !== previous.uuid || previous.credential !== void 0 && row.credential !== previous.credential || ["enqueued", "merged", "failed", "ejected"].includes(previous.state) && (row.state !== previous.state || row.uuid !== previous.uuid) && !(previous.state === "enqueued" && ["ejected", "abandoned"].includes(row.state) && row.uuid === previous.uuid)) {
       throw new Error("queue admission receipt has an illegal transition or changed operation identity");
     }
     return row;
@@ -43828,13 +43832,23 @@ function admissionRejected(reason, repo, pr) {
   };
 }
 async function submitQueueAdmission(pr, repo, head, read, write, options, resume = false) {
-  const unknown = (reason) => ({
+  let reenqueuedAfterEjection = false;
+  let removalEvidence;
+  const markReenqueued = (result) => reenqueuedAfterEjection ? {
+    ...result,
+    ejectedThenReenqueued: true,
+    ...removalEvidence ? { queueRemovalEvidence: removalEvidence } : {},
+    ...result.error ? { error: `re-enqueued after ejection: ${result.error}` } : {}
+  } : result;
+  const unknown = (reason) => markReenqueued({
     mergeStatus: "failed",
     retryable: false,
     outcomeUnknown: true,
-    error: `queue submission outcome unknown: ${reason}. Never hand-edit files under the mmi-cli queue-admissions receipt store (%LOCALAPPDATA%/MMI Future/mmi-cli/queue-admissions); read the queue entry with \`mmi-cli devops read pr queue ${pr} --repo ${repo} --json\` and rerun \`mmi-cli devops pr land ${pr} --repo ${repo} --json\` to reconcile read-only \u2014 no new request was sent after this uncertainty.`
+    reconcileNeeded: true,
+    ...removalEvidence ? { queueRemovalEvidence: removalEvidence } : {},
+    error: `queue submission outcome unknown: ${reason}. Never hand-edit files under the mmi-cli queue-admissions receipt store (%LOCALAPPDATA%/MMI Future/mmi-cli/queue-admissions); read the queue entry with \`mmi-cli devops read pr queue ${pr} --repo ${repo} --json\`; once the PR is verifiably OPEN at the submitted head and absent from the queue, abandon the stuck admission with \`mmi-cli devops pr land ${pr} --repo ${repo} --abandon-admission\` so a new intent needs no new head \u2014 no new request was sent after this uncertainty.`
   });
-  const rejected = (reason) => admissionRejected(reason, repo, pr);
+  const rejected = (reason) => markReenqueued(admissionRejected(reason, repo, pr));
   const reconcile = async (reason, recordEntry = false, resumingSaved = false) => {
     const maxReads = options.enqueueOnly ? 3 : 1;
     const sleep3 = options.sleep ?? ((ms) => new Promise((resolve8) => setTimeout(resolve8, ms)));
@@ -43842,13 +43856,13 @@ async function submitQueueAdmission(pr, repo, head, read, write, options, resume
       if (readAttempt) await sleep3(readAttempt * 1e3);
       try {
         const observed = await readPrMergeQueue(pr, repo, read);
-        if (observed.state === "MERGED" && observed.headRefOid === head) return { mergeStatus: "merged" };
+        if (observed.state === "MERGED" && observed.headRefOid === head) return markReenqueued({ mergeStatus: "merged" });
         if (observed.isInMergeQueue && observed.headRefOid === head) {
           const entry = observed.mergeQueueEntry;
           if (recordEntry && receipt?.head === head && entry?.headCommit && entry.enqueuedAt) {
             journal.save("enqueued", receipt?.uuid, { headCommitOid: entry.headCommit.oid, enqueuedAt: entry.enqueuedAt });
           }
-          return { mergeStatus: "auto-merge-enqueued" };
+          return markReenqueued({ mergeStatus: "auto-merge-enqueued" });
         }
         const saved = recordEntry ? admissionJournal(repo, pr, options.receiptDirectory).receipt : void 0;
         const boundMs = saved?.queueEntry ? Date.parse(saved.queueEntry.enqueuedAt) : resumingSaved && saved?.state === "enqueued" && saved.queueWitnessed === void 0 ? saved.observedAt : void 0;
@@ -43880,11 +43894,37 @@ async function submitQueueAdmission(pr, repo, head, read, write, options, resume
   let receipt = journal.receipt;
   let response;
   let superseded = false;
-  if (receipt && (receipt.state === "enqueued" || receipt.state === "merged") && receipt.head.toLowerCase() !== head.toLowerCase()) {
-    try {
-      const observed = await readPrMergeQueue(pr, repo, read);
-      superseded = observed.state === "OPEN" && !observed.isInMergeQueue;
-    } catch {
+  if (receipt && (receipt.state === "enqueued" || receipt.state === "merged")) {
+    if (receipt.head.toLowerCase() !== head.toLowerCase()) {
+      try {
+        const observed = await readPrMergeQueue(pr, repo, read);
+        superseded = observed.state === "OPEN" && !observed.isInMergeQueue;
+      } catch {
+      }
+    } else {
+      try {
+        const observed = await readPrMergeQueue(pr, repo, read);
+        if (observed.state === "OPEN" && !observed.isInMergeQueue && observed.headRefOid?.toLowerCase() === receipt.head.toLowerCase()) {
+          const boundMs = receipt.queueEntry ? Date.parse(receipt.queueEntry.enqueuedAt) : receipt.observedAt + UNWITNESSED_EJECTION_GRACE_MS;
+          const events = await readArrayPages(
+            `repos/${repo}/issues/${pr}/timeline?per_page=100`,
+            options.timelineRead ?? read,
+            "queue ejection timeline unreadable"
+          );
+          const removals = events.filter((event) => event.event === "removed_from_merge_queue" && Number.isFinite(Date.parse(event.created_at))).map((event) => Date.parse(event.created_at)).filter((at) => at > boundMs).sort((a, b) => a - b);
+          removalEvidence = {
+            source: receipt.queueEntry ? "queue-entry" : "receipt-checkpoint",
+            boundAt: new Date(boundMs).toISOString(),
+            removalsAfterBound: removals.map((at) => new Date(at).toISOString()),
+            checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          if (removals.length > 0) {
+            reenqueuedAfterEjection = true;
+            superseded = true;
+          }
+        }
+      } catch {
+      }
     }
   }
   if (superseded && receipt?.state === "enqueued") {
@@ -43894,7 +43934,7 @@ async function submitQueueAdmission(pr, repo, head, read, write, options, resume
       return unknown("the superseded admission could not be checkpointed");
     }
   }
-  if (receipt && receipt.state !== "failed" && receipt.state !== "ejected" && !superseded) {
+  if (receipt && receipt.state !== "failed" && receipt.state !== "ejected" && receipt.state !== "abandoned" && !superseded) {
     if (options.selection) {
       options.selection.selected = true;
       options.selection.intentId = receipt.intentId;
@@ -44040,13 +44080,13 @@ async function submitQueueAdmission(pr, repo, head, read, write, options, resume
     if (receipt.head !== head) return reconcile("the previous head completed admission; inspect current head and membership before continuing");
     return reconcile(`operation ${receipt.uuid} reported ${status}, but matching-head membership or merged state is unconfirmed`, status === "enqueued");
   }
-  return {
+  return markReenqueued({
     mergeStatus: "queue-admission-pending",
     retryable: false,
     outcomeUnknown: true,
     queueAdmission: { state: "pending", uuid: receipt.uuid, head: receipt.head },
     error: "GitHub accepted queue admission but has not confirmed queue membership. Rerun pr land to resume the saved operation read-only."
-  };
+  });
 }
 function githubQueueSquashMessage(title, pr, commits) {
   const list = commits.map((commit) => `* ${commit.headline}
@@ -44251,6 +44291,38 @@ async function enqueuePrMergeQueue(pr, repo, options = {}) {
   const result = await submitQueueAdmission(pr, repo, head, queueRead, write, { ...options, timelineRead: read, selection });
   return { ...stamp(result, selection.selected, selection.intentId), ...inspected.warning ? { warning: inspected.warning } : {} };
 }
+async function abandonQueueAdmission(pr, repo, options = {}) {
+  if (!/^\d+$/.test(pr)) return { status: "refused", repo, pr, reason: "a bare PR number is required" };
+  const refuse = (reason) => ({ status: "refused", repo, pr, reason });
+  let journal;
+  try {
+    journal = admissionJournal(repo, pr, options.receiptDirectory);
+  } catch (error) {
+    return refuse(`the durable admission receipt cannot be read (${error.message})`);
+  }
+  const receipt = journal.receipt;
+  if (!receipt) return refuse("no queue-admission receipt exists for this PR; nothing to abandon");
+  if (!["pending", "enqueued"].includes(receipt.state)) {
+    return refuse(`the saved admission is '${receipt.state}', not a stuck non-terminal 'pending'/'enqueued' receipt; nothing to abandon`);
+  }
+  let snapshot;
+  try {
+    snapshot = await readPrMergeQueue(pr, repo, options.read ?? actorReadApi);
+  } catch (error) {
+    return refuse(`the PR and queue state could not be read (${error.message}); the admission is unchanged`);
+  }
+  if (snapshot.state !== "OPEN") return refuse(`the PR is '${snapshot.state}', not OPEN; the admission is unchanged`);
+  if (!snapshot.headRefOid || snapshot.headRefOid.toLowerCase() !== receipt.head.toLowerCase()) {
+    return refuse(`the PR head is ${snapshot.headRefOid ?? "unreadable"}, not the receipt's submitted head ${receipt.head}; the admission is unchanged`);
+  }
+  if (snapshot.isInMergeQueue) return refuse("the PR is currently in the merge queue, so the admission is not stuck; the admission is unchanged");
+  try {
+    journal.save("abandoned");
+  } catch (error) {
+    return refuse(`the abandoned state could not be checkpointed (${error.message}); the admission is unchanged`);
+  }
+  return { status: "abandoned", repo, pr, head: receipt.head, ...receipt.uuid ? { operation: receipt.uuid } : {} };
+}
 function closingGuardDiagnostic(message2) {
   if (!message2) return "";
   const remedy = message2.search(/GitHub's merge queue composes|If this PR is meant to close/);
@@ -46163,7 +46235,7 @@ function refuseNotClaimable(e, json) {
   process.exitCode = 1;
   return true;
 }
-var BOARD_READ_HELP = "\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\nThe --json report is an OBJECT \u2014 never an array, and there is no top-level `items` list:\n  {project, viewer, repo, primary, secondary, warnings, partial[, source, builtAt, eventCursor, ...]}\n`primary` is this repo and `secondary` the other repos in scope; each is a bucket object\n  {userOwned, claimable, taken, unownedInFlight}\nand each bucket is an array of items. Filter the BUCKET, not the report:\n  mmi-cli oracle board read --json --out .jerv/tmp/board.json\n  node -e \"const b=require('./.jerv/tmp/board.json');console.log(b.primary.claimable.length)\"\n\nAdd --flat with --json for one array across both scopes: {ref,number,title,status,assignees,labels,bucket,claim,openPullRequests}\n(#9595: claim is the parsed mmi-claim evidence object, null when unclaimed; openPullRequests lists the OPEN\n PRs whose closing-issue body links name the item. On the FULL JSON object that list lives at\n `report.pullRequests` \u2014 there is no top-level `openPullRequests`, and #9596 hand-written projections\n that assume one crash on `.filter`.)\n\nA cached snapshot read renders `source: cache \xB7 built <timestamp> \xB7 fresh|stale` (#9584) and carries\n`builtAt` under --json, so a same-turn re-read of the same builtAt buys nothing new.\n\nUnder --json, parse stdout ONLY and check the exit code first. A failure still prints a\nhuman-readable reason on stderr, so never pipe 2>&1 into a JSON parser (#9151) \u2014 the merged\ntext is not JSON and hides the real board failure.\n\nA zero-byte or empty .jerv/tmp/*.json means the read FAILED \u2014 `Unexpected end of JSON input` is\nthe symptom of shell-redirected empty stdout, not malformed JSON \u2014 re-run with --out (which writes\nthe file only on success) and check the exit code before parsing.\n\nChanging an existing item's Status is a move, never a hand-written `gh api graphql`\n`updateProjectV2ItemFieldValue` mutation with copied `PVT_`/`PVTI_` node ids and a manual Status\nfield-id lookup:\n  mmi-cli oracle board move <status> <ref>\n";
+var BOARD_READ_HELP = "\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\nThe --json report is an OBJECT \u2014 never an array, and there is no top-level `items` list:\n  {project, viewer, repo, primary, secondary, warnings, partial[, source, builtAt, eventCursor, ...]}\n`primary` is this repo and `secondary` the other repos in scope; each is a bucket object\n  {userOwned, claimable, taken, unownedInFlight}\nand each bucket is an array of items. Filter the BUCKET, not the report:\n  mmi-cli oracle board read --json --out .jerv/tmp/board.json\n  node -e \"const b=require('./.jerv/tmp/board.json');console.log(b.primary.claimable.length)\"\n\nAdd --flat with --json for one array across both scopes: {ref,number,title,status,assignees,labels,bucket,claim,openPullRequests}\n(#9595: claim is the parsed mmi-claim evidence object, null when unclaimed; openPullRequests lists the OPEN\n PRs whose closing-issue body links name the item. On the FULL JSON object that list lives at\n `report.pullRequests` \u2014 there is no top-level `openPullRequests`, and #9596 hand-written projections\n that assume one crash on `.filter`.)\n\nNever sniff the envelope \u2014 `j.items ?? j.rows ?? j`, `Object.values(j)` or any generic \"find the list\"\nwrapper throws `items is not iterable` before any row is read (#9956). For a number|status|claim|title\nprojection across non-Done rows, read --json --flat --out .jerv/tmp/board.json and filter that array locally:\n  mmi-cli oracle board read --json --flat --out .jerv/tmp/board.json\n\nA cached snapshot read renders `source: cache \xB7 built <timestamp> \xB7 fresh|stale` (#9584) and carries\n`builtAt` under --json, so a same-turn re-read of the same builtAt buys nothing new.\n\nUnder --json, parse stdout ONLY and check the exit code first. A failure still prints a\nhuman-readable reason on stderr, so never pipe 2>&1 into a JSON parser (#9151) \u2014 the merged\ntext is not JSON and hides the real board failure.\n\nA zero-byte or empty .jerv/tmp/*.json means the read FAILED \u2014 `Unexpected end of JSON input` is\nthe symptom of shell-redirected empty stdout, not malformed JSON \u2014 re-run with --out (which writes\nthe file only on success) and check the exit code before parsing.\n\nChanging an existing item's Status is a move, never a hand-written `gh api graphql`\n`updateProjectV2ItemFieldValue` mutation with copied `PVT_`/`PVTI_` node ids and a manual Status\nfield-id lookup:\n  mmi-cli oracle board move <status> <ref>\n";
 function flattenBoardReport(report) {
   const closingByRef = /* @__PURE__ */ new Map();
   for (const pull of report.pullRequests ?? []) {
@@ -60899,6 +60971,32 @@ function rejectionReason(error) {
   const text = (error instanceof Error ? error.message : String(error)).trim().split("\n")[0] || "no error detail";
   return text.length > 300 ? `${text.slice(0, 300)}\u2026` : text;
 }
+var PERMISSION_REFUSAL = /Resource not accessible|HTTP 40[13]|40[13] (?:Forbidden|Unauthorized)|Bad credentials|must have admin rights|insufficient (?:permissions?|scope)|not authorized/i;
+async function observePolicy(deps, candidate) {
+  if (!candidate) return void 0;
+  try {
+    return await deps.policy(candidate);
+  } catch (error) {
+    const refusal = rejectionReason(error);
+    if (!PERMISSION_REFUSAL.test(refusal)) throw error;
+    await deps.fetchCandidate?.(candidate).catch(() => void 0);
+    let retried;
+    try {
+      retried = await deps.policy(candidate);
+    } catch (retryError) {
+      const second = rejectionReason(retryError);
+      if (!PERMISSION_REFUSAL.test(second)) throw retryError;
+      return {
+        check: "policy",
+        state: "skipped",
+        detail: `committed test policy was not observed: GitHub refused the policy read twice (${second}) \u2014 the identity running pr create lacks the permission that observation needs, repository Administration: read, which covers rulesets and the merge-queue configuration; grant it to the App installation (APP_POLL_PERMISSIONS or the installed App's permissions on ${candidate.repo}) or run with an owner GH_TOKEN. This is an unreadable guard, NOT a policy violation.`
+      };
+    }
+    process.stderr.write(`pr create: WARNING \u2014 the committed test-policy read was refused (${refusal}); re-fetched the candidate objects and retried it once (#9946)
+`);
+    return retried;
+  }
+}
 async function preparePrCreate(input, deps = createPreparationDeps(input)) {
   const observations = [];
   const refs = await deps.candidate().catch((error) => ({ findings: [`candidate refs unavailable (${rejectionReason(error)}); verify the repository and pushed head/base before retrying`] }));
@@ -60907,7 +61005,7 @@ async function preparePrCreate(input, deps = createPreparationDeps(input)) {
   const reads = await Promise.allSettled([
     deps.claims(refs.candidate),
     refs.candidate ? deps.docs(refs.candidate) : Promise.resolve(void 0),
-    refs.candidate ? deps.policy(refs.candidate) : Promise.resolve(void 0)
+    observePolicy(deps, refs.candidate)
   ]);
   const [claims, docs, policy] = reads;
   if (claims.status === "fulfilled") {
@@ -60944,7 +61042,7 @@ async function preparePrCreate(input, deps = createPreparationDeps(input)) {
       await claims.value.restamp();
       const beforeCreate = await deps.candidate();
       if (beforeCreate.findings.length || JSON.stringify(beforeCreate.candidate) !== JSON.stringify(expected)) {
-        throw new Error("pr create: candidate changed while restamping claims; prepare again before creating the PR");
+        throw new Error("pr create: candidate identity changed during preparation while restamping claims; prepare the current head and base again");
       }
     }
   };
@@ -61017,6 +61115,15 @@ function createPreparationDeps(input, io = {}) {
   return {
     candidate: readCandidate,
     publish: (proof) => publishPreparedPrHead(proof, exec3),
+    // #9946: the retry needs the exact candidate objects. Fetch each ref on its own so a fork-only head
+    // that origin cannot resolve never costs the base fetch too, and never surface a fetch failure as the
+    // reason the policy read stayed unreadable.
+    fetchCandidate: async (candidate) => {
+      if (!candidate.root) return;
+      const branch = (name) => name.slice(name.lastIndexOf(":") + 1);
+      const refspecs = [.../* @__PURE__ */ new Set([candidate.head, candidate.base])].map((name) => `+refs/heads/${branch(name)}:refs/remotes/origin/${branch(name)}`);
+      await Promise.allSettled(refspecs.map((refspec) => exec3("git", ["-C", candidate.root, "fetch", "--no-tags", "origin", refspec], { timeout: GIT_TIMEOUT_MS })));
+    },
     claims: (candidate) => observePrCreateClaims(input.body, candidate?.repo ?? input.repo, { head: candidate?.head, headSha: candidate?.headSha }),
     docs: (candidate) => checkDocsIndexAtHead({ repo: candidate.repo, head: candidate.headSha }, docs),
     policy: async (candidate) => {
@@ -62672,6 +62779,46 @@ var RESIDUE_LEDGER_FILE = "mmi-worktree-residue.json";
 function canonicalWorktreeRoot(primary) {
   return (0, import_node_path49.join)((0, import_node_path49.dirname)(primary), "mmi-worktrees", (0, import_node_path49.basename)(primary));
 }
+function lastSegment(p) {
+  return (0, import_node_path49.basename)(p.split(/[\\/]+/).filter(Boolean).pop() ?? p);
+}
+function readProvenance(folder, gitCommonDir, exists) {
+  const found = {
+    path: folder,
+    gitdirPresent: false,
+    registrationId: (0, import_node_path49.basename)(folder),
+    registrationPresent: false
+  };
+  try {
+    const pointer = /^\s*gitdir:\s*(.+?)\s*$/m.exec((0, import_node_fs53.readFileSync)((0, import_node_path49.join)(folder, ".git"), "utf8"));
+    if (pointer) {
+      const target = pointer[1];
+      found.gitdir = (0, import_node_path49.isAbsolute)(target) ? target : (0, import_node_path49.join)(folder, target);
+      found.gitdirPresent = exists(found.gitdir);
+      found.registrationId = lastSegment(found.gitdir);
+    }
+  } catch {
+  }
+  try {
+    found.registrationPresent = exists((0, import_node_path49.join)(gitCommonDir, "worktrees", found.registrationId));
+  } catch {
+  }
+  if (found.gitdir && found.gitdirPresent) {
+    try {
+      const head = (0, import_node_fs53.readFileSync)((0, import_node_path49.join)(found.gitdir, "HEAD"), "utf8").trim();
+      const branch = /^ref:\s*(.+?)\s*$/.exec(head);
+      if (branch) found.head = branch[1].startsWith("refs/heads/") ? branch[1].slice("refs/heads/".length) : `ref ${branch[1]}`;
+      else if (/^[0-9a-f]{7,64}$/i.test(head)) found.head = `detached ${head.slice(0, 12)}`;
+      else if (head) found.head = `ref ${head}`;
+    } catch {
+    }
+  }
+  try {
+    found.mtime = (0, import_node_fs53.statSync)(folder).mtime.toISOString();
+  } catch {
+  }
+  return found;
+}
 function norm2(p) {
   const s = p.replace(/\\/g, "/").replace(/\/+$/, "");
   return process.platform === "win32" ? s.toLowerCase() : s;
@@ -62766,7 +62913,7 @@ async function sweepWorktreeResidue(gitCommonDir, registered, deps = {}) {
         } catch {
         }
       } else {
-        report.unrecorded.push(child2);
+        report.unrecorded.push(readProvenance(child2, gitCommonDir, exists));
       }
     }
   }
@@ -62780,12 +62927,19 @@ function renderResidueSweepLines(report) {
   if (cleaned) lines2.push(`pr merge: removed ${cleaned} leftover worktree folder(s) from earlier merges${where}`);
   for (const k of report.kept) lines2.push(`pr merge: leftover folder still locked, retried on the next merge \u2014 ${k.path}`);
   if (report.unrecorded.length) {
-    const shown = report.unrecorded.slice(0, 5).join(", ");
+    const listed = report.unrecorded.slice(0, 5);
     const more = report.unrecorded.length > 5 ? `, \u2026 ${report.unrecorded.length - 5} more` : "";
-    lines2.push(`pr merge: ${report.unrecorded.length} unregistered folder(s) with content under the worktree root${where} were left untouched (not recorded by a merge): ${shown}${more}`);
+    lines2.push(`pr merge: ${report.unrecorded.length} unregistered folder(s) with content under the worktree root${where} were left untouched (not recorded by a merge): ${listed.map((u) => u.path).join(", ")}${more}`);
+    for (const u of listed) lines2.push(`pr merge:   left untouched ${u.path} \u2014 ${provenanceText(u)}`);
   }
   return lines2;
 }
+function provenanceText(u) {
+  const pointer = u.gitdir ? `.git \u2192 ${u.gitdir}${u.gitdirPresent ? "" : " (admin dir gone)"}` : ".git pointer missing";
+  const registration = `worktrees/${u.registrationId} ${u.registrationPresent ? "registered" : "not registered"}`;
+  const head = u.head ? `HEAD ${u.head}` : "HEAD unknown";
+  return `${pointer}; ${registration}; ${head}; ${u.mtime ? `modified ${u.mtime}` : "mtime unknown"}`;
+}
 
 // src/command-register-collaboration.ts
 var DEFAULT_PRIORITY = "medium";
@@ -63935,9 +64089,19 @@ ${preparation.findings.map((finding) => `[${finding.check}/${finding.state}] ${f
   }
   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", "silence the leftover-scratch warning (scratch never blocks, #8785) and acknowledge 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 per-repo ruleset check_response_timeout_minutes is 15 default with 30/45/60 overrides in .github/rulesets/mmi-development-merge-queue.json; agents never edit the ruleset to shorten a queue wait)`).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) => {
+  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("--abandon-admission", "one stuck-receipt recovery, one PR per call: journal the saved non-terminal (pending/enqueued) queue-admission receipt terminal ONLY after positively observing the PR OPEN at the receipt head and absent from the queue; any unprovable observation refuses and changes nothing (#9951). The next pr land then submits a new intent with no new head").option("--no-require-train", "skip train-authority preflight (not recommended for autonomous agents)").option("--force", "silence the leftover-scratch warning (scratch never blocks, #8785) and acknowledge 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 per-repo ruleset check_response_timeout_minutes is 15 default with 30/45/60 overrides in .github/rulesets/mmi-development-merge-queue.json; agents never edit the ruleset to shorten a queue wait)`).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.abandonAdmission) {
+      if (numbers.length !== 1) return fail("pr land: --abandon-admission abandons one PR per call");
+      const repo = await resolveRepo(opts.repo).catch(() => void 0) ?? opts.repo;
+      if (!repo) return fail("pr land: --abandon-admission needs --repo <owner/repo>; the PR repo could not be resolved");
+      const outcome = await abandonQueueAdmission(numbers[0], repo);
+      if (opts.json) printLine(JSON.stringify(outcome));
+      else printLine(outcome.status === "abandoned" ? `pr land: abandoned the stuck queue admission of PR #${outcome.pr} on ${repo}${outcome.operation ? ` (operation ${outcome.operation})` : ""} at head ${outcome.head} \u2014 the next pr land submits a new intent with no new head` : `pr land: refused to abandon the queue admission of PR #${outcome.pr} on ${repo} \u2014 ${outcome.reason}`);
+      if (outcome.status !== "abandoned") process.exitCode = 1;
+      return;
+    }
     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");
@@ -71555,6 +71719,54 @@ function renderTenantLogs(r) {
   return out.join("\n");
 }
 
+// src/tenant-status-wait.ts
+var TENANT_STATUS_WAIT_INTERVAL_MS = 12e3;
+var TENANT_STATUS_WAIT_TIMEOUT_DEFAULT_S = 660;
+var TENANT_STATUS_WAIT_TIMEOUT_MAX_S = 1800;
+var TENANT_STATUS_WAIT_MIN_SHA_LENGTH = 7;
+function parseWaitForSha(raw) {
+  const sha = raw.trim().toLowerCase();
+  if (!new RegExp(`^[0-9a-f]{${TENANT_STATUS_WAIT_MIN_SHA_LENGTH},40}$`).test(sha)) {
+    return { ok: false, reason: `--wait-for must be a commit SHA (${TENANT_STATUS_WAIT_MIN_SHA_LENGTH}-40 hex characters), got "${raw.trim()}"` };
+  }
+  return { ok: true, sha };
+}
+function parseWaitTimeoutSeconds(raw) {
+  if (raw === void 0) return { ok: true, seconds: TENANT_STATUS_WAIT_TIMEOUT_DEFAULT_S, clamped: false };
+  const seconds = Number(raw.trim());
+  if (!Number.isInteger(seconds) || seconds <= 0) {
+    return { ok: false, reason: `--timeout must be a positive whole number of seconds, got "${raw.trim()}"` };
+  }
+  if (seconds > TENANT_STATUS_WAIT_TIMEOUT_MAX_S) return { ok: true, seconds: TENANT_STATUS_WAIT_TIMEOUT_MAX_S, clamped: true };
+  return { ok: true, seconds, clamped: false };
+}
+function deployedTagReaches(tag, sha) {
+  const stamped = (tag ?? "").trim().toLowerCase();
+  const needle = sha.trim().toLowerCase();
+  if (!stamped || !needle) return false;
+  if (stamped === needle) return true;
+  const [shorter, longer] = stamped.length <= needle.length ? [stamped, needle] : [needle, stamped];
+  return shorter.length >= TENANT_STATUS_WAIT_MIN_SHA_LENGTH && longer.startsWith(shorter);
+}
+async function waitForDeployedTag(deps) {
+  const intervalMs = deps.intervalMs ?? TENANT_STATUS_WAIT_INTERVAL_MS;
+  const now = deps.now ?? Date.now;
+  const sleep2 = deps.sleep ?? ((ms) => new Promise((resolve8) => setTimeout(resolve8, ms)));
+  const startedAt = now();
+  const deadline = startedAt + deps.timeoutMs;
+  let polls = 0;
+  for (; ; ) {
+    const status = await deps.readStatus();
+    polls += 1;
+    if (deployedTagReaches(deps.deployedTagOf(status), deps.sha)) {
+      return { matched: true, status, polls, elapsedMs: now() - startedAt };
+    }
+    const remaining = deadline - now();
+    if (remaining <= 0) return { matched: false, status, polls, elapsedMs: now() - startedAt };
+    await sleep2(Math.min(intervalMs, remaining));
+  }
+}
+
 // src/tenant-sweep.ts
 function isRcBearingTenant(p) {
   if ((p.deployModel ?? "") !== "tenant-container") return false;
@@ -73613,12 +73825,33 @@ tenant.command("reconcile <owner/repo> <stage>").description("re-render this ten
     return failGraceful(`runtime tenant reconcile: ${e.message}`);
   }
 });
-tenant.command("status <owner/repo> <stage>").description("read tenant runtime readiness without dispatching tenant-control: DEPLOY row, last deploy run, public URL probe, and TLS/Caddy/Cloudflare hints; a root answering 401/403/404 is re-probed at /health and the `url` field names the endpoint that answered (#6137)").action(async (repo, stage) => {
+tenant.command("status <owner/repo> <stage>").description("read tenant runtime readiness without dispatching tenant-control: DEPLOY row, last deploy run, public URL probe, and TLS/Caddy/Cloudflare hints; a root answering 401/403/404 is re-probed at /health and the `url` field names the endpoint that answered (#6137); `--wait-for <sha>` polls the same read to a deadline (#9942)").option("--wait-for <sha>", "poll until DEPLOY#<stage> deployedTag reaches this commit SHA (7-40 hex, short form ok), then print the final status and exit 0; exits 1 on timeout \u2014 use this instead of a shell sleep loop (#9942)").option("--timeout <secs>", `with --wait-for: give up after this many seconds (default ${TENANT_STATUS_WAIT_TIMEOUT_DEFAULT_S}, max ${TENANT_STATUS_WAIT_TIMEOUT_MAX_S}, polled every ${TENANT_STATUS_WAIT_INTERVAL_MS / 1e3}s)`).action(async (repo, stage, o) => {
   if (!["dev", "rc", "main"].includes(stage)) return fail("runtime tenant status: <stage> must be dev, rc, or main");
+  let wait;
+  if (o.waitFor !== void 0) {
+    const sha = parseWaitForSha(o.waitFor);
+    if (!sha.ok) return fail(`runtime tenant status: ${sha.reason}`);
+    const timeout = parseWaitTimeoutSeconds(o.timeout);
+    if (!timeout.ok) return fail(`runtime tenant status: ${timeout.reason}`);
+    wait = { sha: sha.sha, seconds: timeout.seconds, clamped: timeout.clamped };
+  } else if (o.timeout !== void 0) {
+    return fail("runtime tenant status: --timeout only applies with --wait-for <sha>");
+  }
   const cfg = await loadConfig();
-  const result = await buildTenantRuntimeStatusFor(repo, stage, cfg);
+  const readStatus = () => buildTenantRuntimeStatusFor(repo, stage, cfg);
+  let result;
+  let waitMatched;
+  if (!wait) result = await readStatus();
+  else {
+    console.error(`runtime tenant status: waiting up to ${wait.seconds}s for ${repo} ${stage} deployedTag to reach ${wait.sha}${wait.clamped ? ` (--timeout clamped to the ${TENANT_STATUS_WAIT_TIMEOUT_MAX_S}s max)` : ""}`);
+    const waited = await waitForDeployedTag({ sha: wait.sha, timeoutMs: wait.seconds * 1e3, readStatus, deployedTagOf: (status) => status.deploy?.deployedTag });
+    result = waited.status;
+    waitMatched = waited.matched;
+    if (!waited.matched) console.error(`runtime tenant status: timed out after ${Math.round(waited.elapsedMs / 1e3)}s (limit ${wait.seconds}s, ${waited.polls} read(s)); deployedTag is ${waited.status.deploy?.deployedTag ?? "unset"}, not ${wait.sha}`);
+  }
   console.log(JSON.stringify(result, null, 2));
-  if (result.publicProbe?.ok === false || result.edgeCertificate?.missing) process.exitCode = 1;
+  if (waitMatched !== void 0) process.exitCode = waitMatched ? 0 : 1;
+  else if (result.publicProbe?.ok === false || result.edgeCertificate?.missing) process.exitCode = 1;
 });
 tenant.command("logs <owner/repo> <stage>").description("READ-ONLY: read a tenant stage's application journal (journald, so a deploy-recreated container still answers) \u2014 the unit namespace comes from the tenant's DEPLOY coords and the blue/green slot is chosen on the box, never from a flag; bounded and redacted (#9230)").option("--tail <n>", `lines to return (1-${TENANT_LOG_TAIL_MAX}, default ${TENANT_LOG_TAIL_DEFAULT}); the applied bound is printed`).option("--since <window>", "window start: a relative window like 15m, 6h or 2d, or a UTC time like 2026-10-07T13:10Z (default 1h)").option("--until <time>", "window end: same forms as --since (default: now) \u2014 the box returns the newest N lines OF the window, so end it earlier to reach older lines on a busy tenant (#9878)").option("--grep <needle>", "keep only returned lines containing this literal text (applied to the bounded tail, not the whole journal)").option("--json", "machine-readable output").action(async (repo, stage, o) => {
   try {

package/package.json

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