dev-loops 0.5.0 → 0.7.1

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

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, normalizeTimestamp } from "../_core-helpers.mjs";
+import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, normalizeTimestamp, parseJsonText } from "../_core-helpers.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { detectPostConvergenceSignificantChange } from "./_post-convergence-change.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId } from "@dev-loops/core/loop/run-context";
-import path from "node:path";
 import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
 import { autoDetectSnapshot } from "./detect-copilot-loop-state.mjs";
 import { performCopilotReviewRequest } from "../github/request-copilot-review.mjs";
 import { detectInternalOnly as detectPrInternalOnly } from "./detect-internal-only-pr.mjs";
 import { applyConfirmedReviewRequest, interpretLoopState, NEXT_ACTIONS, STATE, summarizeLoopInterpretation, TRANSITIONS } from "@dev-loops/core/loop/copilot-loop-state";
-import { ensureAsyncRunnerOwnership } from "./_pr-runner-coordination.mjs";
+import { ensureAsyncRunnerOwnership, releaseAsyncRunnerOwnership } from "./_pr-runner-coordination.mjs";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
 
 
 import {
@@ -17,7 +18,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 { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import {
   DEFAULT_POLL_INTERVAL_MS,
   COPILOT_REVIEW_WAIT_TIMEOUT_MS,
@@ -183,14 +184,7 @@ 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;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.pr === undefined) {
@@ -300,12 +294,32 @@ export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env
   }
 }
 
+// Facts needed by the round-cap escape-hatch significant-change detector
+// (#1103, #1126): the current head, the Copilot reviews (to find the last
+// reviewed head), and the PR's changed files. Fetched only when the interpreter
+// already resolved ROUND_CAP_CLEAN_FALLBACK, so this extra call is off the hot path.
+async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+  const result = await runChild(
+    ghCommand,
+    ["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,reviews,files"],
+    env,
+  );
+  if (result.code !== 0) {
+    return null;
+  }
+  try {
+    return parseJsonText(result.stdout, { label: "gh pr view reopen-cycle facts" });
+  } catch {
+    return null;
+  }
+}
+
 export async function runHandoff(options, { env = process.env, ghCommand = "gh" } = {}) {
   const runnerOwnership = await ensureAsyncRunnerOwnership({
     repo: options.repo,
     pr: options.pr,
     env,
-    cwd: path.resolve(process.cwd()),
+    cwd: resolveRepoRoot(process.cwd()),
     claimIfMissing: true,
   });
   if (!runnerOwnership.ok) {
@@ -337,7 +351,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
     { repo: options.repo, pr: options.pr },
     { env, ghCommand },
   );
-  const config = await loadDevLoopConfig({ repoRoot: path.resolve(process.cwd()) });
+  const config = await loadDevLoopConfig({ repoRoot: resolveRepoRoot(process.cwd()) });
   if (config.errors?.length > 0) {
     console.error("[copilot-pr-handoff] config warnings:", JSON.stringify(config.errors));
   }
@@ -358,6 +372,12 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   const TERMINAL_STATES = new Set([STATE.NO_PR, STATE.DONE, STATE.BLOCKED_NEEDS_USER_DECISION]);
   const humanCommentUnavailable = humanCommentCheck.error && !humanCommentCheck.paused;
   if ((humanCommentCheck.paused || humanCommentUnavailable) && !TERMINAL_STATES.has(interpretation.state)) {
+    const runnerRelease = await releaseAsyncRunnerOwnership({
+      repo: options.repo,
+      pr: options.pr,
+      env,
+      cwd: resolveRepoRoot(process.cwd()),
+    });
     return {
       ok: true,
       action: "stop",
@@ -373,6 +393,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       terminal: true,
       snapshot,
       runnerOwnership,
+      ...(runnerRelease.status !== "skipped_no_async_run_id" ? { runnerRelease } : {}),
       humanCommentPause: {
         reason: humanCommentCheck.paused ? "human_comment_detected" : "human_comment_check_unavailable",
         error: humanCommentCheck.error || undefined,
@@ -438,6 +459,76 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
     }
   }
 
+  // In-flight-rerequest race (#1165): the interpreter routes to
+  // ROUND_CAP_CLEAN_FALLBACK even when a Copilot review is REQUESTED and pending
+  // on the current head, because at the cap it treats any assignment as a stale
+  // leftover (copilot-loop-state.mjs). An in-flight request is usually a fresh
+  // review genuinely coming (e.g. a force-rerequest for a significant
+  // post-convergence change) — but it can also be a stale at-cap assignment
+  // mislabeled as requested, as detect-copilot-loop-state.mjs's own fallback
+  // notes. Proceeding to pre_approval_gate on a real in-flight review would skip
+  // it — the exact gate-integrity gap #1126 closes — and
+  // detect-pr-gate-coordination-state gates pre-approval here. The reopen escape
+  // hatch below can only recover the wait verdict via a SECOND, fail-silent gh
+  // fetch (fetchReopenCycleFacts) whose failure/compare-miss silently drops back
+  // to "proceed", diverging from detect (which reused already-validated facts).
+  // Fail closed instead: while the in-flight evidence stands, wait for it to
+  // resolve rather than stop. If it never lands, a --watch-status refresh
+  // (which skips this branch) re-resolves to the clean fallback, so this never
+  // dead-ends the loop.
+  const reviewRequestInFlight = snapshot.copilotReviewRequestStatus === "requested"
+    || snapshot.copilotReviewRequestStatus === "already-requested";
+  if (!internalOnlySkipCopilot
+      && options.watchStatus === undefined
+      && interpretation.state === STATE.ROUND_CAP_CLEAN_FALLBACK
+      && reviewRequestInFlight) {
+    interpretation = {
+      ...interpretation,
+      state: STATE.WAITING_FOR_COPILOT_REVIEW,
+      nextAction: NEXT_ACTIONS[STATE.WAITING_FOR_COPILOT_REVIEW],
+      allowedTransitions: [...(TRANSITIONS[STATE.WAITING_FOR_COPILOT_REVIEW] || [])],
+      roundCapCleanEligible: false,
+    };
+  }
+
+  // Round-cap escape hatch (#1103, #1126): the interpreter resolves
+  // ROUND_CAP_CLEAN_FALLBACK (stop, no re-request) at the cap. But when a
+  // SIGNIFICANT post-convergence change (new product/test-logic since the last
+  // Copilot review — not doc/comment-only) has landed, a new Copilot cycle is
+  // owed. Reopen it here via the SAME shared detector detect-pr-gate-coordination-state
+  // uses, so the two agree: both offer a re-request iff (cap reached AND
+  // significant post-convergence change). A doc-only change stays at the clean
+  // fallback (stop), unchanged.
+  let reopenedCapCycle = false;
+  if (!internalOnlySkipCopilot
+      && options.watchStatus === undefined
+      && interpretation.state === STATE.ROUND_CAP_CLEAN_FALLBACK) {
+    const reopenFacts = await fetchReopenCycleFacts(options, { env, ghCommand });
+    const significant = await detectPostConvergenceSignificantChange(
+      {
+        repo: options.repo,
+        pr: options.pr,
+        currentHeadSha: typeof reopenFacts?.headRefOid === "string" ? reopenFacts.headRefOid.trim() : null,
+        reviews: reopenFacts?.reviews,
+        changedFiles: reopenFacts?.files,
+        roundCapReached: true,
+        regularCopilotRounds: (snapshot.copilotReviewRoundCount ?? 0) > 0,
+      },
+      { env, ghCommand },
+    );
+    if (significant) {
+      reopenedCapCycle = true;
+      interpretation = {
+        ...interpretation,
+        state: STATE.READY_TO_REREQUEST_REVIEW,
+        nextAction: NEXT_ACTIONS[STATE.READY_TO_REREQUEST_REVIEW],
+        allowedTransitions: [...(TRANSITIONS[STATE.READY_TO_REREQUEST_REVIEW] || [])],
+        autoRerequestEligible: true,
+        roundCapCleanEligible: false,
+      };
+    }
+  }
+
   let reviewRequestStatus;
   const shouldRequestReview = !internalOnlySkipCopilot && options.watchStatus === undefined
     && (interpretation.state === STATE.PR_READY_NO_FEEDBACK
@@ -449,12 +540,31 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
         repo: options.repo,
         pr: options.pr,
         sameHeadCleanConverged: interpretation.sameHeadCleanConverged,
+        // A reopened cap cycle was decided via the shared significant-change
+        // detector; tell the requester to honor it. performCopilotReviewRequest
+        // still refuses unless the head actually advanced past the last review
+        // (its hasNewCommits guard), so this cannot force an over-cap same-head request.
+        forceRerequestReview: reopenedCapCycle,
       },
       { env, ghCommand },
     );
     reviewRequestStatus = requestResult.status;
     snapshot = applyConfirmedReviewRequest(snapshot, reviewRequestStatus);
     interpretation = interpretLoopState(snapshot, refinementConfig);
+    // The re-interpretation re-hits the round cap (rounds still >= max) and would
+    // flip a reopened cycle back to ROUND_CAP_CLEAN_FALLBACK. A confirmed request
+    // for a significant new change is a genuine new wait cycle, so map it to the
+    // honest WAITING_FOR_COPILOT_REVIEW state (what a below-cap re-request yields).
+    if (reopenedCapCycle
+        && (reviewRequestStatus === "requested" || reviewRequestStatus === "already-requested")) {
+      interpretation = {
+        ...interpretation,
+        state: STATE.WAITING_FOR_COPILOT_REVIEW,
+        nextAction: NEXT_ACTIONS[STATE.WAITING_FOR_COPILOT_REVIEW],
+        allowedTransitions: [...(TRANSITIONS[STATE.WAITING_FOR_COPILOT_REVIEW] || [])],
+        roundCapCleanEligible: false,
+      };
+    }
   }
   const interpretationSummary = summarizeLoopInterpretation(interpretation, refinementConfig);
   const effectiveReviewRequestStatus = reviewRequestStatus
