@mutmutco/codex-plugin 4.6.1 → 4.6.2

package/.codex-plugin/plugin.json

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

package/cli/dist/main.cjs

@@ -189,6 +189,7 @@ async function finishCliRun(watchdogMs = CLI_EXIT_WATCHDOG_MS) {
   }, watchdogMs);
   timer.unref?.();
   await closeHttpPool();
+  await flushStdio();
 }
 function describeActiveHandles() {
   let summary;
@@ -555,6 +556,7 @@ async function githubKeyringTokenRead() {
   return cachedGhCliTokenRead;
 }
 async function githubTokenRead() {
+  if (process.env.MMI_GH_POOL === "app" && process.env.GH_TOKEN) return { state: "ok", token: process.env.GH_TOKEN };
   const mmiPat = process.env.MMI_GH_PAT?.trim();
   if (mmiPat) return { state: "ok", token: mmiPat };
   if (process.env.GH_TOKEN) return { state: "ok", token: process.env.GH_TOKEN };
@@ -15445,8 +15447,10 @@ async function activateAppActor(commandPath4, env, mint, note = (line) => proces
       }
       return "personal";
     }
+    delete env.MMI_GH_PAT;
     throw e;
   }
+  delete env.MMI_GH_PAT;
   env.GH_TOKEN = minted.token;
   env.MMI_GH_POOL = "app";
   activeQuotaScope = minted.quotaScope;
@@ -21561,7 +21565,8 @@ async function postIssueComment(client, input) {
     number: parsed.number,
     repo,
     url: `https://github.com/${repo}/issues/${parsed.number}`,
-    commentUrl: comment.html_url
+    commentUrl: comment.html_url,
+    ...comment.user?.login ? { author: comment.user.login } : {}
   };
 }
 
@@ -22079,19 +22084,19 @@ function evaluateClaim(item, login) {
   if (others.length && item.status === "In Review") {
     return {
       ok: false,
-      reason: `${item.ref} is not claimable: In Review and held by @${others.join(", @")} \u2014 ask the holder, or wait for the review to land`
+      reason: `${item.ref} is not claimable: In Review and held by @${others.join(", @")} \u2014 ask the holder, or wait for the review to land (never chain separate claims with && \u2014 a refused claim aborts the chain; pass all refs in one batch call, e.g. \`mmi-cli oracle board claim <ref> <ref>\`)`
     };
   }
-  if (others.length) return { ok: false, reason: `${item.ref} is already assigned to @${others.join(", @")}` };
+  if (others.length) return { ok: false, reason: `${item.ref} is already assigned to @${others.join(", @")} (never chain separate claims with && \u2014 a refused claim aborts the chain; pass all refs in one batch call, e.g. \`mmi-cli oracle board claim <ref> <ref>\`)` };
   if (item.status === "In Progress" && mine) return { ok: true, alreadyClaimed: true };
   if (item.status === "Done") {
     return {
       ok: false,
-      reason: `${item.ref} is not claimable: Status is Done \u2014 claim does not reopen terminal cards; skip completed items and pass only open issues (never chain separate claims with &&)`
+      reason: `${item.ref} is not claimable: Status is Done \u2014 claim does not reopen terminal cards; skip completed items and pass only open issues (never chain separate claims with && \u2014 a refused claim aborts the chain; pass all refs in one batch call, e.g. \`mmi-cli oracle board claim <ref> <ref>\`)`
     };
   }
   if (item.status !== "Todo" && item.status !== "In Progress" && item.status !== "In Review") {
-    return { ok: false, reason: `${item.ref} is not claimable: Status is ${item.status}` };
+    return { ok: false, reason: `${item.ref} is not claimable: Status is ${item.status} (never chain separate claims with && \u2014 a refused claim aborts the chain; pass all refs in one batch call, e.g. \`mmi-cli oracle board claim <ref> <ref>\`)` };
   }
   return { ok: true, alreadyClaimed: false };
 }
