@dev-loops/core 1.0.0-rc.3 → 1.0.0-rc.5

package/src/config/extension-defaults.yaml

@@ -125,19 +125,52 @@ gates:
           Scan PR comments for unresolved issues before declaring the gate clean. Check all PR comments and review threads for: - Comments from the repository owner or collaborators that point out
             implementation bugs, logic errors, contract violations, or security
             issues
-          - Unresolved review threads that raise implementation concerns Flag any unresolved comment that identifies a concrete implementation problem as a blocking finding (severity: must-fix or worth-fixing-now). Do not flag: - Resolved threads - Style nits, formatting suggestions, or cosmetic feedback - Comments from non-collaborators or bots - Outdated comments that were already addressed in a later commit If no unresolved implementation concerns exist, return clean.
+          - Unresolved review threads that raise implementation concerns Flag any unresolved comment that identifies a concrete implementation problem as a blocking finding (severity: high or medium). Do not flag: - Resolved threads - Style nits, formatting suggestions, or cosmetic feedback - Comments from non-collaborators or bots - Outdated comments that were already addressed in a later commit If no unresolved implementation concerns exist, return clean.
       - contradiction-lens
       - code-conformance
       - semantic-drift
       - name: pr-description
         mandatory: true
         persona: review
-        prompt: 'Review the PR description for completeness, contract fitness, and checkbox formatting before this PR is marked ready for review. The PR body is the implementation contract — it must have: - A Summary section explaining what changed and why - A Scope and context section defining the boundary of the change - An Acceptance criteria section with the linked issue acceptance criteria - A Definition of done section - A Non-goals section - A Validation command section describing exactly how to verify the change - The "Closes #N" line must match the linked issue; flag changes that alter or remove the operator-intended close target Checkboxes (`- [ ]` / `- [x]`, or `* [ ]` / `* [x]`) must appear inside genuine Markdown list items. Flag any checkbox marker used outside a list item (including table cells) as a worth-fixing-now finding. Flag any checkbox marker wrapped in backticks (e.g. `` `[x]` ``) as a worth-fixing-now finding. Flag PRs where the body is a single sentence or lacks any of these sections. Do not block on formatting preferences other than checkbox correctness.'
+        prompt: 'Review the PR description for completeness, contract fitness, and checkbox formatting before this PR is marked ready for review. The PR body is the implementation contract — it must have: - A Summary section explaining what changed and why - A Scope and context section defining the boundary of the change - An Acceptance criteria section with the linked issue acceptance criteria - A Definition of done section - A Non-goals section - A Validation command section describing exactly how to verify the change - The "Closes #N" line must match the linked issue; flag changes that alter or remove the operator-intended close target Checkboxes (`- [ ]` / `- [x]`, or `* [ ]` / `* [x]`) must appear inside genuine Markdown list items. Flag any checkbox marker used outside a list item (including table cells) as a medium finding. Flag any checkbox marker wrapped in backticks (e.g. `` `[x]` ``) as a medium finding. Flag PRs where the body is a single sentence or lacks any of these sections. Do not block on formatting preferences other than checkbox correctness.'
     required: true
     requireCi: true
