dev-loops 0.5.0 → 0.7.1

package/scripts/loop/_post-convergence-change.mjs

@@ -0,0 +1,211 @@
+// Single source of truth (#1103, #1126) for "did a significant product/test-logic
+// change land since the last Copilot review at the round cap". Both
+// detect-pr-gate-coordination-state.mjs and copilot-pr-handoff.mjs consume this
+// so they agree on the round-cap escape hatch: at the cap, a significant
+// post-convergence change reopens a Copilot cycle (rerequest) instead of the
+// clean fallback; a doc/comment-only change stays at the clean fallback.
+//
+// It lives in scripts/loop/ (not packages/core) because significance is derived
+// from a `gh api .../compare` diff — gh I/O that does not belong in core.
+import { extractReviewCommitSha, isCopilotLogin, parseJsonText } from "../_core-helpers.mjs";
+import { runChild } from "../_cli-primitives.mjs";
+
+export function getLatestSubmittedCopilotReviewHeadSha(reviews) {
+  const copilotSubmitted = (Array.isArray(reviews) ? reviews : [])
+    .filter((review) => {
+      const login = review?.author?.login;
+      const state = String(review?.state ?? "").toUpperCase();
+      return isCopilotLogin(login) && state !== "PENDING";
+    })
+    .map((review, index) => {
+      const submittedAt = review?.submittedAt ?? review?.submitted_at;
+      const submittedAtMs = typeof submittedAt === "string" ? Date.parse(submittedAt) : Number.NaN;
+      return { review, submittedAtMs, index };
+    })
+    .sort((left, right) => {
+      const leftValid = !Number.isNaN(left.submittedAtMs);
+      const rightValid = !Number.isNaN(right.submittedAtMs);
+      if (leftValid && rightValid) {
+        return right.submittedAtMs - left.submittedAtMs;
+      }
+      if (leftValid !== rightValid) {
+        return leftValid ? -1 : 1;
+      }
+      return right.index - left.index;
+    });
+  const latest = copilotSubmitted[0]?.review;
+  const sha = extractReviewCommitSha(latest);
+  return typeof sha === "string" && sha.trim().length > 0 ? sha.trim() : null;
+}
+
+export function isTrivialDocumentationOnlyPath(filePath) {
+  if (typeof filePath !== "string") return true;
+  const normalized = filePath.trim().toLowerCase();
+  if (normalized.length === 0) return true;
+  if (normalized.startsWith("docs/")) return true;
+  return normalized.endsWith(".md")
+    || normalized.endsWith(".mdx")
+    || normalized.endsWith(".txt")
+    || normalized.endsWith(".rst")
+    || normalized.endsWith(".adoc");
+}
+
+// Extensions whose comment syntax we can classify with confidence (`//`, `/* */`).
+const JS_TS_EXTENSIONS = [".mjs", ".cjs", ".js", ".jsx", ".ts", ".tsx", ".mts", ".cts"];
+
+// Classifies one line's content given the current block-comment state.
+// Returns { code, state }: code=true when the line carries anything that is not
+// comment/blank; state = inBlockComment AFTER the line.
+// Known ceilings (both err toward significance or genuinely-trivial cases only):
+//   - a line STARTING with `//` or `/*` inside a string literal is misread as a
+//     comment — such a line still has to literally begin with the token, which
+//     real code lines almost never do;
+//   - a `/*` opener sitting AFTER code on the same line (`foo(); /* start`) is
+//     not tracked (we return code=true immediately) — follow-up `*` body lines
+//     then read as code → significant, the safe direction.
+function classifyLine(content, inBlock) {
+  let rest = content;
+  let state = inBlock;
+  while (true) {
+    if (state) {
+      const close = rest.indexOf("*/");
+      if (close === -1) return { code: false, state: true };
+      rest = rest.slice(close + 2);
+      state = false;
+      continue;
+    }
+    const trimmed = rest.trim();
+    if (trimmed.length === 0) return { code: false, state };
+    if (trimmed.startsWith("//")) return { code: false, state };
+    if (trimmed.startsWith("/*")) {
+      rest = trimmed.slice(2);
+      state = true;
+      continue;
+    }
+    // Anything else is code — including a bare `*`-leading line with NO open
+    // block observed: generator signatures (`*items() {`) and operator
+    // continuations (`* b`) start with `*` and are real code.
+    return { code: true, state };
+  }
+}
+
+// Content-level significance filter (#1137). A JS/TS file change is "comment-only"
+// when EVERY added/removed line in its patch is blank OR a comment line. Such
+// changes (JSDoc/inline-comment tweaks) must NOT reopen a Copilot round past the
+// cap. Comment rules:
+//   - a line starting with `//` is a comment;
+//   - `/*` opens block-comment state, `*/` closes it; state is tracked across
+//     ALL patch lines (changed AND context) and RESET at every `@@` hunk header
+//     — a block opened before the hunk is unobservable, so a `*`-leading line
+//     with no observed opener in the same hunk is treated as CODE (conservative:
+//     bare `*` counts as comment ONLY inside an observed open `/* ... */` block).
+// Conservative by construction — every ambiguous case returns false (= NOT
+// classifiable as comment-only; the file remains subject to the existing
+// size/count thresholds, it is NOT auto-escalated to significant):
+//   - patch missing (binary / oversized to diff)     → false
+//   - extension we cannot classify (non-JS/TS code)  → false
+//   - a changed line mixing code + comment           → false
+//   - a patch with no parseable added/removed lines  → false
+// Input contract: GitHub compare `files[].patch` starts at `@@` and never
+// contains `---`/`+++` file headers, so `+`/`-` prefixes are always content
+// (`+++counter;` is the real added line `++counter;`, not a header).
+// Note: line-scanner heuristic, upgrade to a real tokenizer only if string-literal misreads ever bite.
+export function isCommentOnlyFileChange(file) {
+  const filename = typeof file?.filename === "string" ? file.filename : "";
+  const lower = filename.toLowerCase();
+  if (!JS_TS_EXTENSIONS.some((ext) => lower.endsWith(ext))) {
+    // Not a classifiable code file (or a doc path handled elsewhere) → treat as code.
+    return false;
+  }
+  const patch = file?.patch;
+  if (typeof patch !== "string" || patch.length === 0) {
+    // No patch (binary / too large) → cannot prove trivial → treat as code.
+    return false;
+  }
+  let sawChangedLine = false;
+  let inBlock = false;
+  for (const line of patch.split("\n")) {
+    if (line.startsWith("@@")) {
+      inBlock = false; // hunk boundary: the gap is unobserved → reset state
+      continue;
+    }
+    if (line.startsWith("\\")) continue; // ""
+    const marker = line[0];
+    const content = line.slice(1);
+    if (marker === "+" || marker === "-") {
+      sawChangedLine = true;
+      const { code, state } = classifyLine(content, inBlock);
+      if (code) return false;
+      inBlock = state;
+    } else {
+      // Context line: never classified as changed content, but it advances
+      // block-comment state so an opener/closer visible in the hunk is honored.
+      inBlock = classifyLine(content, inBlock).state;
+    }
+  }
+  // A patch with zero parseable changed lines is ambiguous → treat as code.
+  return sawChangedLine;
+}
+
+export async function detectPostConvergenceSignificantChange(
+  { repo, pr, currentHeadSha, reviews, changedFiles, roundCapReached, regularCopilotRounds },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  if (!roundCapReached || !regularCopilotRounds) {
+    return false;
+  }
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return false;
+  }
+  if (!currentHeadSha) {
+    // No usable current head → the compare call would be doomed; fail closed
+    // without issuing a wasted gh API request.
+    return false;
+  }
+  const lastReviewedHeadSha = getLatestSubmittedCopilotReviewHeadSha(reviews);
+  if (!lastReviewedHeadSha || lastReviewedHeadSha === currentHeadSha) {
+    return false;
+  }
+  const compareResult = await runChild(
+    ghCommand,
+    ["api", `repos/${repo}/compare/${lastReviewedHeadSha}...${currentHeadSha}`],
+    env,
+  );
+  if (compareResult.code !== 0) {
+    return false;
+  }
+  let payload;
+  try {
+    payload = parseJsonText(compareResult.stdout, { label: "gh compare" });
+  } catch {
+    return false;
+  }
+  const rawFiles = Array.isArray(payload?.files) ? payload.files : [];
+  if (rawFiles.length === 0) {
+    return false;
+  }
+  // Content-aware filter (#1137): drop comment/JSDoc-only JS/TS changes BEFORE the
+  // existing size/count thresholds so trivial comment fixes no longer reopen a
+  // Copilot round past the cap. Doc paths and un-classifiable files fall through
+  // unchanged (isCommentOnlyFileChange returns false for them), preserving the
+  // prior threshold behavior for everything else.
+  const files = rawFiles.filter((file) => !isCommentOnlyFileChange(file));
+  if (files.length === 0) {
+    return false;
+  }
+  const hasNonDocChanges = files.some((file) => !isTrivialDocumentationOnlyPath(file?.filename));
+  if (!hasNonDocChanges) {
+    return false;
+  }
+  const totalChangedLines = files.reduce((sum, file) => {
+    const changes = Number(file?.changes);
+    if (Number.isFinite(changes) && changes > 0) {
+      return sum + changes;
+    }
+    const additions = Number(file?.additions);
+    const deletions = Number(file?.deletions);
+    const fallback = (Number.isFinite(additions) ? additions : 0) + (Number.isFinite(deletions) ? deletions : 0);
+    return sum + (fallback > 0 ? fallback : 0);
+  }, 0);
+  return totalChangedLines >= 20 || files.length >= 2;
+}

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

