dev-loops 0.6.0 → 0.7.2

package/scripts/github/verify-fresh-review-context.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
-import { mkdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { buildParseError, isDirectCliRun, formatCliError } from "../_core-helpers.mjs";
-const USAGE = `Usage: verify-fresh-review-context.mjs [--help] [--scope <name>]
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+const USAGE = `Usage: verify-fresh-review-context.mjs [--help] [--scope <name>] [--context-path <path>]
+       [--prefix-hash <sha256>|--prefix-file <path>]
 Verify that the current scoped-reviewer session has fresh context.
 
 "Fresh" means the reviewer's context is the neutral gate-context builder
@@ -10,30 +14,76 @@ artifact (the build-once diff + adjacent-code bundle) plus its single review
 angle, and explicitly NOT the main (orchestrating) agent's conversation/state
 or a prior reviewer session's state. The injected neutral bundle is the
 INTENDED seed and is NOT contamination; this guard detects main-agent /
-cross-session state bleed by way of a per-(cwd, scope) sentinel: a first run in
-a fresh session creates the sentinel and passes, a re-entry that finds an
-existing sentinel fails closed. Seeding a reviewer with the neutral bundle (a
-path/prompt, not a sentinel) never creates a sentinel, so it never
-false-positives as contaminated.
+cross-session state bleed by way of a per-(cwd, scope, round) sentinel: a first
+run in a fresh session creates the sentinel and passes, a re-entry that finds an
+existing sentinel for the same round fails closed. Seeding a reviewer with the
+neutral bundle (a path/prompt, not a sentinel) never creates a sentinel, so it
+never false-positives as contaminated.
+
+Sentinels are per review ROUND, keyed by the current head SHA (\`git rev-parse
+HEAD\`). A retry at a new head naturally gets a fresh sentinel (no manual clear
+step), while a same-scope + same-head re-entry still fails closed. When git is
+unavailable the sentinel is keyed by scope only (legacy behavior).
 Options:
   --scope <name>  Unique reviewer scope (e.g. "draft-gate-coverage").
                   Must be non-empty, containing only alphanumeric
                   characters and hyphens. When provided, the sentinel
                   is scoped so parallel reviewers in the same working
                   directory do not trigger false contamination.
+  --context-path <path>  Path to the seeded gate-context artifact this
+                  reviewer must be reading from (the build-once bundle
+                  written by write-gate-context.mjs, e.g.
+                  tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json).
+                  Must resolve to a path within the reviewer's working
+                  directory; a path that resolves OUTSIDE cwd (an absolute
+                  or ..-escaping path pointing at another worktree's bundle,
+                  which would defeat the worktree-locality guard) fails
+                  closed (exit 1).
+                  When provided, also fails closed (exit 1) if the artifact
+                  is missing (ENOENT) from the reviewer's cwd. Per-angle
+                  gate reviewers must run in the PR's actual worktree/head
+                  (never an isolated worktree) so this gitignored,
+                  worktree-local artifact is present; a missing artifact
+                  means either a stale/isolated checkout or a skipped
+                  preamble, and the reviewer must refuse to proceed
+                  rather than silently reviewing without seeded context.
+  --prefix-hash <sha256>  A 64-character hex SHA-256 digest (case-insensitive,
+                  normalized to lowercase) of the
+                  invariant briefing block this reviewer was seeded with
+                  (GATE-EXEC-BRIEFING-PREFIX in
+                  docs/gate-review-sub-loop-contract.md). Recorded on the
+                  reviewer's sentinel so \`verify-briefing-prefixes.mjs\` can
+                  fail closed when reviewers of the same gate pass were
+                  seeded with different invariant blocks. Mutually exclusive
+                  with --prefix-file.
+  --prefix-file <path>  Path to the invariant briefing block text; the tool
+                  hashes its raw bytes (sha256) and records the digest same
+                  as --prefix-hash. Fails closed (exit 1) if the file is
+                  missing. Mutually exclusive with --prefix-hash.
 Output (stdout, JSON):
-  { "ok": true, "fresh": true, "sentinelCreated": true }
-  { "ok": true, "fresh": false, "sentinelCreated": false, "reason": "..." }
+  { "ok": true, "fresh": true, "sentinelCreated": true, "round": "<headSha|null>" }
+  { "ok": true, "fresh": true, "sentinelCreated": true, "round": "...", "gateContextPath": "...", "gateContextPresent": true }
+  { "ok": true, "fresh": false, "sentinelCreated": false, "round": "...", "reason": "..." }
+  { "ok": true, "fresh": false, "sentinelCreated": false, "round": "...", "gateContextPath": "...", "gateContextPresent": false, "reason": "..." }
   On error (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Clean (first run)
-  1  Contaminated (prior session detected)
-  2  Usage or internal error`.trim();
+  1  Refuse to review: contaminated (prior session detected), OR (with
+     --context-path) the seeded gate-context artifact is missing or resolves
+     outside the reviewer's working directory, OR (with --prefix-file) the
+     prefix file is missing
+  2  Usage or internal error, invalid --jq filter, or invalid/conflicting
+     --prefix-hash/--prefix-file`.trim();
 const VALID_SCOPE_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 const parseError = buildParseError(USAGE);
-function resolveScope(argv) {
-  const idx = argv.indexOf("--scope");
+// Resolve a `--flag <value>` argument. Returns null when the flag is absent,
+// "" when it is present but the value is missing/empty/flag-like (a following
+// `-`-prefixed token, which must not be silently consumed), else the value.
+function resolveFlagValue(argv, flag) {
+  const idx = argv.indexOf(flag);
   if (idx === -1) return null;
   const val = argv[idx + 1];
   if (val === undefined || val === "" || (val.length > 0 && val[0] === "-")) {
@@ -41,6 +91,9 @@ function resolveScope(argv) {
   }
   return val;
 }
+function resolveScope(argv) {
+  return resolveFlagValue(argv, "--scope");
+}
 function resolveValidatedScope(argv) {
   const raw = resolveScope(argv);
   if (raw === null) return null;
@@ -52,22 +105,53 @@ function resolveValidatedScope(argv) {
   }
   return raw;
 }
-function sentinelRelative(scope) {
-  const suffix = scope ? `-${scope}` : "";
-  return path.join("tmp", `checkpoint-context-sentinel${suffix}.json`);
+function resolveContextPath(argv) {
+  return resolveFlagValue(argv, "--context-path");
+}
+function resolvePrefixHash(argv) {
+  return resolveFlagValue(argv, "--prefix-hash");
+}
+function resolvePrefixFile(argv) {
+  return resolveFlagValue(argv, "--prefix-file");
+}
+// Round = the current head SHA, so a retry on a new head gets a fresh key while
+// a same-head re-entry collides and fails closed. `git rev-parse HEAD` yields the
+// same full SHA on every invocation for a given head, so the key is deterministic
+// with no user input to spell it inconsistently. Returns null when git is
+// unavailable (falls back to the legacy scope-only key).
+function resolveHeadRound(cwd = process.cwd()) {
+  try {
+    const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return VALID_SCOPE_RE.test(sha) ? sha : null;
+  } catch {
+    return null; // not a git repo / git unavailable
+  }
+}
+function sentinelRelative(scope, round) {
+  const scopeSuffix = scope ? `-${scope}` : "";
+  const roundSuffix = round ? `-${round}` : "";
+  return path.join("tmp", `checkpoint-context-sentinel${scopeSuffix}${roundSuffix}.json`);
 }
 function legacySentinelRelative(scope) {
   const suffix = scope ? `-${scope}` : "";
   return path.join("tmp", `gate-review-context-sentinel${suffix}.json`);
 }
-async function checkSentinelExists(scope, cwd = process.cwd()) {
-  const sentinelPath = path.resolve(cwd, sentinelRelative(scope));
+async function checkSentinelExists(scope, round, cwd = process.cwd()) {
+  const sentinelPath = path.resolve(cwd, sentinelRelative(scope, round));
   try { await stat(sentinelPath); return { exists: true, path: sentinelPath, legacy: false }; } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
-  const legacyPath = path.resolve(cwd, legacySentinelRelative(scope));
-  try { await stat(legacyPath); return { exists: true, path: legacyPath, legacy: true }; } catch (err) {
-    if (err.code !== "ENOENT") throw err;
+  // Legacy names predate head-keyed rounds; only consult them for the
+  // scope-only key so a stale pre-round sentinel never blocks a new round.
+  if (!round) {
+    const legacyPath = path.resolve(cwd, legacySentinelRelative(scope));
+    try { await stat(legacyPath); return { exists: true, path: legacyPath, legacy: true }; } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
   }
   return { exists: false, path: sentinelPath, legacy: false };
 }
@@ -78,27 +162,135 @@ async function main(argv = process.argv.slice(2)) {
   }
   const scope = resolveValidatedScope(argv);
   if (scope === undefined) return 2;
-  const sentinelPath = path.resolve(process.cwd(), sentinelRelative(scope));
+  const contextPathArg = resolveContextPath(argv);
+  if (contextPathArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --context-path value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  const prefixHashArg = resolvePrefixHash(argv);
+  if (prefixHashArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --prefix-hash value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  const prefixFileArg = resolvePrefixFile(argv);
+  if (prefixFileArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --prefix-file value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  if (prefixHashArg !== null && prefixFileArg !== null) {
+    process.stderr.write(`${formatCliError(
+      parseError("--prefix-hash and --prefix-file are mutually exclusive — pass at most one.")
+    )}\n`);
+    return 2;
+  }
+  if (prefixHashArg !== null && !SHA256_HEX_RE.test(prefixHashArg.trim().toLowerCase())) {
+    process.stderr.write(`${formatCliError(
+      parseError(`Invalid --prefix-hash value "${prefixHashArg}": must be a 64-character hex SHA-256 digest (case-insensitive).`)
+    )}\n`);
+    return 2;
+  }
+  const jqArg = resolveFlagValue(argv, "--jq");
+  if (jqArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --jq value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  const jq = jqArg === null ? undefined : jqArg;
+  const silent = argv.includes("--silent") || argv.includes("-s");
+  // Every branch below reports ok:true (the tool ran successfully); the
+  // fresh/contaminated verdict maps to the exit code via `ok` here so the
+  // shared --jq/--silent contract composes with the existing 0=fresh/1=refuse
+  // signal instead of always reading ok:true as success.
+  const finish = (payload, freshLike) => emitResult(payload, { jq, silent, ok: freshLike });
+  const round = resolveHeadRound();
+  if (contextPathArg !== null) {
+    const cwd = process.cwd();
+    const resolvedContextPath = path.resolve(cwd, contextPathArg);
+    // The guard proves the reviewer is in the working tree where the gitignored
+    // tmp/gate-context bundle was written. An absolute or ..-escaping path could
+    // stat the real bundle in ANOTHER (stale/isolated) worktree and pass — so a
+    // path resolving outside cwd fails closed, defeating that bypass.
+    const withinCwd =
+      resolvedContextPath === cwd || resolvedContextPath.startsWith(cwd + path.sep);
+    if (!withinCwd) {
+      return finish({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        round: round ?? null,
+        gateContextPath: contextPathArg,
+        gateContextPresent: false,
+        reason: `Seeded gate-context artifact path "${contextPathArg}" resolves outside the reviewer's working directory — refusing. --context-path must be a cwd-relative path to the worktree-local bundle; an absolute or ..-escaping path could point at another (stale/isolated) worktree's bundle and defeat the worktree-locality guard.`,
+      }, false);
+    }
+    try {
+      await stat(resolvedContextPath);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      return finish({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        round: round ?? null,
+        gateContextPath: contextPathArg,
+        gateContextPresent: false,
+        reason: `Seeded gate-context artifact missing at "${contextPathArg}" — refusing to review without the build-once neutral context bundle. Per-angle gate reviewers must run in the PR's actual worktree/head (never an isolated worktree checked out from stale main), which is where the context-builder preamble wrote this gitignored artifact.`,
+      }, false);
+    }
+  }
+  // Resolve the invariant-briefing prefix hash (GATE-EXEC-BRIEFING-PREFIX) before
+  // sentinel creation, same ordering rationale as --context-path above: a failure
+  // here must not burn the scope sentinel.
+  let prefixHash = prefixHashArg !== null ? prefixHashArg.trim().toLowerCase() : null;
+  if (prefixHash === null && prefixFileArg !== null) {
+    let prefixFileBytes;
+    try {
+      prefixFileBytes = await readFile(path.resolve(process.cwd(), prefixFileArg));
+    } catch (err) {
+      // ANY read failure (ENOENT, EACCES, EPERM, ...) refuses the review in the
+      // normal fail-closed shape — an unreadable prefix file means the
+      // invariant-briefing proof cannot be established, which is an enforcement
+      // refusal, not a tool crash.
+      return finish({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        round: round ?? null,
+        reason: `--prefix-file "${prefixFileArg}" unreadable (${err.code ?? "error"}) — cannot compute the invariant-briefing prefix hash (GATE-EXEC-BRIEFING-PREFIX).`,
+      }, false);
+    }
+    prefixHash = createHash("sha256").update(prefixFileBytes).digest("hex");
+  }
+  const sentinelPath = path.resolve(process.cwd(), sentinelRelative(scope, round));
   try {
     await mkdir(path.dirname(sentinelPath), { recursive: true });
   } catch (err) {
     process.stderr.write(`${formatCliError(err)}\n`);
     return 2;
   }