@@ -517,6 +627,17 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
     requestStatus: normalizedRequestStatus,
     watchArgs: result.watchArgs,
   });
+  if (result.terminal === true) {
+    const runnerRelease = await releaseAsyncRunnerOwnership({
+      repo: options.repo,
+      pr: options.pr,
+      env,
+      cwd: resolveRepoRoot(process.cwd()),
+    });
+    if (runnerRelease.status !== "skipped_no_async_run_id") {
+      result.runnerRelease = runnerRelease;
+    }
+  }
   return result;
 }
 export async function runCli(

package/scripts/loop/debt-remediate.mjs

@@ -24,6 +24,7 @@ import { DebtSignalSchema } from "@dev-loops/core/debt/signal";
 import { clusterSignalsEnriched } from "@dev-loops/core/debt/cluster";
 import { shapeFindings } from "@dev-loops/core/debt/shape";
 import { createRemediationIssue } from "@dev-loops/core/debt/remediation-to-issue";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
 
@@ -45,9 +46,12 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "signals": N, "findings": N, "remediationItems": N, "issues": [...], "summary": "..." }
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0  Success (all remediation issue creations succeeded)
-  1  Argument error, input validation failure, or issue creation failure`.trim();
+  1  Argument error, input validation failure, or issue creation failure
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -160,6 +164,7 @@ export async function runCli(argv) {
       input: { type: "string" },
       repo: { type: "string" },
       "dry-run": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -188,6 +193,7 @@ export async function runCli(argv) {
       options.dryRun = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown flag: ${token.rawName}`);
   }
 
