@mutmutco/cli 4.6.33 → 4.6.35

package/dist/main.cjs

@@ -15497,6 +15497,7 @@ var APP_WRITE_COMMANDS = /* @__PURE__ */ new Map([
   ["run cancel", { metadata: "read", actions: "write" }],
   // #9587: one named run rerun (all or failed jobs) — same actions:write profile, nothing broader.
   ["run rerun", { metadata: "read", actions: "write" }],
+  ["run dispatch", { metadata: "read", actions: "write" }],
   // #9780: repository Actions variables — get/list mint only Variables:read; create/update/delete
   // Variables:write. Repository scope only; no secret store, no rename, no workflow dispatch.
   // #9790: the token key is `actions_variables` (as ci-reconcile.yml mints); `variables` was refused 422.
@@ -28366,10 +28367,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.33",
-    tag: "v4.6.33",
-    commit: "80768b0b2052",
-    npm: "@mutmutco/cli@4.6.33"
+    version: "4.6.35",
+    tag: "v4.6.35",
+    commit: "2a54cf011975",
+    npm: "@mutmutco/cli@4.6.35"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -28386,14 +28387,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.6.33"
+          v3Target: "v4.6.35"
         }
       ],
       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.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)"
+        mechanism: "npm dist-tag latest -> 4.6.35 and redeploy the Hub Lambda from tag v4.6.35 (2a54cf011975); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.6.35 (@mutmutco/cli@4.6.35, tag commit 2a54cf011975 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -30698,6 +30699,8 @@ var CORRELATE_ATTEMPTS = 5;
 var CORRELATE_DELAY_MS = 1500;
 var CORRELATE_SKEW_SLACK_MS = 1e4;
 var CORRELATE_PAGE_LIMIT = 50;
+var GET_PUBLISH_CORRELATE_ATTEMPTS = 12;
+var GET_PUBLISH_CORRELATE_DELAY_MS = 2500;
 var RUN_CONFIRM_ATTEMPTS = 3;
 var RUN_CONFIRM_DELAY_MS = 1e3;
 var defaultSleep = (ms) => new Promise((resolve8) => setTimeout(resolve8, ms));
