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

package/src/github/comment-id-guard.mjs

@@ -0,0 +1,158 @@
+/**
+ * ISSUE/PR-ID GUARD for generated comment bodies.
+ *
+ * Mandate (#1731, operator directive): generated gate/review/verdict comment
+ * bodies must NEVER emit raw issue or PR ids. Public comment surfaces are
+ * world-readable, and a bare `#<digits>` in a comment body is auto-linked by
+ * GitHub to that issue/PR — leaking internal cross-references and violating
+ * the no-ids-in-comments rule.
+ *
+ * This helper fails CLOSED: it refuses (throws) a body that contains a raw
+ * `#<digits>` token, unless that id is explicitly allowlisted as a deliberate
+ * cross-reference (`allowedRefs`). There is deliberately NO silent stripping —
+ * a stripped id could silently drop a needed cross-ref while still posting;
+ * refusal forces the caller to make the cross-ref deliberate (or reword).
+ *
+ * Wire this into every comment/review write helper that posts a GENERATED
+ * body (verdict comments, gate findings reviews, inline finding comments,
+ * review-thread replies, and the generic comment/edit writers). Applying it at
+ * the low-level POST/PATCH write point means current AND future comment flows
+ * are guarded automatically — a future writer that routes through these
+ * helpers cannot emit an issue/PR id without an explicit allowlist entry.
+ *
+ * Deliberate cross-reference mechanism: pass the id(s) to allow as
+ * `allowedRefs: ["1670"]`. Aside from a genuine HTML numeric character
+ * reference (`&#<digits>;`, e.g. `&#91;` for `[`) — each such OCCURRENCE is
+ * skipped; the same digit run appearing elsewhere as a bare token still
+ * refuses — this is the ONLY sanctioned way a generated comment body may
+ * carry a `#<digits>` token. Extraction is decode-aware on BOTH sides of the
+ * token: the body is also scanned after a single left-to-right decode of the
+ * entity forms GitHub's renderer resolves (numeric character references,
+ * zero-padding and hex included at cmark-gfm's 8-digit bound, plus the named
+ * hash entity),
+ * so a hash or any digit of the id smuggled as an entity — `&#35;123`,
+ * `&num;123`, `#&#49;23`, any mix — still refuses. The decode is single-pass
+ * like the renderer's: a double-encoded form (`&amp;#35;123`) renders as
+ * inert literal text and the decode pass never manufactures a refusal of its
+ * INNER id — though the raw scan still refuses the outer digit run of the
+ * numeric form as a pre-existing fail-closed near-miss (the outer entity's
+ * semicolon sits before the hash, so the well-formed-entity exclusion does
+ * not apply). Case-variants of the named hash entity are decoded too even
+ * where GitHub would not (`&NUM;`): deliberate over-refusal, keeping the
+ * guard fail-closed. Keep the allowlist small and deliberate.
+ */
+
+// Matches a bare GitHub auto-link issue/PR reference: `#<digits>`. Bound to
+// 1..9 digits to avoid absurd ids while covering the full GitHub id space.
+// A match is excluded only when it forms a well-formed HTML numeric character
+// reference — preceded by `&` AND immediately followed by `;` (e.g. `&#91;`,
+// the entity-encoded form of `[`). Any other shape (a bare `#123`, an
+// `&`-preceded run with no terminating `;`, or a `;`-followed run with no
+// preceding `&`) is not a well-formed entity and still refuses as a genuine
+// auto-link candidate.
+const ISSUE_PR_ID_RE = /#(\d{1,9})/g;
+
+function isNumericCharacterReference(body, match) {
+  // The digit bound mirrors cmark-gfm's 8-digit entity parser: a 9-digit
+  // ampersand-wrapped run is NOT decoded by the renderer, so it renders
+  // literally and must not be excluded as a spent entity.
+  return match[1].length <= 8
+    && body[match.index - 1] === "&"
+    && body[match.index + match[0].length] === ";";
+}
+
+// Entity forms the renderer resolves that can participate in assembling a
+// rendered `#<digits>` auto-link: numeric character references (any code
+// point — the hash AND the digits themselves are smuggleable) plus the named
+// hash entity. The digit bounds match cmark-gfm's numeric-entity parser
+// (up to 8 digits, decimal or hex) so nothing GitHub decodes escapes the
+// pass. Single non-rescanning replace = one decode, like the renderer, so a
+// double-encoded form's output is never re-read as a fresh entity.
+const DECODABLE_ENTITY_RE = /&(?:#(?:\d{1,8}|x[0-9a-f]{1,8})|num);/gi;
+
+function decodeRenderedText(body) {
+  return body.replace(DECODABLE_ENTITY_RE, (entity) => {
+    const inner = entity.slice(1, -1).toLowerCase();
+    if (inner === "num") return "#";
+    const code = inner[1] === "x" ? Number.parseInt(inner.slice(2), 16) : Number.parseInt(inner.slice(1), 10);
+    try {
+      return String.fromCodePoint(code);
+    } catch {
+      // cmark substitutes the replacement character for a reference it cannot
+      // decode; mirroring that keeps decodable-shaped text from lingering in
+      // the decoded scan, where it could masquerade as a spent entity.
+      return "�";
+    }
+  });
+}
+
+function collectBareIds(text, found, { excludeEntities }) {
+  for (const m of text.matchAll(ISSUE_PR_ID_RE)) {
+    if (excludeEntities && isNumericCharacterReference(text, m)) continue;
+    found.add(m[1]);
+  }
+}
+
+/**
+ * Extract the raw issue/PR id tokens found in a body (as strings, deduped).
+ * Scans the body as written AND after a single renderer-like entity decode,
+ * so an id assembled from entity-encoded pieces is still found. The entity
+ * exclusion applies only to the RAW scan: in decoded text the renderer's one
+ * decode is already spent, so an ampersand-then-digits-then-semicolon shape
+ * there is plain text a wrapper cannot re-protect (an ampersand-wrapped
+ * encoded hash plus digits must refuse, not hide). Returns [] for non-string
+ * input (and for a body with no `#<digits>`).
+ */
+export function extractIssuePrIds(body) {
+  if (typeof body !== "string" || body.length === 0) return [];
+  const found = new Set();
+  collectBareIds(body, found, { excludeEntities: true });
+  const decoded = decodeRenderedText(body);
+  if (decoded !== body) collectBareIds(decoded, found, { excludeEntities: false });
+  return [...found];
+}
+
+// A caller-supplied allowlist is normally already an array (or other
+// iterable) of ids. Guard the one mis-shaped input that would otherwise
+// silently produce the wrong set: a plain CSV string. `Array.from` over a
+// string character-splits it ("1670" -> ["1","6","7","0"]), which would
+// spuriously allowlist single-digit refs while still refusing the id the
+// caller meant to allow. Mirrors parseAllowedRefsCsv's comma-split (trim,
+// drop empties) — deliberately without its numeric validation, since this is
+// a permissive low-level guard, not the CLI arg parser.
+function normalizeAllowedRefs(allowedRefs) {
+  if (allowedRefs == null) return [];
+  if (typeof allowedRefs === "string") {
+    return allowedRefs.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  return Array.from(allowedRefs, (id) => String(id));
+}
+
+/**
+ * Fail-closed guard: returns `body` unchanged when it contains no raw
+ * issue/PR id (or every id it contains is explicitly allowlisted). Throws
+ * otherwise, refusing to emit the body.
+ *
+ * @param {string} body - the generated comment body to guard.
+ * @param {object} [opts]
+ * @param {string} [opts.ref] - human label for the guarded surface (error context).
+ * @param {Iterable<number|string>|string} [opts.allowedRefs] - explicit
+ *   allowlist of deliberate cross-reference ids permitted to appear in the
+ *   body. A plain string is treated as a comma-separated list (like a CLI
+ *   `--allowed-refs` value), never character-split.
+ * @returns {string} the (unchanged, since no stripping) body.
+ */
+export function guardCommentBodyNoIssuePrIds(body, { ref = "generated comment body", allowedRefs = [] } = {}) {
+  if (typeof body !== "string") return body;
+  const allow = new Set(normalizeAllowedRefs(allowedRefs));
+  const offending = extractIssuePrIds(body).filter((id) => !allow.has(id));
+  if (offending.length > 0) {
+    throw new Error(
+      `comment-id-guard refused to emit ${ref}: contains raw issue/PR id reference(s) ` +
+        `#${offending.join(", #")}. Bare #digits in generated comment bodies violate the ` +
+        `no-ids-in-comments rule (public leakage). Reword to a generic reference, or pass the ` +
+        `id(s) to allowedRefs on the guarded write to make an explicit deliberate cross-reference.`,
+    );
+  }
+  return body;
+}

package/src/github/copilot-helpers.mjs

@@ -6,14 +6,32 @@
  * scripts and other packages/core modules.
  */
 
+import { GATE_REVIEW_VERDICT_SET } from "../loop/policy-constants.mjs";
+import { trimmedOrNull } from "../loop/normalize.mjs";
+
 // 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"]);
+// `review` (the standalone review entrypoint, upsert-checkpoint-verdict.mjs's
+// `--gate review`) is a RECOGNIZED gate header — it is identified, not
+// absent — but carries no draft/pre-approval evidence by design (#1808 AC3).
+// Recognizing it (rather than leaving it unrecognized) is what lets
+// parseGateReviewCommentFields below short-circuit to null the instant a
+// `review` header is seen, instead of falling through to the lenient
+// draft_gate/pre_approval_gate token scan — the fallthrough that previously
+// let a `review` verdict whose findings text merely MENTIONED "draft_gate"
+// get recorded as real draft-gate evidence (a draft-gate bypass).
+const NON_EVIDENCE_GATE_NAMES = new Set(["review"]);
+const RECOGNIZED_GATE_NAMES = new Set([...GATE_REVIEW_NAMES, ...NON_EVIDENCE_GATE_NAMES]);
 const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
+// Size-budget outcome vocabulary — mirrors
+// check-size-budget.mjs's computeSizeBudget outcome enum exactly; this file
+// never recomputes the outcome, only round-trips it through the verdict
+// comment.
+const GATE_SIZE_OUTCOMES = new Set(["pass", "escalate", "block"]);
 
 // The literal header line the gate review body always emits first
 // (upsert-checkpoint-verdict.mjs's renderGateReviewCommentBody, re-exported
@@ -80,6 +98,37 @@ export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
 }
 
+/**
+ * Resolve whether Copilot is present as a reviewer on a PR from the REVIEW
+ * surface only — requested reviewers plus submitted reviews — never from
+ * assignees (#1670).
+ *
+ * Copilot review is configured in two ways: Copilot is either formally listed
+ * in the PR's `requested_reviewers`, or it is a configured auto-reviewer
+ * (`copilot-pull-request-reviewer[bot]`) that submits an actual review without
+ * ever appearing in `requested_reviewers`. Both are review-surface facts.
+ * Assignment is a disjoint surface and must never decide presence: on a
+ * reviewer-configured repo Copilot is never an assignee, so an assignee-based
+ * proxy would falsely report a fully-configured Copilot reviewer as absent and
+ * could let the gate skip the Copilot-convergence requirement on a false premise.
+ *
+ * @param {object} params
+ * @param {boolean} [params.requested] - Copilot is listed in the PR's requested_reviewers
+ * @param {Array<{author?: {login?: string}}>} [params.reviews] - PR review list
+ * @returns {{ present: boolean, sources: string[] }}
+ */
+export function resolveCopilotReviewPresence({ requested = false, reviews = [] } = {}) {
+  const list = Array.isArray(reviews) ? reviews : [];
+  const sources = [];
+  if (requested === true) {
+    sources.push("requested_reviewer");
+  }
+  if (list.some((review) => isCopilotLogin(review?.author?.login))) {
+    sources.push("submitted_review");
+  }
+  return { present: sources.length > 0, sources };
+}
+
 // Anti-summon literal: bare-text `@copilot` or a `/copilot*` slash command. Both
 // the write-side sanitizer and the read-side guard scan key off this shape so a
 // gate-evidence comment can quote the rule (inside a code span/fenced block)
@@ -257,14 +306,19 @@ function stripGateCommentMarkdown(rawLine) {
   return line.trim();
 }
 
+// Recognizes BOTH evidence gates (draft_gate/pre_approval_gate) and the
+// non-evidence `review` gate — parseGateReviewCommentFields below relies on
+// `review` coming back as an identified value (not null) so it can
+// short-circuit to non-evidence explicitly, rather than leaving the field
+// null and falling through to the lenient token-scan fallback.
 function normalizeGateReviewName(value) {
   const normalized = stripOptionalCodeTicks(value).toLowerCase();
-  return GATE_REVIEW_NAMES.has(normalized) ? normalized : null;
+  return RECOGNIZED_GATE_NAMES.has(normalized) ? normalized : null;
 }
 
 function normalizeGateReviewVerdict(value) {
   const normalized = stripOptionalCodeTicks(value).toLowerCase();
-  return GATE_REVIEW_VERDICTS.has(normalized) ? normalized : null;
+  return GATE_REVIEW_VERDICT_SET.has(normalized) ? normalized : null;
 }
 
 function normalizeGateReviewHeadSha(value) {
@@ -277,6 +331,32 @@ function normalizeGateExecutionMode(value) {
   return GATE_EXECUTION_MODES.has(normalized) ? normalized : null;
 }
 
+function normalizeGateSizeOutcome(value) {
+  const normalized = stripOptionalCodeTicks(value).toLowerCase();
+  return GATE_SIZE_OUTCOMES.has(normalized) ? normalized : null;
+}
+
+function normalizeGateSizeTouchesT1(value) {
+  const normalized = stripOptionalCodeTicks(value).toLowerCase();
+  if (normalized === "touched") return true;
+  if (normalized === "not touched") return false;
+  return null;
+}
+
+// "none" | "granted" | "granted by <name>" — the approver name is free text
+// (already sanitized by the poster via sanitizeInline before rendering), so
+// no further normalization beyond trimming is applied here.
+function normalizeGateSizeWaiver(value) {
+  const normalized = stripOptionalCodeTicks(value).trim();
+  if (/^none$/iu.test(normalized)) return { granted: false, approvedBy: null };
+  const grantedMatch = normalized.match(/^granted(?:\s+by\s+(.+))?$/iu);
+  if (grantedMatch) {
+    const approvedBy = grantedMatch[1]?.trim();
+    return { granted: true, approvedBy: approvedBy && approvedBy.length > 0 ? approvedBy : null };
+  }
+  return null;
+}
+
 function parseGateReviewCommentFields(body) {
   if (typeof body !== "string" || body.trim().length === 0) {
     return null;
@@ -290,6 +370,10 @@ function parseGateReviewCommentFields(body) {
     nextAction: null,
     executionMode: null,
     inlineReason: null,
+    sizeOutcome: null,
+    sizeTouchesT1: null,
+    sizeWaiverGranted: null,
+    sizeWaiverApprovedBy: null,
   };
 
   for (const rawLine of body.split(/\r?\n/u)) {
@@ -382,6 +466,50 @@ function parseGateReviewCommentFields(body) {
       }
       continue;
     }
+
+    match = line.match(/^(?:[-*]\s*)?size[\s-]budget\s+outcome\s*:\s*(.+)$/iu);
+    if (match) {
+      if (fields.sizeOutcome === null) {
+        fields.sizeOutcome = normalizeGateSizeOutcome(match[1]);
+      }
+      continue;
+    }
+
+    match = line.match(/^(?:[-*]\s*)?size[\s-]budget\s+t1\s+slice\s*:\s*(.+)$/iu);
+    if (match) {
+      if (fields.sizeTouchesT1 === null) {
+        fields.sizeTouchesT1 = normalizeGateSizeTouchesT1(match[1]);
+      }
+      continue;
+    }
+
+    match = line.match(/^(?:[-*]\s*)?size[\s-]budget\s+waiver\s*:\s*(.+)$/iu);
+    if (match) {
+      if (fields.sizeWaiverGranted === null) {
+        const parsedWaiver = normalizeGateSizeWaiver(match[1]);
+        if (parsedWaiver) {
+          fields.sizeWaiverGranted = parsedWaiver.granted;
+          fields.sizeWaiverApprovedBy = parsedWaiver.approvedBy;
+        }
+      }
+      continue;
+    }
+  }
+
+  // An explicit, RECOGNIZED `review` gate field is authoritative and returns
+  // null here — before the lenient token-scan fallback below ever runs. A
+  // `review` verdict comment carries no draft/pre-approval evidence by
+  // design (#1808 AC3); without this short circuit, `fields.gate` would stay
+  // "review" (not one of the two evidence gates) but the lenient fallback
+  // below only fires when `!fields.gate` — so a *recognized* `review` gate
+  // would otherwise skip the fallback yet still return non-null fields keyed
+  // to "review", which is harmless for the two summarizers here (they only
+  // read `.draft_gate`/`.pre_approval_gate`) but leaves the non-evidence
+  // contract implicit rather than explicit. Stated plainly: an identified
+  // non-evidence gate must never be treated as an unidentified body, and an
+  // unidentified body is the ONLY case the token-scan fallback exists for.
+  if (NON_EVIDENCE_GATE_NAMES.has(fields.gate)) {
+    return null;
   }
 
   // Lenient fallback: detect gate name and head SHA anywhere in body
@@ -450,6 +578,10 @@ export function parseGateReviewCommentMarkerBody(body) {
     nextAction: fields.nextAction,
     executionMode: fields.executionMode,
     inlineReason: fields.inlineReason,
+    sizeOutcome: fields.sizeOutcome,
+    sizeTouchesT1: fields.sizeTouchesT1,
+    sizeWaiverGranted: fields.sizeWaiverGranted,
+    sizeWaiverApprovedBy: fields.sizeWaiverApprovedBy,
     contractComplete: Boolean(fields.verdict && fields.findingsSummary && fields.nextAction),
   };
 }
@@ -494,9 +626,13 @@ export function summarizeGateReviewComments(comments) {
       nextAction: parsed.nextAction,
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
+      sizeOutcome: parsed.sizeOutcome ?? null,
+      sizeTouchesT1: parsed.sizeTouchesT1 ?? null,
+      sizeWaiverGranted: parsed.sizeWaiverGranted ?? null,
+      sizeWaiverApprovedBy: parsed.sizeWaiverApprovedBy ?? 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,
+      commentUrl: trimmedOrNull(comment?.html_url),
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
         ? (comment.updated_at ?? comment.updatedAt).trim()
         : typeof (comment?.created_at ?? comment?.createdAt) === "string"
@@ -548,10 +684,14 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
       nextAction: parsed.nextAction,
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
+      sizeOutcome: parsed.sizeOutcome ?? null,
+      sizeTouchesT1: parsed.sizeTouchesT1 ?? null,
+      sizeWaiverGranted: parsed.sizeWaiverGranted ?? null,
+      sizeWaiverApprovedBy: parsed.sizeWaiverApprovedBy ?? 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,
+      commentUrl: trimmedOrNull(comment?.html_url),
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
         ? (comment.updated_at ?? comment.updatedAt).trim()
         : typeof (comment?.created_at ?? comment?.createdAt) === "string"

package/src/github/gh.mjs

@@ -0,0 +1,94 @@
+/**
+ * Shared `gh` CLI invoke-and-parse helpers (child 6 of the simplification
+ * epic #1689). This module introduces the shared implementation only; the
+ * ~19 call-site migrations are the follow-up children (projects: #1696;
+ * github/loop/refine: #1697).
+ *
+ * `ghJson` is the composed SUPERSET the callers share (per #1695's AC): a
+ * label-conditional non-zero-exit message — `gh command failed: <detail>` with
+ * no label (probe-ci-status shape) or `<label> failed: <detail>` with one
+ * (fetch-ci-logs shape) — always carrying `code: "GH_API_ERROR"`, plus the
+ * inline `Invalid JSON from gh: <stdout|<empty>>` malformed-stdout shape
+ * (probe-ci-status). `ghGraphql` reproduces scripts/projects/add-queue-item.mjs's
+ * superset (`gh api graphql failed` / `GraphQL errors:` with GH_API_ERROR /
+ * GRAPHQL_ERROR; `parseJsonText` → `Invalid JSON input`).
+ *
+ * Because `ghJson` is a composed superset, NO current caller matches it exactly
+ * — migrating each is a deliberate behavior harmonization, not a blind swap:
+ *   - probe-ci-status.mjs: `gh command failed:` / `Invalid JSON from gh:` already
+ *     match; it gains the `GH_API_ERROR` code on non-zero exit.
+ *   - fetch-ci-logs.mjs: `<label> failed:` matches (pass its label); it gains the
+ *     `GH_API_ERROR` code and its malformed-JSON message becomes
+ *     `Invalid JSON from gh:` (was `parseJsonText` → `Invalid JSON input`).
+ *   - upsert-checkpoint-verdict.mjs / post-gate-findings.mjs: gain the code and
+ *     their malformed-JSON message becomes `Invalid JSON from gh:` (was
+ *     `Invalid JSON input`).
+ * The follow-up children (projects: #1696; github/loop/refine: #1697) migrate
+ * each caller and update its pinned test messages accordingly.
+ */
+
+import { runChild as defaultRunChild } from "../cli/primitives.mjs";
+import { parseJsonText } from "./review-threads.mjs";
+
+/**
+ * Run a `gh` subcommand and parse its stdout as JSON. Fails loudly on a
+ * non-zero exit (naming the command's stderr) and on malformed JSON stdout.
+ *
+ * @param {string[]} args - argv passed to `ghCommand`.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {string} [opts.ghCommand] - defaults to `"gh"`.
+ * @param {typeof defaultRunChild} [opts.runChild] - injectable child-exec seam.
+ * @param {string} [opts.label] - controls the non-zero-exit message: when set,
+ *   the thrown error reads `<label> failed: <detail>` (the fetch-ci-logs shape);
+ *   when omitted it reads `gh command failed: <detail>` (the probe-ci-status
+ *   shape). Either way the non-zero-exit error carries `code: "GH_API_ERROR"`.
+ */
+export async function ghJson(args, { env, ghCommand = "gh", runChild = defaultRunChild, label } = {}) {
+  const result = await runChild(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    const prefix = label ? `${label} failed` : "gh command failed";
+    throw Object.assign(new Error(`${prefix}: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Invalid JSON from gh: ${result.stdout.trim() || "<empty>"}`);
+  }
+}
+
+/**
+ * Run a `gh api graphql` query and parse its response.
+ *
+ * @param {string} query - the GraphQL document.
+ * @param {Record<string, string>} vars - `--field key=value` variables.
+ * @param {NodeJS.ProcessEnv} env
+ * @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.
+ */
+export async function ghGraphql(query, vars, env, runChild = defaultRunChild, { allowErrors = false } = {}) {
+  const fieldArgs = [];
+  for (const [key, value] of Object.entries(vars)) {
+    fieldArgs.push("--field", `${key}=${value}`);
+  }
+  const result = await runChild(
+    "gh",
+    ["api", "graphql", "--field", `query=${query}`, ...fieldArgs],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  const payload = parseJsonText(result.stdout);
+  if (!allowErrors && payload.errors && payload.errors.length > 0) {
+    throw Object.assign(
+      new Error(`GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`),
+      { code: "GRAPHQL_ERROR" },
+    );
+  }
+  return payload;
+}

package/src/github/issue-ops.mjs

@@ -3,6 +3,7 @@ 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";
+import { guardCommentBodyNoIssuePrIds } from "./comment-id-guard.mjs";
 
 /**
  * Core `gh issue` operations, extracted from the thin CLI wrappers under
@@ -227,6 +228,11 @@ export async function resolveCommentBody(options) {
 
 export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
   const body = await resolveCommentBody(options);
+  // ISSUE/PR-ID GUARD (#1731): a generated comment body must never emit a raw
+  // issue/PR id (fail-closed unless explicitly allowlisted). `allowedRefs` is
+  // the ONLY sanctioned escape for a deliberate cross-reference, threaded from
+  // the generic CLI writers' --allowed-refs option.
+  guardCommentBodyNoIssuePrIds(body, { ref: "issue comment body", allowedRefs: options.allowedRefs });
   const result = await run(
     ghCommand,
     ["issue", "comment", String(options.issue), "--repo", options.repo, "--body", body],
@@ -282,6 +288,13 @@ export async function listIssues(options, { env = process.env, ghCommand = "gh",
   for (const label of options.labels ?? []) {
     args.push("--label", label);
   }
+  // `--search` narrows the result set to gh's own full-text search (title,
+  // body, comments) rather than the bare paged listing — needed by a caller
+  // that must find one specific issue by title without trusting that it falls
+  // within the default 30-issue page.
+  if (typeof options.search === "string" && options.search.length > 0) {
+    args.push("--search", options.search);
+  }
   const result = await run(ghCommand, args, env);
   if (result.code !== 0) {
     const detail = result.stderr.trim() || `exit code ${result.code}`;