@dev-loops/core 0.6.0 → 0.7.1

package/src/loop/bash-command-classify.mjs

@@ -14,6 +14,53 @@ export const TARGET_REPO_SLUG = "mfittko/dev-loops";
 /** Flags known to take a value argument for `gh pr ready` (not boolean flags). */
 export const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
 
+/**
+ * Shell command separators that terminate one segment and begin the next.
+ * Newline (`\n`) and carriage return (`\r`) are full command terminators in bash
+ * (equivalent to `;`), and the Claude Code Bash tool accepts multi-line command
+ * strings — so a segment must break on them too, else `echo hi\ngh pr create` evades
+ * the gate. Used by all segment-splitting sites (DRY).
+ */
+const SHELL_SEGMENT_SEPARATOR = /\s*(?:&&|\|\||;|\||\n|\r)\s*/;
+
+/**
+ * Strip a single balanced surrounding quote pair (`'…'` or `"…"`) from a shell arg value.
+ * A repo flag value may reach us quoted (`--repo 'owner/name'`); the scope check compares against
+ * the bare slug, so quotes must be normalized or a quoted on-target repo evades the guard (#1074).
+ * ponytail: single balanced pair only — no full shell tokenization (mismatched/partial quotes stay).
+ * @param {string|null} value @returns {string|null}
+ */
+function stripSurroundingQuotes(value) {
+  if (value == null || value.length < 2) return value;
+  const first = value[0];
+  if ((first === "'" || first === '"') && value[value.length - 1] === first) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Read an inline `GH_REPO=<value>` env-assignment prefix on a single command segment.
+ * `gh` resolves its target repo from the `GH_REPO` env var, and a segment may set it inline
+ * (`GH_REPO=owner/name gh issue create …`) — same targeting intent as `--repo owner/name`, so the
+ * scope check must treat it the same or an off-cwd redirect evades the guard (#1074). Only the
+ * FIRST leading env assignment matching `GH_REPO=` is read (env assignments precede the executable);
+ * the value is quote-normalized. Ambient `process.env.GH_REPO` is out of scope — this is a static
+ * command-string classifier, so only the inline assignment in the string is considered.
+ * @param {string} segment @returns {string|null}
+ */
+function extractGhRepoEnvAssignment(segment) {
+  if (!segment) return null;
+  for (const token of segment.trim().split(/\s+/)) {
+    const assign = token.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!assign) break; // first non-assignment token ends the env-assignment prefix
+    if (assign[1] === "GH_REPO") {
+      return trimToNull(stripSurroundingQuotes(assign[2]));
+    }
+  }
+  return null;
+}
+
 /** @param {string|null|undefined} value @returns {string|null} */
 export function trimToNull(value) {
   const trimmed = `${value ?? ""}`.trim();
@@ -50,7 +97,7 @@ export function normalizeGitHubRepoSlug(remoteUrl) {
   return null;
 }
 
-function isGhPrMergeCommand(segment) {
+function segmentIsGhPrMerge(segment) {
   if (!/^gh\s+pr\s+merge(?:\s|$)/i.test(segment)) {
     return false;
   }
@@ -81,36 +128,178 @@ export function isMergeCapableCommand(command) {
     return false;
   }
   return normalized
-    .split(/\s*(?:&&|\|\||;|\|)\s*/)
-    .some((segment) => isGhPrMergeCommand(segment) || isGitMergeCompletionCommand(segment));
+    .split(SHELL_SEGMENT_SEPARATOR)
+    .some((segment) => segmentIsGhPrMerge(segment) || isGitMergeCompletionCommand(segment));
 }
 
 /** @param {string} command @returns {string} */
 export function firstShellSegment(command) {
-  return command.trim().split(/\s*(?:&&|\|\||;|\|)\s*/)[0]?.trim() ?? "";
+  return command.trim().split(SHELL_SEGMENT_SEPARATOR)[0]?.trim() ?? "";
 }
 
-/** @param {string} command @returns {boolean} */
-export function isGhPrReadyCommand(command) {
-  const segment = firstShellSegment(command);
-  if (!segment || !/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return false;
+/** Split a compound shell command into its individual segments. */
+function shellSegments(command) {
+  return command.trim().split(SHELL_SEGMENT_SEPARATOR).map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Leading prefix a `gh pr <verb>` segment may carry before the `gh` executable:
+ * a run of `NAME=value` env assignments, optional `command`/`env`/`exec` wrapper
+ * words, and an absolute/relative path on the gh binary (`/usr/bin/gh`).
+ *
+ * Note: this is a pragmatic normalizer, not a full shell tokenizer. Subshell
+ * `(gh pr create)`, `{ …; }` group, `-R=value` short-flag, and backslash-escaped
+ * `\gh` forms are deliberately out of scope.
+ */
+const GH_PR_VERB_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
+
+/**
+ * Build the `gh <subcmd> <verb>` prefix matcher (subcmd = "pr" | "issue").
+ * Tolerates a leading env-assignment/wrapper/path prefix so `GH_TOKEN=x gh pr create`,
+ * `command gh issue create`, and `/usr/bin/gh pr create` are all matched. The same regex
+ * is reused to strip the matched prefix (`segment.replace(re, "")`), so remainder
+ * extraction stays consistent across all matcher/extractor call sites. The `gh` prefix
+ * requirement means node-wrapper commands (`node scripts/github/comment-issue.mjs …`) never
+ * match — their first token is `node`, not `gh`.
+ */
+function ghSubcmdVerbRegex(subcmd, verb) {
+  return new RegExp(`^${GH_PR_VERB_PREFIX}gh\\s+${subcmd}\\s+${verb}(?:\\s|$)`, "i");
+}
+
+/** Build the `gh pr <verb>` prefix matcher — delegates to the generic subcmd matcher (DRY). */
+function ghPrVerbRegex(verb) {
+  return ghSubcmdVerbRegex("pr", verb);
+}
+
+/**
+ * Return the first segment in the command that is a `gh <subcmd> <verb>` call (ignoring
+ * --help/-h), or null. Scans ALL segments so compound commands are caught.
+ */
+function findGhSubcmdVerbSegment(command, subcmd, verb) {
+  const re = ghSubcmdVerbRegex(subcmd, verb);
+  for (const segment of shellSegments(command)) {
+    if (!re.test(segment)) continue;
+    const remainder = segment.replace(re, "").trim();
+    if (!remainder) return segment;
+    const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
+    if (!args.includes("--help") && !args.includes("-h")) return segment;
   }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
-  if (!remainder) {
-    return true;
+  return null;
+}
+
+/**
+ * Extract the `--repo`/`-R` flag value from an already-isolated `gh <subcmd> <verb>` segment.
+ * @param {string} segment @param {string} subcmd @param {string} verb @returns {string|null}
+ */
+function extractRepoFlagFromSubcmdSegment(segment, subcmd, verb) {
+  const re = ghSubcmdVerbRegex(subcmd, verb);
+  if (!segment || !re.test(segment)) return null;
+  const remainder = segment.replace(re, "").trim();
+  if (!remainder) return null;
+  const tokens = remainder.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const lower = token.toLowerCase();
+    if (lower === "-r" || lower === "--repo") {
+      if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) return stripSurroundingQuotes(tokens[i + 1]);
+    }
+    const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
+    if (repoEqMatch) return stripSurroundingQuotes(repoEqMatch[1]);
+  }
+  // No explicit --repo/-R flag: fall back to an inline GH_REPO= env assignment (flag wins,
+  // mirroring gh's own precedence). This closes the GH_REPO repo-targeting bypass (#1074).
+  return extractGhRepoEnvAssignment(segment);
+}
+
+/**
+ * Return one `{ segment, explicitRepo }` entry for EVERY `gh <subcmd> <verb>` segment (ignoring
+ * --help/-h). Mirrors `extractRepoFlagsFromGhPrCreateSegments`.
+ * @param {string} command @param {string} subcmd @param {string} verb
+ * @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+function extractRepoFlagsFromGhSubcmdVerbSegments(command, subcmd, verb) {
+  const re = ghSubcmdVerbRegex(subcmd, verb);
+  const out = [];
+  for (const segment of shellSegments(command)) {
+    if (!re.test(segment)) continue;
+    const remainder = segment.replace(re, "").trim();
+    if (remainder) {
+      const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
+      if (args.includes("--help") || args.includes("-h")) continue;
+    }
+    out.push({ segment, explicitRepo: extractRepoFlagFromSubcmdSegment(segment, subcmd, verb) });
   }
+  return out;
+}
+
+/**
+ * The raw external-write verb forms that must be blocked when originating from a subagent:
+ * ad-hoc GitHub issue/PR creation and comments run directly via `gh` (not the sanctioned node
+ * wrappers). Each entry is `[subcmd, verb]`.
+ */
+const EXTERNAL_WRITE_VERB_FORMS = Object.freeze([
+  ["issue", "create"],
+  ["issue", "comment"],
+  ["pr", "comment"],
+]);
+
+/**
+ * Whether `command` contains a raw `gh issue create`, `gh issue comment`, or `gh pr comment`
+ * invocation in ANY shell segment (ignoring --help/-h). PreToolUse gate use only — the gate
+ * blocks these when they originate from a subagent context. Node-wrapper commands
+ * (`node scripts/github/comment-issue.mjs …`) never match (first token is `node`, not `gh`).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsRawExternalWrite(command) {
+  return EXTERNAL_WRITE_VERB_FORMS.some(([subcmd, verb]) => findGhSubcmdVerbSegment(command, subcmd, verb) !== null);
+}
+
+/**
+ * Return `{ segment, explicitRepo }` for every raw external-write segment across all three verb
+ * forms (`gh issue create` / `gh issue comment` / `gh pr comment`). PreToolUse gate use only —
+ * lets the gate decide in-scope-ness per segment so a leading out-of-scope write can't shield a
+ * later in-scope one. `explicitRepo` is the segment's `--repo`/`-R` value or null.
+ * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+export function extractRepoFlagsFromExternalWriteSegments(command) {
+  return EXTERNAL_WRITE_VERB_FORMS.flatMap(([subcmd, verb]) =>
+    extractRepoFlagsFromGhSubcmdVerbSegments(command, subcmd, verb),
+  );
+}
+
+/**
+ * Return the first segment in the command that is a `gh pr <verb>` call (ignoring --help/-h),
+ * or null. Scans ALL segments so compound commands (`echo ok && gh pr merge 1`) are caught.
+ */
+function findGhPrVerbSegment(command, verb) {
+  return findGhSubcmdVerbSegment(command, "pr", verb);
+}
+
+/**
+ * Generic `gh pr <verb>` detector — checks the FIRST shell segment only.
+ *
+ * Used by the Pi extension's post-execute handler (`onUserBash`) to record that `gh pr ready`
+ * actually ran. First-segment-only is correct for that use: `false && gh pr ready 42` short-
+ * circuits so ready never executes, and the extension should not record a spurious invocation.
+ *
+ * For the Claude Code PreToolUse gate (block before execution), use
+ * `commandContainsGhPrReady`/`commandContainsGhPrMerge` instead — those scan ALL segments.
+ */
+function isGhPrVerbCommand(command, verb) {
+  const re = ghPrVerbRegex(verb);
+  const segment = firstShellSegment(command);
+  if (!segment || !re.test(segment)) return false;
+  const remainder = segment.replace(re, "").trim();
+  if (!remainder) return true;
   const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
   return !args.includes("--help") && !args.includes("-h");
 }
 
-/** @param {string} command @returns {number|null} */
-export function extractPrNumberFromGhPrReady(command) {
-  const segment = firstShellSegment(command);
-  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return null;
-  }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+/** Extract PR number from a single already-isolated segment (shared by both first- and all-segment paths). */
+function extractPrNumberFromSegment(segment, verb) {
+  const re = ghPrVerbRegex(verb);
+  if (!segment || !re.test(segment)) return null;
+  const remainder = segment.replace(re, "").trim();
   if (!remainder) {
     return null;
   }
@@ -135,13 +324,11 @@ export function extractPrNumberFromGhPrReady(command) {
   return null;
 }
 
-/** @param {string} command @returns {string|null} */
-export function extractRepoFlagFromGhPrReady(command) {
-  const segment = firstShellSegment(command);
-  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return null;
-  }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+/** Extract repo flag from a single already-isolated segment. */
+function extractRepoFlagFromSegment(segment, verb) {
+  const re = ghPrVerbRegex(verb);
+  if (!segment || !re.test(segment)) return null;
+  const remainder = segment.replace(re, "").trim();
   if (!remainder) {
     return null;
   }
@@ -151,13 +338,130 @@ export function extractRepoFlagFromGhPrReady(command) {
     const lower = token.toLowerCase();
     if (lower === "-r" || lower === "--repo") {
       if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
-        return tokens[i + 1];
+        return stripSurroundingQuotes(tokens[i + 1]);
       }
     }
     const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
     if (repoEqMatch) {
-      return repoEqMatch[1];
+      return stripSurroundingQuotes(repoEqMatch[1]);
     }
   }
-  return null;
+  // No explicit --repo/-R flag: fall back to an inline GH_REPO= env assignment (flag wins,
+  // mirroring gh's own precedence). Applied here too so gh pr ready/merge/create scope checks get
+  // consistent GH_REPO handling — the root-cause fix, not just the external-write path (#1074).
+  return extractGhRepoEnvAssignment(segment);
+}
+
+/** First-segment extractor for `gh pr <verb>` PR number — Pi extension public API. */
+function extractPrNumberFromGhPrVerb(command, verb) {
+  return extractPrNumberFromSegment(firstShellSegment(command), verb);
+}
+
+/** First-segment extractor for `gh pr <verb>` --repo flag — Pi extension public API. */
+function extractRepoFlagFromGhPrVerb(command, verb) {
+  return extractRepoFlagFromSegment(firstShellSegment(command), verb);
+}
+
+/** @param {string} command @returns {boolean} */
+export function isGhPrReadyCommand(command) {
+  return isGhPrVerbCommand(command, "ready");
+}
+
+/** @param {string} command @returns {number|null} */
+export function extractPrNumberFromGhPrReady(command) {
+  return extractPrNumberFromGhPrVerb(command, "ready");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrReady(command) {
+  return extractRepoFlagFromGhPrVerb(command, "ready");
+}
+
+/**
+ * Whether `command` contains a `gh pr merge` invocation in the FIRST shell segment,
+ * ignoring `--help`/`-h`. Used by the Pi extension's post-execute handler.
+ * For the Claude Code PreToolUse gate, use `commandContainsGhPrMerge` instead.
+ * @param {string} command @returns {boolean}
+ */
+export function isGhPrMergeCommand(command) {
+  return isGhPrVerbCommand(command, "merge");
+}
+
+/**
+ * Whether `command` contains a `gh pr ready` invocation in ANY shell segment.
+ * For use in the Claude Code PreToolUse gate only — blocks the whole command pre-emptively
+ * regardless of shell short-circuit semantics (`false && gh pr ready 42` is still blocked).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGhPrReady(command) {
+  return findGhPrVerbSegment(command, "ready") !== null;
+}
+
+/**
+ * Whether `command` contains a `gh pr merge` invocation in ANY shell segment.
+ * For use in the Claude Code PreToolUse gate only — blocks the whole command pre-emptively.
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGhPrMerge(command) {
+  return findGhPrVerbSegment(command, "merge") !== null;
+}
+
+/** Extract PR number from `gh pr ready` in any shell segment — PreToolUse gate use only. */
+export function extractPrNumberFromGhPrReadyAnywhere(command) {
+  return extractPrNumberFromSegment(findGhPrVerbSegment(command, "ready"), "ready");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrReadyAnywhere(command) {
+  return extractRepoFlagFromSegment(findGhPrVerbSegment(command, "ready"), "ready");
+}
+
+/** Extract PR number from `gh pr merge` in any shell segment — PreToolUse gate use only. */
+export function extractPrNumberFromGhPrMergeAnywhere(command) {
+  return extractPrNumberFromSegment(findGhPrVerbSegment(command, "merge"), "merge");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrMergeAnywhere(command) {
+  return extractRepoFlagFromSegment(findGhPrVerbSegment(command, "merge"), "merge");
+}
+
+/**
+ * Whether `command` contains a raw `gh pr create` invocation in ANY shell segment.
+ * PreToolUse gate use only — blocks raw `gh pr create` so PR creation flows through the
+ * canonical wrapper (`scripts/github/create-pr.mjs` / `dev-loops pr create`), which always
+ * creates a draft and self-assigns. The wrapper runs `gh pr create` inside a node child
+ * process, so its Bash command string (`node …/create-pr.mjs …`) never matches this — only a
+ * literal `gh pr create` in the agent's shell command does.
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGhPrCreate(command) {
+  return findGhPrVerbSegment(command, "create") !== null;
+}
+
+/** Extract repo flag from `gh pr create` in any shell segment — PreToolUse gate use only. */
+export function extractRepoFlagFromGhPrCreateAnywhere(command) {
+  return extractRepoFlagFromSegment(findGhPrVerbSegment(command, "create"), "create");
+}
+
+/**
+ * Return one `{ segment, explicitRepo }` entry for EVERY `gh pr create` segment (ignoring
+ * --help/-h), not just the first. PreToolUse gate use only: the create-scope decision must
+ * consider every create segment, so a leading out-of-scope create can't shield a later
+ * in-scope raw create (`gh pr create --repo other/repo && gh pr create --fill`).
+ * `explicitRepo` is the segment's `--repo`/`-R` value or null when none is present.
+ * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+export function extractRepoFlagsFromGhPrCreateSegments(command) {
+  return extractRepoFlagsFromGhSubcmdVerbSegments(command, "pr", "create");
+}
+
+/** @param {string} command @returns {number|null} */
+export function extractPrNumberFromGhPrMerge(command) {
+  return extractPrNumberFromGhPrVerb(command, "merge");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrMerge(command) {
+  return extractRepoFlagFromGhPrVerb(command, "merge");
 }

package/src/loop/conductor-routing.mjs

@@ -697,13 +697,6 @@ export const OUTER_TERMINAL_STATES = Object.freeze([
   OUTER_STATE.NEEDS_RECONCILE,
 ]);
 
-export const OUTER_NONTERMINAL_STATES = Object.freeze([
-  OUTER_STATE.CONTINUE_CURRENT_WAIT,
-  OUTER_STATE.HANDOFF_TO_COPILOT_LOOP,
-  OUTER_STATE.HANDOFF_TO_REVIEWER_LOOP,
-  OUTER_STATE.STAY_WITH_CURRENT_LIVE_OWNER,
-]);
-
 const OUTER_TERMINAL_STATE_SET = new Set(OUTER_TERMINAL_STATES);
 const ALL_OUTER_STATES = Object.freeze([...OUTER_STATE_VALUES]);
 
@@ -714,26 +707,6 @@ export const OUTER_GRAPH = Object.freeze({
   terminalStates: OUTER_TERMINAL_STATES,
 });
 
-export const OUTER_STATE_TO_OUTER_ACTION = Object.freeze({
-  [OUTER_STATE.CONTINUE_CURRENT_WAIT]: "continue_wait",
-  [OUTER_STATE.HANDOFF_TO_COPILOT_LOOP]: "reenter_copilot_loop",
-  [OUTER_STATE.HANDOFF_TO_REVIEWER_LOOP]: "reenter_reviewer_loop",
-  [OUTER_STATE.STAY_WITH_CURRENT_LIVE_OWNER]: "continue_wait",
-  [OUTER_STATE.STOP_NEEDS_HUMAN]: "stop",
-  [OUTER_STATE.DONE_TERMINAL]: "done",
-  [OUTER_STATE.NEEDS_RECONCILE]: "stop",
-});
-
-export const OUTER_STATE_TO_ROUTING_OUTCOME = Object.freeze({
-  [OUTER_STATE.CONTINUE_CURRENT_WAIT]: ROUTING_OUTCOME.CONTINUE_CURRENT_WAIT,
-  [OUTER_STATE.HANDOFF_TO_COPILOT_LOOP]: ROUTING_OUTCOME.HANDOFF_TO_COPILOT_LOOP,
-  [OUTER_STATE.HANDOFF_TO_REVIEWER_LOOP]: ROUTING_OUTCOME.HANDOFF_TO_REVIEWER_LOOP,
-  [OUTER_STATE.STAY_WITH_CURRENT_LIVE_OWNER]: ROUTING_OUTCOME.STAY_WITH_CURRENT_LIVE_OWNER,
-  [OUTER_STATE.STOP_NEEDS_HUMAN]: ROUTING_OUTCOME.STOP_NEEDS_HUMAN,
-  [OUTER_STATE.DONE_TERMINAL]: ROUTING_OUTCOME.DONE_TERMINAL,
-  [OUTER_STATE.NEEDS_RECONCILE]: ROUTING_OUTCOME.NEEDS_RECONCILE,
-});
-
 export const OUTER_NEXT_ACTIONS = Object.freeze({
   [OUTER_STATE.CONTINUE_CURRENT_WAIT]: "Remain in outer wait and re-inspect after the bounded interval.",
   [OUTER_STATE.HANDOFF_TO_COPILOT_LOOP]: "Re-enter the Copilot loop.",

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

@@ -148,6 +148,30 @@ function isBlockedCiStatus(status) {
   return status === "failure";
 }
 
+/**
+ * Single source of truth for whether the Copilot review round cap has been
+ * reached (issue #1126). `copilot-pr-handoff.mjs` enforces the cap by calling
+ * `interpretLoopState`, which uses this predicate internally; every other
+ * caller that needs the same "cap reached" boolean (gate coordination,
+ * detect-pr-gate-coordination-state) MUST call this function too rather than
+ * re-deriving `copilotReviewRoundCount >= maxCopilotRounds` locally, so the
+ * two never disagree at the cap boundary.
+ *
+ * `copilotReviewRoundCount` counts COMPLETED rounds, so `>=` means every
+ * permitted round has already happened. `maxCopilotRounds` of `null`/`0`/
+ * non-number means the cap does not apply (unlimited or disabled).
+ *
+ * @param {object} params
+ * @param {number} params.copilotReviewRoundCount
+ * @param {number|null} [params.maxCopilotRounds]
+ * @returns {boolean}
+ */
+export function isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRounds }) {
+  return typeof maxCopilotRounds === "number" && maxCopilotRounds > 0
+    && typeof copilotReviewRoundCount === "number"
+    && copilotReviewRoundCount >= maxCopilotRounds;
+}
+
 export function normalizeCiStatus(rollup) {
   return normalizeStatusCheckRollupContract(rollup).overallStatus;
 }
@@ -375,8 +399,7 @@ export function interpretLoopState(snapshot, refinementConfig) {
   const maxRounds = refinementConfig?.maxCopilotRounds;
   const reviewInFlight = s.copilotReviewRequestStatus === "requested"
     || s.copilotReviewRequestStatus === "already-requested";
-  if (typeof maxRounds === "number" && maxRounds > 0
-      && s.copilotReviewRoundCount >= maxRounds
+  if (isCopilotRoundCapReached({ copilotReviewRoundCount: s.copilotReviewRoundCount, maxCopilotRounds: maxRounds })
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {

package/src/loop/gate-fanin.mjs

@@ -24,6 +24,98 @@
 const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
 const VALID_VERDICTS = new Set(["clean", "findings_present"]);
 
+/**
+ * Canonical fail-closed signal for when a child/agent cannot perform real
+ * parallel fan-out (e.g. the harness does not honor the subagent tool at child
+ * depth). The flow MUST fail closed with this message and route the gate review
+ * to the conductor rather than silently degrading to a single-agent inline
+ * review (which requireFanoutProvenance is designed to reject). Documented as a
+ * contract in docs/gate-review-sub-loop-contract.md.
+ */
+export const FANOUT_UNAVAILABLE_MESSAGE = "fan-out unavailable — route to conductor";
+
+/**
+ * Build a fail-closed Error carrying the route-to-conductor contract signal.
+ * Callers throw this (or check `.routeToConductor === true`) when real fan-out
+ * cannot be performed. `detail` is appended for diagnostics but the stable,
+ * matchable prefix is always {@link FANOUT_UNAVAILABLE_MESSAGE}.
+ *
+ * @param {string} [detail] — optional diagnostic suffix (e.g. why fan-out failed)
+ * @returns {Error & { routeToConductor: true, code: "FANOUT_UNAVAILABLE" }}
+ */
+export function fanoutUnavailableError(detail) {
+  const suffix = typeof detail === "string" && detail.trim().length > 0 ? ` (${detail.trim()})` : "";
+  const error = new Error(`${FANOUT_UNAVAILABLE_MESSAGE}${suffix}`);
+  return Object.assign(error, { routeToConductor: /** @type {const} */ (true), code: /** @type {const} */ ("FANOUT_UNAVAILABLE") });
+}
+
+/**
+ * Count DISTINCT reviewer identities actually recorded in a `perAngle` array.
+ * An entry contributes an identity via `reviewer` (preferred) or `dispatchId`;
+ * entries carrying neither are not countable reviewers (a bare `{angle}` proves
+ * nothing about who reviewed it). Pure.
+ *
+ * @param {unknown} perAngle
+ * @returns {number}
+ */
+export function countDistinctReviewers(perAngle) {
+  if (!Array.isArray(perAngle)) return 0;
+  const ids = new Set();
+  for (const e of perAngle) {
+    if (!e || typeof e !== "object" || Array.isArray(e)) continue;
+    const id = typeof e.reviewer === "string" && e.reviewer.trim().length > 0
+      ? e.reviewer.trim()
+      : typeof e.dispatchId === "string" && e.dispatchId.trim().length > 0
+        ? e.dispatchId.trim()
+        : null;
+    if (id) ids.add(id);
+  }
+  return ids.size;
+}
+
+/**
+ * Validate INTERNAL CONSISTENCY of a fan-out provenance object. Returns an error
+ * string when the provenance is malformed or self-inconsistent, or null when it
+ * is well-formed and consistent. Shared by the write path (write-gate-findings-log)
+ * and the enforcement read path (buildPreMergeGateCheck) so both agree.
+ *
+ * Consistency rule (documented in docs/gate-review-sub-loop-contract.md):
+ *   - `distinctReviewers` must be a non-negative integer.
+ *   - `perAngle` must be an array, and non-empty when `distinctReviewers > 0`.
+ *   - `distinctReviewers` must be <= the count of DISTINCT reviewer identities
+ *     actually recorded in `perAngle` — you cannot claim more reviewers than you
+ *     recorded dispatch entries for.
+ *
+ * HONEST CAVEAT: this makes recorded provenance internally consistent and raises
+ * the bar, but the provenance is self-reported (written by the same agent whose
+ * independence it claims), so it remains forgeable by a determined single agent.
+ * Un-forgeable recording is the Pi-harness bridge (subagent tool at child depth).
+ *
+ * @param {unknown} prov
+ * @returns {string|null}
+ */
+export function provenanceConsistencyError(prov) {
+  if (!prov || typeof prov !== "object" || Array.isArray(prov)) {
+    return "provenance must be an object";
+  }
+  const p = /** @type {Record<string, unknown>} */ (prov);
+  if (!Number.isInteger(p.distinctReviewers) || /** @type {number} */ (p.distinctReviewers) < 0) {
+    return "provenance.distinctReviewers must be a non-negative integer";
+  }
+  if (!Array.isArray(p.perAngle)) {
+    return "provenance.perAngle must be an array";
+  }
+  const claimed = /** @type {number} */ (p.distinctReviewers);
+  if (claimed > 0 && p.perAngle.length === 0) {
+    return "provenance.perAngle must be non-empty when distinctReviewers > 0";
+  }
+  const recorded = countDistinctReviewers(p.perAngle);
+  if (claimed > recorded) {
+    return `provenance.distinctReviewers (${claimed}) exceeds distinct recorded reviewer identities (${recorded})`;
+  }
+  return null;
+}
+
 /**
  * Default cap on parallel fan-out reviewers when a caller does not supply one.
  * Mirrors the config default (gates.maxFanoutReviewers).