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

package/agent/channels/github-post-arm.ts

@@ -0,0 +1,422 @@
+// github-post-arm — GitHub's POST arm for the post-arms registry (OPE-114 stage 1c). Absorbs, VERBATIM,
+// GitHub's arms out of unified-reply.ts (liveGitHubPost + its installation-token minting/caching) and
+// unified-redrive.ts (the github describe/container cases). The unified session runs on the synthetic
+// `unified` channel, so this arm mints its OWN repo-scoped CONVERSATION-WRITE installation token
+// (scm/mint.ts `CONVERSATION_WRITE_PERMISSIONS`) rather than using an eve github channel handle.
+//
+// 🔴 THE MID-TURN ARM RIDES THE SAME TRANSPORT (OPE-811). This file used to state that GitHub has no
+// mid-turn reply arm "because eve exports no public proactive comment helper". That reasoned from the
+// EVE ENTRY, not from what this deployment can do: `liveGitHubPost` below has posted every unified
+// GitHub reply for weeks, and it needs no eve channel handle — it mints its own token and calls the
+// REST comments endpoint. So the honest availability bar ("never expose a `reply` that would throw")
+// is met, and `resolveTarget` / `dispatchReply` now sit here over the SAME function the unified spine
+// uses. A GitHub supervisor turn therefore delivers through the same `reply` tool as a Slack seat.
+
+// The SCM plane (mint/config) STAYS in core by doctrine (the single SCM implementation) — this arm
+// reaches its App-token minting + config through the adapter-api barrel, alongside the post-arm /
+// wake-origin / unified-reply contracts. See docs/extending/provider-bundles.md.
+import {
+  parsePrivateKey,
+  signAppJwt,
+  mintInstallationToken,
+  CONVERSATION_WRITE_PERMISSIONS,
+  loadGitHubAppConfig,
+  resolveGitHubInstallationId,
+  warmCredential,
+  markNotApplied,
+  withRetryAfter,
+  type RateLimitRetryOptions,
+  type BrokeredSecret,
+  type PostArm,
+  type ReplyTarget,
+  type ReactTarget,
+  type TargetResolveBag,
+  type UnifiedWakeOrigin,
+  type UnifiedReplyDeps,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { markGitHubConversationPosted } from "./github-reaction-scope.js";
+
+type GitHubOrigin = Extract<UnifiedWakeOrigin, { platform: "github" }>;
+type GitHubReactTarget = Extract<ReactTarget, { platform: "github" }>;
+
+/** What the mint needs at call time. `privateKeyPem` never leaves this process and is never part of
+ *  the cache key or any log/audit line. */
+interface GitHubMintContext {
+  readonly appId: string;
+  readonly privateKeyPem: string;
+  readonly installationId: string;
+  readonly owner: string;
+  readonly repo: string;
+}
+
+/**
+ * One minted token per (installation, repo), held warm by the SHARED seam (core
+ * credentials/warm.ts, OPE-134). Installation tokens live 1h; re-minting per reply would be correct
+ * but wasteful. Keyed by installation id AND repo, because the token is down-scoped to
+ * `[origin.repo]` (buildMintBody): a domain spanning two repos under ONE installation must NOT serve
+ * repo-A's repo-scoped token for a repo-B reply (GitHub 404s). `re-mint` posture with the seam's
+ * 5-minute default margin — exactly the rhythm this arm ran before, now with per-key single-flight
+ * and, crucially, a LOUD `github.token_mint_failed` audit row on failure (previously a mint failure
+ * left nothing durable behind at all: the reply just threw).
+ */
+const installationToken = warmCredential<GitHubMintContext>({
+  name: "github.installation-token",
+  platform: "github",
+  auditAction: "github.token_mint_failed",
+  refresh: "re-mint",
+  fallbackTtlSeconds: 3600,
+  // Non-secret by construction: an installation id and a repo name, the same key the local cache used.
+  key: (ctx) => `${ctx.installationId} ${ctx.repo}`,
+  mint: async (ctx): Promise<BrokeredSecret> => {
+    const jwt = await signAppJwt(parsePrivateKey(ctx.privateKeyPem), ctx.appId, Math.floor(Date.now() / 1000));
+    // Repo-scoped CONVERSATION-WRITE set (scm/mint.ts): `issues:write` + `pull_requests:write` +
+    // `metadata:read`. NEVER `contents` — this arm must not be able to touch code.
+    //
+    // 🔴 BOTH WRITE FAMILIES, BECAUSE A CONVERSATION IS AN ISSUE OR A PR (OPE-1020). This file used
+    // to mint `{issues: "write"}` alone and call it "the narrowest permission that posts an
+    // issue/PR-timeline comment". That was WRONG for the PR half, and it made the agent MUTE on
+    // every GitHub PR thread: the wake fired, the turn ran, the spend was incurred, and the reply
+    // POST came back 403. Measured on deploy #118 — two plain issues took 201 and one PR took 403
+    // twice, same repo, same session, same endpoint. GitHub routes `/issues/{n}/comments` by the
+    // RESOURCE the number names, and lists that endpoint under BOTH permission families.
+    const minted = await mintInstallationToken({ jwt, installationId: ctx.installationId, repoNames: [ctx.repo], permissions: CONVERSATION_WRITE_PERMISSIONS });
+    // OPE-914: a 201 mint is NOT proof the token covers the repo it was asked for — GitHub can
+    // return a token whose `repositories` list omits the requested name (a stale/mismatched
+    // installation-repo mapping) without erroring the mint call itself, and the ONLY symptom
+    // downstream is a 403 on the comment POST that looks identical to a permissions gap. Check the
+    // grant here, at the one place that still holds the expected full_name, so a repo the
+    // installation does not actually cover fails LOUD (the warmCredential seam's own
+    // `github.token_mint_failed` audit row) instead of a confusing later 403.
+    const expected = `${ctx.owner}/${ctx.repo}`;
+    if (!minted.repositories.includes(expected)) {
+      throw new Error(
+        `installation token for "${ctx.installationId}" does not cover "${expected}" — granted: [${minted.repositories.join(", ") || "none"}].`,
+      );
+    }
+    // GitHub states expiry as an ISO-8601 string. An unparseable one falls back to the declared
+    // 1h TTL rather than becoming a NaN deadline (which would compare false forever and re-mint on
+    // every single reply).
+    const parsed = Date.parse(minted.expiresAt);
+    return { value: minted.token, expiresAtMs: Number.isFinite(parsed) ? parsed : undefined };
+  },
+});
+
+/** Test-only reset — drops every held installation token. */
+export function _resetGitHubInstallationTokenCache(): void {
+  installationToken.reset();
+}
+
+/** GitHub App credentials for the unified reply arm: the scm plane's env pair preferred, the eve
+ *  channel's pair as fallback (same App in a normal deploy — two spellings, one identity). */
+function githubAppCreds(): { appId: string; privateKeyPem: string; installations: Record<string, string> } | null {
+  const scm = loadGitHubAppConfig();
+  if (scm) return { appId: scm.clientId ?? scm.appId, privateKeyPem: scm.privateKeyPem, installations: scm.installations };
+  const appId = process.env.GITHUB_APP_ID;
+  const privateKeyPem = process.env.GITHUB_APP_PRIVATE_KEY;
+  if (!appId || !privateKeyPem) return null;
+  return { appId, privateKeyPem, installations: {} };
+}
+
+/** Exported for the reaction-feedback poll (channels/github-reaction-feedback.ts, OPE-1502), which
+ *  reads under the same App identity every other GitHub call in this bundle uses. */
+export async function installationTokenFor(origin: GitHubOrigin): Promise<string> {
+  const creds = githubAppCreds();
+  if (!creds) {
+    // DEFINITIVE (OPE-825): no App credentials ⇒ no request ever left this host.
+    throw markNotApplied(new Error("reply couldn't post to GitHub — no App credentials (set OE_GITHUB_APP_* or GITHUB_APP_ID/GITHUB_APP_PRIVATE_KEY)."));
+  }
+  // The wake's own (webhook-supplied) installation id first; then the SCM plane's composed map —
+  // OE_GITHUB_INSTALLATIONS authoritative, `installation`-webhook-discovered installs augmenting it
+  // (scm/installations.ts), so an org that self-installed resolves without an env edit.
+  const installationId = origin.installationId !== undefined ? String(origin.installationId) : await resolveGitHubInstallationId(origin.owner, creds.installations);
+  if (!installationId) {
+    // DEFINITIVE (OPE-825): unresolved before any comment request is built — nothing left this host.
+    throw markNotApplied(new Error(
+      `reply couldn't post to GitHub — no installation id for owner "${origin.owner}" (the wake carried none, OE_GITHUB_INSTALLATIONS has no entry, and no installation webhook has registered one).`,
+    ));
+  }
+  // Key by (installation, repo): the minted token is scoped to exactly [origin.repo], so a sibling
+  // repo under the same installation needs its OWN token.
+  return installationToken.get({ appId: creds.appId, privateKeyPem: creds.privateKeyPem, installationId, owner: origin.owner, repo: origin.repo });
+}
+
+// --- THE GITHUB WRITE SEAM (OPE-1235) ----------------------------------------------------------
+//
+// THE ONE PLACE a GitHub CHANNEL write leaves this package. Before OPE-1235 the three writes below —
+// the comment POST, the comment PATCH, the reaction POST — each called the global `fetch` with its
+// own copy of the same four headers and no 429 handling at all. GitHub answers a rate-limited write
+// with HTTP 429 and a `Retry-After` header, so every one of those writes failed on the FIRST
+// refusal: the reply threw `reply couldn't post to GitHub — 429 …` and the answer was lost.
+//
+// 🔴 "THIS PACKAGE" IS THE HONEST SCOPE, AND THE COUNTER-EXAMPLE IS ONE LINE ABOVE EVERY CALL.
+// `installationTokenFor` mints the token through core's `mintInstallationToken` (scm/mint.ts), which
+// is a bare `fetch` POST to `api.github.com/app/installations/{id}/access_tokens` with NO backoff. It
+// runs immediately before every write below, against the same vendor limiter. A 429 there loses the
+// reply exactly as a 429 here used to — one call earlier. `scm/mint.ts` is a PROTECTED PATH
+// (`scripts/upgrade-fence/manifest.ts`'s `github-permission-sets` rule), so the merge fence refuses
+// EVERY diff that touches it, whoever authored it (OPE-1315). Closing this gap needs the
+// orchestrator's explicit review-and-override.
+// Core's OTHER SCM write plane files (issue-actions.ts, pr.ts, contents.ts, refs.ts) DO carry the
+// backoff now, via `withRetryAfterLoose` (OPE-1253) — `docs/extending/provider-rate-limits.md`
+// records the mint as the one remaining gap. Do not read the paragraph above as "the mint is
+// covered".
+//
+// THE 403 SPELLING IS COVERED HERE NOW, AND ONLY HERE (OPE-1256). GitHub documents a rate-limit
+// refusal as "403 Forbidden or 429 Too Many Requests", often with `Retry-After` on either. The shared
+// primitive still branches on 429 for every other provider; this seam sets the per-seam opt-in
+// `retryForbiddenWithRetryAfter`, which admits a 403 ONLY when it carries a readable `Retry-After`. A
+// BARE 403 stays a permission refusal on every seam, this one included. GitHub's live 403 rate-limit
+// response is still UNMEASURED — `isRateLimitedForbidden` in `channels/rate-limit-retry.ts` carries
+// that residual and the argument for why the discriminator can under-fire but cannot misfire.
+// STILL OUT OF SCOPE: GitHub's OTHER paths do not set the flag — core's SCM write plane (pr.ts,
+// issue-actions.ts, contents.ts, refs.ts) and `github-read.ts` carry the 429 backoff only.
+//
+// One funnel fixes that once. It also removes the header triplication, which is the reason a fourth
+// write would have grown a fourth copy with a fourth chance to omit something.
+//
+// WHAT IT DOES, and only this:
+//   • Builds the request — base URL, method, the four fixed headers, a JSON body.
+//   • Honours a 429's `Retry-After` through `channels/rate-limit-retry.js`, bounded in attempts, in
+//     one wait, and in total wait.
+//   • Ends an outlasted 429 in the NAMED `RateLimitExhaustedError`, which states the surface and the
+//     operation and carries no token, no body and no personal data.
+//   • Returns EVERY other response untouched — a 201, a 404, a 5xx. The callers below keep reading
+//     `res.ok` and `res.status` exactly as they did, so the OPE-825 status-on-the-error posture is
+//     unchanged. A transport throw still propagates unretried: GitHub may already have applied that
+//     write, and repeating it could double a comment.
+//
+// 🔴 NOTHING ELSE IN THIS PACKAGE'S `agent/` MAY CALL THE GLOBAL `fetch` DIRECTLY.
+// `github-write-seam-test.ts` scans this package and reds when a bare `fetch(` appears in it. That
+// scan reaches THIS PACKAGE ONLY: a call site that imports a core SCM helper bypasses the backoff
+// with the scan still green, which is why the paragraph above names those helpers rather than
+// trusting the gate to catch them.
+//
+// `github-read.ts` holds its own read-only transport (`PrFetchFn`) — a SEPARATE seam from this one,
+// tracked as its own § 4 entry in the same scan, and it now carries the backoff too (OPE-1255, via
+// `withRetryAfterLoose`). See `channels/rate-limit-retry.ts`'s doc comment on `withRetryAfterLoose`
+// for why the loose adapter exists rather than `withRetryAfter` directly.
+
+/** GitHub's REST base. */
+export const GITHUB_API_BASE = "https://api.github.com";
+
+/** The subset of the global `fetch` this seam uses — injectable so a test drives it without GitHub. */
+export type GitHubFetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** Transport and retry seams. A test injects them; live code passes none and takes the shared
+ *  defaults from `channels/rate-limit-retry.ts`. */
+export interface GitHubWriteDeps {
+  readonly fetch?: GitHubFetchLike;
+  readonly retry?: Pick<RateLimitRetryOptions, "maxAttempts" | "capMs" | "fallbackMs" | "totalBudgetMs" | "sleep" | "now">;
+}
+
+/**
+ * Issue one GitHub REST write under an installation token, with the 429 backoff applied.
+ *
+ * `operation` is the vendor route name (`issues.createComment`), NOT the resolved path: it is what
+ * `RateLimitExhaustedError` reports, and a path would put an owner, a repo and an issue number into
+ * a failure that promises every field on it is safe to log.
+ */
+export async function githubWrite(
+  input: {
+    readonly operation: string;
+    readonly method: "POST" | "PATCH";
+    readonly path: string;
+    readonly token: string;
+    readonly body: unknown;
+  },
+  deps: GitHubWriteDeps = {},
+): Promise<Response> {
+  const send = (): Promise<Response> =>
+    (deps.fetch ?? (globalThis.fetch as GitHubFetchLike))(`${GITHUB_API_BASE}${input.path}`, {
+      method: input.method,
+      headers: {
+        authorization: `Bearer ${input.token}`,
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(input.body),
+    });
+  // `retryForbiddenWithRetryAfter` is the PER-SEAM opt-in of OPE-1256, and this seam is the only
+  // place in the repo that sets it. GitHub is the one vendor that documents 403 as a rate-limit
+  // spelling; the primitive still refuses to retry a BARE 403 here or anywhere. The unverified half —
+  // GitHub's live 403 shape — and why it cannot misfire are written on `isRateLimitedForbidden`.
+  return withRetryAfter(send, { ...deps.retry, surface: "github", operation: input.operation, retryForbiddenWithRetryAfter: true });
+}
+
+/** THE ONE GitHub POST: an issue/PR-timeline comment via the GitHub REST API under a SHORT-LIVED
+ *  installation token minted host-side from the App credentials. Both spines call it — the UNIFIED
+ *  window (with a frozen wake origin) and the MID-TURN `reply` tool (with a binding-resolved target,
+ *  OPE-811). The installation id rides the origin/target when the webhook carried one, with the scm
+ *  config's owner map as the fallback — a missing/mismatched installation fails VISIBLE, never a
+ *  comment into the wrong repo. */
+/** Exported for github-message-ops.ts (OPE-899's `SurfaceMessageOps.postText`) — the SAME comment
+ *  POST, never a second copy of the mint/fetch mechanics. */
+export async function liveGitHubPost(origin: GitHubOrigin, text: string): Promise<string> {
+  const token = await installationTokenFor(origin);
+  const res = await githubWrite({
+    operation: "issues.createComment",
+    method: "POST",
+    path: `/repos/${origin.owner}/${origin.repo}/issues/${origin.issueNumber}/comments`,
+    token,
+    body: { body: text },
+  });
+  if (!res.ok) {
+    // Token-free error (the response body can't contain our credential; keep it short anyway). The
+    // numeric HTTP status rides on the error (OPE-825) so the classifier can read it directly.
+    throw Object.assign(new Error(`reply couldn't post to GitHub — ${res.status} on ${origin.owner}/${origin.repo}#${origin.issueNumber}`), { status: res.status });
+  }
+  const json = (await res.json().catch(() => ({}))) as { id?: number };
+  // 🔴 ONE HALF OF THE REACTION POLL'S SCOPE RECORD (OPE-1540). This is the one place a GitHub
+  // comment leaves THIS BUNDLE, so it is where this bundle learns the agent is now in a conversation.
+  // It is NOT every comment the agent posts: eve's own poster still emits the `input.requested`
+  // comment, which this bundle does not override and this code never sees. (The native @mention
+  // leg's TERMINAL completion does claim here now — it posts through this function since OPE-1681.)
+  // The poll's gate therefore reads the ENGAGEMENT row as well — see
+  // channels/github-reaction-scope.ts, which states why one record cannot cover both posters. AFTER
+  // the post, and never a reason to fail one: the call never throws.
+  //
+  // 🔴 AND NEVER A REASON TO DELAY ONE EITHER. The comment has already landed when this runs, so the
+  // only thing this await can cost is the reply tool's RETURN — on the turn path, where an unbounded
+  // store call has no business. `markGitHubConversationPosted` owns that ceiling
+  // (`GITHUB_POSTED_MARK_TIMEOUT_MS`) rather than this call site, because the best-effort contract
+  // that says a lost mark costs a later poll and never a reply belongs with the mark.
+  await markGitHubConversationPosted(origin.owner, origin.repo, origin.issueNumber, new Date().toISOString());
+  return json.id !== undefined ? String(json.id) : "unknown";
+}
+
+type GitHubReplyTarget = Extract<ReplyTarget, { platform: "github" }>;
+
+/** The {@link GitHubOrigin} shape {@link liveGitHubPost} posts to, built from a mid-turn
+ *  {@link ReplyTarget}. The two carry the same four facts under the same names, so this is a widening
+ *  rather than a translation — stated as a function so a future divergence has one place to live. */
+function originForTarget(target: GitHubReplyTarget): GitHubOrigin {
+  return {
+    platform: "github",
+    owner: target.owner,
+    repo: target.repo,
+    issueNumber: target.issueNumber,
+    ...(target.installationId !== undefined ? { installationId: target.installationId } : {}),
+  };
+}
+
+/** THE ONE GitHub EDIT (OPE-862): rewrite an existing issue/PR-timeline comment's body. `channelId`
+ *  is the SAME composite "owner/repo" string {@link replyDedupeLocus}/{@link unifiedDedupeLocus} in
+ *  reply-post.ts/unified-reply.ts already use for a GitHub locus — the arm parses it back apart
+ *  rather than the EditLocus contract growing a second field, mirroring how those two dedupe keys
+ *  are already built. The installation id rides no locus, so this resolves through the SAME
+ *  owner→installation fallback map `liveGitHubPost` falls back to when a target carries none. */
+/** Exported for github-message-ops.ts (OPE-899's `SurfaceMessageOps.editMessage`) — same reason as
+ *  {@link liveGitHubPost}: one PATCH implementation, never two. */
+export async function liveGitHubEditComment(channelId: string, commentId: string, text: string): Promise<void> {
+  const [owner, repo] = channelId.split("/");
+  if (!owner || !repo) {
+    throw markNotApplied(new Error(`edit_reply couldn't parse the GitHub locus "${channelId}" — expected "owner/repo".`));
+  }
+  const token = await installationTokenFor({ platform: "github", owner, repo, issueNumber: 0 });
+  const res = await githubWrite({
+    operation: "issues.updateComment",
+    method: "PATCH",
+    path: `/repos/${owner}/${repo}/issues/comments/${commentId}`,
+    token,
+    body: { body: text },
+  });
+  if (!res.ok) {
+    throw Object.assign(new Error(`edit_reply couldn't edit the GitHub comment — ${res.status} on ${owner}/${repo} comment ${commentId}`), { status: res.status });
+  }
+}
+
+// --- REACT (OPE-862) --------------------------------------------------------------------------
+//
+// GitHub's reaction primitive (`POST /repos/{o}/{r}/issues/{n}/reactions`) is a FIXED 8-value
+// `content` enum, unlike Slack/Linear's free-text emoji name — so the model's bare name (react.ts's
+// EMOJI_NAME_PATTERN) is mapped to GitHub's own vocabulary here, and a name with no equivalent
+// refuses honestly rather than silently reacting with the wrong glyph or dropping the call.
+// Idempotent on GitHub's side (a duplicate reaction returns the existing one, 200/201 either way),
+// so — unlike Slack's `already_reacted` — no special-case handling is needed for a repeat call.
+type GitHubReactionContent = "+1" | "-1" | "laugh" | "confused" | "heart" | "hooray" | "rocket" | "eyes";
+
+const GITHUB_REACTION_MAP: Readonly<Record<string, GitHubReactionContent>> = {
+  "+1": "+1",
+  thumbsup: "+1",
+  "-1": "-1",
+  thumbsdown: "-1",
+  laugh: "laugh",
+  laughing: "laugh",
+  joy: "laugh",
+  confused: "confused",
+  heart: "heart",
+  hooray: "hooray",
+  tada: "hooray",
+  rocket: "rocket",
+  eyes: "eyes",
+};
+
+async function liveGitHubReact(origin: GitHubOrigin, emoji: string): Promise<void> {
+  const content = GITHUB_REACTION_MAP[emoji.toLowerCase()];
+  if (!content) {
+    // DEFINITIVE (OPE-825): decided before any byte left this host — the model's name has no mapping.
+    throw markNotApplied(
+      new Error(
+        `react couldn't post to GitHub — "${emoji}" has no GitHub reaction equivalent; GitHub only supports: ${[...new Set(Object.values(GITHUB_REACTION_MAP))].join(", ")}.`,
+      ),
+    );
+  }
+  const token = await installationTokenFor(origin);
+  const res = await githubWrite({
+    operation: "issues.createReaction",
+    method: "POST",
+    path: `/repos/${origin.owner}/${origin.repo}/issues/${origin.issueNumber}/reactions`,
+    token,
+    body: { content },
+  });
+  if (!res.ok) {
+    throw Object.assign(new Error(`react couldn't post to GitHub — ${res.status} on ${origin.owner}/${origin.repo}#${origin.issueNumber}`), { status: res.status });
+  }
+}
+
+export const githubPostArm: PostArm = {
+  platform: "github",
+  // MID-TURN (OPE-811): owner + repo + the issue/PR anchor, all off the binding's post-back target
+  // (github-identity.ts `bindGitHub`), never a tool argument. A PR timeline comment anchors on the
+  // SAME `/issues/{n}/comments` endpoint, so either anchor number resolves the one target shape.
+  resolveTarget: (bag: TargetResolveBag): ReplyTarget | null => {
+    const owner = bag.str("owner");
+    const repo = bag.str("repo");
+    const issueNumber = bag.num("issueNumber") ?? bag.num("pullRequestNumber");
+    if (!owner || !repo || issueNumber === undefined || !Number.isFinite(issueNumber) || issueNumber <= 0) return null;
+    const installationId = bag.num("installationId");
+    return { platform: "github", owner, repo, issueNumber, ...(installationId !== undefined ? { installationId } : {}) };
+  },
+  dispatchReply: (target, text) => liveGitHubPost(originForTarget(target as GitHubReplyTarget), text),
+  dispatchUnified: (origin, text, deps: UnifiedReplyDeps) => (deps.postGitHub ?? liveGitHubPost)(origin as GitHubOrigin, text),
+  // EDIT (OPE-862): PATCH the issue/PR-timeline comment `liveGitHubPost` already returns a real id
+  // for — no sentinel-id prerequisite here, unlike Linear's ambient route.
+  editMessage: (locus, messageId, text) => liveGitHubEditComment(locus.channelId, messageId, text),
+  // REACT (OPE-862): the same conversation anchor `reply` posts into — GitHub has no message-level
+  // react target the binding carries, so this resolves owner/repo/issueNumber independently of
+  // resolveTarget (see ReactTarget's doc in post-arms.ts).
+  resolveReactTarget: (bag: TargetResolveBag): ReactTarget | null => {
+    const owner = bag.str("owner");
+    const repo = bag.str("repo");
+    const issueNumber = bag.num("issueNumber") ?? bag.num("pullRequestNumber");
+    if (!owner || !repo || issueNumber === undefined || !Number.isFinite(issueNumber) || issueNumber <= 0) return null;
+    const installationId = bag.num("installationId");
+    return { platform: "github", owner, repo, issueNumber, ...(installationId !== undefined ? { installationId } : {}) };
+  },
+  react: (target, emoji) => {
+    const t = target as GitHubReactTarget;
+    return liveGitHubReact(
+      { platform: "github", owner: t.owner, repo: t.repo, issueNumber: t.issueNumber, ...(t.installationId !== undefined ? { installationId: t.installationId } : {}) },
+      emoji,
+    );
+  },
+  describeRedriveTarget: (origin) => {
+    const o = origin as GitHubOrigin;
+    return `github ${o.owner}/${o.repo}#${o.issueNumber}`;
+  },
+  redriveContainerId: (origin) => {
+    const o = origin as GitHubOrigin;
+    return `${o.owner}/${o.repo}`;
+  },
+};