dev-loops 0.6.0 → 0.7.2

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

@@ -54,6 +54,7 @@ import { readFileSync } from "node:fs";
 import process from "node:process";
 import { parseArgs } from "node:util";
 import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: node scripts/loop/check-retro-tooling.mjs [--transcript <path>] [--json]
 
@@ -65,10 +66,13 @@ Options:
   --transcript <path>   File of newline-delimited commands (default: read stdin)
   --json                Emit machine-readable JSON (default: human summary)
 
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  No violations
   1  One or more violations found
-  2  Argument/runtime error`;
+  2  Argument/runtime error, or invalid --jq filter`;
 
 /**
  * Write-ops that currently have no internal dev-loops wrapper. Recorded
@@ -81,6 +85,10 @@ const ALLOWED_WRITE_OPS = Object.freeze([
   /^gh\s+pr\s+ready\b/,
   /^gh\s+issue\s+create\b/,
   /^gh\s+issue\s+edit\b/,
+  // `gh label create` HAS a wrapper (scripts/github/create-label.mjs); this
+  // entry is belt-and-suspenders so a bare invocation (e.g. surfaced from the
+  // wrapper's own subprocess) classifies as an allowed write-op, not a violation.
+  /^gh\s+label\s+create\b/,
 ]);
 
 /** Split a command line into top-level segments on &&, ||, |, ;. */
@@ -190,6 +198,7 @@ function parseCliArgs(argv) {
         transcript: { type: "string" },
         json: { type: "boolean" },
         help: { type: "boolean", short: "h" },
+        ...JQ_OUTPUT_PARSE_OPTIONS,
       },
       strict: true,
       allowPositionals: false,
