@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/findingscheck.ts

@@ -0,0 +1,298 @@
+// The findings record's enforcement: the daemon's half of the durable
+// reasoning record (packages/pi-plugin/src/findingsrecord.ts says what the record is, and holds
+// its parser). After a round, the record is parsed into queryable rows; a
+// missing or unparseable one costs an anomaly every time and at most ONE
+// nudge, through `wakeOrHold`, and a record that lands after its nudge is
+// still stored. A round is never held open for it.
+import {
+  findingsRecordFile,
+  findingsRecordPath,
+  findingsRecordWake,
+  isConformant,
+  readFindingsRecord,
+  type FindingsRecordFile,
+  type ParsedFindingsRecord,
+} from "@quickchatai/pi-quickreview/src/findingsrecord.js";
+import { enqueueRoundWork, finishRoundWork, pendingRoundWork } from "./round-work.js";
+import type { StateStore } from "./state.js";
+import { wakeOrHold } from "./wakes.js";
+
+export interface FindingsCheckDeps {
+  store: StateStore;
+  /** Where the record lives — daemon.ts passes `<root>/state/findings`. */
+  findingsDir: string;
+  /** SessionHooks.inject — rides wakeOrHold, so a check that somehow lands
+   * mid-round holds rather than interleaving (rule 9). */
+  inject: (pr: number, message: string) => Promise<void>;
+  log?: (msg: string, extra?: unknown) => void;
+  /**
+   * Told every time a round's findings record LANDS in `round_findings`: the
+   * lesson shadow ledger marks the round's posted
+   * findings a selected dont-raise lesson would have touched
+   * (src/lessonshadow.ts). Runs asynchronously after `findings_recorded`;
+   * its durable obligation is retried until the callback returns successfully.
+   * A returned promise is awaited; synchronous callbacks stay accepted.
+   */
+  onRecorded?: (target: { pr: number; roundNo: number; roundId: number | null }) => unknown;
+}
+
+export interface FindingsCheckTarget {
+  pr: number;
+  roundNo: number;
+  /** The round row the parsed entries hang off. Null ⇒ rows are still stored,
+   * attributed by (pr, round_no) alone. */
+  roundId: number | null;
+  headSha: string;
+  /** The round's PLANNED lenses (`rounds.lenses`). The add protocol lets the
+   * main pi run a lens that appears in no plan, so the executed set is NOT
+   * assumed equal to the plan: a lens outside this list is stored with
+   * `unplanned = 1` rather than dropped or treated as an error. */
+  planned: readonly string[];
+}
+
+export type FindingsCheckResult = "recorded" | "nudged" | "already_nudged";
+
+/**
+ * The enforcement step. Parsed ⇒ rows are written and the per-round comment
+ * count lands on the round. Otherwise an anomaly EVERY time (the durable
+ * audit trail) — `findings_record_missing` until the round's one nudge has
+ * gone out, `findings_record_unresolved` after it — plus at most ONE nudge.
+ *
+ * The once-mark is stamped BEFORE the inject, so no failure mode — a throwing
+ * inject, a crash between the two, a second sweep of the same round — can ever
+ * nudge twice. The safety direction is "never a loop"; the wake is best-effort
+ * on top of a durable anomaly row.
+ */
+export async function enforceFindingsRecord(
+  deps: FindingsCheckDeps,
+  target: FindingsCheckTarget,
+): Promise<FindingsCheckResult> {
+  const { store, log } = deps;
+  const { pr, roundNo, headSha, planned } = target;
+  const path = findingsRecordPath(deps.findingsDir, pr, roundNo);
+  const parsed = readFindingsRecord(path, pr, roundNo);
+
+  if (parsed.status === "ok" && parsed.record) {
+    ingestFindingsRecord(deps, target, parsed, parsed.record);
+    return "recorded";
+  }
+
+  const detail = `findings record ${parsed.status} at ${path}`;
+  log?.(`findings: #${pr} round ${roundNo} record ${parsed.status}`, { path });
+
+  const key = `round-${roundNo}`;
+  if (store.findingsNudgeSent(pr, key)) {
+    // Still missing AFTER its one nudge: the session ignored it. A distinct,
+    // WAKE-grade kind (anomalies.ts) — first detection stays quiet, because
+    // the nudge itself is the response.
+    store.logAnomaly("findings_record_unresolved", pr, roundNo, detail);
+    store.logEvent("findings_record_repeat", pr, { round_no: roundNo, status: parsed.status });
+    return "already_nudged";
+  }
+  store.logAnomaly("findings_record_missing", pr, roundNo, detail);
+  // The mark carries what `ingestRepairedFindingsRecords` needs to store the
+  // record the nudge asks for once it lands.
+  store.recordFindingsNudge(pr, key, {
+    round_no: roundNo,
+    round_id: target.roundId,
+    head_sha: headSha,
+    planned: [...planned],
+    status: parsed.status,
+  });
+  await wakeOrHold(
+    { store, inject: deps.inject, ...(log ? { log } : {}) },
+    pr,
+    findingsRecordWake(pr, roundNo, `state/findings/${findingsRecordFile(pr, roundNo)}`),
+    "findings_record_missing",
+  );
+  return "nudged";
+}
+
+/** How long after its nudge a missing record is still looked for. */
+export const FINDINGS_REPAIR_WINDOW_MS = 7 * 24 * 3_600_000;
+
+/**
+ * Store the records the missing-record nudge asked for. The round's tail
+ * checks once and nudges once; the reconstructed file lands later, when no
+ * round tail is left to read it. So every sweep re-reads the record of each
+ * round nudged within `FINDINGS_REPAIR_WINDOW_MS` that has no
+ * `findings_recorded` event yet, and stores a record that now parses exactly
+ * as the tail would have — rows, comment count, prior reports, the
+ * `findings_recorded` event and `onRecorded`. A record still missing is left
+ * alone: no second nudge and no further anomaly. Returns how many it stored.
+ */
+export function ingestRepairedFindingsRecords(
+  deps: Pick<FindingsCheckDeps, "store" | "findingsDir" | "log" | "onRecorded">,
+  now: Date,
+): number {
+  const { store } = deps;
+  const since = new Date(now.getTime() - FINDINGS_REPAIR_WINDOW_MS).toISOString();
+  const nudges = store.db
+    .prepare(
+      "SELECT pr, payload FROM events WHERE kind = 'findings_record_nudged' AND ts >= ? ORDER BY id",
+    )
+    .all(since) as Array<{ pr: number | null; payload: string | null }>;
+  const recorded = store.db.prepare(
+    "SELECT 1 FROM events WHERE kind = 'findings_recorded' AND pr = ? AND json_extract(payload, '$.round_no') = ? LIMIT 1",
+  );
+  const roundRow = store.db.prepare(
+    "SELECT id, lenses, head_sha FROM rounds WHERE pr = ? AND round_no = ? ORDER BY id DESC LIMIT 1",
+  );
+  let stored = 0;
+  for (const n of nudges) {
+    if (n.pr === null || !n.payload) continue;
+    let mark: { round_no?: unknown; round_id?: unknown; head_sha?: unknown; planned?: unknown };
+    try {
+      mark = JSON.parse(n.payload) as typeof mark;
+    } catch {
+      continue;
+    }
+    const roundNo = typeof mark.round_no === "number" ? mark.round_no : null;
+    if (roundNo === null || recorded.get(n.pr, roundNo) !== undefined) continue;
+    const parsed = readFindingsRecord(
+      findingsRecordPath(deps.findingsDir, n.pr, roundNo),
+      n.pr,
+      roundNo,
+    );
+    if (parsed.status !== "ok" || !parsed.record) continue;
+    // A mark written before it carried the round's identity: the round row.
+    const round = roundRow.get(n.pr, roundNo) as
+      { id: number; lenses: string | null; head_sha: string | null } | undefined;
+    const planned = Array.isArray(mark.planned)
+      ? mark.planned.filter((l): l is string => typeof l === "string")
+      : (round?.lenses ?? "").split(",").filter(Boolean);
+    ingestFindingsRecord(
+      deps,
+      {
+        pr: n.pr,
+        roundNo,
+        roundId: typeof mark.round_id === "number" ? mark.round_id : (round?.id ?? null),
+        headSha: typeof mark.head_sha === "string" ? mark.head_sha : (round?.head_sha ?? ""),
+        planned,
+      },
+      parsed,
+      parsed.record,
+    );
+    deps.log?.(`findings: #${n.pr} round ${roundNo} record arrived after its nudge — stored`);
+    stored++;
+  }
+  return stored;
+}
+
+/** Store one parsed record: its rows, the round's comment count, the prior
+ * reports, the `findings_recorded` event, `onRecorded`, and the output-rule
+ * audit. */
+function ingestFindingsRecord(
+  deps: Pick<FindingsCheckDeps, "store" | "log" | "onRecorded">,
+  target: FindingsCheckTarget,
+  parsed: ParsedFindingsRecord,
+  record: FindingsRecordFile,
+): void {
+  const { store, log } = deps;
+  const { pr, roundNo, roundId, headSha, planned } = target;
+  const stored = store.db.transaction(() => {
+    const stored = store.recordRoundFindings(
+      { pr, round_id: roundId, round_no: roundNo, head_sha: record.head_sha ?? headSha },
+      record.findings,
+      planned,
+    );
+    if (record.comments_posted !== null && roundId !== null)
+      store.recordRoundComments(roundId, record.comments_posted);
+    // The statuses this round reported for prior findings. Stored
+    // beside the listing the daemon made at order build; the next round's
+    // list drops what a later report resolved.
+    const priorReported =
+      record.prior.length > 0
+        ? store.recordPriorReports(pr, roundNo, record.head_sha ?? headSha, record.prior)
+        : 0;
+    if (deps.onRecorded)
+      enqueueRoundWork(store, {
+        key: `findings_hook:${roundId ?? `${pr}:${roundNo}`}`,
+        kind: "findings_hook",
+        pr,
+        round_no: roundNo,
+        due_at: "",
+        payload: { pr, roundNo, roundId },
+      });
+    store.logEvent("findings_recorded", pr, {
+      round_id: roundId,
+      round_no: roundNo,
+      entries: stored,
+      comments_posted: record.comments_posted,
+      ...(priorReported > 0 ? { prior_reported: priorReported } : {}),
+      ...(parsed.note ? { note: parsed.note } : {}),
+    });
+    return stored;
+  })();
+  void resumeFindingsRecordedHooks(deps);
+  // The round's posted output against the three output rules. A quiet
+  // anomaly (anomalies.ts wakes nobody for this kind) — a durable, queryable
+  // row is the point, and no round is ever held open for it.
+  const c = parsed.conformance;
+  if (c) {
+    store.logEvent("findings_conformance", pr, {
+      round_no: roundNo,
+      ungrammatical_tags: c.ungrammatical_tags.length,
+      nits_without_request: c.nits_without_request.length,
+      doubted_posted: c.doubted_posted.length,
+      restated: c.restated.length,
+    });
+    if (!isConformant(c)) {
+      store.logAnomaly(
+        "review_output_unreasoned",
+        pr,
+        roundNo,
+        `posted output outside the output rules: ${c.ungrammatical_tags.length} tag(s) outside the grammar ` +
+          `(${c.ungrammatical_tags.join(", ")}), ${c.nits_without_request.length} nit(s) asking for nothing ` +
+          `(${c.nits_without_request.join(", ")})` +
+          (c.doubted_posted.length > 0
+            ? `, ${c.doubted_posted.length} doubted finding(s) posted (${c.doubted_posted.join(", ")})`
+            : ""),
+      );
+    }
+  }
+  log?.(
+    `findings: #${pr} round ${roundNo} recorded ${stored} entr${stored === 1 ? "y" : "ies"}` +
+      (parsed.note ? ` (${parsed.note})` : ""),
+  );
+}
+
+const recordedHookFlights = new WeakMap<StateStore, Promise<void>>();
+
+/** Resume unfinished callback delivery. The callback may return an async
+ * completion; legacy synchronous callbacks remain accepted. No round waits
+ * for this worker, and an exhausted per-thread failure remains terminal. */
+export function resumeFindingsRecordedHooks(
+  deps: Pick<FindingsCheckDeps, "store" | "log" | "onRecorded">,
+): Promise<void> {
+  if (!deps.onRecorded) return Promise.resolve();
+  const existing = recordedHookFlights.get(deps.store);
+  if (existing) return existing;
+  const work = Promise.resolve()
+    .then(async () => {
+      for (const row of pendingRoundWork(deps.store, "findings_hook", new Date().toISOString())) {
+        try {
+          const target = JSON.parse(row.payload) as {
+            pr: number;
+            roundNo: number;
+            roundId: number | null;
+          };
+          await deps.onRecorded!(target);
+          finishRoundWork(deps.store, row.key, new Date().toISOString());
+        } catch (err) {
+          deps.log?.(
+            `findings: #${row.pr} round ${row.round_no} recorded hook incomplete — retained for retry`,
+            err,
+          );
+        }
+      }
+    })
+    .catch((err: unknown) => {
+      deps.log?.("findings: recorded hook worker unavailable — obligations retained", err);
+    })
+    .finally(() => {
+      recordedHookFlights.delete(deps.store);
+    });
+  recordedHookFlights.set(deps.store, work);
+  return work;
+}