-  const existing = await checkSentinelExists(scope);
+  const existing = await checkSentinelExists(scope, round);
   if (existing.exists) {
-    process.stdout.write(JSON.stringify({
+    return finish({
       ok: true,
       fresh: false,
       sentinelCreated: false,
+      round: round ?? null,
       reason: `Checkpoint context sentinel already exists${existing.legacy ? " (legacy name)" : ""} — inherited session context detected. Restart the subagent with fresh context (subagent({context:\"fresh\"})).`,
-    }) + "\n");
-    return 1;
+    }, false);
   }
   const sentinel = {
     createdAt: new Date().toISOString(),
     pid: process.pid,
     ...(scope ? { scope } : {}),
+    ...(round ? { round } : {}),
+    ...(prefixHash ? { prefixHash } : {}),
   };
   try {
     await writeFile(sentinelPath, JSON.stringify(sentinel, null, 2) + "\n", {
@@ -107,23 +299,25 @@ async function main(argv = process.argv.slice(2)) {
     });
   } catch (err) {
     if (err.code === "EEXIST") {
-      process.stdout.write(JSON.stringify({
+      return finish({
         ok: true,
         fresh: false,
         sentinelCreated: false,
+        round: round ?? null,
         reason: "Checkpoint context sentinel already exists (detected on atomic create) — inherited session context detected. Restart the subagent with fresh context (subagent({context:\"fresh\"})).",
-      }) + "\n");
-      return 1;
+      }, false);
     }
     process.stderr.write(`${formatCliError(err)}\n`);
     return 2;
   }
-  process.stdout.write(JSON.stringify({
+  return finish({
     ok: true,
     fresh: true,
     sentinelCreated: true,
-  }) + "\n");
-  return 0;
+    round: round ?? null,
+    ...(contextPathArg !== null ? { gateContextPath: contextPathArg, gateContextPresent: true } : {}),
+    ...(prefixHash ? { prefixHash } : {}),
+  }, true);
 }
 if (isDirectCliRun(import.meta.url)) {
   try {

package/scripts/github/view-pr.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+// Default PR facts a follow-up run reads: the fields loop info surfaces plus the
+// head SHA. Callers needing a different set pass --json <fields> (a comma list,
+// same vocabulary as `gh pr view --json`).
+const DEFAULT_FIELDS =
+  "number,title,body,state,isDraft,headRefName,baseRefName,headRefOid,author,mergedAt,mergeable,mergeStateStatus,url";
+
+const USAGE = `Usage: view-pr.mjs --repo <owner/name> --pr <number> [--json <fields>]
+Read PR facts (branch/state/mergeStateStatus/head SHA/etc.). Thin wrapper over
+\`gh pr view --json …\` — use this instead of an agent-level raw \`gh pr view\` so the
+loop's internal-tooling record stays clean (siblings: list-issues.mjs,
+comment-issue.mjs, fetch-ci-logs.mjs; #1057). For composite loop routing/CI facts
+prefer \`dev-loops loop info --pr\`; this is the thin field-read counterpart.
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --pr <number>                 Pull request number
+Optional:
+  --json <fields>               Comma-separated gh pr view field list
+                                (default: ${DEFAULT_FIELDS})
+Output (stdout, JSON):
+  { "ok": true, "pr": { <requested fields> } }
+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);
+
+export function parseViewPrCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      json: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    fields: DEFAULT_FIELDS,
+    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 === "json") {
+      const fields = requireTokenValue(token, parseError)
+        .split(",")
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+      if (fields.length === 0) {
+        throw parseError("--json must list at least one field");
+      }
+      if (fields.some((f) => !/^[A-Za-z][A-Za-z0-9]*$/.test(f))) {
+        throw parseError("--json fields must be gh pr view field names (letters/digits)");
+      }
+      options.fields = fields.join(",");
+      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("Viewing a PR 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;
+}
+
+export async function viewPr(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const result = await run(
+    ghCommand,
+    ["pr", "view", String(options.pr), "--repo", options.repo, "--json", options.fields],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh pr view failed: ${detail}`);
+  }
+  const pr = parseJsonText(result.stdout, { label: "gh pr view" });
+  if (pr === null || typeof pr !== "object" || Array.isArray(pr)) {
+    throw new Error("gh pr view did not return a JSON object");
+  }
+  return { ok: true, pr };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseViewPrCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await viewPr(options, { env, ghCommand, run });
+  } 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/wait-pr-checks.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseNonNegativeInteger, parsePositiveInteger, parsePrNumber, requireTokenValue } 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 {
+  DEFAULT_POLL_INTERVAL_MS,
+  COPILOT_REVIEW_WAIT_TIMEOUT_MS,
+} from "@dev-loops/core/loop/policy-constants";
+// Reuse probe-ci-status.mjs's watch engine verbatim (polling, heartbeats, the
+// not-yet-registered-check grace/race guard, head-change detection) instead of
+// re-implementing it. This wrapper only adds seconds-based flags and a direct
+// process-exit-code contract for shell/scripted callers.
+import { watchCiStatus } from "./probe-ci-status.mjs";
+
+const DEFAULT_TIMEOUT_SECONDS = Math.floor(COPILOT_REVIEW_WAIT_TIMEOUT_MS / 1000);
+const DEFAULT_POLL_SECONDS = Math.floor(DEFAULT_POLL_INTERVAL_MS / 1000);
+
+const USAGE = `Usage: wait-pr-checks.mjs --repo <owner/name> --pr <number> [--timeout <seconds>] [--poll <seconds>]
+Block until the current head SHA's CI checks/statuses settle, or the wait
+budget elapses. Replaces hand-rolled \`until [ "$(gh pr checks | grep -c pending)" = 0 ]\`
+shell loops with a single deterministic call.
+Required:
+  --repo <owner/name>     Repository slug (e.g. owner/repo)
+  --pr <number>           Pull request number
+Optional:
+  --timeout <seconds>     Total wait budget (default ${DEFAULT_TIMEOUT_SECONDS}; 0 = single
+                          immediate check, no wait)
+  --poll <seconds>        Delay between polls (default ${DEFAULT_POLL_SECONDS})
+Not-yet-registered-check race guard:
+  A freshly pushed head with zero registered checks does NOT settle green on
+  the first poll — a provider may post its first check a beat after the push.
+  The watcher requires either an observed check/status, or a stable empty
+  result across two consecutive polls, before treating the head as genuinely
+  check-less. A repo with no CI at all still settles after that grace instead
+  of hanging to timeout.
+Output (stdout, JSON, the final per-check summary):
+  { "ok": true, "status": "success"|"failure"|"pending"|"timeout"|"changed",
+    "settled": bool, "ciStatus": "success"|"failure"|"pending"|"none",
+    "failedChecks": [{ "name": "...", "conclusion"?: "..." }], "headSha": "...", "attempts": N }
+"changed" means the head SHA advanced during the wait; re-baseline and re-run.
+Diagnostic output (stderr):
+  { "ok": true, "type": "watch_heartbeat", "elapsedMs": N, "totalBudgetMs": N, "poll": N, "maxPolls": N }
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes (default output, no --jq/--silent):
+  0  Green (status "success")
+  1  Red (status "failure"), or an argument/gh/runtime error
+  2  Not settled (status "timeout"/"changed"/"pending")
+With --jq/--silent, the standard jq-output contract above applies instead
+(0/1 by result truthiness; 2 reserved for an invalid --jq filter).`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseWaitPrChecksCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      timeout: { type: "string" },
+      poll: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    timeoutMs: DEFAULT_TIMEOUT_SECONDS * 1000,
+    pollIntervalMs: DEFAULT_POLL_SECONDS * 1000,
+  };
+  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 === "timeout") {
+      // Canonical-digits validation (shared /^\d+$/ primitives): rejects
+      // JS-coercible spellings like 1e3, 0x10, "1.0", or " 5 ".
+      options.timeoutMs = parseNonNegativeInteger(requireTokenValue(token, parseError), "--timeout", parseError) * 1000;
+      continue;
+    }
+    if (token.name === "poll") {
+      options.pollIntervalMs = parsePositiveInteger(requireTokenValue(token, parseError), "--poll", parseError) * 1000;
+      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("Waiting on PR checks 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;
+}
+
+// Direct process-exit-code contract for shell/scripted callers — this is the
+// tool's reason to exist alongside `dev-loops loop watch-ci`, whose CLI always
+// exits 0 and expects callers to branch on the JSON `status` field instead.
+export function exitCodeForWaitResult(result) {
+  if (result.status === "success") return 0;
+  if (result.status === "failure") return 1;
+  return 2;
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    env = process.env,
+    ghCommand = "gh",
+    delayImpl = undefined,
+    now = undefined,
+  } = {},
+) {
+  const options = parseWaitPrChecksCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const result = await watchCiStatus(
+    { repo: options.repo, pr: options.pr, timeoutMs: options.timeoutMs, pollIntervalMs: options.pollIntervalMs },
+    {
+      env,
+      ghCommand,
+      ...(delayImpl ? { delayImpl } : {}),
+      ...(now ? { now } : {}),
+    },
+  );
+  if (options.jq !== undefined || options.silent) {
+    return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr, ok: result.status === "success" });
+  }
+  stdout.write(`${JSON.stringify(result)}\n`);
+  return exitCodeForWaitResult(result);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}