dev-loops 0.3.0 → 0.5.0

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

@@ -3,6 +3,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, parseJsonText, parseReviewThreads } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
 import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
   DEFAULT_POLL_INTERVAL_MS,
@@ -24,6 +25,10 @@ Required:
 Output (stdout, JSON):
   { "ok": true, "status": "changed"|"timeout"|"idle", "repo": "...", "pr": N, "attempts": N,
     "newComments": [...], "newReviews": [...], "newIssueComments": [...] }
+Concise mode:
+  --concise, --summary      Human-readable summary: status, attempts, new-activity
+                            counts, AND the current round's new Copilot comment bodies.
+${JQ_OUTPUT_USAGE}
 Activity statuses:
   changed    Fresh Copilot review activity found (check newComments/newReviews/newIssueComments)
   timeout    Watch period elapsed with no fresh Copilot activity
@@ -91,7 +96,14 @@ function rejectRemovedFlag(token) {
 export function parseWatchCliArgs(argv) {
   const { tokens } = parseArgs({
     args: [...argv],
-    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      concise: { type: "boolean" },
+      summary: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
     allowPositionals: true,
     strict: false,
     tokens: true,
@@ -102,6 +114,9 @@ export function parseWatchCliArgs(argv) {
     pr: undefined,
     pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
     timeoutMs: COPILOT_REVIEW_WAIT_TIMEOUT_MS,
+    concise: false,
+    jq: undefined,
+    silent: false,
   };
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -125,6 +140,18 @@ export function parseWatchCliArgs(argv) {
       options.pr = parsePositiveInteger(requireTokenValue(token, parseError), "--pr", parseError);
       continue;
     }
+    if (token.name === "concise" || token.name === "summary") {
+      options.concise = true;
+      continue;
+    }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -311,6 +338,37 @@ export function buildPollDelayMs(watchStartedAtMs, timeoutMs, pollIntervalMs, at
   const scheduledAtMs = watchStartedAtMs + Math.min(timeoutMs, attempt * pollIntervalMs);
   return Math.max(0, scheduledAtMs - nowMs);
 }
+// Human-readable concise summary of a probe result, including the current
+// round's new Copilot comment bodies (the field `loop info --pr` omits).
+export function formatProbeConcise(result) {
+  const newComments = result.newComments ?? [];
+  const newReviews = result.newReviews ?? [];
+  const newIssueComments = result.newIssueComments ?? [];
+  const lines = [
+    `Copilot probe: PR #${result.pr} (${result.repo})`,
+    `  status:        ${result.status}`,
+    `  attempts:      ${result.attempts}`,
+    `  new threadComments: ${newComments.length}`,
+    `  new reviews:        ${newReviews.length}`,
+    `  new issueComments:  ${newIssueComments.length}`,
+  ];
+  const bodies = [
+    ...newReviews.map((r) => ({ kind: "review", body: r.body })),
+    ...newComments.map((c) => ({ kind: "threadComment", body: c.body })),
+    ...newIssueComments.map((c) => ({ kind: "issueComment", body: c.body })),
+  ].filter((entry) => typeof entry.body === "string" && entry.body.trim().length > 0);
+  if (bodies.length > 0) {
+    lines.push("  new Copilot comment bodies this round:");
+    for (const entry of bodies) {
+      const indented = entry.body.trim().split("\n").map((l) => `      ${l}`).join("\n");
+      lines.push(`    [${entry.kind}]`);
+      lines.push(indented);
+    }
+  } else {
+    lines.push("  new Copilot comment bodies this round: (none)");
+  }
+  return lines.join("\n");
+}
 export async function runCli(
   argv = process.argv.slice(2),
   {
@@ -325,10 +383,18 @@ export async function runCli(
     return;
   }
   const result = await watchCopilotReview(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  if (options.concise && options.jq === undefined && !options.silent) {
+    stdout.write(`${formatProbeConcise(result)}\n`);
+    return result.ok === false ? 1 : 0;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

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

@@ -30,7 +30,7 @@ Optional:
                             the last Copilot review. Refused when the PR head
                             has not changed since the last review.
 Debug:
-  PI_DEV_LOOPS_DEBUG=1      Emit stderr traces when best-effort same-head clean
+  DEVLOOPS_DEBUG=1      Emit stderr traces when best-effort same-head clean
                             convergence detection falls back to unsuppressed behavior
 Output (stdout, JSON):
   { "ok": true, "status": "requested"|"already-requested"|"unavailable"|"suppressed_same_head_clean"|"blocked_by_copilot_comment"|"round_cap_reached"|"no_changes_since_last_review"|"suppressed_draft",
@@ -262,7 +262,7 @@ async function detectSameHeadCleanConvergence(options, runtime, priorReviewState
     const interpretation = interpretLoopState(snapshot);
     return interpretation.sameHeadCleanConverged;
   } catch (error) {
-    if (runtime?.env?.PI_DEV_LOOPS_DEBUG === "1") {
+    if (runtime?.env?.DEVLOOPS_DEBUG === "1") {
       const detail = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[request-copilot-review] same-head clean-convergence detection unavailable: ${detail}\n`);
     }
@@ -302,7 +302,7 @@ async function detectRoundCapAutoRerequestEligibility(options, runtime, priorRev
       interpretation,
     };
   } catch (error) {
-    if (runtime?.env?.PI_DEV_LOOPS_DEBUG === "1") {
+    if (runtime?.env?.DEVLOOPS_DEBUG === "1") {
       const detail = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[request-copilot-review] round-cap auto-rerequest detection unavailable: ${detail}\n`);
     }

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

@@ -0,0 +1,412 @@
+#!/usr/bin/env node
+import { readFile as fsReadFile } from "node:fs/promises";
+import path from "node:path";
+
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parsePrNumber, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  loadDevLoopConfig,
+  resolveHumanHandoffConfig,
+} from "@dev-loops/core/config";
+
+const USAGE = `Usage: resolve-handoff-candidates.mjs --repo <owner/name> --pr <number> [--changed-files <a,b,c>] [--pr-author <login>]
+Resolve an ordered, deduped list of human-handoff reviewer/assignee candidates
+for a PR, from the sources configured under \`approval.humanHandoff\` (#920).
+This is the "offer" side: it surfaces candidates only — it never assigns anyone.
+
+Sources (in priority order):
+  assignees          Static configured list (approval.humanHandoff.assignees).
+  codeowners         .github/CODEOWNERS / CODEOWNERS / docs/CODEOWNERS matched
+                     against the PR's changed paths (last-match-wins per
+                     CODEOWNERS semantics). Team handles (@org/team) are
+                     included, flagged with isTeam:true.
+  recent-committers  git log authors on the PR's changed paths (recent commits),
+                     by GitHub login where derivable from the commit email,
+                     excluding the PR author and bots.
+
+Which sources run is controlled by approval.humanHandoff.candidatesFrom.
+Disabled (default) => no-op: ok:true with an empty candidate list.
+
+Required:
+  --repo <owner/name>
+  --pr <number>
+Optional:
+  --changed-files <csv>   Comma-separated changed paths. When omitted, derived
+                          from \`gh pr view --json files\`.
+  --pr-author <login>     PR author login (excluded from recent-committers).
+                          When omitted, derived from \`gh pr view --json author\`.
+Output (stdout, JSON):
+  { "ok": true, "enabled": bool, "candidates": [{ "login", "source", "isTeam"?, "paths"? }],
+    "changedFiles": [...], "sources": [...], "warnings": [...] }
+Exit codes:
+  0  Success (including disabled no-op and fail-soft per-source skips)
+  1  Argument error`.trim();
+
+const parseError = buildParseError(USAGE);
+
+function nextValue(args, i, flag) {
+  const value = args[i];
+  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+    throw parseError(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+const RECENT_COMMITTERS_LIMIT = 50;
+const CODEOWNERS_PATHS = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"];
+// Bot author handles to exclude from recent-committers.
+const BOT_PATTERN = /\[bot\]$|^(?:dependabot|github-actions|copilot|renovate)$/i;
+
+export function parseResolveCandidatesCliArgs(argv) {
+  const args = [...argv];
+  if (args.includes("--help") || args.includes("-h")) {
+    return { help: true };
+  }
+  const options = { help: false, repo: undefined, pr: undefined, changedFiles: undefined, prAuthor: undefined };
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === "--repo") { options.repo = nextValue(args, ++i, "--repo"); continue; }
+    if (token === "--pr") { options.pr = parsePrNumber(nextValue(args, ++i, "--pr"), parseError); continue; }
+    if (token === "--changed-files") {
+      options.changedFiles = nextValue(args, ++i, "--changed-files")
+        .split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+      continue;
+    }
+    if (token === "--pr-author") { options.prAuthor = nextValue(args, ++i, "--pr-author").trim().replace(/^@/, ""); continue; }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Resolving handoff candidates requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+// ---------------------------------------------------------------------------
+// CODEOWNERS — parse + match
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CODEOWNERS content into ordered { pattern, owners } rules.
+ * Comments (#...) and blank lines are skipped. Owners keep their leading `@`.
+ * @param {string} content
+ * @returns {{ pattern: string, owners: string[] }[]}
+ */
+export function parseCodeowners(content) {
+  const rules = [];
+  for (const rawLine of String(content).split("\n")) {
+    // A `#` starts a comment only at line start (after leading whitespace) or
+    // when preceded by whitespace; a mid-token `#` is part of the pattern/owner
+    // (gitignore/CODEOWNERS semantics).
+    const line = rawLine.replace(/(^|\s)#.*$/, "").trim();
+    if (line === "") continue;
+    const [pattern, ...owners] = line.split(/\s+/);
+    if (!pattern) continue;
+    rules.push({ pattern, owners: owners.filter((o) => o.length > 0) });
+  }
+  return rules;
+}
+
+/**
+ * Match a CODEOWNERS pattern against a repo-relative path (gitignore-ish).
+ * Leading `/` anchors to repo root; trailing `/` matches a directory subtree;
+ * `*` matches within a path segment, `**` across segments; a bare pattern with
+ * no slash matches the path's basename or any segment.
+ * @param {string} pattern
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function codeownersMatch(pattern, filePath) {
+  const file = filePath.replace(/^\.?\//, "");
+  let pat = pattern;
+  const dirOnly = pat.endsWith("/");
+  if (dirOnly) pat = pat.slice(0, -1);
+  // Bare name (no slash, not anchored): match any path segment subtree.
+  const anchored = pat.startsWith("/");
+  if (anchored) pat = pat.slice(1);
+
+  const toRegex = (p) => {
+    let re = "";
+    for (let i = 0; i < p.length; i += 1) {
+      const c = p[i];
+      if (c === "*") {
+        if (p[i + 1] === "*") { re += ".*"; i += 1; }
+        else re += "[^/]*";
+      } else if ("\\^$.|?+()[]{}".includes(c)) {
+        re += `\\${c}`;
+      } else {
+        re += c;
+      }
+    }
+    return re;
+  };
+
+  // Bare-vs-anchored is decided on the NORMALIZED pattern: a trailing-only `/`
+  // (e.g. `build/`) normalizes to a bare token with no leading/internal slash,
+  // so it matches at any depth like gitignore. Only a leading or internal slash
+  // anchors the match.
+  if (!anchored && !pat.includes("/")) {
+    // Bare token: match a full segment anywhere, plus its subtree.
+    const seg = toRegex(pat);
+    return new RegExp(`(?:^|/)${seg}(?:/|$)`).test(file);
+  }
+
+  const body = toRegex(pat);
+  // Anchored (or contains slash): match from root, allow subtree under it.
+  const re = new RegExp(`^${body}(?:/|$)`);
+  if (re.test(file)) return true;
+  // Directory pattern also matches the directory's whole subtree.
+  if (dirOnly) return new RegExp(`^${body}/`).test(file);
+  return false;
+}
+
+/**
+ * Resolve CODEOWNERS owners for a set of changed paths. Last-match-wins per
+ * CODEOWNERS semantics: the final matching rule for each path wins.
+ * @param {{ pattern: string, owners: string[] }[]} rules
+ * @param {string[]} changedFiles
+ * @returns {Map<string, Set<string>>} owner login (no `@`) -> set of paths
+ */
+export function ownersForPaths(rules, changedFiles) {
+  /** @type {Map<string, Set<string>>} */
+  const byOwner = new Map();
+  for (const file of changedFiles) {
+    let winner = null;
+    for (const rule of rules) {
+      if (codeownersMatch(rule.pattern, file)) winner = rule;
+    }
+    if (!winner || winner.owners.length === 0) continue;
+    for (const owner of winner.owners) {
+      const login = owner.replace(/^@/, "");
+      if (login === "") continue;
+      if (!byOwner.has(login)) byOwner.set(login, new Set());
+      byOwner.get(login).add(file);
+    }
+  }
+  return byOwner;
+}
+
+// ---------------------------------------------------------------------------
+// Source resolvers (each fail-soft: returns candidates + a warning on error)
+// ---------------------------------------------------------------------------
+
+async function resolveCodeownersSource(changedFiles, { repoRoot, readFile }) {
+  const warnings = [];
+  for (const rel of CODEOWNERS_PATHS) {
+    let content;
+    try {
+      content = await readFile(path.join(repoRoot, rel), "utf8");
+    } catch (error) {
+      // ENOENT => genuinely absent at this location: try the next path quietly.
+      // Any other error (EACCES / IO) is real: surface it rather than silently
+      // claiming "no CODEOWNERS file found".
+      if (error && error.code === "ENOENT") continue;
+      warnings.push(`codeowners: failed to read ${rel}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const rules = parseCodeowners(content);
+    const byOwner = ownersForPaths(rules, changedFiles);
+    return {
+      candidates: [...byOwner.entries()].map(([login, paths]) => ({
+        login,
+        source: "codeowners",
+        isTeam: login.includes("/"),
+        paths: [...paths],
+      })),
+      warnings,
+    };
+  }
+  // Fail-soft: no CODEOWNERS file anywhere -> no candidates, no abort. Keep any
+  // non-ENOENT read warnings so a permissions/IO failure is not masked.
+  return { candidates: [], warnings: [...warnings, "codeowners: no CODEOWNERS file found"] };
+}
+
+/**
+ * Map a git author email to a GitHub login. `<login>@users.noreply.github.com`
+ * (optionally `<id>+<login>@...`) carries the login directly; otherwise fall
+ * back to the local-part of the email as a best-effort handle.
+ */
+export function loginFromCommitEmail(email) {
+  const e = String(email).trim().toLowerCase();
+  const noreply = e.match(/^(?:\d+\+)?([^@]+)@users\.noreply\.github\.com$/);
+  if (noreply) return noreply[1];
+  const at = e.indexOf("@");
+  return at > 0 ? e.slice(0, at) : null;
+}
+
+async function resolveRecentCommittersSource(changedFiles, { repoRoot, prAuthor, run }) {
+  if (changedFiles.length === 0) {
+    return { candidates: [], warnings: [] };
+  }
+  let stdout;
+  try {
+    const result = await run("git", [
+      "-C", repoRoot,
+      "log", `-n${RECENT_COMMITTERS_LIMIT}`, "--no-merges", "--pretty=format:%ae",
+      "--", ...changedFiles,
+    ]);
+    if (result.code !== 0) {
+      return { candidates: [], warnings: [`recent-committers: git log exited ${result.code}`] };
+    }
+    stdout = result.stdout;
+  } catch (error) {
+    return { candidates: [], warnings: [`recent-committers: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  const author = prAuthor ? prAuthor.toLowerCase() : null;
+  const seen = new Set();
+  const candidates = [];
+  for (const line of stdout.split("\n")) {
+    const email = line.trim();
+    if (email === "") continue;
+    const login = loginFromCommitEmail(email);
+    if (!login) continue;
+    const key = login.toLowerCase();
+    if (seen.has(key)) continue;
+    if (BOT_PATTERN.test(login)) continue;
+    if (author && key === author) continue;
+    seen.add(key);
+    candidates.push({ login, source: "recent-committers" });
+  }
+  return { candidates, warnings: [] };
+}
+
+// ---------------------------------------------------------------------------
+// gh lookups for changed files / author (only when not supplied)
+// ---------------------------------------------------------------------------
+
+async function fetchPrFacts(repo, pr, { run, ghCommand }) {
+  const result = await run(ghCommand, [
+    "pr", "view", String(pr), "--repo", repo, "--json", "files,author",
+  ]);
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || `gh pr view exited ${result.code}`);
+  }
+  const payload = JSON.parse(result.stdout);
+  const files = Array.isArray(payload?.files)
+    ? payload.files.map((f) => (typeof f?.path === "string" ? f.path : "")).filter((p) => p.length > 0)
+    : [];
+  const author = typeof payload?.author?.login === "string" ? payload.author.login : null;
+  return { files, author };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve handoff candidates. Pure-ish: all IO is injected.
+ * @param {{ repo: string, pr: number, changedFiles?: string[], prAuthor?: string|null }} input
+ * @param {object} deps
+ * @returns {Promise<object>}
+ */
+export async function resolveHandoffCandidates(input, deps = {}) {
+  const {
+    config,
+    repoRoot = process.cwd(),
+    ghCommand = "gh",
+    run = (cmd, args) => runChild(cmd, args),
+    readFile = fsReadFile,
+  } = deps;
+
+  const handoff = resolveHumanHandoffConfig(config);
+  const warnings = [];
+
+  if (!handoff.enabled) {
+    return {
+      ok: true,
+      enabled: false,
+      candidates: [],
+      changedFiles: input.changedFiles ?? [],
+      sources: [],
+      warnings: [],
+    };
+  }
+
+  let changedFiles = input.changedFiles;
+  let prAuthor = input.prAuthor ?? null;
+  if (changedFiles === undefined || prAuthor === null) {
+    try {
+      const facts = await fetchPrFacts(input.repo, input.pr, { run, ghCommand });
+      if (changedFiles === undefined) changedFiles = facts.files;
+      if (prAuthor === null) prAuthor = facts.author;
+    } catch (error) {
+      warnings.push(`pr-facts: ${error instanceof Error ? error.message : String(error)}`);
+      if (changedFiles === undefined) changedFiles = [];
+    }
+  }
+
+  const ordered = [];
+  // 1. Static assignees — highest priority.
+  for (const login of handoff.assignees) {
+    ordered.push({ login: login.replace(/^@/, ""), source: "assignees", isTeam: login.includes("/") });
+  }
+
+  // 2/3. Other sources, in the CANONICAL priority order
+  // (assignees > codeowners > recent-committers), regardless of the order they
+  // appear in candidatesFrom. candidatesFrom only selects WHICH sources run,
+  // not their relative rank.
+  const enabledSources = new Set(handoff.candidatesFrom);
+  if (enabledSources.has("codeowners")) {
+    const result = await resolveCodeownersSource(changedFiles, { repoRoot, readFile });
+    ordered.push(...result.candidates);
+    warnings.push(...result.warnings);
+  }
+  if (enabledSources.has("recent-committers")) {
+    const result = await resolveRecentCommittersSource(changedFiles, { repoRoot, prAuthor, run });
+    ordered.push(...result.candidates);
+    warnings.push(...result.warnings);
+  }
+
+  // Dedup by login (case-insensitive), first occurrence wins (preserves the
+  // assignees > codeowners > recent-committers priority).
+  const seen = new Set();
+  const candidates = [];
+  for (const c of ordered) {
+    const key = c.login.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    candidates.push(c);
+  }
+
+  return {
+    ok: true,
+    enabled: true,
+    candidates,
+    changedFiles,
+    sources: handoff.candidatesFrom,
+    warnings,
+  };
+}
+
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  let options;
+  try {
+    options = parseResolveCandidatesCliArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const repoRoot = deps.repoRoot ?? process.cwd();
+  const { config } = deps.config !== undefined
+    ? { config: deps.config }
+    : await loadDevLoopConfig({ repoRoot });
+  const result = await resolveHandoffCandidates(
+    { repo: options.repo, pr: options.pr, changedFiles: options.changedFiles, prAuthor: options.prAuthor ?? null },
+    { ...deps, config, repoRoot },
+  );
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  return 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; });
+}

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig } from "@dev-loops/core/config";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { truncateText } from "@dev-loops/core/bash-exit-one";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -105,9 +106,11 @@ exists on a different head SHA (the old comment is stale for the current head).
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error, gh failure, or contradictory gate evidence`.trim();
+  1  Argument error, gh failure, or contradictory gate evidence
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 function rejectRemovedFlag(token) {
   throw parseError(
@@ -258,6 +261,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       "findings-severity-counts": { type: "string" },
       "execution-mode": { type: "string" },
       "inline-reason": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -277,6 +281,8 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
     findingsSeverityCounts: undefined,
     executionMode: undefined,
     inlineReason: undefined,
+    jq: undefined,
+    silent: false,
   };
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -385,6 +391,14 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.inlineReason = smartTruncate(reason, MAX_GATE_COMMENT_EXCERPT_LENGTH);
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   // Default execution mode to inline_single_agent when omitted. inlineReason is
@@ -1194,7 +1208,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   if (existing) {
     const updated = await updateComment({ repo: options.repo, commentId: existing.commentId, body: desiredBody }, { env, ghCommand });
     // Post-update verification: verify the updated comment is visible via direct API fetch by comment ID.
-    // A run id is set (production context) — DEVLOOPS_RUN_ID, or the PI_SUBAGENT_RUN_ID alias.
+    // A run id is set (production context) — DEVLOOPS_RUN_ID.
     let updateVerificationWarning = null;
     if (envRunId) {
       let verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, { env, ghCommand });
@@ -1229,7 +1243,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   // comment is not yet returned by paginated list endpoints. A direct fetch
   // by comment ID confirms the comment is persisted, preventing the evidence
   // checker from falsely reporting "missing" and triggering a duplicate post.
-  // Only active when a run id is set (production context) — DEVLOOPS_RUN_ID or the PI_SUBAGENT_RUN_ID alias.
+  // Only active when a run id is set (production context) — DEVLOOPS_RUN_ID.
   let verified = true;
   let verificationWarning = null;
   if (envRunId) {
@@ -1286,10 +1300,11 @@ async function main() {
     const result = await upsertCheckpointVerdict(options);
     // Emit the inline-execution warning only on success so the JSON error
     // envelope on stderr stays clean and machine-parseable on failures.
-    if (inlineWarning) {
+    // Suppress it under --silent, which contracts to zero output (exit code only).
+    if (inlineWarning && !options.silent) {
       process.stderr.write(`${inlineWarning}\n`);
     }
-    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
     process.exitCode = 1;