dev-loops 0.6.0 → 0.7.2

package/scripts/github/reply-resolve-review-threads.mjs

@@ -12,6 +12,7 @@ import {
   replyAndMaybeResolve,
   validateResolutionMessage,
 } from "./_review-thread-mutations.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: reply-resolve-review-threads.mjs --repo <owner/name> --pr <number> [--author <login>] [--message <text>] [--resolve]
 Reply to all matching unresolved review threads on one PR and optionally resolve them.
 Required:
@@ -30,9 +31,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   Runtime/gh failures:
     { "ok": false, "error": "...", "partialProgress"?: { ... } }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh/runtime failure`.trim();
+  1  Argument error or gh/runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseReplyResolveThreadsCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -44,6 +47,7 @@ export function parseReplyResolveThreadsCliArgs(argv) {
       author: { type: "string" },
       message: { type: "string" },
       resolve: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -88,6 +92,7 @@ export function parseReplyResolveThreadsCliArgs(argv) {
       options.resolve = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -111,6 +116,62 @@ async function readStdinText(stdin) {
   }
   return text;
 }
+// When --message is set, stdin is read only to detect a conflicting second
+// message source. A detached/idle pipe never sends EOF, so an unbounded read
+// hangs forever and the process never exits (issue #1012). Resolve as soon as
+// any NON-WHITESPACE byte arrives (a conflicting body is detected the instant
+// real content appears — no need to wait for EOF); keep buffering while only
+// whitespace has arrived (a leading newline is not yet a conflict and more may
+// follow); resolve on natural EOF; and time out on a silent/idle pipe. Either
+// way the stdin handle is released so the event loop can drain and the tool
+// always terminates.
+const CONFLICT_STDIN_TIMEOUT_MS = 500;
+function readStdinConflictProbe(stdin, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer;
+    const cleanup = () => {
+      clearTimeout(timer);
+      stdin.off?.("data", onData);
+      stdin.off?.("end", onEnd);
+      stdin.off?.("error", onEnd);
+      // Release the handle: an abandoned reader on a still-open pipe would
+      // otherwise keep the event loop alive and re-introduce the hang.
+      stdin.pause?.();
+      if (typeof stdin.unref === "function") {
+        stdin.unref();
+      } else {
+        stdin.destroy?.();
+      }
+    };
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    // Resolve early only once non-whitespace content is seen (a real conflict);
+    // '' or whitespace-only on clean EOF is not a conflict; undefined only on
+    // timeout (idle pipe) so the caller proceeds with --message.
+    let text = "";
+    const onData = (chunk) => {
+      text += String(chunk);
+      if (text.trim().length > 0) {
+        finish(text);
+      }
+    };
+    const onEnd = () => finish(text);
+    timer = setTimeout(() => finish(undefined), timeoutMs);
+    timer.unref?.();
+    stdin.setEncoding?.("utf8");
+    stdin.on?.("data", onData);
+    stdin.on?.("end", onEnd);
+    stdin.on?.("error", onEnd);
+  });
+}
+
 async function resolveMessageInput(options, { stdin = process.stdin } = {}) {
   if (typeof options.message === "string") {
     if (stdin.isTTY) {
@@ -119,8 +180,8 @@ async function resolveMessageInput(options, { stdin = process.stdin } = {}) {
       }
       return options.message;
     }
-    const stdinText = await readStdinText(stdin);
-    if (stdinText.trim().length > 0) {
+    const stdinText = await readStdinConflictProbe(stdin, CONFLICT_STDIN_TIMEOUT_MS);
+    if (typeof stdinText === "string" && stdinText.trim().length > 0) {
       throw parseError("Choose exactly one message source: --message <text> or stdin");
     }
     if (options.message.trim().length === 0) {
@@ -241,6 +302,7 @@ export async function runCli(
   {
     stdin = process.stdin,
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -258,7 +320,7 @@ export async function runCli(
   );
   const { matchedTargets, skippedThreadCount } = planBatchReplyTargets(parsed, options.author);
   if (matchedTargets.length === 0) {
-    stdout.write(`${JSON.stringify(createSuccessPayload({
+    process.exitCode = emitResult(createSuccessPayload({
       repo: options.repo,
       pr: options.pr,
       author: options.author,
@@ -268,7 +330,7 @@ export async function runCli(
       resolvedThreadCount: 0,
       skippedThreadCount,
       results: [],
-    }))}\n`);
+    }), { jq: options.jq, silent: options.silent, stdout, stderr });
     return;
   }
   const results = [];
@@ -328,7 +390,7 @@ export async function runCli(
   }
   const repliedThreadCount = results.length;
   const resolvedThreadCount = results.filter((entry) => entry.resolved).length;
-  stdout.write(`${JSON.stringify(createSuccessPayload({
+  process.exitCode = emitResult(createSuccessPayload({
     repo: options.repo,
     pr: options.pr,
     author: options.author,
@@ -338,7 +400,7 @@ export async function runCli(
     resolvedThreadCount,
     skippedThreadCount,
     results,
-  }))}\n`);
+  }), { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/github/request-copilot-review.mjs

@@ -2,6 +2,7 @@
 import { parseArgs } from "node:util";
 import {
   buildParseError,
+  containsBareCopilotSummon,
   formatCliError,
   isCopilotLogin,
   isDirectCliRun,
@@ -14,7 +15,8 @@ import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.m
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState } from "@dev-loops/core/loop/copilot-loop-state";
-import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveRefinement } from "@dev-loops/core/config";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const BLOCKED_BY_COPILOT_COMMENT_STATUS = "blocked_by_copilot_comment";
 const SUPPRESSED_SAME_HEAD_CLEAN_STATUS = "suppressed_same_head_clean";
 const ROUND_CAP_REACHED_STATUS = "round_cap_reached";
@@ -29,13 +31,19 @@ Optional:
   --force-rerequest-review  Bypass the round cap when new commits exist since
                             the last Copilot review. Refused when the PR head
                             has not changed since the last review.
+  --lightweight             This PR is light-dispatched (#1210): enforce the
+                            composed round cap min(localImplementation.lightMode.
+                            maxCopilotRounds ?? 1, refinement.maxCopilotRounds)
+                            instead of refinement.maxCopilotRounds alone.
 Debug:
   DEVLOOPS_DEBUG=1      Emit stderr traces when best-effort same-head clean
                             convergence detection falls back to unsuppressed behavior
 Output (stdout, JSON):
   { "ok": true, "status": "requested"|"already-requested"|"unavailable"|"suppressed_same_head_clean"|"blocked_by_copilot_comment"|"round_cap_reached"|"no_changes_since_last_review"|"suppressed_draft",
     "repo": "...", "pr": N, "reviewer": "Copilot", "detail"?: "...",
-    "sameHeadCleanConverged"?: true, "violationCommentIds"?: [N], "completedRounds"?: N, "maxRounds"?: N }
+    "sameHeadCleanConverged"?: true, "violationCommentIds"?: [N], "completedRounds"?: N, "maxRounds"?: N,
+    "configWarning"?: "..." (present only when --lightweight and dev-loop config failed to load/validate;
+                             the lightweight default cap of 1 was applied instead of the full-PR default) }
 Request statuses:
   requested                     Copilot review was successfully requested
   already-requested             Copilot review was already observably in progress; no new request needed
@@ -50,9 +58,22 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
+Status contract: "ok": true means the helper ran without error, NOT that a
+review was placed. Callers MUST branch on "status", never on "ok" truthiness
+alone — every non-"requested" status (including blocked_by_copilot_comment)
+is a caller-must-branch outcome, not a silent success.
+--silent exit code: 0 only when status is "requested" (a new request was just
+placed this run); non-zero for every other status, including
+already-requested/suppressed_same_head_clean/unavailable/blocked_by_copilot_comment/
+round_cap_reached/no_changes_since_last_review/suppressed_draft. Without
+--silent the JSON body always prints regardless of status. --jq combined with
+--silent keeps the shared jq-stream truthiness semantics (exit reflects the
+filtered value) and is exempt from the status-based rule above.
 Exit codes:
-  0  Success (including unavailable)
-  1  Argument error or gh failure`.trim();
+  0  Success (including unavailable); with --silent, only when status is "requested"
+  1  Argument error, gh failure, or (--silent) any non-"requested" status
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseRequestCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -60,8 +81,10 @@ export function parseRequestCliArgs(argv) {
     options: {
       help: { type: "boolean", short: "h" },
       "force-rerequest-review": { type: "boolean" },
+      lightweight: { type: "boolean" },
       repo: { type: "string" },
       pr: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -72,6 +95,7 @@ export function parseRequestCliArgs(argv) {
     repo: undefined,
     pr: undefined,
     forceRerequestReview: false,
+    lightweight: false,
   };
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -88,6 +112,10 @@ export function parseRequestCliArgs(argv) {
       options.forceRerequestReview = true;
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
     if (token.name === "repo") {
       options.repo = requireTokenValue(token, parseError).trim();
       continue;
@@ -96,6 +124,7 @@ export function parseRequestCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -437,7 +466,9 @@ export async function checkForCopilotComments({ repo, pr }, { env = process.env,
     if (isCopilotLogin(author)) {
       continue;
     }
-    if (/(?:^|\W)(@copilot|\/copilot)(?:$|\W)/i.test(body)) {
+    // Exempt bare-text occurrences inside inline code spans/fenced blocks: a
+    // gate-evidence comment legitimately quotes the anti-summon rule itself.
+    if (containsBareCopilotSummon(body)) {
       violationCommentIds.push(comment.id);
     }
   }
@@ -474,16 +505,47 @@ export async function performCopilotReviewRequest(options, { env = process.env,
   }
   let refinementConfig = { maxCopilotRounds: 5 };
   let maxRounds = 5; // Built-in default; overridden by config when loadable
+  // Lightweight fallback when config is unreadable/invalid: fail toward the
+  // SAFE (smaller) lightweight cap instead of silently inheriting the
+  // full-PR default of 5 above, which would let a light-dispatched PR run
+  // far more review rounds than intended whenever the config can't be read.
+  const LIGHTWEIGHT_DEFAULT_CAP = 1;
+  let configWarning = null;
   try {
     const { config, errors } = await loadDevLoopConfig();
     if (!errors || errors.length === 0) {
       refinementConfig = resolveRefinement(config);
-      if (Number.isFinite(refinementConfig.maxCopilotRounds) && refinementConfig.maxCopilotRounds > 0) {
-        maxRounds = refinementConfig.maxCopilotRounds;
+      // Light-dispatched PRs (#1210) enforce the COMPOSED cap —
+      // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds) — so
+      // this enforcement backstop cannot permit rounds beyond the lightweight cap.
+      const effectiveCap = options.lightweight
+        ? resolveEffectiveCopilotRoundCap(config, { lightweight: true })
+        : refinementConfig.maxCopilotRounds;
+      // >= 0 (not > 0): maxCopilotRounds: 0 is documented as "disable Copilot
+      // rounds"; it must be honored as an immediate refusal, not silently
+      // ignored in favor of the built-in default of 5.
+      if (Number.isFinite(effectiveCap) && effectiveCap >= 0) {
+        maxRounds = effectiveCap;
       }
+      if (options.lightweight) {
+        refinementConfig = { ...refinementConfig, maxCopilotRounds: effectiveCap };
+      }
+    } else if (options.lightweight) {
+      maxRounds = LIGHTWEIGHT_DEFAULT_CAP;
+      refinementConfig = { ...refinementConfig, maxCopilotRounds: LIGHTWEIGHT_DEFAULT_CAP };
+      configWarning = `dev-loop config could not be validated; using the lightweight default cap of ${LIGHTWEIGHT_DEFAULT_CAP} instead of the full-PR default. errors=${JSON.stringify(errors)}`;
+    }
+  } catch (err) {
+    if (options.lightweight) {
+      maxRounds = LIGHTWEIGHT_DEFAULT_CAP;
+      refinementConfig = { ...refinementConfig, maxCopilotRounds: LIGHTWEIGHT_DEFAULT_CAP };
+      configWarning = `dev-loop config could not be loaded; using the lightweight default cap of ${LIGHTWEIGHT_DEFAULT_CAP} instead of the full-PR default. error=${err instanceof Error ? err.message : String(err)}`;
     }
-  } catch {
   }
+  // Every remaining return in this function is config-dependent (round-cap
+  // decisions, the request itself); surface a config-load fallback on all of
+  // them rather than just the path a given test happens to exercise.
+  const withConfigWarning = (result) => (configWarning ? { ...result, configWarning } : result);
   // Reconcile the completed-round count with detect-pr-gate-coordination-state (#896):
   // when the raw count has reached the cap, re-derive it with the draft-gate round
   // reset applied. A clean draft_gate re-pass on an earlier head resets the count, so
@@ -506,7 +568,7 @@ export async function performCopilotReviewRequest(options, { env = process.env,
         refinementConfig,
       );
       if (!roundCapAutoRerequest.eligible) {
-        return {
+        return withConfigWarning({
           ok: true,
           status: ROUND_CAP_REACHED_STATUS,
           repo: options.repo,
@@ -515,7 +577,7 @@ export async function performCopilotReviewRequest(options, { env = process.env,
           completedRounds,
           maxRounds,
           detail: `Round cap of ${maxRounds} reached with ${completedRounds} completed rounds. No further re-requests will be made.`,
-        };
+        });
       }
     }
     // --force-rerequest-review: only bypass when there are new commits since the last review
@@ -526,7 +588,7 @@ export async function performCopilotReviewRequest(options, { env = process.env,
     const canCompare = currentHeadSha !== null && lastReviewSha !== null;
     const hasNewCommits = canCompare && currentHeadSha !== lastReviewSha;
     if (!canCompare) {
-      return {
+      return withConfigWarning({
         ok: true,
         status: ROUND_CAP_REACHED_STATUS,
         repo: options.repo,
@@ -535,10 +597,10 @@ export async function performCopilotReviewRequest(options, { env = process.env,
         detail: `Round cap of ${maxRounds} reached with ${completedRounds} completed rounds. --force-rerequest-review was supplied but commit SHA data is unavailable, so change-since-last-review could not be evaluated.`,
         completedRounds,
         maxRounds,
-      };
+      });
     }
     if (!hasNewCommits) {
-      return {
+      return withConfigWarning({
         ok: true,
         status: NO_CHANGES_SINCE_LAST_REVIEW_STATUS,
         repo: options.repo,
@@ -547,7 +609,7 @@ export async function performCopilotReviewRequest(options, { env = process.env,
         detail: "No changes since last Copilot review. --force-rerequest-review requires new commits on the PR head.",
         completedRounds,
         maxRounds,
-      };
+      });
     }
     // Has new commits — bypass the round cap and proceed with the request
   }
@@ -557,7 +619,7 @@ export async function performCopilotReviewRequest(options, { env = process.env,
     before,
   );
   if (sameHeadCleanConverged) {
-    return {
+    return withConfigWarning({
       ok: true,
       status: SUPPRESSED_SAME_HEAD_CLEAN_STATUS,
       repo: options.repo,
@@ -565,35 +627,35 @@ export async function performCopilotReviewRequest(options, { env = process.env,
       reviewer: "Copilot",
       sameHeadCleanConverged: true,
       detail: "Current head already has a clean submitted Copilot review; same-head clean-convergence suppression is always enforced.",
-    };
+    });
   }
   if (before.requested || before.hasPendingReviewOnCurrentHead) {
-    return {
+    return withConfigWarning({
       ok: true,
       status: "already-requested",
       repo: options.repo,
       pr: options.pr,
       reviewer: "Copilot",
-    };
+    });
   }
   const requestResult = await requestCopilotReview(options, { env, ghCommand });
   if (requestResult.status === "unavailable") {
     const after = await fetchCopilotReviewState(options, { env, ghCommand });
     if (after.requested || after.hasPendingReviewOnCurrentHead || after.hasSubmittedReviewOnCurrentHead) {
-      return {
+      return withConfigWarning({
         ok: true,
         status: "already-requested",
         repo: options.repo,
         pr: options.pr,
         reviewer: "Copilot",
-      };
+      });
     }
-    return {
+    return withConfigWarning({
       ...requestResult,
-    };
+    });
   }
   if (requestResult.status === "already-requested") {
-    return requestResult;
+    return withConfigWarning(requestResult);
   }
   const after = await fetchCopilotReviewState(options, { env, ghCommand });
   const reviewCountIncreased = after.copilotReviewIds.length > before.copilotReviewIds.length;
@@ -601,14 +663,15 @@ export async function performCopilotReviewRequest(options, { env = process.env,
   if (!reviewNowObservablyInProgress) {
     throw new Error("Copilot review request did not appear in requested reviewers or fresh/in-progress Copilot reviews after gh pr edit");
   }
-  return {
+  return withConfigWarning({
     ...requestResult,
-  };
+  });
 }
 export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -619,7 +682,16 @@ export async function runCli(
     return;
   }
   const result = await performCopilotReviewRequest(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  // Honest status under --silent: `ok: true` reports "the helper ran without
+  // error", not "a review was placed" — a caller checking only exit-code
+  // truthiness must NOT read a non-`requested` status (blocked_by_copilot_comment,
+  // round_cap_reached, etc.) as a placed request. --silent therefore answers
+  // "was a request just placed" specifically: exit 0 only for `requested`,
+  // non-zero for every other status. Non-silent output is unaffected — the full
+  // JSON body (with `ok: true`) still prints for every documented status; the
+  // caller MUST branch on `.status`, not `.ok`.
+  const silentOk = options.silent ? result.status === "requested" : undefined;
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr, ok: silentOk });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/github/resolve-handoff-candidates.mjs

@@ -9,6 +9,7 @@ import {
   loadDevLoopConfig,
   resolveHumanHandoffConfig,
 } from "@dev-loops/core/config";
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: resolve-handoff-candidates.mjs --repo <owner/name> --pr <number> [--changed-files <a,b,c>] [--pr-author <login>]
 Resolve an ordered, deduped list of human-handoff reviewer/assignee candidates
@@ -39,9 +40,11 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "enabled": bool, "candidates": [{ "login", "source", "isTeam"?, "paths"? }],
     "changedFiles": [...], "sources": [...], "warnings": [...] }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (including disabled no-op and fail-soft per-source skips)
-  1  Argument error`.trim();
+  1  Argument error
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -74,6 +77,8 @@ export function parseResolveCandidatesCliArgs(argv) {
       continue;
     }
     if (token === "--pr-author") { options.prAuthor = nextValue(args, ++i, "--pr-author").trim().replace(/^@/, ""); continue; }
+    if (token === "--jq") { options.jq = nextValue(args, ++i, "--jq"); continue; }
+    if (token === "--silent" || token === "-s") { options.silent = true; continue; }
     throw parseError(`Unknown argument: ${token}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -403,8 +408,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     { repo: options.repo, pr: options.pr, changedFiles: options.changedFiles, prAuthor: options.prAuthor ?? null },
     { ...deps, config, repoRoot },
   );
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  return 0;
+  return emitResult(result, { jq: options.jq, silent: options.silent });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/github/resolve-tracker-local-spec.mjs

@@ -3,6 +3,7 @@ import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const ISSUE_JSON_FIELDS = "number,title,body,url,state";
 const USAGE = `Usage: resolve-tracker-local-spec.mjs (--repo <owner/name> --issue <number> | --issue-url <github-issue-url>)
 Resolve the canonical tracker-backed local spec bundle from one GitHub issue reference.
@@ -30,7 +31,8 @@ Error output (stderr, JSON):
   Argument/usage errors:
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
-    { "ok": false, "error": "..." }`.trim();
+    { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
 const parseError = buildParseError(USAGE);
 export function parseGitHubIssueUrl(value) {
   let parsedUrl;
@@ -68,6 +70,7 @@ export function parseResolveTrackerLocalSpecCliArgs(argv) {
       repo: { type: "string" },
       issue: { type: "string" },
       "issue-url": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -102,6 +105,7 @@ export function parseResolveTrackerLocalSpecCliArgs(argv) {
       options.issueUrl = requireTokenValue(token, parseError).trim();
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const usingIssueUrl = typeof options.issueUrl === "string";
@@ -119,6 +123,8 @@ export function parseResolveTrackerLocalSpecCliArgs(argv) {
       repo,
       issue,
       issueUrl: options.issueUrl,
+      ...(options.jq !== undefined ? { jq: options.jq } : {}),
+      ...(options.silent !== undefined ? { silent: options.silent } : {}),
     };
   }
   try {
@@ -201,7 +207,7 @@ export async function resolveTrackerLocalSpec(
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseResolveTrackerLocalSpecCliArgs(argv);
   if (options.help) {
@@ -212,7 +218,7 @@ export async function runCli(
     { repo: options.repo, issue: options.issue },
     { env, ghCommand },
   );
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/github/stage-reviewer-draft.mjs

@@ -7,6 +7,7 @@ import { parseArgs } from "node:util";
 import { parsePositiveInteger, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildDraftReviewPayload } from "@dev-loops/core/loop/reviewer-loop-state";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const HELP = `Usage: stage-reviewer-draft.mjs --repo <owner/name> --pr <number> --review-file <path> [--local-state-output <path>]
 Stage a pending draft review on a GitHub pull request.
 Options:
@@ -15,9 +16,13 @@ Options:
   --review-file <path>      Path to JSON file containing review payload (required)
   --local-state-output <path>  Path to write local state snapshot (optional)
   --help, -h                Show this help
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 export function parseStageDraftCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -28,6 +33,7 @@ export function parseStageDraftCliArgs(argv) {
       pr: { type: "string" },
       "review-file": { type: "string" },
       "local-state-output": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -67,6 +73,7 @@ export function parseStageDraftCliArgs(argv) {
       options.localStateOutput = requireTokenValue(token);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
     throw new Error(`Unknown argument: ${token.rawName}`);
   }
   if (!options.repo || !options.pr || !options.reviewFile) {
@@ -169,6 +176,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -190,7 +198,7 @@ export async function runCli(
     await postDraftReview({ repo: options.repo, pr: options.pr, reviewPayload }, { env, ghCommand }),
   );
   const localStatePath = await writeLocalState(options.localStateOutput, draftReview);
-  stdout.write(`${JSON.stringify({
+  process.exitCode = emitResult({
     ok: true,
     repo: options.repo,
     pr: options.pr,
@@ -199,7 +207,7 @@ export async function runCli(
     reviewState: draftReview.state,
     commitSha: draftReview.commitSha,
     localStatePath,
-  })}\n`);
+  }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {