@dev-loops/core 1.0.3 → 1.0.4-pre.1

package/src/github/copilot-helpers.mjs

@@ -11,20 +11,71 @@ import { trimmedOrNull } from "../loop/normalize.mjs";
 // review is.
 export const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 
-// Copilot's COMMENTED review summary opens with a disposition header whose
-// emoji is the authoritative signal: "### 🟡 Changes recommended" (findings)
-// vs "### 🟢 Approval recommended" (clean). Keying on the 🟡 marker means a
-// clean body that merely quotes the phrase "changes recommended" — with or
-// without markdown emphasis ("No **changes recommended**", "No _changes
-// recommended_") — is never a false finding. The strong no-emoji signal is
-// already covered by the CHANGES_REQUESTED state.
-const COPILOT_CHANGES_RECOMMENDED_MARKER = "🟡";
+// Copilot's `ccr-overview-v2` COMMENTED review opens with ONE of three
+// disposition headers: "### 🟢 Approval recommended" (clean), "### 🟡 Changes
+// recommended" (findings), or "### 🔵 Needs a closer look" (non-approval, the
+// reviewer is uncertain). All Copilot reviews are COMMENTED, so this header is
+// the only body signal. We match the disposition by its TEXT, not the emoji:
+// the old 🟡-only key read the 🔵 "Needs a closer look" non-approval as clean
+// and would fail-open on any future glyph change. Line-anchor the disposition
+// header (`^###\s+`, multiline) with the emoji optional so a body merely
+// QUOTING a phrase ("No changes recommended") never false-positives.
+const COPILOT_DISPOSITION_HEADER_RE = /^###\s+(.+)$/mu;
+// Strip a leading emoji/glyph run (any leading non-letters) so the text alone
+// is compared, then lowercase for a case-insensitive disposition lookup.
+const COPILOT_DISPOSITION_LEADING_GLYPHS_RE = /^[^\p{L}]+/u;
+const COPILOT_CLEAN_DISPOSITION = "approval recommended";
+const COPILOT_CHANGES_RECOMMENDED_DISPOSITION = "changes recommended";
+const COPILOT_NEEDS_CLOSER_LOOK_DISPOSITION = "needs a closer look";
+
+// Canonical current-head Copilot review body dispositions. `changes_recommended`
+// (🟡) and `unrecognized` are actionable non-approvals; `needs_closer_look` (🔵)
+// is a soft, conductor-overridable non-approval; `clean` (🟢) and `none` (no
+// disposition header) are not findings. Both the loop-block signal
+// (copilotReviewBodySignalsChanges) and the merge-convergence precondition read
+// the SAME classification, so the two can never drift.
+export const COPILOT_DISPOSITION = Object.freeze({
+  CLEAN: "clean",
+  CHANGES_RECOMMENDED: "changes_recommended",
+  NEEDS_CLOSER_LOOK: "needs_closer_look",
+  UNRECOGNIZED: "unrecognized",
+  NONE: "none",
+});
 
-export function copilotReviewBodySignalsChanges(state, body) {
+/**
+ * Classify a Copilot review's current-head body disposition. Text-matched (not
+ * emoji-keyed) so a glyph change never silently reclassifies. Fails closed: an
+ * unrecognized `### ` disposition header returns UNRECOGNIZED (an actionable
+ * non-approval), so a future format change degrades safe.
+ */
+export function classifyCopilotReviewBodyDisposition(state, body) {
   const normalizedState = typeof state === "string" ? state.toUpperCase() : "";
-  if (normalizedState === "CHANGES_REQUESTED") return true;
-  if (normalizedState !== "COMMENTED") return false;
-  return typeof body === "string" && body.includes(COPILOT_CHANGES_RECOMMENDED_MARKER);
+  // A human-style CHANGES_REQUESTED is always actionable regardless of body.
+  if (normalizedState === "CHANGES_REQUESTED") return COPILOT_DISPOSITION.CHANGES_RECOMMENDED;
+  if (normalizedState !== "COMMENTED") return COPILOT_DISPOSITION.NONE;
+  if (typeof body !== "string") return COPILOT_DISPOSITION.NONE;
+
+  const headerMatch = body.match(COPILOT_DISPOSITION_HEADER_RE);
+  // No disposition header at all (empty body, generic footer, legacy format):
+  // no body signal, so this is not a finding.
+  if (!headerMatch) return COPILOT_DISPOSITION.NONE;
+
+  const disposition = headerMatch[1]
+    .replace(COPILOT_DISPOSITION_LEADING_GLYPHS_RE, "")
+    .trim()
+    .toLowerCase();
+  if (disposition === COPILOT_CLEAN_DISPOSITION) return COPILOT_DISPOSITION.CLEAN;
+  if (disposition === COPILOT_CHANGES_RECOMMENDED_DISPOSITION) return COPILOT_DISPOSITION.CHANGES_RECOMMENDED;
+  if (disposition === COPILOT_NEEDS_CLOSER_LOOK_DISPOSITION) return COPILOT_DISPOSITION.NEEDS_CLOSER_LOOK;
+  // Fail closed on an unrecognized disposition header on the current head.
+  return COPILOT_DISPOSITION.UNRECOGNIZED;
+}
+
+export function copilotReviewBodySignalsChanges(state, body) {
+  const disposition = classifyCopilotReviewBodyDisposition(state, body);
+  return disposition === COPILOT_DISPOSITION.CHANGES_RECOMMENDED
+    || disposition === COPILOT_DISPOSITION.NEEDS_CLOSER_LOOK
+    || disposition === COPILOT_DISPOSITION.UNRECOGNIZED;
 }
 const GATE_REVIEW_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
 // `review` is a RECOGNIZED gate header that carries no draft/pre-approval
@@ -213,7 +264,7 @@ export function sanitizeCopilotSummonTokens(text) {
 // line) from `text`, leaving only bare-text markdown to scan. Unlike
 // transformNonFencedLines, fenced content here must be REMOVED, not kept:
 // leaving it would let bare text inside a fence still match the summon scan.
-function stripMarkdownCodeForScan(text) {
+export function stripMarkdownCodeForScan(text) {
   const lines = String(text).split(/\r?\n/);
   let inFencedBlock = false;
   let fencedDelimiter = "";
@@ -259,7 +310,8 @@ export function normalizeTimestamp(value) {
 export function extractReviewCommitSha(review) {
   const graphqlSha = typeof review?.commit?.oid === "string" ? review.commit.oid.trim() : "";
   const restSha = typeof review?.commit_id === "string" ? review.commit_id.trim() : "";
-  const sha = graphqlSha || restSha;
+  const camelCaseSha = typeof review?.commitId === "string" ? review.commitId.trim() : "";
+  const sha = graphqlSha || restSha || camelCaseSha;
   return sha.length > 0 ? sha : null;
 }
 
@@ -717,6 +769,11 @@ export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs }
   let hasSubmittedReviewOnCurrentHead = false;
   let latestSubmittedReviewOnCurrentHeadAt = null;
   let hasBodyFindingOnCurrentHead = false;
+  // The id of the review whose body set hasBodyFindingOnCurrentHead: the
+  // review a copilot-body-disposition record must name to clear the finding.
+  // Updated on every branch that updates hasBodyFindingOnCurrentHead so the two
+  // never drift.
+  let bodyFindingReviewId = null;
   let completedCopilotReviewRounds = 0;
 
   for (const review of effectiveReviews) {
@@ -742,21 +799,28 @@ export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs }
       const submittedAt = typeof review?.submittedAt === "string"
         ? review.submittedAt
         : (typeof review?.submitted_at === "string" ? review.submitted_at : null);
+      const reviewId = review?.id !== null && review?.id !== undefined ? String(review.id) : null;
       if (submittedAt !== null && (latestSubmittedReviewOnCurrentHeadAt === null || submittedAt > latestSubmittedReviewOnCurrentHeadAt)) {
         latestSubmittedReviewOnCurrentHeadAt = submittedAt;
         hasBodyFindingOnCurrentHead = copilotReviewBodySignalsChanges(state, review?.body);
-      } else if (submittedAt !== null && submittedAt === latestSubmittedReviewOnCurrentHeadAt) {
-        // Equal-timestamp tie on the same head: fail toward surfacing so array
-        // order never silently drops a finding when two reviews share a timestamp.
-        hasBodyFindingOnCurrentHead = hasBodyFindingOnCurrentHead || copilotReviewBodySignalsChanges(state, review?.body);
-      } else if (submittedAt === null && latestSubmittedReviewOnCurrentHeadAt === null) {
-        hasBodyFindingOnCurrentHead = hasBodyFindingOnCurrentHead || copilotReviewBodySignalsChanges(state, review?.body);
+        bodyFindingReviewId = hasBodyFindingOnCurrentHead ? reviewId : null;
+      } else if (submittedAt === latestSubmittedReviewOnCurrentHeadAt) {
+        // Equal-timestamp (or both-null) tie on the same head: fail toward
+        // surfacing so array order never silently drops a finding. When two
+        // tied reviews both signal, no single review owns the finding, so
+        // bodyFindingReviewId is null and no disposition record can clear it.
+        const tieSignals = copilotReviewBodySignalsChanges(state, review?.body);
+        if (tieSignals) {
+          bodyFindingReviewId = hasBodyFindingOnCurrentHead ? null : reviewId;
+        }
+        hasBodyFindingOnCurrentHead = hasBodyFindingOnCurrentHead || tieSignals;
       }
     }
   }
 
   return {
     copilotReviews,
+    effectiveCopilotReviews: effectiveReviews,
     copilotReviewIds: copilotReviews
       .map((review) => review?.id)
       .filter((id) => id !== null && id !== undefined)
@@ -767,5 +831,6 @@ export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs }
     hasSubmittedReviewOnCurrentHead,
     latestSubmittedReviewOnCurrentHeadAt,
     hasBodyFindingOnCurrentHead,
+    bodyFindingReviewId,
   };
 }

package/src/github/gh.mjs

