@mutmutco/codex-plugin 4.6.31 → 4.6.33

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mmi",
-  "version": "4.6.31",
+  "version": "4.6.33",
   "mmiCompat": "4.x",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {

package/cli/dist/main.cjs

@@ -27062,6 +27062,71 @@ function contentPutInputArgs(repo, path2, inputFile) {
     inputFile
   ];
 }
+var BANK_REQUEST_REPO = "mutmutco/Jerv-Hub";
+var BANK_REQUEST_LABEL = "bank-request";
+var BANK_REQUEST_SOURCE = "MMI-Hub#9958";
+function bankRequestTitle(repoName2) {
+  return `bank-request: coding-agent::${repoName2}`;
+}
+function bankRequestBody(fullName) {
+  return `Create the coding-agent memory bank for \`${fullName}\` (asked by \`mmi-cli devops bootstrap apply\`; see ${BANK_REQUEST_SOURCE}).`;
+}
+function planBankRequest(fullName, existing) {
+  const parsed = parseOwnerRepo(fullName);
+  const base = { title: bankRequestTitle(parsed.name), label: BANK_REQUEST_LABEL, body: bankRequestBody(parsed.fullName) };
+  if (existing == null) return { ...base, action: "skip", reason: `could not read ${BANK_REQUEST_REPO} issues` };
+  const found = existing.find((issue) => issue?.title === base.title);
+  if (found) {
+    return {
+      ...base,
+      action: "exists",
+      number: found.number,
+      state: found.state ?? "open",
+      url: found.url ?? `https://github.com/${BANK_REQUEST_REPO}/issues/${found.number}`
+    };
+  }
+  return { ...base, action: "create" };
+}
+var oneLine = (e) => String(e?.message ?? e).split("\n")[0].trim();
+function bankRequestManualStep(request, reason) {
+  return `file it by hand at https://github.com/${BANK_REQUEST_REPO}/issues/new \u2014 title "${request.title}", label ${request.label}, body: ${request.body} (${reason})`;
+}
+function renderBankRequestPlan(result) {
+  return [
+    "bootstrap apply \u2014 coding-agent memory bank request (dry-run; no issue filed):",
+    `  PLAN file issue "${result.title}" (label ${result.label}) in ${BANK_REQUEST_REPO}`,
+    `  body: ${result.body}`
+  ].join("\n");
+}
+function renderBankRequestLine(result) {
+  if (result.status === "opened") {
+    return `memory bank request: ${BANK_REQUEST_REPO}#${result.number} opened \u2014 "${result.title}" (label ${result.label})${result.url ? ` ${result.url}` : ""}`;
+  }
+  if (result.status === "exists") {
+    return `memory bank request: already requested \u2014 ${BANK_REQUEST_REPO}#${result.number} (${result.state})${result.url ? ` ${result.url}` : ""}`;
+  }
+  return `memory bank request: SKIPPED (${result.reason ?? "not attempted"}) \u2014 ${bankRequestManualStep(result, result.reason ?? "not attempted")}`;
+}
+async function runBankRequest(fullName, options, deps) {
+  const parsed = parseOwnerRepo(fullName);
+  const request = { title: bankRequestTitle(parsed.name), label: BANK_REQUEST_LABEL, body: bankRequestBody(parsed.fullName) };
+  if (options.dryRun) return { ...request, status: "planned" };
+  let existing;
+  try {
+    existing = await deps.listIssues();
+  } catch (e) {
+    return { ...request, status: "skipped", reason: `could not read ${BANK_REQUEST_REPO} issues: ${oneLine(e)}` };
+  }
+  const plan = planBankRequest(fullName, existing);
+  if (plan.action === "exists") return { ...request, status: "exists", number: plan.number, state: plan.state, url: plan.url };
+  if (plan.action === "skip") return { ...request, status: "skipped", reason: plan.reason };
+  try {
+    const created = await deps.createIssue(request);
+    return { ...request, status: "opened", number: created.number, url: created.url };
+  } catch (e) {
+    return { ...request, status: "skipped", reason: `App issue write failed: ${oneLine(e)}` };
+  }
+}
 
 // src/train-apply-contracts.ts
 var import_node_fs21 = require("node:fs");
