dev-loops 0.1.0

package/scripts/loop/detect-reviewer-loop-state.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  interpretReviewerLoopState,
+  normalizeReviewerSnapshot,
+} from "@dev-loops/core/loop/reviewer-loop-state";
+const HELP = `Usage: detect-reviewer-loop-state.mjs [--input <path> | --repo <owner/name> --pr <number>] [--review-requested <true|false>] [--local-state <path>]
+Detect reviewer loop state for a pull request.
+Modes:
+  --input <path>                Interpret a JSON snapshot from file
+  --repo <owner/name> --pr <n>  Auto-detect state from GitHub PR
+Options (auto-detect mode only):
+  --review-requested <bool>     Override review-requested detection (true/false)
+  --local-state <path>          Path to local state file for snapshot merging
+Reviewer scope is auto-resolved from PR requested reviewers.
+Exit codes:
+  0   Success
+  1   Error
+`;
+function parseBool(value, flag) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`${flag} must be true or false`);
+}
+export function parseDetectReviewerCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    inputPath: undefined,
+    repo: undefined,
+    pr: undefined,
+    reviewRequestedOverride: undefined,
+    localStatePath: undefined,
+    help: false,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--input") {
+      options.inputPath = requireOptionValue(args, "--input");
+      continue;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo").trim();
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr"));
+      continue;
+    }
+    if (token === "--review-requested") {
+      options.reviewRequestedOverride = parseBool(
+        requireOptionValue(args, "--review-requested"),
+        "--review-requested",
+      );
+      continue;
+    }
+    if (token === "--local-state") {
+      options.localStatePath = requireOptionValue(args, "--local-state");
+      continue;
+    }
+    throw new Error(`Unknown argument: ${token}`);
+  }
+  if (options.inputPath !== undefined) {
+    if (options.repo !== undefined || options.pr !== undefined) {
+      throw new Error("Choose exactly one input source: --input <path> or --repo/--pr auto-detect");
+    }
+    const hasInputOnlyConflict = options.localStatePath !== undefined
+      || options.reviewRequestedOverride !== undefined;
+    if (hasInputOnlyConflict) {
+      throw new Error("--input cannot be combined with --review-requested or --local-state");
+    }
+    return options;
+  }
+  const hasRepo = options.repo !== undefined;
+  const hasPr = options.pr !== undefined;
+  if (hasRepo || hasPr) {
+    if (!hasRepo || !hasPr) {
+      throw new Error("Auto-detect mode requires both --repo <owner/name> and --pr <number>");
+    }
+    parseRepoSlug(options.repo);
+  } else {
+    throw new Error("Provide either --input <path> or --repo <owner/name> --pr <number>");
+  }
+  return options;
+}
+async function runGhJson(args, { env, ghCommand }) {
+  const result = await runChild(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Invalid JSON from gh: ${result.stdout.trim() || "<empty>"}`);
+  }
+}
+async function fetchPrView({ repo, pr }, deps) {
+  const result = await runChild(
+    deps.ghCommand,
+    ["pr", "view", String(pr), "--repo", repo, "--json", "isDraft,state,number,headRefOid"],
+    deps.env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    if (/no pull requests found/i.test(detail) || /could not find pull request/i.test(detail)) {
+      return null;
+    }
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Invalid JSON from gh: ${result.stdout.trim() || "<empty>"}`);
+  }
+}
+function isReviewInScope(review, reviewerLogin) {
+  if (!reviewerLogin) return true;
+  const login = typeof review?.user?.login === "string"
+    ? review.user.login
+    : (typeof review?.author?.login === "string" ? review.author.login : "");
+  return login.toLowerCase() === reviewerLogin.toLowerCase();
+}
+function isSubmittedReviewState(state) {
+  return ["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"].includes(state);
+}
+function pickLatestById(items) {
+  if (!Array.isArray(items) || items.length === 0) return null;
+  return items.filter(Boolean).slice().sort((a, b) => {
+    const aid = typeof a.id === "number" ? a.id : -1;
+    const bid = typeof b.id === "number" ? b.id : -1;
+    return bid - aid;
+  })[0] ?? null;
+}
+async function fetchReviewRequested({ repo, pr, reviewerLogin, reviewRequestedOverride }, deps) {
+  if (typeof reviewRequestedOverride === "boolean") return reviewRequestedOverride;
+  const payload = await runGhJson(["api", `repos/${repo}/pulls/${pr}/requested_reviewers`], deps);
+  const users = Array.isArray(payload?.users) ? payload.users : [];
+  if (reviewerLogin) {
+    return users.some((user) => {
+      const login = typeof user?.login === "string" ? user.login : "";
+      return login.toLowerCase() === reviewerLogin.toLowerCase();
+    });
+  }
+  return users.length > 0;
+}
+async function fetchReviewState({ repo, pr, reviewerLogin }, deps) {
+  const payload = await runGhJson(["api", `repos/${repo}/pulls/${pr}/reviews`], deps);
+  const reviews = Array.isArray(payload) ? payload : [];
+  const scoped = reviews.filter((review) => isReviewInScope(review, reviewerLogin));
+  const pendingReview = pickLatestById(
+    scoped.filter((review) => String(review?.state || "").toUpperCase() === "PENDING"),
+  );
+  const submittedReview = pickLatestById(
+    scoped.filter((review) => isSubmittedReviewState(String(review?.state || "").toUpperCase())),
+  );
+  return {
+    draftReviewPosted: Boolean(pendingReview),
+    draftReviewId: typeof pendingReview?.id === "number" ? pendingReview.id : null,
+    draftReviewUrl: typeof pendingReview?.html_url === "string" ? pendingReview.html_url : null,
+    draftReviewCommitSha: typeof pendingReview?.commit_id === "string" ? pendingReview.commit_id : null,
+    submittedReviewPresent: Boolean(submittedReview),
+    submittedReviewCommitSha: typeof submittedReview?.commit_id === "string" ? submittedReview.commit_id : null,
+    submittedReviewState: typeof submittedReview?.state === "string" ? submittedReview.state.toUpperCase() : null,
+  };
+}
+async function readLocalState(pathname) {
+  if (!pathname) return {};
+  let text;
+  try { text = await readFile(pathname, "utf8"); }
+  catch (error) { if (error && error.code === "ENOENT") return {}; throw error; }
+  const parsed = parseJsonText(text);
+  if (!parsed || typeof parsed !== "object") throw new Error("Local state file must contain a JSON object");
+  return parsed;
+}
+export async function autoDetectReviewerSnapshot(
+  { repo, pr, reviewerLogin, reviewRequestedOverride, localStatePath }, deps,
+) {
+  const prView = await fetchPrView({ repo, pr }, deps);
+  if (prView === null) return normalizeReviewerSnapshot({ prExists: false, reviewerLogin });
+  let effectiveReviewerLogin = reviewerLogin;
+  if (effectiveReviewerLogin === undefined) {
+    try {
+      const reviewersPayload = await runGhJson(["api", `repos/${repo}/pulls/${pr}/requested_reviewers`], deps);
+      const users = Array.isArray(reviewersPayload?.users) ? reviewersPayload.users : [];
+      const humanReviewers = users.filter((user) => {
+        const login = typeof user?.login === "string" ? user.login : "";
+        return login.length > 0 && login !== "copilot-pull-request-reviewer";
+      });
+      if (humanReviewers.length === 1) {
+        effectiveReviewerLogin = humanReviewers[0].login;
+      }
+    } catch {
+    }
+  }
+  const localState = await readLocalState(localStatePath);
+  const prState = typeof prView.state === "string" ? prView.state.toUpperCase() : "OPEN";
+  const prMerged = prState === "MERGED";
+  const prClosed = prState === "CLOSED";
+  if (prMerged || prClosed) {
+    return normalizeReviewerSnapshot({ ...localState, prExists: true, prNumber: typeof prView.number === "number" ? prView.number : pr, prMerged, prClosed, prHeadSha: typeof prView.headRefOid === "string" ? prView.headRefOid : null, reviewerLogin: effectiveReviewerLogin });
+  }
+  const reviewRequested = await fetchReviewRequested({ repo, pr, reviewerLogin: effectiveReviewerLogin, reviewRequestedOverride }, deps);
+  const reviewState = await fetchReviewState({ repo, pr, reviewerLogin: effectiveReviewerLogin }, deps);
+  return normalizeReviewerSnapshot({ ...localState, prExists: true, prNumber: typeof prView.number === "number" ? prView.number : pr, prDraft: Boolean(prView.isDraft), prMerged: false, prClosed: false, prHeadSha: typeof prView.headRefOid === "string" ? prView.headRefOid : null, reviewerLogin: effectiveReviewerLogin, reviewRequested, ...reviewState });
+}
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+) {
+  const options = parseDetectReviewerCliArgs(argv);
+  if (options.help) { stdout.write(HELP); return; }
+  let snapshot;
+  if (options.inputPath) {
+    const text = await readFile(options.inputPath, "utf8");
+    snapshot = normalizeReviewerSnapshot(parseJsonText(text));
+  } else {
+    snapshot = await autoDetectReviewerSnapshot(options, { env, ghCommand });
+  }
+  const interpretation = interpretReviewerLoopState(snapshot);
+  stdout.write(`${JSON.stringify({ ok: true, snapshot, state: interpretation.state, allowedTransitions: interpretation.allowedTransitions, nextAction: interpretation.nextAction })}\n`);
+}
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });
+}

