@open-everywhere/core 0.1.0

package/agent/scm/pr-feedback.ts

@@ -0,0 +1,335 @@
+// A read-only, BOUNDED digest of the human/CI feedback on a pull request — the reviews,
+// the inline review comments, the issue-thread comments, and the check runs. This is what
+// closes the loop the GitHub @mention wake leaves open: a mention delivers only the single
+// triggering comment + a one-shot diff, so the model has no way to READ the requested
+// changes it's being asked to make. get_pr_feedback (tools/get_pr_feedback.ts) is that read.
+//
+// Everything here runs HOST-SIDE with a READ-scoped credential (resolveReadToken, the same
+// path check_pr_status/subscribe_pr use) — api.github.com is deliberately NOT sandbox-reachable.
+// The digest is deliberately BOUNDED (cap counts + per-item chars) and reports its own
+// truncation so a huge PR can't blow the context or hide that it was clipped.
+
+import { prApiHeaders, type PrFetchFn } from "./pr.js";
+import { fetchCheckRuns, summarizeChecks, type CheckRun, type PrChecksSummary } from "./pr-status.js";
+import { ingestUntrusted } from "../access/untrusted.js";
+
+// --- bounds (all deliberate; every clip is reported in the digest's `truncation`) ----------
+/** Max reviews kept (most-recent first). */
+export const MAX_REVIEWS = 30;
+/** Max inline review comments kept (most-recent first). */
+export const MAX_REVIEW_COMMENTS = 50;
+/** Max issue-thread comments kept (most-recent first). */
+const MAX_ISSUE_COMMENTS = 50;
+/** Max check runs kept in the per-run list (the summary counts stay exact). */
+const MAX_CHECKS = 50;
+/** Per-item character cap on any free-text body/summary. */
+export const MAX_BODY_CHARS = 2000;
+
+export interface PrFeedbackReview {
+  readonly author: string;
+  /** APPROVED | CHANGES_REQUESTED | COMMENTED | DISMISSED */
+  readonly state: string;
+  readonly body: string;
+}
+
+export interface PrFeedbackReviewComment {
+  readonly path: string;
+  /** The line in the diff the comment is anchored to (null if the anchor is outdated). */
+  readonly line: number | null;
+  readonly author: string;
+  readonly body: string;
+}
+
+export interface PrFeedbackIssueComment {
+  readonly author: string;
+  readonly body: string;
+}
+
+export interface PrFeedbackCheck {
+  readonly name: string;
+  readonly status: string;
+  readonly conclusion: string | null;
+  /** Bounded excerpt of the run's output summary — populated for FAILING runs so the model can
+   *  see WHY CI is red; empty for passing runs (no need to spend context on green output). */
+  readonly summary: string;
+}
+
+/** Per-section honesty about what got clipped: how many items were dropped, and the char cap
+ *  applied to each body. `truncated` is true when ANY section or body was clipped. */
+export interface PrFeedbackTruncation {
+  readonly truncated: boolean;
+  readonly reviewsDropped: number;
+  readonly reviewCommentsDropped: number;
+  readonly issueCommentsDropped: number;
+  readonly checksDropped: number;
+  /** Number of individual bodies/summaries that hit the per-item char cap. */
+  readonly bodiesClipped: number;
+  readonly maxBodyChars: number;
+}
+
+export interface PrFeedbackDigest {
+  readonly repo: string;
+  readonly number: number;
+  readonly reviews: readonly PrFeedbackReview[];
+  readonly reviewComments: readonly PrFeedbackReviewComment[];
+  readonly issueComments: readonly PrFeedbackIssueComment[];
+  readonly checks: readonly PrFeedbackCheck[];
+  /** The compact CI roll-up over ALL runs (exact counts, even when the per-run list is capped). */
+  readonly checksSummary: PrChecksSummary;
+  readonly truncation: PrFeedbackTruncation;
+  /** `base.repo.private` as GitHub reports it on the PR object this digest ALREADY fetches — the
+   *  source-tier table's deciding fact for the `github` row (OPE-331). BASE, never HEAD: a PR from a
+   *  fork has a public `head.repo` while the repository whose reviews and comments this digest reads
+   *  is the base one. `undefined` only when GitHub omitted the field, which keeps the table on its
+   *  fail-closed default. Costs NO extra API call — see fetchPrFeedback. */
+  readonly repoPrivate?: boolean;
+}
+
+// --- raw GitHub shapes (only the fields we read) -------------------------------------------
+interface RawUser {
+  login?: string;
+}
+interface RawReview {
+  user?: RawUser;
+  state?: string;
+  body?: string;
+}
+interface RawReviewComment {
+  path?: string;
+  line?: number | null;
+  original_line?: number | null;
+  user?: RawUser;
+  body?: string;
+}
+interface RawIssueComment {
+  user?: RawUser;
+  body?: string;
+}
+
+/** A single-body clip. Mutates the shared counter so the digest can report bodiesClipped. */
+function clip(text: string | undefined, counter: { n: number }): string {
+  const t = (text ?? "").trim();
+  if (t.length <= MAX_BODY_CHARS) return t;
+  counter.n += 1;
+  return `${t.slice(0, MAX_BODY_CHARS)}… [clipped, ${t.length} chars total]`;
+}
+
+async function getJson<T>(fetchFn: PrFetchFn, url: string, token: string): Promise<T> {
+  const res = await fetchFn(url, { method: "GET", headers: prApiHeaders(token) });
+  if (!res.ok) {
+    throw new Error(`GitHub feedback read failed for ${url}: ${res.status} ${await res.text()}`);
+  }
+  return (await res.json()) as T;
+}
+
+/**
+ * Assemble the bounded feedback digest for one PR. Five host-side reads (PR head, reviews,
+ * review comments, issue comments, check runs); the fetch is injected so the whole assembly is
+ * unit-testable without network. Check-runs is best-effort (a red check-runs read yields an
+ * empty checks section rather than sinking the digest); the other reads surface their errors.
+ */
+export async function fetchPrFeedback(opts: {
+  repo: string;
+  number: number;
+  token: string;
+  fetchFn?: PrFetchFn;
+  apiBase?: string;
+}): Promise<PrFeedbackDigest> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as PrFetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const { repo, number, token } = opts;
+  const bodies = { n: 0 };
+
+  // 🔴 `base.repo.private` COMES FREE HERE (OPE-331). This read already happens — it is the "PR head"
+  // call the docblock above counts — and the PR object carries the base repository's visibility. The
+  // comment in renderPrFeedbackForModel used to say proving visibility "would mean an EXTRA API
+  // call"; that was wrong, and it had made the source-tier table's `github` row permanently `assumed` at this
+  // seam for no reason. Reading one more field off a response already in hand is not a behaviour
+  // change: no extra request, no extra scope, no extra latency.
+  const pr = await getJson<{ head?: { sha?: string }; base?: { repo?: { private?: boolean } } }>(
+    fetchFn,
+    `${apiBase}/repos/${repo}/pulls/${number}`,
+    token,
+  );
+  const [rawReviews, rawReviewComments, rawIssueComments] = await Promise.all([
+    getJson<RawReview[]>(fetchFn, `${apiBase}/repos/${repo}/pulls/${number}/reviews?per_page=100`, token),
+    getJson<RawReviewComment[]>(fetchFn, `${apiBase}/repos/${repo}/pulls/${number}/comments?per_page=100`, token),
+    getJson<RawIssueComment[]>(fetchFn, `${apiBase}/repos/${repo}/issues/${number}/comments?per_page=100`, token),
+  ]);
+
+  // Reviews: drop the empty-body COMMENTED containers (their content is the inline review
+  // comments below); keep every APPROVED / CHANGES_REQUESTED / DISMISSED (the state IS the
+  // signal even with no body) and any review that carries a body. PENDING = an unsubmitted
+  // draft belonging to the viewer, never anyone else's feedback — always dropped.
+  const reviewsAll = (rawReviews ?? []).filter((r) => {
+    const state = (r.state ?? "").toUpperCase();
+    if (state === "PENDING") return false;
+    if (state === "COMMENTED" && !(r.body ?? "").trim()) return false;
+    return true;
+  });
+  const reviews = mostRecent(reviewsAll, MAX_REVIEWS).map((r) => ({
+    author: r.user?.login ?? "(unknown)",
+    state: (r.state ?? "COMMENTED").toUpperCase(),
+    body: clip(r.body, bodies),
+  }));
+
+  const reviewComments = mostRecent(rawReviewComments ?? [], MAX_REVIEW_COMMENTS).map((c) => ({
+    path: c.path ?? "(unknown)",
+    line: c.line ?? c.original_line ?? null,
+    author: c.user?.login ?? "(unknown)",
+    body: clip(c.body, bodies),
+  }));
+
+  const issueComments = mostRecent(rawIssueComments ?? [], MAX_ISSUE_COMMENTS).map((c) => ({
+    author: c.user?.login ?? "(unknown)",
+    body: clip(c.body, bodies),
+  }));
+
+  // Checks: best-effort (a failing check-runs read leaves the section empty rather than sinking
+  // the whole digest). Only FAILING runs carry an output excerpt — green output isn't worth context.
+  let runs: CheckRun[] = [];
+  const headSha = pr.head?.sha;
+  if (headSha) {
+    try {
+      runs = await fetchCheckRuns({ repo, ref: headSha, token, fetchFn, apiBase });
+    } catch {
+      runs = [];
+    }
+  }
+  const checksSummary = summarizeChecks(runs);
+  const failingNames = new Set(checksSummary.failing);
+  const checks = runs.slice(0, MAX_CHECKS).map((r) => ({
+    name: r.name,
+    status: r.status,
+    conclusion: r.conclusion,
+    summary: failingNames.has(r.name) ? clip(r.summary, bodies) : "",
+  }));
+
+  const reviewCommentsDropped = Math.max(0, (rawReviewComments ?? []).length - MAX_REVIEW_COMMENTS);
+  const issueCommentsDropped = Math.max(0, (rawIssueComments ?? []).length - MAX_ISSUE_COMMENTS);
+  const reviewsDropped = Math.max(0, reviewsAll.length - MAX_REVIEWS);
+  const checksDropped = Math.max(0, runs.length - MAX_CHECKS);
+
+  const truncation: PrFeedbackTruncation = {
+    truncated: bodies.n > 0 || reviewsDropped > 0 || reviewCommentsDropped > 0 || issueCommentsDropped > 0 || checksDropped > 0,
+    reviewsDropped,
+    reviewCommentsDropped,
+    issueCommentsDropped,
+    checksDropped,
+    bodiesClipped: bodies.n,
+    maxBodyChars: MAX_BODY_CHARS,
+  };
+
+  const repoPrivate = pr.base?.repo?.private;
+  return {
+    repo,
+    number,
+    reviews,
+    reviewComments,
+    issueComments,
+    checks,
+    checksSummary,
+    truncation,
+    ...(typeof repoPrivate === "boolean" ? { repoPrivate } : {}),
+  };
+}
+
+/** Keep the most recent `max` items (GitHub returns these oldest-first; recent feedback wins). */
+function mostRecent<T>(items: readonly T[], max: number): T[] {
+  return items.length <= max ? [...items] : items.slice(items.length - max);
+}
+
+// --- model-facing rendering (OPE-109 untrusted-content envelope) ----------------------------
+// The digest mixes HOST-DERIVED STRUCTURE (repo/number, per-item author/state/path/line, check
+// name/status/conclusion, the roll-up counts, the truncation report) with THIRD-PARTY FREE TEXT
+// (review bodies, inline-comment bodies, issue-comment bodies, and the failing-check output
+// excerpts — the last authored by a CI system running PR-influenced code). The structure is the
+// navigational scaffold and stays TRUSTED so the model can still tell which comment is which; each
+// free-text body is wrapped in its OWN untrusted-content fence (access/untrusted.ts ingestUntrusted
+// — the SAME framing wrapUntrusted produces, plus turn taint). Per-item (not one big fence) so the
+// item boundaries are host-controlled and delimiter-defanged: a malicious body cannot forge a
+// neighbouring item's identity or read as instructions, and cannot escape the fence. Empty bodies
+// carry no fence — a bodiless APPROVED review is pure structural signal, and fencing "" would only
+// add noise and a spurious taint.
+
+function truncNote(n: number, unit: string): string {
+  return n > 0 ? `, ${n} older ${unit} dropped` : "";
+}
+
+/**
+ * Render a {@link PrFeedbackDigest} as the model-facing text for get_pr_feedback's `toModelOutput`.
+ * Host-derived structure is plain (trusted) text; every non-empty third-party body is individually
+ * fenced, source-labelled by author/location so provenance is explicit.
+ *
+ * 🔴 WHETHER IT TAINTS IS THE TABLE'S CALL SINCE OPE-324, and it turns on `repoPrivate`: a PRIVATE
+ * org repo's reviews and comments fence WITHOUT tainting (they are org-authored — the instance-binary
+ * rule), a PUBLIC repo's still taint (anyone with a fork can author them). The fence is unconditional
+ * either way.
+ */
+export function renderPrFeedbackForModel(d: PrFeedbackDigest): string {
+  // ONE descriptor for all four fenced-body sites below — they are the same source instance (this
+  // repository), and access/taint-enforcement.ts dedupes ROWS per (kind, divergence) per turn, so a
+  // PR with forty comments still produces one row while every one of the forty is classified.
+  //
+  // `repoPrivate` is PLUMBED as of OPE-331, and the sentence that used to sit here was WRONG: it said
+  // proving visibility "would mean an EXTRA API call", which had frozen the GitHub row at `assumed`
+  // for no reason. fetchPrFeedback already GETs the PR object, and `base.repo.private` rides it — so
+  // the deciding fact was in hand the whole time and costs nothing to read. An absent value now means
+  // only that GitHub omitted the field, and the table still falls closed there.
+  const ingestion = {
+    kind: "github",
+    label: `get_pr_feedback:${d.repo}`,
+    ...(d.repoPrivate !== undefined ? { repoPrivate: d.repoPrivate } : {}),
+  } as const;
+  const out: string[] = [`PR feedback for ${d.repo}#${d.number}`];
+
+  out.push("", `Reviews (${d.reviews.length}${truncNote(d.truncation.reviewsDropped, "reviews")}):`);
+  if (d.reviews.length === 0) out.push("  (none)");
+  d.reviews.forEach((r, i) => {
+    const head = `  [${i + 1}] ${r.author} — ${r.state}`;
+    if (r.body.trim()) out.push(`${head}:`, ingestUntrusted(r.body, { source: `pr review by ${r.author}`, ingestion }));
+    else out.push(`${head} (no comment)`);
+  });
+
+  out.push("", `Inline review comments (${d.reviewComments.length}${truncNote(d.truncation.reviewCommentsDropped, "comments")}):`);
+  if (d.reviewComments.length === 0) out.push("  (none)");
+  d.reviewComments.forEach((c, i) => {
+    const loc = `${c.path}:${c.line ?? "?"}`;
+    const head = `  [${i + 1}] ${loc} — ${c.author}`;
+    if (c.body.trim()) out.push(`${head}:`, ingestUntrusted(c.body, { source: `pr review comment by ${c.author} on ${loc}`, ingestion }));
+    else out.push(`${head} (no body)`);
+  });
+
+  out.push("", `Issue-thread comments (${d.issueComments.length}${truncNote(d.truncation.issueCommentsDropped, "comments")}):`);
+  if (d.issueComments.length === 0) out.push("  (none)");
+  d.issueComments.forEach((c, i) => {
+    const head = `  [${i + 1}] ${c.author}`;
+    if (c.body.trim()) out.push(`${head}:`, ingestUntrusted(c.body, { source: `pr comment by ${c.author}`, ingestion }));
+    else out.push(`${head} (empty)`);
+  });
+
+  const s = d.checksSummary;
+  const byConclusion = Object.entries(s.byConclusion).map(([k, v]) => `${k}:${v}`).join(", ") || "none";
+  out.push(
+    "",
+    `Checks: ${s.total} total (${byConclusion})${s.pending ? `, ${s.pending} pending` : ""}` +
+      `${s.failing.length ? `; failing: ${s.failing.join(", ")}${s.failingTruncated ? " (…more)" : ""}` : ""}`,
+  );
+  d.checks.forEach((c) => {
+    const head = `  - ${c.name}: ${c.status}${c.conclusion ? `/${c.conclusion}` : ""}`;
+    // Only failing runs carry a summary (host caps it to green-empty upstream). It is CI output —
+    // external free text — so it is fenced like the human bodies.
+    if (c.summary.trim()) out.push(`${head} —`, ingestUntrusted(c.summary, { source: `pr check ${c.name}`, ingestion }));
+    else out.push(head);
+  });
+
+  if (d.truncation.truncated) {
+    out.push(
+      "",
+      `Note: this digest was truncated (bodies clipped at ${d.truncation.maxBodyChars} chars${
+        d.truncation.checksDropped ? `; ${d.truncation.checksDropped} checks dropped` : ""
+      }). Re-read a specific item on GitHub if you need the full text.`,
+    );
+  }
+  return out.join("\n");
+}

