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

package/agent/channels/github-read.ts

@@ -0,0 +1,471 @@
+// The GitHub read adapter (OPE-958) — the sixth surface's arm of the uniform chat read, and the
+// last one that was missing.
+//
+// WHAT IT CLOSES, IN BOTH PLANES AT ONCE.
+//   • THE SEAT. `read_channel` / `read_thread` are documented as identical on all six surfaces and
+//     were not: with no adapter registered, a GitHub seat got "reading a github channel is not
+//     supported yet" (core channels/channel-read.ts `resolveReadAdapter`).
+//   • THE WORKER. `read_work_channel` / `read_work_thread` run the NEUTRAL engine over the same
+//     adapter, so GitHub could not hold a work read either. It now does, under its own grant — the
+//     access bundle's `repos:` list (access/surface-work-grant.ts).
+//
+// 🔴 THE CONTAINER IS THE ISSUE-OR-PR CONVERSATION, NOT THE REPO. The GitHub SURFACE grain is the
+// repo (github-identity.ts `bindGitHub`: workspace = owner, surface = repo), because a repo is the
+// persistent room that groups every issue and PR in it. The READ grain is one conversation inside
+// it, and it has to be: a "repo timeline" is not a thing a member wrote in, and the read verbs read
+// the container THIS turn arrived in (OPE-929). So the container id is the conversation key
+// `owner/repo#number` — the SAME key `githubConversationKey` already mints for the stop registry, so
+// this file adds no second spelling of a GitHub conversation's address.
+//
+// 🔴 A PLAIN ISSUE READS THE SAME WAY A PR DOES, AND THAT IS THE SECOND GAP THIS CLOSES.
+// `fetchPrFeedback` (core scm/pr-feedback.ts) opens with `GET /repos/{repo}/pulls/{number}`, which
+// 404s on an issue, so a worker delegated from an ISSUE thread had no read of it at all. This
+// adapter fetches `GET /repos/{repo}/issues/{number}` instead — GitHub's issues endpoint serves
+// PULL REQUESTS too, because every PR IS an issue with a `pull_request` member. One call, both
+// kinds, no branch. The comment fetch was never the problem: `/issues/{n}/comments` already served
+// both, which is why `get_pr_feedback` reads a PR's timeline correctly today.
+//
+// 🔴 THE PAGE IS THE NEWEST MESSAGES, WHICH TAKES ONE EXTRA REQUEST. `/issues/{n}/comments` returns
+// OLDEST first with no `direction` parameter, so reading page 1 would hand the model the START of a
+// long conversation while the render says "Recent messages … (oldest first)" and the coverage note
+// says "the most recent". That is the fabrication class this read tier exists to close, so the
+// adapter pages to the END instead: the issue object it already fetched carries the `comments`
+// COUNT, which names the last page directly. At most two comment requests, no `Link` header
+// parsing — {@link PrFetchFn} exposes no headers.
+//
+// OPE-1015 — AND THAT SAME `comments` COUNT ANSWERS COVERAGE EXACTLY, NO HEURISTIC NEEDED. The issue
+// object names the TRUE total comment count; {@link readChannel} compares it against how many this
+// call actually returned and DECLARES `AdapterReadFetch.possiblyIncomplete` from that exact fact
+// rather than leaving core to guess from the line count. A review thread's coverage
+// ({@link readThread}) is not exact the same way — GitHub's review-comment endpoint carries no total
+// count — so that arm declares from whether {@link fetchReviewComments}'s bounded walk ran out of
+// pages (exact "no more") or hit its own ceiling (honest "cannot tell").
+//
+// THE FENCE IS TWO CHECKS AND BOTH FAIL CLOSED. The shared `assertSurfaceAllowed` runs the domain
+// read scope on the REPO (and audits its refusal, like every other surface), and an OWNER check runs
+// beside it because that allowlist compares surface SEGMENTS: `acme/api` and `evil/api` are both
+// "api", so the repo name alone would admit another owner's repo of the same name. The owner is
+// compared against THIS turn's own binding, which is the container fence in its strictest form.
+//
+// THE CREDENTIAL IS THE BROKERED CONVERSATION-READ TOKEN — `resolveConversationReadToken` (core
+// scm/pr-status.ts), the App installation token for the repo, falling back to `GITHUB_TOKEN`.
+// GitHub holds ONE credential family, so the chat read and the work read present the same token;
+// access/surface-work-grant.ts's header carries the full argument for why that is the shipped seam
+// and not an oversight.
+//
+// 🔴 IT IS NOT `resolveReadToken` (OPE-1019). That resolver mints `{contents, pull_requests,
+// metadata}` for the PR verbs, and a token with no `issues` family is refused 403 on `/issues/{n}`
+// when the number names a PLAIN ISSUE — measured live on deploy #118, where both read drives went
+// red while the reply POST on the same two issues returned 201. `resolveConversationReadToken`
+// mints `{issues, pull_requests, metadata}`, which is what an endpoint that serves both
+// conversation kinds needs. See scm/mint.ts for the full measurement.
+//
+// NO `refutedAuthorIds`. The core contract calls its absence a real answer, and GitHub's own header
+// says why: GitHub reads are classified by their own taint-table rows and the author grain is served
+// at the WAKE by `githubAuthorFacts` off `author_association`. A second probe here would be a second
+// place deciding one question.
+
+import {
+  assertGithubActingIdentity,
+  assertSurfaceAllowed,
+  bindFrom,
+  prApiHeaders,
+  resolveConversationReadToken,
+  withRetryAfterLoose,
+  ChannelScopeError,
+  type AdapterReadFetch,
+  type BindableContext,
+  type PrFetchFn,
+  type RenderedLine,
+  type RetryPolicy,
+  type WakeReadAddress,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { githubReviewThreadRoot } from "./github-identity.js";
+
+const GITHUB_CHANNEL_DEFAULT_LIMIT = 50;
+const GITHUB_THREAD_DEFAULT_LIMIT = 100;
+/** GitHub's REST page ceiling for both comment endpoints. */
+const GITHUB_MAX_PAGE = 100;
+/** How many review-comment pages one thread read will walk. A review thread is a handful of
+ *  comments; the ceiling exists so a pathological PR cannot turn one read into unbounded paging. */
+const MAX_REVIEW_PAGES = 5;
+
+const API_BASE = "https://api.github.com";
+
+/**
+ * The 429 budget ONE READ may spend, across every call it makes (OPE-1299).
+ *
+ * 🔴 THE DEFECT WAS MULTIPLICATION, NOT THE PER-CALL POLICY. `withRetryAfterLoose`'s budget is
+ * per call, and both reads here walk several: `readChannel` issues up to three (`issues.get`, then
+ * one or two `issues.comments.list` pages) and `readThread` up to {@link MAX_REVIEW_PAGES}
+ * `pulls.comments.list` pages (it fetches no issue object — the review-comment walk is the whole
+ * read). Under the shared 60 s default that is ~3 and ~5 minutes of waiting for ONE `read_channel` /
+ * `read_thread` tool call, and nothing bounded the sum.
+ *
+ * So the whole read shares ONE deadline, read fresh per call ({@link walkRetry}). The first call
+ * still gets the full budget — a single-call read is not tightened at all, which is why this costs
+ * no extra failures on the ordinary path — and each later call gets only what is left. The worst
+ * case for a whole read becomes this number instead of a multiple of it.
+ *
+ * 🔴 THIS IS THE SEAM'S OWN POLICY, NOT A CALLER'S. `ReadAdapter.readChannel`/`readThread`
+ * (core's channels/channel-read.ts) take no options object, and every one of the six adapters
+ * already spends the trailing parameter on its own transport seam — so widening the interface to
+ * carry a policy is a cross-provider change, and no production caller could pass one until it
+ * happened. Slack answered the same question the same way: `PROBE_OPERATIONS`
+ * (providers/slack/agent/channels/slack-web-api.ts) is a table the seam applies itself, with an
+ * explicit dependency still winning. `getJson`'s `retry` argument keeps that property here — a test
+ * passes its own policy and this default never reaches it.
+ *
+ * 60 s, matching `DEFAULT_TOTAL_BUDGET_MS`: a read that 429s out degrades the turn's context rather
+ * than losing an answer, so the budget buys latency back without making a first attempt any more
+ * likely to fail.
+ */
+export const READ_WALK_BUDGET_MS = 60_000;
+
+/**
+ * The clock and sleep one walk runs on. Absent in production — the adapter takes the real ones.
+ *
+ * 🔴 IT IS HERE SO THE SHARED BUDGET IS TESTABLE AT ALL. The claim this seam makes is about the
+ * SECOND and later calls of a walk, and a walk under the real clock can only be observed by waiting
+ * out its real waits. `github-read-test.ts` § 8 drives a clock that advances on each recorded sleep,
+ * which is what lets one assertion separate "one deadline for the walk" from "one budget per call".
+ */
+export interface ReadWalkSeam {
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/** The policy one call inside a walk takes: whatever is left of the walk's shared deadline. Zero is
+ *  a real value the primitive honours — at the deadline, a retry gives up instead of waiting. */
+export function walkRetry(deadlineMs: number, seam: ReadWalkSeam = {}): RetryPolicy {
+  const now = seam.now ?? Date.now;
+  return {
+    totalBudgetMs: Math.max(0, deadlineMs - now()),
+    ...(seam.sleep ? { sleep: seam.sleep } : {}),
+    ...(seam.now ? { now: seam.now } : {}),
+  };
+}
+
+/** One GitHub conversation's address, parsed out of the container id. */
+export interface GitHubContainer {
+  /** The repo owner, as GitHub spells it — the API path segment, never a sanitized key segment. */
+  readonly owner: string;
+  readonly repo: string;
+  /** `owner/repo` — the form every core SCM helper takes. */
+  readonly repoFull: string;
+  /** The issue or PR number. */
+  readonly number: number;
+}
+
+/**
+ * Parse `owner/repo#number` — the container id {@link githubReadAdapter.wakeAddress} mints.
+ *
+ * Returns `undefined` on anything else rather than guessing a part. A partial address would fetch
+ * another repo's conversation of the same number, which is the silent mis-address the whole
+ * wake-container design refuses (core channels/wake-container.ts).
+ */
+export function parseGithubContainer(container: string): GitHubContainer | undefined {
+  const hash = container.lastIndexOf("#");
+  if (hash <= 0) return undefined;
+  const repoFull = container.slice(0, hash);
+  const rest = container.slice(hash + 1);
+  if (!/^[0-9]+$/u.test(rest)) return undefined;
+  const parts = repoFull.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return undefined;
+  const number = Number(rest);
+  if (!Number.isSafeInteger(number) || number <= 0) return undefined;
+  return { owner: parts[0], repo: parts[1], repoFull, number };
+}
+
+/** The live transport. Injected in every read below so the whole adapter drives offline — the same
+ *  DI shape slack-read / discord-read take. */
+/** THE package's ONE read transport. Exported so channels/github-reaction-feedback.ts borrows it
+ *  rather than reaching for `globalThis.fetch` itself — a second reach would be a second transport
+ *  outside this module's retry seam, which `test:github-write-seam` §4 exists to refuse. */
+export const liveGithubReadFetch = globalThis.fetch as unknown as PrFetchFn;
+
+/**
+ * `operation` is the vendor route name (OPE-1255) `withRetryAfterLoose`'s `RateLimitExhaustedError`
+ * reports on exhaustion — this read-only transport was, until now, the ONE issue/PR reader in this
+ * package with no 429 backoff (`docs/extending/provider-rate-limits.md`).
+ *
+ * Exported so its retry behaviour is unit-tested directly (github-read-test.ts), the same way
+ * `github-rate-limit-test.ts` drives `githubWrite` directly rather than through a full reply.
+ *
+ * `retry` reaches no caller OUTSIDE this file — `ReadAdapter.readChannel`/`readThread`
+ * (channels/channel-read.ts) take no options object. Since OPE-1299 the adapter itself passes one:
+ * each read builds a shared deadline and hands every call what is left of it
+ * ({@link READ_WALK_BUDGET_MS}, {@link walkRetry}), so a multi-call read is bounded as a whole.
+ */
+export async function getJson<T>(fetchFn: PrFetchFn, url: string, token: string, operation: string, retry?: RetryPolicy): Promise<T> {
+  const res = await withRetryAfterLoose(() => fetchFn(url, { method: "GET", headers: prApiHeaders(token) }), { ...retry, surface: "github", operation });
+  if (!res.ok) throw new Error(`read: GitHub GET failed (HTTP ${res.status}) for ${url}.`);
+  return (await res.json()) as T;
+}
+
+/** The raw shapes this adapter reads. Only the fields it renders are declared. */
+interface RawGitHubUser {
+  readonly login?: string;
+  readonly type?: string;
+}
+interface RawIssue {
+  readonly title?: string;
+  readonly body?: string | null;
+  readonly user?: RawGitHubUser;
+  readonly created_at?: string;
+  /** The TIMELINE comment count — the field that names the last comment page. */
+  readonly comments?: number;
+}
+interface RawComment {
+  readonly id?: number;
+  readonly body?: string | null;
+  readonly user?: RawGitHubUser;
+  readonly created_at?: string;
+  readonly in_reply_to_id?: number | null;
+}
+
+/** One GitHub author rendered into the neutral line's fields. A `Bot` actor is marked a MACHINE for
+ *  the same reason every other adapter marks one: a bot sits below peer standing and is never an
+ *  outside person. An unattributed comment carries neither id nor mark, which is the fail-open
+ *  answer for an author nobody can name. */
+function authorFields(user: RawGitHubUser | undefined): Pick<RenderedLine, "author" | "authorId" | "bot"> {
+  const login = user?.login;
+  if (!login) return { author: "(unknown)" };
+  return { author: login, ...(user?.type === "Bot" ? { bot: true } : { authorId: login }) };
+}
+
+/** The OPENING line of a conversation — the issue/PR title and body, as the author wrote them.
+ *  Included because it IS the first message: a read that started at the first COMMENT would drop
+ *  the request the whole thread answers. */
+function openingLine(issue: RawIssue): RenderedLine {
+  const title = (issue.title ?? "").trim();
+  const body = (issue.body ?? "").trim();
+  return {
+    ...authorFields(issue.user),
+    ts: issue.created_at ?? "",
+    text: [title, body].filter((part) => part.length > 0).join("\n\n"),
+  };
+}
+
+function commentLine(comment: RawComment): RenderedLine {
+  return { ...authorFields(comment.user), ts: comment.created_at ?? "", text: (comment.body ?? "").trim() };
+}
+
+/**
+ * The FENCE — this read names the conversation THIS turn arrived in, in a repo this session may
+ * read. Both halves throw {@link ChannelScopeError}; see the header for why the owner needs its own
+ * check.
+ *
+ * The owner is compared against the binding's own post-back target, which carries the RAW owner the
+ * webhook delivered. The partition's surface key cannot serve here: its segments are sanitized for
+ * use as storage keys, so they are not always the vendor ids an API call takes.
+ *
+ * Comparison is case-INSENSITIVE because GitHub logins are.
+ */
+async function assertGithubContainerAllowed(ctx: BindableContext, target: GitHubContainer): Promise<void> {
+  const bound = bindFrom(ctx).target as { owner?: unknown } | undefined;
+  const boundOwner = typeof bound?.owner === "string" ? bound.owner : undefined;
+  if (boundOwner === undefined || boundOwner.toLowerCase() !== target.owner.toLowerCase()) {
+    throw new ChannelScopeError(
+      `owner "${target.owner}" is not the owner this turn arrived under (${boundOwner ?? "none"}). A GitHub read ` +
+        "reads the conversation its own turn is in.",
+    );
+  }
+  await assertSurfaceAllowed(ctx, "github", target.repo);
+}
+
+/**
+ * Parse the container id and run the fence — the FIRST two steps of both reads, in one place so
+ * they can never come apart. A read that parsed here and fenced there would be one edit away from a
+ * fetch on an unfenced address.
+ *
+ * A malformed id raises {@link ChannelScopeError} rather than a plain `Error` because the two mean
+ * the same thing to a caller: this read names an address it may not have, and nothing was fetched.
+ *
+ * 🔴 THE ACTING-IDENTITY GATE RUNS LAST, AFTER THE ADDRESS FENCE. The fence answers "may this
+ * session read this conversation at all"; the gate answers "whose account may answer it". A gate
+ * that ran first would write a `connector.acting_identity` row for an address this session may not
+ * name, and the row would read as a real read that was refused for the wrong reason.
+ */
+async function admitContainer(ctx: BindableContext, channel: string, tool: string): Promise<GitHubContainer> {
+  const target = parseGithubContainer(channel);
+  if (!target) throw new ChannelScopeError(`"${channel}" is not a GitHub conversation id (expected "owner/repo#number").`);
+  await assertGithubContainerAllowed(ctx, target);
+  await assertGithubActingIdentity(ctx, tool);
+  return target;
+}
+
+/** Fetch the issue-or-PR object. `/issues/{n}` serves BOTH kinds — see the header. */
+async function fetchIssue(fetchFn: PrFetchFn, token: string, target: GitHubContainer, retry?: RetryPolicy): Promise<RawIssue> {
+  return await getJson<RawIssue>(fetchFn, `${API_BASE}/repos/${target.repoFull}/issues/${target.number}`, token, "issues.get", retry);
+}
+
+/**
+ * The NEWEST `limit` timeline comments, oldest-first. `total` is the issue object's own `comments`
+ * count, which names the last page: page `ceil(total / 100)`. When that last page holds fewer lines
+ * than the caller asked for, the page before it is prepended, which is enough for any `limit` up to
+ * the 100-comment page size (the read verbs cap at 100).
+ */
+async function fetchRecentComments(
+  fetchFn: PrFetchFn,
+  token: string,
+  target: GitHubContainer,
+  total: number,
+  limit: number,
+  retry?: () => RetryPolicy,
+): Promise<RawComment[]> {
+  const url = (page: number): string =>
+    `${API_BASE}/repos/${target.repoFull}/issues/${target.number}/comments?per_page=${GITHUB_MAX_PAGE}&page=${page}`;
+  const lastPage = Math.max(1, Math.ceil(total / GITHUB_MAX_PAGE));
+  let out = await getJson<RawComment[]>(fetchFn, url(lastPage), token, "issues.comments.list", retry?.());
+  if (!Array.isArray(out)) return [];
+  if (out.length < limit && lastPage > 1) {
+    const previous = await getJson<RawComment[]>(fetchFn, url(lastPage - 1), token, "issues.comments.list", retry?.());
+    if (Array.isArray(previous)) out = [...previous, ...out];
+  }
+  return out.slice(-limit);
+}
+
+/**
+ * Every review comment on a PR, oldest-first, walked to the {@link MAX_REVIEW_PAGES} ceiling. The
+ * thread filter runs over the whole set rather than a recent slice: a review thread's OPENING
+ * comment is the one that names the code being discussed, so a read that dropped it would render
+ * replies with nothing to reply to.
+ *
+ * OPE-1015 — `mightBeTruncated` is the walk's own exact answer to "did I definitely see every review
+ * comment?": `false` when the walk stopped because a page came back short or empty (there is
+ * provably nothing more), `true` only when it stopped because it hit {@link MAX_REVIEW_PAGES} with a
+ * full last page (there COULD be more, and this walk cannot tell). GitHub's review-comment endpoint
+ * carries no total count the way the issue object does for {@link fetchRecentComments}, so this is
+ * the exact fact this endpoint CAN give, not a guess from the returned thread's own length.
+ */
+async function fetchReviewComments(
+  fetchFn: PrFetchFn,
+  token: string,
+  target: GitHubContainer,
+  retry?: () => RetryPolicy,
+): Promise<{ comments: RawComment[]; mightBeTruncated: boolean }> {
+  const out: RawComment[] = [];
+  let mightBeTruncated = false;
+  for (let page = 1; page <= MAX_REVIEW_PAGES; page++) {
+    const batch = await getJson<RawComment[]>(
+      fetchFn,
+      `${API_BASE}/repos/${target.repoFull}/pulls/${target.number}/comments?per_page=${GITHUB_MAX_PAGE}&page=${page}`,
+      token,
+      "pulls.comments.list",
+      retry?.(),
+    );
+    if (!Array.isArray(batch) || batch.length === 0) {
+      mightBeTruncated = false;
+      break;
+    }
+    out.push(...batch);
+    if (batch.length < GITHUB_MAX_PAGE) {
+      mightBeTruncated = false;
+      break;
+    }
+    // A full page at the LAST page this walk will ever take: the loop is about to exit on the `for`
+    // condition, not on a short/empty page, so "no more" was never confirmed.
+    mightBeTruncated = page === MAX_REVIEW_PAGES;
+  }
+  return { comments: out, mightBeTruncated };
+}
+
+/**
+ * The review comments belonging to ONE thread, oldest-first — the thread's own root plus every
+ * comment that replies into it. PURE, and exported for the render test.
+ *
+ * GitHub sets `in_reply_to_id` to the thread's ROOT on every reply, not to the comment being
+ * answered, so one equality covers a thread of any depth. The root itself carries no
+ * `in_reply_to_id`, which is why it is matched by id.
+ */
+export function reviewThreadLines(comments: readonly RawComment[], rootId: string): RenderedLine[] {
+  const root = Number(rootId);
+  return comments.filter((c) => c.id === root || c.in_reply_to_id === root).map((c) => commentLine(c));
+}
+
+export const githubReadAdapter = {
+  platform: "github" as const,
+  /**
+   * OPE-929 — GitHub's own spelling of "which container and which thread is this turn in".
+   *
+   * The CONTAINER is the conversation key `owner/repo#number`, read off the binding's
+   * `anchorChannelId`: `bindGitHub` already mints it there through `githubConversationKey`, so this
+   * adds no second derivation. A turn with no conversation anchor (a supervisor seed, a degraded
+   * binding) reports none, and the caller refuses loudly rather than reading the repo's newest
+   * issue.
+   *
+   * The THREAD ROOT is present only on a REVIEW-THREAD turn — an inline comment on a PR's diff.
+   * An issue comment and a PR TIMELINE comment are at the top level of their conversation, so they
+   * report no thread root and `read_thread` refuses them honestly. That is the same answer a
+   * base-channel Discord turn gets, and for the same reason.
+   */
+  wakeAddress(ctx: BindableContext): WakeReadAddress | undefined {
+    const container = bindFrom(ctx).anchorChannelId;
+    if (!container || parseGithubContainer(container) === undefined) return undefined;
+    const threadRoot = githubReviewThreadRoot(ctx);
+    return { container, ...(threadRoot ? { threadRoot } : {}) };
+  },
+  /**
+   * The issue-or-PR conversation: its opening post, then its newest timeline comments. `channel` is
+   * the container id — see {@link parseGithubContainer}.
+   */
+  async readChannel(
+    ctx: BindableContext,
+    channel: string,
+    limit?: number,
+    fetchFn: PrFetchFn = liveGithubReadFetch,
+    walk: ReadWalkSeam = {},
+  ): Promise<AdapterReadFetch> {
+    const target = await admitContainer(ctx, channel, "github_read_channel");
+    const effective = Math.min(limit ?? GITHUB_CHANNEL_DEFAULT_LIMIT, GITHUB_MAX_PAGE);
+    const token = await resolveConversationReadToken(target.repoFull);
+    // OPE-1299 — one deadline for the whole read, read fresh per call. See READ_WALK_BUDGET_MS.
+    const deadline = (walk.now ?? Date.now)() + READ_WALK_BUDGET_MS;
+    const issue = await fetchIssue(fetchFn, token, target, walkRetry(deadline, walk));
+    const total = typeof issue.comments === "number" && issue.comments > 0 ? issue.comments : 0;
+    // The OPENING line takes one of the caller's slots, so the comment fetch asks for one fewer.
+    // Counting it would return `limit + 1` lines and set the coverage flag on a complete read.
+    const wanted = Math.max(1, effective - 1);
+    const comments = total === 0 ? [] : await fetchRecentComments(fetchFn, token, target, total, wanted, () => walkRetry(deadline, walk));
+    // OPE-1015 — the issue's OWN `comments` count names the true total exactly: MORE exists beyond
+    // this page iff the total exceeds what this call asked for, regardless of the page's own length.
+    const possiblyIncomplete = total > wanted;
+    return {
+      lines: [openingLine(issue), ...comments.map((c) => commentLine(c))],
+      possiblyIncomplete,
+      ...(possiblyIncomplete ? { partialReason: `vendor page limit: the conversation holds ${total} comments, only the newest ${wanted} were fetched` } : {}),
+    };
+  },
+  /**
+   * One REVIEW THREAD on a PR — the inline discussion `threadTs` roots. An issue has no review
+   * threads, so a read there comes back empty and the neutral render says so; it never invents a
+   * thread out of the timeline.
+   */
+  async readThread(
+    ctx: BindableContext,
+    channel: string,
+    threadTs: string,
+    limit?: number,
+    fetchFn: PrFetchFn = liveGithubReadFetch,
+    walk: ReadWalkSeam = {},
+  ): Promise<AdapterReadFetch> {
+    const target = await admitContainer(ctx, channel, "github_read_thread");
+    const token = await resolveConversationReadToken(target.repoFull);
+    // OPE-1299 — the walk this budget exists for: up to MAX_REVIEW_PAGES calls under one deadline.
+    const deadline = (walk.now ?? Date.now)() + READ_WALK_BUDGET_MS;
+    const { comments, mightBeTruncated } = await fetchReviewComments(fetchFn, token, target, () => walkRetry(deadline, walk));
+    const threadAll = reviewThreadLines(comments, threadTs);
+    const lines = threadAll.slice(-(limit ?? GITHUB_THREAD_DEFAULT_LIMIT));
+    // OPE-1015 — either the review-comment WALK could not confirm it saw everything (hit its own
+    // page ceiling), or THIS call trimmed the thread to the caller's limit — both are real partial
+    // views. The reason names only the walk's own honest "cannot tell"; a caller-limit trim needs no
+    // reason beyond the coverage note's own words.
+    const callerTrimmed = lines.length < threadAll.length;
+    return {
+      lines,
+      possiblyIncomplete: mightBeTruncated || callerTrimmed,
+      ...(mightBeTruncated ? { partialReason: `vendor page limit: only the first ${MAX_REVIEW_PAGES * GITHUB_MAX_PAGE} review comments on this PR were fetched` } : {}),
+    };
+  },
+};

package/agent/channels/github-stop.ts

@@ -0,0 +1,175 @@
+// THE GITHUB STOP ARM (OPE-898) — the nearest honest equivalent to the ✋ reaction.
+//
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+// 🔴 GITHUB SENDS NO WEBHOOK FOR A REACTION. THIS IS THE VENDOR EVIDENCE, AND IT IS WHY THIS FILE
+//    READS A COMMENT INSTEAD OF AN EMOJI.
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+//
+// GitHub's complete webhook event list (docs.github.com/en/webhooks/webhook-events-and-payloads,
+// read 2026-08-20) carries no `reaction` member and no reaction sub-event on any of the comment
+// families. Reactions exist in the REST API (`/reactions`) as a read-and-write resource, but nothing
+// PUSHES one — so consuming a ✋ on this surface would need polling, and a stop affordance that costs
+// a poll loop is not an affordance, it is a background job with a latency floor.
+//
+// SO THE TRIGGER IS A COMMENT, READ AT THE INGRESS. `channels/turn-cancel.ts`'s `isStopDirective`
+// owns the grammar and its header carries the reasoning for why the match is exactly one word. Two
+// properties make it a real equivalent rather than a chat message the agent happens to notice:
+//
+//   1. IT NEVER QUEUES BEHIND THE TURN IT STOPS. The cancel runs in the INGRESS process, before any
+//      session is minted and before any model call — the same pre-dispatch position the Slack and
+//      Discord reactions run in. A message the AGENT read would queue behind the very turn it means
+//      to stop, which is the structural reason stop cannot be an inference decision at all.
+//   2. IT COSTS NOTHING. No session, no model call, nothing spent — so it keeps working for exactly
+//      the person most likely to need it, whose scope is already over its cap.
+//
+// 🔴 THE BARE SPELLINGS ONLY, AND THAT IS DELIBERATE. An `@bot stop` comment is a MENTION, so eve's
+// native GitHub channel would open a session for it — the ingress would cancel the running turn and
+// start a new one in the same breath. `isStopDirective` refuses the mention spellings for that
+// reason. The caller ALSO suppresses its own ambient leg for a stop delivery (channels/github.ts),
+// so a bare `stop` wakes nothing on either path.
+
+import {
+  cancelAnchoredTurn,
+  isStopDirective,
+  resolvePartition,
+  turnChannelKey,
+  type AttachSessionForCancel,
+  type CancelOutcome,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { buildGitHubAuth, githubConversationKey } from "./github-identity.js";
+
+/** The two comment event types a stop directive can arrive on. A review COMMENT and an issue/PR
+ *  comment are the only GitHub comment families that hang off a numbered conversation the anchor
+ *  registry can key by. A commit comment has no number, so it is not here. */
+const STOP_EVENT_TYPES = new Set(["issue_comment", "pull_request_review_comment"]);
+
+/** One stop directive, resolved from a webhook delivery. */
+export interface GitHubStopComment {
+  readonly owner: string;
+  readonly repo: string;
+  /** The issue or PR number the comment sits on — half of the conversation key. */
+  readonly number: number;
+  /** WHO asked. Recorded on the audit row; the bot check has already passed by the time this exists. */
+  readonly authorLogin: string;
+  readonly repoPrivate?: boolean;
+}
+
+/** Why the arm did what it did — for the caller's log, never for a person to read. */
+export type GitHubStopOutcome =
+  | { readonly stopped: false; readonly reason: string }
+  | { readonly stopped: true; readonly outcome: CancelOutcome };
+
+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 pick(o: unknown, k: string): unknown {
+  return isObject(o) ? o[k] : undefined;
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/**
+ * Is this comment author a machine? FAIL-CLOSED: an unresolvable author counts as one.
+ *
+ * Behind `cancel()` a fail-OPEN author check is a self-cancel — the agent posts into these very
+ * threads, and its own comment could then stop its own turn. GitHub reports an app's comment with
+ * `user.type: "Bot"` AND a login that ends `[bot]`; both are checked, because either one alone has a
+ * spelling this tree has not measured.
+ */
+export function githubCommentIsMachine(comment: unknown): boolean {
+  const login = str(pick(pick(comment, "user"), "login"));
+  if (!login) return true; // no author ⇒ refuse
+  const type = str(pick(pick(comment, "user"), "type"));
+  return type?.toLowerCase() === "bot" || login.endsWith("[bot]");
+}
+
+/**
+ * Parse a GitHub webhook delivery into a {@link GitHubStopComment}, or null when it is not a stop
+ * directive from a human. NEVER THROWS.
+ *
+ * Every refusal below is silent by design. A delivery that is not a stop directive is the ordinary
+ * case — this function runs on every comment GitHub sends — so there is nothing to log.
+ */
+export function parseGitHubStopComment(body: string, eventType: string): GitHubStopComment | null {
+  if (!STOP_EVENT_TYPES.has(eventType)) return null;
+  let ev: unknown;
+  try {
+    ev = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!isObject(ev)) return null;
+  // `created` only. An EDIT that turns a sentence into "stop" is not somebody pressing a button; it
+  // is a rewrite of history, and acting on one would make the affordance retro-triggerable.
+  if (ev["action"] !== "created") return null;
+  const comment = ev["comment"];
+  if (!isStopDirective(str(pick(comment, "body")))) return null;
+  if (githubCommentIsMachine(comment)) return null;
+  const repository = ev["repository"];
+  const owner = str(pick(pick(repository, "owner"), "login"));
+  const repo = str(pick(repository, "name"));
+  // An `issue_comment` on a PR still carries the PR under `issue` (GitHub models a PR as an issue for
+  // comments), so `issue.number` is the right probe for both; `pull_request.number` covers the review
+  // comment family, whose payload has no `issue`.
+  const number = num(pick(ev["issue"], "number")) ?? num(pick(ev["pull_request"], "number"));
+  const authorLogin = str(pick(pick(comment, "user"), "login"));
+  if (!owner || !repo || number === undefined || !authorLogin) return null;
+  const repoPrivate = pick(repository, "private");
+  return { owner, repo, number, authorLogin, ...(typeof repoPrivate === "boolean" ? { repoPrivate } : {}) };
+}
+
+/** Injected seams, so parse + guard + cancel is unit-tested without a live installation. */
+export interface GitHubStopDeps {
+  readonly attachSession: AttachSessionForCancel;
+  /** Injectable for the test; defaults to the shared `cancelAnchoredTurn`. There is no second cancel
+   *  implementation behind this — the seam exists to observe the call, never to replace it. */
+  readonly cancel?: typeof cancelAnchoredTurn;
+}
+
+/**
+ * Cancel the turn running on the conversation this stop directive was posted into.
+ *
+ * THE CONVERSATION KEY ONLY. A comment id is not the turn's anchor message — the anchor is the
+ * message that STARTED the turn — so offering an `anchorKey` here would be a lookup that always
+ * misses. This is the `/oe stop` grain: the newest running turn in this issue or PR.
+ */
+export async function routeGitHubStopComment(stop: GitHubStopComment, deps: GitHubStopDeps): Promise<GitHubStopOutcome> {
+  const conversationKey = githubConversationKey(stop.owner, stop.repo, stop.number);
+  const channelKey = conversationKey ? turnChannelKey("github", conversationKey) : undefined;
+  if (!channelKey) return { stopped: false, reason: "stop: no conversation key" };
+  const partition = resolvePartition({
+    channel: { kind: "github" },
+    session: {
+      auth: {
+        current: buildGitHubAuth({
+          owner: stop.owner,
+          repo: stop.repo,
+          issueNumber: stop.number,
+          actorLogin: stop.authorLogin,
+          ...(stop.repoPrivate === undefined ? {} : { isPrivate: stop.repoPrivate }),
+        }),
+      },
+    },
+  });
+  const result = await (deps.cancel ?? cancelAnchoredTurn)({
+    org: partition.org,
+    platform: "github",
+    workspace: partition.workspace,
+    requestedBy: stop.authorLogin,
+    // `reaction` names the AFFORDANCE class, not the vendor mechanism: a member pressed the stop
+    // control this surface offers. `command` is the slash-command door and `tool` is the agent's own
+    // verb — neither is what happened here. The audit row's job is "which door do people reach for",
+    // and a GitHub stop comment is the same door as a Slack ✋.
+    via: "reaction",
+    query: { channelKey },
+    attachSession: deps.attachSession,
+  });
+  return { stopped: true, outcome: result.outcome };
+}