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

package/agent/channels/github-identity.ts

@@ -0,0 +1,376 @@
+// Pure GitHub→OpenEverywhere identity capture. The GitHub channel (github.ts) calls
+// these from its `onComment` hook to stow RAW GitHub facts (repo owner/name + privacy +
+// conversation anchor + actor) into the session auth context's `attributes`. The
+// INTERPRETATION of those facts into visibility/trust lives here too (githubVisibility/
+// githubTrust) — kept beside the capture so the mapper in agent/identity/binding.ts
+// (bindGitHub) just calls them, exactly as Slack/Teams split capture from
+// interpretation. This file imports no eve types, so it's trivially unit-testable.
+//
+// The two security-critical decisions are ONE tested place each and both FAIL CLOSED:
+//   - githubVisibility: "is this a world-readable (public-repo) surface whose learnings
+//     may flow up to shared memory?" — only an explicit public repo yields `public`.
+//   - githubTrust: "is this surface positively inside the org trust boundary?" — only a
+//     PRIVATE repo touched by an org OWNER/MEMBER yields `internal`; everything else
+//     (public repos, outside collaborators, missing signals) → no verdict, so bindFrom
+//     binds it `external`.
+//
+// GitHub has no 1:1 DM surface (every issue/PR/review thread is a shared conversation on
+// a repo), so mode is always "channel" — bindGitHub inlines that, no helper needed.
+//
+// The IDENTITY MAPPER (bindGitHub) lives here too (moved out of core identity/binding.ts in
+// OPE-114 stage 4, mirroring the notion bundle): registerGithubProvider() registers it via the
+// registerIdentityMapper seam. The only imports are TYPE-ONLY barrel contracts (erased at
+// compile), so the file stays trivially unit-testable.
+
+import type { BindableContext, IdentityMapper, IngestedChatMessage, RawIdentity } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** Structural match for eve's SessionAuthContext (attributes + principal). */
+export interface OpenEverywhereGitHubAuth {
+  readonly authenticator: string;
+  readonly principalId: string;
+  readonly principalType: string;
+  readonly attributes: Record<string, string>;
+}
+
+export interface GitHubIdentityInput {
+  /** Repo owner (org/user login) — becomes the OpenEverywhere `workspace`, the org boundary. */
+  readonly owner: string;
+  /** Repo name — becomes the OpenEverywhere `surface` (the silo grain: one repo, many issues/PRs). */
+  readonly repo: string;
+  /** "owner/name" — carried for reference/logging (not a partition key on its own). */
+  readonly repositoryFullName?: string;
+  readonly repositoryId?: number;
+  /** Repo visibility, when positively known (off ctx.repository.private); absent → fail closed. */
+  readonly isPrivate?: boolean;
+  /** "issue" | "pull_request" | "review_thread" — picks the post-back anchor (issue vs PR number). */
+  readonly conversationKind?: string;
+  /** Issue number for the conversation, when it's an issue thread (post-back anchor). */
+  readonly issueNumber?: number;
+  /** PR number for the conversation, when it's a PR/review thread (post-back anchor). */
+  readonly pullRequestNumber?: number;
+  /**
+   * The ROOT comment id of the review thread this turn arrived in (OPE-958) — present only on a
+   * `review_thread` conversation. It is the id `read_thread` fetches the thread by, and the binding
+   * is the only place it can ride: `ReadAdapter.wakeAddress` is pure and synchronous and reads the
+   * binding, while eve carries the root on its own channel STATE, which the mapper never sees.
+   *
+   * GitHub sends `in_reply_to_id` on a REPLY and omits it on the comment that OPENED the thread, so
+   * the root is `in_reply_to_id ?? comment.id` and github.ts derives it there, once.
+   */
+  readonly reviewThreadRootCommentId?: number;
+  /** GitHub App installation id (needed to mint tokens for proactive post-back). */
+  readonly installationId?: number;
+  /** The acting GitHub user (comment author) — the OpenEverywhere principal. */
+  readonly actorLogin: string;
+  readonly actorId?: number;
+  /** "User" | "Bot" | "Organization" — a Bot actor maps to a `service` principal. */
+  readonly actorType?: string;
+  /**
+   * The actor's relationship to the repo, as GitHub reports it on the comment payload
+   * (`author_association`): OWNER | MEMBER | COLLABORATOR | CONTRIBUTOR |
+   * FIRST_TIME_CONTRIBUTOR | FIRST_TIMER | MANNEQUIN | NONE. A verifiable trust signal.
+   */
+  readonly authorAssociation?: string;
+}
+
+/** Build the auth context OpenEverywhere dispatches with — raw facts as string attributes. */
+export function buildGitHubAuth(input: GitHubIdentityInput): OpenEverywhereGitHubAuth {
+  const attributes: Record<string, string> = {
+    owner: input.owner,
+    repo: input.repo,
+    user_login: input.actorLogin,
+  };
+  if (input.repositoryFullName) attributes.repository = input.repositoryFullName;
+  if (typeof input.repositoryId === "number") attributes.repository_id = String(input.repositoryId);
+  if (typeof input.isPrivate === "boolean") attributes.repo_private = String(input.isPrivate);
+  if (input.conversationKind) attributes.conversation_kind = input.conversationKind;
+  if (typeof input.issueNumber === "number") attributes.issue_number = String(input.issueNumber);
+  if (typeof input.pullRequestNumber === "number") attributes.pull_request_number = String(input.pullRequestNumber);
+  if (typeof input.reviewThreadRootCommentId === "number") attributes.review_thread_root_comment_id = String(input.reviewThreadRootCommentId);
+  if (typeof input.installationId === "number") attributes.installation_id = String(input.installationId);
+  if (typeof input.actorId === "number") attributes.user_id = String(input.actorId);
+  if (input.actorType) attributes.user_type = input.actorType;
+  if (input.authorAssociation) attributes.author_association = input.authorAssociation;
+  return {
+    authenticator: "github",
+    principalId: input.actorLogin,
+    principalType: input.actorType === "Bot" ? "service" : "github-user",
+    attributes,
+  };
+}
+
+/**
+ * A comment @mentions the bot and should wake a turn. Faithfully mirrors eve's
+ * internal gate (shouldDispatchGitHubComment: isIgnoredGitHubComment +
+ * extractGitHubCommentTrigger), which is NOT on eve's public export surface — so we
+ * replicate it here (small, deterministic, and unit-tested) rather than reach into a
+ * package-internal path. Kept byte-consistent with eve because the channel's message
+ * layer still strips the mention token via eve's own extractGitHubCommentTrigger; a
+ * divergent gate here would fire turns eve then can't strip. FAIL CLOSED: no botName,
+ * a bot author, the bot's own comments, or eve's marker → no wake.
+ */
+export function githubBotMentioned(
+  body: string | undefined,
+  botName: string | undefined,
+  author: { readonly login?: string; readonly type?: string } | undefined,
+): boolean {
+  const name = botName?.trim();
+  if (!name || !body) return false;
+  if (body.includes("<!-- eve:github:")) return false; // eve's own comment marker — never self-trigger
+  if (author?.type === "Bot") return false; // ignore bot actors (loop guard)
+  if (author?.login && author.login.toLowerCase() === `${name}[bot]`.toLowerCase()) return false; // the bot itself
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  // "@name" not followed by a word char — matches eve's `@${name}(?=$|[^A-Za-z0-9_-])`.
+  return new RegExp(`@${escaped}(?=$|[^A-Za-z0-9_-])`, "iu").test(body);
+}
+
+/**
+ * GitHub repo privacy → visibility. FAIL CLOSED, mirroring slackVisibility/
+ * linearVisibility: only an explicitly PUBLIC repo (`repo_private="false"`) yields
+ * `public`; a private repo (`"true"`) or an unknown signal → `private`, so an
+ * under-identified session or a private repo never writes its learnings up to shared
+ * (workspace) memory. A public repo's issue/PR threads are world-readable, so treating
+ * them as a public surface (learnings may flow to the workspace brain across the org's
+ * repos) is correct; anything we can't confirm public stays surface-tier private.
+ */
+export function githubVisibility(repoPrivate: string | undefined): Visibility {
+  if (repoPrivate === "false") return "public";
+  return "private"; // "true" or unknown → fail closed
+}
+
+/**
+ * GitHub actor + repo privacy → trust (the shared-memory gate). FAIL CLOSED — only a
+ * POSITIVE in-boundary fact yields a verdict:
+ *   - A PRIVATE repo (only org members + invited collaborators can see it) touched by an
+ *     org OWNER or MEMBER → `internal`. OWNER/MEMBER are GitHub's strong "part of the org
+ *     that owns this repo" signals (`author_association`); on a private repo that means an
+ *     insider acting inside the boundary, so shared/org memory is safe to read.
+ *   - ANYTHING ELSE → `undefined`, so bindFrom FAILS CLOSED to `external`:
+ *       · a PUBLIC repo — world-readable, anyone (external contributors) can comment, so it
+ *         must never light up the org brain regardless of who this particular actor is;
+ *       · a private repo touched by a COLLABORATOR (may be an OUTSIDE collaborator),
+ *         CONTRIBUTOR, first-timer, mannequin, NONE, or a missing/unknown association;
+ *       · a missing repo-privacy signal.
+ * The operator can still vouch for a deployment with OE_TRUST=internal — the same layer
+ * Slack-DM/Teams/Discord/Linear use. An ambiguous GitHub event must never reach
+ * the shared org brain. (Per-repo collaborator-membership enrichment — GET
+ * /repos/{o}/{r}/collaborators/{u}/permission — is the future layer-2 gate that could
+ * promote a verified internal collaborator; until then, only OWNER/MEMBER on a private
+ * repo is trusted.)
+ */
+export function githubTrust(repoPrivate: string | undefined, authorAssociation: string | undefined): Trust | undefined {
+  if (repoPrivate !== "true") return undefined; // public / unknown repo → no verdict (binds external)
+  if (authorAssociation === "OWNER" || authorAssociation === "MEMBER") return "internal";
+  return undefined; // collaborator/contributor/outside/unknown on a private repo → fail closed
+}
+
+/** Local copies of the binding's unions (kept eve-free + import-cycle-free). */
+type Visibility = "public" | "private";
+type Trust = "internal" | "external";
+
+// --- the EXTERNAL-AUTHOR grain (OPE-533) --------------------------------------------------------
+//
+// THE EVIDENCE IS FREE. GitHub reports `author_association` on every `issue_comment` payload, and
+// {@link buildGitHubAuth} already stows it. The author grain needs no new call and no new
+// installation permission — the org-membership probe (`orgs/{org}/members/{user}`) would need the
+// "Members" permission, which every installed org would have to re-approve.
+//
+// 🔴 THE SET IS A RULING, NOT AN INFERENCE (Tommy, 2026-08-14). INTERNAL is the three values that
+// each carry a DELIBERATE ACCESS GRANT on the repo: `OWNER`, `MEMBER`, `COLLABORATOR`. Every other
+// value is EXCLUDED. Tommy verbatim: "contributor shouldn't be trusted" — a past merged PR is not an
+// access grant. `MANNEQUIN` is an import placeholder with no live person behind it, so it is
+// excluded as hygiene.
+//
+// 🔴 THIS IS A DIFFERENT QUESTION FROM {@link githubTrust}, AND THE TWO MUST NOT BE MERGED.
+// `githubTrust` asks "may this session read the shared org brain?" and fails CLOSED, so it demands
+// a PRIVATE repo AND an OWNER/MEMBER author. This asks "may this person's bytes task the agent?"
+// and fails OPEN. A COLLABORATOR is internal here and still not trusted there, which is correct:
+// denying service is a different act from opening the org's memory.
+
+/** `author_association` values that carry a deliberate access grant on the repo — the INTERNAL set. */
+export const GITHUB_INTERNAL_ASSOCIATIONS: readonly string[] = ["OWNER", "MEMBER", "COLLABORATOR"];
+
+/** `author_association` values that carry NO access grant — the EXCLUDED (external) set. This is
+ *  GitHub's whole documented enum minus {@link GITHUB_INTERNAL_ASSOCIATIONS}, written out rather
+ *  than derived by negation: see {@link githubAssociationRefutes} for why the difference matters. */
+export const GITHUB_EXTERNAL_ASSOCIATIONS: readonly string[] = [
+  "CONTRIBUTOR",
+  "FIRST_TIME_CONTRIBUTOR",
+  "FIRST_TIMER",
+  "NONE",
+  "MANNEQUIN",
+];
+
+/**
+ * Does this `author_association` POSITIVELY refute the author's membership?
+ *
+ * 🔴 IT MATCHES THE EXCLUDED SET, IT DOES NOT NEGATE THE INTERNAL ONE, and the difference is the
+ * whole fail-open posture. An ABSENT association (a payload shape GitHub changed, a synthesised
+ * event) and an UNRECOGNISED one (a value GitHub adds later) both answer `false` — "not refuted",
+ * which is what `IngestedChatMessage.refuted` means by absence of evidence. Negating the internal
+ * set would read every unknown as external and take the agent off the air on a payload change.
+ *
+ * Case-sensitive on purpose: GitHub sends these values upper-case, and accepting a lower-case
+ * variant would be inventing a second spelling of a vendor enum.
+ */
+export function githubAssociationRefutes(authorAssociation: string | undefined): boolean {
+  return authorAssociation !== undefined && GITHUB_EXTERNAL_ASSOCIATIONS.includes(authorAssociation);
+}
+
+/**
+ * The author grain's evidence for one GitHub comment, in the core's own vocabulary
+ * (`IngestedChatMessage`) so access/external-policy.ts answers the exclusion question — this bundle
+ * never re-derives it.
+ *
+ * A `Bot` actor grades as the machine floor `relay` and is therefore NEVER excluded, which is the
+ * core's own ruling (access/taint-signal.ts `nonMemberChatTrust`): a bot is below peer standing but
+ * it is not a person outside the organisation, and withholding every app's comments would be an
+ * outage. Stating it as the tier rather than as a local `if` keeps ONE place deciding.
+ *
+ * A human author carries `refuted` only when {@link githubAssociationRefutes} says so. `trust` is
+ * left ABSENT for a human on purpose: this runs before the per-wake trust resolution, so naming a
+ * tier here would be a guess, and the refutation leg needs no tier.
+ */
+export function githubAuthorFacts(input: {
+  readonly authorAssociation?: string;
+  readonly actorType?: string;
+}): IngestedChatMessage {
+  if (input.actorType === "Bot") return { trust: "relay" };
+  return githubAssociationRefutes(input.authorAssociation) ? { refuted: true } : {};
+}
+
+// --- the identity MAPPER (moved out of core identity/binding.ts in OPE-114 stage 4) ---------
+// A GitHub session runs on an ISSUE / PR / review thread inside a repo, which lives under an owner
+// (org or user). The silo grain is the REPO — the persistent container that groups all of a repo's
+// issues and PRs (the Slack-channel analog); the issue/PR number is the post-back ANCHOR, not the
+// partition key. So: workspace = owner (the org boundary), surface = repo, mode = channel (GitHub
+// has no 1:1 DM surface). Raw facts are stowed by buildGitHubAuth above; visibility/trust
+// interpretation lives here too (githubVisibility/githubTrust) — the one tested place. Trust FAILS
+// CLOSED: githubTrust returns a verdict only on a POSITIVE fact (a private repo touched by an org
+// OWNER/MEMBER → internal), so bindFrom binds a public repo or an outside/unknown actor `external`
+// unless the operator vouches with OE_TRUST=internal.
+//
+// The two attribute helpers are LOCAL COPIES of core binding.ts's module-private probes (attr /
+// authPrincipalId) — deliberately not barrel ports (mirrors the notion bundle): they are three-line
+// structural reads over the public BindableContext shape; the barrel exposes the CONTRACT
+// (BindableContext / RawIdentity / IdentityMapper), not core's private conveniences.
+
+type AuthAttrs = Readonly<Record<string, string | readonly string[]>> | undefined;
+
+function githubAuthOf(ctx: BindableContext): { attributes?: AuthAttrs; principalId?: string } | null {
+  return ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? null;
+}
+
+function githubAttr(a: AuthAttrs, keys: readonly string[]): string | undefined {
+  if (!a) return undefined;
+  for (const k of keys) {
+    const v = a[k];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (Array.isArray(v) && typeof v[0] === "string" && v[0].length > 0) return v[0];
+  }
+  return undefined;
+}
+
+function githubAuthPrincipalId(ctx: BindableContext): string | undefined {
+  const pid = githubAuthOf(ctx)?.principalId;
+  return pid && pid.length > 0 ? pid : undefined;
+}
+
+/**
+ * The CONVERSATION key the stop registry keys a GitHub turn by (OPE-898) — `owner/repo#number`.
+ *
+ * ONE derivation, used by BOTH sides of the affordance: {@link bindGitHub} writes it onto the anchor
+ * row at turn start, and the stop-comment leg (channels/github-stop.ts) rebuilds it from the webhook
+ * that carries the directive. Two spellings of this key would make the whole arm silently miss.
+ *
+ * It is NOT a surface key and never becomes one — the GitHub surface grain is the REPO, and this
+ * value names one issue or PR inside it. Returns undefined on any missing part: a partial key would
+ * collide across repos.
+ */
+export function githubConversationKey(owner: string | undefined, repo: string | undefined, number: number | undefined): string | undefined {
+  return owner && repo && Number.isFinite(number) ? `${owner}/${repo}#${number}` : undefined;
+}
+
+/**
+ * The ROOT comment id of the review thread this turn arrived in, or `undefined` (OPE-958). The read
+ * side of {@link GitHubIdentityInput.reviewThreadRootCommentId} — this file owns the attribute
+ * spelling on BOTH sides, so a rename cannot leave the reader looking for a key nobody writes.
+ *
+ * It reads the AUTH ATTRIBUTES rather than the composed binding on purpose. `RawIdentity.target` is
+ * eve's `GitHubReceiveTarget` and throws on a member it does not know, so the root cannot ride
+ * there, and no other binding field names a comment.
+ *
+ * Returns the id as a STRING of digits, which is what `ReadAdapter.readThread` takes as its thread
+ * id. A non-numeric value is treated as absent: a review thread id that is not a comment id would
+ * fetch nothing, and refusing honestly beats reading an empty thread.
+ */
+export function githubReviewThreadRoot(ctx: BindableContext): string | undefined {
+  const raw = githubAttr(githubAuthOf(ctx)?.attributes, ["review_thread_root_comment_id", "reviewThreadRootCommentId"]);
+  return raw !== undefined && /^\d+$/u.test(raw) ? raw : undefined;
+}
+
+export const bindGitHub: IdentityMapper = (ctx): RawIdentity => {
+  const a = githubAuthOf(ctx)?.attributes;
+  const owner = githubAttr(a, ["owner"]);
+  const repo = githubAttr(a, ["repo"]);
+  const repoPrivate = githubAttr(a, ["repo_private", "repoPrivate"]);
+  const conversationKind = githubAttr(a, ["conversation_kind", "conversationKind"]);
+  const issueNumber = githubAttr(a, ["issue_number", "issueNumber"]);
+  const pullRequestNumber = githubAttr(a, ["pull_request_number", "pullRequestNumber"]);
+  const installationId = githubAttr(a, ["installation_id", "installationId"]);
+  // Proactive post-back uses eve's GitHubReceiveTarget: { owner, repo, and EXACTLY ONE of
+  // issueNumber | pullRequestNumber } (supplying both throws). Pick the PR number for a
+  // pull_request/review_thread conversation, else the issue number. Only emitted when we
+  // have owner + repo + a usable anchor number.
+  const isPr = conversationKind === "pull_request" || conversationKind === "review_thread";
+  const anchor =
+    isPr && pullRequestNumber
+      ? { pullRequestNumber: Number(pullRequestNumber) }
+      : issueNumber
+        ? { issueNumber: Number(issueNumber) }
+        : pullRequestNumber
+          ? { pullRequestNumber: Number(pullRequestNumber) }
+          : undefined;
+  return {
+    workspace: owner,
+    surface: repo,
+    mode: "channel", // GitHub has no DM analog — every issue/PR/review thread is shared
+    visibility: githubVisibility(repoPrivate),
+    trust: githubTrust(repoPrivate, githubAttr(a, ["author_association", "authorAssociation"])),
+    principalId: githubAuthPrincipalId(ctx) ?? githubAttr(a, ["user_login", "userLogin", "user_id", "userId"]),
+    // OPE-811: `installationId` rides the post-back target so the mid-turn `reply` arm mints its
+    // token against THIS wake's own installation instead of falling back to the owner→installation
+    // map. Absent when the webhook carried none — the arm's map lookup is the fallback, never a guess.
+    target: owner && repo && anchor ? { owner, repo, ...anchor, ...(installationId ? { installationId: Number(installationId) } : {}) } : undefined,
+    // THE STOP REGISTRY'S ADDRESS FOR THIS TURN (OPE-898). A GitHub conversation is ONE issue or PR
+    // thread, so that is what a stop directive posted into the thread can name. It cannot ride
+    // `target`: that object is eve's `GitHubReceiveTarget` and it throws on an unexpected member.
+    //
+    // GitHub sends NO webhook for a reaction (verified against the event list, 2026-08-20), so the
+    // trigger on this surface is a bare `stop` comment read at the ingress — see
+    // channels/github-stop.ts. The key it resolves by is this one.
+    ...(anchor
+      ? {
+          anchorChannelId: githubConversationKey(
+            owner,
+            repo,
+            "pullRequestNumber" in anchor ? anchor.pullRequestNumber : anchor.issueNumber,
+          ),
+          // THE ENGAGEMENT REGISTRY'S ADDRESS FOR THIS TURN (OPE-1501) — the SAME container key, and
+          // deliberately the same derivation rather than a second spelling of it. `stand_down` marks
+          // `binding.engagementKey ?? binding.threadTs`, and GitHub carries no `threadTs`, so
+          // without this field the verb found no anchor and refused on every GitHub turn.
+          //
+          // It is a SEPARATE field from `anchorChannelId` because the two answer different
+          // questions — which running turn a stop directive cancels, and which conversation row the
+          // agent was asked to stop following — and `channels/github-engagement.ts` reads this one
+          // back through `githubEngagementAnchor`, which calls the very same function.
+          engagementKey: githubConversationKey(
+            owner,
+            repo,
+            "pullRequestNumber" in anchor ? anchor.pullRequestNumber : anchor.issueNumber,
+          ),
+        }
+      : {}),
+  };
+};