package/scripts/loop/detect-stale-runner.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  detectStaleRunner,
+  STALE_RUNNER_ERROR,
+} from "./_stale-runner-detection.mjs";
+const USAGE = `Usage: detect-stale-runner.mjs --repo <owner/name> --pr <number>
+Detect whether the active runner for a PR is stale or has received an exit
+signal. Fails closed with status "stale_runner" or "exit_signal_recorded" so
+the pre-merge guard can refuse to proceed.
+Required:
+  --repo <owner/name>   Repository slug (e.g. owner/repo)
+  --pr <number>         Pull request number
+Optional:
+  --stale-runner-max-age-ms <ms>
+                        Override the staleness threshold (default 30 minutes,
+                        or $PI_DEV_LOOP_STALE_RUNNER_MAX_AGE_MS).
+  --run-id <id>         Override the active run id (default: read from
+                        PI_SUBAGENT_RUN_ID). When supplied, the detector
+                        additionally verifies the current run id is still
+                        the active owner.
+Output (stdout, JSON; always includes staleRunnerCheck):
+  {
+    "ok": true,
+    "repo": "owner/repo",
+    "pr": 17,
+    "status": "fresh_runner",
+    "activeRun": { "runId": "...", "claimedAt": "...", "updatedAt": "..." },
+    "staleRunnerCheck": {
+      "ok": true,
+      "failures": []
+    }
+  }
+  or on failure:
+  {
+    "ok": false,
+    "error": "stale_runner" | "exit_signal_recorded",
+    "message": "...",
+    "staleRunnerCheck": {
+      "ok": false,
+      "failures": ["stale runner: run X claimed N ms ago, last updated M ms ago (max age K ms)"]
+    }
+  }
+Exit codes:
+  0  Success / fresh runner / no owner record
+  1  Argument error or stale/exit-signal condition detected`.trim();
+const parseError = buildParseError(USAGE);
+function parseCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    staleRunnerMaxAgeMs: undefined,
+    runId: undefined,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+      continue;
+    }
+    if (token === "--stale-runner-max-age-ms") {
+      const raw = requireOptionValue(args, "--stale-runner-max-age-ms", parseError).trim();
+      const parsed = Number(raw);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw parseError(`--stale-runner-max-age-ms must be a positive integer (ms), got: ${raw}`);
+      }
+      options.staleRunnerMaxAgeMs = Math.floor(parsed);
+      continue;
+    }
+    if (token === "--run-id") {
+      options.runId = requireOptionValue(args, "--run-id", parseError).trim();
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("detect-stale-runner 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;
+}
+function resolveRunId(explicitRunId, env) {
+  if (typeof explicitRunId === "string" && explicitRunId.trim().length > 0) {
+    return explicitRunId.trim();
+  }
+  if (typeof env?.PI_SUBAGENT_RUN_ID === "string" && env.PI_SUBAGENT_RUN_ID.trim().length > 0) {
+    return env.PI_SUBAGENT_RUN_ID.trim();
+  }
+  return null;
+}
+function buildStaleRunnerCheck(detection) {
+  if (detection.status === "no_owner_record") {
+    return {
+      ok: true,
+      failures: [],
+    };
+  }
+  if (detection.status === "exit_signal_recorded") {
+    return {
+      ok: false,
+      failures: [`exit signal recorded for run ${detection.activeRun?.runId ?? "unknown"}: refuse to merge`],
+    };
+  }
+  if (detection.status === "stale_runner") {
+    return {
+      ok: false,
+      failures: [
+        `stale runner: run ${detection.staleRunner.runId} claimed ${detection.staleRunner.claimedAgeMs}ms ago, last updated ${detection.staleRunner.updatedAgeMs}ms ago (max age ${detection.staleRunner.maxAgeMs}ms)`,
+      ],
+    };
+  }
+  return { ok: true, failures: [] };
+}
+export async function runDetectStaleRunner(options, { env = process.env, cwd = process.cwd() } = {}) {
+  const detection = await detectStaleRunner({
+    repo: options.repo,
+    pr: options.pr,
+    maxAgeMs: options.staleRunnerMaxAgeMs,
+    cwd,
+  });
+  const explicitRunId = resolveRunId(options.runId, env);
+  const ownershipLost = explicitRunId !== null
+    && detection.activeRun !== null
+    && detection.activeRun.runId !== explicitRunId;
+  const ownershipMissing = explicitRunId !== null && detection.activeRun === null;
+  const staleRunnerCheck = buildStaleRunnerCheck(detection);
+  if (ownershipMissing) {
+    return {
+      ok: false,
+      error: "ownership_lost",
+      repo: options.repo.trim().toLowerCase(),
+      pr: options.pr,
+      status: "ownership_lost",
+      activeRun: null,
+      runId: explicitRunId,
+      exitSignals: [],
+      filePath: detection.filePath,
+      maxAgeMs: detection.maxAgeMs,
+      message: `Stale-runner check: run ${explicitRunId} is no longer the active owner of ${options.repo}#${options.pr}; no active owner record exists.`,
+      staleRunnerCheck: {
+        ok: false,
+        failures: [`ownership_lost: no active owner record exists; run ${explicitRunId} is not the owner`],
+      },
+    };
+  }
+  if (ownershipLost) {
+    return {
+      ok: false,
+      error: "ownership_lost",
+      repo: options.repo.trim().toLowerCase(),
+      pr: options.pr,
+      status: "ownership_lost",
+      activeRun: detection.activeRun,
+      runId: explicitRunId,
+      exitSignals: detection.exitSignal?.signals ?? [],
+      filePath: detection.filePath,
+      maxAgeMs: detection.maxAgeMs,
+      message: `Stale-runner check: run ${explicitRunId} is no longer the active owner of ${options.repo}#${options.pr}; current owner is ${detection.activeRun?.runId}.`,
+      staleRunnerCheck: {
+        ok: false,
+        failures: [`ownership_lost: active owner is ${detection.activeRun?.runId ?? "unknown"}, not ${explicitRunId}`],
+      },
+    };
+  }
+  if (detection.status === "exit_signal_recorded") {
+    return {
+      ok: false,
+      error: STALE_RUNNER_ERROR.EXIT_SIGNAL_RECORDED,
+      repo: options.repo.trim().toLowerCase(),
+      pr: options.pr,
+      status: "exit_signal_recorded",
+      activeRun: detection.activeRun,
+      runId: explicitRunId,
+      exitSignals: detection.exitSignal?.signals ?? [],
+      filePath: detection.filePath,
+      maxAgeMs: detection.maxAgeMs,
+      message: detection.message,
+      staleRunnerCheck,
+    };
+  }
+  if (detection.status === "stale_runner") {
+    return {
+      ok: false,
+      error: STALE_RUNNER_ERROR.STALE_RUNNER,
+      repo: options.repo.trim().toLowerCase(),
+      pr: options.pr,
+      status: "stale_runner",
+      activeRun: detection.activeRun,
+      runId: explicitRunId,
+      exitSignals: [],
+      staleRunner: detection.staleRunner,
+      filePath: detection.filePath,
+      maxAgeMs: detection.maxAgeMs,
+      message: detection.message,
+      staleRunnerCheck,
+    };
+  }
+  return {
+    ok: true,
+    repo: options.repo.trim().toLowerCase(),
+    pr: options.pr,
+    status: detection.status,
+    activeRun: detection.activeRun,
+    runId: explicitRunId,
+    exitSignals: [],
+    filePath: detection.filePath,
+    maxAgeMs: detection.maxAgeMs,
+    staleRunnerCheck,
+  };
+}
+async function main() {
+  try {
+    const options = parseCliArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log(USAGE);
+      return;
+    }
+    const result = await runDetectStaleRunner(options, { env: process.env });
+    if (!result.ok) {
+      console.error(JSON.stringify(result));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    const payload = formatCliError(error, { usage: USAGE });
+    console.error(JSON.stringify(payload));
+    process.exitCode = 1;
+  }
+}
+if (isDirectCliRun(import.meta.url)) {
+  await main();
+}

package/scripts/loop/detect-tracker-first-loop-state.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { interpretTrackerLoopState } from "@dev-loops/core/loop/tracker-first-loop-state";
+function showHelp() {
+  process.stdout.write(`Usage: detect-tracker-first-loop-state.mjs --repo <owner/name> --issue <number>
+Detect tracker-first loop state for a GitHub issue.
+Options:
+  --repo <owner/name>   GitHub repository slug
+  --issue <number>      GitHub issue number
+  --help, -h            Show this help
+Exit codes:
+  0   Success
+  1   Error
+`);
+  process.exit(0);
+}
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = { repo: null, issue: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") {
+      showHelp();
+    }
+    if (args[i] === "--repo" && i + 1 < args.length) opts.repo = args[++i];
+    else if (args[i] === "--issue" && i + 1 < args.length) opts.issue = args[++i];
+  }
+  return opts;
+}
+async function main() {
+  const opts = parseArgs();
+  if (!opts.repo || !opts.issue) {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: "--repo and --issue required" }) + "\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let rawState = "";
+  let prContext = null;
+  try {
+    const issueJson = execFileSync(
+      "gh",
+      ["issue", "view", String(opts.issue), "--repo", opts.repo, "--json", "state,title", "--jq", ".state"],
+      { encoding: "utf8" }
+    ).trim();
+    rawState = issueJson;
+    try {
+      const prJson = execFileSync(
+        "gh",
+        ["pr", "list", "--repo", opts.repo, "--search", `${opts.issue} in:body`, "--state", "open", "--json", "number,state,headRefName", "--jq", ".[0]"],
+        { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
+      ).trim();
+      if (prJson) prContext = JSON.parse(prJson);
+    } catch {
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: `gh command failed: ${message}` }) + "\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const result = interpretTrackerLoopState({ trackerState: rawState, prContext });
+  process.stdout.write(JSON.stringify(result) + "\n");
+}
+const isDirectRun =
+  process.argv[1] && process.argv[1].includes("detect-tracker-first-loop-state.mjs");
+if (isDirectRun) {
+  main().catch((err) => {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+  });
+}
+export { main };