-  # Gate findings comments live ON the PR (the local-first spec-of-record /
-  # human-review surface), so they are evidence, not tracker noise — keep them on.
-  postFindingsComments: true
+    # Diff-class angle tiers (opt-in, ordered, first match wins). A matching tier
+    # replaces this gate's resolved angle set with its own for that round's
+    # fan-out (mandatory angles are always kept); it never changes execution
+    # mode. A tiered round is still a normal fanout_fanin round:
+    #   tiers:
+    #     - name: docs-only
+    #       match: { kinds: [docs] }
+    #       angles: [pr-description, link-check, gate-evidence]
+  # The gate round's verdict review already carries every finding, so the
+  # consolidated findings comment is opt-in duplication — keep it off.
+  postFindingsComments: false
+  # Grouped fan-out dispatch (AC6, default mode — see resolveFanoutGroups):
+  # angles that read the same surface batch onto one reviewer. Angles not
+  # named below join the auto-chunked leftover pool. Set `mode: per-angle`
+  # to restore full one-reviewer-per-angle fan-out repo-wide (bypasses
+  # maxAnglesPerGroup: 1 honors configured groups; the two match in unit size only when no configured multi-angle group matches). `gate:full` forces the full angle set but no
+  # longer restores per-angle dispatch (ADR 0047 superseded by 0048) — it
+  # dispatches grouped.
+  #
+  # Two orthogonal dispatch bounds (#1601):
+  #   maxAnglesPerGroup (N, default 3, min 1) — leftover ungrouped angles
+  #     auto-chunk into dispatch units of ≤N instead of singletons.
+  #   maxConcurrent (M, default 4, min 1) — at most M dispatch units per wave.
+  # Both count dispatch units (groups), not angles.
+  fanout:
+    maxAnglesPerGroup: 3
+    maxConcurrent: 4
+    groups:
+      - name: docs-surface
+        angles: [docs, link-check, config-drift, contract-surface]
+      - name: process
+        angles: [scope, pr-description, gate-evidence, pr-checklist-matrix]
+      - name: correctness-input
+        angles: [correctness, input-validation]
+      - name: determinism-state
+        angles: [determinism, state-concurrency]
   preApproval:
     angles:
       - name: dry

package/src/github/copilot-helpers.mjs

@@ -6,11 +6,76 @@
  * scripts and other packages/core modules.
  */
 
-const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
+// Exported so anything deciding "is there a real prior review" uses the same
+// whitelist as the loop-state reader — two copies could drift, and a guard
+// acting on the gate's behalf must agree with the gate about what a submitted
+// review is.
+export const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 const GATE_REVIEW_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
 const GATE_REVIEW_VERDICTS = new Set(["clean", "findings_present", "blocked"]);
 const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
 
+// The literal header line the gate review body always emits first
+// (upsert-checkpoint-verdict.mjs's renderGateReviewCommentBody, re-exported
+// from there). Owned here so the machine-artifact filter below and every
+// consumer that needs to recognize "is this a real gate verdict surface" read
+// the same producer-owned literal instead of restating it. Line-start anchored
+// (`m`) so a quoted header in a reply/blockquote can't match.
+export const GATE_REVIEW_COMMENT_HEADER_RE = /^###\s+Gate review:\s*`(draft_gate|pre_approval_gate)`\s*$/m;
+
+/** Returns the matched gate name when `body` carries a genuine gate verdict header, else null. */
+export function matchGateReviewCommentHeader(body) {
+  if (typeof body !== "string") return null;
+  const match = body.match(GATE_REVIEW_COMMENT_HEADER_RE);
+  return match ? match[1] : null;
+}
+
+// Machine-authored gate artifacts that must never win the newest-gate-marker
+// tie-break in summarizeGateReviewComments/summarizeGateReviewCommentMarkers:
+// a historical standalone findings review always embedded this gate's name in
+// its header line and could quote the current head sha inside a finding's own
+// free text (the lenient gate-name+hex-token fallback in
+// parseGateReviewCommentFields would otherwise happily match that), and the
+// historical deferred-summary PR comment quoted a gate name plus a sha-shaped
+// id in its table rows the same way. Both are excluded HERE, inside the two
+// shared summarizers, because this module is the true merge point: every
+// consumer (detect-checkpoint-evidence.mjs, pre-pr-ready-gate.mjs,
+// ready-for-review.mjs, request-copilot-review.mjs) calls
+// summarizeGateReviewComments/summarizeGateReviewCommentMarkers to turn a raw
+// comment/review list into a gate verdict, so filtering here — rather than
+// per-caller — covers all of them by construction.
+//
+// Anchored to the start of a line (`^` with `m`) so only a marker rendered as
+// the first character of its own line is excluded — a genuine verdict
+// comment whose findings summary merely QUOTES the marker text mid-line (for
+// example, describing this very mechanism) still counts as evidence. Both
+// producers render their marker at column 0, so the anchor costs nothing
+// against genuine artifacts.
+// The set covers exactly three marker tokens: the per-round review round
+// marker (gate-findings-review), post-gate-findings.mjs's opt-in findings
+// COMMENT marker (gate-findings gate=...), and the historical
+// deferred-summary comment. Without the findings-comment marker, that comment
+// parses as a verdict marker candidate (its "Gate fan-out findings:"/
+// "Reviewed head:" lines yield gate+headSha) and the verdict upsert claims
+// and overwrites it in place, silently destroying the round's visible
+// findings record. Every branch is delimiter-anchored — the token must be
+// followed by whitespace or the closing `-->` — so no suffixed `<token>-<x>`
+// variant ever matches.
+const GATE_MACHINE_ARTIFACT_MARKER_RE = /^<!--\s*dev-loops:(?:gate-findings-review|gate-findings|deferred-summary)(?=\s|-->)/mu;
+
+export function isGateMachineArtifactBody(body) {
+  if (typeof body !== "string" || !GATE_MACHINE_ARTIFACT_MARKER_RE.test(body)) {
+    return false;
+  }
+  // A gate round now posts ONE PR review carrying BOTH the verdict header and
+  // the gate-findings-review marker (the findings it files live on that same
+  // surface). Such a body IS the verdict, not a separate machine artifact, so
+  // the producer-owned verdict header wins over the artifact marker. Only a
+  // marker-bearing body with NO genuine verdict header (a historical standalone
+  // findings review or deferred-summary comment) stays excluded.
+  return matchGateReviewCommentHeader(body) === null;
+}
+
 export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
 }