package/agent/channels/github-installations.ts

@@ -0,0 +1,152 @@
+// The GitHub App's INSTALLATION leg — the eve-free, tested half of "an org installing the App
+// registers itself" (OPE-118 GitHub §3; github.ts is the thin wiring, mirroring github-supervisor.ts).
+//
+// GitHub's App-level webhook (ONE url + ONE secret, fanning in every installation of the App across
+// every account) delivers:
+//   • `installation` — actions `created`, `deleted`, `suspend`, `unsuspend`, `new_permissions_accepted`
+//   • `installation_repositories` — actions `added`, `removed` (the repo-scope change)
+// Verified against docs.github.com/en/webhooks/webhook-events-and-payloads (2026-07). We map those
+// onto exactly two effects, LEARN and REVOKE:
+//   LEARN   ← created / unsuspend / new_permissions_accepted / added / removed
+//   REVOKE  ← deleted / suspend
+// `suspend` revokes because a suspended installation's tokens are refused by GitHub — keeping the
+// row would advertise an installation that cannot mint, and `unsuspend` re-learns it. The two
+// metadata-only actions (`new_permissions_accepted`, and both `installation_repositories` actions)
+// re-LEARN rather than no-op so `repository_selection` on the row can't drift from reality.
+//
+// SIGNATURE: this module never verifies anything — it runs INSIDE the route, AFTER the one
+// existing `gateGithubDelivery` HMAC gate (GITHUB_WEBHOOK_SECRET) that already fail-closed 401s
+// every unverified delivery for the whole route. There is deliberately no second verification path.
+//
+// AUDIT: install/uninstall is a surface-lifecycle fact, so it takes the cross-platform `surface.*`
+// action namespace (the same one slack-front/teams-front's wake_failed/wake_dropped rows use),
+// not a github-only verb — an operator asking "who installed us, and when?" wants one query.
+
+/** One installation delivery, normalized. `effect` is the whole decision; everything else is the
+ *  row/audit payload. */
+export interface GitHubInstallationEvent {
+  readonly effect: "learn" | "revoke";
+  /** The webhook's `action` — carried verbatim into the audit row (why the effect happened). */
+  readonly action: string;
+  /** `installation.account.login` — the SCM map's key. */
+  readonly owner: string;
+  readonly installationId: string;
+  /** `installation.account.type` — "Organization" | "User". */
+  readonly accountType?: string;
+  /** `installation.repository_selection` — "all" | "selected". */
+  readonly repositorySelection?: string;
+  /** How many repos the delivery named, when it named any (diagnostics in the audit row only —
+   *  the repo LIST is never stored; the App's own grant is the source of truth). */
+  readonly repositoryCount?: number;
+}
+
+const LEARN_ACTIONS = new Set(["created", "unsuspend", "new_permissions_accepted", "added", "removed"]);
+const REVOKE_ACTIONS = new Set(["deleted", "suspend"]);
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/** GitHub sends `installation.id` as a NUMBER; the mint API wants a path segment. Accept both
+ *  spellings and reject anything else (never coerce an object/array into "[object Object]"). */
+function idOf(v: unknown): string | undefined {
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  return str(v);
+}
+
+function countOf(v: unknown): number | undefined {
+  return Array.isArray(v) ? v.length : undefined;
+}
+
+/**
+ * Normalize one webhook delivery into a {@link GitHubInstallationEvent}, or null when it isn't an
+ * installation delivery we act on. PURE — no I/O, so every branch is unit-tested.
+ *
+ * FAIL-CLOSED on an unusable payload: an unknown action, a missing `installation.id`, or a missing
+ * `installation.account.login` all return null (nothing learned, nothing revoked) rather than
+ * writing a half-formed row. An installation with no resolvable owner is unroutable anyway.
+ */
+export function extractGitHubInstallationEvent(eventType: string, payload: Record<string, unknown>): GitHubInstallationEvent | null {
+  if (eventType !== "installation" && eventType !== "installation_repositories") return null;
+  const action = str(payload["action"]);
+  if (!action) return null;
+  const effect = LEARN_ACTIONS.has(action) ? "learn" : REVOKE_ACTIONS.has(action) ? "revoke" : undefined;
+  if (!effect) return null;
+
+  const installation = payload["installation"];
+  if (typeof installation !== "object" || installation === null) return null;
+  const inst = installation as Record<string, unknown>;
+  const installationId = idOf(inst["id"]);
+  if (!installationId) return null;
+
+  const account = typeof inst["account"] === "object" && inst["account"] !== null ? (inst["account"] as Record<string, unknown>) : undefined;
+  const owner = str(account?.["login"]);
+  if (!owner) return null;
+
+  // `repository_selection` sits on the installation for `installation`, and is re-sent at the TOP
+  // level of an `installation_repositories` delivery (that event's whole point is the change) —
+  // prefer the top-level value so a scope change is reflected, not the pre-change installation copy.
+  const repositorySelection = str(payload["repository_selection"]) ?? str(inst["repository_selection"]);
+  const repositoryCount =
+    countOf(payload["repositories"]) ?? countOf(payload["repositories_added"]) ?? countOf(payload["repositories_removed"]);
+
+  return {
+    effect,
+    action,
+    owner,
+    installationId,
+    ...(str(account?.["type"]) ? { accountType: str(account?.["type"])! } : {}),
+    ...(repositorySelection ? { repositorySelection } : {}),
+    ...(repositoryCount !== undefined ? { repositoryCount } : {}),
+  };
+}
+
+/** The side-effecting seams, injected so the dispatch core is testable without a store or a clock. */
+export interface GitHubInstallationDeps {
+  readonly record: (rec: {
+    owner: string;
+    installationId: string;
+    accountType?: string;
+    repositorySelection?: string;
+    updatedAt: string;
+  }) => Promise<void>;
+  readonly forget: (owner: string) => Promise<boolean>;
+  readonly audit: (action: string, detail: Record<string, unknown>, workspace: string) => Promise<void>;
+  readonly now?: () => string;
+  readonly log?: (msg: string) => void;
+}
+
+/**
+ * Apply one normalized delivery: persist-or-clear the owner→installation entry, then audit it.
+ *
+ * ORDER IS DELIBERATE — the durable write happens FIRST and its failure propagates (the route's
+ * catch logs it), so we never audit an install we didn't actually record. The audit row is written
+ * after, best-effort at the appendAudit layer.
+ */
+export async function handleGitHubInstallationDelivery(ev: GitHubInstallationEvent, deps: GitHubInstallationDeps): Promise<void> {
+  const at = deps.now ? deps.now() : new Date().toISOString();
+  const detail: Record<string, unknown> = {
+    action: ev.action,
+    installationId: ev.installationId,
+    ...(ev.accountType ? { accountType: ev.accountType } : {}),
+    ...(ev.repositorySelection ? { repositorySelection: ev.repositorySelection } : {}),
+    ...(ev.repositoryCount !== undefined ? { repositoryCount: ev.repositoryCount } : {}),
+  };
+
+  if (ev.effect === "revoke") {
+    const removed = await deps.forget(ev.owner);
+    deps.log?.(`installation ${ev.action} for ${ev.owner} — ${removed ? "discovered entry cleared" : "no discovered entry to clear"}`);
+    await deps.audit("surface.app_uninstalled", { ...detail, removed }, ev.owner);
+    return;
+  }
+
+  await deps.record({
+    owner: ev.owner,
+    installationId: ev.installationId,
+    ...(ev.accountType ? { accountType: ev.accountType } : {}),
+    ...(ev.repositorySelection ? { repositorySelection: ev.repositorySelection } : {}),
+    updatedAt: at,
+  });
+  deps.log?.(`installation ${ev.action} for ${ev.owner} → installation ${ev.installationId} registered (no env edit needed)`);
+  await deps.audit("surface.app_installed", detail, ev.owner);
+}

