dev-loops 0.2.7 → 0.4.0

package/scripts/github/probe-ci-status.mjs

@@ -0,0 +1,468 @@
+#!/usr/bin/env node
+import { setTimeout as delay } from "node:timers/promises";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  summarizeHeadScopedCheckRunsSignal,
+  normalizeHeadScopedCommitStatus,
+  normalizeHeadScopedCiContract,
+} from "@dev-loops/core/loop/copilot-ci-status";
+import {
+  DEFAULT_POLL_INTERVAL_MS,
+  COPILOT_REVIEW_WAIT_TIMEOUT_MS,
+} from "@dev-loops/core/loop/policy-constants";
+
+/** Maximum interval between heartbeat outputs during watch delays.
+ *  Must be shorter than pi-subagents default needsAttentionAfterMs (60s). */
+const WATCH_HEARTBEAT_MS = 45_000; // 45 seconds
+const USAGE = `Usage: probe-ci-status.mjs --repo <owner/name> --pr <number> [--timeout-ms <n>] [--poll-interval-ms <n>]
+Block-wait on a PR's combined CI check/status state (GitHub Actions + CircleCI +
+any external commit-status / check-run) for the current head SHA, until terminal
+or timeout. Provider-agnostic — unlike \`gh run watch\`, which is Actions-only.
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --pr <number>                 Pull request number
+Optional:
+  --timeout-ms <n>              Total watch budget (default 1800000; 0 = single check, no wait)
+  --poll-interval-ms <n>        Delay between polls (default 60000)
+Output (stdout, JSON):
+  { "ok": true, "status": "success"|"failure"|"pending"|"timeout"|"changed",
+    "settled": bool, "ciStatus": "success"|"failure"|"pending"|"none",
+    "failedChecks": [{ "name": "...", "conclusion"?: "..." }], "headSha": "...", "attempts": N }
+Statuses:
+  success    Combined CI is green (or no checks present — see no-checks rule)
+  failure    At least one check/status failed (failedChecks populated)
+  pending    Timed-out single check (timeout-ms 0) found CI still in flight
+  timeout    Watch budget elapsed while CI was still pending
+  changed    Head SHA advanced during the wait; caller must re-baseline
+No-checks rule (grace, race-safe):
+  Zero check-runs AND zero commit-statuses is NOT settled green on the first
+  poll — a provider (CircleCI/Actions) may post its first check a beat after a
+  fresh push, and settling early would report green before any CI ran. Instead
+  the watcher awaits 2 consecutive zero-check polls (a ~2-poll-interval grace)
+  before settling success (ciStatus "none"): a genuinely check-less repo still
+  settles instead of hanging, while a late first check is awaited. If the PR's
+  statusCheckRollup lists EXPECTED checks while the APIs still report zero, that
+  is pending (checks expected, not yet reported), never none. A gh-api / parse
+  failure is never treated as empty — it forces pending so the watch keeps
+  polling, and a persistent error settles as "timeout", never fabricated green.
+  (timeout-ms 0 single check has no waiting budget, so a clean no-checks head
+  settles immediately.)
+Diagnostic output (stderr):
+  { "ok": true, "type": "watch_heartbeat", "elapsedMs": N, "totalBudgetMs": N, "poll": N, "maxPolls": N }
+  { "ok": false, "error": "...", "usage"?: "..." }
+Exit codes:
+  0  Success
+  1  Argument error or gh failure`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseCiWatchCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "timeout-ms": { type: "string" },
+      "poll-interval-ms": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs: COPILOT_REVIEW_WAIT_TIMEOUT_MS,
+  };
+  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-ms") {
+      options.timeoutMs = parseNonNegativeMs(requireTokenValue(token, parseError), "--timeout-ms");
+      continue;
+    }
+    if (token.name === "poll-interval-ms") {
+      options.pollIntervalMs = parsePositiveMs(requireTokenValue(token, parseError), "--poll-interval-ms");
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Watching CI 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 parseNonNegativeMs(raw, flag) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw parseError(`${flag} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function parsePositiveMs(raw, flag) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw parseError(`${flag} must be a positive integer`);
+  }
+  return value;
+}
+
+async function ghJson(ghCommand, args, env) {
+  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>"}`);
+  }
+}
+
+function extractPrVisibleCheckNames(statusCheckRollup) {
+  if (!Array.isArray(statusCheckRollup)) return [];
+  return statusCheckRollup
+    .map((entry) => entry?.name || entry?.context)
+    .filter((name) => typeof name === "string" && name.length > 0);
+}
+
+// Failing commit-status contexts (state "failure"/"error"), e.g. CircleCI which
+// reports through the status API rather than as check-runs.
+function extractFailedStatusContexts(statuses) {
+  if (!Array.isArray(statuses)) return [];
+  return statuses
+    .filter((s) => {
+      const state = typeof s?.state === "string" ? s.state.toLowerCase() : "";
+      return state === "failure" || state === "error";
+    })
+    .map((s) => ({
+      name: typeof s?.context === "string" && s.context.length > 0 ? s.context : "unknown",
+      conclusion: typeof s?.state === "string" ? s.state.toLowerCase() : "",
+    }));
+}
+
+async function fetchPrHeadSha({ repo, pr }, { env, ghCommand }) {
+  const payload = await ghJson(
+    ghCommand,
+    ["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,statusCheckRollup"],
+    env,
+  );
+  const headSha = typeof payload.headRefOid === "string" ? payload.headRefOid.trim() : "";
+  if (headSha.length === 0) {
+    throw new Error("Missing required PR facts: headRefOid");
+  }
+  return { headSha, prVisibleCheckNames: extractPrVisibleCheckNames(payload.statusCheckRollup) };
+}
+
+/**
+ * Read the combined check-runs + commit-status state for one head SHA.
+ * Provider-agnostic: covers GitHub Actions, CircleCI, and any external
+ * commit-status / check-run reported against the commit.
+ *
+ * `fetchError` is true when a `gh api` call failed (non-zero exit) or returned
+ * an unparseable / malformed payload. The caller MUST NOT treat a fetchError as
+ * a genuine empty (no-checks) state — a transient API error would otherwise
+ * fabricate green. On fetchError, ciStatus is forced to "pending" so the watch
+ * keeps polling (and a persistent error settles as "timeout", never success).
+ *
+ * @returns {{ ciStatus: "success"|"failure"|"pending"|"none", noChecks: boolean, fetchError: boolean, failedChecks: Array<{ name: string, conclusion?: string }> }}
+ */
+async function fetchHeadCiState({ repo, headSha, prVisibleCheckNames }, { env, ghCommand }) {
+  const [checkRunsResult, statusesResult] = await Promise.all([
+    runChild(ghCommand, ["api", `repos/${repo}/commits/${headSha}/check-runs?per_page=100`], env),
+    runChild(ghCommand, ["api", `repos/${repo}/commits/${headSha}/status?per_page=100`], env),
+  ]);
+
+  let checkRunsSignal = null;
+  let checkRunsCount = 0;
+  let checkRunsError = checkRunsResult.code !== 0;
+  if (checkRunsResult.code === 0) {
+    try {
+      const payload = JSON.parse(checkRunsResult.stdout);
+      if (Array.isArray(payload?.check_runs)) {
+        const visibleSet = prVisibleCheckNames?.length > 0 ? new Set(prVisibleCheckNames) : null;
+        const visibleRuns = visibleSet
+          ? payload.check_runs.filter((run) => !run.name || visibleSet.has(run.name))
+          : payload.check_runs;
+        const visibleSignal = summarizeHeadScopedCheckRunsSignal({ check_runs: visibleRuns });
+        const fullSignal = summarizeHeadScopedCheckRunsSignal(payload);
+        checkRunsSignal = { ...visibleSignal, unsupportedCompleted: fullSignal.unsupportedCompleted };
+        checkRunsCount = payload.check_runs.length;
+      } else {
+        checkRunsError = true; // exit 0 but no check_runs array → malformed payload, not empty
+      }
+    } catch {
+      checkRunsSignal = null;
+      checkRunsError = true;
+    }
+  }
+
+  let commitStatus = null;
+  let statusesCount = 0;
+  let statusFailures = [];
+  let statusesError = statusesResult.code !== 0;
+  if (statusesResult.code === 0) {
+    try {
+      const payload = JSON.parse(statusesResult.stdout);
+      if (Array.isArray(payload?.statuses)) {
+        commitStatus = normalizeHeadScopedCommitStatus(payload);
+        statusesCount = payload.statuses.length;
+        statusFailures = extractFailedStatusContexts(payload.statuses);
+      } else {
+        statusesError = true; // exit 0 but no statuses array → malformed payload, not empty
+      }
+    } catch {
+      commitStatus = null;
+      statusesError = true;
+    }
+  }
+
+  const fetchError = checkRunsError || statusesError;
+  const ciStatus = fetchError
+    ? "pending"
+    : normalizeHeadScopedCiContract({
+        checkRunsStatus: checkRunsSignal?.status ?? "none",
+        commitStatus: commitStatus ?? "none",
+        checkRunsUnsupportedCompleted: checkRunsSignal?.unsupportedCompleted ?? false,
+      }).overallStatus;
+  // Provider-agnostic failure reporting: check-runs failures AND failing
+  // commit-status contexts (e.g. CircleCI reports via the status API with NO
+  // check-runs). Without the status side, a CircleCI failure would surface
+  // ciStatus "failure" with an empty failedChecks.
+  const failedChecks = fetchError
+    ? []
+    : [
+        ...(checkRunsSignal?.failureDetails ?? []).map((name) => ({ name })),
+        ...statusFailures,
+      ];
+  // No-checks: zero check-runs AND zero commit-statuses, observed cleanly (no
+  // fetchError) AND with no PR-visible expected checks. If statusCheckRollup
+  // lists expected checks the providers haven't reported yet, that is pending
+  // (checks expected but not yet posted), not a genuinely check-less head.
+  const noChecks =
+    !fetchError &&
+    checkRunsCount === 0 &&
+    statusesCount === 0 &&
+    !(prVisibleCheckNames?.length > 0);
+  return { ciStatus, noChecks, fetchError, failedChecks };
+}
+
+function buildAttemptBudget(timeoutMs, pollIntervalMs) {
+  if (timeoutMs === 0) {
+    return 1;
+  }
+  // Polls land at t=0, interval, 2*interval, ... so floor(timeout/interval)+1
+  // polls fit inside the budget (the first poll costs no delay).
+  return Math.max(1, Math.floor(timeoutMs / pollIntervalMs) + 1);
+}
+
+// Attempt 1 polls immediately (t=0); attempt N waits (N-1)*pollIntervalMs from
+// the watch start, capped by the total timeout budget.
+function buildPollDelayMs(watchStartedAtMs, timeoutMs, pollIntervalMs, attempt, nowMs) {
+  if (timeoutMs === 0 || attempt <= 1) {
+    return 0;
+  }
+  const scheduledAtMs = watchStartedAtMs + Math.min(timeoutMs, (attempt - 1) * pollIntervalMs);
+  return Math.max(0, scheduledAtMs - nowMs);
+}
+
+function settledResult(state, { settled, status }) {
+  return {
+    ok: true,
+    status,
+    settled,
+    ciStatus: state.ciStatus,
+    failedChecks: state.failedChecks,
+    headSha: state.headSha,
+    attempts: state.attempts,
+  };
+}
+
+/** Consecutive clean zero-check polls required before settling none->success.
+ *  A provider (CircleCI/Actions) may post its first check a beat after the push;
+ *  settling on the FIRST zero-check poll would fabricate green before any CI ran.
+ *  So we await this many consecutive zero-check observations (a grace of ~2 poll
+ *  intervals) before treating a head as genuinely check-less. A repo that truly
+ *  has no CI still settles after the grace instead of hanging to timeout. */
+export const NO_CHECKS_GRACE_POLLS = 2;
+
+/**
+ * Map a head CI state to a terminal watcher status, or null when still in flight.
+ * - failure / success classify immediately (a check is terminal).
+ * - none (zero checks, clean fetch, no expected checks) settles success only
+ *   after NO_CHECKS_GRACE_POLLS consecutive observations (see constant).
+ * - fetchError / expected-but-unreported checks → pending (keep polling).
+ */
+function terminalStatusFor({ ciStatus, noChecks }, consecutiveNoChecks, graceFloor) {
+  if (ciStatus === "failure") return "failure";
+  if (ciStatus === "success") return "success";
+  if (noChecks && consecutiveNoChecks >= graceFloor) return "success";
+  return null;
+}
+
+export async function watchCiStatus(
+  options,
+  {
+    env = process.env,
+    ghCommand = "gh",
+    delayImpl = delay,
+    now = Date.now,
+  } = {},
+) {
+  const { headSha: baselineSha, prVisibleCheckNames } = await fetchPrHeadSha(
+    { repo: options.repo, pr: options.pr },
+    { env, ghCommand },
+  );
+  const attemptBudget = buildAttemptBudget(options.timeoutMs, options.pollIntervalMs);
+  const watchStartedAtMs = now();
+  // timeout-ms 0 is a single live check with no waiting budget: there is no
+  // grace window to await a late first check, so a clean no-checks head settles
+  // immediately (preserves single-check semantics). A real watch awaits the grace.
+  const graceFloor = options.timeoutMs === 0 ? 1 : NO_CHECKS_GRACE_POLLS;
+  let consecutiveNoChecks = 0;
+  for (let attempt = 1; attempt <= attemptBudget; attempt += 1) {
+    // Attempt 1 polls at t=0 (CI may already be terminal); sleep only between
+    // subsequent polls so the watcher never burns a full interval before its
+    // first observation.
+    if (attempt > 1) {
+      const pollDelayMs = buildPollDelayMs(
+        watchStartedAtMs,
+        options.timeoutMs,
+        options.pollIntervalMs,
+        attempt,
+        now(),
+      );
+      let remainingMs = pollDelayMs;
+      while (remainingMs > 0) {
+        const chunkMs = Math.min(WATCH_HEARTBEAT_MS, remainingMs);
+        await delayImpl(chunkMs);
+        remainingMs -= chunkMs;
+        if (remainingMs > 0) {
+          process.stderr.write(
+            JSON.stringify({
+              ok: true,
+              type: "watch_heartbeat",
+              elapsedMs: now() - watchStartedAtMs,
+              totalBudgetMs: options.timeoutMs,
+              poll: attempt,
+              maxPolls: attemptBudget,
+            }) + "\n",
+          );
+        }
+      }
+    }
+    // Re-resolve the head SHA every poll: a new push must short-circuit to
+    // "changed" so the caller re-baselines instead of waiting on a stale head.
+    const { headSha: currentSha, prVisibleCheckNames: currentNames } = await fetchPrHeadSha(
+      { repo: options.repo, pr: options.pr },
+      { env, ghCommand },
+    );
+    if (currentSha !== baselineSha) {
+      const changedState = await fetchHeadCiState(
+        { repo: options.repo, headSha: currentSha, prVisibleCheckNames: currentNames },
+        { env, ghCommand },
+      );
+      return settledResult({ ...changedState, headSha: currentSha, attempts: attempt }, {
+        settled: false,
+        status: "changed",
+      });
+    }
+    // Use the per-poll currentNames (not the baseline): statusCheckRollup may
+    // start empty and later populate expected checks for the SAME head SHA. With
+    // the stale baseline names this head would look check-less and wrongly settle
+    // none->success; currentNames keeps it pending until the checks report.
+    const state = await fetchHeadCiState(
+      { repo: options.repo, headSha: currentSha, prVisibleCheckNames: currentNames },
+      { env, ghCommand },
+    );
+    consecutiveNoChecks = state.noChecks ? consecutiveNoChecks + 1 : 0;
+    const terminal = terminalStatusFor(state, consecutiveNoChecks, graceFloor);
+    if (terminal !== null) {
+      return settledResult({ ...state, headSha: currentSha, attempts: attempt }, {
+        settled: true,
+        status: terminal,
+      });
+    }
+  }
+  // Budget exhausted while still pending. Re-resolve the head before the final
+  // fetch: the head may have advanced during the last delay (short-circuit to
+  // "changed" so the caller re-baselines), and the rollup may have populated
+  // expected checks for the same SHA (use the current names, not baseline).
+  // A zero-timeout single check reports the live "pending" state; a real watch
+  // budget reports "timeout".
+  const { headSha: finalSha, prVisibleCheckNames: finalNames } = await fetchPrHeadSha(
+    { repo: options.repo, pr: options.pr },
+    { env, ghCommand },
+  );
+  if (finalSha !== baselineSha) {
+    const changedState = await fetchHeadCiState(
+      { repo: options.repo, headSha: finalSha, prVisibleCheckNames: finalNames },
+      { env, ghCommand },
+    );
+    return settledResult({ ...changedState, headSha: finalSha, attempts: attemptBudget }, {
+      settled: false,
+      status: "changed",
+    });
+  }
+  const finalState = await fetchHeadCiState(
+    { repo: options.repo, headSha: finalSha, prVisibleCheckNames: finalNames },
+    { env, ghCommand },
+  );
+  return settledResult({ ...finalState, headSha: finalSha, attempts: attemptBudget }, {
+    settled: false,
+    status: options.timeoutMs === 0 ? "pending" : "timeout",
+  });
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdout = process.stdout,
+    env = process.env,
+    ghCommand = "gh",
+  } = {},
+) {
+  const options = parseCiWatchCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const result = await watchCiStatus(options, { env, ghCommand });
+  stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/github/reconcile-draft-gate.mjs

@@ -124,7 +124,7 @@ async function resolvePrNodeId({ repo, pr }, { env, ghCommand }) {
   }
   return { id: prData.id, isDraft: prData.isDraft };
 }
