@open-everywhere/provider-github 0.0.0-stage → 0.1.0

package/agent/channels/github-reaction-feedback.ts

@@ -0,0 +1,489 @@
+// THE GITHUB REACTION-FEEDBACK ARM (OPE-1502) — a reaction on the agent's own comment becomes a
+// durable feedback signal, the same way it already does on Slack and Discord.
+//
+// 🔴 GITHUB PUSHES NO REACTION WEBHOOK. Slack, Discord, Teams and Linear all DELIVER a reaction
+// event; GitHub delivers none for an issue, a pull request or a comment. That is the same vendor
+// fact the stop arm rests on (channels/github-stop.ts, which is a `stop` COMMENT for exactly this
+// reason). So the inbound half here is a READ, not a delivery — and every design choice below falls
+// out of that one difference.
+//
+// ── THE TRIGGER, AND WHAT IT COSTS
+//
+// The poll rides an inbound delivery this deployment already receives for the same conversation: an
+// `issue_comment` or `issues` webhook names an issue, and the arm then reads the reactions on the
+// agent's own comments in it. A reaction therefore reaches the seat on the NEXT delivery for that
+// conversation, not the instant somebody clicks. That is a real latency, it is the honest ceiling of
+// what GitHub offers, and it is what the bundle's parity declaration says out loud rather than
+// claiming a parity this surface does not have.
+//
+// 🔴 TWO GATES RUN BEFORE THE FIRST REST CALL (OPE-1540), and channels/github-reaction-scope.ts owns
+// both. The agent must be IN this conversation — a conversation it is not in can hold no reaction it
+// could record — and the repository must have hourly budget left. Only then does the arm read
+// anything. Before those gates every delivery paid the issue read and the comment page just to
+// discover there was nothing to look at.
+//
+// 🔴 READING THE NEWEST COMMENTS TAKES AN EXTRA REQUEST, and getting this wrong is silent.
+// `/issues/{n}/comments` returns OLDEST first and has no `direction` parameter — the measured vendor
+// fact this bundle's read adapter is built on (channels/github-read.ts, its header). Asking page 1
+// of a 250-comment thread would hand the poll the conversation's START, so the agent's recent
+// replies would never be examined and the arm would report nothing while looking perfectly healthy.
+// So the poll does what the read adapter does: it takes the issue's own `comments` COUNT, which
+// names the last page directly, and reads that page.
+//
+// THE COST, per ADMITTED delivery — one the two gates above let through: one issue read for the
+// count, one comment page (a second when that page is short and there is a page before it), plus one
+// reactions read per agent comment the page already says carries a reaction — capped by
+// {@link GITHUB_REACTION_POLL_COMMENT_BUDGET}. A conversation with no comments costs the issue read
+// and nothing more. A REFUSED delivery costs no read at all.
+//
+// ── WHY ONLY `added`
+//
+// The reactions route returns the reactions that EXIST. It cannot report one that was taken away, so
+// a poll can only ever see an add. The arm records `added` and never invents a `removed`: a
+// retraction this surface cannot observe is better absent than guessed at.
+//
+// ── THE DEDUPE IS A KEY (OPE-1535)
+//
+// A poll re-reads reactions it has already recorded, so it must not write a second row for each. The
+// arm therefore keeps a durable CLAIM per recorded reaction, keyed by the three fields that identify
+// one: the comment, the reactor and the glyph ({@link githubReactionKey}). A poll asks the store
+// about the exact reaction in front of it and skips the ones it already holds.
+//
+// 🔴 IT IS A `notice_claim`, AND THE LIFETIME IS THE WHOLE POINT. "This reaction was recorded" never
+// stops being true, and a reaction stays visible to the poll for as long as its comment stays in the
+// poll's view — which on a quiet conversation is forever. So the claim must never expire.
+// `claimNotice`/`noticeClaimed` (operational/store.ts) is the tree's at-most-once claim with no TTL
+// and no prune, which is exactly that shape. Growth is one row per recorded reaction — the same
+// number of rows the audit log already holds for them, so the marginal cost is a copy of a thing the
+// deployment already keeps.
+//
+// 🔴 WHY THE AUDIT LOG STOPPED BEING THE ANSWER. It was: the arm read back the newest reaction rows
+// for the surface and skipped what it found. That read is a WINDOW, not a key — `readAudit` takes a
+// LIMIT rather than a cursor, and the surface grain the rows carry is the REPOSITORY, so a repository
+// with more recorded reactions than the window held would re-record one whose row had aged out as
+// soon as a delivery brought the poll back to that conversation. The window's size decided
+// correctness, which is the property a key does not have.
+//
+// 🔴 THE DEDUPE FAILS CLOSED, AND SAYS SO. An unreadable claim reads as ALREADY RECORDED, which
+// bounds what the audit log claims happened — but a store that stays down then disables the feedback
+// signal entirely, with zero rows and no error to look at. So a poll that could not read the claim
+// store writes ONE `github.reaction_claim_unreadable` audit row naming how many reactions it skipped,
+// the same way the budget gate audits its trip (channels/github-reaction-scope.ts).
+//
+// 🔴 THAT ROW ANSWERS A PARTIAL FAULT, NOT EVERY ONE. It is written through `appendAudit`, into the
+// SAME operational store whose claim read just threw — so a whole-store outage loses the row as well,
+// and shows up as the audit DROP COUNTER and its warn instead. The row is what makes the partial case
+// legible: a missing `notice_claim` table, or a grant that covers `audit_log` and not it.
+//
+// 🔴 THE ORDER IS READ, RECORD, CLAIM — and it is chosen so nothing is ever LOST. The claim is
+// written only after `ingestReaction` reports the row recorded, so a sink that fails leaves no claim
+// and the next poll retries the reaction. Claiming first would make the dedupe a mutex across
+// concurrent deliveries, but a failed write would then swallow the reaction permanently — the claim
+// table has no release. Two cases stay open in the same benign direction, both of them a repeated
+// audit row that over-reports the count and corrupts nothing: two deliveries polling the same
+// conversation at the same instant, where both read "not recorded" before either writes; and a claim
+// WRITE that fails after the row landed, which the next poll answers by recording the reaction again.
+// The first was there before the key and is unchanged by it; the second is the price of the order.
+//
+// ── IDENTITY
+//
+// "The agent's own comment" is `<GITHUB_APP_SLUG>[bot]` — the login GitHub gives an App's comments,
+// and the same self-identity channels/github-supervisor.ts drops its own replies by. 🔴 IT FAILS
+// CLOSED: with no slug configured the arm polls nothing at all, because it cannot tell the agent's
+// comments from anybody else's and reading every comment's reactions would record strangers' reactions
+// to strangers' posts as feedback about the agent.
+
+import {
+  buildIngestedReaction,
+  deploymentOrg,
+  getOperationalStore,
+  ingestReaction,
+  liveReactionSink,
+  resolvePartition,
+  type ReactionIngestOutcome,
+  type PrFetchFn,
+  type ReactionSinkDeps,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { buildGitHubAuth } from "./github-identity.js";
+import { GITHUB_API_BASE, installationTokenFor } from "./github-post-arm.js";
+import { getJson, liveGithubReadFetch } from "./github-read.js";
+import { auditGitHubReactionClaimUnreadable, githubConversationInScope, spendGitHubPollBudget } from "./github-reaction-scope.js";
+
+/** The webhook families that name a conversation this arm can poll. Both carry `repository` and an
+ *  issue number; a PR arrives as an `issue_comment` too, because GitHub models a PR as an issue for
+ *  timeline comments. */
+const POLL_EVENT_TYPES: ReadonlySet<string> = new Set(["issue_comment", "issues"]);
+
+/** The conversation one accepted delivery names — everything the poll needs and nothing else. */
+export interface GitHubReactionPollTarget {
+  readonly owner: string;
+  readonly repo: string;
+  readonly number: number;
+  readonly installationId?: number;
+  readonly repoPrivate?: boolean;
+}
+
+/** One of the agent's timeline comments, narrowed to what the poll reads. */
+export interface GitHubPolledComment {
+  readonly id: number;
+  readonly authorLogin?: string;
+  /** GitHub's `user.type` — `"Bot"` for an App's comment. */
+  readonly authorType?: string;
+  /** `reactions.total_count`. Zero ⇒ the arm never asks for the reactions. */
+  readonly reactionCount?: number;
+}
+
+/** One reaction on one of those comments. */
+export interface GitHubPolledReaction {
+  /** GitHub's fixed eight-value `content` enum (`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`,
+   *  `rocket`, `eyes`) — passed through as the emoji DATA, bucketed by core. */
+  readonly content: string;
+  /** WHO reacted. GitHub sends a `user.type` beside it, and this shape deliberately drops it: the
+   *  agent's own reaction is identified by its EXACT login, and adding the type could only widen
+   *  what counts as ours. That is the opposite of {@link GitHubPolledComment}, where the type is a
+   *  second signal that must AGREE before a comment counts as the agent's. */
+  readonly userLogin?: string;
+}
+
+/** Injected seams, so parse + filter + dedupe + record is unit-tested with no live installation. */
+export interface GitHubReactionFeedbackDeps {
+  readonly sink: ReactionSinkDeps;
+  /** The app's own bot login (`<slug>[bot]`). Absent ⇒ the arm polls nothing — see the header. */
+  readonly botLogin?: string;
+  readonly listComments: (target: GitHubReactionPollTarget) => Promise<readonly GitHubPolledComment[]>;
+  readonly listReactions: (target: GitHubReactionPollTarget, commentId: number) => Promise<readonly GitHubPolledReaction[]>;
+  /** Has this exact reaction already been recorded? The keyed dedupe's read half — see the header.
+   *  {@link liveGitHubReactionRecorded} answers it off the durable claim store. */
+  readonly recorded: (partition: GitHubReactionPartition, key: string) => Promise<boolean>;
+  /** Claim this reaction as recorded. Called ONLY after the sink reports the row written, which is
+   *  what makes a failed write retryable rather than lost. */
+  readonly markRecorded: (partition: GitHubReactionPartition, key: string, atIso: string) => Promise<void>;
+  /** GATE 1 (OPE-1540): is the agent IN this conversation — has this bundle posted here, or did an
+   *  @mention engage the container? Refusing here is what makes a delivery in a conversation the
+   *  agent is not in cost ZERO REST calls. */
+  readonly inScope: (target: GitHubReactionPollTarget, partition: GitHubReactionPartition) => Promise<boolean>;
+  /** GATE 2 (OPE-1540): spend one poll from this repository's hourly budget. False refuses the poll
+   *  and the refusal is audited by the scope module, not here. */
+  readonly spendBudget: (target: GitHubReactionPollTarget, partition: GitHubReactionPartition, atIso: string) => Promise<boolean>;
+  /** Say out loud that {@link GitHubReactionFeedbackDeps.recorded} threw during this poll, and how
+   *  many reactions the fail-closed dedupe skipped because of it. Called AT MOST ONCE per poll —
+   *  see the write's own header in channels/github-reaction-scope.ts for why the count rides the row
+   *  rather than the row riding each reaction. Absent ⇒ the poll writes nothing, which is what the
+   *  unit stubs take. */
+  readonly auditClaimUnreadable?: (target: GitHubReactionPollTarget, partition: GitHubReactionPartition, atIso: string, skipped: number) => Promise<void>;
+  /** How many of the agent's own comments one poll examines, newest first. Bounds the REST cost of a
+   *  long thread; defaults to {@link GITHUB_REACTION_POLL_COMMENT_BUDGET}. */
+  readonly commentBudget?: number;
+  readonly now?: () => string;
+}
+
+/** The partition coordinates the audit read and the ingest share. */
+export interface GitHubReactionPartition {
+  readonly org: string;
+  readonly workspace: string;
+  readonly surfaceKey: string;
+}
+
+/** One poll examines at most this many of the agent's own comments, newest first. A conversation
+ *  with more agent comments than this is one where the older ones stopped attracting reactions. */
+export const GITHUB_REACTION_POLL_COMMENT_BUDGET = 10;
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function pick(o: unknown, k: string): unknown {
+  return isObject(o) ? o[k] : undefined;
+}
+
+/**
+ * The conversation one delivery names, or null when the delivery names none. NEVER THROWS.
+ *
+ * It reads the SAME body the stop leg and the ambient leg read, and it accepts a delivery those two
+ * refuse — an `issues` event, or an `issue_comment` the agent itself wrote. The poll is about the
+ * CONVERSATION, so any accepted delivery naming one is a valid occasion to look.
+ */
+export function parseGitHubReactionPollTarget(body: string, eventType: string): GitHubReactionPollTarget | null {
+  if (!POLL_EVENT_TYPES.has(eventType)) return null;
+  let ev: unknown;
+  try {
+    ev = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!isObject(ev)) return null;
+  const repository = ev["repository"];
+  const owner = str(pick(pick(repository, "owner"), "login"));
+  const repo = str(pick(repository, "name"));
+  const number = num(pick(ev["issue"], "number")) ?? num(pick(ev["pull_request"], "number"));
+  if (!owner || !repo || number === undefined) return null;
+  const installationId = num(pick(ev["installation"], "id"));
+  const repoPrivate = pick(repository, "private");
+  return {
+    owner,
+    repo,
+    number,
+    ...(installationId === undefined ? {} : { installationId }),
+    ...(typeof repoPrivate === "boolean" ? { repoPrivate } : {}),
+  };
+}
+
+/** Is this comment the agent's own? `user.type === "Bot"` AND the configured `<slug>[bot]` login —
+ *  both, because either alone is wrong: every App's comment is type `Bot`, and a human account may
+ *  legally be named to look like one. */
+export function githubCommentIsOwn(comment: GitHubPolledComment, botLogin: string | undefined): boolean {
+  const login = botLogin?.trim().toLowerCase();
+  if (!login) return false;
+  if (comment.authorType?.toLowerCase() !== "bot") return false;
+  return comment.authorLogin?.toLowerCase() === login;
+}
+
+/** The identity of one recorded reaction — a comment, a reactor and a glyph. The dedupe key, and the
+ *  same three fields `liveReactionSink` writes into the audit row. */
+export function githubReactionKey(messageId: string, reactorId: string, emoji: string): string {
+  return [messageId, reactorId, emoji].join("\u001f");
+}
+
+/**
+ * Poll one conversation and record every reaction on the agent's own comments that is not recorded
+ * yet. Returns one outcome per NEW reaction — an empty array when there is nothing new, which is the
+ * ordinary case on a busy conversation.
+ *
+ * NEVER THROWS: a failed read or a failed sink must never cost the ingress its ack. A comment whose
+ * reactions cannot be read is skipped, and the rest of the poll continues.
+ */
+export async function routeGitHubReactionFeedback(
+  target: GitHubReactionPollTarget,
+  deps: GitHubReactionFeedbackDeps,
+): Promise<readonly ReactionIngestOutcome[]> {
+  // FAIL CLOSED on self-identity — see the header. Without it every reaction in the thread would
+  // read as feedback on the agent.
+  const botLogin = deps.botLogin?.trim().toLowerCase();
+  if (!botLogin) return [];
+
+  // THE PARTITION IS RESOLVED FIRST, because the gates below are keyed by the same surface the rows
+  // are. It is PURE — no store, no network — so computing it ahead of a gate that may refuse costs
+  // nothing.
+  const partition = resolvePartition({
+    channel: { kind: "github" },
+    session: {
+      auth: {
+        current: buildGitHubAuth({
+          owner: target.owner,
+          repo: target.repo,
+          issueNumber: target.number,
+          // The POLL has no actor — it is the deployment looking, not a person acting. The reactor's
+          // own login rides each ingested reaction instead, which is where it belongs.
+          actorLogin: botLogin,
+          ...(target.repoPrivate === undefined ? {} : { isPrivate: target.repoPrivate }),
+        }),
+      },
+    },
+  });
+  const coords: GitHubReactionPartition = { org: partition.org, workspace: partition.workspace, surfaceKey: partition.surfaceKey };
+
+  // ── THE TWO SCOPE GATES (OPE-1540) ─────────────────────────────────────────────────────────────
+  //
+  // 🔴 BOTH RUN BEFORE THE FIRST REST CALL, which is the whole of the fix: the cost this bundle used
+  // to pay was paid to LEARN there was nothing to do. Gate 1 is the cheap one and the one that cuts
+  // the most, so it runs first — and a conversation it refuses spends no budget either, because a
+  // poll that never happens is not a poll this repository ran.
+  //
+  // Both FAIL OPEN on a throw, matching their live implementations: a gate that cannot answer costs
+  // REST calls, never a lost feedback signal. The `.catch` is also what keeps this function's
+  // never-throws contract true for an injected dep.
+  const atIso = deps.now?.() ?? new Date().toISOString();
+  if (!(await deps.inScope(target, coords).catch(() => true))) return [];
+  if (!(await deps.spendBudget(target, coords, atIso).catch(() => true))) return [];
+
+  const comments = await deps.listComments(target).catch(() => []);
+  const own = comments
+    .filter((c) => githubCommentIsOwn(c, botLogin) && (c.reactionCount ?? 0) > 0)
+    .slice(0, deps.commentBudget ?? GITHUB_REACTION_POLL_COMMENT_BUDGET);
+  if (own.length === 0) return [];
+
+  // The keys this poll has already answered for. It is a memo over `deps.recorded`, not the dedupe
+  // itself: the durable claim is what decides, and this only stops one poll asking the store twice
+  // about a reaction the vendor happened to list twice.
+  const asked = new Set<string>();
+
+  // How many reactions this poll skipped because the claim store could not answer. It is a COUNT,
+  // not a flag, because the row written at the end reports it — see below.
+  let claimUnreadable = 0;
+
+  const outcomes: ReactionIngestOutcome[] = [];
+  for (const comment of own) {
+    const reactions = await deps.listReactions(target, comment.id).catch(() => []);
+    for (const reaction of reactions) {
+      const reactorId = reaction.userLogin;
+      // The agent's OWN reactions ride the same route — its `react` verb places them. They are never
+      // feedback, and unlike the comment filter this one needs no type check: the login is exact.
+      if (!reactorId || reactorId.toLowerCase() === botLogin) continue;
+      const messageId = String(comment.id);
+      const key = githubReactionKey(messageId, reactorId, reaction.content);
+      if (asked.has(key)) continue;
+      asked.add(key);
+      // FAIL-CLOSED on an unreadable claim: an unknown answer is treated as ALREADY RECORDED, so a
+      // store blip costs a delayed feedback row rather than a duplicate one. The opposite posture
+      // from the two scope gates above, and deliberately: those bound a COST, this one bounds what
+      // the audit log claims happened.
+      //
+      // 🔴 BUT IT IS NEVER SILENT. Failing closed on a store that stays down disables the whole
+      // feedback signal with zero rows and no error, which reads exactly like a week nobody reacted
+      // in. The throw is counted here and audited ONCE at the end of the poll.
+      const claimed = await deps.recorded(coords, key).catch(() => {
+        claimUnreadable++;
+        return true;
+      });
+      if (claimed) continue;
+      const ingested = buildIngestedReaction({
+        surface: "github",
+        // Only ever an ADD — see the header. A poll cannot observe a retraction.
+        verb: "added",
+        reactorId,
+        emoji: reaction.content,
+        // The CONVERSATION is the channel grain a GitHub turn is keyed by; the COMMENT is the
+        // message the reaction landed on.
+        target: { channelId: `${target.owner}/${target.repo}#${target.number}`, messageId },
+        // Structurally true: the loop only ever reaches the agent's own comments.
+        onBotReply: true,
+        partition,
+      });
+      const outcome = await ingestReaction(ingested, deps.sink).catch(() => ({ recorded: false, onBotReply: true, reason: "sink failed" }));
+      outcomes.push(outcome);
+      // CLAIM ONLY WHAT LANDED — see the header's read/record/claim order. A sink that failed leaves
+      // no claim, so the next poll for this conversation tries the reaction again.
+      if (outcome.recorded) await deps.markRecorded(coords, key, atIso).catch(() => undefined);
+    }
+  }
+  // ONE ROW PER POLL for an unreadable claim store, and only when one read actually threw. The count
+  // is what makes a single row as informative as the flood it replaces. Best-effort and swallowed,
+  // like every other write on this path — the never-throws contract holds through it.
+  if (claimUnreadable > 0) await deps.auditClaimUnreadable?.(target, coords, atIso, claimUnreadable).catch(() => undefined);
+  return outcomes;
+}
+
+/** The durable claim key one recorded reaction occupies, namespaced by the SURFACE — `notice_claim`
+ *  is keyed by org alone, so two repositories in one deployment would otherwise share a key space and
+ *  a comment id collision across repos would read as a duplicate. */
+function githubReactionClaimKey(p: GitHubReactionPartition, key: string): string {
+  return `github-reaction:${p.surfaceKey}\u001f${key}`;
+}
+
+/** The live dedupe's read half: has this exact reaction already been recorded? */
+async function liveGitHubReactionRecorded(p: GitHubReactionPartition, key: string): Promise<boolean> {
+  return getOperationalStore().noticeClaimed(deploymentOrg(), githubReactionClaimKey(p, key));
+}
+
+/** The live dedupe's write half. Idempotent — a re-claim of a held key answers false, which nothing
+ *  here reads: the question this store answers is "is it claimed", never "who claimed it". */
+async function liveGitHubReactionMarkRecorded(p: GitHubReactionPartition, key: string, atIso: string): Promise<void> {
+  await getOperationalStore().claimNotice(deploymentOrg(), githubReactionClaimKey(p, key), atIso);
+}
+
+// --- THE LIVE READS ------------------------------------------------------------------------------
+//
+// Every GET below runs under the SAME short-lived installation token every other GitHub call in this
+// bundle mints, through the SAME `getJson` and the SAME transport the read adapter uses — so they
+// inherit its 429 backoff and add no second transport (channels/github-read.ts, and
+// `test:github-write-seam` §4). None of them reads a comment BODY: the poll needs an author, a count
+// and a glyph, and nothing else.
+
+/** GitHub's own page ceiling for the comment list. The read adapter pages by the same number. */
+const GITHUB_COMMENT_PAGE = 100;
+
+interface RawPollComment {
+  readonly id?: number;
+  readonly user?: { readonly login?: string; readonly type?: string };
+  readonly reactions?: { readonly total_count?: number };
+}
+
+interface RawPollReaction {
+  readonly content?: string;
+  readonly user?: { readonly login?: string; readonly type?: string };
+}
+
+function tokenFor(target: GitHubReactionPollTarget): Promise<string> {
+  return installationTokenFor({
+    platform: "github",
+    owner: target.owner,
+    repo: target.repo,
+    issueNumber: target.number,
+    ...(target.installationId === undefined ? {} : { installationId: target.installationId }),
+  });
+}
+
+/** Production deps for the poll. `botLogin` is `<GITHUB_APP_SLUG>[bot]` — absent when the slug is
+ *  unset, which is exactly the fail-closed case {@link routeGitHubReactionFeedback} refuses on. */
+export function liveGitHubReactionFeedbackDeps(appSlug: string | undefined, fetchFn: PrFetchFn = liveGithubReadFetch): GitHubReactionFeedbackDeps {
+  const slug = appSlug?.trim();
+  return {
+    sink: liveReactionSink(),
+    ...(slug ? { botLogin: `${slug}[bot]` } : {}),
+    listComments: async (target) => {
+      const token = await tokenFor(target);
+      // 🔴 THE LAST PAGE, NOT THE FIRST. `/issues/{n}/comments` returns OLDEST first and honours no
+      // `direction` — see the header. The issue object's own `comments` count names the last page
+      // directly, which is the same two-request shape channels/github-read.ts uses and for the same
+      // reason. Reading page 1 here would examine the conversation's START and find nothing.
+      const issue = await getJson<{ readonly comments?: number }>(
+        fetchFn,
+        `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/issues/${target.number}`,
+        token,
+        "issues.get",
+      );
+      const total = typeof issue.comments === "number" && issue.comments > 0 ? issue.comments : 0;
+      if (total === 0) return [];
+      const page = (nth: number): string => `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/issues/${target.number}/comments?per_page=${GITHUB_COMMENT_PAGE}&page=${nth}`;
+      const lastPage = Math.max(1, Math.ceil(total / GITHUB_COMMENT_PAGE));
+      let raw = await getJson<readonly RawPollComment[]>(fetchFn, page(lastPage), token, "issues.comments.list");
+      if (!Array.isArray(raw)) return [];
+      // A short last page can hold fewer of the agent's comments than the budget wants, so the page
+      // before it is prepended — the same fallback the read adapter makes, and enough for any budget
+      // up to the page size.
+      if (raw.length < GITHUB_REACTION_POLL_COMMENT_BUDGET && lastPage > 1) {
+        const previous = await getJson<readonly RawPollComment[]>(fetchFn, page(lastPage - 1), token, "issues.comments.list");
+        if (Array.isArray(previous)) raw = [...previous, ...raw];
+      }
+      return raw
+        .filter((c): c is RawPollComment & { id: number } => typeof c.id === "number")
+        // NEWEST FIRST, so the budget's slice takes the agent's most recent comments — the ones a
+        // person is plausibly still reacting to.
+        .reverse()
+        .map((c) => ({
+          id: c.id,
+          ...(c.user?.login ? { authorLogin: c.user.login } : {}),
+          ...(c.user?.type ? { authorType: c.user.type } : {}),
+          ...(typeof c.reactions?.total_count === "number" ? { reactionCount: c.reactions.total_count } : {}),
+        }));
+    },
+    listReactions: async (target, commentId) => {
+      const token = await tokenFor(target);
+      const raw = await getJson<readonly RawPollReaction[]>(
+        fetchFn,
+        `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/issues/comments/${commentId}/reactions?per_page=100`,
+        token,
+        "reactions.listForIssueComment",
+      );
+      return raw
+        .filter((r): r is RawPollReaction & { content: string } => typeof r.content === "string" && r.content.length > 0)
+        .map((r) => ({
+          content: r.content,
+          ...(r.user?.login ? { userLogin: r.user.login } : {}),
+        }));
+    },
+    recorded: (partition, key) => liveGitHubReactionRecorded(partition, key),
+    markRecorded: (partition, key, atIso) => liveGitHubReactionMarkRecorded(partition, key, atIso),
+    inScope: (target, partition) => githubConversationInScope(partition.surfaceKey, target.owner, target.repo, target.number),
+    spendBudget: async (target, _partition, atIso) => (await spendGitHubPollBudget(target.owner, target.repo, atIso)).admitted,
+    auditClaimUnreadable: (target, _partition, atIso, skipped) => auditGitHubReactionClaimUnreadable(target.owner, target.repo, atIso, skipped),
+  };
+}