package/agent/channels/github-message-ops.ts

@@ -0,0 +1,62 @@
+// github-message-ops — GitHub's SurfaceMessageOps (OPE-899): the ancillary message ops core
+// features dispatch through channels/surface-message-ops.ts. Before this file, GitHub registered
+// none, so the stop acknowledgement (turn-anchor.ts's `postSurfaceText`) resolved nothing on a
+// GitHub turn — the stop control worked (github-stop.ts, the bare `stop` comment), it was just
+// invisible: a person who pressed it saw the agent go quiet and read nothing.
+//
+//   - postText    → the SAME issue/PR-timeline comment POST the reply spine uses
+//                   (github-post-arm.ts's `liveGitHubPost`, exported for this file — one mint/fetch
+//                   implementation, never a second copy of it).
+//   - editMessage → the SAME comment PATCH the `edit_reply` verb uses (`liveGitHubEditComment`).
+//   - NO `postFiles` (OPE-899's registry ruling): GitHub has no API for attaching a file to a
+//     comment — web upload only. The optional tier exists exactly for this shape.
+//   - NO `setReaction`: GitHub's reaction set is the fixed eight (+1, -1, laugh, confused, heart,
+//     hooray, rocket, eyes) — there is no raised hand. The bare `stop` comment (github-stop.ts) IS
+//     GitHub's stop affordance; there is no ✋ glyph to place beside it, so this module offers no
+//     `setReaction` rather than faking one against the wrong emoji.
+//
+// `channelId` IS THE CONVERSATION KEY `owner/repo#number`, not a GitHub-specific pair invented
+// here. `turn-anchor.ts`'s `turnAnchorAddress` reads it off `binding.anchorChannelId`, which
+// `bindGitHub` (github-identity.ts) mints through `githubConversationKey` — the SAME key
+// github-read.ts's `parseGithubContainer` already parses for the read adapter's container id. This
+// file reuses that parser rather than writing a second one: two derivations of the same address
+// would be exactly the "silently miss" trap github-identity.ts's own header warns about.
+//
+// `messageId` on `editMessage` is the COMMENT id `postText`/`liveGitHubPost` returned — GitHub's
+// comment ids are unique across the whole repo, so `editMessage` needs only the owner/repo half of
+// the parsed container, never the issue number.
+//
+// NO THREADING ON `postText`. GitHub's issue/PR-timeline comment stream is flat — there is no
+// "reply to this specific comment" primitive on the endpoint `liveGitHubPost` posts through (that
+// exists only for PR review comments, a different family this registry does not address) — so
+// `opts?.replyToMessageId` is accepted (the interface's contract) and ignored, exactly like a
+// top-level Slack post with no thread.
+
+import type { SurfaceMessageOps } from "@open-everywhere/core/agent/adapter-api.js";
+import { liveGitHubEditComment, liveGitHubPost } from "./github-post-arm.js";
+import { parseGithubContainer } from "./github-read.js";
+
+/** Parse the `owner/repo#number` container id, or throw the same honest, naming refusal every
+ *  other surface-message-ops call gives on a malformed address — never a guessed target. */
+function requireContainer(channelId: string): { readonly owner: string; readonly repo: string; readonly repoFull: string; readonly number: number } {
+  const target = parseGithubContainer(channelId);
+  if (!target) throw new Error(`GitHub surface message ops: "${channelId}" is not a conversation id (expected "owner/repo#number").`);
+  return target;
+}
+
+export const githubMessageOps: SurfaceMessageOps = {
+  platform: "github",
+
+  /** Post to the issue/PR-timeline comment stream. `opts?.replyToMessageId` is accepted and
+   *  ignored — see the header's "NO THREADING" note. */
+  async postText(channelId, text) {
+    const { owner, repo, number } = requireContainer(channelId);
+    return liveGitHubPost({ platform: "github", owner, repo, issueNumber: number }, text);
+  },
+
+  /** PATCH the comment's body in place — the same edit `edit_reply` performs on the reply spine. */
+  async editMessage(channelId, messageId, text) {
+    const { repoFull } = requireContainer(channelId);
+    await liveGitHubEditComment(repoFull, messageId, text);
+  },
+};

