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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -21,11 +21,13 @@
     "./debt/shape": "./src/debt/shape.mjs",
     "./debt/signal": "./src/debt/debt-signal.mjs",
     "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
+    "./github/comment-id-guard": "./src/github/comment-id-guard.mjs",
     "./github/issue-ops": "./src/github/issue-ops.mjs",
     "./github/ownership-helpers": "./src/github/ownership-helpers.mjs",
     "./github/repo-slug": "./src/github/repo-slug.mjs",
     "./github/review-threads": "./src/github/review-threads.mjs",
     "./loop/async-start-contract": "./src/loop/async-start-contract.mjs",
+    "./loop/agent-stall": "./src/loop/agent-stall.mjs",
     "./loop/bash-command-classify": "./src/loop/bash-command-classify.mjs",
     "./loop/conductor-routing": "./src/loop/conductor-routing.mjs",
     "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
@@ -54,6 +56,9 @@
     "./loop/queue-membership": "./src/loop/queue-membership.mjs",
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
     "./loop/queue-state": "./src/loop/queue-state.mjs",
+    "./loop/cache-telemetry-evidence": "./src/loop/cache-telemetry-evidence.mjs",
+    "./loop/primer-evidence": "./src/loop/primer-evidence.mjs",
+    "./loop/review-dispatch-plan": "./src/loop/review-dispatch-plan.mjs",
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",

package/src/claude/hook-decisions.mjs

@@ -10,6 +10,7 @@
  */
 
 import { resolveRunId } from "../loop/run-context.mjs";
