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

package/agent/channels/github-supervisor.ts

@@ -0,0 +1,645 @@
+// The GitHub ambient supervisor — the eve-FREE tested core that turns every NON-mention
+// issue/PR-timeline comment on an opted-in repo into a JUDGED wake to a standing per-REPO
+// supervisor session. It is the SECOND non-Slack adopter of the surface-general
+// ambient-supervision pattern (surface-adapter-port.md §"Ambient supervision everywhere"),
+// deliberately THIN — it copies notion-supervisor.ts (the template) with the two GitHub-shaped
+// differences called out below. Linear copies this pair next.
+//
+// WHAT'S REUSED WHOLESALE (zero GitHub-specific logic in any of it):
+//   • renderWake + the channel-watch preamble (the judge) — normalized-wake.ts (containerNoun
+//     "repo"; the engagement tier rides the same field — GitHub PLATFORM-DEFAULTS to `reserved`,
+//     memory/domain.ts engagementTierFor)
+//   • shouldRotate — the pure rotation policy — slack-events.ts
+//   • the (org, surfaceKey) channel_session registry + the :oe-sup:g spend counter — via deps
+//   • githubBotMentioned — the SAME mention gate the native path wakes on — github-identity.ts
+//
+// THE TWO GITHUB-SHAPED DIFFERENCES vs the Notion template:
+//   1. MENTIONS ARE DROPPED, not `direct`. eve's native githubChannel already owns the @mention
+//      path (github.ts onComment → session + checkout + reply); a mention reaching the ambient
+//      leg too would double-handle the comment. classifyGitHubComment reuses githubBotMentioned
+//      — the EXACT gate the native path wakes on — so the two legs partition every comment
+//      between them with no overlap and no gap.
+//   2. DRIVE-BY REPOS ARE DROPPED (fail closed). A repo ambient-wakes only when it is positively
+//      private (every commenter was invited by the org — the Notion/Slack membership analog) OR
+//      the operator has VOUCHED it internal (identity/trust.ts). On a public, un-vouched repo any
+//      drive-by stranger could wake judged turns — an uninvited spend + prompt-injection surface
+//      the design's "GitHub repos in a domain are ~always private" assumption deliberately
+//      excludes. The VOUCH additionally widens ambient to a vouched public repo (the operator's
+//      explicit "this surface is internal" assertion), and — separately — is the SOLE floor for
+//      the cross-surface single WINDOW (see classifyGitHubAmbientComment): a private flag never
+//      admits the shared window, only the vouch does.
+//
+// The repo-session is the container-session's ORCHESTRATION HALF ONLY (surface-adapter-port
+// §"container session"): a repo-scoped standing session aware of the repo's issue/PR
+// conversations, holding repo memory, that judges every comment and replies into the triggering
+// issue. There is NO container-conversation half — a repo has no top-level chat to post to
+// (containerConversation: false), so a judged reply always targets the triggering issue/PR.
+
+import {
+  renderWake,
+  mkMessageTrigger,
+  shouldRotate,
+  singleWindowMentionPolicy,
+  stampNonMemberChatAuth,
+  seatCatchUpSinceMs,
+  admitContextLines,
+  engagedFollowUpContract,
+  type SeatAdmissionFn,
+  type SeatCatchUpRequest,
+  type SeatCatchUpResult,
+  type NormalizedWake,
+  type WakeEngagementTier,
+  type ContextLine,
+  type UnifiedWindowWake,
+  type WakeTrust,
+  type IngestedChatMessage,
+  type WakeMessageInput,
+  tailAuthorGrain,
+  type SessionTailWakeRow,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { githubBotMentioned, type OpenEverywhereGitHubAuth } from "./github-identity.js";
+
+/** The catch-up's REACHBACK FLOOR (hours): how far back a seat that has been quiet for a long time
+ *  reads. 7 days, the same floor every other surface's bootstrap window uses, so one number governs
+ *  "how much history is a seat ever worth" across the fleet. */
+const GITHUB_CATCH_UP_REACHBACK_HOURS = 168;
+
+// --- supervisor token / sentinel (carry the :oe-sup:g infix — load-bearing) ----------
+//
+// hooks/spend.ts isSupervisorToken keys off the `:oe-sup:g` substring to (a) tag the usage-event
+// `kind="supervisor"` and (b) drive the per-generation cumulative-token rotation counter, and
+// model/routing.ts isSupervisorSession keys the cheap `supervisor` model role off the same
+// `oe-sup:g<n>` suffix. Carry the infix and the ENTIRE cost/rotation/model-tier apparatus works
+// for free. The token puts `owner/repo` in the channel-id slot, `github:`-namespaced (eve
+// prefixes the channel name again on send — harmless, mirrors Notion).
+
+/** The reserved pseudo-thread sentinel for a supervisor generation (mirrors Slack's/Notion's). */
+export function githubSupervisorSentinel(generation: number): string {
+  return `oe-sup:g${generation}`;
+}
+
+/** The reserved continuation token for a repo's supervisor session at a given generation:
+ *  `github:<owner>/<repo>:oe-sup:g<generation>`. A custom continuation token eve never
+ *  re-anchors, carrying the `:oe-sup:g` infix hooks/spend.ts + model/routing.ts key on. */
+export function githubSupervisorToken(owner: string, repo: string, generation: number): string {
+  return `github:${owner}/${repo}:${githubSupervisorSentinel(generation)}`;
+}
+
+// UNIFIED cross-surface dispatch (formerly TODO(unified-dispatch) — wired 2026-07-11), same shape
+// as the Slack reference wiring (channels/slack-events.ts liveSupervisorDeps): when the repo's
+// domain has opted in (both gates on), the LIVE deps in github.ts key the registry ROW + TOKEN by
+// `(org, domain)` via channels/unified-supervisor.ts supervisorGrainFor/supervisorTokenForGrain, so
+// an issue/PR comment dispatches into the domain's SHARED session, and this core stamps
+// `<channel platform="github">` + the P5 disclosure on the wake (`unified` on the dispatch input).
+// Gated → byte-identical off (grain `{unified:false}` ⇒ the per-repo registry key + token below and
+// an unstamped wake). The cross-surface REPLY leg is per-wake by construction — github.ts's
+// turn.started snapshots owner/repo/issue off THIS delivery's auth on the unified path, so a
+// multi-repo domain session always answers into the repo that woke it (see unified-supervisor.ts's
+// cross-surface-reply header for the whole model + the eve session-namespacing caveat).
+
+// --- the classifier (pure) -----------------------------------------------------------
+
+/** How the ambient leg treats one comment. By default a bot @mention is owned by eve's NATIVE
+ *  githubChannel path (github.ts onComment), so the ambient leg `drop`s it and everything it keeps
+ *  is `channel-watch` (judged by the repo supervisor). The `direct` value exists ONLY for the
+ *  SINGLE-WINDOW path (github.ts passes `treatMentionAsDirect` for the GRAIN alone — the repo's
+ *  domain has crossSurfaceWindow on — and passes the operator VOUCH beside it as the privacy floor,
+ *  never the repo-private flag; see step 4 below): there the native mention session is suppressed,
+ *  so the ambient leg keeps the @mention and routes it to the unified window as an ADDRESSED wake
+ *  the shared-context supervisor answers. */
+export type GitHubAmbientAddressing = "direct" | "channel-watch" | "drop";
+
+export interface GitHubAmbientClassification {
+  readonly addressing: GitHubAmbientAddressing;
+  readonly reason: string;
+}
+
+/** The comment facts the classifier consumes — a narrow projection of the issue_comment
+ *  webhook payload (the route leg extracts it; tests build it directly). */
+export interface GitHubAmbientComment {
+  readonly body?: string;
+  readonly authorLogin?: string;
+  /** "User" | "Bot" | "Organization" — GitHub's `comment.user.type`. */
+  readonly authorType?: string;
+  /** Repo privacy, positively known (payload `repository.private`); absent → unknown. DEMOTED to
+   *  a logged defense-in-depth SIGNAL: it no longer gates the cross-surface window (the operator
+   *  vouch does) but still enables the per-repo ambient path (a private repo is invite-only). */
+  readonly repoPrivate?: boolean;
+}
+
+/**
+ * Decide how the ambient leg should treat one issue/PR-timeline comment, in cost order:
+ *  1. NO bot slug configured ⇒ DROP (fail closed) — self-identity is a precondition for the
+ *     loop guard (the same hardening as Notion's unresolved-botUserId drop).
+ *  2. BOT-authored (`user.type === "Bot"`) ⇒ DROP — covers our own `<slug>[bot]` replies AND
+ *     every other bot (prevents bot-to-bot loops).
+ *  3. Our own login (`<slug>[bot]`, belt-and-braces under a mislabelled type) ⇒ DROP.
+ *  4. @mentions the bot (githubBotMentioned — the native path's EXACT gate):
+ *       • DEFAULT (per-repo) ⇒ DROP: the native githubChannel session owns mentions; the two legs
+ *         partition, never overlap.
+ *       • SINGLE-WINDOW (`treatMentionAsDirect`) on a VOUCHED repo ⇒ `direct`: github.ts
+ *         suppresses the native session for exactly this case, so the ambient leg keeps the mention
+ *         and the unified window answers it as an addressed wake. Still DROP on an un-vouched repo —
+ *         the native path is NOT suppressed there (the gate on both sides is
+ *         `singleWindow && vouched`, the OPERATOR VOUCH — NOT the repo-private flag), so letting
+ *         ambient keep it would double-handle.
+ *  5. Repo neither positively private NOR operator-vouched ⇒ DROP (fail closed) — drive-by public
+ *     repos never ambient-wake (strangers must not buy judged turns; see the header).
+ *  6. otherwise ⇒ channel-watch (judged by the standing repo supervisor).
+ *
+ * `opts.vouched` is the OPERATOR-VOUCH fact the caller resolves (github.ts: isVouchedInternal on
+ * `github/<owner>` OR `github/<owner>/<repo>`, or OE_TRUST=internal). It is the SOLE floor for the
+ * cross-surface WINDOW (step 4's `direct` divert) — the repo's own `repoPrivate` flag is a logged
+ * defense-in-depth SIGNAL, never a window gate. `repoPrivate` still enables the per-repo ambient
+ * path (step 5): a private repo is invite-only, so it ambient-wakes even un-vouched; the vouch
+ * WIDENS ambient to a vouched public repo, and never narrows an already-private one.
+ */
+export function classifyGitHubAmbientComment(
+  c: GitHubAmbientComment,
+  botSlug: string | undefined,
+  opts?: { treatMentionAsDirect?: boolean; vouched?: boolean },
+): GitHubAmbientClassification {
+  const slug = botSlug?.trim();
+  if (!slug) return { addressing: "drop", reason: "no bot slug configured — fail-closed loop guard" };
+  if (c.authorType === "Bot") return { addressing: "drop", reason: "bot-authored comment (loop guard)" };
+  if (c.authorLogin && c.authorLogin.toLowerCase() === `${slug}[bot]`.toLowerCase()) {
+    return { addressing: "drop", reason: "self-authored comment (our own reply)" };
+  }
+  const vouched = opts?.vouched === true;
+  if (githubBotMentioned(c.body, slug, { login: c.authorLogin, type: c.authorType })) {
+    // Single-window VOUCHED repos: the native session is suppressed (github.ts) so the unified
+    // window owns the mention as an addressed wake. Every other repo → the native path owns it.
+    // The decision is the SHARED seam (unified-window.ts singleWindowMentionPolicy) — the exact
+    // predicate the native suppression consults, so the two legs can never double-handle or gap.
+    // `isMention` is pinned true here (this branch is inside the githubBotMentioned gate); the
+    // privacy floor is the operator VOUCH, NOT the repo-private flag.
+    if (singleWindowMentionPolicy(opts?.treatMentionAsDirect === true, true, vouched).addressing === "direct-mention") {
+      return { addressing: "direct", reason: "bot @mention on a single-window vouched repo — answered by the unified window" };
+    }
+    return { addressing: "drop", reason: "bot @mention — owned by the native githubChannel path" };
+  }
+  // Per-repo ambient enablement: a private repo is invite-only (the existing product rule) OR the
+  // operator vouched it internal (widens to a vouched public repo). repoPrivate is now a SIGNAL —
+  // it enables ambient but is no longer the window floor (the vouch is, above).
+  if (c.repoPrivate !== true && !vouched) {
+    return { addressing: "drop", reason: "repo neither positively private nor operator-vouched — fail-closed (no drive-by ambient)" };
+  }
+  return { addressing: "channel-watch", reason: `ambient comment — judged by the repo supervisor (private=${c.repoPrivate === true}, vouched=${vouched})` };
+}
+
+// --- the wake builder (pure) ---------------------------------------------------------
+
+export interface GitHubSupervisorWakeInput {
+  readonly owner: string;
+  readonly repo: string;
+  /** The issue (or PR timeline) number the comment landed on — the reply anchor. */
+  readonly issueNumber: number;
+  /** The issue/PR title (untrusted, payload-supplied) — rendered as a wrapped context line so
+   *  the judge knows WHAT conversation the comment belongs to. Absent ⇒ no context block. */
+  readonly issueTitle?: string;
+  /**
+   * THE DOMAIN'S ADMISSION POLICY over this wake's CONTEXT-LINE slot (OPE-1800), resolved by NAME by
+   * the caller (`seatAdmissionFor`, channels/seat-catch-up.ts) so this core stays config-free —
+   * exactly as `engagementTier` is. It judges the ONE line the slot holds: the issue/PR title.
+   * 🔴 THE SAME POLICY THE CATCH-UP READ ALREADY APPLIES, over the seat's OTHER read, off the SAME
+   * channel key. Since OPE-1857 the catch-up half does not pass a policy at all — `seatCatchUp`
+   * resolves the domain's own from `req.channelKey`, which is the key this caller spells here — so
+   * the two reads take one rule per domain from one resolver. The docs row promises that, and until
+   * OPE-1800 only the catch-up half delivered it.
+   * 🔴 THE TITLE LINE IS UNGRADED AND FLOORS AT `unauth`, by construction: this surface has no
+   * synchronous roster probe for the person who OPENED the issue, and the wake input carries no
+   * identity for them — the same reason `deps.catchUp` is wired with no `trustFor`. So a
+   * `members-only` domain reads the comment without the title, which is the fail-closed answer the
+   * seam's own header states; `wide` (the default) and `wide-with-bots` admit it unchanged.
+   * Absent ⇒ NO admission runs and the slot is byte-identical to the pre-OPE-1800 wake, which is
+   * what keeps an older test double compiling (the posture `catchUp` and `recordWake` take).
+   */
+  readonly admit?: SeatAdmissionFn;
+  readonly trigger: {
+    readonly id: string;
+    readonly authorLogin?: string;
+    readonly sentAt: string;
+    readonly text: string;
+    /**
+     * Resolved per-wake trust tier (identity/wake-trust.ts — the audit-wedge F3 assignment). The
+     * live dispatch (github.ts ambientDelivery) resolves it off the binding gate + admin rosters.
+     *
+     * 🔴 REQUIRED, NOT OPTIONAL (OPE-596) — see LinearSupervisorWakeInput.trigger.trust for the
+     * whole reason. An upward default is fail-OPEN, and since OPE-577 the tier decides the
+     * `<untrusted_external_data>` fence. A caller that cannot resolve a tier states the fail-closed
+     * one itself: `relay` for a machine author, `unauth` for an unvouchable human.
+     */
+    readonly trust: WakeTrust;
+  };
+  /** Engagement calibration (memory/domain.ts engagementTierFor — GitHub platform-defaults to
+   *  `reserved`). Resolved by the caller; this core stays config-free. */
+  readonly engagementTier?: WakeEngagementTier;
+  /** The OUTGOING generation's recorded TAIL (OPE-794), rendered as this first wake's backscroll.
+   *  Only a FRESH generation's first wake carries one; empty or omitted otherwise. */
+  readonly tail?: readonly WakeMessageInput[];
+  /** This surface could not read its own conversation since the seat's last wake (core
+   *  channels/seat-catch-up.ts). Rendered as a trusted `<system-note>`; unset ⇒ no note. */
+  readonly catchUpUnavailable?: string;
+  // 🔴 NO `unified` (OPE-770). It existed to stamp `<channel platform>` and the P5 disclosure
+  // sentence, and both are gone: the render names no surface and the standing block states the
+  // cross-surface rule once per session. A GitHub wake is the same wake whether or not its session
+  // spans surfaces. The unified GRAIN decision is unaffected — it lives on the dispatch input.
+  /** Host-minted wake id (rendered `<wake wake-id=…>`) — SINGLE-WINDOW path only (channels/
+   *  unified-window.ts): the id the model echoes to `reply` so the host resolves this wake's
+   *  origin from the map. Unset ⇒ byte-identical (no attribute) — mirrors SlackWakeOpts.wakeId. */
+  readonly wakeId?: string;
+  /** SINGLE-WINDOW addressed @mention: render
+   *  the wake as `direct-mention` — the full judged envelope (so the `wake-id` survives for the reply
+   *  tool, which is the ONLY reply route on the unified channel) but with the ADDRESSED preamble that
+   *  tells the supervisor it was @mentioned and owes a reply, instead of the silence-biased
+   *  channel-watch preamble. Unset/false ⇒ the channel-watch ambient wake, byte-identical to today.
+   *  Only github.ts's single-window direct path sets it (the classifier returned `direct`). */
+  readonly directMention?: boolean;
+  /**
+   * This issue/PR carries an ENGAGED registry row that reaches the seat — the seam's `deliver`
+   * verdict floored on `githubEngagedFollowUpReach` (github.ts `engagedFollowUp`). A JUDGED
+   * wake then states `follow-up="thread-engaged"`, the envelope's own words for "you are already in
+   * this conversation and `stand_down` is how you leave". Slack, Linear and Notion state the same
+   * fact through the same shared helper (channels/engaged-wake.ts).
+   *
+   * 🔴 THE AUDIT ROW ALREADY SAID IT AND THE ENVELOPE DID NOT (OPE-2093). `github.dispatched` reads
+   * `addressing=thread-follow` off this verdict (OPE-1752) while the seat read bare ambient
+   * activity, so it declined an engaged follow-up with `no_reply` (ship #237, J-ENGAGED-github).
+   * It does NOT touch `addressing`: an @mention stays `direct-mention` and carries no follow-up
+   * attribute, because it is owed an answer whatever the enrolment says. Unset/false ⇒ no attribute.
+   */
+  readonly threadEngaged?: boolean;
+}
+
+/**
+ * Build the NormalizedWake for one repo-supervisor turn: platform "github", containerNoun
+ * "repo", locus.channel = `owner/repo`, locus.thread = `#<issueNumber>` (the conversation the
+ * comment belongs to), the issue title as an untrusted-wrapped context line, and the comment as
+ * the trigger. `channel-watch` (judged) by default; `direct-mention` (addressed, enveloped) when
+ * `directMention` is set — the SINGLE-WINDOW @mention path, which keeps the wake-id envelope but
+ * swaps the silence-biased watch preamble for the addressed one (see the field doc). renderWake
+ * then emits the exact `{message, context}` every OE dispatch sends — the SAME renderer
+ * Slack/Notion use, with NO platform branch.
+ */
+export function buildGitHubSupervisorWake(input: GitHubSupervisorWakeInput): NormalizedWake {
+  const directMention = input.directMention === true;
+  // THE SLOT, THEN THE DOMAIN'S ADMISSION POLICY OVER IT ({@link GitHubSupervisorWakeInput.admit} —
+  // OPE-1800). `thread` is the container position: on GitHub the issue/PR IS the conversation
+  // (locus.thread below), and this line describes it. Nothing admitted ⇒ no context block at all,
+  // never an empty one, which is the same `undefined` an absent title produces.
+  const titleLine: ContextLine[] | undefined = input.issueTitle
+    ? [{ senderType: "user", ts: `#${input.issueNumber}`, text: `issue/PR #${input.issueNumber}: ${input.issueTitle}` }]
+    : undefined;
+  const admittedTitle = titleLine && input.admit ? admitContextLines(titleLine, input.admit, "thread") : titleLine;
+  const contextLines: ContextLine[] | undefined = admittedTitle && admittedTitle.length > 0 ? admittedTitle : undefined;
+
+  return {
+    platform: "github",
+    // A direct @mention is reason "mention" (honest, and rides the envelope); an ambient comment is
+    // "channel-activity". Both keep the full envelope, so the wake-id survives on the single-window path.
+    reason: directMention ? "mention" : "channel-activity",
+    addressing: directMention ? "direct-mention" : "channel-watch",
+    containerNoun: "repo",
+    // engagementTier is the AMBIENT-watch calibration dial (it RAISES the reply bar for a
+    // `reserved` repo); an addressed @mention is owed an answer, so it never applies to a
+    // direct-mention wake — and is byte-identical (input.engagementTier) on the channel-watch path.
+    engagementTier: directMention ? undefined : input.engagementTier,
+    // The ENROLMENT fact ({@link GitHubSupervisorWakeInput.threadEngaged}), through the ONE shared
+    // helper every enveloped surface calls. The helper drops it on a `direct-mention` wake.
+    followUp: engagedFollowUpContract({
+      addressing: directMention ? "direct-mention" : "channel-watch",
+      threadEngaged: input.threadEngaged,
+    }),
+    // Single-window wake id — only the singleWindow dispatch passes it (byte-identical off).
+    wakeId: input.wakeId,
+    locus: {
+      channel: { id: `${input.owner}/${input.repo}` },
+      thread: { ts: `#${input.issueNumber}` },
+    },
+    contextLines,
+    contextSource: contextLines ? "the issue/PR this comment is on" : undefined,
+    backscroll: input.tail && input.tail.length > 0 ? input.tail : undefined,
+    ...(input.catchUpUnavailable !== undefined ? { catchUpUnavailable: input.catchUpUnavailable } : {}),
+    trigger: mkMessageTrigger({
+      from: "human", // self/bot already dropped in classify
+      author: input.trigger.authorLogin ?? "unknown",
+      authorId: input.trigger.authorLogin,
+      id: input.trigger.id,
+      sentAt: input.trigger.sentAt,
+      // The caller's stated per-person tier — no default (OPE-596). Directness is the `mention`
+      // flag below, never a trust tier.
+      trust: input.trigger.trust,
+      // The @mention response-obligation flag (rendered `mention="true"`). Unset on the ambient
+      // path ⇒ no attribute ⇒ byte-identical render.
+      mention: directMention ? true : undefined,
+      body: input.trigger.text,
+    }),
+  };
+}
+
+// --- the payload extractor (pure) ------------------------------------------------------
+
+/** The narrow projection of an `issue_comment` webhook payload the ambient leg consumes —
+ *  classifier facts + wake parts + identity facts, extracted defensively (GitHub payloads are
+ *  external input; anything missing/odd → the fact stays undefined and the consumers fail
+ *  closed). Review-thread inline comments (`pull_request_review_comment`) are deliberately NOT
+ *  ambient v1 — a different reply endpoint/threading model; the extractor returns null. */
+export interface GitHubAmbientEvent {
+  readonly owner: string;
+  readonly repo: string;
+  readonly repositoryFullName?: string;
+  readonly repositoryId?: number;
+  readonly repoPrivate?: boolean;
+  readonly installationId?: number;
+  readonly issueNumber: number;
+  readonly issueTitle?: string;
+  /** True when the timeline comment is on a PR (issue_comment fires for both). */
+  readonly isPullRequest: boolean;
+  readonly comment: GitHubAmbientComment & {
+    readonly id?: string;
+    readonly createdAt?: string;
+    readonly authorId?: number;
+    readonly authorAssociation?: string;
+  };
+}
+
+/** The taint-clean identity fields on one admitted ambient dispatch audit row. */
+export function githubDispatchAuditDetail(input: {
+  readonly addressing: string;
+  readonly issueNumber: number;
+  readonly commentId?: string;
+  readonly wakeId?: string;
+  readonly repoPrivate: boolean;
+  readonly vouched: boolean;
+}): Readonly<Record<string, unknown>> {
+  return {
+    addressing: input.addressing,
+    issueNumber: input.issueNumber,
+    ...(input.commentId ? { commentId: input.commentId } : {}),
+    ...(input.wakeId ? { wakeId: input.wakeId } : {}),
+    repoPrivate: input.repoPrivate,
+    vouched: input.vouched,
+  };
+}
+
+function pick(o: unknown, k: string): unknown {
+  return o && typeof o === "object" ? (o as Record<string, unknown>)[k] : undefined;
+}
+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;
+}
+
+/**
+ * Extract the ambient-leg facts from one webhook delivery, or null when the delivery is not an
+ * ambient candidate at all: only `issue_comment` + `action: "created"` qualifies (edits/deletes
+ * are not conversational triggers v1; review-thread comments are out of scope v1 — see
+ * {@link GitHubAmbientEvent}). Null is "not for this leg", NOT an error — the native mention
+ * path and the routine fan-out see every delivery regardless.
+ */
+export function extractGitHubAmbientEvent(eventType: string, payload: Record<string, unknown>): GitHubAmbientEvent | null {
+  if (eventType !== "issue_comment") return null;
+  if (str(pick(payload, "action")) !== "created") return null;
+  const repository = pick(payload, "repository");
+  const issue = pick(payload, "issue");
+  const comment = pick(payload, "comment");
+  const owner = str(pick(pick(repository, "owner"), "login"));
+  const repo = str(pick(repository, "name"));
+  const issueNumber = num(pick(issue, "number"));
+  if (!owner || !repo || issueNumber === undefined || !comment) return null;
+  const user = pick(comment, "user");
+  const isPrivate = pick(repository, "private");
+  const commentId = num(pick(comment, "id"));
+  return {
+    owner,
+    repo,
+    repositoryFullName: str(pick(repository, "full_name")),
+    repositoryId: num(pick(repository, "id")),
+    repoPrivate: typeof isPrivate === "boolean" ? isPrivate : undefined,
+    installationId: num(pick(pick(payload, "installation"), "id")),
+    issueNumber,
+    issueTitle: str(pick(issue, "title")),
+    isPullRequest: pick(issue, "pull_request") !== undefined,
+    comment: {
+      id: commentId !== undefined ? String(commentId) : undefined,
+      body: str(pick(comment, "body")),
+      authorLogin: str(pick(user, "login")),
+      authorType: str(pick(user, "type")),
+      authorId: num(pick(user, "id")),
+      authorAssociation: str(pick(comment, "author_association")),
+      createdAt: str(pick(comment, "created_at")),
+      repoPrivate: typeof isPrivate === "boolean" ? isPrivate : undefined,
+    },
+  };
+}
+
+// --- the dispatch core (session get-or-create → build → wake → terminal rotate) -------
+
+/** The live supervisor session pointer for a repo, as the deps report it (mirrors
+ *  NotionSupervisorSession). `freshGeneration` = brand-new OR just-rotated. */
+export interface GitHubSupervisorSession {
+  readonly token: string;
+  readonly generation: number;
+  readonly freshGeneration: boolean;
+  /** ISO-8601 of the most recent wake this generation delivered (the registry row's `lastWakeAt`),
+   *  or null on a freshly minted/rotated generation. The lower bound of the since-last-wake catch-up
+   *  read (OPE-1695 (b), brought to this surface by OPE-1726); absent ⇒ no catch-up. */
+  readonly lastWakeAt?: string | null;
+  /** The OUTGOING generation's recorded tail, oldest-first — empty unless this is a fresh
+   *  generation's first wake (OPE-794). */
+  readonly tail: readonly WakeMessageInput[];
+}
+
+/** Deps for {@link handleGitHubSupervisorDispatch} — mirror NotionSupervisorDeps, injected so
+ *  the core is unit-testable over a mock store + a capture `wake`. The eve-typed session STATE
+ *  is built by the wiring (github.ts), not here — this core stays eve-free. */
+export interface GitHubSupervisorDeps {
+  /** Create-or-fetch the live supervisor session for this repo's surfaceKey: mint generation 1
+   *  on first sighting, rotate to generation+1 when {@link shouldRotate} says it aged out, else
+   *  return the current generation. */
+  readonly getOrCreateSession: (surfaceKey: string, owner: string, repo: string, atIso: string) => Promise<GitHubSupervisorSession>;
+  /** Record one wake on the current generation (lastWakeAt/turnCount). Best-effort. */
+  readonly touchSession?: (surfaceKey: string, atIso: string) => Promise<void>;
+  /**
+   * Record this delivered wake onto the LIVE generation's TAIL ring (OPE-794). Injected because the
+   * entry has to be filed under an ORG and a registry key, and this core deliberately holds neither
+   * — the live wiring does. Absent (a unit test) ⇒ nothing is recorded and the dispatch is
+   * unchanged, which is the same posture `touchSession` takes.
+   */
+  readonly recordWake?: (entry: SessionTailWakeRow, token: string, surfaceKey: string) => Promise<void>;
+
+  /** Start/continue the supervisor session under its reserved token, posting the rendered wake.
+   *  The wiring closes over the channel `send` and builds the eve-typed supervisor state.
+   *  `window` is present ONLY on the SINGLE-WINDOW path (dispatch input carried it): the wiring
+   *  then DIVERTS the wake through eve's cross-channel `receive` into the synthetic `unified`
+   *  channel (github.ts). Absent ⇒ this channel's own send, byte-identical. */
+  readonly wake: (input: {
+    token: string;
+    auth: OpenEverywhereGitHubAuth;
+    message: string;
+    context: readonly string[];
+    window?: UnifiedWindowWake;
+  }) => Promise<void>;
+  /**
+   * THE SINCE-LAST-WAKE CATCH-UP, through the ONE shared path every surface takes
+   * (channels/seat-catch-up.ts `seatCatchUp`). Optional so older test doubles keep compiling
+   * (absent ⇒ no catch-up, the pre-OPE-1726 behaviour); fail-soft by construction.
+   */
+  readonly catchUp?: (req: SeatCatchUpRequest) => Promise<SeatCatchUpResult>;
+  /** Clock seam (defaults to the real clock). */
+  readonly now?: () => string;
+}
+
+/** Everything github.ts hands the supervisor dispatch: the wake parts + identity/session facts.
+ *  Built by the route leg AFTER the ambient gate + classifier kept the comment. */
+export interface GitHubSupervisorDispatch {
+  readonly surfaceKey: string;
+  readonly owner: string;
+  readonly repo: string;
+  readonly issueNumber: number;
+  readonly issueTitle?: string;
+  readonly auth: OpenEverywhereGitHubAuth;
+  /**
+   * THE CHAT NON-MEMBER TAINT CARRIAGE input (OPE-494 / OPE-466): the author facts for every
+   * message whose bytes enter this wake's context. GitHub sends one comment per wake, so the route
+   * leg passes exactly one entry — `githubAuthorFacts` over the free `author_association`.
+   *
+   * 🔴 REQUIRED, NOT OPTIONAL, and for the reason `stampNonMemberChatAuth` makes its own `room`
+   * argument required: an optional field lets a new leg silently lose the author question, and a
+   * carriage that is absent looks identical to a carriage that answered "member". A leg with
+   * genuinely nothing to say passes `[]` and says so on purpose.
+   */
+  readonly ingested: readonly IngestedChatMessage[];
+  readonly trigger: GitHubSupervisorWakeInput["trigger"];
+  /**
+   * The domain's admission policy for this surface's context-line slot, resolved by the route leg
+   * off the SAME channel key `deps.catchUp` resolves its own from. See
+   * {@link GitHubSupervisorWakeInput.admit}.
+   * 🔴 REQUIRED, NOT OPTIONAL, and for the reason `ingested` above is: an optional field lets a
+   * SECOND route leg compile with the slot unpoliced, and an absent policy looks identical to a
+   * policy that admitted. The builder's own `admit` stays optional — that keeps this core
+   * config-free for a pure caller — so `required here, optional there` is the whole guard.
+   */
+  readonly admit: SeatAdmissionFn;
+  /** Engagement calibration tier (resolved by the route leg; fail-soft neutral). */
+  readonly engagementTier?: WakeEngagementTier;
+  /** UNIFIED cross-surface grain resolved by the route leg (supervisorGrainFor, fail-soft false) —
+   *  stamps the wake's platform address + P5 disclosure. Unset ⇒ byte-identical per-repo wake. */
+  readonly unified?: boolean;
+  /** SINGLE-WINDOW wake plumbing, minted by the route leg when the grain says `singleWindow`
+   *  (channels/unified-window.ts): the wakeId is rendered into the envelope by this core; the
+   *  whole object is passed through to deps.wake, whose wiring registers the map entry and
+   *  diverts into the unified channel. Unset ⇒ byte-identical. */
+  readonly window?: UnifiedWindowWake;
+  /** SINGLE-WINDOW addressed @mention (the classifier returned `direct`): render the wake as the
+   *  addressed `direct-mention` variant (envelope kept, watch-preamble swapped for the addressed
+   *  one) so the shared-context supervisor answers it. Unset ⇒ the channel-watch ambient wake,
+   *  byte-identical. See {@link GitHubSupervisorWakeInput.directMention}. */
+  readonly directMention?: boolean;
+  /** The seam's enrolment verdict for this issue/PR (github.ts `admission.engagedFollowUp`) — the
+   *  SAME value the `github.dispatched` row promotes to `thread-follow`. Rendered as
+   *  `follow-up="thread-engaged"` on a judged wake. See {@link GitHubSupervisorWakeInput.threadEngaged}. */
+  readonly threadEngaged?: boolean;
+}
+
+/**
+ * Route one kept comment to the repo supervisor: get-or-create the session, build + render the
+ * wake for that generation, and deliver it.
+ *
+ * A DELIVERY failure (the send itself) propagates to the caller's catch. A session that dies at
+ * TURN time does not: nothing here observes it, so the trigger is lost SILENTLY, and no reactive
+ * arm can exist (OPE-174 removed the inert one; channels/session-resume.ts holds the measurement).
+ * The working remedy is PRE-DISPATCH — the live `getOrCreateSession` claims the OPE-599
+ * runtime-change rotation before this call and hands back a session the running eve build can read.
+ */
+export async function handleGitHubSupervisorDispatch(d: GitHubSupervisorDispatch, deps: GitHubSupervisorDeps): Promise<void> {
+  const atIso = deps.now ? deps.now() : new Date().toISOString();
+  const session = await deps.getOrCreateSession(d.surfaceKey, d.owner, d.repo, atIso);
+
+  const doWake = async (token: string, generation: number, tail: readonly WakeMessageInput[], catchUpUnavailable?: string) => {
+    const nw = buildGitHubSupervisorWake({
+      owner: d.owner,
+      repo: d.repo,
+      issueNumber: d.issueNumber,
+      issueTitle: d.issueTitle,
+      admit: d.admit,
+      trigger: d.trigger,
+      engagementTier: d.engagementTier,
+      wakeId: d.window?.wakeId,
+      directMention: d.directMention,
+      threadEngaged: d.threadEngaged,
+      tail,
+      catchUpUnavailable,
+    });
+    const { message, context } = renderWake(nw, deps.now);
+    // OPE-466 CARRIAGE, wired here by OPE-494. The wake renders its envelope in the INGRESS process,
+    // outside any turn, so the taint half of `ingestUntrusted` no-ops and the reading turn would
+    // otherwise run with a CLEAN signal over an outside contributor's bytes. The stamp is the same
+    // host-set, model-unforgeable auth attribute Slack, Discord, Teams and Notion already carry.
+    //
+    // POSITION: inside `doWake`, so BOTH delivery routes get it — this channel's own `send` and the
+    // single-window divert (github.ts hands `deps.wake` the auth for either). The room leg reads the
+    // OPERATOR's trust declaration for the repo; the author leg reads `d.ingested`. On an unmarked
+    // wake the input auth returns BY REFERENCE, so no existing golden moves.
+    const auth = stampNonMemberChatAuth(d.auth, d.ingested, { surfaceKey: d.surfaceKey });
+    await deps.wake({ token, auth, message, context: context ?? [], window: d.window });
+  };
+
+  // A wake failure PROPAGATES to the caller's catch. (OPE-174 removed a terminal-session-death
+  // force-rotate branch here: it could never fire — a conversation-mode session PARKS at eve's
+  // token bound rather than failing, and a turn-time error cannot reject the awaited enqueue
+  // anyway. The reachable handler is core's agent/channels/session-park.ts.)
+  // 🔴 EVERY WAKE READS THE CONVERSATION SINCE THE SEAT LAST LOOKED (OPE-1695 (b), brought to GitHub
+  // by OPE-1726). A FRESH generation renders its carried tail, as it always did; an ONGOING
+  // generation reads the timeline comments this issue/PR collected since its own `lastWakeAt`,
+  // through the ONE shared catch-up path — same bounds, same admission policy, same cap as Slack's.
+  // FAIL-SOFT: the shared path never throws, and an unregistered fetch comes back as the UNAVAILABLE
+  // note rather than as a silent empty context.
+  const catchUp =
+    session.freshGeneration || !deps.catchUp
+      ? undefined
+      : await deps.catchUp({
+          container: `${d.owner}/${d.repo}#${d.issueNumber}`,
+          sinceMs: seatCatchUpSinceMs(session.lastWakeAt, Date.parse(atIso) || Date.now(), GITHUB_CATCH_UP_REACHBACK_HOURS),
+          untilMs: Date.parse(d.trigger.sentAt) || Date.parse(atIso) || Date.now(),
+          excludeId: d.trigger.id,
+          channelKey: d.surfaceKey,
+        });
+  await doWake(session.token, session.generation, session.freshGeneration ? session.tail : (catchUp?.messages ?? []), catchUp?.unavailable);
+  if (deps.touchSession) await deps.touchSession(d.surfaceKey, atIso);
+  if (deps.recordWake) {
+    // AFTER the wake landed, and only the TRIGGER — never the backscroll rendered beside it. That is
+    // what stops a tail inheriting a tail (channels/session-tail.ts).
+    await deps.recordWake(
+      {
+        kind: "wake",
+        at: atIso,
+        from: "human",
+        trust: d.trigger.trust,
+        // THE AUTHOR GRAIN (OPE-1747) — `d.ingested[0]` is the TRIGGER's own facts: GitHub sends one
+        // comment per wake, so the route leg passes exactly one entry (see `ingested`'s own header),
+        // and `stampNonMemberChatAuth` above joins over that same entry. Resolved through the one core
+        // road, so this row and the join cannot disagree. A leg that passed `[]` says so on purpose, and
+        // the row then records `refuted: false` — the SAME answer the live wake acted on, not the
+        // UNKNOWN an absent field means. UNKNOWN is reserved for a row persisted before this field
+        // existed: recording it here would withhold, in the next generation, a body this wake delivered.
+        ...tailAuthorGrain(d.ingested[0] ?? { trust: d.trigger.trust }),
+        author: d.trigger.authorLogin ?? "unknown",
+        ...(d.trigger.authorLogin ? { authorId: d.trigger.authorLogin } : {}),
+        id: d.trigger.id,
+        platform: "github",
+        container: d.surfaceKey,
+        threadRoot: `#${d.issueNumber}`,
+        text: d.trigger.text,
+      },
+      session.token,
+      d.surfaceKey,
+    );
+  }
+}
+
+// Re-export shouldRotate so the live wiring (github.ts) drives get-or-create/rotate with the
+// SAME pure policy Slack/Notion use, without importing slack-events itself.
+export { shouldRotate };