@@ -30744,11 +30747,13 @@ async function correlateRun(deps, args) {
   const sleep2 = resolveSleep(deps);
   const threshold = args.since - CORRELATE_SKEW_SLACK_MS;
   const repo = args.mode === "workflow" ? args.repo ?? HUB_REPO2 : HUB_REPO2;
+  const attempts = args.mode === "dispatch" ? args.attempts ?? CORRELATE_ATTEMPTS : CORRELATE_ATTEMPTS;
+  const delayMs = args.mode === "dispatch" ? args.delayMs ?? CORRELATE_DELAY_MS : CORRELATE_DELAY_MS;
   let lastError;
   let parsedAnyResponse = false;
   let truncatedWindow = false;
-  for (let attempt = 0; attempt < CORRELATE_ATTEMPTS; attempt++) {
-    if (attempt > 0) await sleep2(CORRELATE_DELAY_MS);
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (attempt > 0) await sleep2(delayMs);
     const listArgs = [
       "run",
       "list",
@@ -30791,7 +30796,7 @@ async function correlateRun(deps, args) {
   if (!parsedAnyResponse) {
     return {
       read: "failed",
-      error: `\`gh run list --workflow ${args.workflow} --repo ${repo}\` failed on all ${CORRELATE_ATTEMPTS} attempts${lastError ? ` (${describeReadError(lastError)})` : ""}`
+      error: `\`gh run list --workflow ${args.workflow} --repo ${repo}\` failed on all ${attempts} attempts${lastError ? ` (${describeReadError(lastError)})` : ""}`
     };
   }
   if (truncatedWindow) {
@@ -30806,7 +30811,7 @@ function correlateTenantRun(deps, since, titleIncludes) {
   return correlateRun(deps, { workflow: "tenant-deploy.yml", since, mode: "dispatch", titleIncludes });
 }
 function correlateGetPublishRun(deps, since, product, mode) {
-  return correlateRun(deps, { workflow: "get-publish.yml", since, mode: "dispatch", titleIncludes: [product, ...mode ? [mode] : []], ...mode ? { requireTitleMatch: true } : {} });
+  return correlateRun(deps, { workflow: "get-publish.yml", since, mode: "dispatch", titleIncludes: [product, ...mode ? [mode] : []], ...mode ? { requireTitleMatch: true } : {}, attempts: GET_PUBLISH_CORRELATE_ATTEMPTS, delayMs: GET_PUBLISH_CORRELATE_DELAY_MS });
 }
 function correlateControlRun(deps, since, titleIncludes) {
   return correlateRun(deps, { workflow: "tenant-control.yml", since, mode: "dispatch", titleIncludes, titleFieldsFrom: 2, ...titleIncludes?.length ? { requireTitleMatch: true } : {} });
@@ -31937,7 +31942,7 @@ async function fetchServedChannelVersion(url, fetchImpl = fetch) {
     return { ok: false, error: e instanceof Error ? e.message : String(e) };
   }
 }
-async function findPriorGreenDispatch(deps, repo, workflow, sha, titleTokens) {
+async function findPriorGreenDispatch(deps, repo, workflow, sha, titleTokens, opts = {}) {
   if (!/^[0-9a-f]{40}$/i.test(sha)) return void 0;
   try {
     const rows = JSON.parse(await deps.run("gh", [
@@ -31956,12 +31961,18 @@ async function findPriorGreenDispatch(deps, repo, workflow, sha, titleTokens) {
       "--json",
       "databaseId,url,status,conclusion,displayTitle,headSha"
     ]));
-    const hit = rows.find((r) => typeof r.databaseId === "number" && r.headSha?.toLowerCase() === sha.toLowerCase() && r.status === "completed" && r.conclusion === "success" && titleTokens.every((t) => (r.displayTitle ?? "").split(/[^\w.-]+/).includes(t)));
-    return hit ? { runId: hit.databaseId, ...hit.url ? { runUrl: hit.url } : {} } : void 0;
+    const titleMatch = (r) => titleTokens.every((t) => (r.displayTitle ?? "").split(/[^\w.-]+/).includes(t));
+    const atSha = (r) => r.headSha?.toLowerCase() === sha.toLowerCase();
+    const hit = rows.find((r) => typeof r.databaseId === "number" && atSha(r) && r.status === "completed" && r.conclusion === "success" && titleMatch(r));
+    if (hit) return { runId: hit.databaseId, ...hit.url ? { runUrl: hit.url } : {} };
+    if (!opts.includeActive) return void 0;
+    const active = rows.find((r) => typeof r.databaseId === "number" && atSha(r) && PRIOR_DISPATCH_ACTIVE_STATUSES.has(r.status ?? "") && titleMatch(r));
+    return active ? { runId: active.databaseId, ...active.url ? { runUrl: active.url } : {}, active: true } : void 0;
   } catch {
     return void 0;
   }
 }
+var PRIOR_DISPATCH_ACTIVE_STATUSES = /* @__PURE__ */ new Set(["in_progress", "queued", "waiting", "requested", "pending"]);
 function planeFailureRow(workflow, evidence) {
   return { workflow, runUrlNote: evidence, conclusion: "failure" };
 }
@@ -32040,10 +32051,13 @@ async function appendMmiGetRedeploy(deps, input, dispatch) {
 async function appendServedChannelStage(deps, input, dispatch) {
   if (!isHubControlRepo(input.repo)) return dispatch;
   const remedy = `${getPublishDispatchCommand(input.repo)} -f mode=stage`;
-  const prior = await findPriorGreenDispatch(deps, input.repo, "get-publish.yml", input.releaseSha, [HUB_SERVED_PRODUCT, "stage"]);
+  const prior = await findPriorGreenDispatch(deps, input.repo, "get-publish.yml", input.releaseSha, [HUB_SERVED_PRODUCT, "stage"], { includeActive: true });
   let row;
-  if (prior) {
+  if (prior && !prior.active) {
     row = { workflow: "get-publish.yml", runId: prior.runId, ...prior.runUrl ? { runUrl: prior.runUrl } : {}, conclusion: "success" };
+  } else if (prior?.active) {
+    row = { workflow: "get-publish.yml", runId: prior.runId, ...prior.runUrl ? { runUrl: prior.runUrl } : {}, conclusion: "pending" };
+    if (input.watch) row.conclusion = await watchTenantRun(deps, prior.runId, input.repo);
   } else {
     const since = (deps.now ?? Date.now)();
     try {
@@ -32058,7 +32072,7 @@ async function appendServedChannelStage(deps, input, dispatch) {
       };
     }
     const correlated = await correlateGetPublishRun(deps, since, HUB_SERVED_PRODUCT, "stage");
-    if (correlated.read !== "found") {
+    if (correlated.read === "failed") {
       return {
         ...dispatch,
         note: `${dispatch.note}; get-publish stage dispatched but its run could not be READ \u2014 check Actions; recover with \`${remedy}\``,
@@ -32066,6 +32080,14 @@ async function appendServedChannelStage(deps, input, dispatch) {
         workflowRuns: [...dispatch.workflowRuns ?? [], planeFailureRow("get-publish.yml", "stage dispatched, but its run could not be read")]
       };
     }
+    if (correlated.read === "absent") {
+      const dispatchedAt = new Date(since).toISOString();
+      return {
+        ...dispatch,
+        note: `${dispatch.note}; get-publish stage dispatched at ${dispatchedAt} but its run is not listed yet \u2014 recorded PENDING; \`devops release --resume\` re-correlates it by title and time`,
+        workflowRuns: [...dispatch.workflowRuns ?? [], { workflow: "get-publish.yml", runUrlNote: `stage dispatched ${dispatchedAt}; run not listed within the correlation window`, conclusion: "pending", dispatchedAt, titleTokens: [HUB_SERVED_PRODUCT, "stage"] }]
+      };
+    }
     row = { workflow: "get-publish.yml", runId: correlated.runId, ...correlated.runUrl ? { runUrl: correlated.runUrl } : {}, conclusion: "pending" };
     if (input.watch) row.conclusion = await watchTenantRun(deps, correlated.runId, input.repo);
   }
@@ -32090,12 +32112,15 @@ async function appendServedChannelPublish(deps, input, dispatch, redeployed) {
   if (input.publishStatus !== "success") {
     return withNote(`served channel NOT moved (publish did not succeed) \u2014 after the publish is green, run \`${remedy}\``);
   }
-  const prior = input.releaseSha ? await findPriorGreenDispatch(deps, input.repo, "get-publish.yml", input.releaseSha, [HUB_SERVED_PRODUCT, "pointer"]) : void 0;
+  const prior = input.releaseSha ? await findPriorGreenDispatch(deps, input.repo, "get-publish.yml", input.releaseSha, [HUB_SERVED_PRODUCT, "pointer"], { includeActive: true }) : void 0;
   let runRow;
   let runStatus;
-  if (prior) {
+  if (prior && !prior.active) {
     runRow = { workflow: "get-publish.yml", runId: prior.runId, ...prior.runUrl ? { runUrl: prior.runUrl } : {} };
     runStatus = "success";
+  } else if (prior?.active) {
+    runRow = { workflow: "get-publish.yml", runId: prior.runId, ...prior.runUrl ? { runUrl: prior.runUrl } : {} };
+    runStatus = input.watch ? await watchTenantRun(deps, prior.runId, input.repo) : "pending";
   } else {
     const version = input.tag?.replace(/^v/, "") ?? (deps.readLauncherVersion ?? readLocalLauncherVersion)();
     if (!version) return withNote("the local launcher version could not be read \u2014 nothing was compared, so the move is unverified");
@@ -32107,9 +32132,17 @@ async function appendServedChannelPublish(deps, input, dispatch, redeployed) {
       return withNote(`get-publish dispatch FAILED: ${msg}. The release itself landed, but the SERVED CHANNEL IS UNCHANGED \u2014 recover with \`${pointerRemedy}\``, "failure", planeFailureRow("get-publish.yml", `dispatch refused: ${msg}`));
     }
     const correlated = await correlateGetPublishRun(deps, since, HUB_SERVED_PRODUCT, "pointer");
-    if (correlated.read !== "found") {
+    if (correlated.read === "failed") {
       return withNote(`get-publish dispatched but its run could not be READ: ${correlated.error ?? "no matching run appeared"}. Check the Actions tab; if it never ran, recover with \`${pointerRemedy}\``, "failure", planeFailureRow("get-publish.yml", `dispatched, but its run could not be read`));
     }
+    if (correlated.read === "absent") {
+      const dispatchedAt = new Date(since).toISOString();
+      return {
+        ...dispatch,
+        note: `${dispatch.note}; get-publish pointer dispatched at ${dispatchedAt} but its run is not listed yet \u2014 recorded PENDING; \`devops release --resume\` re-correlates it by title and time`,
+        workflowRuns: [...dispatch.workflowRuns ?? [], { workflow: "get-publish.yml", runUrlNote: `pointer dispatched ${dispatchedAt}; run not listed within the correlation window`, conclusion: "pending", dispatchedAt, titleTokens: [HUB_SERVED_PRODUCT, "pointer"] }]
+      };
+    }
     const { runId, runUrl } = correlated;
     runRow = { workflow: "get-publish.yml", ...runId ? { runId } : {}, ...runUrl ? { runUrl } : {} };
     if (!input.watch) {
@@ -32121,7 +32154,7 @@ async function appendServedChannelPublish(deps, input, dispatch, redeployed) {
     }
     runStatus = await watchTenantRun(deps, runId, input.repo);
   }
-  if (runStatus !== "success") {
+  if (runStatus === "failure") {
     return {
       ...dispatch,
       note: `${dispatch.note}; get-publish.yml ${runStatus} \u2014 the SERVED CHANNEL IS UNCHANGED; recover with \`${pointerRemedy}\``,
@@ -32129,6 +32162,13 @@ async function appendServedChannelPublish(deps, input, dispatch, redeployed) {
       deployStatus: "failure"
     };
   }
+  if (runStatus === "pending") {
+    return {
+      ...dispatch,
+      note: `${dispatch.note}; get-publish.yml pointer run is still unverified (pending) \u2014 the served channel move is not yet proven; \`devops release --resume\` re-reads it`,
+      workflowRuns: [...dispatch.workflowRuns ?? [], { ...runRow, conclusion: "pending" }]
+    };
+  }
   const expected = input.tag ? input.tag.replace(/^v/, "") : (deps.readLauncherVersion ?? readLocalLauncherVersion)();
   const runs2 = [...dispatch.workflowRuns ?? [], { ...runRow, conclusion: "success" }];
   if (!channelUrl) {
@@ -32269,6 +32309,14 @@ async function appendInstallHomePublish(deps, input, dispatch) {
       deployStatus: "failure"
     };
   }
+  if (correlated.read === "absent") {
+    const dispatchedAt = new Date(since).toISOString();
+    return {
+      ...dispatch,
+      note: note(`installer home publish for ${product} dispatched at ${dispatchedAt} but its run is not listed yet \u2014 recorded PENDING; \`devops release --resume\` re-correlates it by title and time`),
+      workflowRuns: [...dispatch.workflowRuns ?? [], { workflow: "get-publish.yml", runUrlNote: `installer home (${product}) dispatched ${dispatchedAt}; run not listed within the correlation window`, conclusion: "pending", dispatchedAt, titleTokens: [product] }]
+    };
+  }
   const row = { workflow: "get-publish.yml", ...correlated.runId ? { runId: correlated.runId } : {}, ...correlated.runUrl ? { runUrl: correlated.runUrl } : {} };
   if (!input.watch) {
     return {
@@ -32278,7 +32326,7 @@ async function appendInstallHomePublish(deps, input, dispatch) {
     };
   }
   const status = await watchTenantRun(deps, correlated.runId, HUB_REPO2);
-  if (status !== "success") {
+  if (status === "failure") {
     return {
       ...dispatch,
       note: note(`get-publish.yml (product=${product}) ${status} \u2014 the INSTALLER HOME IS UNCHANGED; recover with \`${remedy}\``),
@@ -32286,6 +32334,13 @@ async function appendInstallHomePublish(deps, input, dispatch) {
       deployStatus: "failure"
     };
   }
+  if (status === "pending") {
+    return {
+      ...dispatch,
+      note: note(`get-publish.yml (product=${product}) run is still unverified (pending) \u2014 the installer home is not yet proven published; \`devops release --resume\` re-reads it`),
+      workflowRuns: [...dispatch.workflowRuns ?? [], { ...row, conclusion: "pending" }]
+    };
+  }
   return {
     ...dispatch,
     note: note(`installer home published for ${product} (get-publish.yml green)`),
@@ -32324,8 +32379,10 @@ async function appendServedChannelLegs(deps, input, dispatch) {
     ]);
     return mergeServedLegs(dispatch, home2, proof2);
   }
-  const stageGreen = (prepared.workflowRuns ?? []).filter((r) => r.workflow === "get-publish.yml").every((r) => r.conclusion === "success");
-  const channel = stageGreen || !isHubControlRepo(input.repo) || publishStatus !== "success" ? await appendServedChannelPublish(deps, { repo: input.repo, publishStatus, watch: input.watch, releaseSha: input.releaseSha, tag: input.tag }, dispatch, Promise.resolve(prepared)) : { ...dispatch, note: `${dispatch.note}; served channel NOT moved (stage not green) \u2014 recover with \`${getPublishDispatchCommand(input.repo)} -f mode=stage\`, then \`${getPublishDispatchCommand(input.repo)} -f mode=pointer -f version=${input.tag.replace(/^v/, "")}\`` };
+  const stageRows = (prepared.workflowRuns ?? []).filter((r) => r.workflow === "get-publish.yml");
+  const stageGreen = stageRows.every((r) => r.conclusion === "success");
+  const stagePending = !stageGreen && stageRows.every((r) => r.conclusion !== "failure");
+  const channel = stageGreen || !isHubControlRepo(input.repo) || publishStatus !== "success" ? await appendServedChannelPublish(deps, { repo: input.repo, publishStatus, watch: input.watch, releaseSha: input.releaseSha, tag: input.tag }, dispatch, Promise.resolve(prepared)) : { ...dispatch, note: `${dispatch.note}; served channel NOT moved (stage ${stagePending ? "still pending \u2014 `devops release --resume` re-correlates the stage run and moves the pointer" : "not green"}) \u2014 recover with \`${getPublishDispatchCommand(input.repo)} -f mode=stage\`, then \`${getPublishDispatchCommand(input.repo)} -f mode=pointer -f version=${input.tag.replace(/^v/, "")}\`` };
   const out = mergeServedLegs(dispatch, {
     ...dispatch,
     note: dispatch.note + prepared.note,
@@ -44822,6 +44879,56 @@ function registerRunRerun(run, writeToken, projects) {
   });
 }
 
+// src/run-dispatch.ts
+init_cli_shared();
+async function dispatchWorkflow(repo, workflow, ref, inputs, deps) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) throw new Error("run dispatch: invalid repository");
+  if (!/^[A-Za-z0-9_.-]+\.ya?ml$/.test(workflow)) throw new Error("run dispatch: workflow must be a YAML filename");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/.test(ref) || ref.includes("..") || ref.includes("//") || ref.endsWith("/")) throw new Error("run dispatch: invalid ref");
+  if (inputs.length > 10) throw new Error("run dispatch: at most 10 inputs");
+  const fields = ["-f", `ref=${ref}`];
+  const names = /* @__PURE__ */ new Set();
+  for (const input of inputs) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]{0,63})=([^\r\n]{0,2048})$/.exec(input);
+    if (!match || names.has(match[1])) throw new Error("run dispatch: invalid or duplicate input");
+    names.add(match[1]);
+    fields.push("-f", `inputs[${match[1]}]=${match[2]}`);
+  }
+  const projects = await deps.projects();
+  if (!projects) throw new Error("run dispatch: registry unavailable; no dispatch attempted");
+  if (!projects.some((p) => (p.repos ?? []).some((r) => typeof r === "string" && registryRepoKey(qualifyRegistryRepo(r)) === registryRepoKey(repo)))) {
+    throw new Error("run dispatch: repository is not registered; no dispatch attempted");
+  }
+  let status;
+  try {
+    status = await deps.post(`repos/${repo}/actions/workflows/${workflow}/dispatches`, fields);
+  } catch {
+    throw new Error("run dispatch: outcome unknown; inspect GitHub before any retry");
+  }
+  if (status !== 204) throw new Error("run dispatch: outcome unknown; inspect GitHub before any retry");
+  return { ok: true, repo, workflow, ref, credential: "app_installation", status: "dispatch-requested", httpStatus: status };
+}
+function appDispatchPost(writeToken, exec3 = execFileP) {
+  return async (path2, fields) => {
+    const token = await writeToken();
+    const { stdout } = await exec3("gh", ["api", "--include", "--method", "POST", path2, ...fields], {
+      timeout: 2e4,
+      env: { ...process.env, GH_TOKEN: token, MMI_GH_POOL: "app" }
+    });
+    return Number(/^HTTP\/[\d.]+ (\d{3})/.exec(stdout)?.[1] ?? 0);
+  };
+}
+function registerRunDispatch(run, writeToken, projects) {
+  run.command("dispatch <workflow>").description("request one workflow dispatch using the org App; an ambiguous result is never retried").requiredOption("--repo <owner/repo>", "registered repository").requiredOption("--ref <ref>", "workflow ref").option("--input <name=value>", "workflow input (repeatable)", (v, values) => [...values, v], []).option("--json", "machine-readable receipt").action(async (workflow, options) => {
+    try {
+      const receipt = await dispatchWorkflow(options.repo, workflow, options.ref, options.input, { projects, post: appDispatchPost(writeToken) });
+      console.log(options.json ? JSON.stringify(receipt) : `run dispatch: requested ${receipt.repo}/${receipt.workflow} at ${receipt.ref}`);
+    } catch (error) {
+      return fail(error.message);
+    }
+  });
+}
+
 // src/devops-vars.ts
 var import_node_crypto13 = require("node:crypto");
 init_github_client();
@@ -46300,7 +46407,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\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";
+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:\n  {project, viewer, repo, primary, secondary, items, 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 for ownership context:\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\n`items` (#9974) is that same flat row array, already on the full report: {ref,number,title,status,assignees,labels,bucket,claim,openPullRequests}\n  node -e \"const b=require('./.jerv/tmp/board.json');for(const i of b.items)console.log(i.number,i.status,i.title)\"\nIt is built from the same flattener as --flat, so `const rows = j.items || j` is now safe on either form.\n\nAdd --flat with --json for that array as the WHOLE output (no project/viewer/warnings envelope):\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 read `report.items` (or `primary`/`secondary`) by name. `j.items ?? j.rows ?? j`,\n`Object.values(j)` and any generic \"find the list\" wrapper are still guesses: before `items` existed they\nthrew `items is not iterable` before any row was read (#9956), and `j.rows` has never been a key. For a\nnumber|status|claim|title projection across non-Done rows, read --json --flat --out .jerv/tmp/board.json\nand filter that array locally (identical rows to `report.items`):\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 ?? []) {
@@ -46322,6 +46429,9 @@ function flattenBoardReport(report) {
     openPullRequests: closingByRef.get(ref) ?? []
   }))));
 }
+function withBoardItems(report) {
+  return { ...report, items: flattenBoardReport(report) };
+}
 function registerBoardCommands(program3) {
   function withDiscoverMissDetail(message2) {
     const miss = lastBoardDiscoverMiss();
@@ -46346,7 +46456,7 @@ function registerBoardCommands(program3) {
         snapshotOnly: o.snapshotOnly,
         ...o.minCursor !== void 0 ? { minCursor: Number(o.minCursor) } : {}
       }, o.direct ? {} : { snapshot: registryClientDeps(config) });
-      const output = o.json ? JSON.stringify(o.flat ? flattenBoardReport(report) : report) : renderBoardReport(report);
+      const output = o.json ? JSON.stringify(o.flat ? flattenBoardReport(report) : withBoardItems(report)) : renderBoardReport(report);
       if (!o.out) console.log(output);
       else console.log(`Wrote board read to ${o.out} (UTF-8, ${writeUtf8Receipt(o.out, output)} bytes)`);
     } catch (e) {
@@ -61128,9 +61238,10 @@ 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),
-    observePolicy(deps, refs.candidate)
+    observePolicy(deps, refs.candidate),
+    refs.candidate ? deps.queueWaiver?.(refs.candidate) : Promise.resolve(void 0)
   ]);
-  const [claims, docs, policy] = reads;
+  const [claims, docs, policy, waiver] = reads;
   if (claims.status === "fulfilled") {
     observations.push(...claims.value.findings.length ? claims.value.findings.map((detail) => ({ check: "claims", state: "failed", detail })) : [{ check: "claims", state: "passed", detail: "issue and claim evidence read" }]);
   } else observations.push({ check: "claims", state: "unavailable", detail: `issue/claim evidence unavailable (${rejectionReason(claims.reason)}); retry the read` });
@@ -61138,6 +61249,8 @@ async function preparePrCreate(input, deps = createPreparationDeps(input)) {
   else if (docs.value) observations.push({ check: "docs", state: docs.value.state, detail: [docs.value.detail, docs.value.fix].filter(Boolean).join(" \u2014 ") });
   if (policy.status === "rejected") observations.push({ check: "policy", state: "unavailable", detail: `committed test-policy observation unavailable (${rejectionReason(policy.reason)}); check policy validity and fetch full candidate history before retrying` });
   else if (policy.value) observations.push(policy.value);
+  if (waiver.status === "rejected") observations.push({ check: "queue", state: "skipped", detail: `the queue squash waiver placement was not checked (${rejectionReason(waiver.reason)}); this is non-blocking` });
+  else if (waiver.value) observations.push(waiver.value);
   const findings = observations.filter((item) => item.state === "failed" || item.state === "unavailable");
   let attempted = false;
   return {
@@ -61238,6 +61351,34 @@ function createPreparationDeps(input, io = {}) {
   return {
     candidate: readCandidate,
     publish: (proof) => publishPreparedPrHead(proof, exec3),
+    // #9831/#9968: publication happens only in commit(), after this read-only preparation, so the queue's
+    // buried-waiver refusal is decided here — with the queue's own reader and setting reads — before an
+    // absent remote head is pushed and a PR opened. A range or setting it cannot read is a skip (#9968).
+    queueWaiver: async (candidate) => {
+      const result = (state, detail) => ({ check: "queue", state, detail });
+      if (!candidate.root) return void 0;
+      const range = await exec3("git", ["-C", candidate.root, "log", "--reverse", "--format=%B%x00", `${candidate.baseSha}..${candidate.headSha}`], { timeout: GIT_TIMEOUT_MS }).then((read) => ({ log: read.stdout }), (error) => ({ reason: rejectionReason(error) }));
+      if (!("log" in range)) return result("skipped", `candidate commits ${candidate.baseSha}..${candidate.headSha} could not be read (${range.reason}), so the queue squash waiver placement was not checked; this is non-blocking`);
+      const messages = range.log.split("\0").filter((message2) => message2.trim()).map((message2) => {
+        const [headline, ...body] = message2.trim().split("\n");
+        return { headline, body: body.join("\n") };
+      });
+      const refusal = checkQueueSquashOverride("Candidate PR", "0", messages, candidate.root);
+      if (!refusal) return void 0;
+      const [owner, name] = candidate.repo.split("/");
+      const setting = await (async () => {
+        const metadata = await client.graphql(
+          "query($owner:String!,$name:String!,$base:String!) { repository(owner:$owner,name:$name) { squashMergeCommitMessage mergeQueue(branch:$base) { configuration { mergeMethod } } } }",
+          { owner, name, base: candidate.base }
+        );
+        const rules = await client.restPaginate(`repos/${candidate.repo}/rules/branches/${encodeURIComponent(candidate.base)}?per_page=100`);
+        const methods = [...new Set(rules.filter((rule) => rule.type === "merge_queue").map((rule) => rule.parameters?.merge_method))];
+        const method = methods.length === 1 ? methods[0] : !methods.length ? metadata.repository.mergeQueue?.configuration?.mergeMethod : void 0;
+        return method === "SQUASH" && metadata.repository.squashMergeCommitMessage === "COMMIT_MESSAGES";
+      })().then((squash) => squash, (error) => rejectionReason(error));
+      if (typeof setting === "string") return result("skipped", `the repository's queue squash-message setting could not be read (${setting}), so the queue squash waiver placement was not checked; this is non-blocking`);
+      return setting ? result("failed", `${refusal.error} \u2014 ${refusal.preparation.nextAction}`) : void 0;
+    },
     // #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.
@@ -61258,25 +61399,6 @@ function createPreparationDeps(input, io = {}) {
       if (!await docs.refResolves(candidate.root, candidate.headSha) || !await docs.refResolves(candidate.root, candidate.baseSha)) {
         return result("skipped", "exact remote candidate objects are not available locally; committed test policy was not checked");
       }
-      const log = (await exec3("git", ["-C", candidate.root, "log", "--reverse", "--format=%B%x00", `${candidate.baseSha}..${candidate.headSha}`], { timeout: GIT_TIMEOUT_MS })).stdout;
-      const messages = log.split("\0").filter((message2) => message2.trim()).map((message2) => {
-        const [headline, ...body] = message2.trim().split("\n");
-        return { headline, body: body.join("\n") };
-      });
-      const refusal = checkQueueSquashOverride("Candidate PR", "0", messages, candidate.root);
-      if (refusal) {
-        const [owner, name] = candidate.repo.split("/");
-        const metadata = await client.graphql(
-          "query($owner:String!,$name:String!,$base:String!) { repository(owner:$owner,name:$name) { squashMergeCommitMessage mergeQueue(branch:$base) { configuration { mergeMethod } } } }",
-          { owner, name, base: candidate.base }
-        );
-        const rules = await client.restPaginate(`repos/${candidate.repo}/rules/branches/${encodeURIComponent(candidate.base)}?per_page=100`);
-        const methods = [...new Set(rules.filter((rule) => rule.type === "merge_queue").map((rule) => rule.parameters?.merge_method))];
-        const method = methods.length === 1 ? methods[0] : !methods.length ? metadata.repository.mergeQueue?.configuration?.mergeMethod : void 0;
-        if (method === "SQUASH" && metadata.repository.squashMergeCommitMessage === "COMMIT_MESSAGES") {
-          return result("failed", `${refusal.error} \u2014 ${refusal.preparation.nextAction}`);
-        }
-      }
       let policy;
       try {
         policy = runTestPolicy(candidate.root, { candidate: { head: candidate.headSha, base: candidate.baseSha } });
@@ -63054,9 +63176,11 @@ function renderResidueSweepLines(report) {
     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): ${listed.map((u) => u.path).join(", ")}${more}`);
     for (const u of listed) lines2.push(`pr merge:   left untouched ${u.path} \u2014 ${provenanceText(u)}`);
+    lines2.push(`pr merge:   recovery: ${RESIDUE_RECOVERY_MOVE}`);
   }
   return lines2;
 }
+var RESIDUE_RECOVERY_MOVE = `run \`git worktree list --porcelain\` in the primary checkout and confirm the path is absent and its provenance above shows no live lane (not registered; admin dir gone or .git pointer missing); nothing can record it for this sweep (only \`pr merge\` records its own merged worktree in <git-common-dir>/${RESIDUE_LEDGER_FILE}), so removing a non-empty unrecorded folder stays a human decision \u2014 hand the confirmed path to a human; this sweep never deletes it`;
 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"}`;
@@ -73836,6 +73960,7 @@ registerPreAction.call(program2, "preAction", async (_thisCommand, actionCommand
     "ci cancel-orphans",
     "run cancel",
     "run rerun",
+    "run dispatch",
     // #9779/#9780: the vars verbs and archive-status validate --repo/name/value before the first
     // dispatch, so their scoped App mint waits for the action handler like the run writes above.
     "vars get",
@@ -74715,13 +74840,18 @@ ci.command("hosted-usage").description("read-only hosted tick and lane-demand al
 });
 registerCiChecksWait(ci);
 registerCancelOrphans(ci, async () => (await mintCommandWriteToken(appActorDeps(), "ci cancel-orphans")).token);
-var runRoot = program2.command("run").description("bounded workflow-run writes \u2014 `run cancel <id>` and `run rerun <id> [--failed]`, both on the org App actions:write profile");
+var runRoot = program2.command("run").description("bounded workflow-run writes on the org App actions:write profile");
 registerRunCancel(runRoot, async () => activeAppToken() ?? (await mintCommandWriteToken(appActorDeps(), "run cancel")).token);
 registerRunRerun(
   runRoot,
   async () => activeAppToken() ?? (await mintCommandWriteToken(appActorDeps(), "run rerun")).token,
   async () => fetchProjectsList(registryClientDeps(await loadConfig()))
 );
+registerRunDispatch(
+  runRoot,
+  async () => (await mintCommandWriteToken(appActorDeps(), "run dispatch")).token,
+  async () => fetchProjectsList(registryClientDeps(await loadConfig()))
+);
 var varsAppClient = (commandPath4) => async () => (
   // The concrete client always provides restWithStatus (optional on the interface only so hand-built
   // test stubs of GitHubClient keep compiling).

package/package.json

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