package/agent/scm/pr-status.ts

@@ -0,0 +1,299 @@
+// A read-only GitHub PR status snapshot — the primitive both check_pr_status and
+// subscribe_pr build on. subscribe_pr's whole re-arm loop is a fired routine turn
+// calling check_pr_status again and diffing what it sees against the prompt's
+// embedded baseline (routines/routine.ts's `once` kind + create_routine's own
+// documented "just create another one-shot to check again" pattern — no new
+// dispatcher machinery needed, see tools/subscribe_pr.ts's header for the design).
+
+import type { GitHubApp } from "./app.js";
+import { getGitHubApp } from "./provider.js";
+import { CONVERSATION_READ_PERMISSIONS, PR_READ_PERMISSIONS } from "./mint.js";
+import type { MintPermissions } from "./types.js";
+import { prApiHeaders, type PrFetchFn } from "./pr.js";
+import {
+  describeActivity,
+  fetchPrReviews,
+  prHasActivity,
+  summarizeReviews,
+  type PrActivitySummary,
+} from "./pr-activity.js";
+
+export interface PrStatusSnapshot {
+  readonly repo: string;
+  readonly number: number;
+  readonly url: string;
+  readonly title: string;
+  readonly state: "open" | "closed";
+  readonly merged: boolean;
+  readonly draft: boolean;
+  readonly updatedAt: string;
+  /** CI at the PR head — a COMPACT roll-up so subscribe_pr chains can watch checks without a
+   *  new subscription type (feeds a re-arming routine prompt, so kept small). Absent when the
+   *  head has no check runs, or best-effort when the check-runs read fails (never fatal). */
+  readonly checks?: PrChecksSummary;
+  /** Reviews/comments/commits roll-up (OPE-61) — the PR-ACTIVITY signal a status-only watch
+   *  misses. Counts only, no bodies (scm/pr-activity.ts). Absent when the underlying reads
+   *  weren't reachable; the review tally is best-effort like {@link checks}. */
+  readonly activity?: PrActivitySummary;
+  /** `base.repo.private` as GitHub reports it on the PR object this snapshot ALREADY fetches — the
+   *  source-tier table's deciding fact for the `github` row (OPE-331), so subscribe_pr's fenced PR
+   *  title reports a REAL verdict rather than the fail-closed guess. BASE, never HEAD (a fork's head
+   *  repo is public while the repo under watch is the base one). `undefined` only when GitHub omitted
+   *  the field. NO extra API call, and it is NOT part of the fingerprint — visibility is a property
+   *  of the repository, not a PR state change anyone subscribes to. */
+  readonly repoPrivate?: boolean;
+}
+
+/** One check run at the PR head, normalized. `conclusion` is null until the run completes. */
+export interface CheckRun {
+  readonly name: string;
+  /** queued | in_progress | completed */
+  readonly status: string;
+  /** success | failure | neutral | cancelled | timed_out | action_required | skipped | stale — null while running. */
+  readonly conclusion: string | null;
+  /** The run's `output.summary` (falls back to `output.title`), possibly empty. */
+  readonly summary: string;
+}
+
+/** A compact CI roll-up over a head's check runs — counts by outcome + the failing names. */
+export interface PrChecksSummary {
+  readonly total: number;
+  /** Count keyed by conclusion (or "pending" for a still-running run). */
+  readonly byConclusion: Readonly<Record<string, number>>;
+  /** Names of runs that concluded in a failure class — bounded by {@link MAX_FAILING_CHECK_NAMES}. */
+  readonly failing: readonly string[];
+  /** True when {@link failing} was capped (there are more failing runs than listed). */
+  readonly failingTruncated: boolean;
+  /** Runs still queued/in-progress. */
+  readonly pending: number;
+}
+
+/** Conclusions that count as a failing check for the `failing`/`describeChecks` roll-up. */
+export const CHECK_FAILURE_CONCLUSIONS: ReadonlySet<string> = new Set([
+  "failure",
+  "timed_out",
+  "action_required",
+  "cancelled",
+  "stale",
+]);
+
+/** Cap on failing check-run NAMES carried in a snapshot summary (counts stay exact). */
+export const MAX_FAILING_CHECK_NAMES = 20;
+
+/** Roll a list of check runs up into the compact {@link PrChecksSummary}. Pure. */
+export function summarizeChecks(runs: readonly CheckRun[]): PrChecksSummary {
+  const byConclusion: Record<string, number> = {};
+  const failing: string[] = [];
+  let pending = 0;
+  for (const r of runs) {
+    const bucket = r.conclusion ?? (r.status === "completed" ? "neutral" : "pending");
+    byConclusion[bucket] = (byConclusion[bucket] ?? 0) + 1;
+    if (r.conclusion !== null && CHECK_FAILURE_CONCLUSIONS.has(r.conclusion)) failing.push(r.name);
+    if (r.conclusion === null && r.status !== "completed") pending++;
+  }
+  return {
+    total: runs.length,
+    byConclusion,
+    failing: failing.slice(0, MAX_FAILING_CHECK_NAMES),
+    failingTruncated: failing.length > MAX_FAILING_CHECK_NAMES,
+    pending,
+  };
+}
+
+/** Fetch a head's check runs via `GET /repos/{repo}/commits/{ref}/check-runs`. */
+export async function fetchCheckRuns(opts: {
+  repo: string;
+  ref: string;
+  token: string;
+  fetchFn?: PrFetchFn;
+  apiBase?: string;
+}): Promise<CheckRun[]> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as PrFetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const res = await fetchFn(`${apiBase}/repos/${opts.repo}/commits/${opts.ref}/check-runs?per_page=100`, {
+    method: "GET",
+    headers: prApiHeaders(opts.token),
+  });
+  if (!res.ok) {
+    throw new Error(`GitHub check-runs lookup failed for ${opts.repo}@${opts.ref}: ${res.status} ${await res.text()}`);
+  }
+  const body = (await res.json()) as {
+    check_runs?: { name?: string; status?: string; conclusion?: string | null; output?: { title?: string; summary?: string } }[];
+  };
+  return (body.check_runs ?? []).map((c) => ({
+    name: c.name ?? "(unnamed)",
+    status: c.status ?? "unknown",
+    conclusion: c.conclusion ?? null,
+    summary: (c.output?.summary ?? c.output?.title ?? "").trim(),
+  }));
+}
+
+/** Fetch one PR's current status via `GET /repos/{repo}/pulls/{number}`, plus a best-effort
+ *  compact checks roll-up at its head (skipped silently if the head sha or check-runs read is
+ *  unavailable — the checks summary must never fail the status read a subscription depends on). */
+export async function fetchPullRequestStatus(opts: {
+  repo: string;
+  number: number;
+  token: string;
+  fetchFn?: PrFetchFn;
+  apiBase?: string;
+}): Promise<PrStatusSnapshot> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as PrFetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const res = await fetchFn(`${apiBase}/repos/${opts.repo}/pulls/${opts.number}`, {
+    method: "GET",
+    headers: prApiHeaders(opts.token),
+  });
+  if (!res.ok) {
+    throw new Error(`GitHub PR lookup failed for ${opts.repo}#${opts.number}: ${res.status} ${await res.text()}`);
+  }
+  const pr = (await res.json()) as {
+    html_url: string;
+    title: string;
+    state: string;
+    merged: boolean;
+    draft: boolean;
+    updated_at: string;
+    head?: { sha?: string };
+    // `base.repo.private` rides the response this call already makes (OPE-331) — see PrStatusSnapshot.
+    base?: { repo?: { private?: boolean } };
+    comments?: number;
+    review_comments?: number;
+    commits?: number;
+  };
+  // Three of the five activity counts ride the payload we already have — free (OPE-61).
+  const counts = {
+    issueComments: num(pr.comments),
+    reviewComments: num(pr.review_comments),
+    commits: num(pr.commits),
+  };
+  const base: PrStatusSnapshot = {
+    repo: opts.repo,
+    number: opts.number,
+    url: pr.html_url,
+    title: pr.title,
+    state: pr.state === "closed" ? "closed" : "open",
+    merged: Boolean(pr.merged),
+    draft: Boolean(pr.draft),
+    updatedAt: pr.updated_at,
+    activity: { reviews: 0, approvals: 0, changesRequested: 0, ...counts },
+    ...(typeof pr.base?.repo?.private === "boolean" ? { repoPrivate: pr.base.repo.private } : {}),
+  };
+  const headSha = pr.head?.sha;
+  if (!headSha) return base;
+  // Checks AND the review tally are both nice-to-haves on the snapshot, both keyed off having a
+  // head, and both best-effort: a failing secondary read must not sink the status a subscription
+  // re-arm depends on. Run them together so a subscription check costs one extra round trip, not
+  // two, and settle each independently.
+  const [runs, reviews] = await Promise.all([
+    fetchCheckRuns({ repo: opts.repo, ref: headSha, token: opts.token, fetchFn, apiBase }).catch(() => null),
+    fetchPrReviews({ repo: opts.repo, number: opts.number, token: opts.token, fetchFn, apiBase }).catch(() => null),
+  ]);
+  const activity: PrActivitySummary = { ...summarizeReviews(reviews ?? []), ...counts };
+  const checks = runs && runs.length > 0 ? summarizeChecks(runs) : undefined;
+  return checks ? { ...base, checks, activity } : { ...base, activity };
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0;
+}
+
+/** A compact one-line checks note for {@link describePrStatus}, e.g. `checks: 4 ok, 1 failing (build), 2 pending`. */
+export function describeChecks(c: PrChecksSummary): string {
+  const parts: string[] = [];
+  const ok = (c.byConclusion.success ?? 0) + (c.byConclusion.neutral ?? 0) + (c.byConclusion.skipped ?? 0);
+  if (ok > 0) parts.push(`${ok} ok`);
+  if (c.failing.length > 0 || c.failingTruncated) {
+    const names = c.failing.length > 0 ? ` (${c.failing.join(", ")}${c.failingTruncated ? ", …" : ""})` : "";
+    const failCount = c.total - ok - c.pending;
+    parts.push(`${failCount} failing${names}`);
+  }
+  if (c.pending > 0) parts.push(`${c.pending} pending`);
+  return `checks: ${parts.length > 0 ? parts.join(", ") : `${c.total} run(s)`}`;
+}
+
+/** One-line human summary of a snapshot — the "baseline" text a subscription embeds
+ *  in its next one-shot prompt so the re-armed check has something to diff against. */
+export function describePrStatus(s: PrStatusSnapshot): string {
+  const checks = s.checks ? ` — ${describeChecks(s.checks)}` : "";
+  const act = s.activity && prHasActivity(s.activity) ? ` — ${describeActivity(s.activity)}` : "";
+  return `${prStateLabel(s)} — "${s.title}" (updated ${s.updatedAt}) ${s.url}${checks}${act}`;
+}
+
+/** The OPEN/MERGED/CLOSED/draft label alone. */
+export function prStateLabel(s: PrStatusSnapshot): string {
+  return s.merged ? "MERGED" : s.state === "closed" ? "CLOSED (not merged)" : s.draft ? "OPEN (draft)" : "OPEN";
+}
+
+/**
+ * {@link describePrStatus} MINUS the PR title — the summary a routine PROMPT embeds (OPE-61).
+ *
+ * A PR title is third-party free text: whoever opened the PR wrote it. describePrStatus splices it
+ * into a plain sentence, which is fine for a tool result but NOT for a stored routine prompt, where
+ * it would land in trusted-instruction position in a LATER turn — the exact break-out routines/
+ * events.ts had to fix for webhook payloads (G3). subscribe_pr therefore builds its baseline from
+ * this title-free line and carries the title separately, inside an untrusted fence.
+ */
+export function describePrStatusStructural(s: PrStatusSnapshot): string {
+  const checks = s.checks ? ` — ${describeChecks(s.checks)}` : "";
+  const act = s.activity && prHasActivity(s.activity) ? ` — ${describeActivity(s.activity)}` : "";
+  return `${prStateLabel(s)} (updated ${s.updatedAt}) ${s.url}${checks}${act}`;
+}
+
+/** True once a PR has reached a terminal state — nothing left to watch for. */
+export function prIsSettled(s: PrStatusSnapshot): boolean {
+  return s.merged || s.state === "closed";
+}
+
+/**
+ * Resolve a READ-scoped GitHub credential for one repo: a GitHub App installation
+ * token minted with {@link PR_READ_PERMISSIONS} (never the write set open_pull_request.ts
+ * mints), falling back to a `GITHUB_TOKEN` PAT when the App isn't configured for that
+ * repo's owner. Mirrors open_pull_request.ts's resolvePrToken, read-scoped.
+ *
+ * 🔴 THE PERMISSION SET IS `PR_READ_PERMISSIONS`, NOT `READ_PERMISSIONS` (OPE-353). Every caller of
+ * this resolver starts at `GET /repos/{repo}/pulls/{number}`, and the mint narrows the token to
+ * whatever the request body asked for — so the checkout set (contents + metadata, no
+ * `pull_requests`) 403s that endpoint outright, which is what a live run saw. The two sets stay
+ * separate deliberately: this one is transient and in-memory, the checkout one is persisted into a
+ * clone's git config, and only the first may carry `pull_requests`. See scm/mint.ts.
+ */
+export async function resolveReadToken(repo: string, app: GitHubApp | null = getGitHubApp()): Promise<string> {
+  return await resolveTokenWith(repo, PR_READ_PERMISSIONS, app);
+}
+
+/**
+ * Resolve a CONVERSATION-READ credential for one repo — {@link CONVERSATION_READ_PERMISSIONS} via
+ * the GitHub App, with the same `GITHUB_TOKEN` PAT fallback {@link resolveReadToken} takes.
+ *
+ * 🔴 IT IS A SECOND RESOLVER, NOT A WIDENING OF {@link resolveReadToken} (OPE-1019). Its callers
+ * open at `GET /repos/{repo}/issues/{number}`, which serves an issue AND a pull request, so the
+ * token has to name BOTH permission families. `resolveReadToken`'s callers open at
+ * `GET /repos/{repo}/pulls/{number}`, which serves one kind and needs `contents` for the PR diff.
+ * One resolver for both call shapes would carry every permission either shape can want. See
+ * scm/mint.ts for the measurement behind the split.
+ */
+export async function resolveConversationReadToken(
+  repo: string,
+  app: GitHubApp | null = getGitHubApp(),
+): Promise<string> {
+  return await resolveTokenWith(repo, CONVERSATION_READ_PERMISSIONS, app);
+}
+
+/** The 8-liner both resolvers above share: mint through the App, else fall back to the PAT. The
+ *  permission set is the ONLY difference between them, so it is the only parameter. */
+async function resolveTokenWith(
+  repo: string,
+  permissions: MintPermissions,
+  app: GitHubApp | null,
+): Promise<string> {
+  if (app) {
+    const { tokens, ungranted } = await app.tokensForRepos([repo], permissions);
+    if (!ungranted.length) return tokens.get(repo.slice(0, repo.indexOf("/")))!.token;
+  }
+  const pat = process.env.GITHUB_TOKEN;
+  if (!pat) {
+    throw new Error("no GitHub credential: configure the GitHub App (OE_GITHUB_APP_*) or set GITHUB_TOKEN.");
+  }
+  return pat;
+}