dev-loops 0.6.0 → 0.7.1

package/scripts/github/reply-resolve-review-threads.mjs

@@ -12,6 +12,7 @@ import {
   replyAndMaybeResolve,
   validateResolutionMessage,
 } from "./_review-thread-mutations.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: reply-resolve-review-threads.mjs --repo <owner/name> --pr <number> [--author <login>] [--message <text>] [--resolve]
 Reply to all matching unresolved review threads on one PR and optionally resolve them.
 Required:
@@ -30,9 +31,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   Runtime/gh failures:
     { "ok": false, "error": "...", "partialProgress"?: { ... } }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh/runtime failure`.trim();
+  1  Argument error or gh/runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseReplyResolveThreadsCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -44,6 +47,7 @@ export function parseReplyResolveThreadsCliArgs(argv) {
       author: { type: "string" },
       message: { type: "string" },
       resolve: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -88,6 +92,7 @@ export function parseReplyResolveThreadsCliArgs(argv) {
       options.resolve = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -111,6 +116,62 @@ async function readStdinText(stdin) {
   }
   return text;
 }
+// When --message is set, stdin is read only to detect a conflicting second
+// message source. A detached/idle pipe never sends EOF, so an unbounded read
+// hangs forever and the process never exits (issue #1012). Resolve as soon as
+// any NON-WHITESPACE byte arrives (a conflicting body is detected the instant
+// real content appears — no need to wait for EOF); keep buffering while only
+// whitespace has arrived (a leading newline is not yet a conflict and more may
+// follow); resolve on natural EOF; and time out on a silent/idle pipe. Either
+// way the stdin handle is released so the event loop can drain and the tool
+// always terminates.
+const CONFLICT_STDIN_TIMEOUT_MS = 500;
+function readStdinConflictProbe(stdin, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer;
+    const cleanup = () => {
+      clearTimeout(timer);
+      stdin.off?.("data", onData);
+      stdin.off?.("end", onEnd);
+      stdin.off?.("error", onEnd);
+      // Release the handle: an abandoned reader on a still-open pipe would
+      // otherwise keep the event loop alive and re-introduce the hang.
+      stdin.pause?.();
+      if (typeof stdin.unref === "function") {
+        stdin.unref();
+      } else {
+        stdin.destroy?.();
+      }
+    };
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    // Resolve early only once non-whitespace content is seen (a real conflict);
+    // '' or whitespace-only on clean EOF is not a conflict; undefined only on
+    // timeout (idle pipe) so the caller proceeds with --message.
+    let text = "";
+    const onData = (chunk) => {
+      text += String(chunk);
+      if (text.trim().length > 0) {
+        finish(text);
+      }
+    };
+    const onEnd = () => finish(text);
+    timer = setTimeout(() => finish(undefined), timeoutMs);
+    timer.unref?.();
+    stdin.setEncoding?.("utf8");
+    stdin.on?.("data", onData);
+    stdin.on?.("end", onEnd);
+    stdin.on?.("error", onEnd);
+  });
+}
+
 async function resolveMessageInput(options, { stdin = process.stdin } = {}) {
   if (typeof options.message === "string") {
     if (stdin.isTTY) {
@@ -119,8 +180,8 @@ async function resolveMessageInput(options, { stdin = process.stdin } = {}) {
       }
       return options.message;
     }
-    const stdinText = await readStdinText(stdin);
-    if (stdinText.trim().length > 0) {
+    const stdinText = await readStdinConflictProbe(stdin, CONFLICT_STDIN_TIMEOUT_MS);
+    if (typeof stdinText === "string" && stdinText.trim().length > 0) {
       throw parseError("Choose exactly one message source: --message <text> or stdin");
     }
     if (options.message.trim().length === 0) {
@@ -241,6 +302,7 @@ export async function runCli(
   {
     stdin = process.stdin,
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -258,7 +320,7 @@ export async function runCli(
   );
   const { matchedTargets, skippedThreadCount } = planBatchReplyTargets(parsed, options.author);
   if (matchedTargets.length === 0) {
-    stdout.write(`${JSON.stringify(createSuccessPayload({
+    process.exitCode = emitResult(createSuccessPayload({
       repo: options.repo,
       pr: options.pr,
       author: options.author,
@@ -268,7 +330,7 @@ export async function runCli(
       resolvedThreadCount: 0,
       skippedThreadCount,
       results: [],
-    }))}\n`);
+    }), { jq: options.jq, silent: options.silent, stdout, stderr });
     return;
   }
   const results = [];
@@ -328,7 +390,7 @@ export async function runCli(
   }
   const repliedThreadCount = results.length;
   const resolvedThreadCount = results.filter((entry) => entry.resolved).length;
-  stdout.write(`${JSON.stringify(createSuccessPayload({
+  process.exitCode = emitResult(createSuccessPayload({
     repo: options.repo,
     pr: options.pr,
     author: options.author,
@@ -338,7 +400,7 @@ export async function runCli(
     resolvedThreadCount,
     skippedThreadCount,
     results,
-  }))}\n`);
+  }), { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

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

@@ -15,6 +15,7 @@ import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState } from "@dev-loops/core/loop/copilot-loop-state";
 import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const BLOCKED_BY_COPILOT_COMMENT_STATUS = "blocked_by_copilot_comment";
 const SUPPRESSED_SAME_HEAD_CLEAN_STATUS = "suppressed_same_head_clean";
 const ROUND_CAP_REACHED_STATUS = "round_cap_reached";
@@ -50,9 +51,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (including unavailable)
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseRequestCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -62,6 +65,7 @@ export function parseRequestCliArgs(argv) {
       "force-rerequest-review": { type: "boolean" },
       repo: { type: "string" },
       pr: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -96,6 +100,7 @@ export function parseRequestCliArgs(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.repo === undefined || options.pr === undefined) {
@@ -609,6 +614,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -619,7 +625,7 @@ export async function runCli(
     return;
   }
   const result = await performCopilotReviewRequest(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/github/resolve-handoff-candidates.mjs

@@ -9,6 +9,7 @@ import {
   loadDevLoopConfig,
   resolveHumanHandoffConfig,
 } from "@dev-loops/core/config";
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 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
@@ -39,9 +40,11 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "enabled": bool, "candidates": [{ "login", "source", "isTeam"?, "paths"? }],
     "changedFiles": [...], "sources": [...], "warnings": [...] }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (including disabled no-op and fail-soft per-source skips)
-  1  Argument error`.trim();
+  1  Argument error
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -74,6 +77,8 @@ export function parseResolveCandidatesCliArgs(argv) {
       continue;
     }
     if (token === "--pr-author") { options.prAuthor = nextValue(args, ++i, "--pr-author").trim().replace(/^@/, ""); continue; }
+    if (token === "--jq") { options.jq = nextValue(args, ++i, "--jq"); continue; }
+    if (token === "--silent" || token === "-s") { options.silent = true; continue; }
     throw parseError(`Unknown argument: ${token}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -403,8 +408,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     { 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;
+  return emitResult(result, { jq: options.jq, silent: options.silent });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/github/resolve-tracker-local-spec.mjs

@@ -3,6 +3,7 @@ import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const ISSUE_JSON_FIELDS = "number,title,body,url,state";
 const USAGE = `Usage: resolve-tracker-local-spec.mjs (--repo <owner/name> --issue <number> | --issue-url <github-issue-url>)
 Resolve the canonical tracker-backed local spec bundle from one GitHub issue reference.
@@ -30,7 +31,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 parseError = buildParseError(USAGE);
 export function parseGitHubIssueUrl(value) {
   let parsedUrl;
@@ -68,6 +70,7 @@ export function parseResolveTrackerLocalSpecCliArgs(argv) {
       repo: { type: "string" },
       issue: { type: "string" },
       "issue-url": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -102,6 +105,7 @@ export function parseResolveTrackerLocalSpecCliArgs(argv) {
       options.issueUrl = requireTokenValue(token, parseError).trim();
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const usingIssueUrl = typeof options.issueUrl === "string";
@@ -119,6 +123,8 @@ export function parseResolveTrackerLocalSpecCliArgs(argv) {
       repo,
       issue,
       issueUrl: options.issueUrl,
+      ...(options.jq !== undefined ? { jq: options.jq } : {}),
+      ...(options.silent !== undefined ? { silent: options.silent } : {}),
     };
   }
   try {
@@ -201,7 +207,7 @@ export async function resolveTrackerLocalSpec(
 }
 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 = parseResolveTrackerLocalSpecCliArgs(argv);
   if (options.help) {
@@ -212,7 +218,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/github/stage-reviewer-draft.mjs

@@ -7,6 +7,7 @@ import { parseArgs } from "node:util";
 import { parsePositiveInteger, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildDraftReviewPayload } from "@dev-loops/core/loop/reviewer-loop-state";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const HELP = `Usage: stage-reviewer-draft.mjs --repo <owner/name> --pr <number> --review-file <path> [--local-state-output <path>]
 Stage a pending draft review on a GitHub pull request.
 Options:
@@ -15,9 +16,13 @@ Options:
   --review-file <path>      Path to JSON file containing review payload (required)
   --local-state-output <path>  Path to write local state snapshot (optional)
   --help, -h                Show this help
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 export function parseStageDraftCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -28,6 +33,7 @@ export function parseStageDraftCliArgs(argv) {
       pr: { type: "string" },
       "review-file": { type: "string" },
       "local-state-output": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -67,6 +73,7 @@ export function parseStageDraftCliArgs(argv) {
       options.localStateOutput = requireTokenValue(token);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
     throw new Error(`Unknown argument: ${token.rawName}`);
   }
   if (!options.repo || !options.pr || !options.reviewFile) {
@@ -169,6 +176,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -190,7 +198,7 @@ export async function runCli(
     await postDraftReview({ repo: options.repo, pr: options.pr, reviewPayload }, { env, ghCommand }),
   );
   const localStatePath = await writeLocalState(options.localStateOutput, draftReview);
-  stdout.write(`${JSON.stringify({
+  process.exitCode = emitResult({
     ok: true,
     repo: options.repo,
     pr: options.pr,
@@ -199,7 +207,7 @@ export async function runCli(
     reviewState: draftReview.state,
     commitSha: draftReview.commitSha,
     localStatePath,
-  })}\n`);
+  }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/github/tick-verified-checkboxes.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// Mirror the issue-body AC/DoD tick procedure onto the PR body: after a clean
+// pre_approval_gate verification, flip each verified item's `- [ ]` to `- [x]`
+// in the PR body via a single `gh pr edit --body-file` update. Matches labels by
+// EXACT (trimmed) text and fails closed — never blanket-checks, never unchecks.
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { editPr } from "./edit-pr.mjs";
+import { viewPr } from "./view-pr.mjs";
+
+const USAGE = `Usage: tick-verified-checkboxes.mjs --repo <owner/name> --pr <number> --verified <label> [--verified <label>...] [--dry-run]
+Tick verified acceptance-criteria checkboxes in a PR body. Mirrors the issue-body
+tick from skills/docs/acceptance-criteria-verification.md onto the PR body so the
+merged PR shows checked AC/DoD. Flips \`- [ ] <label>\` to \`- [x] <label>\` ONLY when
+<label> exactly equals a --verified label (exact-match, fail-closed: never blanket-
+checks, never unchecks). Applies a single \`gh pr edit --body-file\` update.
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --pr <number>                 Pull request number
+  --verified <label>            An exact (trimmed) checklist label that was verified
+                                (repeatable; at least one is required)
+Options:
+  --dry-run                     Compute + report the flips but never edit the PR
+Output (stdout, JSON):
+  { "ok": true, "pr": 17, "flipped": [...], "unmatched": [...], "edited": true|false }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+// GFM checklist line: optional indentation, a `-`/`*`/`+` bullet, a `[ ]`/`[x]`
+// box, then the label. Capture indent + bullet so we preserve them on flip, and
+// an optional trailing `\r` so CRLF bodies (as returned by `gh pr view`) round-
+// trip byte-for-byte instead of silently failing to match.
+const CHECKBOX_RE = /^(\s*)([-*+])\s+\[([ xX])\]\s+(.*?)(\r?)$/;
+
+// PURE: flip only unchecked checklist lines whose trimmed label EXACTLY equals a
+// verified label. Never unchecks. Never touches non-checkbox text. Idempotent:
+// an already-`[x]` verified label is neither flipped nor reported as unmatched.
+// Returns { body, flipped, unmatched } where flipped = labels changed this call
+// and unmatched = verified labels absent from the body's checklist.
+export function tickVerifiedCheckboxes(body, verifiedLabels) {
+  const verified = new Set(
+    (verifiedLabels ?? []).map((l) => String(l).trim()).filter((l) => l.length > 0),
+  );
+  const flipped = [];
+  const found = new Set();
+  const lines = String(body).split("\n");
+  const nextLines = lines.map((line) => {
+    const m = line.match(CHECKBOX_RE);
+    if (!m) return line;
+    const [, indent, bullet, mark, rest, cr] = m;
+    const label = rest.trim();
+    if (!verified.has(label)) return line;
+    found.add(label);
+    if (mark !== " ") return line; // already checked — leave it, idempotent
+    if (!flipped.includes(label)) flipped.push(label); // duplicate lines: report once
+    return `${indent}${bullet} [x] ${rest}${cr}`;
+  });
+  const unmatched = [...verified].filter((label) => !found.has(label));
+  return { body: nextLines.join("\n"), flipped, unmatched };
+}
+
+export function parseTickVerifiedCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      verified: { type: "string", multiple: true },
+      "dry-run": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    verified: [],
+    dryRun: false,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") continue;
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "verified") {
+      const label = requireTokenValue(token, parseError).trim();
+      if (label.length === 0) throw parseError("--verified must be a non-empty label");
+      options.verified.push(label);
+      continue;
+    }
+    if (token.name === "dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Ticking PR checkboxes requires both --repo <owner/name> and --pr <number>");
+  }
+  if (options.verified.length === 0) {
+    throw parseError("at least one --verified is required");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+export async function tickCheckboxes(
+  options,
+  { env = process.env, ghCommand = "gh", run = runChild, editPr: edit = editPr } = {},
+) {
+  // Reuse view-pr.mjs rather than re-implementing `gh pr view --json body`.
+  const { pr } = await viewPr(
+    { repo: options.repo, pr: options.pr, fields: "body" },
+    { env, ghCommand, run },
+  );
+  const currentBody = typeof pr.body === "string" ? pr.body : "";
+  const { body: nextBody, flipped, unmatched } = tickVerifiedCheckboxes(currentBody, options.verified);
+  if (flipped.length === 0 || options.dryRun) {
+    return { ok: true, pr: options.pr, flipped, unmatched, edited: false };
+  }
+  const dir = await mkdtemp(join(tmpdir(), "tick-verified-"));
+  try {
+    const bodyFile = join(dir, "body.md");
+    await writeFile(bodyFile, nextBody, "utf8");
+    await edit(
+      { repo: options.repo, pr: options.pr, bodyFile, addAssignees: [], removeAssignees: [] },
+      { env, ghCommand, run },
+    );
+    return { ok: true, pr: options.pr, flipped, unmatched, edited: true };
+  } finally {
+    // Clean up the temp dir on success or failure; never let cleanup mask the result/error.
+    try {
+      await rm(dir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup failures
+    }
+  }
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild, editPr: edit = editPr } = {},
+) {
+  let options;
+  try {
+    options = parseTickVerifiedCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await tickCheckboxes(options, { env, ghCommand, run, editPr: edit });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

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

@@ -3,7 +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 { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } 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";
@@ -391,14 +391,7 @@ 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;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   // Default execution mode to inline_single_agent when omitted. inlineReason is
@@ -897,7 +890,14 @@ async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRo
   try {
     // The PR is now a draft, so RUN_DRAFT_GATE is the legal action. Re-enter with
     // the caller's full options; prIsDraft is now true so this branch is skipped.
-    result = await upsertCheckpointVerdict(options, { env, ghCommand, repoRoot });
+    // `_draftTransitionInProgress` guards against unbounded recursion: if GitHub's
+    // draft-state read still lags the conversion mutation on re-entry (isDraft reads
+    // false again), the reconcile branch must NOT fire a second time — it fails closed
+    // with a clear error instead of recursing indefinitely (exit 13). (#1020)
+    result = await upsertCheckpointVerdict(
+      { ...options, _draftTransitionInProgress: true },
+      { env, ghCommand, repoRoot },
+    );
   } catch (error) {
     if (conversion.alreadyDraft !== true) {
       try {
@@ -1060,11 +1060,32 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   if (
     options.gate === "draft_gate"
     && !prIsDraft
+    && !options._draftTransitionInProgress
     && !coordination.draftGateAlreadySatisfied
     && coordination.allowedNextActions.includes(PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE)
   ) {
     return await postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot });
   }
+  // Fail closed on a lagged draft-state read: we are re-entering FROM
+  // postDraftGateViaDraftTransition (which just converted the PR to draft) yet the
+  // coordination context still reports the PR as non-draft. Recursing would loop
+  // indefinitely (the original #1020 hang → exit 13, error swallowed). Surface a
+  // clear, actionable error instead so the operator knows the draft conversion did
+  // not take (or GitHub's read lags the mutation) and can retry. (#1020)
+  if (
+    options.gate === "draft_gate"
+    && !prIsDraft
+    && options._draftTransitionInProgress
+  ) {
+    throw new Error(
+      `draft_gate self-heal for ${options.repo}#${options.pr} failed: the PR was converted to draft ` +
+      `to post the verdict, but GitHub still reports it as non-draft on re-entry (draft-state read lagged ` +
+      `the conversion mutation, or the conversion did not take). Not recursing. Re-run the draft_gate post ` +
+      `once the PR reflects the draft state, or reconcile manually with ` +
+      `\`gh pr ready ${options.pr} --repo ${options.repo}\` / ` +
+      `\`node scripts/github/reconcile-draft-gate.mjs --repo ${options.repo} --pr ${options.pr}\`.`,
+    );
+  }
   if (gateActionForbidden) {
     throw new Error(buildGateEntryRefusalError({ options, coordination }));
   }