@@ -610,3 +610,73 @@ export async function ensureAsyncRunnerOwnership({
   }
   return claimRunnerOwnership({ repo, pr, runId, cwd, mode: "claim" });
 }
+/**
+ * Env-aware, best-effort release for the run-completion/stop path (issue #1109).
+ *
+ * Mirrors {@link ensureAsyncRunnerOwnership}: a no-op when no async run id is
+ * present, so it is harness-agnostic — Claude Code with no DEVLOOPS_RUN_ID yields
+ * `skipped_no_async_run_id` and never touches the coordination file.
+ *
+ * Non-fatal by contract: a release conflict (the claim is owned by another run,
+ * or no record remains) is swallowed into an `ok:true` result so a failed release
+ * can never block a stop/checkpoint. Fail-closed competitor semantics are
+ * preserved — {@link releaseRunnerOwnership} only clears a claim THIS run owns, so
+ * a genuinely active competing run's claim is left intact.
+ *
+ * Resolves to one of `skipped_no_async_run_id` (no run id present),
+ * `release_skipped` (release conflict swallowed), `release_error` (release threw),
+ * or the passthrough `releaseRunnerOwnership` result — `released` when this run's
+ * claim was cleared, or `release_noop` when the target has no coordination record.
+ */
+export async function releaseAsyncRunnerOwnership({
+  repo,
+  pr,
+  env = process.env,
+  cwd = process.cwd(),
+} = {}) {
+  const filePath = defaultRunnerCoordinationFilePathForTarget({ repo, pr }, cwd);
+  const runId = normalizeRunId(resolveRunId(env));
+  if (runId === null) {
+    return {
+      ok: true,
+      status: "skipped_no_async_run_id",
+      repo: normalizeRepoSlug(repo),
+      pr: normalizePr(pr),
+      runId: null,
+      activeRun: null,
+      exitSignals: [],
+      filePath,
+    };
+  }
+  try {
+    const released = await releaseRunnerOwnership({ repo, pr, runId, cwd });
+    if (released.ok) {
+      return released;
+    }
+    return {
+      ok: true,
+      status: "release_skipped",
+      repo: released.repo ?? normalizeRepoSlug(repo),
+      pr: released.pr ?? normalizePr(pr),
+      runId,
+      activeRun: released.activeRun ?? null,
+      exitSignals: released.exitSignals ?? [],
+      skippedReason: released.error,
+      message: released.message,
+      filePath: released.filePath ?? filePath,
+    };
+  } catch (error) {
+    return {
+      ok: true,
+      status: "release_error",
+      repo: normalizeRepoSlug(repo),
+      pr: normalizePr(pr),
+      runId,
+      activeRun: null,
+      exitSignals: [],
+      skippedReason: "release_threw",
+      message: error instanceof Error ? error.message : String(error),
+      filePath,
+    };
+  }
+}

