@open-everywhere/provider-github 0.7.0 → 0.8.1

package/agent/app-manifest.ts

@@ -0,0 +1,237 @@
+// THE GITHUB APP MANIFEST (OPE-2529) — one-click GitHub App creation.
+//
+// Creating a GitHub App by hand means picking permissions, events and a webhook URL, then copying
+// a key and a secret back. GitHub's App MANIFEST FLOW does all of it from one document: the person
+// confirms a pre-filled App on github.com, and GitHub redirects with a one-time code that one API
+// call turns into the App's id, private key and webhook secret
+// (https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest).
+//
+// 🔴 THE DOCUMENT IS DERIVED, NEVER HAND-KEPT. Two lists decide what the App needs, and both are
+// code this repository already runs on:
+//   • the PERMISSIONS are the union of every job set the source-control plane mints
+//     (core `scmAppPermissionFloor`, over scm/mint.ts), plus the read permission each subscribed
+//     event needs. A token can only narrow below the App, so a family missing here is a 403 later.
+//   • the EVENTS are this bundle's own event inventory (provider-events.ts), minus the rows no
+//     subscription can fire (`routing: "none"`). GitHub refuses a manifest whose events lack their
+//     permission, so EVENT_PERMISSION below must name a row for every event the inventory routes.
+// The doc's permission table (docs/deploy/surfaces/github.md) is rendered from the same builder by
+// scripts/github-app-manifest-docs.ts, and `lint:github-app-manifest-docs` fails when they differ.
+//
+// The core half (the local page, the state check, the env write) is ops/surface-app-create.ts.
+
+import {
+  agentDisplayName,
+  scmAppPermissionFloor,
+  unionPermissions,
+  SCM_MINT_JOB_SETS,
+  type PermissionGrade,
+  type SurfaceAppCreateFlow,
+  type SurfaceAppCreateResult,
+} from "@open-everywhere/core/agent/adapter-api-ops.js";
+import { GITHUB_PROVIDER_EVENTS } from "./provider-events.js";
+
+/** GitHub's longest App name. */
+export const GITHUB_APP_NAME_MAX = 34;
+
+/** The webhook route every GitHub delivery lands on (channels/github.ts). */
+const GITHUB_WEBHOOK_PATH = "/eve/v1/github";
+
+/**
+ * The repository permission each event needs before GitHub lets an App subscribe to it, from
+ * GitHub's "Webhook events and payloads" page (each event names its "Availability" permission).
+ * Read is enough for a delivery: the job sets above carry the write grades.
+ */
+export const EVENT_PERMISSION: Readonly<Record<string, string>> = {
+  issues: "issues",
+  issue_comment: "issues",
+  pull_request: "pull_requests",
+  pull_request_review: "pull_requests",
+  pull_request_review_comment: "pull_requests",
+  push: "contents",
+  release: "contents",
+  check_run: "checks",
+  check_suite: "checks",
+  workflow_run: "actions",
+  workflow_job: "actions",
+};
+
+/** The two shapes of App. The full App is the default. */
+export type GithubAppVariant = "full" | "source-control";
+
+const GITHUB_APP_VARIANTS: readonly { readonly name: GithubAppVariant; readonly summary: string }[] = [
+  {
+    name: "full",
+    summary: "source control plus the GitHub conversational surface: the agent answers @mentions on issues and pull requests, and routines fire on repository events",
+  },
+  {
+    name: "source-control",
+    summary: "source control only: checkout, pull requests and ticket actions, with no @mention replies and no event subscriptions",
+  },
+];
+
+/** The events the App subscribes to: every inventory row a routine or a mention can act on. */
+export function githubAppEvents(variant: GithubAppVariant): string[] {
+  if (variant === "source-control") return [];
+  return GITHUB_PROVIDER_EVENTS.events
+    .filter((e) => e.routing !== "none" && EVENT_PERMISSION[e.event] !== undefined)
+    .map((e) => e.event)
+    .sort();
+}
+
+/** The App's permissions: the mint floor, plus read on every family a subscribed event needs. */
+export function githubAppPermissions(variant: GithubAppVariant): Record<string, PermissionGrade> {
+  const eventFamilies = Object.fromEntries(githubAppEvents(variant).map((e) => [EVENT_PERMISSION[e]!, "read"]));
+  return unionPermissions([scmAppPermissionFloor(), eventFamilies]);
+}
+
+/** The manifest GitHub reads. `redirectUrl` is the local catch page core opens. */
+export function githubAppManifest(opts: {
+  readonly host: string;
+  readonly variant: GithubAppVariant;
+  readonly redirectUrl: string;
+  readonly appName?: string;
+}): Record<string, unknown> {
+  // The configured `identity.name`, else the shipped display name (identity/bot-name.ts).
+  const name = opts.appName ?? agentDisplayName();
+  return {
+    name: name.slice(0, GITHUB_APP_NAME_MAX),
+    url: `https://${opts.host}`,
+    description: `${name}, an agent that works in this organization's repositories.`,
+    // The webhook is ON in both shapes: GitHub sends `installation` to every App with an active
+    // hook, and that delivery is how each installing org registers itself (no env edit).
+    hook_attributes: { url: `https://${opts.host}${GITHUB_WEBHOOK_PATH}`, active: true },
+    redirect_url: opts.redirectUrl,
+    // Private: only the account that owns the App can install it. A deployment is one org's agent.
+    public: false,
+    default_permissions: githubAppPermissions(opts.variant),
+    default_events: githubAppEvents(opts.variant),
+  };
+}
+
+/** 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. */
+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;
+}
+
+interface Conversion {
+  readonly id?: unknown;
+  readonly slug?: unknown;
+  readonly name?: unknown;
+  readonly pem?: unknown;
+  readonly webhook_secret?: unknown;
+  readonly client_id?: unknown;
+}
+
+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
+ * (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).
+ */
+export async function exchangeGithubManifestCode(opts: {
+  readonly code: string;
+  readonly variant: GithubAppVariant;
+  readonly fetchFn: typeof fetch;
+}): Promise<SurfaceAppCreateResult> {
+  const res = await opts.fetchFn(`${API}/app-manifests/${encodeURIComponent(opts.code)}/conversions`, { method: "POST", headers: HEADERS });
+  // The status only: a refusal body can echo request detail, and this message reaches the page.
+  if (!res.ok) throw new Error(`GitHub refused the code (HTTP ${res.status}). The code is single-use and lasts one hour.`);
+  // A fixed message on a body that is not JSON: the parser's own error quotes part of the body.
+  let body: Conversion;
+  try {
+    body = (await res.json()) as Conversion;
+  } catch {
+    throw new Error(`GitHub's reply was not JSON (HTTP ${res.status}).`);
+  }
+  const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : typeof v === "number" ? String(v) : undefined);
+  const id = str(body.id);
+  const slug = str(body.slug);
+  const pem = str(body.pem);
+  const webhookSecret = str(body.webhook_secret);
+  const clientId = str(body.client_id);
+  const missing = Object.entries({ id, slug, pem, webhook_secret: webhookSecret, client_id: clientId })
+    .filter(([, v]) => v === undefined)
+    .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_WEBHOOK_SECRET: webhookSecret!,
+  };
+  if (opts.variant === "full") {
+    env.GITHUB_APP_ID = id!;
+    env.GITHUB_APP_SLUG = slug!;
+    env.GITHUB_APP_PRIVATE_KEY = pem!;
+  }
+  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;
+  } catch {
+    // Fail-soft, see above.
+  }
+  return { env, 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);
+
+/** The flow core's `surface_app_create` drives. */
+export const GITHUB_APP_CREATE_FLOW: SurfaceAppCreateFlow = {
+  vendor: "GitHub",
+  variants: GITHUB_APP_VARIANTS,
+  appNameMax: GITHUB_APP_NAME_MAX,
+  // A GitHub login: letters, digits and single hyphens, at most 39 characters.
+  ownerProblem: (owner) =>
+    /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/.test(owner) ? undefined : "it is not a GitHub organization login",
+  createUrl: ({ owner, state }) =>
+    owner === undefined
+      ? `https://github.com/settings/apps/new?state=${encodeURIComponent(state)}`
+      : `https://github.com/organizations/${encodeURIComponent(owner)}/settings/apps/new?state=${encodeURIComponent(state)}`,
+  manifestField: "manifest",
+  manifest: ({ host, variant, redirectUrl, appName }) =>
+    githubAppManifest({ host, variant: isVariant(variant) ? variant : "full", redirectUrl, ...(appName === undefined ? {} : { appName }) }),
+  envNames: (variant) => githubAppEnvNames(isVariant(variant) ? variant : "full"),
+  codeProblem: (code) => (/^[A-Za-z0-9_-]{1,128}$/.test(code) ? undefined : "the redirect carried no usable code"),
+  exchange: ({ code, variant, fetchFn }) => exchangeGithubManifestCode({ code, variant: isVariant(variant) ? variant : "full", fetchFn }),
+  // 🔴 PUSH AND REDEPLOY BEFORE THE INSTALL (OPE-2544). The deployment learns the installation from the
+  // 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.",
+    "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.",
+  ],
+};
+
+// ── THE DOC TABLE ───────────────────────────────────────────────────────────────────────────────
+
+/** The permission and event tables for docs/deploy/surfaces/github.md, rendered from the manifest. */
+export function renderGithubAppManifestDocs(): string {
+  const full = githubAppPermissions("full");
+  const floor = scmAppPermissionFloor();
+  const events = githubAppEvents("full");
+  const label = (family: string): string => family.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+  const rows = Object.entries(full).map(([family, grade]) => {
+    const jobs = Object.entries(SCM_MINT_JOB_SETS)
+      .filter(([, set]) => (set as Record<string, string | undefined>)[family] !== undefined)
+      .map(([job]) => job);
+    const byEvent = events.filter((e) => EVENT_PERMISSION[e] === family);
+    const why = [...jobs, ...(byEvent.length > 0 ? [`the ${byEvent.map((e) => `\`${e}\``).join(", ")} event${byEvent.length > 1 ? "s" : ""}`] : [])].join("; ");
+    const scope = floor[family] === undefined ? "full App only" : "both";
+    return `| ${label(family)} | ${grade === "write" ? "Read and write" : "Read-only"} | ${scope} | ${why} |`;
+  });
+  return [
+    "| Repository permission | Access | Shape | Why |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+    "",
+    `Events (full App only): ${events.map((e) => `\`${e}\``).join(", ")}. GitHub sends \`installation\` and \`installation_repositories\` to every App with an active webhook, so neither is listed.`,
+  ].join("\n");
+}

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

@@ -23,7 +23,7 @@
 
 import {
   catchUpSender,
-  resolveConversationReadToken,
+  resolveSurfaceReadToken,
   type NormalizedMessage,
   type PrFetchFn,
   type SeatCatchUpFetch,
@@ -103,7 +103,7 @@ export async function fetchGitHubCatchUpWindow(
 ): Promise<readonly NormalizedMessage[]> {
   const target = parseGithubContainer(req.container);
   if (!target) return []; // not a conversation key ⇒ nothing addressable to read
-  const token = await (deps.resolveToken ?? resolveConversationReadToken)(target.repoFull);
+  const token = await (deps.resolveToken ?? resolveSurfaceReadToken)(target.repoFull);
   const since = new Date(req.sinceMs).toISOString();
   const url = `${API_BASE}/repos/${target.repoFull}/issues/${target.number}/comments?per_page=${CATCH_UP_PAGE_LIMIT}&since=${encodeURIComponent(since)}`;
   const raw = await getJson<readonly RawTimelineComment[]>(deps.fetchFn, url, token, "issues.listComments");

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

@@ -0,0 +1,15 @@
+// DO GITHUB'S EVENTS REACH THIS DEPLOYMENT? (OPE-2547) — GitHub's probe for core's routines/event-reach.ts.
+//
+// GitHub's event normalizer registers from core on every deployment, so core cannot tell from it whether a
+// delivery ever arrives. The native route (`POST /eve/v1/github`, ./github.ts `wrapRoute`) admits a delivery
+// into the routine fan-out only through `gateGithubDelivery`: with `GITHUB_WEBHOOK_SECRET` set, or with the
+// 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.
+
+import { getSettings } from "@open-everywhere/core/agent/adapter-api.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;
+}

package/agent/channels/github-installations.ts

@@ -22,6 +22,8 @@
 // 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.
 
+import type { AuditDetail, AuditDetailBuilder } from "@open-everywhere/core/agent/adapter-api.js";
+
 /** One installation delivery, normalized. `effect` is the whole decision; everything else is the
  *  row/audit payload. */
 export interface GitHubInstallationEvent {
@@ -111,7 +113,7 @@ export interface GitHubInstallationDeps {
     updatedAt: string;
   }) => Promise<void>;
   readonly forget: (owner: string) => Promise<boolean>;
-  readonly audit: (action: string, detail: Record<string, unknown>, workspace: string) => Promise<void>;
+  readonly audit: (action: string, detail: AuditDetail, workspace: string) => Promise<void>;
   readonly now?: () => string;
   readonly log?: (msg: string) => void;
 }
@@ -125,7 +127,7 @@ export interface GitHubInstallationDeps {
  */
 export async function handleGitHubInstallationDelivery(ev: GitHubInstallationEvent, deps: GitHubInstallationDeps): Promise<void> {
   const at = deps.now ? deps.now() : new Date().toISOString();
-  const detail: Record<string, unknown> = {
+  const detail: AuditDetailBuilder = {
     action: ev.action,
     installationId: ev.installationId,
     ...(ev.accountType ? { accountType: ev.accountType } : {}),

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

@@ -21,6 +21,7 @@ import {
   mintInstallationToken,
   CONVERSATION_WRITE_PERMISSIONS,
   loadGitHubAppConfig,
+  githubAuthMode,
   resolveGitHubInstallationId,
   warmCredential,
   markNotApplied,
@@ -121,6 +122,11 @@ function githubAppCreds(): { appId: string; privateKeyPem: string; installations
 /** Exported for the reaction-feedback poll (channels/github-reaction-feedback.ts, OPE-1502), which
  *  reads under the same App identity every other GitHub call in this bundle uses. */
 export async function installationTokenFor(origin: GitHubOrigin): Promise<string> {
+  // ONE CREDENTIAL PER HOST (OPE-2530): a deployment that signs in with a personal access token never
+  // uses the App, so the conversation surface posts nothing, even when App secrets are still set.
+  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();
   if (!creds) {
     // DEFINITIVE (OPE-825): no App credentials ⇒ no request ever left this host.

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

@@ -87,7 +87,7 @@ import { githubConversationKey } from "./github-identity.js";
  *  and up to `GITHUB_REACTION_POLL_COMMENT_BUDGET` reaction reads), so this bounds a repository's
  *  worst hour to ~780 GETs on the installation token the reply path shares. The everyday cost is far
  *  below that: most polls read three. */
-export const GITHUB_REACTION_POLL_HOURLY_BUDGET = 60;
+const GITHUB_REACTION_POLL_HOURLY_BUDGET = 60;
 
 /** The `task_result` retention every consumer of that table shares. See the header: it is coupled,
  *  not tunable. Six hours, the same window `model/turn-state.ts` and the three other consumers use. */

package/agent/channels/github-read.ts

@@ -6,8 +6,9 @@
 //     were not: with no adapter registered, a GitHub seat got "reading a github channel is not
 //     supported yet" (core channels/channel-read.ts `resolveReadAdapter`).
 //   • THE WORKER. `read_work_channel` / `read_work_thread` run the NEUTRAL engine over the same
-//     adapter, so GitHub could not hold a work read either. It now does, under its own grant — the
-//     access bundle's `repos:` list (access/surface-work-grant.ts).
+//     adapter, so GitHub could not hold a work read either. It now does. A delegated worker reads
+//     its own origin conversation with no grant (OPE-2491); any other session needs GitHub's own
+//     grant, the access bundle's `repos:` list (access/surface-work-grant.ts).
 //
 // 🔴 THE CONTAINER IS THE ISSUE-OR-PR CONVERSATION, NOT THE REPO. The GitHub SURFACE grain is the
 // repo (github-identity.ts `bindGitHub`: workspace = owner, surface = repo), because a repo is the
@@ -47,8 +48,10 @@
 // "api", so the repo name alone would admit another owner's repo of the same name. The owner is
 // compared against THIS turn's own binding, which is the container fence in its strictest form.
 //
-// THE CREDENTIAL IS THE BROKERED CONVERSATION-READ TOKEN — `resolveConversationReadToken` (core
-// scm/pr-status.ts), the App installation token for the repo, falling back to `GITHUB_TOKEN`.
+// THE CREDENTIAL IS THE BROKERED CONVERSATION-READ TOKEN — `resolveSurfaceReadToken` (core
+// scm/pr-status.ts), the App installation token for the repo. APP ONLY (OPE-2530): before it, this read
+// fell back to the `GITHUB_TOKEN` personal access token; now a deployment that signs in with one refuses
+// here, because the surface exists only through the App's webhook.
 // GitHub holds ONE credential family, so the chat read and the work read present the same token;
 // access/surface-work-grant.ts's header carries the full argument for why that is the shipped seam
 // and not an oversight.
@@ -56,7 +59,7 @@
 // 🔴 IT IS NOT `resolveReadToken` (OPE-1019). That resolver mints `{contents, pull_requests,
 // metadata}` for the PR verbs, and a token with no `issues` family is refused 403 on `/issues/{n}`
 // when the number names a PLAIN ISSUE — measured live on deploy #118, where both read drives went
-// red while the reply POST on the same two issues returned 201. `resolveConversationReadToken`
+// red while the reply POST on the same two issues returned 201. `resolveSurfaceReadToken`
 // mints `{issues, pull_requests, metadata}`, which is what an endpoint that serves both
 // conversation kinds needs. See scm/mint.ts for the full measurement.
 //
@@ -70,7 +73,7 @@ import {
   assertSurfaceAllowed,
   bindFrom,
   prApiHeaders,
-  resolveConversationReadToken,
+  resolveSurfaceReadToken,
   withRetryAfterLoose,
   ChannelScopeError,
   type AdapterReadFetch,
@@ -419,7 +422,7 @@ export const githubReadAdapter = {
   ): Promise<AdapterReadFetch> {
     const target = await admitContainer(ctx, channel, "github_read_channel");
     const effective = Math.min(limit ?? GITHUB_CHANNEL_DEFAULT_LIMIT, GITHUB_MAX_PAGE);
-    const token = await resolveConversationReadToken(target.repoFull);
+    const token = await resolveSurfaceReadToken(target.repoFull);
     // OPE-1299 — one deadline for the whole read, read fresh per call. See READ_WALK_BUDGET_MS.
     const deadline = (walk.now ?? Date.now)() + READ_WALK_BUDGET_MS;
     const issue = await fetchIssue(fetchFn, token, target, walkRetry(deadline, walk));
@@ -451,7 +454,7 @@ export const githubReadAdapter = {
     walk: ReadWalkSeam = {},
   ): Promise<AdapterReadFetch> {
     const target = await admitContainer(ctx, channel, "github_read_thread");
-    const token = await resolveConversationReadToken(target.repoFull);
+    const token = await resolveSurfaceReadToken(target.repoFull);
     // OPE-1299 — the walk this budget exists for: up to MAX_REVIEW_PAGES calls under one deadline.
     const deadline = (walk.now ?? Date.now)() + READ_WALK_BUDGET_MS;
     const { comments, mightBeTruncated } = await fetchReviewComments(fetchFn, token, target, () => walkRetry(deadline, walk));

package/agent/channels/github-supervisor.ts

@@ -58,6 +58,7 @@ import {
   type SessionTailWakeRow,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import { githubBotMentioned, type OpenEverywhereGitHubAuth } from "./github-identity.js";
+import type { AuditDetail } from "@open-everywhere/core/agent/adapter-api.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
@@ -371,7 +372,7 @@ export function githubDispatchAuditDetail(input: {
   readonly wakeId?: string;
   readonly repoPrivate: boolean;
   readonly vouched: boolean;
-}): Readonly<Record<string, unknown>> {
+}): AuditDetail {
   return {
     addressing: input.addressing,
     issueNumber: input.issueNumber,

package/agent/channels/github.ts

@@ -85,6 +85,7 @@
 // one repo supervisor session. Still needs a live opted-in repo + App install + Tommy for
 // provisioning.
 
+import { auditErrorDetail } from "@open-everywhere/core/agent/adapter-api.js";
 import type { HttpRouteDefinition, RouteHandlerArgs } from "eve/channels";
 import { githubChannel, type GitHubChannel, type GitHubChannelState, type GitHubInboundContext, type GitHubComment, type GitHubInboundResult } from "eve/channels/github";
 import { buildGitHubAuth, githubAuthorFacts, githubBotMentioned } from "./github-identity.js";
@@ -173,7 +174,7 @@ import {
   OE_ADDRESSED_ATTR,
   dispatchNativeWakeWithRetry,
 } from "@open-everywhere/core/agent/adapter-api.js";
-import { withEndsTurnFinalChannel } from "@open-everywhere/core/agent/adapter-api.js";
+import { githubAuthMode, withEndsTurnFinalChannel } from "@open-everywhere/core/agent/adapter-api.js";
 
 const ROUTE = "/eve/v1/github";
 const BOT_NAME = process.env.GITHUB_APP_SLUG;
@@ -613,7 +614,7 @@ export function liveGitHubSupervisorDeps(send: GitHubSend, ev: GitHubAmbientEven
           await auditSupervisorFailure(
             { org: deploymentOrg(), platform: "github", workspace: ev.owner, surface: surfaceKey },
             "surface.wake_failed",
-            { message: String(err instanceof Error ? err.message : err).slice(0, 500), wakeId: window.wakeId },
+            { message: auditErrorDetail(err).error, wakeId: window.wakeId },
           );
           throw err;
         }
@@ -1401,6 +1402,16 @@ function wrapRoute(inner: HttpHandler): HttpHandler {
     // can drop a REDELIVERY (GitHub retries on any non-2xx) without re-firing every matched event
     // routine. Passed only AFTER the signature gate above, never before it (OPE-139).
     args.waitUntil(fanOutGitHubDelivery(body, eventType, args.to, req.headers.get("x-github-delivery")));
+    // ─── TOKEN MODE: THE CONVERSATION SURFACE IS OFF (OPE-2530) ──────────────────────────────────
+    // A deployment that signs in with a personal access token never uses the App, and the surface
+    // (the @mention session, the ambient seat, the stop and reaction legs, installation discovery)
+    // runs on the App. So only the event-routine fan-out above runs: it posts to chat, needs no GitHub
+    // credential, and a plain repository webhook can feed it. Nothing below runs, eve's native channel
+    // included, so no turn starts here and no App token is minted even when App secrets are still set.
+    if (githubAuthMode() === "token") {
+      log(`${eventType || "delivery"}: routine fan-out only — the GitHub conversation surface is off while this deployment signs in with a personal access token`);
+      return new Response("ok", { status: 200 });
+    }
     // ─── THE STOP LEG (OPE-898) ───────────────────────────────────────────────────────────────
     // GitHub sends no reaction webhook, so the stop affordance on this surface is a bare `stop`
     // comment read HERE, in the ingress — before any session is minted. See channels/github-stop.ts