package/agent/channels/github-origin-codec.ts

@@ -0,0 +1,42 @@
+// The GitHub UnifiedWakeOrigin codec — MOVED VERBATIM out of core's
+// channels/wake-origin-codecs.ts (OPE-114 stage 4). STORED-DATA COMPATIBILITY IS THE CONTRACT:
+// a GitHub origin is JSON-serialised into the durable operational store and fail-closed
+// re-validated on read, so every behaviour here is frozen by core's
+// scripts/wake-origin-fixtures-test.ts (run from the app root with this bundle's boot wiring —
+// scripts/wake-origin-fixtures-boot.ts). Validator tolerances (typeof-only optional checks, extra
+// unknown fields) are LOAD-BEARING for rows already on disk — never tighten them here.
+//
+// The `UnifiedWakeOrigin` TYPE union (including its github arm) stays in core — it is the wire
+// schema for stored rows; only the codec BEHAVIOUR lives in the bundle, registered by
+// registerGithubProvider() (../register.ts).
+
+import type { UnifiedWakeOrigin, WakeOriginCodec } from "@open-everywhere/core/agent/adapter-api.js";
+
+type GitHubOrigin = Extract<UnifiedWakeOrigin, { platform: "github" }>;
+
+/** COLON-FREE by construction (a task windowId is `[^:]+` — core channels/window-key.ts): any colon
+ *  in a raw surface id is folded to `_`, deterministically, so spawn + ingress agree on identity. */
+const noColon = (s: string): string => s.replace(/:/g, "_");
+
+export const githubWakeOriginCodec: WakeOriginCodec<GitHubOrigin> = {
+  validate: (o) =>
+    typeof o.owner === "string" &&
+    o.owner.length > 0 &&
+    typeof o.repo === "string" &&
+    o.repo.length > 0 &&
+    typeof o.issueNumber === "number" &&
+    Number.isFinite(o.issueNumber) &&
+    o.issueNumber > 0 &&
+    (o.installationId === undefined || typeof o.installationId === "number"),
+  threadRef: (origin) => ({ channelKey: noColon(`github/${origin.owner}/${origin.repo}`), threadKey: String(origin.issueNumber) }),
+  // The container and the thread coincide (an issue IS its own thread) ⇒ always thread-scoped.
+  isThreadScoped: () => true,
+  containerId: (origin) => `${origin.owner}/${origin.repo}`,
+  // NO `placementRef` AND NO `carryPlacement`, AND THAT ABSENCE IS THE DECLARATION (OPE-1826). A
+  // GitHub reply is a comment appended to the issue timeline, and the issue IS the thread key above —
+  // there is no "where inside it" left to name, so two origins that pass `sameUnifiedConversation`
+  // cannot disagree about placement. `installationId` is not a counter-example: it selects the
+  // credential the post mints under, never where the post lands. The position is recorded, and held
+  // to account against the live registry, by the `origin-placement-carry` row in core's
+  // identity/surface-parity.ts.
+};