@@ -221,8 +230,10 @@ async function run(argv, { stdout, stderr }) {
   const { violations, allowedWriteOps, internalToolingOnly } = analyzeTranscript(transcript);
 
   if (values.json) {
-    stdout.write(`${JSON.stringify({ ok: internalToolingOnly, internalToolingOnly, rawCallViolations: violations, allowedWriteOps })}\n`);
-  } else if (internalToolingOnly) {
+    const payload = { ok: internalToolingOnly, internalToolingOnly, rawCallViolations: violations, allowedWriteOps };
+    return emitResult(payload, { jq: values.jq, silent: values.silent, stdout, stderr });
+  }
+  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`);

package/scripts/loop/checkpoint-contract.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import process from "node:process";
 import { parseArgs } from "node:util";
 import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const CHECKPOINT_FILE = ".pi/dev-loop-retrospective-checkpoint.json";
 const ALLOWED_STATES = new Set(["required", "complete", "skipped", "none", "missing"]);
@@ -17,7 +18,9 @@ Required:
 
 Optional:
   --notes <text>           Required when --state is complete
-  --reason <text>          Required when --state is skipped`;
+  --reason <text>          Required when --state is skipped
+
+${JQ_OUTPUT_USAGE}`;
 
 function parseError(message) {
   return Object.assign(new Error(message), { usage: USAGE });
@@ -43,6 +46,7 @@ function parseCliArgs(argv) {
         notes: { type: "string" },
         reason: { type: "string" },
         help: { type: "boolean", short: "h" },
+        ...JQ_OUTPUT_PARSE_OPTIONS,
       },
       strict: true,
       allowPositionals: false,
@@ -67,7 +71,7 @@ function parseCliArgs(argv) {
     throw parseError('state "skipped" requires --reason');
   }
 
-  return { state, notes: values.notes ?? null, reason: values.reason ?? null };
+  return { state, notes: values.notes ?? null, reason: values.reason ?? null, jq: values.jq, silent: values.silent === true };
 }
 
 async function run(argv) {
@@ -82,8 +86,7 @@ async function run(argv) {
   const checkpointPath = path.join(process.cwd(), CHECKPOINT_FILE);
   await mkdir(path.dirname(checkpointPath), { recursive: true });
   await writeFile(checkpointPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-  process.stdout.write(JSON.stringify({ ok: true, path: CHECKPOINT_FILE, checkpoint: payload }) + "\n");
-  return 0;
+  return emitResult({ ok: true, path: CHECKPOINT_FILE, checkpoint: payload }, { jq: parsed.jq, silent: parsed.silent });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/loop/cleanup-worktree.mjs

@@ -21,6 +21,7 @@ import { requireTokenValue } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 import { resolveWorktreePath, WORKTREE_NAMESPACE } from "@dev-loops/core/loop/handoff-envelope";
 import { canonicalize } from "./_worktree-path.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   cleanup-worktree.mjs --repo-root <p> (--issue <n> | --pr <n> | --path <p>)
@@ -37,7 +38,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": bool, "removed": <path>|null, "reason": "<why>" }
   ok is true on success/skip (incl. fail-soft git errors); false ONLY when the
-  path is refused for being outside ${WORKTREE_NAMESPACE}/ (removed: null).`.trim();
+  path is refused for being outside ${WORKTREE_NAMESPACE}/ (removed: null).
+
+${JQ_OUTPUT_USAGE}`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -57,6 +60,7 @@ export function parseCleanupWorktreeCliArgs(argv) {
       issue: { type: "string" },
       pr: { type: "string" },
       path: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -85,6 +89,7 @@ export function parseCleanupWorktreeCliArgs(argv) {
       options.path = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.help) return options;
@@ -155,14 +160,18 @@ export function cleanupWorktree({ repoRoot, issue, pr, path: explicitPath }, { g
   return { ok: true, removed: target, reason: "removed" };
 }
 
-export function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+export function runCli(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
   const options = parseCleanupWorktreeCliArgs(argv);
   if (options.help) {
     stdout.write(`${USAGE}\n`);
     return;
   }
   const result = cleanupWorktree(options);
-  stdout.write(`${JSON.stringify(result)}\n`);
+  // FAIL-SOFT contract (see file header): a parsed command always exits 0 on the
+  // non-jq path, even when `ok:false` (path refused) — it must never break a
+  // merge-completion caller. Force ok:true here so the default path keeps that
+  // contract; --jq/--silent can still read the real `ok` field explicitly.
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr, ok: true });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/loop/conductor-monitor.mjs

@@ -4,7 +4,7 @@ import { access, open, readFile, readdir } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { requireTokenValue } from "../_cli-primitives.mjs";
-import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText, readJsonIfExists } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { autoDetectSnapshot } from "./detect-copilot-loop-state.mjs";
 import {
@@ -15,6 +15,7 @@ import {
 import { interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { listOpenPrs } from "./_loop-pr-aggregation.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: conductor-monitor.mjs --repo <owner/name> [--auto-resume]
 Aggregate Copilot-loop status across all open PRs in one repo.
 Required:
@@ -78,9 +79,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 PR status`.trim();
+  1  Argument error, gh failure, or indeterminate PR status
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 const DEFAULT_SESSION_ROOT = path.join(os.homedir(), ".pi", "agent", "sessions");
 const RUN_STATE = {
@@ -125,6 +128,7 @@ function parseCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       "auto-resume": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -149,6 +153,7 @@ function parseCliArgs(argv) {
       options.autoResume = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined) {
@@ -306,17 +311,6 @@ async function readFirstLineIfExists(filePath, chunkSize = 4096) {
     await handle?.close().catch(() => {});
   }
 }
-async function readJsonIfExists(filePath) {
-  const text = await readTextIfExists(filePath);
-  if (text === null) {
-    return null;
-  }
-  try {
-    return parseJsonText(text);
-  } catch {
-    return null;
-  }
-}
 function normalizeRunState(value) {
   const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
   switch (normalized) {
@@ -455,7 +449,7 @@ async function scanSessionArtifactRoot(artifactsDir, records) {
     const record = records.get(key) ?? createRunRecord(runId, childIndex);
     const filePath = path.join(artifactsDir, entry.name);
     if (entry.name.endsWith("_meta.json")) {
-      const meta = await readJsonIfExists(filePath);
+      const meta = await readJsonIfExists(filePath).catch(() => null);
       if (meta && typeof meta === "object") {
         records.set(key, mergeRunRecord(record, {
           agent: typeof meta.agent === "string" ? meta.agent : (record.agent ?? agent),
@@ -540,7 +534,7 @@ async function scanAsyncRunRoot(asyncRoot, records) {
     const asyncDir = path.join(asyncRoot, runDirEntry.name);
     const statusPath = path.join(asyncDir, "status.json");
     const eventsPath = path.join(asyncDir, "events.jsonl");
-    const status = await readJsonIfExists(statusPath);
+    const status = await readJsonIfExists(statusPath).catch(() => null);
     if (!status || typeof status !== "object") {
       continue;
     }
@@ -632,7 +626,7 @@ async function scanAsyncResultRoot(resultsRoot, records) {
     }
     const filePath = path.join(resultsRoot, entry.name);
     if (entry.name.endsWith(".json")) {
-      const result = await readJsonIfExists(filePath);
+      const result = await readJsonIfExists(filePath).catch(() => null);
       if (!result || typeof result !== "object") {
         continue;
       }
@@ -1807,7 +1801,7 @@ export async function runConductorMonitor(
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh", cwd = process.cwd() } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", cwd = process.cwd() } = {},
 ) {
   const options = parseCliArgs(argv);
   if (options.help) {
@@ -1819,7 +1813,7 @@ export async function runCli(
     ghCommand,
     repoRoot: cwd,
   });
-  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/copilot-pr-handoff.mjs

@@ -1,15 +1,17 @@
 #!/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 { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, 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 { PR_LIFECYCLE_STATE } from "@dev-loops/core/loop/pr-lifecycle";
+import { ensureAsyncRunnerOwnership, releaseAsyncRunnerOwnership } from "./_pr-runner-coordination.mjs";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
 
 
 import {
@@ -17,7 +19,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,
@@ -37,6 +39,13 @@ Optional:
   --watch-status <status>   Refresh deterministic loop state after a prior
                            watcher result (changed|timeout|idle). This mode
                            never requests review; it only re-detects state.
+  --lightweight         This PR is light-dispatched (#1210): compose the
+                        Copilot round cap with localImplementation.lightMode.
+                        maxCopilotRounds (default 1) via
+                        min(lightMode.maxCopilotRounds, refinement.maxCopilotRounds)
+                        instead of using refinement.maxCopilotRounds alone.
+                        refinement.maxCopilotRounds: 0 still disables Copilot
+                        rounds even with --lightweight.
 Output (stdout, JSON):
   { "ok": true, "action": "watch"|"fix"|"stop", "state": "...",
     "allowedTransitions": [...], "nextAction": "...", "snapshot": {...},
@@ -99,7 +108,7 @@ function summarizeRequestWatchContract({
     || interpretation.state === STATE.READY_TO_REREQUEST_REVIEW
     && interpretation.sameHeadCleanConverged !== true
   ) {
-    routingState = "ready_state_needs_copilot_request";
+    routingState = PR_LIFECYCLE_STATE.READY_STATE_NEEDS_COPILOT_REQUEST;
   } else if (interpretation.state === STATE.INTERNAL_TOOLING_DIRECT_GATE) {
     routingState = "internal_tooling_skip_copilot";
   }
@@ -137,6 +146,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
     repo: undefined,
     pr: undefined,
     watchStatus: undefined,
+    lightweight: false,
     jq: undefined,
     silent: false,
   };
@@ -147,6 +157,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       repo: { type: "string" },
       pr: { type: "string" },
       "watch-status": { type: "string" },
+      lightweight: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -183,14 +194,11 @@ 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;
+    if (token.name === "lightweight") {
+      options.lightweight = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.pr === undefined) {
@@ -300,12 +308,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,13 +365,22 @@ 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));
   }
   const refinementConfig = config.errors?.length > 0
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(config.config);
+  if (options.lightweight) {
+    // Compose (not replace) the round cap for light-dispatched PRs (#1210):
+    // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds), so
+    // maxCopilotRounds: 0 still disables Copilot rounds everywhere.
+    refinementConfig.maxCopilotRounds = resolveEffectiveCopilotRoundCap(
+      config.errors?.length > 0 ? { version: 1 } : config.config,
+      { lightweight: true },
+    );
+  }
   let interpretation = interpretLoopState(snapshot, refinementConfig);
 
   // Check for human comments since last subagent action
@@ -358,6 +395,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 +416,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 +482,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 +563,35 @@ 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,
+        // Thread the light-dispatch signal so the requester enforces the same
+        // composed round cap this handoff resolved (#1210) — the enforcement
+        // backstop must never permit rounds the interpreter already forbids.
+        lightweight: options.lightweight,
       },
       { 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 +654,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`);