@@ -28301,10 +28366,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.33",
+    tag: "v4.6.33",
+    commit: "80768b0b2052",
+    npm: "@mutmutco/cli@4.6.33"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -28321,14 +28386,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.6.31"
+          v3Target: "v4.6.33"
         }
       ],
       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.33 and redeploy the Hub Lambda from tag v4.6.33 (80768b0b2052); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.6.33 (@mutmutco/cli@4.6.33, tag commit 80768b0b2052 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -42556,6 +42621,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 +43795,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 +43809,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 +43897,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 +43921,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 +43959,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 +43999,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 +44145,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 +44356,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 +46300,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 ?? []) {
@@ -51436,6 +51573,7 @@ function registerBootstrapCommands(program3) {
     }
     const actions = [];
     const applied = [];
+    let bankRequest = null;
     let applyDeployModel;
     let applyProjectType;
     try {
@@ -51914,6 +52052,48 @@ ${onlyManagedBlock ? `Only the marker-bounded Hub-managed block inside repo-owne
         applied.push(`ddb register ${registerPayload.slug} (failed: ${why})`);
       }
     }
+    if (!onlyTarget) {
+      bankRequest = await runBankRequest(repo, { dryRun: !o.execute }, {
+        listIssues: async () => {
+          const listed = await gh2([
+            "issue",
+            "list",
+            "--repo",
+            BANK_REQUEST_REPO,
+            "--state",
+            "all",
+            "--search",
+            `in:title "${bankRequestTitle(parsedRepo.name)}"`,
+            "--json",
+            "number,title,state,url",
+            "--limit",
+            "50"
+          ]);
+          const rows = JSON.parse(listed.stdout || "[]");
+          if (!Array.isArray(rows)) throw new Error("issue list is not an array");
+          return rows;
+        },
+        createIssue: async (request) => {
+          const out = await gh2([
+            "issue",
+            "create",
+            "--repo",
+            BANK_REQUEST_REPO,
+            "--title",
+            request.title,
+            "--body",
+            request.body,
+            "--label",
+            request.label
+          ]);
+          const url = out.stdout.trim().split("\n").pop()?.trim() ?? "";
+          const number = Number(/(\d+)$/.exec(url)?.[1]);
+          if (!url || !Number.isFinite(number)) throw new Error(`issue create returned no issue URL: ${out.stdout.trim().slice(0, 200)}`);
+          return { number, url };
+        }
+      });
+      if (o.execute) applied.push(renderBankRequestLine(bankRequest));
+    }
     if (o.execute && !onlyTarget) {
       const github = await readBootstrapGitHubFacts(repo, effectiveTrack, controlClient);
       controlDeployFacts = await fetchDeployFactsBySlug(slug, registryClientDeps(await loadConfig()));
@@ -52009,13 +52189,15 @@ ${onlyManagedBlock ? `Only the marker-bounded Hub-managed block inside repo-owne
         return failGraceful(`bootstrap apply: cannot plan labels/environments; no writes made: ${e.message}`);
       }
     }
-    if (o.json) console.log(JSON.stringify({ repo, class: o.class, sourceSha: seedSource.sha, only: onlyTarget || null, execute: o.execute, seedDelivery: seedPlan.mode, seedBranch: seedPlan.branch, seedBaseSha: scopedPlan?.baseSha, seedPrUrl, actions, controlPlane: controlRows, labels: ancillaryPlan, environments: environmentPlan, applied, ddbWrites }, null, 2));
+    if (o.json) console.log(JSON.stringify({ repo, class: o.class, sourceSha: seedSource.sha, only: onlyTarget || null, execute: o.execute, seedDelivery: seedPlan.mode, seedBranch: seedPlan.branch, seedBaseSha: scopedPlan?.baseSha, seedPrUrl, actions, controlPlane: controlRows, labels: ancillaryPlan, environments: environmentPlan, bankRequest, applied, ddbWrites }, null, 2));
     else {
       console.log(renderSeedPlan(actions));
       if (controlRows.length) console.log(`
 ${renderBootstrapControlPlan(controlRows)}`);
       if (ancillaryPlan && environmentPlan) console.log(`
 ${renderBootstrapAncillaryPlan(ancillaryPlan, environmentPlan, repoEnvironmentSpecs(repo, effectiveTrack, suiteSlug).filter((spec) => spec.exception).map((spec) => ({ name: spec.name, detail: spec.exception })))}`);
+      if (bankRequest?.status === "planned") console.log(`
+${renderBankRequestPlan(bankRequest)}`);
       if (o.execute) console.log(`
 LIVE apply to ${repo}:
   ${applied.join("\n  ")}`);
@@ -56383,6 +56565,7 @@ async function verifyCustodyBootstrap(value, api, controller, requiredContexts,
 // src/release-custody.ts
 var RELEASE_CUSTODY_BRANCH = "mmi-release-state";
 var RELEASE_CUSTODY_PATH = "release-custody.json";
+var HUB_RELEASE_CUSTODY_JOB = "release";
 var ReleaseCustodyError = class extends Error {
   constructor(message2) {
     super("Release custody: " + message2);
@@ -56456,6 +56639,14 @@ function githubCustodyStore(repo, baseSha, api = defaultGitHubClient()) {
         `repos/${repo}/actions/runs/${controller.runId}/attempts/${controller.runAttempt}`
       );
       return run.id === controller.runId && run.run_attempt === controller.runAttempt && run.path === HUB_RELEASE_WORKFLOW && run.status === "completed";
+    },
+    async jobCompleted(controller) {
+      const jobs = await api.rest(
+        "GET",
+        `repos/${repo}/actions/runs/${controller.runId}/attempts/${controller.runAttempt}/jobs?per_page=100`
+      );
+      const job = (jobs?.jobs ?? []).find((row) => row.name === (controller.job ?? HUB_RELEASE_CUSTODY_JOB));
+      return job?.status === "completed" && job.conclusion === "success";
     }
   };
 }
@@ -56474,8 +56665,12 @@ var ReleaseCustodySession = class _ReleaseCustodySession {
   poison;
   static async acquire(store, controller, repo, initialize, prepare) {
     const found = await store.read();
-    if (found.state && !await store.terminal(found.state.controller)) {
-      throw new ReleaseCustodyError(`previous controller run ${found.state.controller.runId} attempt ${found.state.controller.runAttempt} is not proven terminal`);
+    const prior = found.state?.controller;
+    if (prior) {
+      const handoff = prior.runId === controller.runId && prior.runAttempt === controller.runAttempt;
+      if (!(handoff ? await store.jobCompleted(prior) : await store.terminal(prior))) {
+        throw new ReleaseCustodyError(handoff ? `previous controller ${prior.job ?? HUB_RELEASE_CUSTODY_JOB} job of run ${prior.runId} attempt ${prior.runAttempt} is not proven completed` : `previous controller run ${prior.runId} attempt ${prior.runAttempt} is not proven terminal`);
+      }
     }
     let state = {
       ...found.state ?? { schema: "mmi-release-custody/v1", repo, precutId: (0, import_node_crypto21.randomUUID)(), effects: {}, ...await initialize() },
@@ -56773,7 +56968,7 @@ function withHubReleaseCustody(deps) {
         if (!authority.ok || !authority.train || authority.authenticatedDelegation !== true) {
           throw new ReleaseCustodyError("repository custody requires the server-verified owner-triggered train session");
         }
-        const controller = { ...runIdentity, token: (0, import_node_crypto21.randomUUID)() };
+        const controller = { ...runIdentity, token: (0, import_node_crypto21.randomUUID)(), ...process.env.GITHUB_JOB ? { job: process.env.GITHUB_JOB } : {} };
         const raw = localRaw(path2);
         const requiredContexts = () => discoverRequiredCheckContexts(
           deps,
@@ -60899,6 +61094,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 +61128,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 +61165,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 +61238,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 +62902,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 +63036,7 @@ async function sweepWorktreeResidue(gitCommonDir, registered, deps = {}) {
         } catch {
         }
       } else {
-        report.unrecorded.push(child2);
+        report.unrecorded.push(readProvenance(child2, gitCommonDir, exists));
       }
     }
   }
@@ -62780,12 +63050,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 +64212,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 +71842,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 +73948,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/cli/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/codex-plugin",
-  "version": "4.6.31",
+  "version": "4.6.33",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/skills/board/SKILL.md

@@ -13,17 +13,23 @@ permission to take anything.
 
 ```bash
 mkdir -p .jerv/tmp
-mmi-cli oracle board read --json --out .jerv/tmp/board.json
+mmi-cli oracle board read --json --flat --out .jerv/tmp/board.json
 ```
 
-One call; the JSON carries `viewer`, `repo` and the project title. Use `primary` for this repo and
-`secondary` for other repos on the Project. Without `--flat`, `board read --json` returns an object
+One call; `--flat` gives one array of rows to iterate. A routine read already excludes Done and closed
+items, so no status post-filter is needed. The detailed form (`--json` without `--flat`) carries `viewer`,
+`repo` and the project title; use its `primary` for this repo and `secondary` for other repos on the
+Project. Without `--flat`, `board read --json` returns an object
 `{project, viewer, repo, primary, secondary, warnings, partial}` whose `primary` and `secondary` are bucket
 objects `{userOwned, claimable, taken, unownedInFlight}` of item arrays (no top-level `items` array), so filter
-a bucket (e.g. `report.primary.claimable`) or pass `--json --flat`, never `(j.items||j).filter`. `--flat` rows
-are `{ref,number,title,status,assignees,labels,bucket,claim,openPullRequests}` (`claim` is the parsed mmi-claim
-evidence object, null when unclaimed; `openPullRequests` lists the OPEN PRs whose closing-issue body links name
-the item — on the full JSON object that list lives at `report.pullRequests`, never `openPullRequests`). Partial reads
+a bucket (e.g. `report.primary.claimable`) or pass `--json --flat`, never `(j.items||j).filter`. Never sniff
+for the list (`j.items ?? j.rows ?? j`, `Object.values`, any generic "find the list" wrapper): it throws
+`items is not iterable` before any row is read. For a number|status|claim|title projection across non-Done
+rows, run `mmi-cli oracle board read --json --flat --out .jerv/tmp/board.json` and filter that array locally.
+`--flat` rows are `{ref,number,title,status,assignees,labels,bucket,claim,openPullRequests}` (`claim` is the
+parsed mmi-claim evidence object, null when unclaimed; `openPullRequests` lists the OPEN PRs whose
+closing-issue body links name the item — on the full JSON object that list lives at `report.pullRequests`,
+never `openPullRequests`). Partial reads
 exit nonzero; `--allow-partial` only when the dev accepts an incomplete board. The CLI partitions rows into
 **Yours**, **Free to claim** and **Taken**; stale stamps (4 hours without work) hold nothing. Recovery
 moves: a zero-byte or empty `.jerv/tmp/*.json` (`Unexpected end of JSON input`) means a shell-redirected
@@ -33,7 +39,7 @@ item is `mmi-cli oracle board move <status> <ref>`, never a hand-written `gh api
 lookup. Partition rules,
 stamp details and `--out` rationale: [reference.md](reference.md).
 
-**Under the App pool, never type raw `gh` for a read** (`gh issue list/view --jq`, `gh run list --event`/`--jq`, `gh run view --jq`, `gh api -q` all bounce). Use `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json <fields>` (or `issue list`, `pr view`, `run view`, `run list --event <event>`, or `MMI_ACTOR=app mmi-cli devops api get "repos/<owner>/<repo>/actions/runs?event=<event>&per_page=<n>"`); `--jq '<expr>'` on that typed read filters locally. A single issue or PR item (`repos/<owner>/<repo>/issues/<n>` and `pulls/<n>`) has no `devops api get` route — `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner>/<repo> --json <fields>` (and `pr view`) is the only read. Those typed reads take **one** number per call, exactly like native gh: a second number is refused as `too many arguments`, so read several issues by repeating the typed read once per number (one `--jq` each, joined `&&`). Filter in a pipe or save output (`>`, `2>&1`, `--out`) under this worktree's `.jerv/tmp/` (`mkdir -p .jerv/tmp` first), never `../` or a sibling path: the workspace output guard refuses those. Body edits are read-then-edit: `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json body > .jerv/tmp/issue-body.json`, append or filter the JSON locally (`node -e`; the typed read's own `--jq` also filters locally), then write back with `mmi-cli oracle issue edit <ref> --body-file .jerv/tmp/issue-body.md`. When `node -e` reads saved JSON, pass an absolute path or use `JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))`: `require()` of a relative path (e.g. `tmp\board.json` from `cygpath -w`) throws MODULE_NOT_FOUND.
+**Under the App pool, never type raw `gh` for a read** (`gh issue list/view --jq`, `gh run list --event`/`--jq`, `gh run view --jq`, `gh api -q` all bounce). Use `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json <fields>` (or `issue list`, `pr view`, `run view`, `run list --event <event>`, or `MMI_ACTOR=app mmi-cli devops api get "repos/<owner>/<repo>/actions/runs?event=<event>&per_page=<n>"`); `--jq '<expr>'` on that typed read filters locally. A single issue or PR item (`repos/<owner>/<repo>/issues/<n>` and `pulls/<n>`) has no `devops api get` route — `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner>/<repo> --json <fields>` (and `pr view`) is the only read. Those typed reads take **one** number per call, exactly like native gh: a second number is refused as `too many arguments`, so read several issues by repeating the typed read once per number (one `--jq` each, joined `&&`). Filter in a pipe or save output (`--out`, or `>`; never `2>&1` into a JSON parser) under this worktree's `.jerv/tmp/` (`mkdir -p .jerv/tmp` first), never `../` or a sibling path: the workspace output guard refuses those. Body edits are read-then-edit: `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json body > .jerv/tmp/issue-body.json`, append or filter the JSON locally (`node -e`; the typed read's own `--jq` also filters locally), then write back with `mmi-cli oracle issue edit <ref> --body-file .jerv/tmp/issue-body.md`. When `node -e` reads saved JSON, pass an absolute path or use `JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))`: `require()` of a relative path (e.g. `tmp\board.json` from `cygpath -w`) throws MODULE_NOT_FOUND.
 
 ## Step 2 — render it
 

package/skills/board/reference.md

@@ -15,7 +15,10 @@ the gate again.
 Prefer `--out` for a shell-independent UTF-8 receipt. Windows PowerShell 5.1's `>` writes
 UTF-16LE with a BOM (#5802); Bash redirects preserve the CLI's UTF-8 output.
 
-One call. Its JSON carries `viewer`, `repo` and the project title — do not spend extra calls on
+The canonical read is `mmi-cli oracle board read --json --flat --out .jerv/tmp/board.json`: one array of
+rows to iterate. A routine read already excludes Done and closed items, so no status post-filter is needed.
+
+One call. The detailed form (`--json` without `--flat`) carries `viewer`, `repo` and the project title — do not spend extra calls on
 `gh api user` or `gh repo view`. Use `primary` for this repo and `secondary` for other repos on the same
 Project. Without `--flat`, `board read --json` returns an object
 `{project, viewer, repo, primary, secondary, warnings, partial}` whose `primary` and `secondary` are bucket

package/skills/bootstrap/SKILL.md

@@ -55,6 +55,8 @@ mmi-cli devops bootstrap apply "$OWNER/$REPO" --class deployable \
 
 `tenant-container` repos need a `docker-compose.yml` and Dockerfile building from the shipped source archive (no prebuilt `dist/`); bootstrap seeds both from `skills/bootstrap/seeds/`. The seeded compose is fileless: label `mmi.runtime-env: "true"`, no `env_file`, loopback-only port; deploy injects the stage's vault values (`DEPLOY#<stage>.noEnvFile: true`), so the app reads plain env vars, never self-loads SSM, never ships a `.env`. For an MM-Work module or non-suite web-app with OAuth META, read [reference.md](reference.md) before the first CI/deploy or OAuth provisioning.
 
+`bootstrap apply --execute` also asks Jerv-Hub for this repo's coding-agent memory bank, by filing one `bank-request: coding-agent::<RepoName>` issue (label `bank-request`) there; if it reports that step SKIPPED with a manual next step, the MMI App could not file it — file that issue by hand at https://github.com/mutmutco/Jerv-Hub/issues/new and carry on.
+
 **Stage port block:** `tenant-container` and `solo-container` need Hub registry `portRange` (`bootstrap verify` fails without it). `bootstrap apply --execute` assigns it; for older META run `mmi-cli stage port-range <Repo>` (idempotent).
 
 ## Step 7 — org-managed .gitignore block