@@ -67,7 +67,8 @@ export async function ghJson(args, { env, ghCommand = "gh", runChild = defaultRu
  * @param {typeof defaultRunChild} [runChild] - injectable child-exec seam.
  * @param {object} [opts]
  * @param {boolean} [opts.allowErrors] - when true, a GraphQL `errors` array
- *   in the response is returned instead of thrown.
+ *   in the response is returned instead of thrown. This includes a non-zero
+ *   `gh` exit whose stdout is JSON with an `errors` array.
  */
 export async function ghGraphql(query, vars, env, runChild = defaultRunChild, { allowErrors = false } = {}) {
   const fieldArgs = [];
@@ -80,6 +81,18 @@ export async function ghGraphql(query, vars, env, runChild = defaultRunChild, {
     env,
   );
   if (result.code !== 0) {
+    // `gh api graphql` exits non-zero when the response carries GraphQL
+    // `errors` (e.g. NOT_FOUND) but still prints the JSON on stdout. With
+    // allowErrors the caller wants that errors array, so return it.
+    if (allowErrors) {
+      let errorPayload = null;
+      try {
+        errorPayload = JSON.parse(result.stdout);
+      } catch {
+        // not JSON: fall through to GH_API_ERROR
+      }
+      if (Array.isArray(errorPayload?.errors)) return errorPayload;
+    }
     const detail = result.stderr.trim() || `exit code ${result.code}`;
     throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
   }

package/src/github/review-threads.mjs

@@ -121,6 +121,11 @@ export function parseReviewThreads(payload) {
   const threads = rawThreads.map((thread, threadIndex) => {
     const threadId = normalizeId(thread?.id ?? thread?.databaseId, `thread-${threadIndex + 1}`);
     const isResolved = Boolean(thread?.isResolved);
+    // The review that opened the thread: the root (first) comment's
+    // pullRequestReview id. null when the payload does not carry it, so a
+    // consumer that needs attribution treats the thread as unattributed.
+    const rootReviewId = extractRawComments(thread)[0]?.pullRequestReview?.id;
+    const reviewId = typeof rootReviewId === "string" && rootReviewId.length > 0 ? rootReviewId : null;
     const normalizedComments = extractRawComments(thread)
       .map((comment, commentIndex) => normalizeComment(comment, threadId, commentIndex, { isResolved }))
       .sort((left, right) => compareIds(left.id, right.id));
@@ -141,6 +146,7 @@ export function parseReviewThreads(payload) {
     return {
       id: threadId,
       isResolved,
+      reviewId,
       isActionable: actionableCommentIds.length > 0,
       commentIds,
       commentDatabaseIds,

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

@@ -235,6 +235,34 @@ function shellSegments(command) {
  */
 const SHELL_EXEC_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
 
+/**
+ * Leading prefix a code-verification/build command may carry before its real executable: the
+ * shared `SHELL_EXEC_PREFIX` (env assignments, `command`/`env`/`exec` wrapper words, binary path)
+ * plus `nice`/`timeout` process wrappers, scoped to this classifier only so the sibling `gh`/`git`
+ * classifiers above are not broadened by wrapper forms they never need to tolerate. Covers bare
+ * `nice`, `nice -n <N>`, bare `timeout <duration>`, and `timeout` carrying `-s <sig>`/`-k <dur>`/
+ * `--signal=<sig>`/`--kill-after=<dur>`/`--preserve-status`/`--foreground` before the duration —
+ * the wrapper forms the coordinator's daily verify/build commands are routinely run behind
+ * (`timeout 600 bun run verify`, `nice -n 10 bun run verify`). Not a full flag parser: other
+ * `timeout`/`nice` flags are a known, deliberately uncovered ceiling.
+ *
+ * The `env` wrapper word additionally tolerates zero-or-more trailing `NAME=value` assignments
+ * before the real executable (`env CI=1 bun run verify`, `env CI=1 FOO=bar npm test`) — the common
+ * everyday `env VAR=value ... cmd` CI-invocation shape, on top of the bare-leading-assignment form
+ * (`CI=1 bun run verify`) already covered by the shared assignment run at the front of this prefix.
+ * It also tolerates the common `env` OPTION forms (mixed freely with `NAME=value` assignments, in
+ * any order/count): `-i`/`--ignore-environment`, `-u <NAME>`/`--unset=<NAME>`, `-C <dir>`/
+ * `--chdir=<dir>`, `-S <str>`/`--split-string=<str>`, a bare `-`, and `--` — so
+ * `env -u DEVLOOPS_COORDINATOR_READONLY bun run verify`, `env -i bun run verify`, and
+ * `env -u FOO CI=1 npm test` all match. Closes the cheap classifier gap where an `env` flag (rather
+ * than a `NAME=value` assignment) reached the executable unclassified. Not a full `env` flag parser:
+ * any other/exotic `env` option is a known, deliberately uncovered ceiling (documented, not chased).
+ * `command`/`exec` do not get the same trailing-assignment/option tolerance — no known daily
+ * invocation shape needs it, and adding it would only widen the pattern without a use case.
+ */
+const VERIFY_EXEC_PREFIX =
+  "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:env(?:\\s+(?:[A-Za-z_][A-Za-z0-9_]*=\\S*|-i|--ignore-environment|-u\\s+\\S+|--unset=\\S+|-C\\s+\\S+|--chdir=\\S+|-S\\s+\\S+|--split-string=\\S+|--|-))*\\s+|(?:command|exec)\\s+|nice(?:\\s+-n\\s+\\S+)?\\s+|timeout(?:\\s+(?:-s\\s+\\S+|-k\\s+\\S+|--signal=\\S+|--kill-after=\\S+|--preserve-status|--foreground))*\\s+\\S+\\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`,
@@ -802,29 +830,197 @@ export function commandContainsCopilotSummonComment(command) {
 }
 
 /**
- * COPILOT-FOLLOWUP-WAIT-TOOLS: a banned detached/polling wait — `nohup`, `disown`, `tmux new-session`,
- * `screen -dm`, or a `while`/`until`/`seq` loop whose body contains both a `sleep` and a gh or
- * loop-state call. Behavioral rule (required-rules classification `agent`): scoped in decideBashGate to the
- * dev-loop driving agent (subagent-only) so the main agent/operator retains manual wait tooling.
+ * Blank the CONTENTS of quoted string literals ('...' and "...") to a space, EXCEPT a quote that is
+ * the payload of an executable-code flag — a short-flag cluster CONTAINING `c` ANYWHERE in the
+ * cluster (`sh -c '…'`, `bash -c '…'`, `bash -lc '…'`, `bash -ec '…'`, `bash -cl '…'`, `bash -ci '…'`,
+ * `bash -cx '…'`) — bash treats ANY `-c`-containing short-flag cluster as command-execution
+ * regardless of where `c` sits in the cluster, not only one that ENDS in `c` — optionally followed by
+ * a `--` terminator (`bash -c -- '…'`), a long `--command` flag, or `eval` — that payload is REAL
+ * shell syntax to be executed, not inert data, so blanking it would hide an actual poll-loop
+ * construct wrapped in one of these forms. A real poll loop's structural tokens
+ * (`while`/`until`/`for`/`do`/`sleep`/`done`, a `[ -f … ]` file test) are UNQUOTED shell syntax; a
+ * quoted issue body, `--body` payload, or quoted example that merely mentions them carries them
+ * INSIDE quotes as inert data. Blanking those quoted contents is what lets the poll-loop matchers key
+ * on an actual loop CONSTRUCT rather than the token sequence appearing anywhere in a command
+ * (`gh issue create --body "while … sleep … done"` must not be flagged). The `s` (dotAll) flag lets
+ * `.` match a newline too, so a MULTI-LINE quoted `--body` (a real issue body commonly spans lines) is
+ * stripped in full, not just its first line.
+ * A quoted string that itself contains a command substitution (`$(...)`) or a backtick (`` `...` ``)
+ * is executable code, not inert data — its inner command runs regardless of the surrounding quotes.
+ * Blanking it would hide a real poll loop such as `while [ "$(gh pr view 5)" != MERGED ]; do sleep 5;
+ * done` that the gh/loop-state ban already denies, so such a quoted literal is PRESERVED (fail-closed
+ * direction) ahead of the `-c`/`--command`/`eval` exemption check below.
+ *
+ * The `-c`-cluster/`--command`/`eval` exemption is intentionally coarse in the fail-closed direction:
+ * it looks only for a `c` anywhere in a preceding short-flag cluster (or `--command`/`eval`), not for
+ * a shell-interpreter anchor. A non-shell command carrying `-c` (e.g. `grep -ci '<loop text>'`,
+ * `wc -c`) may therefore have its quoted argument preserved too and get over-denied — an accepted
+ * benign false positive, because tightening the exemption to a shell-interpreter anchor would risk a
+ * fail-open (missing a real `sh -c` poll loop), the worse direction.
+ *
+ * ponytail: blanks balanced quote pairs only, with the command-substitution/backtick preserve rule
+ * and the `-c`-cluster/`--command`/`eval` exemption above — no full shell tokenizer (mismatched/
+ * partial quotes and other exec-wrapper flags stay out of scope). Accepted ceiling: a deliberately
+ * quoted structural keyword (e.g. `"sleep"`) placed inside a real UNQUOTED loop is blanked like any
+ * other quoted literal and can therefore evade the ban — accepted as a deliberate-evasion class, not
+ * a natural shape a genuine poll loop takes.
+ * @param {string} command @returns {string}
+ */
+function stripQuotedLiterals(command) {
+  return command.replace(/(['"])((?:(?!\1).)*)\1/gs, (match, _quote, inner, offset, full) => {
+    // A quoted string containing a command substitution ($()) or backtick is executable code, not
+    // inert data — its command runs regardless of the surrounding quotes. Blanking it would hide a
+    // real poll loop such as `while [ "$(gh pr view 5)" != MERGED ]; do sleep 5; done` that the
+    // gh/loop-state ban already denied. Preserve it (fail-closed direction).
+    if (/\$\(|`/.test(inner)) {
+      return match;
+    }
+    const before = full.slice(0, offset);
+    if (/(?:^|\s)(?:-[A-Za-z]*c[A-Za-z]*(?:\s+--)?|--command|eval)\s*$/.test(before)) {
+      return match; // executable -c/eval payload — leave the real shell syntax intact
+    }
+    return " ";
+  });
+}
+
+/**
+ * Whether COMMAND is (or contains) a sleep-poll loop over `gh`/`loop-state` — a `while`/`until`/
+ * `for` loop whose body contains both a `sleep` and a `gh` or `loop-state` call. Checked on the
+ * WHOLE command (not per-segment): the loop body is `;`-delimited, so a per-segment split would
+ * separate the loop head from its `sleep`/`gh` body calls and miss the pattern. `gh` must be a
+ * standalone token (not `grep gh-notes`), and `loop-state` must sit at a command-head position
+ * (not a substring inside `grep loop-state x`). Quoted literals are blanked first (see
+ * `stripQuotedLiterals`) so a quoted body/example that merely contains the tokens is not flagged.
+ * @param {string} command @returns {boolean}
+ */
+export function commandIsSleepPollLoop(command) {
+  const whole = stripQuotedLiterals(command.trim());
+  return (
+    /(?:while|until|for)\b/i.test(whole) &&
+    /\bsleep\b/.test(whole) &&
+    /\bgh(?=\s|$)|(?:^|[;&|(])\s*loop-state(?=\s|$)/.test(whole)
+  );
+}
+
+/**
+ * Whether COMMAND is (or contains) a bare FILE-MARKER poll loop: a `while`/`until`/`for` loop that
+ * repeatedly tests for a file's existence/type/permission (`[ -f … ]`, `[[ -e … ]]`, `test -f …`,
+ * `[ -r … ]`, `[ -L … ]`) and sleeps, with NO gated wait-tool. This is the orphan pattern under
+ * Claude Code — a `<tasks>/<id>.done` sentinel Claude Code never writes (completion arrives via
+ * async notification), so the loop never exits and, once backgrounded, orphans with no async wake to
+ * reap it. Distinct from `commandIsSleepPollLoop`, which keys on a `gh`/`loop-state` CALL: this keys
+ * on any bash FILE-test operator (existence, type, or permission — `efsdrwxugkOGLNShb`; string/numeric
+ * tests like `-z`/`-n`/`-t` are deliberately excluded, as those never test a marker FILE), catching a
+ * marker poll that calls no gh/loop-state at all. Verb-independent (while/until/for). Quoted literals
+ * are blanked first (see `stripQuotedLiterals`) so a quoted example or `--body` payload that merely
+ * contains the tokens is NOT flagged.
+ * @param {string} command @returns {boolean}
+ */
+export function commandIsFileMarkerPollLoop(command) {
+  const whole = stripQuotedLiterals(command.trim());
+  return (
+    /(?:while|until|for)\b/i.test(whole) &&
+    /\bsleep\b/.test(whole) &&
+    /(?:\[\[?|\btest\b)\s+(?:!\s+)?-[a-hkprsuwxGLNOS]\b/.test(whole)
+  );
+}
+
+/**
+ * Whether COMMAND contains a bare `&` backgrounding control operator — not `&&` (logical AND) and
+ * not a redirection (`2>&1`, `>&2`, `&>file`, `&>>file`). A coarse whole-string check (no shell
+ * parse): redirection forms are stripped first, then any surviving lone `&` (not immediately
+ * preceded or followed by another `&`) counts.
+ * @param {string} command @returns {boolean}
+ */
+function commandHasBareBackgroundOperator(command) {
+  const withoutRedir = command
+    .replace(/\d*>&\d*-?/g, " ") // 2>&1, 1>&2, >&2, >&-
+    .replace(/&>>?/g, " "); // &>file, &>>file
+  return /(?<!&)&(?!&)/.test(withoutRedir);
+}
+
+/**
+ * The wait/probe helper FAMILY: the Copilot/CI wait tools that MUST run as a bounded FOREGROUND
+ * probe — the `.mjs` helpers (`probe-copilot-review`, `wait-pr-checks`, `detect-copilot-loop-state`,
+ * `run-watch-cycle`, `probe-ci-status` — the sanctioned `ci-status`/`watch-ci` CI-status wait,
+ * skills/dev-loop/SKILL.md's "PR checks/status" entry), `gh run watch`, and the
+ * `dev-loops`/`dev-loops-run` `watch-cycle`/`watch-ci`/`watch-initial`/`gate probe-copilot` CLI
+ * verbs. A coarse ANYWHERE-in-the-string substring/family match (deliberately NOT exec-position
+ * anchored) — see `commandContainsDetachedWaitTool`'s JSDoc for the fail-closed rationale.
+ */
+const WAIT_PROBE_FAMILY_RE = new RegExp(
+  [
+    "probe-copilot-review\\.mjs",
+    "wait-pr-checks\\.mjs",
+    "detect-copilot-loop-state\\.mjs",
+    "run-watch-cycle\\.mjs",
+    "probe-ci-status\\.mjs",
+    "gh\\s+run\\s+watch",
+    "watch-cycle",
+    "watch-ci",
+    "watch-initial",
+    "probe-copilot",
+  ].join("|"),
+  "i",
+);
+
+/**
+ * COPILOT-FOLLOWUP-WAIT-TOOLS: a banned detached/polling wait. This is a UNION of three
+ * independent deny conditions — NOT one big AND (an AND-condition here would inadvertently
+ * narrow the unconditional detach-wrapper ban below to "detach AND family reference", wrongly
+ * allowing a family-less `nohup node build.mjs &`):
+ *
+ *   (1) `nohup`/`disown`/`tmux new-session`/`screen -dm` anywhere in a command segment — denied
+ *       UNCONDITIONALLY, with NO wait/probe-family requirement.
+ *   (2) A `while`/`until`/`for` sleep-poll loop over `gh`/`loop-state` (`commandIsSleepPollLoop`) —
+ *       denied UNCONDITIONALLY — it IS the backgrounding signal.
+ *   (3) OPTION-C, prevention-only scope: a bare `&` background (`commandHasBareBackgroundOperator`,
+ *       including a `timeout …`/`env …`/`sh -c` wrapper of it) that ALSO references the wait/probe
+ *       FAMILY anywhere in the command string (`WAIT_PROBE_FAMILY_RE`) — a coarse substring/family
+ *       match, deliberately NOT exec-position anchored.
+ *
+ * Because (3)'s family match is coarse (anywhere in the string, not the executed token), NO wrapper
+ * can hide the reference from it: `timeout N … &`, `env … &`, `sh -c '… &'`, or a node loader flag
+ * (`node -r ./loader.mjs …/probe-copilot-review.mjs &`, `--require`/`--loader`/`--import`) all still
+ * carry the family token in the backgrounded command text, so all are denied. This trades precision
+ * for guaranteed coverage: a background command that merely MENTIONS a family name as an unrelated
+ * argument (`echo "see probe-copilot-review.mjs" &`) is also denied — a benign false positive,
+ * sanctioned by the issue's non-goals (this is a prevention gate, not an exec-position parser; a
+ * denied benign command simply falls back to the sanctioned foreground path). The precise
+ * exec-position parser this replaced (and the SubagentStop background-shell reaper it fed) is
+ * deferred to a follow-up safety-net effort.
+ *
+ * Actor-independent at the decideBashGate call site: the coordinator/main agent — not only a
+ * subagent — is the actor that leaves these orphaned under Claude Code (no async wake to join a
+ * backgrounded wait), so the gate catches its backgrounding too.
  * @param {string} command @returns {boolean}
  */
 export function commandContainsDetachedWaitTool(command) {
   const whole = command.trim();
-  // Checked on the WHOLE command (not per-segment): the `while`/`until`/`for` loop body is
-  // `;`-delimited, so a per-segment split would separate the loop head from its `sleep`/`gh`
-  // body calls and miss the pattern. `gh` must be a standalone token (not `grep gh-notes`), and
-  // `loop-state` must sit at a command-head position (not a substring inside `grep loop-state x`).
-  if (/(?:while|until|for)\b/i.test(whole) && /\bsleep\b/.test(whole) && /\bgh(?=\s|$)|(?:^|[;&|(])\s*loop-state(?=\s|$)/.test(whole)) {
-    return true;
-  }
-  return shellSegments(command).some((segment) => {
-    // `nohup`/`disown` only detach when they head a command (segment start, or right after a shell
-    // operator) — a bare mention (`cat nohup.out`, `echo "nohup banned"`) is not a detach.
+
+  // (1) Unconditional detach-wrapper ban — no wait/probe-family requirement.
+  const hasDetachWrapper = shellSegments(command).some((segment) => {
+    // `nohup`/`disown` only detach when they head a command (segment start, or right after a
+    // shell operator) — a bare mention (`cat nohup.out`, `echo "nohup banned"`) is not a detach.
     if (/(?:^|[;&|])\s*(?:nohup|disown)\b/.test(segment)) return true;
     if (/^tmux\s+new-session\b/i.test(segment)) return true;
     if (/^screen\s+-dm/i.test(segment)) return true;
     return false;
   });
+  if (hasDetachWrapper) {
+    return true;
+  }
+
+  // (2) Unconditional sleep-poll-loop ban — a gh/loop-state poll OR a bare file-marker poll.
+  if (commandIsSleepPollLoop(whole) || commandIsFileMarkerPollLoop(whole)) {
+    return true;
+  }
+
+  // (3) OPTION-C: bare-`&` background AND a wait/probe family reference.
+  if (!commandHasBareBackgroundOperator(whole)) {
+    return false;
+  }
+  return WAIT_PROBE_FAMILY_RE.test(whole);
 }
 
 /** Build a `node`/`python`/`python3` command-head matcher (env/wrapper/path prefix tolerated). */
@@ -875,3 +1071,44 @@ export function commandContainsInlineInterpreter(command) {
     return false;
   });
 }
+
+/**
+ * A package-manager `test`/`verify`/`build` script/task invocation, the `run` keyword optional
+ * (`npm test`, `npm run test`, `bun run verify`, `yarn build`, `pnpm run build`, ...). Anchored on
+ * the executable HEAD (env-assignment/wrapper/path/nice/timeout prefix tolerated via
+ * `VERIFY_EXEC_PREFIX`) so a path that merely contains the word "test" (`cat test/foo.test.mjs`)
+ * never matches — the head token must literally be one of these four package-manager binaries.
+ *
+ * Tolerates a run of binary flags between the binary and `run`/the script name (`bun --bun run
+ * verify`), and a `:`-namespaced sub-script (`test:extension`, `test:core`, `verify:docs`, ...) —
+ * the tail is `(?:[:\s]|$)` rather than `(?:\s|$)` so `npm run test:unit` / `yarn test:ci` match
+ * while `npm run build-docs` (hyphen form, a genuinely different script name) still does not.
+ */
+const PACKAGE_MANAGER_VERIFY_RUN_RE = new RegExp(
+  `^${VERIFY_EXEC_PREFIX}(?:bun|npm|yarn|pnpm)(?:\\s+--\\S+)*\\s+(?:run\\s+)?(?:test|verify|build)(?:[:\\s]|$)`,
+  "i",
+);
+
+/**
+ * `vitest` run directly (any args: `vitest`, `vitest run`, `vitest --coverage`), or via the
+ * `npx`/`bunx` package-runner (`npx vitest run`, `bunx vitest`) or `bun`'s `x` subcommand
+ * (`bun x vitest`).
+ */
+const VITEST_RE = new RegExp(`^${VERIFY_EXEC_PREFIX}(?:(?:npx|bunx)\\s+|bun\\s+x\\s+)?vitest(?:\\s|$)`, "i");
+
+/**
+ * COORDINATOR-VERIFY-DELEGATION: whether `command` contains a known code-verification/
+ * build entrypoint in ANY shell segment — `bun test`/`bun run verify`/`bun run build`, `vitest`,
+ * `npm test`/`npm run test`/`npm run build`, and the `yarn`/`pnpm` `test`/`build` equivalents
+ * (with or without the `run` keyword). PreToolUse gate use only: the dev-loop COORDINATOR must
+ * delegate these to a fresh WORKER subagent instead of running them inline; a worker subagent may
+ * run them freely (the actor scoping lives in `decideBashGate`, not here).
+ *
+ * Compact orchestration commands the coordinator MAY still run inline never match — their head
+ * token is not a package-manager binary or `vitest` (`dev-loops queue list`, `gh pr checks --json
+ * --jq`, `detect-checkpoint-evidence`, `git log --oneline -1`, `git status --short`).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsCodeVerificationEntrypoint(command) {
+  return shellSegments(command).some((segment) => PACKAGE_MANAGER_VERIFY_RUN_RE.test(segment) || VITEST_RE.test(segment));
+}

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

@@ -20,16 +20,33 @@ const STATUS_CONTEXT_SUCCESS_STATES = new Set(["SUCCESS"]);
 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
+ * The same workflow ALSO surfaces as check runs under its two job ids
+ * (`gate-evidence-runner`, the compute-heavy detector, and
+ * `gate-evidence-reporter`, the always-settling job that owns the status
+ * above — see docs/decisions/0076) beside the commit status named above, and
+ * all are the loop's own derived signal. Excluding only the status context
+ * left either job'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"]);
+export const LOOP_DERIVED_CI_CHECK_NAMES = Object.freeze([
+  LOOP_DERIVED_CI_CHECK_NAME,
+  "gate-evidence-runner",
+  "gate-evidence-reporter",
+]);
+
+/**
+ * The two Gate-evidence JOB check-run names — the detector and the reporter.
+ * These (and ONLY these, never the `gate-evidence` status name) are the runs
+ * whose superseded CANCELLED check-runs `classifyBenignGateEvidenceUnstable`
+ * treats as cosmetic UNSTABLE noise.
+ */
+export const GATE_EVIDENCE_JOB_CHECK_NAMES = Object.freeze([
+  "gate-evidence-runner",
+  "gate-evidence-reporter",
+]);
 
 function checkEntryName(entry) {
   if (typeof entry?.name === "string" && entry.name.length > 0) return entry.name;
@@ -141,6 +158,27 @@ export function normalizeStatusCheckRollupStatus(rollup) {
   return "none";
 }
 
+/**
+ * Resolve the normalized status of ONE named context/check within a
+ * `statusCheckRollup` (or check-runs-shaped) payload — e.g. whether the
+ * required `gate-evidence` context itself (as opposed to the loop's own
+ * exclusion of it, see `deriveLoopCiStatusFromRollup`) is success, failure,
+ * pending, or absent. Reuses the same name matching
+ * (`partitionEntriesByCheckName`) and state normalization
+ * (`normalizeStatusCheckRollupStatus`) the rollup helpers on this module
+ * already use, so a caller that needs one context's own state (e.g.
+ * merge-pr.mjs naming the real cause of a block on `gate-evidence`) does not
+ * re-derive name matching or status normalization.
+ *
+ * @param {Array<object>} rollup
+ * @param {string} contextName
+ * @returns {"success"|"failure"|"pending"|"none"}
+ */
+export function resolveNamedContextState(rollup, contextName) {
+  const { matched } = partitionEntriesByCheckName(rollup, contextName);
+  return normalizeStatusCheckRollupStatus(matched);
+}
+
 /**
  * Summarize the GitHub check-runs API payload for one head SHA.
  *
@@ -317,6 +355,78 @@ export function normalizeHeadScopedCiContract({
   return buildCiContract(overallStatus);
 }
 
+/**
+ * Classify a `mergeStateStatus === "UNSTABLE"` as BENIGN when the required
+ * `gate-evidence` commit status is itself `success` and the ONLY non-success
+ * rollup entries are superseded Gate-evidence job check-runs (the
+ * `gate-evidence-runner` detector OR the `gate-evidence-reporter`, conclusion
+ * `CANCELLED`).
+ *
+ * Both jobs cancel superseded runs: the detector via `cancel-in-progress`, the
+ * reporter via its non-cancelling group cancelling a still-queued run superseded
+ * by a newer one. Each leaves a `cancelled` check-run on the head, so
+ * `mergeStateStatus` reads `UNSTABLE` on nearly every PR even when the required
+ * `gate-evidence` status on the head is green. The cancellation is correct and
+ * stays (docs/decisions/0076); this classifier only lets a reader distinguish
+ * that cosmetic noise from a real non-success.
+ *
+ * Fail-closed: only an actual `UNSTABLE` with a `success` `gate-evidence` status
+ * and no other non-success entry is benign. A failed (not cancelled) Gate-evidence
+ * job, a non-success `gate-evidence` status, or any other failing/pending check
+ * makes it non-benign.
+ *
+ * ponytail: `gh pr view --json statusCheckRollup` returns a single bounded page
+ * (~100 contexts); a very chatty PR could exceed it and hide a real failure,
+ * failing this open. Acceptable because this is a display-only surface — the
+ * merge path never consults it. Do NOT wire this classifier into a merge
+ * decision without adding pagination.
+ *
+ * @param {Array<object>} rollup A `gh pr view --json statusCheckRollup` payload.
+ * @param {string|null} mergeStateStatus
+ * @returns {{ benign: boolean, reason: string }}
+ */
+export function classifyBenignGateEvidenceUnstable(rollup, mergeStateStatus) {
+  const state = typeof mergeStateStatus === "string" ? mergeStateStatus.toUpperCase() : "";
+  if (state !== "UNSTABLE") {
+    return { benign: false, reason: "mergeStateStatus is not UNSTABLE" };
+  }
+  if (!Array.isArray(rollup)) {
+    return { benign: false, reason: "status rollup unavailable" };
+  }
+  // The required gate-evidence signal is a commit STATUS (a StatusContext,
+  // `.context`), never a check-run (`.name`). Anchor the success guard on the
+  // StatusContext alone so a same-named success check-run can never stand in for
+  // an absent required status (partitionEntriesByCheckName matches `.name` OR
+  // `.context`, so it would otherwise accept either).
+  const gateEvidenceStatusEntries = rollup.filter(
+    (entry) => entry?.context === LOOP_DERIVED_CI_CHECK_NAME && typeof entry?.state === "string",
+  );
+  if (normalizeStatusCheckRollupStatus(gateEvidenceStatusEntries) !== "success") {
+    return { benign: false, reason: "gate-evidence status is not success" };
+  }
+  const offenders = [];
+  for (const entry of rollup) {
+    if (normalizeStatusCheckRollupStatus([entry]) === "success") continue;
+    const name = checkEntryName(entry);
+    const conclusion = typeof entry?.conclusion === "string" ? entry.conclusion.toUpperCase() : "";
+    // Only a cancelled Gate-evidence JOB check-run (runner or reporter) is the
+    // superseded-run artifact this classifier ignores — an explicit two-job
+    // allowlist, not LOOP_DERIVED_CI_CHECK_NAMES (which also carries the
+    // `gate-evidence` status name), so a cancelled entry named `gate-evidence`
+    // can never be waved through as benign.
+    if (GATE_EVIDENCE_JOB_CHECK_NAMES.includes(name) && conclusion === "CANCELLED") continue;
+    const status = typeof entry?.status === "string" ? entry.status.toUpperCase() : "";
+    offenders.push(`${name || "unknown"}=${conclusion || status || "?"}`);
+  }
+  if (offenders.length > 0) {
+    return { benign: false, reason: `non-benign non-success checks present: ${offenders.join(", ")}` };
+  }
+  return {
+    benign: true,
+    reason: "no non-success entry other than superseded Gate-evidence job cancellations; gate-evidence status is success",
+  };
+}
+
 /**
  * Derive a loop-safe CI status from a PR `statusCheckRollup` snapshot: the
  * `LOOP_DERIVED_CI_CHECK_NAMES` entries (the `gate-evidence` status and the