package/src/fsdenied.ts

@@ -0,0 +1,24 @@
+// When a verb may not write where it tried. A filesystem refusal (no
+// permission, a read-only file system) on a path is the person's to fix, so
+// the `qcr` bin says it in one line naming the path and the refusal, never as
+// a stack trace. Any other error is not this one and is left to propagate.
+
+const REFUSALS: Readonly<Record<string, string>> = {
+  EACCES: "permission denied",
+  EPERM: "operation not permitted",
+  EROFS: "read-only file system",
+};
+
+/** The one line for `err` when it is a filesystem refusal on a named path,
+ * else null. */
+export function fsDeniedLine(verb: string | undefined, err: unknown): string | null {
+  if (!(err instanceof Error)) return null;
+  const e = err as { code?: unknown; path?: unknown; syscall?: unknown };
+  const code = typeof e.code === "string" ? e.code : "";
+  const why = REFUSALS[code];
+  if (why === undefined) return null;
+  const path = typeof e.path === "string" && e.path !== "" ? e.path : null;
+  if (path === null) return null;
+  const op = typeof e.syscall === "string" && e.syscall !== "" ? `, ${e.syscall}` : "";
+  return `qcr${verb ? ` ${verb}` : ""}: ${path}: ${why} (${code}${op}) — \`qcr install where\` shows where this install keeps its files`;
+}