package/scripts/loop/detect-tracker-pr-state.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildParseError, formatCliError, parseJsonText } from "../_core-helpers.mjs";
+import { requireOptionValue } from "../_cli-primitives.mjs";
+import {
+  interpretTrackerPrState,
+  normalizeTrackerPrSnapshot,
+} from "@dev-loops/core/loop/tracker-pr-state";
+const USAGE = `Usage:
+  detect-tracker-pr-state.mjs --input <path>
+Interpret a pre-built tracker-PR snapshot JSON and emit the current lifecycle
+state, allowed transitions, recommended next action, and canonical reverse-sync
+action.
+Required:
+  --input <path>   Path to a JSON file containing the tracker-PR snapshot.
+Snapshot schema (all fields optional; unknown fields are ignored):
+  trackerItemExists  boolean     Whether a tracker work item was found
+  trackerItemId      string|null Opaque tracker item ID (e.g. "PROJ-123") when present
+  prExists           boolean     Whether a GitHub PR exists for this item
+  prNumber           number|null PR number if known; prNumber with prExists=false is contradictory
+  prDraft            boolean     Whether the PR is in draft state
+  prMerged           boolean     Whether the PR has been merged
+  prClosed           boolean     Whether the PR is closed on GitHub (merged PRs are also closed)
+  prHeadSha          string|null Current PR head SHA
+  draftGateCommentVisible boolean Whether the draft-gate comment is visible on the PR thread
+  draftGateCommentHeadSha string|null Head SHA encoded in the draft-gate comment
+  draftGateCommentVerdict string|null Draft-gate verdict: clean|findings_present|blocked
+This snapshot intentionally excludes tracker-native workflow readiness/blocking
+state. Callers must combine tracker-owned workflow state separately when
+interpreting whether opening a PR is appropriate.
+Unlike the Copilot/reviewer loop snapshots, this tracker contract uses prClosed
+for the raw GitHub closed state. Merged PRs therefore set both prMerged=true
+and prClosed=true, while pr_closed_unmerged is derived from
+prClosed && !prMerged.
+Output (stdout, JSON):
+  {
+    "ok": true,
+    "snapshot": { ... },
+    "state": "...",
+    "allowedTransitions": [...],
+    "nextAction": "...",
+    "reverseSyncAction": "..."
+  }
+Error output (stderr, JSON):
+  Argument/usage errors: { "ok": false, "error": "...", "usage": "..." }
+  Runtime failures:      { "ok": false, "error": "..." }
+Exit codes:
+  0  Success
+  1  Argument error or runtime failure`.trim();
+const parseError = buildParseError(USAGE);
+export function parseDetectTrackerPrCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    inputPath: undefined,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--input") {
+      options.inputPath = requireOptionValue(args, "--input", parseError);
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (options.inputPath === undefined) {
+    throw parseError("--input <path> is required");
+  }
+  return options;
+}
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdout = process.stdout,
+  } = {},
+) {
+  const options = parseDetectTrackerPrCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const text = await readFile(path.resolve(options.inputPath), "utf8");
+  const raw = parseJsonText(text);
+  const snapshot = normalizeTrackerPrSnapshot(raw);
+  const { state, allowedTransitions, nextAction, reverseSyncAction } = interpretTrackerPrState(snapshot);
+  stdout.write(
+    `${JSON.stringify({ ok: true, snapshot, state, allowedTransitions, nextAction, reverseSyncAction })}\n`,
+  );
+}
+const isDirectRun =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectRun) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}