dev-loops 0.4.0 → 0.5.0

package/scripts/loop/check-retro-tooling.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * check-retro-tooling
+ *
+ * Deterministic, dependency-free verifier for the internal-tooling-only rule
+ * (issue #982). Given a transcript of the shell commands the agent ran during a
+ * dev-loop run, it detects AGENT-LEVEL raw escape-hatch calls that should have
+ * gone through internal dev-loops tooling:
+ *   - `gh ...` (incl. `gh api`, `gh ... --jq`)
+ *   - `python` / `python3`
+ *   - `node -e` / `node --eval`
+ *
+ * These three are the same breach: reaching past the dev-loops tooling to read
+ * or parse tool output with a raw call. The verifier returns the list of
+ * violations so the retrospective author can record them in
+ * `behavioralReview.rawCallViolations` and set `behavioralReview.internalToolingOnly`.
+ *
+ * Input source (how the harness feeds it):
+ *   Newline-delimited shell commands — one top-level command per line — as the
+ *   agent actually invoked them. Pass via a file (`--transcript <path>`) or pipe
+ *   on stdin. Each line is one Bash-tool invocation's command string.
+ *
+ * ALLOWED (NOT a violation):
+ *   - dev-loops subcommands and `node scripts/....mjs` invocations. Those scripts
+ *     legitimately call gh/GraphQL/etc. internally — that IS the tooling.
+ *   - A small explicit allowlist of write-ops that have no internal wrapper today:
+ *     `gh pr merge`, `gh pr ready`, `gh issue create`, `gh issue edit`. These are
+ *     recorded as `allowedWriteOps` rather than violations so the gate is not
+ *     blocked forever on an unavoidable gap. Document/close the gap with a wrapper
+ *     to remove them from the allowlist.
+ *
+ * VIOLATION (agent-level raw call):
+ *   - `gh ...` at the start of a command segment (start of line, or after
+ *     `&&`, `||`, `|`, `;`) that is not in the write-op allowlist.
+ *   - `python` / `python3` at the start of a command segment.
+ *   - `node -e` / `node --eval` (inline eval) at the start of a command segment.
+ *
+ * Head normalization (before classifying a segment, fail-closed):
+ *   - strips leading `NAME=value ` env-assignment prefixes (`GH_TOKEN=x gh api`)
+ *   - strips a leading wrapper binary from {sudo, env, xargs, time, nice, command}
+ *     and re-classifies the remainder (`sudo gh api`, `xargs gh api`, `env gh api`)
+ *   - reduces a path-prefixed binary to its basename (`./node_modules/.bin/gh`,
+ *     `/usr/bin/python3`) so the real tool is matched.
+ *
+ * Known limitations (honest):
+ *   - Segment splitting is a simple top-level split on `&&`, `||`, `|`, `;` and
+ *     does NOT fully parse shell quoting/substitution. A `;`/`|` inside a quoted
+ *     argument can over-report (flags a harmless inner token). It catches the
+ *     common raw-call forms (incl. the env/wrapper/path-prefixed ones above), but
+ *     deeply obfuscated calls — command substitution `$(...)`, aliases, `eval` —
+ *     may evade it. Prefer single-line, single-purpose commands in transcripts.
+ */
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+
+const USAGE = `Usage: node scripts/loop/check-retro-tooling.mjs [--transcript <path>] [--json]
+
+Reads a newline-delimited transcript of agent shell commands (from --transcript
+or stdin) and reports agent-level raw gh/python/node -e calls (internal-tooling-only
+rule, issue #982).
+
+Options:
+  --transcript <path>   File of newline-delimited commands (default: read stdin)
+  --json                Emit machine-readable JSON (default: human summary)
+
+Exit codes:
+  0  No violations
+  1  One or more violations found
+  2  Argument/runtime error`;
+
+/**
+ * Write-ops that currently have no internal dev-loops wrapper. Recorded
+ * distinctly so the gate is not blocked forever on an unavoidable gap.
+ * Keep this set SMALL and explicit; remove an entry once a wrapper exists.
+ * @type {ReadonlyArray<RegExp>}
+ */
+const ALLOWED_WRITE_OPS = Object.freeze([
+  /^gh\s+pr\s+merge\b/,
+  /^gh\s+pr\s+ready\b/,
+  /^gh\s+issue\s+create\b/,
+  /^gh\s+issue\s+edit\b/,
+]);
+
+/** Split a command line into top-level segments on &&, ||, |, ;. */
+function splitSegments(line) {
+  return line
+    .split(/&&|\|\||\||;/g)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** Wrapper binaries whose first argument is the real command to classify. */
+const WRAPPER_BINARIES = new Set(["sudo", "env", "xargs", "time", "nice", "command"]);
+
+/**
+ * Strip prefixes that hide the real command head, fail-closed (over-report is
+ * fine, under-report is the bug):
+ *   - leading `NAME=value ` env-assignment tokens (any number)
+ *   - leading wrapper binaries (`sudo`, `env`, `xargs`, ...) — recurse on the rest
+ *   - a path-prefixed binary (`./x/gh`, `/usr/bin/python3`) → reduce head to its basename
+ * Returns the segment with a bare, classifiable command head.
+ */
+function normalizeSegmentHead(segment) {
+  let s = segment.trim();
+  // (a) strip leading env-assignment tokens: NAME=value. The value may be
+  //   unquoted (`X=1`) or a single/double-quoted string that itself contains
+  //   spaces (`X="a b"`); match the quoted form first so the space inside the
+  //   quotes is not mistaken for the token separator (would under-report).
+  const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+(?=\S)/;
+  while (ENV_ASSIGN.test(s)) {
+    s = s.replace(ENV_ASSIGN, "");
+  }
+  // (c) reduce a path-prefixed head to its basename so `.../gh` → `gh`
+  s = s.replace(/^(\S*\/)([^/\s]+)/, "$2");
+  // (b) strip a leading wrapper binary, then re-normalize the remainder
+  const head = s.split(/\s+/, 1)[0];
+  if (WRAPPER_BINARIES.has(head)) {
+    const rest = s.slice(head.length).trim();
+    if (rest.length > 0) return normalizeSegmentHead(rest);
+  }
+  return s;
+}
+
+/**
+ * Classify a single command segment.
+ * @returns {{ kind: "violation"|"allowedWriteOp"|"clean", tool?: string }}
+ */
+function classifySegment(rawSegment) {
+  const segment = normalizeSegmentHead(rawSegment);
+  // `node scripts/....mjs` (or any script path) is allowed tooling; only inline
+  // eval forms are violations. Check node first so script invocations pass.
+  if (/^node\b/.test(segment)) {
+    // Inline eval (`-e`/`--eval`) is a violation only before the script path:
+    // once a non-flag token (the script) appears, a later `--eval` is just a
+    // script argument, not Node's inline-eval mode (avoids false positives).
+    const tokens = segment.split(/\s+/).slice(1);
+    for (const tok of tokens) {
+      if (tok === "-e" || tok === "--eval" || /^--eval=/.test(tok)) {
+        return { kind: "violation", tool: "node -e" };
+      }
+      if (!tok.startsWith("-")) break; // script path reached
+    }
+    return { kind: "clean" };
+  }
+  if (/^gh\b/.test(segment)) {
+    if (ALLOWED_WRITE_OPS.some((re) => re.test(segment))) {
+      return { kind: "allowedWriteOp", tool: "gh" };
+    }
+    return { kind: "violation", tool: "gh" };
+  }
+  if (/^python3?\b/.test(segment)) {
+    return { kind: "violation", tool: /^python3\b/.test(segment) ? "python3" : "python" };
+  }
+  return { kind: "clean" };
+}
+
+/**
+ * Analyze a transcript of newline-delimited shell commands.
+ *
+ * @param {string} transcript
+ * @returns {{ violations: string[], allowedWriteOps: string[], internalToolingOnly: boolean }}
+ */
+export function analyzeTranscript(transcript) {
+  const violations = [];
+  const allowedWriteOps = [];
+  const lines = String(transcript ?? "").split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    for (const segment of splitSegments(line)) {
+      const result = classifySegment(segment);
+      if (result.kind === "violation") {
+        violations.push(`${result.tool}: ${segment}`);
+      } else if (result.kind === "allowedWriteOp") {
+        allowedWriteOps.push(segment);
+      }
+    }
+  }
+  return { violations, allowedWriteOps, internalToolingOnly: violations.length === 0 };
+}
+
+function parseCliArgs(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        transcript: { type: "string" },
+        json: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    throw Object.assign(new Error(err instanceof Error ? err.message : String(err)), { usage: USAGE });
+  }
+  return values;
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+async function run(argv, { stdout, stderr }) {
+  const values = parseCliArgs(argv);
+  if (values.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const transcript = values.transcript
+    ? readFileSync(values.transcript, "utf8")
+    : readStdin();
+
+  const { violations, allowedWriteOps, internalToolingOnly } = analyzeTranscript(transcript);
+
+  if (values.json) {
+    stdout.write(`${JSON.stringify({ ok: internalToolingOnly, internalToolingOnly, rawCallViolations: violations, allowedWriteOps })}\n`);
+  } else if (internalToolingOnly) {
+    stdout.write(`internalToolingOnly: true — no agent-level raw gh/python/node -e calls found.\n`);
+    if (allowedWriteOps.length > 0) {
+      stdout.write(`Allowed write-ops (no wrapper yet): ${allowedWriteOps.length}\n`);
+    }
+  } else {
+    stderr.write(`internalToolingOnly: false — ${violations.length} raw-call violation(s):\n`);
+    for (const v of violations) stderr.write(`  - ${v}\n`);
+  }
+  return internalToolingOnly ? 0 : 1;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr }).then(
+    (code) => { process.exitCode = typeof code === "number" ? code : 0; },
+    (error) => {
+      const usage = error instanceof Error && typeof error.usage === "string" ? `\n${error.usage}` : "";
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}${usage}\n`);
+      process.exitCode = 2;
+    },
+  );
+}

package/scripts/loop/copilot-pr-handoff.mjs

@@ -17,6 +17,7 @@ import {
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import {
   DEFAULT_POLL_INTERVAL_MS,
   COPILOT_REVIEW_WAIT_TIMEOUT_MS,
@@ -69,9 +70,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const WATCH_STATES = new Set([
   STATE.WAITING_FOR_COPILOT_REVIEW,
 ]);
@@ -134,6 +137,8 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
     repo: undefined,
     pr: undefined,
     watchStatus: undefined,
+    jq: undefined,
+    silent: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -142,6 +147,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       repo: { type: "string" },
       pr: { type: "string" },
       "watch-status": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -177,6 +183,14 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       options.watchStatus = watchStatus;
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.pr === undefined) {
@@ -519,10 +533,14 @@ export async function runCli(
     return;
   }
   const result = await runHandoff(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -163,7 +163,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
 async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
   const result = await runChild(
     ghCommand,
-    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
+    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
     env,
   );
   if (result.code !== 0) {
@@ -172,6 +172,32 @@ async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh"
   }
   return parseJsonText(result.stdout, { label: "gh pr view" });
 }
+
+// GitHub computes `mergeable` asynchronously, so a freshly-pushed head briefly
+// reads `UNKNOWN`. After the initial fetch, re-poll up to `maxPolls` more times
+// while the value stays UNKNOWN (so at most 1 + maxPolls total fetches) before
+// deciding; never treat a transient UNKNOWN as a pass — the caller fails closed
+// to recheck if it never settles. (issue #980)
+export async function fetchPrFactsWithSettledMergeable(
+  options,
+  {
+    env = process.env,
+    ghCommand = "gh",
+    maxPolls = 3,
+    pollDelayMs = 1500,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    fetch = fetchPrFacts,
+  } = {},
+) {
+  let prData = await fetch(options, { env, ghCommand });
+  let polls = 0;
+  while (String(prData?.mergeable || "").toUpperCase() === "UNKNOWN" && polls < maxPolls) {
+    polls += 1;
+    await sleep(pollDelayMs);
+    prData = await fetch(options, { env, ghCommand });
+  }
+  return prData;
+}
 export function resolveLinkedIssueFromPr(prData) {
   if (!prData || typeof prData !== "object") return null;
   const closing = Array.isArray(prData.closingIssuesReferences) ? prData.closingIssuesReferences : [];
@@ -290,7 +316,7 @@ async function loadRetrospectiveCheckpoint(repoRoot) {
   }
 }
 export async function loadPrGateCoordinationContext(options, runtime = {}) {
-  const prData = await fetchPrFacts(options, runtime);
+  const prData = await fetchPrFactsWithSettledMergeable(options, runtime);
   const currentHeadSha = typeof prData?.headRefOid === "string" && prData.headRefOid.trim().length > 0
     ? prData.headRefOid.trim()
     : null;
@@ -349,6 +375,9 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
     ? prData.mergeStateStatus.trim().toUpperCase()
     : null;
+  const mergeable = typeof prData?.mergeable === "string" && prData.mergeable.trim().length > 0
+    ? prData.mergeable.trim().toUpperCase()
+    : null;
   const isDraft = Boolean(prData?.isDraft);
   const isClosed = String(prData?.state || "").toUpperCase() === "CLOSED";
   const isMerged = String(prData?.state || "").toUpperCase() === "MERGED";
@@ -361,6 +390,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
     pr: options.pr,
     currentHeadSha,
     mergeStateStatus,
+    mergeable,
     conflictFiles,
     prData,
     snapshot,
@@ -396,6 +426,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
   const draftGateConfig = resolveGateConfig(config, "draft");
   const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
   const requireRetrospectiveGate = resolveWorkflowConfig(config, "requireRetrospectiveGate");
+  const requireRetrospectiveInternalTooling = resolveWorkflowConfig(config, "requireRetrospectiveInternalTooling");
   const retrospectiveCheckpoint = await loadRetrospectiveCheckpoint(repoRoot);
   const result = evaluatePrGateCoordination({
     repo: context.repo,
@@ -406,6 +437,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     prMerged: String(context.prData?.state || "").toUpperCase() === "MERGED",
     prTitle: context.prData?.title,
     mergeStateStatus: context.mergeStateStatus,
+    mergeable: context.mergeable,
     conflictFiles: context.conflictFiles,
     lifecycleState: context.interpretation.state,
     loopDisposition: context.disposition.loopDisposition,
@@ -415,6 +447,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     sameHeadCleanConverged: context.interpretation.sameHeadCleanConverged,
     draftGateRequireCi: draftGateConfig.requireCi,
     requireRetrospectiveGate,
+    requireRetrospectiveInternalTooling,
     retrospectiveCheckpoint,
     draftGate: context.gateEvidence.draftGate,
     draftGateMarker: context.gateEvidence.draftGateMarker,

package/scripts/loop/docs-grill-contract.mjs

@@ -0,0 +1,70 @@
+// Bounded docs-grill disposition classifier behind `dev-loop`. Sibling of
+// scripts/loop/slides-story-review-contract.mjs: this one codifies the keep/fix
+// rule for the autonomous docs-grill step (claims vs the actual contracts,
+// code-vs-doc drift, stale references, contract-surface accuracy). Pure module,
+// no I/O. See docs/docs-grill-step.md.
+
+// What each finding asserts is wrong. `drift` covers any divergence between a
+// claim/reference and the contract surface it points at; `stale_reference`
+// covers a link/path/command that no longer resolves; `cosmetic` covers
+// wording-only nits with no behavioral or reference impact.
+export const DOCS_GRILL_FINDING_KINDS = Object.freeze([
+  'drift',
+  'stale_reference',
+  'cosmetic',
+]);
+
+// The bounded disposition the step assigns to each finding.
+export const DOCS_GRILL_DISPOSITIONS = Object.freeze([
+  'record_finding', // real drift between code/behavior and a contract claim — record it
+  'fix_in_place', // doc-only drift the loop can correct on this branch
+  'route_followup', // doc-only drift too large for this branch — route a follow-up
+  'ignore_cosmetic', // wording nit that does not justify a block or a fix here
+]);
+
+/**
+ * Classify one docs-grill finding into its keep/fix disposition.
+ *
+ * The keep/fix rule (docs/docs-grill-step.md):
+ *   - real drift between code/behavior and a contract claim   -> record_finding
+ *   - doc-only drift the loop can correct here                -> fix_in_place
+ *   - doc-only drift too large for this branch                -> route_followup
+ *   - cosmetic wording nit                                    -> ignore_cosmetic
+ *
+ * A coerced/invalid finding returns a structured invalid result rather than
+ * throwing (the module's contract is a structured result, never an exception).
+ *
+ * @param {object} finding
+ * @param {string} finding.kind - one of DOCS_GRILL_FINDING_KINDS
+ * @param {boolean} [finding.docOnly] - true when only docs (no code/behavior) diverge
+ * @param {boolean} [finding.fixableHere] - true when a doc-only fix is small enough for this branch
+ * @returns {{ ok: boolean, disposition?: string, status: string, reason: string, invalid?: string[] }}
+ */
+export function classifyDocsGrillFinding(finding = {}) {
+  if (!finding || typeof finding !== 'object') finding = {};
+  if (!DOCS_GRILL_FINDING_KINDS.includes(finding.kind)) {
+    return {
+      ok: false,
+      status: 'invalid_finding',
+      reason: 'unknown_finding_kind',
+      invalid: ['kind'],
+    };
+  }
+
+  if (finding.kind === 'cosmetic') {
+    return { ok: true, disposition: 'ignore_cosmetic', status: 'classified', reason: 'cosmetic_nit' };
+  }
+
+  // drift | stale_reference against live code/behavior is always recorded; the
+  // reason reflects the kind so downstream filtering stays accurate.
+  if (finding.docOnly !== true) {
+    const reason = finding.kind === 'stale_reference' ? 'stale_reference' : 'real_drift';
+    return { ok: true, disposition: 'record_finding', status: 'classified', reason };
+  }
+
+  // Doc-only drift: fix it here when small, otherwise route a follow-up.
+  if (finding.fixableHere === true) {
+    return { ok: true, disposition: 'fix_in_place', status: 'classified', reason: 'doc_only_fixable_here' };
+  }
+  return { ok: true, disposition: 'route_followup', status: 'classified', reason: 'doc_only_too_large' };
+}

package/scripts/loop/info.mjs

@@ -100,13 +100,32 @@ function formatCiDisplay(ciStatus, ciConclusion) {
   return `CI ${ciStatus}`;
 }
 
+function formatMergeableDisplay(mergeable, mergeStateStatus) {
+  const m = typeof mergeable === "string" ? mergeable.toUpperCase() : null;
+  const s = typeof mergeStateStatus === "string" ? mergeStateStatus.toUpperCase() : null;
+  if (m === "CONFLICTING" || s === "DIRTY" || s === "CONFLICTING") {
+    return `❌ CONFLICTING${s ? ` (${s})` : ""} — resolve before any gate`;
+  }
+  if (s === "BEHIND") {
+    return "⚠️ BEHIND — update branch from base before any gate";
+  }
+  if (m === "UNKNOWN") {
+    return "⏳ UNKNOWN — GitHub still computing; recheck before proceeding";
+  }
+  if (m === "MERGEABLE") {
+    return `✅ MERGEABLE${s ? ` (${s})` : ""}`;
+  }
+  return s || m || "unknown";
+}
+
 function formatPrSummary(prData, handoffResult) {
   const lines = [];
   lines.push(`PR #${prData.number}: ${prData.title}`);
   lines.push(`  Branch: ${formatBranchDisplay(prData.headRefName, prData.baseRefName)}`);
   lines.push(`  State: ${prData.state}${prData.isDraft ? " (draft)" : ""}`);
   lines.push(`  Author: ${prData.author?.login || "unknown"}`);
-  
+  lines.push(`  Mergeable: ${formatMergeableDisplay(prData.mergeable, prData.mergeStateStatus)}`);
+
   if (handoffResult?.snapshot) {
     const s = handoffResult.snapshot;
     if (s.ciStatus !== undefined) {
@@ -189,7 +208,7 @@ function formatIssueSummary(issueData, startupBundle, linkedPrData) {
 }
 
 function buildPrInfo(prNumber, repo, cwd) {
-  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,url,reviewRequests"], cwd);
+  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,mergeable,mergeStateStatus,url,reviewRequests"], cwd);
   
   let handoffResult = null;
   try {

package/scripts/loop/pr-runner-coordination.mjs

@@ -5,6 +5,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import {
   assertRunnerOwnership,
   claimRunnerOwnership,
@@ -23,6 +24,7 @@ If --run-id is omitted for claim/assert/release/takeover, DEVLOOPS_RUN_ID is use
 Output:
   stdout: { "ok": true, ... }
   stderr: { "ok": false, "error": "...", ... }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success / clean stop-compatible result
   1  Argument error or coordination conflict`.trim();
@@ -36,6 +38,8 @@ function parseCliArgs(argv) {
     pr: undefined,
     runId: undefined,
     requireExisting: false,
+    jq: undefined,
+    silent: false,
   };
   const command = args.shift();
   if (command === undefined || command === "--help" || command === "-h") {
@@ -51,6 +55,7 @@ function parseCliArgs(argv) {
       pr: { type: "string" },
       "run-id": { type: "string" },
       "require-existing": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +88,14 @@ function parseCliArgs(argv) {
       options.requireExisting = true;
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const validCommands = new Set(["status", "claim", "takeover", "assert", "release"]);
@@ -146,11 +159,14 @@ async function main() {
     }
     const result = await runPrRunnerCoordination(options, { env: process.env });
     if (!result.ok) {
-      console.error(JSON.stringify(result));
-      process.exitCode = 1;
-      return;
+      // Preserve the established stderr-on-failure contract when not filtering.
+      if (options.jq === undefined && !options.silent) {
+        console.error(JSON.stringify(result));
+        process.exitCode = 1;
+        return;
+      }
     }
-    console.log(JSON.stringify(result));
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     const payload = formatCliError(error, { usage: USAGE });
     console.error(JSON.stringify(payload));