+import { isUnderWorktreePath } from "../loop/worktree-guard.mjs";
 import {
   commandContainsGhPrReady,
   commandContainsGhPrMerge,
@@ -22,13 +23,23 @@ import {
   commandContainsRawExternalWrite,
   extractRepoFlagsFromExternalWriteSegments,
   commandContainsGitStash,
+  extractGhApiEndpointSegments,
+  commandContainsSubIssueAdHocBypass,
+  commandContainsReplyResolveBypass,
+  commandContainsGraphqlResolveReviewThread,
+  commandContainsCopilotRequestBypass,
+  commandContainsCopilotSummonComment,
+  commandContainsDetachedWaitTool,
+  commandContainsInlineInterpreter,
   TARGET_REPO_SLUG,
 } from "../loop/bash-command-classify.mjs";
 
 /**
  * @typedef {Object} HookDecision
- * @property {"allow"|"deny"} decision
- * @property {string} [reason] - Human-readable reason (shown to Claude on deny).
+ * @property {"allow"|"deny"|"block"} decision — `block` is the SubagentStop vocabulary
+ *   (exit 2 + stderr JSON), used by `decideSubagentStopGuard`; `allow`/`deny` are the PreToolUse
+ *   vocabulary used by `decideBashGate`/`decideWriteGuard`.
+ * @property {string} [reason] - Human-readable reason (shown to the agent on deny/block).
  */
 
 const ALLOW = Object.freeze({ decision: "allow" });
@@ -78,18 +89,81 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  * @param {boolean} [params.gatePassed] - Whether the relevant gate evidence exists for the PR.
  * @param {string|null} [params.gateError] - Error detail when the gate guard could not run.
  * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload; non-null
- *   string inside a subagent, null in the main agent. Scopes the external-write guard.
+ *   string inside a subagent, null in the main agent. Scopes the subagent-only predicates.
+ * @param {boolean} [params.humanMergeOnly] - Effective repo `autonomy.humanMergeOnly` invariant
+ *   (`resolveHumanMergeOnly`); when true, `gh pr merge` is refused actor-independently
+ *   (STOP-HUMAN-MERGE-001), because the main agent is the actor that performs GitHub writes and a
+ *   subagent-only deny would enforce nothing.
  * @returns {HookDecision}
  */
-export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null }) {
+export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null, humanMergeOnly = false }) {
   if (typeof command !== "string") {
     return ALLOW;
   }
+  // Normalize (trim + case-fold) so a divergent slug (surrounding whitespace, casing) does not
+  // silently fail OPEN and disable every guard that depends on inTargetRepo (#1622).
+  const inTargetRepo = (repoSlug ?? "").trim().toLowerCase() === TARGET_REPO_SLUG.trim().toLowerCase();
+
+  // OPS-NO-INLINE-INTERPRETER (#1622): inline interpreters (`node -e`/`--eval`/`-p`, `python3 -c`,
+  // heredocs fed to node/python) are barred actor-independently on the target repo — the rule bars
+  // "Coordinator and agent flows"; sanctioned output parsing uses `--jq`/`--silent`, never an
+  // inline interpreter.
+  if (inTargetRepo && commandContainsInlineInterpreter(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "OPS-NO-INLINE-INTERPRETER: inline interpreters (node -e/--eval/-p, python3 -c, heredoc to " +
+        "node/python) are barred in the dev-loop flow. Parse tool output via --jq/--silent and mutate " +
+        "files via the editor/patch tools or a --jq-composed --body-file, never an inline interpreter.",
+    };
+  }
+
+  // SUBISSUE-NO-ADHOC-BYPASS (#1622): ad-hoc `gh api` writes to the target repo's sub-issue endpoints.
+  // Actor-independent (no reserved direct path). Gated on the target repo: the absolute slug-embedded
+  // form identifies the target repo; the bare relative form (`gh api issues/5/sub_issues`) resolves
+  // against the cwd repo, so it is in scope only when running in the target repo (mirrors the #1047
+  // explicit-`--repo`/cwd-target posture).
+  if (inTargetRepo && commandContainsSubIssueAdHocBypass(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "SUBISSUE-NO-ADHOC-BYPASS: ad-hoc `gh api` writes to the target repo's sub_issues endpoint are " +
+        "blocked. Manage sub-issues via the sanctioned manage-sub-issues wrapper instead.",
+    };
+  }
+
+  // COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER (#1622): ad-hoc thread-resolution writes — raw `gh api` POST
+  // to pulls/<n>/comments/<m>/replies, or a `gh api graphql` resolveReviewThread mutation (the Rest
+  // path names the target repo; the graphql form has no path-host repo, so it is scoped to the cwd
+  // repo). Actor-independent: reply through reply-resolve-review-thread(s).mjs.
+  if (inTargetRepo && (commandContainsReplyResolveBypass(command) || commandContainsGraphqlResolveReviewThread(command))) {
+    return {
+      decision: "deny",
+      reason:
+        "COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER: ad-hoc thread-reply mutations are blocked. Resolve review " +
+        "threads via scripts/github/reply-resolve-review-thread.mjs (one thread) or " +
+        "reply-resolve-review-threads.mjs (multiple threads, --message-map), not raw gh api/graphql.",
+    };
+  }
+
+  // COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY (#1622): ad-hoc Copilot review requests — raw `gh api` writes
+  // to pulls/<n>/requested_reviewers, or a bare `/copilot` / `/copilot re-review` comment summon on the
+  // target repo. Actor-independent: request Copilot via scripts/github/request-copilot-review.mjs.
+  if (inTargetRepo && (commandContainsCopilotRequestBypass(command) || commandContainsCopilotSummonComment(command))) {
+    return {
+      decision: "deny",
+      reason:
+        "COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY: ad-hoc Copilot review requests are blocked. Request Copilot " +
+        "via scripts/github/request-copilot-review.mjs — do not write requested_reviewers or post a literal " +
+        "/copilot comment.",
+    };
+  }
+
   // `git stash` writes to `refs/stash`, one ref shared by every worktree over this repo's single
   // `.git` directory — a stash from one worktree can pop into another's. Block it outright on the
   // target repo; see skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout for the
   // stash-free alternative (git diff / a patch file / a scratch checkout).
-  if (commandContainsGitStash(command) && (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase()) {
+  if (commandContainsGitStash(command) && inTargetRepo) {
     return {
       decision: "deny",
       reason:
@@ -130,7 +204,36 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   const isReady = commandContainsGhPrReady(command);
   const isMerge = commandContainsGhPrMerge(command);
   const isCreate = commandContainsGhPrCreate(command);
+
+  // STOP-HUMAN-MERGE-001 (#1622): when the repo resolves `autonomy.humanMergeOnly`, `gh pr merge` is
+  // refused actor-independently — the main agent is the actor that performs GitHub writes, so only an
+  // actor-independent deny enforces the human-merge invariant (an agent-scoped deny would enforce
+  // nothing on the main-agent write path).
+  if (humanMergeOnly && isMerge && inTargetRepo) {
+    return {
+      decision: "deny",
+      reason:
+        "STOP-HUMAN-MERGE-001: this repo resolves autonomy.humanMergeOnly — the loop must stop at merge " +
+        "for a human action; the agent MUST NOT run `gh pr merge`. Leave the PR merge-ready and a human " +
+        "merges it.",
+    };
+  }
+
   if (!isReady && !isMerge && !isCreate) {
+    // COPILOT-FOLLOWUP-WAIT-TOOLS (#1622): banned detached/polling wait wrappers. Subagent-only — the
+    // rule is classified `agent` (behavioral guidance for the dev-loop driving agent); the main
+    // agent/operator retains manual wait tooling. The main agent's own sanctioned wait path is still
+    // the deterministic tools.
+    if (typeof agentType === "string" && inTargetRepo && commandContainsDetachedWaitTool(command)) {
+      return {
+        decision: "deny",
+        reason:
+          "COPILOT-FOLLOWUP-WAIT-TOOLS: wait only through deterministic tools (scripts/loop/detect-copilot-" +
+          "loop-state.mjs one-shot, dev-loops loop watch-cycle persistent, scripts/github/wait-pr-checks.mjs, " +
+          "gh run watch) — nohup/disown/tmux/screen detach and while-sleep-poll loops are barred for the " +
+          "dev-loop driving agent.",
+      };
+    }
     return ALLOW;
   }
 
@@ -265,3 +368,67 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
       "See skills/docs/main-agent-contract.md.",
   };
 }
+
+/**
+ * Env var that exempts an interactive session awaiting commit authorization from the
+ * SubagentStop uncommitted-work guard (#1619).
+ *
+ * An opt-in signal set by the operator or the interactive coordination path
+ * (`DEVLOOPS_COMMIT_AUTH_PENDING=1`) when intentionally holding uncommitted work pending
+ * operator commit authorization — consistent with the operator-set `DEVLOOPS_*` env vars in
+ * this repo (`DEVLOOPS_MAIN_AGENT_READONLY`, `DEVLOOPS_ALLOW_MAIN`, `DEVLOOPS_SUBAGENT_AVAILABLE`),
+ * which are environment/operator signals rather than values written by a code path. A
+ * non-interactive (dispatched) subagent leaves it unset, so its commit-before-exit obligation
+ * stays enforced.
+ */
+export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
+
+/**
+ * Decide whether a SubagentStop must be blocked because the subagent's worktree has
+ * uncommitted changes (#1619).
+ *
+ * `scripts/loop/cleanup-worktree.mjs` runs `git worktree remove --force` after a merge, so
+ * uncommitted changes in a worktree are destroyed with no warning. `LOCAL-COMMIT-BEFORE-EXIT`
+ * existed only as prose. This decider makes it mechanical: refuse the subagent stop when the
+ * cwd is under `tmp/worktrees/` and `git status --porcelain` is non-empty, unless the session
+ * is an interactive one awaiting commit authorization (exempt). A clean worktree, a cwd
+ * outside `tmp/worktrees/`, and a git-error/empty-porcelain case all allow the stop.
+ *
+ * Pure and side-effect free. The hook script gathers `cwd` and the `git status --porcelain`
+ * output and calls this; the block decision is surfaced via exit code 2 + stderr JSON by the
+ * hook (the SubagentStop contract differs from PreToolUse's `permissionDecision` form).
+ *
+ * @param {Object} params
+ * @param {string|undefined} params.cwd - Current working directory; a non-string value is
+ *   treated as out of scope (allow) — the decider is fail-safe.
+ * @param {string|undefined} params.porcelain - Raw `git status --porcelain` output; a non-string
+ *   or empty value is treated as clean (allow) — the decider is fail-safe.
+ * @param {boolean} [params.pendingCommitAuthorization] - True when the interactive session is
+ *   awaiting commit authorization (exempt) — derived by the hook script from the
+ *   `DEVLOOPS_COMMIT_AUTH_PENDING=1` opt-in env signal.
+ * @returns {HookDecision}
+ */
+export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false }) {
+  if (typeof cwd !== "string" || !isUnderWorktreePath(cwd)) {
+    return ALLOW;
+  }
+  if (pendingCommitAuthorization) {
+    return ALLOW;
+  }
+  if (typeof porcelain !== "string" || porcelain.trim() === "") {
+    return ALLOW;
+  }
+  const dirty = porcelain
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  return {
+    decision: "block",
+    reason:
+      "LOCAL-COMMIT-BEFORE-EXIT: the worktree has uncommitted changes — refusing subagent exit " +
+      "to prevent silent data loss from post-merge worktree cleanup (cleanup-worktree.mjs runs " +
+      "`git worktree remove --force`). Commit your work before stopping. " +
+      `Dirty paths (${dirty.length}):\n` +
+      dirty.map((p) => "  " + p).join("\n"),
+  };
+}

package/src/cli/primitives.mjs

@@ -126,6 +126,27 @@ export function parseIssueNumber(value, parseError = null) {
   return parsePositiveInteger(value, "--issue", parseError);
 }
 
+// Parse a comma-separated allowlist of numeric issue/PR ids (e.g. `1670,9000`
+// from an `--allowed-refs` CLI option). Returns the ids as deduped numeric
+// strings, empty array for an empty/whitespace-only input. Rejects any
+// non-numeric (or zero) entry so a typo can never silently allowlist nothing.
+export function parseAllowedRefsCsv(value, flag, parseError = null) {
+  const parts = String(value ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  const ids = [];
+  for (const part of parts) {
+    if (!/^\d+$/u.test(part) || Number(part) === 0) {
+      throw toCliError(`${flag} must be a comma-separated list of positive integers (got ${JSON.stringify(part)})`, parseError);
+    }
+    if (!ids.includes(part)) {
+      ids.push(part);
+    }
+  }
+  return ids;
+}
+
 // `stdinText` is optional and additive: omit it and stdin stays closed exactly
 // as before. Supply it (a `gh api ... --input -` payload) and it is piped in,
 // so a caller that needs stdin no longer has to reach for a second, separately

package/src/config/config.mjs

@@ -286,7 +286,8 @@ const FanoutConfig = z.strictObject({
   mode: z.enum(["grouped", "per-angle"]).default("grouped").describe("Angle dispatch mode: grouped batches related angles onto one reviewer each (default); per-angle bypasses the configured-groups table and emits one singleton unit per angle (the original full-scrutiny shape). per-angle is equivalent to maxAnglesPerGroup: 1 in dispatch unit size ONLY when no configured multi-angle group matches a resolved angle; otherwise per-angle bypasses configured groups while maxAnglesPerGroup: 1 honors them (matched first, never split)."),
   groups: z.array(FanoutGroup).optional().describe("Static named angle groups consulted in grouped mode. An angle absent from every group joins the auto-chunked leftover pool (chunked into units of ≤maxAnglesPerGroup)."),
   maxAnglesPerGroup: z.number().int().min(1).default(3).describe("Max angles per auto-chunked dispatch unit for leftover ungrouped angles (default 3, min 1). Configured groups are matched first and never split by this knob; mode: per-angle bypasses the table entirely (one singleton per angle)."),
-  maxConcurrent: z.number().int().min(1).default(4).describe("Max dispatch units (groups) the conductor dispatches concurrently per wave (default 4, min 1). The wave plan is emitted by write-gate-context.mjs via scheduleFanoutWaves (scheduleParallelWaves)."),
+  maxConcurrent: z.number().int().min(1).default(4).describe("Max dispatch units (groups) the conductor dispatches concurrently per wave (default 4, min 1). The wave plan is emitted by write-gate-context.mjs via scheduleFanoutWaves (scheduleParallelWaves). Ignored when sequential is true (which forces one unit per wave)."),
+  sequential: z.boolean().default(false).describe("Dispatch heavy reviewers one at a time (serial) instead of wave-by-wave parallel (issue #1726). When true, effective fan-out concurrency is one dispatch unit per wave regardless of maxConcurrent, so each heavy reviewer completes and writes its evidence artifact before the next starts. Distinct reviewers, real fan-in/ledger, and provenance are unchanged — this only bounds dispatch concurrency. Default false keeps shipped behaviour unchanged for other harnesses/repos (cross-harness non-regression #1086); a repo sets it in .devloops to bound concurrency for all its PRs."),
 });
 
 /**
@@ -427,6 +428,17 @@ const WorkflowConfig = z.strictObject({
   requireRetrospective: z.boolean().describe("Require a retrospective checkpoint for the previous qualifying async completion before the next dev-loop start/resume."),
   requireDraftFirst: z.boolean().describe("Open pull requests as drafts and promote via the draft gate."),
   devModeDefault: z.boolean().describe("Default new loops to dev mode."),
+  // Agent-level stall detection (#1669): when a dev-loop child shows no turn
+  // progress for `thresholdMinutes` with no pending request, the parent bails
+  // to a fresh-context recovery dispatch instead of waiting through a manual
+  // interrupt+resume. `enabled: false` disables the auto-bail and restores
+  // the old wait behavior.
+  stallDetection: z
+    .strictObject({
+      enabled: z.boolean().default(true).describe("Enable agent-level stall -> auto-fresh-dispatch."),
+      thresholdMinutes: z.number().int().min(1).default(5).describe("No-turn-progress window in minutes before a child is treated as stalled."),
+    })
+    .optional(),
   // No default here and absent from BUILT_IN_DEFAULTS — unset means "keep
   // auto-detecting the default branch" (see resolveBaseBranch), never a static
   // "main". Bare branch name; consumers add the `origin/` remote-ref prefix
@@ -795,6 +807,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     requireRetrospective: false,
     requireDraftFirst: false,
     devModeDefault: false,
+    stallDetection: Object.freeze({ enabled: true, thresholdMinutes: 5 }),
   }),
   localImplementation: Object.freeze({
     lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200, maxCopilotRounds: 1 }),
@@ -2059,6 +2072,36 @@ export const DEFAULT_MAX_ANGLES_PER_GROUP = 3;
  * `scheduleFanoutWaves` (@dev-loops/core/loop/gate-fanin).
  */
 export const DEFAULT_FANOUT_MAX_CONCURRENT = 4;
+export const DEFAULT_FANOUT_SEQUENTIAL = false;
+
+/**
+ * Resolve `gates.fanout.sequential` (issue #1726, default false). Serial
+ * (one-at-a-time) dispatch of heavy reviewers so each completes and writes its
+ * evidence before the next starts — the concurrency bound that keeps genuine
+ * fan-out from SIGTERMing under child-safe parallel overload. Separate from
+ * `maxConcurrent` so a repo may choose either serial (sequential: true) or a
+ * small parallel cap (maxConcurrent: 1-2, sequential: false); the shipped
+ * default stays false for cross-harness non-regression (#1086).
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveFanoutSequential(config) {
+  const s = config?.gates?.fanout?.sequential;
+  return s === true;
+}
+
+/**
+ * Resolve the effective fan-out concurrency (dispatch units per wave) for a
+ * round: 1 when `gates.fanout.sequential` is set (serial dispatch forces one
+ * unit per wave), else `resolveFanoutMaxConcurrent`. The conductor builds the
+ * wave plan from this effective value (issue #1726).
+ * @param {DevLoopConfig} config
+ * @returns {number}
+ */
+export function resolveFanoutEffectiveConcurrency(config) {
+  if (resolveFanoutSequential(config)) return 1;
+  return resolveFanoutMaxConcurrent(config);
+}
 
 /**
  * Resolve `gates.fanout.maxAnglesPerGroup` (issue #1601, default 3, min 1).
@@ -2531,6 +2574,15 @@ export function resolveWorkflowConfig(config, key) {
     return config?.workflow?.devModeDefault ?? DEFAULT_WORKFLOW_CONFIG.devModeDefault;
   }
 
+  if (key === "stallDetection") {
+    const configured = config?.workflow?.stallDetection;
+    const def = DEFAULT_WORKFLOW_CONFIG.stallDetection;
+    return {
+      enabled: configured?.enabled ?? def.enabled,
+      thresholdMinutes: configured?.thresholdMinutes ?? def.thresholdMinutes,
+    };
+  }
+
   throw new Error(`Unknown workflow config key: ${key}`);
 }
 

package/src/config/extension-defaults.yaml

@@ -278,6 +278,11 @@ workflow:
   # it on consumers' product phases (#846). Matches the code default; the dev-loops repo opts in
   # via its own repo-root .devloops (which takes precedence over these extension defaults).
   devModeDefault: false
+  # Agent-level stall detection (#1669): auto-bail to fresh-context dispatch
+  # when a dev-loop child shows no turn progress for the window.
+  stallDetection:
+    enabled: true
+    thresholdMinutes: 5
 
 # Light-mode threshold for small local changes.
 localImplementation:

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

@@ -0,0 +1,70 @@
+/**
+ * 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"]`. This is the ONLY sanctioned way a generated comment
+ * body may reference an issue/PR id. 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.
+const ISSUE_PR_ID_RE = /#(\d{1,9})/g;
+
+/**
+ * Extract the raw issue/PR id tokens found in a body (as strings, deduped).
+ * 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();
+  for (const m of body.matchAll(ISSUE_PR_ID_RE)) {
+    found.add(m[1]);
+  }
+  return [...found];
+}
+
+/**
+ * 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>} [opts.allowedRefs] - explicit allowlist of
+ *   deliberate cross-reference ids permitted to appear in the body.
+ * @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(Array.from(allowedRefs ?? [], (id) => String(id)));
+  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

@@ -80,6 +80,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)

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],