@@ -196,6 +202,14 @@ export async function runCli(argv) {
     return { exitCode: 0 };
   }
 
+  // Every early-exit failure below reports via the shared jq/silent contract on
+  // stderr (this script's existing error-output convention); `ok:false` maps to
+  // the existing exit 1 by default, and an invalid --jq filter still fails
+  // closed with exit 2 instead of being swallowed by this fixed exit code.
+  const failEarly = (payload) => ({
+    exitCode: emitResult(payload, { jq: options.jq, silent: options.silent, stdout: process.stderr, stderr: process.stderr }),
+  });
+
   if (!options.input) {
     throw parseError("Missing required flag: --input <path>");
   }
@@ -208,20 +222,20 @@ export async function runCli(argv) {
   try {
     rawInput = await readFile(inputPath, "utf-8");
   } catch (err) {
-    return { exitCode: 1, output: { ok: false, error: `Cannot read input file: ${inputPath}`, detail: err.message } };
+    return failEarly({ ok: false, error: `Cannot read input file: ${inputPath}`, detail: err.message });
   }
 
   let signals;
   try {
     signals = JSON.parse(rawInput);
   } catch (err) {
-    return { exitCode: 1, output: { ok: false, error: "Input file is not valid JSON", detail: err.message } };
+    return failEarly({ ok: false, error: "Input file is not valid JSON", detail: err.message });
   }
 
   // Validate signals
   const validation = validateSignals(signals);
   if (!validation.ok) {
-    return { exitCode: 1, output: validation };
+    return failEarly(validation);
   }
 
   // Resolve repo
@@ -230,14 +244,14 @@ export async function runCli(argv) {
     try {
       repo = parseRepoSlug(options.repo);
     } catch {
-      return { exitCode: 1, output: { ok: false, error: `Invalid repo slug: ${options.repo}` } };
+      return failEarly({ ok: false, error: `Invalid repo slug: ${options.repo}` });
     }
   } else {
     repo = detectRepo();
   }
 
   if (!repo) {
-    return { exitCode: 1, output: { ok: false, error: "Cannot detect repository. Pass --repo <owner/name>." } };
+    return failEarly({ ok: false, error: "Cannot detect repository. Pass --repo <owner/name>." });
   }
 
   // Run pipeline: cluster → score → shape
@@ -298,8 +312,9 @@ export async function runCli(argv) {
   report.repo = `${repo.owner}/${repo.name}`;
 
   const outputTarget = report.ok ? process.stdout : process.stderr;
-  outputTarget.write(JSON.stringify(report) + "\n");
-  return { exitCode: anyIssueFailed ? 1 : 0 };
+  return {
+    exitCode: emitResult(report, { jq: options.jq, silent: options.silent, stdout: outputTarget, stderr: process.stderr }),
+  };
 }
 
 // ============================================================================
@@ -307,10 +322,7 @@ export async function runCli(argv) {
 // ============================================================================
 
 if (isDirectCliRun(import.meta.url)) {
-  runCli(process.argv.slice(2)).then(({ exitCode, output }) => {
-    if (output) {
-      process.stderr.write(JSON.stringify(output) + "\n");
-    }
+  runCli(process.argv.slice(2)).then(({ exitCode }) => {
     process.exitCode = exitCode;
   }).catch((err) => {
     process.stderr.write(`${formatCliError(err)}\n`);

package/scripts/loop/detect-change-scope.mjs

@@ -2,6 +2,7 @@
 import { execFileSync } from "node:child_process";
 import process from "node:process";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
 Detect change scope from git diff for light-mode eligibility.
@@ -9,9 +10,13 @@ Options:
   --base <ref>   Override base ref (default: HEAD~1)
   --head <ref>   Override head ref; ignored unless --base is also set
   --help, -h     Show this help
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 
 function parseCliArgs(argv) {
@@ -21,6 +26,7 @@ function parseCliArgs(argv) {
       base: { type: "string" },
       head: { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -43,7 +49,9 @@ function parseCliArgs(argv) {
       }
       if (token.name === "head") {
         opts.head = token.value ?? null;
+        continue;
       }
+      if (matchJqOutputToken(token, opts)) continue;
     }
   }
   return opts;
@@ -88,6 +96,27 @@ function detectScope({ base, head } = {}) {
 function isEligibleForLightMode(scope, threshold) {
   return scope.filesChanged <= threshold.maxFiles && scope.linesChanged <= threshold.maxLines;
 }
+/**
+ * Detect change scope for the merge-base diff between `base` and `head` (the
+ * three-dot `base...head` diff git resolves against merge-base(base, head)).
+ *
+ * Fails CLOSED: a missing base/head, or any git failure, returns `{ ok: false }`
+ * so callers that gate on scope (e.g. the light-mode pre-merge acceptance) reject
+ * rather than silently treating an unmeasurable diff as under threshold. Reuses
+ * the same `parseGitDiffStat` scope resolution as `detectScope`.
+ */
+function detectMergeBaseScope({ base, head, cwd } = {}) {
+  if (!base || !head) {
+    return { ok: false, filesChanged: 0, linesChanged: 0, error: "base and head are required for merge-base scope detection" };
+  }
+  let output;
+  try {
+    output = execFileSync("git", ["diff", "--stat", `${base}...${head}`], { encoding: "utf8", maxBuffer: 1_000_000, cwd: cwd || undefined });
+  } catch (err) {
+    return { ok: false, filesChanged: 0, linesChanged: 0, error: err instanceof Error ? err.message : String(err) };
+  }
+  return { ok: true, ...parseGitDiffStat(output) };
+}
 async function main() {
   const opts = parseCliArgs(process.argv.slice(2));
   const scope = detectScope(opts);
@@ -108,12 +137,12 @@ async function main() {
     }
   } catch {
   }
-  process.stdout.write(
-    JSON.stringify({
-      ...scope,
-      eligibleForLightMode: eligible,
-      threshold,
-    }) + "\n"
+  // This tool always exits 0 on a parsed run (scope.ok:false only reflects a git
+  // diff failure inside the payload, never the process outcome) — force ok:true
+  // as emitResult's default so --jq/--silent compose without changing that.
+  process.exitCode = emitResult(
+    { ...scope, eligibleForLightMode: eligible, threshold },
+    { jq: opts.jq, silent: opts.silent, ok: true },
   );
 }
 const isDirectRun =
@@ -124,4 +153,4 @@ if (isDirectRun) {
     process.exitCode = 1;
   });
 }
-export { detectScope, isEligibleForLightMode };
+export { detectScope, detectMergeBaseScope, isEligibleForLightMode };

package/scripts/loop/detect-copilot-loop-state.mjs

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import {
@@ -28,6 +27,8 @@ import {
   normalizeHeadScopedCommitStatus,
   normalizeHeadScopedCiContract,
 } from "@dev-loops/core/loop/copilot-ci-status";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage:
   detect-copilot-loop-state.mjs --repo <owner/name> --pr <number>
   detect-copilot-loop-state.mjs --input <path>
@@ -53,9 +54,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, gh failure, or indeterminate state`.trim();
+  1  Argument error, gh failure, or indeterminate state
+  2  Invalid --jq filter`.trim();
 const VALID_OVERRIDE_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
 const parseError = buildParseError(USAGE);
 export function parseDetectCliArgs(argv) {
@@ -72,6 +75,7 @@ export function parseDetectCliArgs(argv) {
       input: { type: "string" },
       repo: { type: "string" },
       pr: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -100,6 +104,7 @@ export function parseDetectCliArgs(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.inputPath !== undefined) {
@@ -419,6 +424,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -445,13 +451,13 @@ export async function runCli(
     interpretationInput = snapshot;
   }
   let interpretation;
-  const config = await loadDevLoopConfig({ repoRoot: path.resolve(process.cwd()) });
+  const config = await loadDevLoopConfig({ repoRoot: resolveRepoRoot(process.cwd()) });
   const refinementConfig = config.errors.length > 0
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(config.config);
   interpretation = interpretLoopState(interpretationInput, refinementConfig);
   const interpretationSummary = summarizeLoopInterpretation(interpretation);
-  stdout.write(`${JSON.stringify({
+  process.exitCode = emitResult({
     ok: true,
     snapshot,
     state: interpretation.state,
@@ -461,7 +467,7 @@ export async function runCli(
     sameHeadCleanConverged: interpretation.sameHeadCleanConverged,
     loopDisposition: interpretationSummary.loopDisposition,
     terminal: interpretationSummary.terminal,
-  })}\n`);
+  }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/loop/detect-copilot-session-activity.mjs

@@ -3,6 +3,7 @@ import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "
 import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: detect-copilot-session-activity.mjs --repo <owner/name> --branch <name> [--limit <number>]
 Detect Copilot GitHub Actions session activity on a branch.
 Required:
@@ -32,7 +33,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 DEFAULT_LIMIT = 20;
 const ACTIVE_RUN_STATUSES = new Set(["queued", "in_progress", "pending", "requested", "waiting"]);
 const COPILOT_RUN_NAME_PATTERNS = Object.freeze([
@@ -55,6 +57,7 @@ export function parseDetectCopilotSessionActivityCliArgs(argv) {
       repo: { type: "string" },
       branch: { type: "string" },
       limit: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +86,7 @@ export function parseDetectCopilotSessionActivityCliArgs(argv) {
       options.limit = parsePositiveInteger(requireTokenValue(token, parseError), "--limit", parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.branch === undefined || options.branch.length === 0) {
@@ -185,7 +189,7 @@ export async function detectCopilotSessionActivity({ repo, branch, limit = DEFAU
 }
 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 = parseDetectCopilotSessionActivityCliArgs(argv);
   if (options.help) {
@@ -193,7 +197,7 @@ export async function runCli(
     return;
   }
   const result = await detectCopilotSessionActivity(options, { 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/loop/detect-initial-copilot-pr-state.mjs

@@ -5,6 +5,7 @@ import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectLinkedIssuePr } from "../github/detect-linked-issue-pr.mjs";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: detect-initial-copilot-pr-state.mjs --repo <owner/name> --issue <number>
 Detect whether an assigned issue is still on the bootstrap-only Copilot draft PR
 or has moved into normal linked-PR follow-up.
@@ -43,7 +44,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();
 export const LINKED_PR_STATE = Object.freeze({
   NO_LINKED_PR: "no_linked_pr",
   PRIOR_LINKED_PR_CLOSED_UNMERGED: "prior_linked_pr_closed_unmerged",
@@ -91,6 +93,7 @@ export function parseDetectInitialCopilotPrStateCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       issue: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -115,6 +118,7 @@ export function parseDetectInitialCopilotPrStateCliArgs(argv) {
       options.issue = parseIssueNumber(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.issue === undefined) {
@@ -313,7 +317,7 @@ export async function detectInitialCopilotPrState({ repo, issue }, { env = proce
 }
 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 = parseDetectInitialCopilotPrStateCliArgs(argv);
   if (options.help) {
@@ -324,7 +328,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/loop/detect-internal-only-pr.mjs

@@ -6,6 +6,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: detect-internal-only-pr.mjs --repo <owner/name> --pr <number> [--config <path>]
 Detect whether a PR only touches internal tooling files (scripts, docs, tests, config)
@@ -20,9 +21,11 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "internalOnly": true|false, "files": ["path1", "path2", ...],
     "reason": "...", "repo": "...", "pr": N }
+${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 parseError = buildParseError(USAGE);
 
@@ -134,6 +137,7 @@ export function parseCliArgs(argv) {
       pr: { type: "string" },
       config: { type: "string" },
       "label-check": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -166,6 +170,7 @@ export function parseCliArgs(argv) {
       options.labelCheck = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -265,6 +270,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -275,7 +281,7 @@ export async function runCli(
     return;
   }
   const result = await detectInternalOnly(options, { 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)) {