-async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
+export async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
   const resolvedPr = await resolvePrNodeId({ repo, pr }, { env, ghCommand });
   if (resolvedPr.isDraft === true) {
     return {
@@ -154,7 +154,7 @@ async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
     alreadyDraft: false,
   };
 }
-async function markPrReady({ repo, pr }, { env, ghCommand }) {
+export async function markPrReady({ repo, pr }, { env, ghCommand }) {
   const result = await runChild(ghCommand, [
     "pr", "ready", String(pr),
     "--repo", repo,

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

@@ -6,7 +6,9 @@ import {
   isCopilotLogin,
   isDirectCliRun,
   parseReviewThreads,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
+  summarizeGateReviewComments,
 } from "../_core-helpers.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
@@ -28,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",
@@ -121,7 +123,7 @@ function parseRequestedReviewersPayload(text) {
     requested: users.some((user) => isCopilotLogin(user?.login)),
   };
 }
-function parseReviewsPayload(text) {
+function parseReviewsPayload(text, { draftGateResetAtMs = null } = {}) {
   let payload;
   try {
     payload = JSON.parse(text);
@@ -131,7 +133,10 @@ function parseReviewsPayload(text) {
   const headSha = typeof payload?.headRefOid === "string" && payload.headRefOid.trim().length > 0
     ? payload.headRefOid.trim()
     : null;
-  const reviewSummary = summarizeCopilotReviews(payload?.reviews, { headSha });
+  // Apply the draft-gate round reset so the completed round count matches what
+  // detect-pr-gate-coordination-state computes (#896): when the draft gate has
+  // re-passed clean on an earlier head, only reviews after that re-pass count.
+  const reviewSummary = summarizeCopilotReviews(payload?.reviews, { headSha, draftGateResetAtMs });
   return {
     prData: payload,
     headSha,
@@ -166,6 +171,51 @@ async function fetchCopilotReviewIds({ repo, pr }, { env = process.env, ghComman
   }
   return parseReviewsPayload(result.stdout);
 }
+
+// Re-derive the completed Copilot round count with the draft-gate round reset
+// applied, mirroring detect-pr-gate-coordination-state so both scripts agree on the
+// completed count and therefore on round-cap-reached (#896). A clean draft_gate
+// re-pass on an earlier head resets the count, so post-reset reviews must not be
+// counted toward the cap.
+//
+// Queried lazily — only when the raw (un-reset) count has already hit the cap — so
+// the common (under-cap) request path keeps its existing gh-call contract and adds
+// no API round-trip. Uses a single issue-comments fetch (the same source the gate
+// detector uses for the latest clean draft_gate marker), not the full checkpoint-
+// evidence pipeline, to keep the added surface minimal. Best-effort: a fetch failure
+// falls back to the raw count, so the cap is never silently disabled.
+async function resolveDraftGateAdjustedRounds(options, { env = process.env, ghCommand = "gh" } = {}, before) {
+  try {
+    const currentHeadSha = typeof before?.prData?.headRefOid === "string" && before.prData.headRefOid.trim().length > 0
+      ? before.prData.headRefOid.trim()
+      : null;
+    const result = await runChild(
+      ghCommand,
+      ["api", "--paginate", "--slurp", `repos/${options.repo}/issues/${options.pr}/comments?per_page=100`],
+      env,
+    );
+    if (result.code !== 0) {
+      return before.completedCopilotReviewRounds ?? 0;
+    }
+    let comments;
+    try {
+      const payload = JSON.parse(result.stdout);
+      comments = Array.isArray(payload) ? payload.flat() : [];
+    } catch {
+      return before.completedCopilotReviewRounds ?? 0;
+    }
+    const gateSummary = summarizeGateReviewComments(comments);
+    const draftGateResetAtMs = resolveDraftGateRoundResetMs({ draftGate: gateSummary?.draft_gate, currentHeadSha });
+    if (draftGateResetAtMs == null) {
+      return before.completedCopilotReviewRounds ?? 0;
+    }
+    const adjusted = parseReviewsPayload(JSON.stringify(before.prData ?? {}), { draftGateResetAtMs });
+    return adjusted.completedCopilotReviewRounds ?? 0;
+  } catch {
+    return before.completedCopilotReviewRounds ?? 0;
+  }
+}
+
 async function fetchCopilotReviewState(options, runtime) {
   const requestedReviewers = await fetchRequestedReviewers(options, runtime);
   const reviews = await fetchCopilotReviewIds(options, runtime);
@@ -212,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`);
     }
@@ -252,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`);
     }
@@ -434,7 +484,18 @@ export async function performCopilotReviewRequest(options, { env = process.env,
     }
   } catch {
   }
-  if ((before.completedCopilotReviewRounds ?? 0) >= maxRounds
+  // Reconcile the completed-round count with detect-pr-gate-coordination-state (#896):
+  // when the raw count has reached the cap, re-derive it with the draft-gate round
+  // reset applied. A clean draft_gate re-pass on an earlier head resets the count, so
+  // a post-reset PR that detect reports as under-cap must NOT be refused here as
+  // cap-reached. Only query checkpoint evidence on this (at/over-cap) path.
+  let completedRounds = before.completedCopilotReviewRounds ?? 0;
+  if (completedRounds >= maxRounds
+      && !before.requested
+      && !before.hasPendingReviewOnCurrentHead) {
+    completedRounds = await resolveDraftGateAdjustedRounds(options, { env, ghCommand }, before);
+  }
+  if (completedRounds >= maxRounds
       && !before.requested
       && !before.hasPendingReviewOnCurrentHead) {
     if (!options.forceRerequestReview) {
@@ -451,9 +512,9 @@ export async function performCopilotReviewRequest(options, { env = process.env,
           repo: options.repo,
           pr: options.pr,
           reviewer: "Copilot",
-          completedRounds: before.completedCopilotReviewRounds,
+          completedRounds,
           maxRounds,
-          detail: `Round cap of ${maxRounds} reached with ${before.completedCopilotReviewRounds} completed rounds. No further re-requests will be made.`,
+          detail: `Round cap of ${maxRounds} reached with ${completedRounds} completed rounds. No further re-requests will be made.`,
         };
       }
     }
@@ -471,8 +532,8 @@ export async function performCopilotReviewRequest(options, { env = process.env,
         repo: options.repo,
         pr: options.pr,
         reviewer: "Copilot",
-        detail: `Round cap of ${maxRounds} reached with ${before.completedCopilotReviewRounds} completed rounds. --force-rerequest-review was supplied but commit SHA data is unavailable, so change-since-last-review could not be evaluated.`,
-        completedRounds: before.completedCopilotReviewRounds,
+        detail: `Round cap of ${maxRounds} reached with ${completedRounds} completed rounds. --force-rerequest-review was supplied but commit SHA data is unavailable, so change-since-last-review could not be evaluated.`,
+        completedRounds,
         maxRounds,
       };
     }
@@ -484,7 +545,7 @@ export async function performCopilotReviewRequest(options, { env = process.env,
         pr: options.pr,
         reviewer: "Copilot",
         detail: "No changes since last Copilot review. --force-rerequest-review requires new commits on the PR head.",
-        completedRounds: before.completedCopilotReviewRounds,
+        completedRounds,
         maxRounds,
       };
     }