@@ -23600,10 +23605,11 @@ async function claimOneBoardItem(ctx, selector, options) {
   let staleStamp;
   const tookOver = () => ({ outcome: "took-over", holder, previousHolder, ...staleStamp ? { staleStamp } : {} });
   const claimedReceipt = () => ({
+    held: true,
     ...item.status === "In Review" ? { reclaimedFrom: "In Review" } : {},
     ...previousHolder ? resumeEvidence ? { outcome: "resumed", holder, previousHolder, resumeEvidence } : tookOver() : { outcome: "claimed", holder }
   });
-  const heldReceipt = () => previousHolder ? resumeEvidence ? { outcome: "resumed", holder, previousHolder, resumeEvidence } : tookOver() : { outcome: "held", holder };
+  const heldReceipt = () => ({ held: true, ...previousHolder ? resumeEvidence ? { outcome: "resumed", holder, previousHolder, resumeEvidence } : tookOver() : { outcome: "held", holder } });
   if (flatItem.contentType !== "Issue") throw new Error(`${flatItem.ref} is not an issue`);
   const pre = evaluateClaim(flatItem, assignedLogin);
   if (!pre.ok) throw new NotClaimableError(pre.reason, { ref: flatItem.ref, status: flatItem.status });
@@ -23714,7 +23720,7 @@ async function claimBoardIssues(options, deps = {}) {
       const ref = `${selector.repo}#${selector.number}`;
       try {
         const result = await claimOneBoardItem(ctx, selector, { ...options, bulk: true });
-        results[index] = { ref: result.item.ref, claimed: true, item: result.item, status: result.status, partial: result.partial, warning: result.warning, outcome: result.outcome, holder: result.holder, previousHolder: result.previousHolder, resumeEvidence: result.resumeEvidence, staleStamp: result.staleStamp, reclaimedFrom: result.reclaimedFrom, alreadyClaimed: result.alreadyClaimed, renewed: result.renewed, checked: result.checked, credential: result.credential };
+        results[index] = { ref: result.item.ref, claimed: true, item: result.item, status: result.status, partial: result.partial, warning: result.warning, outcome: result.outcome, held: result.held, holder: result.holder, previousHolder: result.previousHolder, resumeEvidence: result.resumeEvidence, staleStamp: result.staleStamp, reclaimedFrom: result.reclaimedFrom, alreadyClaimed: result.alreadyClaimed, renewed: result.renewed, checked: result.checked, credential: result.credential };
       } catch (e) {
         results[index] = { ref, claimed: false, reason: e.message };
       }
@@ -24816,7 +24822,7 @@ function checkRunbookCoverage(docs, base, git3) {
       const globs = lines2.slice(heading.start, markerEnd - 1).flatMap((text) => /<!--\s*runbook-covers:\s*(.*?)\s*-->/.exec(text)?.[1].split(",").map((s) => s.trim()) ?? []);
       const affected = changed.filter((path2) => globs.some((glob) => matches(glob, path2)) && !changesOnlyUses(path2));
       if (affected.length && !ranges.some((r) => r.count > 0 && r.start < end && r.start + r.count > heading.start)) {
-        findings.push({ kind: "runbook-section-stale", doc, line: heading.start, detail: `${heading.title}: changed ${affected.join(", ")}; update this section's text or runbook-covers list, or add a \`Runbook-Unaffected: <reason>\` trailer to a commit message in this PR`, section: { heading: heading.title, level: heading.level, startLine: heading.start, endLine: end - 1, covers: globs }, sources: affected });
+        findings.push({ kind: "runbook-section-stale", doc, line: heading.start, detail: `${heading.title} (lines ${heading.start}\u2013${end - 1}): changed ${affected.join(", ")}; update this section's text (lines ${heading.start}\u2013${end - 1}) or runbook-covers list, or add a \`Runbook-Unaffected: <reason>\` trailer to a commit message in this PR`, section: { heading: heading.title, level: heading.level, startLine: heading.start, endLine: end - 1, covers: globs }, sources: affected });
       }
     }
   }
@@ -25117,7 +25123,7 @@ function createDocsIndexDeps(repoRoot2) {
 // src/gate-budget.ts
 var BLESSED_RUN_WITH_BUDGET_SHA = "5ce541add569e54e7ca96de67a768577d3d604e4";
 var BLESSED_RUNNER_GATE_SHA = "a19e9392e5ad9b0675f02e4304d68dd933fad60f";
-var BLESSED_KIT_AGENT_FILES_SHA = "a8b273ed418e703c0aa501a53ea87228ba28b1f0";
+var BLESSED_KIT_AGENT_FILES_SHA = "e976df208d891b215844386c1cac0f161946b6fa";
 var BLESSED_JEV_FAILURES_SHA = "d5278c6133318b33727483ddfdfddc8f841e3ef6";
 var BLESSED_RUNBOOK_GUARD_SHA = "e661e0aedc0e58b73c738bf6cdfeac65e5914584";
 var REMOTE_USE = /^mutmutco\/MMI-Hub\/\.github\/actions\/run-with-budget@(\S+)$/;
@@ -27280,10 +27286,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.1",
-    tag: "v4.6.1",
-    commit: "9077f0af09b6",
-    npm: "@mutmutco/cli@4.6.1"
+    version: "4.6.2",
+    tag: "v4.6.2",
+    commit: "1708e0fdc55b",
+    npm: "@mutmutco/cli@4.6.2"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -27300,14 +27306,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.6.1"
+          v3Target: "v4.6.2"
         }
       ],
       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.1 and redeploy the Hub Lambda from tag v4.6.1 (9077f0af09b6); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.6.1 (@mutmutco/cli@4.6.1, tag commit 9077f0af09b6 \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.6.2 and redeploy the Hub Lambda from tag v4.6.2 (1708e0fdc55b); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.6.2 (@mutmutco/cli@4.6.2, tag commit 1708e0fdc55b \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -58054,10 +58060,11 @@ function registerCollaborationCommands(program3) {
           return;
         } catch (reRead) {
           const reErr = reRead;
-          return fail(`issue view: ${repo}#${n} was transferred to ${moved.repo}#${moved.number} (${moved.url}), but re-reading it there failed: ${(reErr.stderr || reErr.message || String(reRead)).trim()}`);
+          return await failGraceful(`issue view: ${repo}#${n} was transferred to ${moved.repo}#${moved.number} (${moved.url}), but re-reading it there failed: ${(reErr.stderr || reErr.message || String(reRead)).trim()}`);
         }
       }
-      return fail(`issue view: ${raw}${argvNote}`);
+      const repoHint = /Could not resolve to an issue/i.test(raw) ? ` (if #${n} is in another repository, pass --repo <owner/repo>)` : "";
+      return await failGraceful(`issue view: ${raw}${repoHint}${argvNote}`);
     }
   });
   issue.command("discover-related").description("find related issues for an existing issue and post only high-confidence links").requiredOption("--number <number>", "created issue number").requiredOption("--title <title>", "created issue title").requiredOption("--body <body>", "created issue body").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "print candidates instead of posting").option("--fail-soft", "suppress errors (used by the background auto-caller; direct runs fail loudly)").action(async (o) => {
@@ -58723,7 +58730,8 @@ ${preparation.findings.map((finding) => `[${finding.check}/${finding.state}] ${f
         readMergeQueue: readPrMergeQueue,
         findMergeGroupRun: findPrMergeGroupRun,
         queueProgress: (receipt) => {
-          if (!o.json) printLine(prMergeQueueLine(receipt));
+          const line = prMergeQueueLine(receipt);
+          if (line) (o.json ? console.warn : printLine)(line);
         },
         resolveRepo: async (prNumber, repoOpt) => {
           const knownRepo = repoOpt ?? await resolveRepo(o.repo).catch(() => void 0) ?? o.repo;
@@ -64567,6 +64575,7 @@ function parseBrokerJsonFields(raw, allowed) {
   return value;
 }
 var BROKER_JSON_FLAGS_NOTE = "gh formatter flags are refused (--template can read child credentials; --web opens a browser) \u2014 use --json with field selection; --jq filters the returned JSON locally with the system jq, never inside gh";
+var JQ_HELP = "filter the returned JSON locally with the system jq (gh --jq habit; JSON stdout only; jq never sees a credential) (#8966)";
 var JQ_MAX_LENGTH = 4e3;
 function parseBrokerJq(raw) {
   if (!raw.trim() || raw.length > JQ_MAX_LENGTH) {
@@ -64611,6 +64620,14 @@ function parseBrokerIssueState(raw) {
   return v;
 }
 var RUN_LIST_STATUSES = ["queued", "completed", "in_progress", "requested", "waiting", "pending", "action_required", "cancelled", "failure", "neutral", "skipped", "stale", "startup_failure", "success", "timed_out"];
+function parseBrokerRunEvent(raw) {
+  if (raw === void 0) return void 0;
+  const event = raw.trim();
+  if (!/^[A-Za-z0-9_]{1,64}$/.test(event)) {
+    throw new Error(`read: --event must be a workflow trigger event name like pull_request, merge_group, push, workflow_dispatch (received '${raw}')`);
+  }
+  return event;
+}
 function parseBrokerRunStatus(raw) {
   if (raw === void 0) return void 0;
   const v = raw.trim().toLowerCase();
@@ -64706,6 +64723,8 @@ function buildRunListSpec(o) {
   if (branch) args.push("--branch", branch);
   const commit = parseBrokerCommit(o.commit);
   if (commit) args.push("--commit", commit);
+  const event = parseBrokerRunEvent(o.event);
+  if (event) args.push("--event", event);
   const status = parseBrokerRunStatus(o.status);
   if (status) args.push("--status", status);
   const created = parseBrokerCreated(o.created);
@@ -64721,17 +64740,21 @@ function buildRunWatchSpec(id, o) {
   const timeoutMin = o.timeoutMin !== void 0 ? parseBrokerInt(o.timeoutMin, "--timeout", 1, 120) : 30;
   return { program: "gh", args, timeoutMs: timeoutMin * 6e4 };
 }
-function rejectPrViewQueueFields(fields, number) {
-  if (!fields || !fields.split(",").includes("mergeQueueEntry")) return;
+function rejectPrViewQueueFields(fields, number, repo) {
+  const badField = fields?.split(",").find((field) => field === "mergeQueueEntry" || field === "isInMergeQueue");
+  if (!badField) return;
+  const targetRepo2 = repo ?? "<owner/repo>";
+  const remaining = fields?.split(",").filter((f) => f && f !== "mergeQueueEntry" && f !== "isInMergeQueue").join(",") ?? "";
   throw new Error(
-    `read pr view: 'mergeQueueEntry' is not a gh pr view --json field \u2014 read the merge queue with \`mmi-cli devops read pr queue ${number} --repo <owner/repo> --json\` and drop it from --json`
+    `read pr view: '${badField}' is not a gh pr view --json field \u2014 read the merge queue with \`mmi-cli devops read pr queue ${number} --repo ${targetRepo2} --json\` and drop it from --json${remaining ? `; for the remaining fields run \`mmi-cli devops read pr view ${number}${repo ? ` --repo ${repo}` : ""} --json ${remaining}\`` : ""}`
   );
 }
 function buildPrViewSpec(ref, o) {
   const number = parseBrokerId(ref, "PR number");
   const jsonFields = parseBrokerJsonFields(o.json);
-  rejectPrViewQueueFields(jsonFields, number);
-  const args = withJson(withRepo(["pr", "view", number], parseBrokerRepo(o.repo, "--repo")), jsonFields, o.json);
+  const repo = parseBrokerRepo(o.repo, "--repo");
+  rejectPrViewQueueFields(jsonFields, number, repo);
+  const args = withJson(withRepo(["pr", "view", number], repo), jsonFields, o.json);
   if (o.comments) args.push("--comments");
   return { program: "gh", args, timeoutMs: SINGLE_SHOT_TIMEOUT_MS };
 }
@@ -64807,8 +64830,8 @@ function ghExitCodeOf(error) {
 function brokerGhFailureHint(failureText, args) {
   const target = args[0] === "pr" && args[1] === "view" ? args[2] : void 0;
   const unknownField = /Unknown JSON field: "([^"]+)"/.exec(failureText)?.[1] ?? /Unknown JSON field: ([A-Za-z][A-Za-z0-9]*)/.exec(failureText)?.[1];
-  if (unknownField === "mergeQueueEntry") {
-    return `'mergeQueueEntry' is not a gh pr view --json field \u2014 read the merge queue with \`mmi-cli devops read pr queue ${target ?? "<number>"} --repo <owner/repo> --json\` and drop it from --json; repeating this read cannot succeed`;
+  if (unknownField === "mergeQueueEntry" || unknownField === "isInMergeQueue") {
+    return `'${unknownField}' is not a gh pr view --json field \u2014 read the merge queue with \`mmi-cli devops read pr queue ${target ?? "<number>"} --repo <owner/repo> --json\` and drop it from --json; repeating this read cannot succeed`;
   }
   if (unknownField) {
     return `gh rejected --json field '${unknownField}' \u2014 drop it or use the typed read whose fields cover it (the "Available fields" list gh printed is its own vocabulary)`;
@@ -64950,7 +64973,6 @@ function registerAppReadBrokerCommands(program3, resolveRepo2, overrides) {
   const runStatusOpt = (v) => parseBrokerRunStatus(v);
   const assigneeOpt = (v) => parseBrokerAssignee(v);
   const jqOpt = (v) => parseBrokerJq(v);
-  const JQ_HELP = "filter the returned JSON locally with the system jq (gh --jq habit; needs --json; jq never sees a credential) (#8966)";
   const read = program3.command("read").description(`closed typed GitHub reads on the App pool (${BROKER_JSON_FLAGS_NOTE})`);
   const run = read.command("run").description("workflow-run reads (view/list/watch pass gh through; log is a bounded App REST read)");
   registerRunLogRead(run, overrides?.apiRunner);
@@ -64964,7 +64986,7 @@ function registerAppReadBrokerCommands(program3, resolveRepo2, overrides) {
     }
     await dispatchGh(spec, "read run view", o.jq);
   });
-  run.command("list").description("list workflow runs (workflow/branch/commit/status/created/limit/json; formatters refused)").option("--repo <owner/repo>", "target repo (defaults to the current repo)", repoOpt).option("--json [fields]", "machine-readable output (comma-separated gh fields)", jsonOpt).option("--workflow <name>", "filter by workflow name or file", workflowOpt).option("--branch <name>", "filter by branch", branchOpt).option("--commit <sha>", "filter by the full 40-character head commit SHA (#8937)", (v) => parseBrokerCommit(v)).option("--status <status>", "filter by run status", runStatusOpt).option("--created <filter>", 'only runs created in this window, e.g. ">=2026-10-11T00:30:00Z" (#8096)', (v) => parseBrokerCreated(v)).option("--limit <n>", "maximum runs to fetch (1-100; larger values clamp to 100)", limitOpt).option("--jq <expr>", JQ_HELP, jqOpt).action(async (o) => {
+  run.command("list").description("list workflow runs (workflow/branch/commit/status/event/created/limit/json; formatters refused)").option("--repo <owner/repo>", "target repo (defaults to the current repo)", repoOpt).option("--json [fields]", "machine-readable output (comma-separated gh fields)", jsonOpt).option("--workflow <name>", "filter by workflow name or file", workflowOpt).option("--branch <name>", "filter by branch", branchOpt).option("--commit <sha>", "filter by the full 40-character head commit SHA (#8937)", (v) => parseBrokerCommit(v)).option("--status <status>", "filter by run status", runStatusOpt).option("-e, --event <event>", "filter by workflow trigger event (e.g. pull_request, merge_group, push, workflow_dispatch)", (v) => parseBrokerRunEvent(v)).option("--created <filter>", 'only runs created in this window, e.g. ">=2026-10-11T00:30:00Z" (#8096)', (v) => parseBrokerCreated(v)).option("--limit <n>", "maximum runs to fetch (1-100; larger values clamp to 100)", limitOpt).option("--jq <expr>", JQ_HELP, jqOpt).action(async (o) => {
     let spec;
     try {
       requireJqJson(o.jq, o.json);
@@ -65173,11 +65195,18 @@ function orgScopedHint(path2) {
   const surface = runners ? `Runner/lane state has no App-token read: a human token holder answers it with \`gh api orgs/${org}/actions/runners\` (docs/Guides/gh-runner-runbook.md).` : "It needs a human token holder with an org-scoped token, or a dedicated mmi-cli verb when one exists for this resource.";
   return ` This route is ORG-SCOPED (\`orgs/${org}/...\`) and is deliberately outside the allowlist \u2014 no App-token read exists for org-level resources, so retrying path variants cannot work and no \`repos/{owner}/{repo}/...\` respelling of it will be accepted. ${surface} A refusal writes nothing to stdout: check the exit code and never merge stderr into the JSON pipe (2>&1).`;
 }
+function tagsReadHint(path2) {
+  const match = new RegExp(`^repos/(${NAME})/(${NAME})/(?:tags|git/(?:refs|matching-refs|tags|commits))(?:[/?#]|$)`).exec(path2);
+  if (!match) return "";
+  const slug = `${match[1]}/${match[2]}`;
+  return ` No App-token REST read exists for git tags or refs \u2014 read git tags directly with \`git ls-remote --tags origin 'refs/tags/*'\` (no token needed; \`git ls-remote origin refs/tags/<tag>\` for one tag), or read tag-backed GitHub Releases with \`MMI_ACTOR=app mmi-cli devops api get "repos/${slug}/releases?per_page=20"\`.`;
+}
 function parseApiGetPath(rawPath) {
   const path2 = rawPath.trim();
   const refuse = () => {
     const hint = /^[A-Za-z]:[/\\]/.test(path2) ? " Git Bash/MSYS may have rewritten a leading-slash argument; retry with MSYS_NO_PATHCONV=1 and the slash-free repos/... path. The endpoint must still be allowlisted." : "";
-    return new Error(`api get: refusing '${rawPath}' \u2014 only these GET reads are allowed (#7219): ${API_GET_ALLOWED_SHAPES}.${API_GET_RECOVERY}${typedReadHint(path2)}${runsReadHint(path2)}${orgScopedHint(path2)}${hint}`);
+    const routeHints = `${typedReadHint(path2)}${runsReadHint(path2)}${orgScopedHint(path2)}${tagsReadHint(path2)}${hint}`;
+    return new Error(`api get: refusing '${rawPath}' \u2014${routeHints}${API_GET_RECOVERY} Only these GET reads are allowed (#7219): ${API_GET_ALLOWED_SHAPES}.`);
   };
   if (/[%#\\]/.test(path2) || path2.split("?")[0].split("/").some((seg) => seg === "." || seg === ".." || seg === "")) throw refuse();
   const q = path2.indexOf("?");
@@ -65225,11 +65254,13 @@ async function readAppApi(path2, runner = apiReadRunner) {
 }
 function registerApiReadCommands(program3, overrides) {
   const spawn7 = overrides?.runner ?? apiReadRunner;
+  const jqRun = overrides?.jqRunner ?? systemJqRunner;
   const api = program3.command("api").description("bounded GitHub REST reads for automation \u2014 GET only, allowlisted paths (pull files, compare, contents, actions runs/jobs/artifacts, releases)");
   api.command("get").description("GET one allowlisted REST path and print the response body to stdout (JSON, or raw file bytes with --accept raw); refuses everything outside the allowlist").option("--accept <type>", "response media type: json (default) or raw (file bytes)", (v) => {
     acceptHeaderFor(v);
     return v.trim().toLowerCase();
-  }, "json").option("--out <file>", "write response bytes to a file (required for, and only valid with, actions artifact zips, job logs, and release assets)").argument("<path>", "allowlisted GET path (shapes named on refusal)", (v) => parseApiGetPath(v)).action(async (req, o) => {
+  }, "json").option("--jq <expr>", JQ_HELP, (v) => parseBrokerJq(v)).option("--out <file>", "write response bytes to a file (required for, and only valid with, actions artifact zips, job logs, and release assets)").argument("<path>", "allowlisted GET path (shapes named on refusal)", (v) => parseApiGetPath(v)).action(async (req, o) => {
+    if (o.jq !== void 0 && (o.accept === "raw" || o.out !== void 0)) return fail("api get: --jq is only valid with JSON stdout reads (not --accept raw or --out)");
     const zip = req.kind === "actions-artifact-zip" || req.kind === "actions-job-logs" || req.kind === "release-asset";
     if (zip !== (o.out !== void 0)) return fail(`api get: --out <file> is required for, and only valid with, repos/{owner}/{repo}/actions/artifacts/{id}/zip and repos/{owner}/{repo}/actions/jobs/{id}/logs and repos/{owner}/{repo}/releases/assets/{id}`);
     const appRoute = req.kind.startsWith("actions-") || req.kind.startsWith("release-");
@@ -65242,6 +65273,7 @@ function registerApiReadCommands(program3, overrides) {
         req.path,
         o.accept
       );
+      if (o.jq !== void 0) body = await jqRun(o.jq, body, localJqEnv());
       if (zip) {
         (0, import_node_fs56.writeFileSync)(o.out, body, "latin1");
         return;
@@ -68188,7 +68220,9 @@ function registerDeveloperCommands(program3) {
         );
         return;
       }
-      console.error("doc refs: unresolved references");
+      const hasStale = result.findings.some((f) => f.kind === "runbook-section-stale" || f.kind === "seed-runbook-unreviewed");
+      const hasRefs = result.findings.some((f) => f.kind !== "runbook-section-stale" && f.kind !== "seed-runbook-unreviewed");
+      console.error(hasStale && !hasRefs ? "doc refs: stale runbook section(s)" : hasStale && hasRefs ? "doc refs: unresolved references and stale runbook section(s)" : "doc refs: unresolved references");
       for (const f of result.findings) console.error(`- ${f.doc}:${f.line} [${f.kind}] ${f.detail}`);
       process.exitCode = 1;
     } catch (e) {

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.6.1",
+  "version": "4.6.2",
   "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.1",
+  "version": "4.6.2",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/skills/org-guide/references/work-and-releases.md

@@ -151,9 +151,11 @@ Impeccable **v4.7.0 / engine v0.1.16** details:
   `NODE_AUTH_TOKEN=$(gh auth token) npm view @mutmutco/mmwork-ds@<v> version --registry https://npm.pkg.github.com`;
   from a root without that line, pass the token directly —
   `npm view @mutmutco/mmwork-ds@<v> version --registry https://npm.pkg.github.com --//npm.pkg.github.com/:_authToken=$(gh auth token)`.
-  To see **which** kit versions are actually published, list the scope's GitHub Packages versions instead
-  of deriving it — `gh api '/orgs/mutmutco/packages/npm/mmwork-ds/versions?per_page=3' --jq '.[]|.name+" "+.created_at'`
-  (newest first, no npm token; #9264). That is the supported listing read:
+  To see **which** kit versions are actually published, run MMI-Hub's
+  `node scripts/kit-adopt.mjs --list-versions [--limit 5] [--json]` (#9426) instead of deriving it: it reads GitHub
+  Packages `/orgs/mutmutco/packages/npm/mmwork-ds/versions` (newest first, falling back to `npm view` against
+  `https://npm.pkg.github.com` with `GH_PACKAGES_READ_TOKEN`/`NODE_AUTH_TOKEN`), reports the local cache's latest
+  version, and never hits the `registry.npmjs.org` 404 of a bare `npm view @mutmutco/mmwork-ds` (#9264). That is the supported listing read:
   `mmi-cli devops packages` covers consumer adoption (`adopt-export`) only, so it never names a published
   version — never carry the packages API as a stopgap.
 - Boot once: `impeccable context --target <path>`; `init` captures PRODUCT.md, `document` maintains