package/scripts/loop/_repo-root-resolver.mjs

@@ -0,0 +1,47 @@
+/**
+ * Shared worktree-relative repo-root / ledger-checkout resolver (issue #1052,
+ * folds #1019 and #1050). ONE shared resolver: derive repo root from the
+ * checkout under operation (git-toplevel, not ambient cwd) for config reads,
+ * and enumerate ALL checkouts (main + every worktree) for ledger reads so a
+ * ledger written in any worktree is visible regardless of which checkout runs
+ * the check.
+ *
+ * #1050: the pre-PR-worktree flow means the session cwd is a DIFFERENT checkout
+ * than the PR worktree. Ledgers get written cwd-relative in the PR worktree but
+ * read cwd-relative from the session checkout, so they diverge and clean gates
+ * false-block on "missing pre-merge gate evidence". resolveLedgerCheckouts
+ * enumerates every checkout so a ledger written in one is found from any.
+ *
+ * #1019: .devloops is read at EXACTLY <repoRoot>/.devloops with no upward walk.
+ * Reading it from process.cwd() (a subdir or sibling checkout) silently falls
+ * back to defaults (maxCopilotRounds -> 5). resolveRepoRoot derives the root
+ * from the checkout's git-toplevel so config resolves correctly.
+ */
+import { execFileSync } from "node:child_process";
+import { parseAllWorktreePaths, parseMainWorktreePath } from "@dev-loops/core/loop/worktree-guard";
+
+export function resolveRepoRoot(cwd, { gitCommand = "git" } = {}) {
+  try {
+    return execFileSync(gitCommand, ["rev-parse", "--show-toplevel"], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || cwd;
+  } catch {
+    // git failed or cwd is not inside a git repo (or git is unavailable) -> fall back to cwd.
+    return cwd;
+  }
+}
+
+export function resolveLedgerCheckouts(cwd, { gitCommand = "git" } = {}) {
+  const roots = [];
+  const add = (p) => { if (typeof p === "string" && p.length > 0 && !roots.includes(p)) roots.push(p); };
+  add(resolveRepoRoot(cwd, { gitCommand }));
+  try {
+    const listing = execFileSync(gitCommand, ["worktree", "list"], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    add(parseMainWorktreePath(listing));
+    for (const p of parseAllWorktreePaths(listing)) add(p);
+  } catch { /* git failed, not inside a git repo, or git unavailable: cwd-toplevel is all we have */ }
+  if (roots.length === 0) add(cwd);
+  return roots;
+}

package/scripts/loop/build-handoff-envelope.mjs

@@ -12,7 +12,7 @@
  *   dev-loops loop build-envelope --input resolver-output.json
  *
  * Or via npx:
- *   npx dev-loops loop build-envelope --input resolver-output.json
+ *   npx dev-loops@<version> loop build-envelope --input resolver-output.json
  */
 import { readFile } from "node:fs/promises";
 import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -23,6 +23,8 @@ import { buildDevLoopHandoffEnvelope } from "@dev-loops/core/loop/handoff-envelo
 import { loadDevLoopConfig } from "@dev-loops/core/config";
 import { createPiAdapter } from "@dev-loops/core/harness";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { SANCTIONED_COMMANDS } from "./sanctioned-commands.mjs";
 
 const USAGE = `Usage: build-handoff-envelope.mjs --input <path>
 Build a deterministic handoff envelope from startup resolver output and settings.
@@ -30,7 +32,7 @@ Required:
   --input <path>         Path to resolver output JSON (from resolve-dev-loop-startup.mjs)
 Optional:
   --gate-state <json>    Gate state JSON string
-                           { currentHeadSha?, ciStatus?, unresolvedThreadCount?, copilotRoundCount? }
+                           { currentHeadSha?, ciStatus?, unresolvedThreadCount?, copilotRoundCount?, retrospectiveFindings? }
   --overrides <json>     Overrides JSON string
                            { mergeAuthorized?, preferLocal?, scopeConstraint?, customStopAt? }
   --repo <owner/name>    Repository slug override (falls back to bundle.repoSlug or bundle.repo)
@@ -41,9 +43,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   Runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or runtime failure`.trim();
+  1  Argument error or runtime failure
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -73,6 +77,7 @@ export function parseBuildHandoffEnvelopeCliArgs(argv) {
       "gate-state": { type: "string" },
       overrides: { type: "string" },
       repo: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -105,6 +110,7 @@ export function parseBuildHandoffEnvelopeCliArgs(argv) {
       options.repo = requireTokenValue(token, parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
@@ -143,6 +149,10 @@ export async function buildHandoffEnvelopeCli(
   // Build options for envelope builder
   const envelopeOptions = {};
 
+  // Carry the canonical sanctioned operation → wrapper command map (issue #1081)
+  // into every emitted envelope by DEFAULT so spawned subagents never re-derive it.
+  envelopeOptions.sanctionedCommands = SANCTIONED_COMMANDS;
+
   // Repo slug: explicit --repo, then resolver output bundle, then git remote
   const bundleSlug = resolverOutput?.bundle?.repoSlug ?? resolverOutput?.bundle?.repo ?? null;
   const repoSlug = options.repo ?? bundleSlug ?? detectRepoSlug(repoRoot);
@@ -186,7 +196,7 @@ export async function runCli(
 
   try {
     const envelope = await buildHandoffEnvelopeCli(options, { adapter });
-    stdout.write(`${JSON.stringify(envelope)}\n`);
+    process.exitCode = emitResult(envelope, { jq: options.jq, silent: options.silent, stdout, stderr });
   } catch (err) {
     const msg = formatCliError(err);
     stderr.write(`${msg}\n`);

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) => {