@open-everywhere/provider-github 0.8.0 → 0.9.0

package/agent/app-manifest.ts

@@ -108,11 +108,34 @@ export function githubAppManifest(opts: {
   };
 }
 
-/** The env names a created App fills, for each shape. The OE_ set is the source-control plane; the
- *  bare set is the conversational surface (docs/deploy/surfaces/github.md). One App serves both. */
+/** The env names a created App fills, for each shape — its SECRETS only. The OE_ key is the
+ *  source-control plane's; the bare key is the conversational surface's (docs/deploy/surfaces/github.md).
+ *  One App serves both. Which App it is (id, slug, client id, bot user id) is the `github.*` settings
+ *  since OPE-2650, so no id is an env name here: see {@link githubAppSettings}. */
 export function githubAppEnvNames(variant: GithubAppVariant): string[] {
-  const scm = ["OE_GITHUB_APP_ID", "OE_GITHUB_APP_SLUG", "OE_GITHUB_APP_PRIVATE_KEY", "OE_GITHUB_APP_CLIENT_ID", "OE_GITHUB_BOT_USER_ID", "GITHUB_WEBHOOK_SECRET"];
-  return variant === "full" ? [...scm, "GITHUB_APP_ID", "GITHUB_APP_SLUG", "GITHUB_APP_PRIVATE_KEY"] : scm;
+  // ONE private-key name for both variants (OPE-2650 folded OE_GITHUB_APP_PRIVATE_KEY into it): the key
+  // and the webhook secret are operator secrets, so `secret_set` moves them from .env.local into the store.
+  return ["GITHUB_APP_PRIVATE_KEY", "GITHUB_WEBHOOK_SECRET"];
+}
+
+/** The PUBLIC settings a created App fills, setting path → value (OPE-2650). The source-control plane and
+ *  the conversation surface read the one `github.appId`/`github.appSlug`. `github.conversation` arms the
+ *  conversation surface, so it is `true` for the `full` App only: a `source-control` App subscribes to no
+ *  comment event and must start no conversation. */
+export function githubAppSettings(app: {
+  readonly variant: GithubAppVariant;
+  readonly id: string;
+  readonly slug: string;
+  readonly clientId: string;
+  readonly botUserId?: string;
+}): Record<string, string | boolean> {
+  return {
+    "github.appId": app.id,
+    "github.appSlug": app.slug,
+    "github.appClientId": app.clientId,
+    ...(app.botUserId === undefined ? {} : { "github.botUserId": app.botUserId }),
+    "github.conversation": app.variant === "full",
+  };
 }
 
 interface Conversion {
@@ -128,7 +151,7 @@ const API = "https://api.github.com";
 const HEADERS = { accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28" };
 
 /**
- * Turn the redirect's code into this deployment's env. One POST to GitHub's conversion endpoint
+ * Turn the redirect's code into this deployment's env and settings. One POST to GitHub's conversion endpoint
  * (it needs no credential: the code is the proof, and it is single-use and lives one hour), then a
  * public read of the App's bot user for the commit e-mail. That second read is fail-soft: without
  * it the plane falls back to the App id (docs/capabilities/source-control.md).
@@ -159,25 +182,23 @@ export async function exchangeGithubManifestCode(opts: {
     .map(([k]) => k);
   if (missing.length > 0) throw new Error(`GitHub's reply lacked ${missing.join(", ")}`);
   const env: Record<string, string> = {
-    OE_GITHUB_APP_ID: id!,
-    OE_GITHUB_APP_SLUG: slug!,
-    OE_GITHUB_APP_PRIVATE_KEY: pem!,
-    OE_GITHUB_APP_CLIENT_ID: clientId!,
+    GITHUB_APP_PRIVATE_KEY: pem!,
     GITHUB_WEBHOOK_SECRET: webhookSecret!,
   };
-  if (opts.variant === "full") {
-    env.GITHUB_APP_ID = id!;
-    env.GITHUB_APP_SLUG = slug!;
-    env.GITHUB_APP_PRIVATE_KEY = pem!;
-  }
+  let botUserId: string | undefined;
   try {
     const bot = await opts.fetchFn(`${API}/users/${encodeURIComponent(`${slug}[bot]`)}`, { headers: HEADERS });
     const botId = bot.ok ? str(((await bot.json()) as { id?: unknown }).id) : undefined;
-    if (botId !== undefined && /^\d+$/.test(botId)) env.OE_GITHUB_BOT_USER_ID = botId;
+    if (botId !== undefined && /^\d+$/.test(botId)) botUserId = botId;
   } catch {
     // Fail-soft, see above.
   }
-  return { env, appName: str(body.name) ?? slug!, installUrl: `https://github.com/apps/${encodeURIComponent(slug!)}/installations/new` };
+  return {
+    env,
+    settings: githubAppSettings({ variant: opts.variant, id: id!, slug: slug!, clientId: clientId!, ...(botUserId === undefined ? {} : { botUserId }) }),
+    appName: str(body.name) ?? slug!,
+    installUrl: `https://github.com/apps/${encodeURIComponent(slug!)}/installations/new`,
+  };
 }
 
 const isVariant = (v: string): v is GithubAppVariant => GITHUB_APP_VARIANTS.some((x) => x.name === v);
@@ -204,7 +225,8 @@ export const GITHUB_APP_CREATE_FLOW: SurfaceAppCreateFlow = {
   // App's one `installation` delivery. Before the redeploy it does not hold the App's webhook secret, so
   // it refuses that delivery with a 401 and never learns the installation.
   after: [
-    "Push each written name to the deployment's environment, piped from .env.local and never printed (the setup skill's deployment-env step), then redeploy.",
+    "Commit the returned settings to agent/settings/settings.ts as `github: { appId, appSlug, appClientId, botUserId, conversation }` (public values, safe in Git). Keep any other github key the file already sets.",
+    "Store each written name in the deployment's credential store: call the ops tool secret_set with names [\"GITHUB_APP_PRIVATE_KEY\", \"GITHUB_WEBHOOK_SECRET\"] (they are operator secrets, OPE-2650), then redeploy with the settings change.",
     "Only after that redeploy, install the app on the repositories the agent works in: open the install link. Installing first sends the app's installation delivery to a deployment that does not hold the new webhook secret yet, and it refuses that delivery.",
     "Optional: on the app's settings page, under Display information, upload the project mark as its logo. The manifest has no logo field.",
   ],

package/agent/channels/github-catch-up.ts

@@ -23,6 +23,7 @@
 
 import {
   catchUpSender,
+  getSettings,
   resolveSurfaceReadToken,
   type NormalizedMessage,
   type PrFetchFn,
@@ -88,12 +89,16 @@ export interface GitHubCatchUpDeps {
   readonly selfLogin?: string;
 }
 
+// The GitHub App's comment author is `<app-slug>[bot]`; the deployment states its own slug in the
+// `github.appSlug` setting (OPE-2650), and an unset one degrades to "our posts look like a bot's",
+// which the admission policy still admits under `wide`. A getter, so each read sees the registered
+// settings rather than the value at module load.
 const liveDeps: GitHubCatchUpDeps = {
   fetchFn: liveGithubReadFetch,
-  // The GitHub App's comment author is `<app-slug>[bot]`; the deployment states its own slug, and an
-  // unset one degrades to "our posts look like a bot's", which the admission policy still admits
-  // under `wide`.
-  selfLogin: process.env.GITHUB_APP_SLUG ? `${process.env.GITHUB_APP_SLUG}[bot]` : undefined,
+  get selfLogin(): string | undefined {
+    const slug = getSettings().github.appSlug;
+    return slug ? `${slug}[bot]` : undefined;
+  },
 };
 
 /** The fetch, with its seams exposed so the contract test drives it with no network. */

package/agent/channels/github-credentials.ts

@@ -0,0 +1,41 @@
+// WHERE THE GITHUB BUNDLE'S SECRETS COME FROM (OPE-2650) — the App's private key and the webhook
+// signing secret.
+//
+// Both are OPERATOR SECRETS: `oe secret set GITHUB_APP_PRIVATE_KEY`, `oe secret set
+// GITHUB_WEBHOOK_SECRET`. Core reads them: the db credential store first, the env var of the same name
+// as its warned on-ramp, each store lookup remembered for thirty seconds. The private key has ONE name
+// for the scm plane and this bundle (core's `githubAppPrivateKey`); OPE-2650 folded the
+// OE_GITHUB_APP_PRIVATE_KEY spelling into it.
+//
+// 🔴 EVE MUST BE HANDED BOTH. eve's `githubChannel` resolves `credentials.privateKey` and
+// `credentials.webhookSecret`, and with neither it reads the GITHUB_APP_PRIVATE_KEY and
+// GITHUB_WEBHOOK_SECRET env vars itself, so it would never see a stored value: the native route would
+// 401 every delivery on a deployment that holds the secrets in the store only.
+// {@link githubEveCredentials} is that hand-over. Functions, not values: the read is async, and a value
+// read at module load would pin whatever was true at boot.
+
+import { githubAppPrivateKey, operatorSecretOrUnset } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The operator secret holding the webhook HMAC secret. */
+const GITHUB_WEBHOOK_SECRET_NAME = "GITHUB_WEBHOOK_SECRET";
+
+/** The webhook signing secret, or `undefined` when this deployment holds none (a fault reads as none,
+ *  logged once — the route then fails closed). */
+export async function githubWebhookSecret(): Promise<string | undefined> {
+  return await operatorSecretOrUnset(GITHUB_WEBHOOK_SECRET_NAME);
+}
+
+/** The `credentials` block both `githubChannel(...)` instances carry. Each arm throws eve's OWN message
+ *  when nothing resolves, byte for byte. */
+export const githubEveCredentials = {
+  privateKey: async (): Promise<string> => {
+    const key = await githubAppPrivateKey();
+    if (!key) throw new Error("githubChannel: GITHUB_APP_PRIVATE_KEY is required.");
+    return key;
+  },
+  webhookSecret: async (): Promise<string> => {
+    const secret = await githubWebhookSecret();
+    if (!secret) throw new Error("githubChannel: GITHUB_WEBHOOK_SECRET is required.");
+    return secret;
+  },
+} as const;

package/agent/channels/github-engagement.ts

@@ -286,7 +286,7 @@ async function liveMarkEngageSeen(org: string, key: string, atIso: string): Prom
  * Is this comment MACHINE-AUTHORED — a GitHub App, a bot account, or this deployment's own reply?
  *
  * 🔴 ONE PREDICATE, AND IT MUST FAIL CLOSED ON AN UNRESOLVED SLUG. `githubBotMentioned` needs the
- * app slug to recognise a mention at all, so before this seam a deployment with no `GITHUB_APP_SLUG`
+ * app slug to recognise a mention at all, so before this seam a deployment with no `github.appSlug`
  * simply never woke natively. A plain comment now reaches the seam, and without the slug the app
  * cannot tell its OWN reply from a person's — so "unknown" answers `true` and nothing is delivered,
  * the same posture `classifyGitHubAmbientComment` takes with its own no-slug drop.

package/agent/channels/github-event-reach.ts

@@ -6,10 +6,15 @@
 // dev-only `webhooks.allowUnverifiedGithub` hatch on. With neither, it 401s every delivery and no GitHub
 // routine can fire. This probe asks the same two questions the gate asks, and reads the secret's PRESENCE only.
 
+// The secret is an operator secret since OPE-2650, so the presence read is async and asks the store
+// first, the env var as its on-ramp — the same read the gate makes.
+
 import { getSettings } from "@open-everywhere/core/agent/adapter-api.js";
+import { githubWebhookSecret } from "./github-credentials.js";
 
-/** True when the native GitHub route can admit a delivery into the routine fan-out. */
-export function githubEventsReach(env: NodeJS.ProcessEnv = process.env): boolean {
-  const secret = env.GITHUB_WEBHOOK_SECRET;
-  return (secret !== undefined && secret.length > 0) || getSettings().webhooks.allowUnverifiedGithub;
+/** True when the native GitHub route can admit a delivery into the routine fan-out. `secret` is a test
+ *  seam; the live default is the gate's own read. */
+export async function githubEventsReach(secret: () => Promise<string | undefined> = githubWebhookSecret): Promise<boolean> {
+  const value = await secret();
+  return (value !== undefined && value.length > 0) || getSettings().webhooks.allowUnverifiedGithub;
 }

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

@@ -21,7 +21,9 @@ import {
   mintInstallationToken,
   CONVERSATION_WRITE_PERMISSIONS,
   loadGitHubAppConfig,
+  githubAppPrivateKey,
   githubAuthMode,
+  getSettings,
   resolveGitHubInstallationId,
   warmCredential,
   markNotApplied,
@@ -108,15 +110,16 @@ 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 {
+/** GitHub App credentials for the unified reply arm. The App id is the `github.appId` setting (the scm
+ *  plane's client id preferred as the JWT issuer when set), and the private key has ONE home since
+ *  OPE-2650: the operator secret GITHUB_APP_PRIVATE_KEY, for both the scm plane and this surface. */
+async function githubAppCreds(): Promise<{ 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: {} };
+  const appId = scm ? (scm.clientId ?? scm.appId) : getSettings().github.appId;
+  if (!appId) return null;
+  const privateKeyPem = await githubAppPrivateKey();
+  if (!privateKeyPem) return null;
+  return { appId, privateKeyPem, installations: scm?.installations ?? {} };
 }
 
 /** Exported for the reaction-feedback poll (channels/github-reaction-feedback.ts, OPE-1502), which
@@ -127,19 +130,19 @@ export async function installationTokenFor(origin: GitHubOrigin): Promise<string
   if (githubAuthMode() === "token") {
     throw markNotApplied(new Error("reply couldn't post to GitHub — this deployment signs in with a personal access token, and the GitHub conversation surface needs the GitHub App."));
   }
-  const creds = githubAppCreds();
+  const creds = await 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)."));
+    throw markNotApplied(new Error("reply couldn't post to GitHub — no App credentials (set the github.appId setting, and store the operator secret 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
+  // the `github.installations` setting 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).`,
+      `reply couldn't post to GitHub — no installation id for owner "${origin.owner}" (the wake carried none, the github.installations setting 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

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

@@ -87,7 +87,7 @@
 //
 // ── IDENTITY
 //
-// "The agent's own comment" is `<GITHUB_APP_SLUG>[bot]` — the login GitHub gives an App's comments,
+// "The agent's own comment" is `<github.appSlug>[bot]` — the login GitHub gives an App's comments,
 // and the same self-identity channels/github-supervisor.ts drops its own replies by. 🔴 IT FAILS
 // CLOSED: with no slug configured the arm polls nothing at all, because it cannot tell the agent's
 // comments from anybody else's and reading every comment's reactions would record strangers' reactions
@@ -421,7 +421,7 @@ function tokenFor(target: GitHubReactionPollTarget): Promise<string> {
   });
 }
 
-/** Production deps for the poll. `botLogin` is `<GITHUB_APP_SLUG>[bot]` — absent when the slug is
+/** Production deps for the poll. `botLogin` is `<github.appSlug>[bot]` — absent when the slug is
  *  unset, which is exactly the fail-closed case {@link routeGitHubReactionFeedback} refuses on. */
 export function liveGitHubReactionFeedbackDeps(appSlug: string | undefined, fetchFn: PrFetchFn = liveGithubReadFetch): GitHubReactionFeedbackDeps {
   const slug = appSlug?.trim();

package/agent/channels/github.ts

@@ -69,7 +69,7 @@
 //   4. The INSTALLATION leg (installationDelivery below): the App's `installation` /
 //      `installation_repositories` events register (or revoke) the owner→installation_id entry the
 //      SCM plane mints tokens with, so a new org installing the App is self-service end-to-end
-//      instead of needing an OE_GITHUB_INSTALLATIONS env edit + redeploy. The env map stays
+//      instead of needing a `github.installations` settings edit + redeploy. The settings map stays
 //      AUTHORITATIVE; discovered installs only augment it (scm/installations.ts).
 //
 // Point the GitHub App webhook at POST /eve/v1/github (content-type application/json),
@@ -175,9 +175,52 @@ import {
   dispatchNativeWakeWithRetry,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import { githubAuthMode, withEndsTurnFinalChannel } from "@open-everywhere/core/agent/adapter-api.js";
+import { githubEveCredentials, githubWebhookSecret } from "./github-credentials.js";
 
 const ROUTE = "/eve/v1/github";
-const BOT_NAME = process.env.GITHUB_APP_SLUG;
+
+/**
+ * The name the conversation surface answers to: the `github.appSlug` setting (was `GITHUB_APP_SLUG`,
+ * OPE-2650), or `undefined`. A function, read per call: a module-level read would run before the app
+ * registers its settings. `undefined` keeps the fail-closed loop guard — every ambient comment drops,
+ * and no @mention wakes.
+ *
+ * 🔴 THE SURFACE ARMS ON ITS OWN SETTING, `github.conversation` (OPE-2650). The source-control plane and
+ * this surface share ONE App id, ONE slug and ONE private key (the operator secret
+ * GITHUB_APP_PRIVATE_KEY). None of them says whether this App should start conversations: a
+ * `source-control` App holds all three too. So the arm is a reviewed line in Git. Off (shipped), a
+ * `source-control` App, or a token-mode deployment that moved to one and kept its repository webhook,
+ * starts no conversation from a comment. `surface_app_create` returns `github.conversation: true` for
+ * the `full` App only.
+ */
+export function githubConversationBotName(): string | undefined {
+  const github = getSettings().github;
+  if (!github.conversation) return undefined;
+  return github.appSlug || undefined;
+}
+const botName = githubConversationBotName;
+
+/**
+ * Which App eve's channel speaks as, for BOTH githubChannel instances below (OPE-2650). The slug and
+ * the App id come from settings, and the private key and the webhook secret come from the operator
+ * secret store (`githubEveCredentials`, ./github-credentials.ts). All are lazy fields.
+ *
+ * 🔴 A FIELD LEFT UNDEFINED FALLS BACK TO ENV INSIDE EVE (`GITHUB_APP_SLUG`, `GITHUB_APP_ID`,
+ * `GITHUB_APP_PRIVATE_KEY`, `GITHUB_WEBHOOK_SECRET`), so every one is always passed. eve caches a
+ * resolved slug per instance and treats "" as unset. The App id resolver throws when the setting is
+ * unset, which is eve's own "is required" refusal.
+ */
+export const GITHUB_CHANNEL_APP = {
+  botName: (): string => botName() ?? "",
+  credentials: {
+    ...githubEveCredentials,
+    appId: (): string => {
+      const id = getSettings().github.appId;
+      if (id === "") throw new Error("githubChannel: the github.appId setting is required.");
+      return id;
+    },
+  },
+} as const;
 
 function log(msg: string): void {
   console.log(`[open-everywhere:routines] ${msg}`);
@@ -679,7 +722,7 @@ async function ambientDelivery(body: string, eventType: string, send: GitHubSend
   // WINDOW-ADMISSION FLOOR = the operator VOUCH (identity/trust.ts — the SAME allowlist that gates
   // the shared memory), NOT the repo-private flag. `ev.repoPrivate` is now a logged SIGNAL only.
   const vouched = githubRepoVouched(ev.owner, ev.repo);
-  const cls = classifyGitHubAmbientComment(ev.comment, BOT_NAME, { treatMentionAsDirect: singleWindow, vouched });
+  const cls = classifyGitHubAmbientComment(ev.comment, botName(), { treatMentionAsDirect: singleWindow, vouched });
   if (cls.addressing === "drop") {
     slog(`comment on ${surfaceKey}#${ev.issueNumber} dropped: ${cls.reason} (private=${ev.repoPrivate === true}, vouched=${vouched})`);
     return;
@@ -906,15 +949,16 @@ async function installationDelivery(body: string, eventType: string): Promise<vo
 
 // --- supervisor-aware events (delegating every non-supervisor turn to eve's defaults) --
 
-// A PRISTINE second githubChannel instance (same config axes that shape the default events:
-// none — api/credentials/progress all unset, matching the real channel below) is the source of
+// A PRISTINE second githubChannel instance (same config axes that shape the default events: the
+// shared GITHUB_CHANNEL_APP slug, App id and credentials, and api/progress unset, matching the real channel
+// below) is the source of
 // eve's DEFAULT handlers. defineChannel compiles authored events into `adapter[<event>]`
 // entries of shape `(data, adapterCtx) => authored(data, enriched(adapterCtx), callbackCtx)`;
 // calling one from inside OUR authored handler (same ALS step scope) re-runs the enrichment
 // harmlessly and rebuilds the callback context — i.e. the default runs EXACTLY as if we had
 // never authored the key. This is how the #623 destructive-replacement axis is used safely:
 // the mention path's checkout/reply/error behaviour is eve's own code, not a replica.
-const pristine = githubChannel({ botName: BOT_NAME });
+const pristine = githubChannel({ ...GITHUB_CHANNEL_APP });
 type AdapterEventFn = (data: unknown, adapterCtx: unknown) => unknown;
 const defaultEvent = (name: string): AdapterEventFn | undefined =>
   (pristine as unknown as { adapter?: Record<string, AdapterEventFn> }).adapter?.[name];
@@ -991,13 +1035,13 @@ function nativeGitHubAuditPartition(state: GitHubChannelState): ChatAuditPartiti
 // can (a) keep the SAME mention semantics (githubBotMentioned mirrors eve's gate) and
 // (b) enrich the dispatched auth with the repo owner/name/privacy + actor association the
 // identity mapper needs — eve's own defaultGitHubAuth omits repo.private, which would peg
-// every surface to fail-closed private/external. botName + credentials fall back to env
-// (GITHUB_APP_SLUG / GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY / GITHUB_WEBHOOK_SECRET).
+// every surface to fail-closed private/external. botName and the App id come from settings,
+// and the private key and the webhook secret from the operator secret store (GITHUB_CHANNEL_APP).
 // Exported for the provider integration test (drives the REAL ingress handler directly with a
 // seeded over-budget scope). The channel below wires it as `onComment`.
 export const githubOnComment = async (ctx: GitHubInboundContext, comment: GitHubComment): Promise<GitHubInboundResult> => {
     // Same wake rule as eve's built-in gate (that helper isn't publicly exported).
-    const isMention = githubBotMentioned(comment.body, BOT_NAME, comment.author);
+    const isMention = githubBotMentioned(comment.body, botName(), comment.author);
     // 🔴 THE §2.5 ENGAGED SEAM (OPE-1501) IS THE SECOND DOOR OF THIS GATE. Before it, a comment that
     // was not an @mention returned here and the native leg answered exactly once per mention. Now a
     // PLAIN comment in a container an @mention already ENGAGED is admitted too, and the seam's own
@@ -1016,7 +1060,7 @@ export const githubOnComment = async (ctx: GitHubInboundContext, comment: GitHub
       // The author gate, in the seam's own vocabulary. `githubBotMentioned` already refuses a
       // self-authored mention; a PLAIN comment reaches the seam with no such check, so an engaged
       // container would otherwise admit the app's own reply and loop on itself.
-      authorIsBot: githubMachineAuthored(comment.author?.login ?? ctx.sender.login, comment.author?.type ?? ctx.sender.type, BOT_NAME),
+      authorIsBot: githubMachineAuthored(comment.author?.login ?? ctx.sender.login, comment.author?.type ?? ctx.sender.type, botName()),
       // 🔴 THE REACH FACT (see `githubEngagedFollowUpReach`): an INLINE review comment shares its
       // pull request's anchor, so the non-mention arm refuses one. A mention inside a review thread
       // still wakes — it never reaches that arm.
@@ -1166,7 +1210,7 @@ export const githubOnComment = async (ctx: GitHubInboundContext, comment: GitHub
 };
 
 const native: GitHubChannel = githubChannel({
-  botName: BOT_NAME,
+  ...GITHUB_CHANNEL_APP,
   // 🔴 QUEUE, NEVER STEER (OPE-412) — eve's default `steer` cancels the turn in flight when a
   // message arrives. Same reasoning as the Slack channel; see slack.ts for the full note.
   turnPolicy: "queue",
@@ -1378,7 +1422,7 @@ const native: GitHubChannel = githubChannel({
 // delegate the request UNCHANGED to the native handler for the @mention/session behaviour.
 // The request body can only be read once, so we buffer it and hand the native handler a fresh
 // Request carrying the same body + headers (it re-verifies the signature itself over that
-// body — same GITHUB_WEBHOOK_SECRET).
+// body — the same GITHUB_WEBHOOK_SECRET operator secret, handed to eve as `githubEveCredentials`).
 type HttpHandler = HttpRouteDefinition<GitHubChannelState>["handler"];
 function wrapRoute(inner: HttpHandler): HttpHandler {
   return async (req, args) => {
@@ -1387,7 +1431,7 @@ function wrapRoute(inner: HttpHandler): HttpHandler {
     // unauthenticated delivery is rejected for the whole route (the native handler would
     // 401 it too). The dev escape hatch keeps the fan-out testable without a secret.
     const rejection = gateGithubDelivery(
-      process.env.GITHUB_WEBHOOK_SECRET,
+      await githubWebhookSecret(),
       body,
       req.headers.get("x-hub-signature-256"),
       getSettings().webhooks.allowUnverifiedGithub,
@@ -1441,7 +1485,7 @@ function wrapRoute(inner: HttpHandler): HttpHandler {
     const pollTarget = parseGitHubReactionPollTarget(body, eventType);
     if (pollTarget) {
       args.waitUntil(
-        routeGitHubReactionFeedback(pollTarget, liveGitHubReactionFeedbackDeps(BOT_NAME)).then(
+        routeGitHubReactionFeedback(pollTarget, liveGitHubReactionFeedbackDeps(botName())).then(
           (outcomes) => {
             if (outcomes.length > 0) slog(`reaction feedback on ${pollTarget.owner}/${pollTarget.repo}#${pollTarget.number}: ${outcomes.length} recorded`);
           },

package/agent/docs-generated.ts

@@ -23,8 +23,9 @@ export const PROVIDER_DOCS: readonly DocEntry[] = [
       "",
       "This is the GitHub *conversational-surface* runbook. It is **distinct from the",
       "[source-control plane](../../capabilities/source-control.md)** (the agent's own coding loop —",
-      "checkout/push/PR via the `OE_GITHUB_*` credentials): the two are orthogonal planes that can",
-      "share one GitHub App but use **separate env var sets** (bare `GITHUB_*` here). For the concept",
+      "checkout/push/PR): the two are orthogonal planes, and since OPE-2650 they are ONE GitHub App. They",
+      "read the App's ids from the same `github.*` settings and sign with the one operator secret",
+      "`GITHUB_APP_PRIVATE_KEY`. The `github.conversation` setting arms this surface. For the concept",
       "of a *surface*, see [Surfaces](../../extending/surfaces.md). Like",
       "[Linear](./linear.md)/[Notion](./notion.md), GitHub is ticket/comment-based rather than",
       "chat-based, so it's out of scope for the chat [support matrix](./support-matrix.md).",
@@ -175,9 +176,9 @@ export const PROVIDER_DOCS: readonly DocEntry[] = [
       "   `https://<your-deploy-url>/eve/v1/github`, a generated webhook secret, and the permissions and",
       "   events below. Check the name and confirm. GitHub App names are unique across GitHub, so change",
       "   the name there if GitHub says it is taken. GitHub then sends the App's id, private key and",
-      "   webhook secret back to the local page, which writes them into `.env.local`. You copy no key, and",
-      "   no value passes through the chat. `surface_app_create { \"surface\": \"github\", \"action\": \"status\" }`",
-      "   then lists the names written and the App's install link.",
+      "   webhook secret back to the local page. The page writes only the secrets into `.env.local`. You",
+      "   copy no key, and no secret passes through the chat. `surface_app_create { \"surface\": \"github\", \"action\": \"status\" }`",
+      "   then lists the names written, the App's install link, and the App's public ids as `settings`.",
       "",
       "   - `owner: \"<org login>\"` creates the App under an organization. Without it, the App belongs to",
       "     your own account.",
@@ -225,20 +226,38 @@ export const PROVIDER_DOCS: readonly DocEntry[] = [
       "   **By hand.** Without the ops server, create the App at GitHub → **Settings → Developer settings",
       "   → GitHub Apps → New GitHub App**. Point the webhook at `https://<your-deploy-url>/eve/v1/github`,",
       "   set a webhook secret, grant the permissions in the table and subscribe to its events. Then set the",
-      "   environment in step 2 yourself.",
+      "   settings and the environment in step 2 yourself.",
       "",
       "   On the App's settings page, under **Display information**, upload [`brand/png/mark-square-1024.png`](../../../brand/png/mark-square-1024.png), the project mark, as its logo. The manifest has no logo field. Skip this when you set [`identity.name`](../configuration-reference.md) and chose your own icon: with no name configured the agent presents as the project, so the project mark is its default avatar.",
-      "2. **Configure the environment.** The full App writes every name below into `.env.local`, plus",
-      "   the `OE_GITHUB_*` source-control set (`OE_GITHUB_APP_ID`, `OE_GITHUB_APP_SLUG`,",
-      "   `OE_GITHUB_APP_PRIVATE_KEY`, `OE_GITHUB_APP_CLIENT_ID`) for the same App. The source-control",
-      "   App writes only the `OE_GITHUB_*` set and `GITHUB_WEBHOOK_SECRET`. `OE_GITHUB_BOT_USER_ID` is",
-      "   written only when GitHub's bot-user lookup answers. Push the names that `status` lists in",
-      "   `written`, piped from the file and never printed, then redeploy. By hand, set them yourself. The conversational surface uses the **bare** names — the",
-      "   `OE_GITHUB_*` set is the separate source-control plane, even when both point at one App:",
+      "2. **Commit the settings and store the secrets.** The App's public values are settings in Git",
+      "   (OPE-2650). The `status` reply returns them as `settings`: `github.appId`, `github.appSlug`,",
+      "   `github.appClientId`, `github.conversation` and, when GitHub's bot-user lookup answers,",
+      "   `github.botUserId`. Commit them to your app's `agent/settings/settings.ts`. One App serves both",
+      "   planes, so the source-control plane and this conversational surface read the same settings.",
+      "   `github.conversation` arms this surface: the full App returns `true`, and a source-control App",
+      "   returns `false`, so its comments start no conversation:",
+      "",
+      "   ```ts",
+      "   // agent/settings/settings.ts",
+      "   export const SETTINGS_OVERRIDES = defineSettings({",
+      "     github: {",
+      "       appId: \"123456\",        // the App's numeric id",
+      "       appSlug: \"acme-agent\",  // the App slug — the bot answers to @<slug>",
+      "       appClientId: \"Iv1.…\",   // the App's public OAuth client id",
+      "       botUserId: \"987654\",    // the bot user's id, for commit attribution",
+      "       conversation: true,     // the full App: @mentions and comments start sessions",
+      "     },",
+      "   });",
+      "   ```",
+      "",
+      "   **The private key and the webhook secret are operator secrets** (OPE-2650). The tool writes both",
+      "   into `.env.local`. Store them with the ops tool `secret_set { names: [\"GITHUB_APP_PRIVATE_KEY\",",
+      "   \"GITHUB_WEBHOOK_SECRET\"] }`, or `npx oe secret set <NAME>` by hand, then redeploy. One",
+      "   private-key name serves both planes: OPE-2650 folded `OE_GITHUB_APP_PRIVATE_KEY` into",
+      "   `GITHUB_APP_PRIVATE_KEY`.",
       "",
       "   ```bash",
-      "   GITHUB_APP_ID=…            # the App's numeric id",
-      "   GITHUB_APP_SLUG=…          # the App slug — the bot answers to @<slug>",
+      "   # Operator secrets: `npx oe secret set <NAME>`, value on stdin. An env var is only the on-ramp.",
       "   GITHUB_APP_PRIVATE_KEY=…   # PEM private key (mint installation tokens)",
       "   GITHUB_WEBHOOK_SECRET=…    # HMAC-verifies every delivery. REQUIRED — unset rejects all (fail closed)",
       "   # DEV ONLY, and it is a SETTING not a variable: turn on `webhooks.allowUnverifiedGithub`",
@@ -258,9 +277,9 @@ export const PROVIDER_DOCS: readonly DocEntry[] = [
       "## Multi-org installs (self-registering)",
       "",
       "The source-control plane mints tokens per **owner**, so it needs an `owner → installation id`",
-      "entry for every account the App is installed on. You can set that by hand with",
-      "`OE_GITHUB_INSTALLATIONS` (a JSON map) or the single-owner `OE_GITHUB_OWNER` /",
-      "`OE_GITHUB_INSTALLATION_ID` pair — and you no longer have to.",
+      "entry for every account the App is installed on. You can set that by hand with the",
+      "`github.installations` setting (an object such as `{ acme: \"4242\" }`, ids as numeric strings) —",
+      "and you no longer have to.",
       "",
       "Because GitHub delivers `installation` + `installation_repositories` to every App by default",
       "(no subscription exists to switch on), each install/uninstall registers",
@@ -268,11 +287,11 @@ export const PROVIDER_DOCS: readonly DocEntry[] = [
       "and a repo-scope change refreshes it. An org installing your App is then self-service end to end —",
       "no env edit, no redeploy.",
       "",
-      "**`OE_GITHUB_INSTALLATIONS` stays authoritative.** The discovered entries are composed *under* the",
-      "env map, so anything you pinned by hand always wins, a store outage degrades to exactly the",
-      "env-configured set, and a webhook can never re-point an owner you configured yourself. (By the same",
-      "rule, uninstalling an org you *also* pinned in env leaves the env entry in place — its mints then",
-      "fail loudly at GitHub, which is the honest signal; remove it from the env map to finish the removal.)",
+      "**`github.installations` stays authoritative.** The discovered entries are composed *under* the",
+      "setting, so anything you pinned by hand always wins. A store outage degrades to exactly the",
+      "configured set, and a webhook can never re-point an owner you configured yourself. (By the same",
+      "rule, uninstalling an org you *also* pinned in the setting leaves its entry in place. Its mints then",
+      "fail loudly at GitHub, which is the honest signal. Remove it from the setting to finish the removal.)",
       "",
       "Install and uninstall both write an audit row — `surface.app_installed` / `surface.app_uninstalled`,",
       "with the owner as the workspace — so the install history is queryable over the control plane's",