@@ -234,50 +299,86 @@ function parseGateReviewCommentFields(body) {
     }
     const line = stripped;
 
+    // First-NON-EMPTY-wins per field: a genuine comment renders its structured
+    // block first, so the first column-0 match for each field is normally the
+    // real one. A free-text field (findings summary, next action) rendered
+    // later in the SAME comment can embed a newline plus a spoofed
+    // "Verdict: clean" (or any other field label) at column 0; capturing only
+    // the first match (rather than the last) stops that later line from
+    // winning and flipping/nulling the field. But the label regex's
+    // `\s*(.+)$` also matches a label followed by nothing but whitespace,
+    // capturing an empty string — for the enum fields (gate/headSha/verdict/
+    // executionMode) an empty capture normalizes to null already, so the
+    // `=== null` guard below naturally stays open for a later, genuine line.
+    // The two free-text fields (findingsSummary, nextAction) do NOT normalize
+    // through an enum, so an empty capture must be checked for explicitly:
+    // treat it as no-capture (leave the field open) rather than locking it to
+    // "" and hiding a real line that renders after it.
     let match = line.match(/^(?:[-*]\s*)?(?:gate(?:\s+name)?|gate\s+review)\s*:\s*(.+)$/iu);
     if (match) {
-      fields.gate = normalizeGateReviewName(match[1]);
+      if (fields.gate === null) {
+        fields.gate = normalizeGateReviewName(match[1]);
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?(?:head\s+sha(?:\s+reviewed)?|reviewed\s+head\s+sha)\s*:\s*(.+)$/iu);
     if (match) {
-      fields.headSha = normalizeGateReviewHeadSha(match[1]);
+      if (fields.headSha === null) {
+        fields.headSha = normalizeGateReviewHeadSha(match[1]);
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?verdict\s*:\s*(.+)$/iu);
     if (match) {
-      fields.verdict = normalizeGateReviewVerdict(match[1]);
+      if (fields.verdict === null) {
+        fields.verdict = normalizeGateReviewVerdict(match[1]);
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?(?:findings(?:\s+summary)?|summary)\s*:\s*(.+)$/iu);
     if (match) {
-      fields.findingsSummary = match[1].trim();
+      if (fields.findingsSummary === null) {
+        const candidate = match[1].trim();
+        // An empty capture (label followed only by whitespace) is treated as
+        // no-capture: leave the field open so a later, genuine line can still
+        // win instead of first-wins locking it to "".
+        if (candidate.length > 0) {
+          fields.findingsSummary = candidate;
+        }
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?next\s+action\s*:\s*(.+)$/iu);
     if (match) {
-      fields.nextAction = match[1].trim();
+      if (fields.nextAction === null) {
+        const candidate = match[1].trim();
+        if (candidate.length > 0) {
+          fields.nextAction = candidate;
+        }
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?execution\s+mode\s*:\s*(.+)$/iu);
     if (match) {
-      const rest = match[1].trim();
-      // Split on the first em-dash / en-dash / " - " separator to recover an
-      // optional inline reason: "inline_single_agent — <reason>".
-      const sepMatch = rest.match(/^(.*?)\s*(?:[—–]|\s-\s)\s*(.*)$/u);
-      const modeToken = sepMatch ? sepMatch[1].trim() : rest;
-      const reasonToken = sepMatch ? sepMatch[2].trim() : "";
-      fields.executionMode = normalizeGateExecutionMode(modeToken);
-      // Only record an inline reason for inline_single_agent. A trailing
-      // "— text" on a fanout_fanin (or invalid) mode line must not surface an
-      // inconsistent mode/reason pair, so leave inlineReason null otherwise.
-      if (reasonToken.length > 0 && fields.executionMode === "inline_single_agent") {
-        fields.inlineReason = reasonToken;
+      if (fields.executionMode === null) {
+        const rest = match[1].trim();
+        // Split on the first em-dash / en-dash / " - " separator to recover an
+        // optional inline reason: "inline_single_agent — <reason>".
+        const sepMatch = rest.match(/^(.*?)\s*(?:[—–]|\s-\s)\s*(.*)$/u);
+        const modeToken = sepMatch ? sepMatch[1].trim() : rest;
+        const reasonToken = sepMatch ? sepMatch[2].trim() : "";
+        fields.executionMode = normalizeGateExecutionMode(modeToken);
+        // Only record an inline reason for inline_single_agent. A trailing
+        // "— text" on a fanout_fanin (or invalid) mode line must not surface an
+        // inconsistent mode/reason pair, so leave inlineReason null otherwise.
+        if (reasonToken.length > 0 && fields.executionMode === "inline_single_agent") {
+          fields.inlineReason = reasonToken;
+        }
       }
       continue;
     }
@@ -353,6 +454,18 @@ export function parseGateReviewCommentMarkerBody(body) {
   };
 }
 
+// Which GitHub surface carries a gate verdict. The poster needs it to pick the
+// right in-place correction endpoint on a same-head rerun (a PR review is PUT
+// to pulls/{pr}/reviews/{id}; a legacy verdict issue comment is PATCHed to
+// issues/comments/{id}). Anything that is not the review surface — including a
+// raw issue-comment payload with no `surface` field — is issue_comment, so the
+// historical shape survives untouched. SINGLE definition: a restatement that
+// misses a future third surface would silently route its body to the
+// issue-comment endpoint, where it does not live.
+export function normalizeVerdictSurface(value) {
+  return value === "review" ? "review" : "issue_comment";
+}
+
 export function summarizeGateReviewComments(comments) {
   const summary = {
     draft_gate: null,
@@ -363,6 +476,9 @@ export function summarizeGateReviewComments(comments) {
 
   for (let index = 0; index < entries.length; index += 1) {
     const comment = entries[index];
+    if (isGateMachineArtifactBody(comment?.body)) {
+      continue;
+    }
     const parsed = parseGateReviewCommentBody(comment?.body);
     if (!parsed) {
       continue;
@@ -378,6 +494,7 @@ export function summarizeGateReviewComments(comments) {
       nextAction: parsed.nextAction,
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
+      surface: normalizeVerdictSurface(comment?.surface),
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
@@ -409,6 +526,9 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
 
   for (let index = 0; index < entries.length; index += 1) {
     const comment = entries[index];
+    if (isGateMachineArtifactBody(comment?.body)) {
+      continue;
+    }
     const parsed = parseGateReviewCommentMarkerBody(comment?.body);
     if (!parsed) {
       continue;
@@ -429,6 +549,7 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
       contractComplete: parsed.contractComplete,
+      surface: normalizeVerdictSurface(comment?.surface),
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"

package/src/github/issue-ops.mjs

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { runChild as defaultRunChild } from "../cli/primitives.mjs";
 import { parseJsonText } from "./review-threads.mjs";
 import { parseRepoSlug } from "./repo-slug.mjs";
@@ -62,7 +62,36 @@ export function buildCreateArgs(options) {
   return args;
 }
 
+// Reject a --body-file path that does not RESOLVE (following symlinks) to a
+// regular file. The CLI layer's literal-string rejections (`-`, `/dev/stdin`,
+// `/dev/fd/N`, ...) only catch known stdin-device spellings; a symlink to one
+// of those devices (or to /dev/null, a FIFO, etc.) dodges that regex yet still
+// reads as empty/non-file when `gh` re-reads the same path with stdin ignored.
+// `statSync` follows symlinks, so this closes that gap regardless of path shape.
+function assertRegularFilePath(path) {
+  if (!statSync(path).isFile()) {
+    throw new Error(`--body-file must be a regular file: ${path}`);
+  }
+}
+
+// Read (for validation only — the actual gh call still forwards the path, see
+// buildCreateArgs) and reject a --body-file that isn't a regular file or whose
+// content is empty/whitespace-only. This is the real guard behind the CLI's
+// stdin-device rejection: `gh` is spawned with stdin ignored, so it re-reads
+// the same path fresh — this validates what gh will actually see, not just the
+// path's literal spelling.
+export async function resolveCreateBody(options) {
+  if (options.bodyFile === undefined) return options.body;
+  assertRegularFilePath(options.bodyFile);
+  return await readFile(options.bodyFile, "utf8");
+}
+
 export async function createIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const body = await resolveCreateBody(options);
+  if (typeof body !== "string" || body.trim().length === 0) {
+    const source = options.bodyFile !== undefined ? `--body-file ${options.bodyFile}` : "--body";
+    throw new Error(`issue body resolved empty from ${source} — refusing to create a bodyless issue`);
+  }
   const args = buildCreateArgs(options);
   const result = await run(ghCommand, args, env);
   if (result.code !== 0) {
@@ -126,12 +155,55 @@ export async function buildEditArgs(options) {
   return { args, edited };
 }
 
+// gh's own --reason values are space-separated ("not planned"), but the
+// CLI-facing flag value stays the underscore form (`not_planned`) since it's
+// stable and shell-friendly without quoting; map it here at the gh-args
+// boundary rather than changing the public flag value.
+const REASON_ARG_BY_CLI_VALUE = { not_planned: "not planned" };
+
+// Build the `gh issue close`/`gh issue reopen` args for a --state change. Kept
+// as a separate `gh` call from `gh issue edit` — that command has no --state
+// flag, so a state change is its own invocation, run after the edit call.
+export function buildStateChangeArgs(options) {
+  if (options.state === "closed") {
+    const args = ["issue", "close", String(options.issue), "--repo", options.repo];
+    if (options.reason !== undefined) {
+      args.push("--reason", REASON_ARG_BY_CLI_VALUE[options.reason] ?? options.reason);
+    }
+    return args;
+  }
+  if (options.state !== "open") {
+    // Fail closed: this is an exported seam, so an unexpected state must never
+    // silently degrade into a reopen.
+    throw new Error(`invalid state ${JSON.stringify(options.state)} — expected "open" or "closed"`);
+  }
+  return ["issue", "reopen", String(options.issue), "--repo", options.repo];
+}
+
 export async function editIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
   const { args, edited } = await buildEditArgs(options);
-  const result = await run(ghCommand, args, env);
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw new Error(`gh issue edit failed: ${detail}`);
+  // Skip the edit call entirely when --state is the only change requested —
+  // `gh issue edit` with no field flags errors ("no changed fields").
+  if (edited.length > 0) {
+    const result = await run(ghCommand, args, env);
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || `exit code ${result.code}`;
+      throw new Error(`gh issue edit failed: ${detail}`);
+    }
+  }
+  if (options.state !== undefined) {
+    const stateArgs = buildStateChangeArgs(options);
+    const result = await run(ghCommand, stateArgs, env);
+    if (result.code !== 0) {
+      const verb = options.state === "closed" ? "close" : "reopen";
+      const detail = result.stderr.trim() || `exit code ${result.code}`;
+      // Surface the edits that DID land before the state change failed, so a
+      // caller (or a human reading the error) knows the field edits are not
+      // rolled back — only the state change itself failed.
+      const landed = edited.length > 0 ? ` after edits were applied: ${edited.join(", ")}` : "";
+      throw new Error(`state change failed${landed} — gh issue ${verb} failed: ${detail}`);
+    }
+    edited.push("state");
   }
   return { ok: true, repo: options.repo, issue: options.issue, edited };
 }

package/src/github/review-threads.mjs

@@ -166,6 +166,34 @@ export function parseReviewThreads(payload) {
   };
 }
 
+/**
+ * The fix-loop's re-entry working set: only unresolved threads, each with its
+ * comment bodies joined in thread order. Location fields come from the thread
+ * node when the payload carries them (`path`/`line`/`isOutdated`); snapshots
+ * without them yield `path: null`, `line: null`, `isOutdated: false`.
+ *
+ * @returns {{ summary: object, threads: Array<{ threadId: string, path: string|null, line: number|null, isOutdated: boolean, bodies: string[] }> }}
+ */
+export function parseUnresolvedThreadBodies(payload) {
+  const rawThreads = extractRawThreads(payload);
+  const { summary } = parseReviewThreads(payload);
+  const threads = rawThreads
+    .map((thread, threadIndex) => ({ thread, threadIndex }))
+    .filter(({ thread }) => !thread?.isResolved)
+    .map(({ thread, threadIndex }) => ({
+      threadId: normalizeId(thread?.id ?? thread?.databaseId, `thread-${threadIndex + 1}`),
+      path: typeof thread?.path === "string" && thread.path.length > 0 ? thread.path : null,
+      line: Number.isInteger(thread?.line) ? thread.line : null,
+      isOutdated: Boolean(thread?.isOutdated),
+      bodies: extractRawComments(thread).map((comment) =>
+        normalizeBody(comment?.body ?? comment?.bodyText ?? comment?.bodyHTML ?? ""),
+      ),
+    }))
+    .sort((left, right) => compareIds(left.threadId, right.threadId));
+
+  return { summary, threads };
+}
+
 // ── Signal classification heuristics ──────────────────────────────────────
 
 const HIGH_SIGNAL_PATTERNS = [
@@ -303,10 +331,23 @@ export function parseJsonText(text) {
   }
 }
 
-export function formatCliError(error) {
+// Renders the one shared { ok: false, error, hint? } envelope every
+// JSON-emitting gate CLI's main() catch block prints to stderr. `usage` is
+// accepted only as a PRESENCE check for a fallback usage string (a caller
+// passing its own `USAGE` constant when the error itself might not already
+// carry one) — the fallback's actual TEXT, like `error.usage`'s, is never
+// embedded here. Argument errors (and any error a caller marks with a usage
+// string) used to inline that string's full multi-KB text into this JSON
+// payload, which every calling agent then paid to read back out of its own
+// tool result on every mistyped flag. A one-line `hint` pointing at --help
+// carries the same "usage exists, go look" signal at a fraction of the size;
+// --help itself is unaffected (it prints the full USAGE text directly, never
+// through this function).
+export function formatCliError(error, { usage } = {}) {
   const payload = { ok: false, error: error instanceof Error ? error.message : String(error) };
-  if (error instanceof Error && typeof error.usage === "string") {
-    payload.usage = error.usage;
+  const hasUsage = (error instanceof Error && typeof error.usage === "string") || typeof usage === "string";
+  if (hasUsage) {
+    payload.hint = "run with --help for usage";
   }
   return JSON.stringify(payload);
 }

package/src/loop/copilot-ci-status.mjs

@@ -6,16 +6,31 @@ const STATUS_CONTEXT_PENDING_STATES = new Set(["PENDING", "EXPECTED"]);
 const STATUS_CONTEXT_SUCCESS_STATES = new Set(["SUCCESS"]);
 
 /**
- * Name of the server-side "Gate evidence" check dev-loops posts on its own
- * pull requests (`.github/workflows/gate-evidence.yml`). Its conclusion is
- * DERIVED from the loop's own progress (a clean current-head
- * pre_approval_gate verdict), not an independent build/test signal — so the
- * loop must exclude it, by this exact name only, when deriving the CI status
- * that gates its own pre_approval step. Otherwise the loop could never post
- * the very verdict that would turn this check green (#1358).
+ * Name of the explicit commit STATUS dev-loops posts on its own pull requests
+ * from `.github/workflows/gate-evidence.yml`. Its conclusion is DERIVED from
+ * the loop's own progress (a clean current-head pre_approval_gate verdict),
+ * not an independent build/test signal — so the loop must exclude it when
+ * deriving the CI status that gates its own pre_approval step. Otherwise the
+ * loop could never post the very verdict that would turn this check green
+ * (#1358). This constant names ONLY the status context; the workflow also
+ * surfaces as a check run, so anything partitioning check runs must use
+ * `LOOP_DERIVED_CI_CHECK_NAMES` below. It remains the label reported in
+ * `excludedFailureDetails` for either shape, since both name one workflow.
  */
 export const LOOP_DERIVED_CI_CHECK_NAME = "gate-evidence";
 
+/**
+ * The same workflow ALSO surfaces as a check run under its job id
+ * (`gate-evidence-runner`) beside the commit status named above, and both are
+ * the loop's own derived signal. Excluding only the status context left the
+ * runner's conclusion gating the loop's own pre_approval step: once the
+ * workflow gained job-level concurrency, a superseded run is cancelled as
+ * normal operation, and a cancelled run is deliberately NOT treated as green
+ * (see normalizeStatusCheckRollupStatus) — so one routine cancellation made
+ * the whole head read "none" and the loop waited on CI forever.
+ */
+export const LOOP_DERIVED_CI_CHECK_NAMES = Object.freeze([LOOP_DERIVED_CI_CHECK_NAME, "gate-evidence-runner"]);
+
 function checkEntryName(entry) {
   if (typeof entry?.name === "string" && entry.name.length > 0) return entry.name;
   if (typeof entry?.context === "string" && entry.context.length > 0) return entry.context;
@@ -28,15 +43,16 @@ function checkEntryName(entry) {
  * both use `.name` (check-runs also use `.context` for legacy StatusContext).
  *
  * @param {Array<object>} entries
- * @param {string} targetName
+ * @param {string|Array<string>} targetName One name, or several to match.
  * @returns {{ matched: Array<object>, rest: Array<object> }}
  */
 export function partitionEntriesByCheckName(entries, targetName) {
   const list = Array.isArray(entries) ? entries : [];
+  const targets = new Set(Array.isArray(targetName) ? targetName : [targetName]);
   const matched = [];
   const rest = [];
   for (const entry of list) {
-    (checkEntryName(entry) === targetName ? matched : rest).push(entry);
+    (targets.has(checkEntryName(entry)) ? matched : rest).push(entry);
   }
   return { matched, rest };
 }
@@ -128,25 +144,36 @@ export function normalizeStatusCheckRollupStatus(rollup) {
 /**
  * Summarize the GitHub check-runs API payload for one head SHA.
  *
+ * `allQueued` is the zero-allocation stall signal (#1631): true when at least one
+ * check-run is present AND every one is still in the `queued` status — i.e. no
+ * runner has been allocated to any job (no job picked up / in_progress / completed).
+ * The CI watcher uses it to bail early on a stuck GitHub Actions queue instead
+ * of burning the full watch budget.
+ *
  * @param {object} payload
- * @returns {{ status: "success"|"failure"|"pending"|"none", unsupportedCompleted: boolean, failureDetails?: Array<string> }}
+ * @returns {{ status: "success"|"failure"|"pending"|"none", unsupportedCompleted: boolean, allQueued: boolean, failureDetails?: Array<string> }}
  */
 export function summarizeHeadScopedCheckRunsSignal(payload) {
   const runs = Array.isArray(payload?.check_runs) ? payload.check_runs : [];
   if (runs.length === 0) {
-    return { status: "none", unsupportedCompleted: false };
+    return { status: "none", unsupportedCompleted: false, allQueued: false };
   }
 
   let hasPending = false;
   let hasFailure = false;
   let hasSuccess = false;
   let hasUnsupportedCompleted = false;
+  let allQueued = true; // every run is status "queued" (zero runner allocation)
   const failureDetails = [];
 
   for (const run of runs) {
     const status = typeof run?.status === "string" ? run.status.toUpperCase() : "";
     const conclusion = typeof run?.conclusion === "string" ? run.conclusion.toUpperCase() : "";
 
+    if (status !== "QUEUED") {
+      allQueued = false;
+    }
+
     if (status !== "COMPLETED") {
       hasPending = true;
       continue;
@@ -167,11 +194,11 @@ export function summarizeHeadScopedCheckRunsSignal(payload) {
     hasUnsupportedCompleted = true;
   }
 
-  if (hasFailure) return { status: "failure", unsupportedCompleted: hasUnsupportedCompleted, failureDetails };
-  if (hasPending) return { status: "pending", unsupportedCompleted: hasUnsupportedCompleted, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
-  if (hasUnsupportedCompleted) return { status: "none", unsupportedCompleted: true, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
-  if (hasSuccess) return { status: "success", unsupportedCompleted: false, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
-  return { status: "none", unsupportedCompleted: false, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
+  if (hasFailure) return { status: "failure", unsupportedCompleted: hasUnsupportedCompleted, allQueued, failureDetails };
+  if (hasPending) return { status: "pending", unsupportedCompleted: hasUnsupportedCompleted, allQueued, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
+  if (hasUnsupportedCompleted) return { status: "none", unsupportedCompleted: true, allQueued, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
+  if (hasSuccess) return { status: "success", unsupportedCompleted: false, allQueued, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
+  return { status: "none", unsupportedCompleted: false, allQueued, failureDetails: failureDetails.length > 0 ? failureDetails : undefined };
 }
 
 /**
@@ -292,7 +319,8 @@ export function normalizeHeadScopedCiContract({
 
 /**
  * Derive a loop-safe CI status from a PR `statusCheckRollup` snapshot: the
- * `LOOP_DERIVED_CI_CHECK_NAME` entry (`gate-evidence`) is excluded from the
+ * `LOOP_DERIVED_CI_CHECK_NAMES` entries (the `gate-evidence` status and the
+ * workflow's own `gate-evidence-runner` check run) are excluded from the
  * status computation before it can block, and surfaced separately so a
  * genuinely failing check right beside it can never be masked. Every reason
  * gate-evidence can be red (missing draft_gate/pre_approval evidence,
@@ -305,7 +333,7 @@ export function normalizeHeadScopedCiContract({
  * @returns {{ status: "success"|"failure"|"pending"|"none", excludedFailureDetails: Array<string> }}
  */
 export function deriveLoopCiStatusFromRollup(rollup) {
-  const { matched, rest } = partitionEntriesByCheckName(rollup, LOOP_DERIVED_CI_CHECK_NAME);
+  const { matched, rest } = partitionEntriesByCheckName(rollup, LOOP_DERIVED_CI_CHECK_NAMES);
   const status = normalizeStatusCheckRollupStatus(rest);
   const excludedFailureDetails = matched.length > 0 && normalizeStatusCheckRollupStatus(matched) === "failure"
     ? [LOOP_DERIVED_CI_CHECK_NAME]

package/src/loop/copilot-loop-iterations.mjs

@@ -1,7 +1,6 @@
-import { isCopilotLogin, normalizeTimestamp } from "../github/copilot-helpers.mjs";
+import { SUBMITTED_REVIEW_STATES, isCopilotLogin, normalizeTimestamp } from "../github/copilot-helpers.mjs";
 
 const ACTIVE_COPILOT_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested"]);
-const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 
 function normalizeReviewRequestEvents(events) {
   if (!Array.isArray(events)) {