package/src/ghread.ts

@@ -0,0 +1,242 @@
+// The session helpers' GitHub reads, served by the daemon.
+//
+// pr-context.sh, pr-checks.sh, pr-threads.sh and pr-self.sh read the reviewed
+// PR from GitHub. They used to mint an installation token themselves
+// (scripts/mint-token.sh), which needs the App's private key: so the model's
+// bash, which runs them, had to be able to read secrets/. On a host the daemon
+// runs (a round worker, an answer worker, a takeover, a debug round) they now ask
+// the daemon instead, over the worker socket with the command's capability
+// (src/ipc/ghreadshim.ts), and the model's tools run as a uid that cannot read
+// secrets/ at all (docker/entrypoint.sh).
+//
+// What the daemon serves is a READ and nothing else, of the reviewed repo and
+// nothing else:
+//   - `rest`: one GET of a path under /repos/<the configured repo>/, a plain
+//     path and query (no `..`, no empty segment, no scheme or host). GET is the
+//     only method there is; a body is never sent.
+//   - `graphql`: one of the queries this module holds (GH_READ_QUERIES), by
+//     name, with the variables that query declares. The owner and the name are
+//     the configured repo's, filled in here; a session never sends query text,
+//     so no mutation can be spelled.
+// GitHub's answer comes back as it is: the status and the body as text, capped
+// (a job log keeps its tail). Nothing here writes, and nothing goes near the
+// MutationGate: there is no mutation to gate.
+import type { RawReadAnswer, RawReadOptions } from "./github.js";
+import type { OpHandler, RequestContext } from "./ipc/server.js";
+import { GH_READ_OP, IpcError } from "./ipc/protocol.js";
+
+export { GH_READ_OP };
+
+/** The most of a body a read hands back, and of a job log's tail. */
+export const GH_READ_MAX_BYTES = 4 * 1024 * 1024;
+export const GH_READ_LOG_TAIL_BYTES = 512 * 1024;
+
+/** The GraphQL reads the helpers make, by name: the query text and the
+ * variables it declares beside `$owner`/`$name` (which are the repo's). Each
+ * text is the script's own, byte for byte where the script still carries it for
+ * a host without the daemon (tests/gh-read.test.ts holds the two equal). */
+export const GH_READ_QUERIES = {
+  "pr-threads": {
+    text: `query($owner:String!,$name:String!,$number:Int!,$after:String){
+  repository(owner:$owner,name:$name){ pullRequest(number:$number){
+    reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}
+      nodes{id isResolved isOutdated path line
+        comments(first:100){totalCount nodes{databaseId author{login} body}}}}}}}`,
+    cursors: ["after"],
+  },
+  "pr-context": {
+    text: `query($owner:String!,$name:String!,$number:Int!,$filesCursor:String,$threadsCursor:String){
+      repository(owner:$owner,name:$name){pullRequest(number:$number){
+        title state headRefOid baseRefName author{login}
+        files(first:100,after:$filesCursor){nodes{path additions deletions} pageInfo{hasNextPage endCursor}}
+        reviews(last:10){nodes{author{login} state submittedAt}}
+        reviewThreads(first:100,after:$threadsCursor){nodes{id isResolved isOutdated path line
+          comments(last:2){nodes{author{login} body}}} pageInfo{hasNextPage endCursor}}
+      }}}`,
+    cursors: ["filesCursor", "threadsCursor"],
+  },
+} as const satisfies Record<string, { text: string; cursors: readonly string[] }>;
+
+export type GhReadQueryName = keyof typeof GH_READ_QUERIES;
+
+/** One read, as the daemon will make it. */
+export type GhRead =
+  | { kind: "rest"; path: string; tail: boolean }
+  | { kind: "graphql"; name: GhReadQueryName; variables: Record<string, unknown> };
+
+/** What answers a read: the adapter's raw reads. */
+export interface GhReader {
+  readonly owner: string;
+  readonly repo: string;
+  readText(path: string, o: RawReadOptions): Promise<RawReadAnswer>;
+  graphqlText(
+    query: string,
+    variables: Record<string, unknown>,
+    o: RawReadOptions,
+  ): Promise<RawReadAnswer>;
+}
+
+const SEGMENT = /^[A-Za-z0-9._~%-]+$/;
+const QUERY = /^[A-Za-z0-9._~%&=,-]*$/;
+const CURSOR = /^[A-Za-z0-9+/=_:-]{1,512}$/;
+
+function bad(message: string): IpcError {
+  return new IpcError("bad_request", `github.read: ${message}`);
+}
+
+/** A REST path the helpers may read: a plain path under the repo's own
+ * /repos/<owner>/<repo>/, with an optional plain query. */
+export function readablePath(path: unknown, owner: string, repo: string): string {
+  if (typeof path !== "string" || path.length === 0 || path.length > 2048)
+    throw bad("`path` must be a string of at most 2048 characters");
+  const q = path.indexOf("?");
+  const pathPart = q === -1 ? path : path.slice(0, q);
+  const query = q === -1 ? "" : path.slice(q + 1);
+  if (!QUERY.test(query)) throw bad(`the query of ${JSON.stringify(path)} is not a plain query`);
+  if (!pathPart.startsWith("/")) throw bad("`path` must start with /repos/<owner>/<repo>/");
+  const segs = pathPart.slice(1).split("/");
+  if (segs.some((s) => !SEGMENT.test(s) || s === "." || s === ".."))
+    throw bad(`${JSON.stringify(path)} is not a plain path`);
+  if (segs.some((s) => /%2e|%2f|%5c/i.test(s)))
+    throw bad(`${JSON.stringify(path)} carries an encoded separator`);
+  const [r, o, n, ...rest] = segs;
+  if (
+    r !== "repos" ||
+    o?.toLowerCase() !== owner.toLowerCase() ||
+    n?.toLowerCase() !== repo.toLowerCase() ||
+    rest.length === 0
+  )
+    throw bad(`only the reviewed repo is read (/repos/${owner}/${repo}/…), not ${path}`);
+  return path;
+}
+
+/** The request body of a read, checked. Throws bad_request. */
+export function parseGhRead(body: unknown, owner: string, repo: string): GhRead {
+  if (typeof body !== "object" || body === null || Array.isArray(body))
+    throw bad("the body must be an object");
+  const b = body as Record<string, unknown>;
+  if (b["kind"] === "rest") {
+    const path = readablePath(b["path"], owner, repo);
+    return { kind: "rest", path, tail: /\/actions\/jobs\/\d+\/logs$/.test(path.split("?")[0]!) };
+  }
+  if (b["kind"] === "graphql") {
+    const name = b["name"];
+    if (typeof name !== "string" || !Object.hasOwn(GH_READ_QUERIES, name))
+      throw bad(
+        `unknown query ${JSON.stringify(name)} (${Object.keys(GH_READ_QUERIES).join(", ")})`,
+      );
+    const q = GH_READ_QUERIES[name as GhReadQueryName];
+    const raw = b["variables"];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+      throw bad("`variables` must be an object");
+    const given = raw as Record<string, unknown>;
+    const allowed = new Set<string>(["number", ...q.cursors]);
+    for (const k of Object.keys(given))
+      if (!allowed.has(k)) throw bad(`query ${name} takes no variable ${JSON.stringify(k)}`);
+    const number = given["number"];
+    if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 1)
+      throw bad("`variables.number` must be a positive integer");
+    const variables: Record<string, unknown> = { owner, name: repo, number };
+    for (const c of q.cursors) {
+      const v = given[c];
+      if (v === undefined || v === null) variables[c] = null;
+      else if (typeof v === "string" && CURSOR.test(v)) variables[c] = v;
+      else throw bad(`\`variables.${c}\` must be a cursor string or null`);
+    }
+    return { kind: "graphql", name: name as GhReadQueryName, variables };
+  }
+  throw bad("`kind` must be rest or graphql");
+}
+
+/** What the op answers: GitHub's status and body, and whether it was cut. */
+export interface GhReadAnswer {
+  status: number;
+  body: string;
+  truncated: boolean;
+}
+
+/** The PR a read names, where it names one: a REST path under the repo's
+ * pulls/<n> or issues/<n>, or a GraphQL query's `number`. Null for a repo-wide
+ * read (a check run, a job log, a commit), which belongs to no PR. */
+export function readPr(read: GhRead): number | null {
+  if (read.kind === "graphql") return read.variables["number"] as number;
+  // Percent-escapes are decoded first: `%38` names PR 8 as surely as `8` does.
+  const decoded = read.path
+    .split("?")[0]!
+    .split("/")
+    .map((seg) => {
+      try {
+        return decodeURIComponent(seg);
+      } catch {
+        return seg;
+      }
+    })
+    .join("/");
+  const m = /^\/repos\/[^/]+\/[^/]+\/(?:pulls|issues)\/(\d+)(?:\/|$)/.exec(decoded);
+  return m ? Number(m[1]) : null;
+}
+
+/** At most this many reads in flight for one PR, and this many a minute. A
+ * session's helpers make a handful per call; the bounds keep a looping one from
+ * spending the App's rate limit for every other PR. */
+export const GH_READ_MAX_IN_FLIGHT = 4;
+export const GH_READ_PER_MINUTE = 120;
+
+/** Serve one read. */
+export async function serveGhRead(reader: GhReader, read: GhRead): Promise<GhReadAnswer> {
+  if (read.kind === "rest")
+    return reader.readText(read.path, {
+      maxBytes: read.tail ? GH_READ_LOG_TAIL_BYTES : GH_READ_MAX_BYTES,
+      tail: read.tail,
+    });
+  return reader.graphqlText(GH_READ_QUERIES[read.name].text, read.variables, {
+    maxBytes: GH_READ_MAX_BYTES,
+  });
+}
+
+/** The op the worker socket serves. Every caller a worker, a post shim or a
+ * pane's script holds a live command; a read needs nothing more (an answer
+ * worker without may_post has no bash, and a takeover may read). */
+export function ghReadOps(deps: {
+  reader: GhReader;
+  log?: (line: string) => void;
+  now?: () => number;
+}): Record<string, OpHandler> {
+  const now = deps.now ?? Date.now;
+  const inFlight = new Map<number, number>();
+  const recent = new Map<number, number[]>();
+  return {
+    [GH_READ_OP]: {
+      roles: ["shim", "worker"],
+      handle: async (ctx: RequestContext, body: unknown) => {
+        const read = parseGhRead(body, deps.reader.owner, deps.reader.repo);
+        // A read that names a PR names the command's own (wrong_pr otherwise).
+        const named = readPr(read);
+        if (named !== null) ctx.requirePr(named);
+        const t = now();
+        const window = (recent.get(ctx.pr) ?? []).filter((at) => t - at < 60_000);
+        const flying = inFlight.get(ctx.pr) ?? 0;
+        if (flying >= GH_READ_MAX_IN_FLIGHT || window.length >= GH_READ_PER_MINUTE)
+          throw new IpcError(
+            "rate_limited",
+            `github.read: pr ${ctx.pr} has ${flying} reads in flight and ${window.length} in the last minute (at most ${GH_READ_MAX_IN_FLIGHT} and ${GH_READ_PER_MINUTE}) — wait and try again`,
+          );
+        window.push(t);
+        recent.set(ctx.pr, window);
+        inFlight.set(ctx.pr, flying + 1);
+        try {
+          return await serveGhRead(deps.reader, read);
+        } catch (e) {
+          deps.log?.(
+            `github.read for pr ${ctx.pr} (${read.kind === "rest" ? read.path : read.name}) failed: ${String(e)}`,
+          );
+          throw new IpcError("internal", `github.read: the request failed (${String(e)})`);
+        } finally {
+          const left = (inFlight.get(ctx.pr) ?? 1) - 1;
+          if (left > 0) inFlight.set(ctx.pr, left);
+          else inFlight.delete(ctx.pr);
+        }
+      },
+    },
+  };
+}