@open-everywhere/core 0.1.0

package/agent/scm/mint.ts

@@ -0,0 +1,299 @@
+// Installation-token minting — the security-sensitive core. Two steps per GitHub's
+// docs: sign a short-lived app JWT (RS256), then exchange it for a repo-scoped
+// installation access token. The fetch is injectable so the whole path is testable
+// without network or real credentials. See docs/capabilities/source-control.md.
+
+import { createPrivateKey, type KeyObject } from "node:crypto";
+import { SignJWT } from "jose";
+import type { InstallationToken, MintPermissions } from "./types.js";
+import type { RepoCapability } from "../access/repo-capabilities.js";
+
+// The WRITE set — minted only inside the approval-gated PR flow (open_pull_request):
+// contents:write pushes the head branch, pull_requests:write opens the PR. metadata:read
+// is the implicit baseline GitHub requires.
+export const DEFAULT_PERMISSIONS: MintPermissions = {
+  contents: "write",
+  pull_requests: "write",
+  metadata: "read",
+};
+
+// The READ set — what checkout_repo mints for clone/fetch. This is the credential that
+// gets persisted into the clone's git config, so it must not be able to push: writes
+// only ever transit inside the approved PR flow (see tools/open_pull_request.ts).
+export const READ_PERMISSIONS: MintPermissions = {
+  contents: "read",
+  metadata: "read",
+};
+
+// The MEMORY-WRITE set — what the GitHub memory backing mints for its warm per-repo credential.
+// It reads, creates, updates and deletes files through the Contents API. It never opens or edits a
+// pull request, so it must not inherit the PR flow's `pull_requests:write` authority.
+export const MEMORY_WRITE_PERMISSIONS: MintPermissions = {
+  contents: "write",
+  metadata: "read",
+};
+
+// The PR-READ set — what the pr-status resolver mints (scm/pr-status.ts resolveReadToken) for the
+// read-only PR verbs that share it: check_pr_status, get_pr_feedback, walk_pr, subscribe_pr,
+// post_pr_walkthrough and the GitHub entity re-read.
+//
+// WHY IT EXISTS (OPE-353). Those verbs all begin at `GET /repos/{owner}/{repo}/pulls/{number}`, and
+// GitHub's installation-token mint NARROWS TO THE REQUEST BODY: a token minted without
+// `pull_requests` is refused on that endpoint — 403 "Resource not accessible by integration" —
+// however wide the INSTALLATION's own grant is. The grant was never the problem; the mint body was.
+// Until this set existed the resolver passed READ_PERMISSIONS, which has no `pull_requests` at all,
+// so every PR read through the App path 403'd and only a `GITHUB_TOKEN` PAT fallback ever worked.
+//
+// 🔴 IT IS A SEPARATE CONSTANT, NOT A WIDENING OF READ_PERMISSIONS, AND THAT IS THE POINT.
+// READ_PERMISSIONS is the credential checkout_repo PERSISTS into the clone's git config (scm/git.ts
+// — the one token in this plane that outlives its call), so it must stay the narrowest thing that
+// can clone. A token minted here is held in memory for a single api.github.com call and is written
+// nowhere; widening the persisted set to serve the transient one would trade a real fence for a
+// keystroke. Anything that clones keeps asking for READ_PERMISSIONS.
+export const PR_READ_PERMISSIONS: MintPermissions = {
+  contents: "read",
+  pull_requests: "read",
+  metadata: "read",
+};
+
+// ── THE CONVERSATION SETS (OPE-1019 / OPE-1020) ────────────────────────────────────────────────
+//
+// A GitHub CONVERSATION is an issue OR a pull request. The chat plane addresses both through the
+// same endpoints — `GET /repos/{r}/issues/{n}`, `GET|POST /repos/{r}/issues/{n}/comments` — because
+// GitHub's own API model makes every PR an issue. The PERMISSION does not follow that model: GitHub
+// lists those endpoints under BOTH the `issues` and the `pull_requests` repository permission, and
+// a token that names only one of the two is refused on the OTHER resource kind with 403 "Resource
+// not accessible by integration".
+//
+// MEASURED, twice, on deploy #118 with one App installation and one repo:
+//   • a token minted `{contents, pull_requests, metadata}` READ 403'd on a plain issue (OPE-1019);
+//   • a token minted `{issues: write}` POSTED 201 on a plain issue and 403'd on a pull request
+//     (OPE-1020) — the agent was MUTE on every PR thread.
+// Each half was the other's control: one session, one repo, minutes apart, only the mint body
+// different. No `github.token_mint_failed` row appeared, so the mint itself succeeded both times.
+//
+// 🔴 A SET THAT SERVES BOTH KINDS MUST NAME BOTH FAMILIES. That is the whole rule these two
+// constants exist to hold. It is the OPE-353 class one endpoint over: a call site moved and its
+// mint body did not follow. `github-mint-scope-test.ts` joins each call site's URLs to its mint
+// body so the next move cannot pass silently.
+//
+// The narrower alternative is a KIND-AWARE mint — pick `issues` or `pull_requests` from the
+// conversation kind. The kind IS known at the wake (github-identity.ts `conversationKind`), but it
+// rides neither `UnifiedWakeOrigin` nor `ReplyTarget` nor an edit locus, so a kind-aware mint would
+// add a field to three core contracts and double the warm-credential cache. Both sets below stay
+// far narrower than DEFAULT_PERMISSIONS: neither can touch `contents`, so neither can push code.
+
+// The CONVERSATION-READ set — what the chat/work read of an issue-or-PR conversation mints
+// (scm/pr-status.ts resolveConversationReadToken): the GitHub read adapter and the entity re-read.
+// It carries NO `contents`: a conversation read fetches an issue, its comments and a PR's review
+// comments, and never a file. So it is narrower than PR_READ_PERMISSIONS on one axis and wider on
+// the other, which is why it is a separate constant rather than a widening of that one.
+export const CONVERSATION_READ_PERMISSIONS: MintPermissions = {
+  issues: "read",
+  pull_requests: "read",
+  metadata: "read",
+};
+
+// The CONVERSATION-WRITE set — what the GitHub post arm mints for a comment on an issue OR a pull
+// request (providers/github channels/github-post-arm.ts: the comment POST, the comment PATCH and
+// the reaction POST). `pull_requests: write` lets the token change a PR's own metadata, which is
+// the price of a reply arm that is not mute on PR threads. It still cannot push code.
+export const CONVERSATION_WRITE_PERMISSIONS: MintPermissions = {
+  issues: "write",
+  pull_requests: "write",
+  metadata: "read",
+};
+
+// The ISSUE-WRITE set — minted only inside the ticket-action verbs (scm/issue-actions.ts:
+// set_state/assign/add_label and create_ticket, OPE-39). Deliberately narrower than
+// DEFAULT_PERMISSIONS: these verbs mutate an issue's state/assignees/labels via the Issues REST
+// API, never contents or PR metadata, so the token can't push code or open a PR even if it leaked.
+//
+// ⚠️ KNOWN LIMIT, FILED AS OPE-1021. The three mutation endpoints are ALSO listed under GitHub's
+// Pull requests permission, so this set is predicted to 403 on a PULL REQUEST for the same reason
+// OPE-1020 measured. It is NOT widened here: unlike the reply arm, nothing measured a break, and
+// the widening trades the PR-metadata fence this comment states. OPE-1021 carries the drive that
+// settles it. `create_ticket` (`POST /repos/{r}/issues`) is issues-only and is unaffected.
+export const ISSUE_WRITE_PERMISSIONS: MintPermissions = {
+  issues: "write",
+  metadata: "read",
+};
+
+// ── THE CAPABILITY EXPANSION (OPE-1024) ────────────────────────────────────────────────────────
+//
+// Everything above is a JOB SET: what one plane of work needs, declared narrow, uniform across every
+// repo and every domain. That stays the DEFAULT and it stays what a binding gets with no config.
+//
+// A domain binding may opt one repo into MORE, by naming a capability set (access/repo-capabilities.ts).
+// This is where a name becomes vendor permission families, and it is the only place that mapping
+// exists. Three rules hold it:
+//
+//  1. THE TABLE IS CLOSED IN CODE. Config names a set; it can never write a permission string. So
+//     the reachable families are exactly what this table lists, no matter how wide the App
+//     installation is, and no matter what a config author writes.
+//  2. EXPANSION IS A JOIN, NEVER AN ASSIGNMENT. `expandMintPermissions` unions the job set with the
+//     named sets and keeps the STRONGER of two grades for a family. So an expansion can only ever
+//     add to what the plane already declared — it cannot silently downgrade a family the job needs.
+//  3. 🔴 NO EXPANSION MAY TOUCH `contents`. `READ_PERMISSIONS` is the one token in this plane that
+//     OUTLIVES ITS CALL — checkout_repo persists it into the clone's git config (scm/git.ts). A
+//     capability that could raise `contents` would hand a pushable credential to cloned code, which
+//     is the exact fence the READ/PR_READ split above exists to keep. The rule is asserted at
+//     runtime rather than left to review, because the table is the kind of thing a later change
+//     extends without re-reading this comment.
+//
+// The App installation stays the one GLOBAL ceiling and is never restated here: GitHub refuses a
+// mint that asks past it, and that refusal is audited (`github.token_mint_failed`). That is the
+// always-on backstop for drift. The ask-time check (scm/capability-fit.ts) is the UX half.
+
+/** Permission families a capability set may never name — see rule 3 above. */
+export const EXPANSION_FORBIDDEN_FAMILIES: readonly string[] = ["contents"];
+
+/**
+ * NAME → GitHub permission families. The closed table; the ONLY place a capability name becomes a
+ * vendor permission. Every key must exist in access/repo-capabilities.ts and vice versa — the mint
+ * test asserts both directions, so a name can never ship with no mapping.
+ */
+export const REPO_CAPABILITY_PERMISSIONS: Readonly<Record<RepoCapability, MintPermissions>> = {
+  // OPE-1021: GitHub lists the issue-mutation endpoints under the Pull requests permission too, so
+  // an `issues`-only token is refused on a PULL REQUEST. This is what lets a domain act on PRs.
+  "pr-admin": { pull_requests: "write" },
+  // GitHub refuses a push that adds or changes `.github/workflows/**` unless the token carries the
+  // Workflows permission, whatever `contents` says.
+  workflows: { workflows: "write" },
+};
+
+/** Is `a` at least as strong as `b`? "write" beats "read"; an absent family is weakest. */
+function atLeast(a: string | undefined, b: string | undefined): boolean {
+  if (b === undefined) return true;
+  if (a === undefined) return false;
+  return a === "write" || a === b;
+}
+
+/**
+ * THE MINT DERIVATION. Start from the plane's job set; add the families every named capability set
+ * carries, keeping the stronger grade per family. Pure and total.
+ *
+ * Returns the job set UNCHANGED (same contents) when no capability is named — which is every
+ * binding written as a bare string, and therefore the whole of today's behaviour.
+ *
+ * Throws on a capability this build does not implement, and on any table entry that names a
+ * forbidden family. Both are code errors, not operator errors: config is validated at load
+ * (`assertBundlesValid`), so anything reaching here unknown means the two closed sets disagree.
+ * Failing loudly beats minting a token whose body nobody can explain.
+ */
+export function expandMintPermissions(
+  plane: MintPermissions,
+  capabilities: readonly RepoCapability[] = [],
+  // The table is a PARAMETER so the forbidden-family guard is drivable in a test. Production never
+  // passes it: there is exactly one table, and it is the one above.
+  table: Readonly<Record<string, MintPermissions>> = REPO_CAPABILITY_PERMISSIONS,
+): MintPermissions {
+  if (capabilities.length === 0) return plane;
+  const out: Record<string, string | undefined> = { ...plane };
+  for (const cap of capabilities) {
+    const add = table[cap];
+    if (!add) {
+      throw new Error(
+        `unknown repo capability "${cap}" — this build maps ${Object.keys(table).sort().join(", ")}. ` +
+          `A capability is a NAME this deployment implements, never a raw GitHub permission string.`,
+      );
+    }
+    for (const [family, grade] of Object.entries(add)) {
+      if (EXPANSION_FORBIDDEN_FAMILIES.includes(family)) {
+        throw new Error(
+          `repo capability "${cap}" maps to the forbidden permission family "${family}" — a capability expansion may never raise it. ` +
+            `READ_PERMISSIONS is persisted into a clone's git config, so a raisable "contents" would hand cloned code a pushable token.`,
+        );
+      }
+      if (!atLeast(out[family], grade)) out[family] = grade;
+    }
+  }
+  return out as MintPermissions;
+}
+
+/**
+ * Hosted platforms (Vercel env vars, etc.) often store the PEM with literal "\n"
+ * instead of real newlines; restore them so the key parses. (Mirrors Eve's own
+ * normalizeGitHubPrivateKey.) No-op when the PEM already has real newlines.
+ */
+export function normalizePrivateKeyPem(pem: string): string {
+  return pem.includes("\\n") && !pem.includes("\n") ? pem.replace(/\\n/g, "\n") : pem;
+}
+
+/**
+ * Parse a GitHub App private key PEM. GitHub issues PKCS#1
+ * ("BEGIN RSA PRIVATE KEY"); node:crypto handles both PKCS#1 and PKCS#8, whereas
+ * jose.importPKCS8 would reject PKCS#1 — hence node:crypto here.
+ */
+export function parsePrivateKey(pem: string): KeyObject {
+  return createPrivateKey(normalizePrivateKeyPem(pem));
+}
+
+/**
+ * Sign the app JWT. iat is back-dated 60s to absorb clock drift; exp is 9 min
+ * (GitHub rejects > 10). `nowSeconds` is injected so tests are deterministic.
+ */
+export async function signAppJwt(key: KeyObject, issuer: string, nowSeconds: number): Promise<string> {
+  return new SignJWT({})
+    .setProtectedHeader({ alg: "RS256", typ: "JWT" })
+    .setIssuedAt(nowSeconds - 60)
+    .setExpirationTime(nowSeconds + 9 * 60)
+    .setIssuer(issuer)
+    .sign(key);
+}
+
+/**
+ * Body for POST .../access_tokens — down-scoped to a repo subset (≤ 500, by name) and a
+ * permission subset. Can only narrow below the installation grant, never widen.
+ */
+export function buildMintBody(
+  repoNames: readonly string[],
+  permissions: MintPermissions,
+): { repositories: string[]; permissions: MintPermissions } {
+  return { repositories: [...new Set(repoNames)].slice(0, 500), permissions };
+}
+
+// A minimal fetch shape so callers can inject a mock; the global fetch satisfies it.
+export type FetchFn = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string>; json(): Promise<unknown> }>;
+
+interface MintResponse {
+  token: string;
+  expires_at: string;
+  repository_selection?: string;
+  repositories?: { full_name: string }[];
+}
+
+/** Exchange a signed app JWT for a repo-scoped installation token (1h TTL). */
+export async function mintInstallationToken(opts: {
+  jwt: string;
+  installationId: string;
+  repoNames: readonly string[];
+  permissions?: MintPermissions;
+  fetchFn?: FetchFn;
+  apiBase?: string;
+}): Promise<InstallationToken> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as FetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const res = await fetchFn(`${apiBase}/app/installations/${opts.installationId}/access_tokens`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${opts.jwt}`,
+      accept: "application/vnd.github+json",
+      "x-github-api-version": "2022-11-28",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(buildMintBody(opts.repoNames, opts.permissions ?? DEFAULT_PERMISSIONS)),
+  });
+  if (!res.ok) {
+    throw new Error(`installation token mint failed: ${res.status} ${await res.text()}`);
+  }
+  const json = (await res.json()) as MintResponse;
+  return {
+    token: json.token,
+    expiresAt: json.expires_at,
+    repositories: (json.repositories ?? []).map((r) => r.full_name),
+  };
+}

package/agent/scm/pr-activity.ts

@@ -0,0 +1,130 @@
+// PR ACTIVITY (OPE-61) — the review/comment/commit signal a STATUS-only subscription misses.
+//
+// subscribe_pr watched a PR's STATUS (open/closed/merged/draft/title, plus the OPE-103 checks
+// roll-up). But the thing people actually want to hear about — "someone approved it", "Alice
+// requested changes", "there are three new comments", "they pushed again" — was invisible: none
+// of it moves any of those fields. That is the gap between the shipped tool and the issue's own
+// title ("PR-ACTIVITY subscription"), and it is what the static config-as-code webhook path
+// (routines/events.ts, `pull_request_review` / `issue_comment` deliveries) already covered.
+//
+// This module is the counts-only roll-up that closes it, deliberately SMALLER than the
+// get_pr_feedback digest (scm/pr-feedback.ts): a subscription needs to know THAT feedback
+// arrived, not WHAT it said — the model calls get_pr_feedback when it wants to read it. So no
+// bodies ever land here, which is also why a subscription's roll-up is cheap enough to re-read
+// every check and safe enough to embed in a routine prompt.
+//
+// COST: three of the five counts (issue comments, inline review comments, commits) come FREE
+// off the single-PR payload fetchPullRequestStatus already reads. Only the review tally needs
+// its own call, and it rides the same best-effort block as the check-runs read.
+
+import { prApiHeaders, type PrFetchFn } from "./pr.js";
+
+/** Counts-only PR activity — no bodies, no authors beyond the single latest reviewer. */
+export interface PrActivitySummary {
+  /** Submitted reviews (PENDING drafts excluded — they belong to their author, not the PR). */
+  readonly reviews: number;
+  readonly approvals: number;
+  readonly changesRequested: number;
+  /** The most recent submitted review, as structure only (login + state), for the diff label. */
+  readonly latestReview?: { readonly author: string; readonly state: string };
+  /** Issue-thread comments on the PR (`comments` on the PR payload). */
+  readonly issueComments: number;
+  /** Inline diff comments (`review_comments` on the PR payload). */
+  readonly reviewComments: number;
+  readonly commits: number;
+}
+
+export const EMPTY_PR_ACTIVITY: PrActivitySummary = {
+  reviews: 0,
+  approvals: 0,
+  changesRequested: 0,
+  issueComments: 0,
+  reviewComments: 0,
+  commits: 0,
+};
+
+/** Only the review fields — what {@link summarizeReviews} derives from the reviews list. */
+export type PrReviewTally = Pick<PrActivitySummary, "reviews" | "approvals" | "changesRequested" | "latestReview">;
+
+/** The review shape we read (GitHub returns much more). */
+export interface RawPrReview {
+  readonly user?: { readonly login?: string };
+  readonly state?: string;
+}
+
+/** GitHub logins are `[A-Za-z0-9-]`, ≤39 chars — but this one ends up inside a routine PROMPT, so
+ *  narrow it to that alphabet HERE rather than trusting the API to have enforced it. Never a body. */
+const MAX_LOGIN_CHARS = 39;
+function safeLogin(login: string | undefined): string {
+  const s = (login ?? "").replace(/[^A-Za-z0-9._-]/g, "").slice(0, MAX_LOGIN_CHARS);
+  return s.length > 0 ? s : "(unknown)";
+}
+
+/**
+ * Tally submitted reviews. PENDING is an unsubmitted draft visible only to its author — never
+ * anyone's feedback — so it is dropped, exactly as fetchPrFeedback drops it. GitHub returns
+ * reviews oldest-first, so the LAST submitted one is the latest.
+ */
+export function summarizeReviews(raw: readonly RawPrReview[]): PrReviewTally {
+  let reviews = 0;
+  let approvals = 0;
+  let changesRequested = 0;
+  let latestReview: { author: string; state: string } | undefined;
+  for (const r of raw) {
+    const state = (r.state ?? "COMMENTED").toUpperCase();
+    if (state === "PENDING") continue;
+    reviews++;
+    if (state === "APPROVED") approvals++;
+    if (state === "CHANGES_REQUESTED") changesRequested++;
+    latestReview = { author: safeLogin(r.user?.login), state };
+  }
+  return latestReview ? { reviews, approvals, changesRequested, latestReview } : { reviews, approvals, changesRequested };
+}
+
+/** Fetch a PR's submitted reviews via `GET /repos/{repo}/pulls/{number}/reviews`. Throws on a bad
+ *  response — the CALLER decides whether that is fatal (fetchPullRequestStatus treats it as
+ *  best-effort, the same way it treats check-runs). */
+export async function fetchPrReviews(opts: {
+  repo: string;
+  number: number;
+  token: string;
+  fetchFn?: PrFetchFn;
+  apiBase?: string;
+}): Promise<RawPrReview[]> {
+  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}/reviews?per_page=100`, {
+    method: "GET",
+    headers: prApiHeaders(opts.token),
+  });
+  if (!res.ok) {
+    throw new Error(`GitHub reviews lookup failed for ${opts.repo}#${opts.number}: ${res.status} ${await res.text()}`);
+  }
+  const body = (await res.json()) as unknown;
+  // The single-PR endpoint and this one differ in shape; a stub/proxy that answers both with the
+  // PR object must not be read as a review list.
+  return Array.isArray(body) ? (body as RawPrReview[]) : [];
+}
+
+/** Has anything happened on this PR at all? An all-zero roll-up adds nothing to a summary line. */
+export function prHasActivity(a: PrActivitySummary): boolean {
+  return a.reviews > 0 || a.issueComments > 0 || a.reviewComments > 0 || a.commits > 0;
+}
+
+function plural(n: number, one: string, many = `${one}s`): string {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** Compact one-line activity note for a status summary, e.g.
+ *  `activity: 1 approval, 3 comments, 2 inline, 5 commits`. Empty string when nothing happened. */
+export function describeActivity(a: PrActivitySummary): string {
+  const parts: string[] = [];
+  if (a.approvals > 0) parts.push(plural(a.approvals, "approval"));
+  if (a.changesRequested > 0) parts.push(plural(a.changesRequested, "change request"));
+  const otherReviews = a.reviews - a.approvals - a.changesRequested;
+  if (otherReviews > 0) parts.push(plural(otherReviews, "review"));
+  if (a.issueComments > 0) parts.push(plural(a.issueComments, "comment"));
+  if (a.reviewComments > 0) parts.push(`${a.reviewComments} inline`);
+  if (a.commits > 0) parts.push(plural(a.commits, "commit"));
+  return parts.length > 0 ? `activity: ${parts.join(", ")}` : "";
+}

package/agent/scm/pr-diff.ts

@@ -0,0 +1,143 @@
+// A READ-ONLY, BOUNDED fetch of one PR's unified diff, plus the head sha and the file list.
+//
+// WHY A DEDICATED READ. `scm/pr-status.ts` answers "what state is this PR in" and
+// `scm/pr-feedback.ts` answers "what did people say about it". Neither returns the CHANGE, and the
+// PR-walkthrough flow (tools/walk_pr.ts) needs exactly that: the diff is the only thing an
+// independent reviewer with no repo access can judge, and the file list is what decides whether the
+// config-diff gate ran at all (review/facts-artifact.ts's `not-triggered` outcome).
+//
+// THE DIFF IS UNTRUSTED CONTENT, and this module never forgets it. Every byte is authored by
+// whoever opened the PR — including, on a bot-authored config PR, by a session that may itself have
+// been steered. Nothing here parses it for meaning; it is fetched, bounded, and handed on to be
+// fenced (`ingestUntrusted`) at the tool seam. The only structure this module extracts is the FILE
+// PATH list, from `diff --git` headers, which is host-side pattern matching over a format GitHub
+// controls rather than an interpretation of the content.
+//
+// Read-scoped credential (`resolveReadToken`), host-side — api.github.com is deliberately not
+// sandbox-reachable. Every network edge is injectable so the whole path is offline-testable.
+
+import { prApiHeaders, type PrFetchFn } from "./pr.js";
+
+/**
+ * Char cap on the unified diff carried into a review surface. A diff past this is reported clipped.
+ *
+ * Set BELOW `access/result-cap.ts`'s {@link DEFAULT_MAX_RESULT_CHARS} (120k) on purpose: the diff
+ * reaches the model inside an untrusted envelope, and `wrapUntrusted` caps that envelope too. If
+ * this cap were the larger of the two, the second one would silently clip the diff again — and the
+ * clip a reader was TOLD about would not be the clip that happened.
+ */
+export const MAX_DIFF_CHARS = 100_000;
+
+/** Cap on the number of file paths extracted from the diff. */
+const MAX_DIFF_FILES = 500;
+
+export interface PrDiffSnapshot {
+  readonly repo: string;
+  readonly number: number;
+  readonly headSha: string;
+  readonly baseRef: string;
+  /** The unified diff, possibly clipped — UNTRUSTED third-party text. */
+  readonly diff: string;
+  /** True when {@link diff} was clipped at {@link MAX_DIFF_CHARS}. */
+  readonly diffClipped: boolean;
+  /** Total chars GitHub returned, before clipping. */
+  readonly diffChars: number;
+  /** Paths the diff touches, sorted, possibly capped at {@link MAX_DIFF_FILES}. */
+  readonly files: readonly string[];
+  /** True when {@link files} was capped — so "this PR touches no config" must not be concluded from it. */
+  readonly filesCapped: boolean;
+  /** `base.repo.private` as GitHub reports it on the PR object {@link fetchPrDiff} ALREADY fetches —
+   *  the source-tier table's deciding fact for the `github` row (OPE-331), so `walk_pr`'s known
+   *  under-taint row states a REAL verdict instead of the fail-closed guess. BASE, never HEAD: a
+   *  fork's `head.repo` is public while the repository under review is the base one. `undefined`
+   *  only when GitHub omitted it, which keeps the table fail-closed. NO extra API call. */
+  readonly repoPrivate?: boolean;
+}
+
+/**
+ * Extract the touched paths from a unified diff's `diff --git a/X b/Y` headers.
+ *
+ * BOTH sides are collected, so a RENAME contributes its old and its new path. That matters for the
+ * trigger question: renaming a file OUT of `agent/` still moves the resolved config, and a reading
+ * that only took the `b/` side would call such a PR "touches no config".
+ *
+ * Quoted paths (git quotes a path containing a space or a non-ASCII byte) are NOT unquoted here —
+ * they are carried with their quotes, which makes them fail a glob match rather than match the
+ * wrong glob. Erring toward "unmatched" is the wrong direction for the trigger check, so callers
+ * treat a capped/odd file list as a reason not to conclude `not-triggered`; see {@link filesCapped}.
+ */
+export function filesFromUnifiedDiff(diff: string): string[] {
+  const out = new Set<string>();
+  for (const m of diff.matchAll(/^diff --git (?:"?a\/(.+?)"?) (?:"?b\/(.+?)"?)$/gmu)) {
+    if (m[1]) out.add(m[1]);
+    if (m[2]) out.add(m[2]);
+  }
+  return [...out].sort((a, b) => a.localeCompare(b));
+}
+
+/** Fetch the PR's head sha + base ref via `GET /repos/{repo}/pulls/{n}`. */
+async function fetchPrRefs(opts: {
+  repo: string;
+  number: number;
+  token: string;
+  fetchFn: PrFetchFn;
+  apiBase: string;
+}): Promise<{ headSha: string; baseRef: string; repoPrivate?: boolean }> {
+  const res = await opts.fetchFn(`${opts.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()}`);
+  // `base.repo.private` rides the response this call already makes (OPE-331) — the source-tier table's
+  // deciding fact for the `github` row, obtained with no extra request, scope or latency.
+  const pr = (await res.json()) as { head?: { sha?: string }; base?: { ref?: string; repo?: { private?: boolean } } };
+  const headSha = pr.head?.sha;
+  if (!headSha) throw new Error(`GitHub returned no head sha for ${opts.repo}#${opts.number} — the facts artifact cannot be located without it`);
+  const repoPrivate = pr.base?.repo?.private;
+  return { headSha, baseRef: pr.base?.ref ?? "(unknown)", ...(typeof repoPrivate === "boolean" ? { repoPrivate } : {}) };
+}
+
+/**
+ * Fetch the PR's unified diff + refs.
+ *
+ * The diff comes from the same `pulls/{n}` endpoint with `Accept: application/vnd.github.v3.diff`,
+ * which GitHub answers with `text/plain`. A PR too large for GitHub to render as a diff answers 406;
+ * that is surfaced as an error rather than an empty diff, because an empty diff would let a
+ * walkthrough claim it reviewed a change it never saw.
+ */
+export async function fetchPrDiff(opts: {
+  repo: string;
+  number: number;
+  token: string;
+  fetchFn?: PrFetchFn;
+  apiBase?: string;
+}): Promise<PrDiffSnapshot> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as PrFetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const { headSha, baseRef, repoPrivate } = await fetchPrRefs({ repo: opts.repo, number: opts.number, token: opts.token, fetchFn, apiBase });
+
+  const res = await fetchFn(`${apiBase}/repos/${opts.repo}/pulls/${opts.number}`, {
+    method: "GET",
+    headers: { ...prApiHeaders(opts.token), accept: "application/vnd.github.v3.diff" },
+  });
+  if (!res.ok) {
+    throw new Error(
+      `GitHub diff read failed for ${opts.repo}#${opts.number}: ${res.status} ${await res.text()}` +
+        (res.status === 406 ? " (406 means the diff is too large for GitHub to render — review it in the UI; nothing here may claim to have read it)" : ""),
+    );
+  }
+  const raw = await res.text();
+  const files = filesFromUnifiedDiff(raw);
+  return {
+    repo: opts.repo,
+    number: opts.number,
+    headSha,
+    baseRef,
+    diff: raw.length > MAX_DIFF_CHARS ? `${raw.slice(0, MAX_DIFF_CHARS)}\n…[diff clipped at ${MAX_DIFF_CHARS} chars of ${raw.length}]` : raw,
+    diffClipped: raw.length > MAX_DIFF_CHARS,
+    diffChars: raw.length,
+    files: files.slice(0, MAX_DIFF_FILES),
+    filesCapped: files.length > MAX_DIFF_FILES,
+    ...(repoPrivate !== undefined ? { repoPrivate } : {}),
+  };
+}