typeclaw 0.9.2 → 0.11.0

package/src/bundled-plugins/security/policies/role-promotion.ts

@@ -8,25 +8,32 @@ import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_ROLE_PROMOTION = 'rolePromotion'
-// Classified `high` (audience-leak axis, adapted).
+// Classified `medium` (silent-attack axis). Originally `high`; reclassified
+// because the privilege escalation does NOT take effect until the operator
+// reloads or restarts — `roles` is `restart-required` in FIELD_EFFECTS, and
+// even the `match`-only path that's classified `applied` writes through
+// `typeclaw.json` which is force-committed by the auto-backup plugin on
+// idle. The operator sees the file change in `git log`, in `typeclaw reload`
+// output, and in their backup commits BEFORE the new role mapping takes
+// effect. There is an operator-visible step between bypass and breach,
+// which puts this guard squarely on the medium axis: bypass produces
+// attacker-favorable state in operator-reviewable surface, not direct
+// audience-leak.
 //
-// Role promotion is privilege escalation: the agent rewrites
-// `typeclaw.json#roles` so a previously-unprivileged actor now resolves
-// to a privileged role. The breach pattern: a `member`-role speaker in a
-// chat asks "give me permission" / "promote me to admin"; the agent
-// edits typeclaw.json with what looks like a routine config change; the
-// schema is valid, the managedConfig guard passes, nonWorkspaceWrite
-// allowlists typeclaw.json — and on next reload the speaker resolves to
-// `owner` with full bypasses.
+// Net effect on the role-tower model: owner and trusted both bypass without
+// ack; member and guest still get blocked. The defense for trusted now
+// depends on operator config-review discipline — if backup commits are
+// reviewed and `typeclaw reload` output is read before applying, a
+// trusted-laundered role promotion is caught before it fires. Operators
+// who do not review can re-tighten by adding `security.bypass.rolePromotion`
+// to `trusted.permissions[]` as an explicit subtraction (replace the
+// default tier grant with a narrower list) — see typeclaw-permissions skill.
 //
-// This is the same audience-leak shape as gitExfil and outboundSecret:
-// the "audience" here is the future-self of the access-control table,
-// which is outside the operator's per-call control loop. Even an `owner`
-// operating from TUI must not silently rewrite the role table based on
-// a channel message — the canonical owner-in-public-channel attack
-// generalizes from "post credentials" to "promote the asker". No role
-// auto-bypasses; per-call ack or an explicit `security.bypass.rolePromotion`
-// grant is required.
+// Breach pattern blocked at `medium`: a `member`-role speaker in a chat
+// asks "promote me to admin"; the agent edits typeclaw.json; the change is
+// schema-valid, managedConfig accepts it, nonWorkspaceWrite allowlists
+// typeclaw.json — but this guard still blocks because member does not
+// carry `bypass.medium` by default.
 //
 // What counts as a promotion (any of):
 //   1. A role's `permissions[]` gained an entry.
@@ -58,7 +65,7 @@ export const GUARD_ROLE_PROMOTION = 'rolePromotion'
 //     agent cannot start a claim, only consume one whose code the
 //     operator already broadcast. That makes the bypass intentionally
 //     out-of-band — do not extend this guard to cover it.
-export const GUARD_ROLE_PROMOTION_SEVERITY: SecuritySeverity = 'high'
+export const GUARD_ROLE_PROMOTION_SEVERITY: SecuritySeverity = 'medium'
 
 export type RolePromotionFinding = {
   role: string

package/src/channels/adapters/github/auth-app.ts

@@ -1,7 +1,9 @@
+import { createPrivateKey } from 'node:crypto'
+
 import { resolveSecret, type Secret } from '@/secrets/resolve'
 
-import type { GithubAuthStrategy, GithubSelfUser } from './auth'
-import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import type { GithubAuthStrategy, GithubInstallationGrants, GithubSelfUser } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders, githubPublicHeaders } from './auth-pat'
 
 export class AppAuthStrategy implements GithubAuthStrategy {
   private readonly appId: number
@@ -52,8 +54,11 @@ export class AppAuthStrategy implements GithubAuthStrategy {
     if (typeof app.slug !== 'string') throw new Error('GitHub /app response missing slug')
 
     const botLogin = `${app.slug}[bot]`
+    // GET /users/{login} is a public endpoint and rejects App JWTs with 401.
+    // Installation tokens also fail here (404 — they're scoped to repos, not user lookups).
+    // The bot user is publicly visible, so no auth is the only path that works.
     const userResponse = await this.fetchImpl(`${GITHUB_API_BASE}/users/${encodeURIComponent(botLogin)}`, {
-      headers: githubJsonHeaders(jwt),
+      headers: githubPublicHeaders(),
     })
     if (!userResponse.ok) throw new Error(`GitHub bot user lookup failed: ${userResponse.status}`)
     const user = (await userResponse.json()) as { id?: unknown; login?: unknown }
@@ -64,6 +69,24 @@ export class AppAuthStrategy implements GithubAuthStrategy {
     return this._selfUser
   }
 
+  async getInstallationGrants(): Promise<GithubInstallationGrants> {
+    const jwt = await this.mintJwt()
+    const installId = await this.resolveInstallationId(jwt)
+    const response = await this.fetchImpl(`${GITHUB_API_BASE}/app/installations/${installId}`, {
+      headers: githubJsonHeaders(jwt),
+    })
+    if (!response.ok) throw new Error(`GitHub App installation fetch failed: ${response.status}`)
+    const raw = (await response.json()) as { permissions?: unknown; events?: unknown }
+    const permissions: Record<string, 'read' | 'write' | 'admin'> = {}
+    if (raw.permissions !== null && typeof raw.permissions === 'object') {
+      for (const [key, value] of Object.entries(raw.permissions as Record<string, unknown>)) {
+        if (value === 'read' || value === 'write' || value === 'admin') permissions[key] = value
+      }
+    }
+    const events = Array.isArray(raw.events) ? raw.events.filter((e): e is string => typeof e === 'string') : []
+    return { permissions, events }
+  }
+
   async dispose(): Promise<void> {
     this.cachedToken = null
   }
@@ -111,10 +134,31 @@ function base64url(input: string | Buffer): string {
 }
 
 async function importRsaPrivateKey(pem: string): Promise<CryptoKey> {
-  const b64 = pem
-    .replace(/-----BEGIN [^-]+-----/, '')
-    .replace(/-----END [^-]+-----/, '')
-    .replace(/\s/g, '')
-  const der = Buffer.from(b64, 'base64')
-  return await crypto.subtle.importKey('pkcs8', der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign'])
+  // GitHub's "Generate a private key" button hands out PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`),
+  // but WebCrypto's importKey only accepts PKCS#8. Round-trip through node:crypto, which accepts
+  // both PKCS#1 and PKCS#8 PEM, then re-export as PKCS#8 DER for WebCrypto.
+  const pkcs8Der = pemToPkcs8Der(pem)
+  return await crypto.subtle.importKey('pkcs8', pkcs8Der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, [
+    'sign',
+  ])
+}
+
+function pemToPkcs8Der(pem: string): ArrayBuffer {
+  if (/-----BEGIN ENCRYPTED PRIVATE KEY-----/.test(pem)) {
+    throw new Error('GitHub App private key is encrypted; provide an unencrypted PEM')
+  }
+  let keyObject
+  try {
+    keyObject = createPrivateKey({ key: pem, format: 'pem' })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`GitHub App private key is invalid: ${message}`)
+  }
+  if (keyObject.asymmetricKeyType !== 'rsa') {
+    throw new Error(`GitHub App private key must be RSA, got ${keyObject.asymmetricKeyType ?? 'unknown'}`)
+  }
+  const der = keyObject.export({ type: 'pkcs8', format: 'der' })
+  const out = new ArrayBuffer(der.byteLength)
+  new Uint8Array(out).set(der)
+  return out
 }

package/src/channels/adapters/github/auth-pat.ts

@@ -40,8 +40,11 @@ export class PatAuthStrategy implements GithubAuthStrategy {
 }
 
 export function githubJsonHeaders(token: string): HeadersInit {
+  return { ...githubPublicHeaders(), Authorization: `Bearer ${token}` }
+}
+
+export function githubPublicHeaders(): HeadersInit {
   return {
-    Authorization: `Bearer ${token}`,
     Accept: 'application/vnd.github+json',
     'Content-Type': 'application/json',
     'X-GitHub-Api-Version': '2022-11-28',

package/src/channels/adapters/github/auth.ts

@@ -7,9 +7,19 @@ export type GithubAuthStrategy = {
   token: () => Promise<string>
   authHeaders: () => Promise<HeadersInit>
   getSelf: () => Promise<GithubSelfUser>
+  // App-only: returns the installation's granted-permissions map and declared
+  // events so the adapter can preflight against the configured eventAllowlist
+  // before any webhook arrives. PATs return access via token scopes, not an
+  // installation grant, so they leave this undefined.
+  getInstallationGrants?: () => Promise<GithubInstallationGrants>
   dispose: () => Promise<void>
 }
 
+export type GithubInstallationGrants = {
+  permissions: Readonly<Record<string, 'read' | 'write' | 'admin'>>
+  events: readonly string[]
+}
+
 export type GithubSelfUser = {
   login: string
   id: number

package/src/channels/adapters/github/event-permissions.ts

@@ -0,0 +1,83 @@
+// Maps a GitHub webhook event (in the form used in typeclaw.json#channels.github.eventAllowlist,
+// e.g. "issue_comment.created" or just "issues") to the GitHub App "Repository permissions"
+// key that gates BOTH receiving payload fields AND posting replies for that event family.
+//
+// Source: https://docs.github.com/en/webhooks/webhook-events-and-payloads (each event page
+// links to the App permission it requires).
+//
+// The permission key on the LEFT is what github.com calls the permission in the App settings UI
+// ("Issues", "Pull requests", "Discussions"); the value on the RIGHT is the snake_case key that
+// appears in the `permissions` object on GET /app/installations/{id} responses. They MUST match
+// the strings GitHub actually emits — these are checked at runtime against an installation grant
+// map, not normalised.
+export const EVENT_PERMISSION_KEY: Record<string, string> = {
+  issues: 'issues',
+  issue_comment: 'issues',
+  pull_request: 'pull_requests',
+  pull_request_review: 'pull_requests',
+  pull_request_review_comment: 'pull_requests',
+  pull_request_review_thread: 'pull_requests',
+  discussion: 'discussions',
+  discussion_comment: 'discussions',
+  commit_comment: 'contents',
+  push: 'contents',
+}
+
+// Human-readable label for each App permission key, mirroring github.com's
+// "Repository permissions" section verbatim. Used in the preflight warning so
+// users can grep for the exact string on the App settings page.
+export const PERMISSION_UI_LABEL: Record<string, string> = {
+  issues: 'Issues',
+  pull_requests: 'Pull requests',
+  discussions: 'Discussions',
+  contents: 'Contents',
+  metadata: 'Metadata',
+}
+
+export type GrantLevel = 'read' | 'write' | 'admin'
+
+// Accepts both the dotted form ("issues.opened", as used in
+// typeclaw.json#channels.github.eventAllowlist) and the bare event family
+// ("issues", as used in webhook event-header names).
+export function permissionKeyForEvent(event: string): string | null {
+  const family = event.includes('.') ? event.slice(0, event.indexOf('.')) : event
+  return EVENT_PERMISSION_KEY[family] ?? null
+}
+
+export type PermissionGap = {
+  permissionKey: string
+  uiLabel: string
+  granted: GrantLevel | null
+  events: string[]
+  needsWrite: boolean
+}
+
+// Unknown allowlist items are silently ignored — forward-compat for events
+// typeclaw doesn't yet know about. `needsWrite` is hardcoded true because
+// channel_reply is today's only canonical exit; flip to a per-event flag the
+// day a read-only github channel becomes a supported use case.
+export function findPermissionGaps(
+  eventAllowlist: readonly string[],
+  installationPermissions: Readonly<Record<string, GrantLevel>>,
+): PermissionGap[] {
+  const eventsByKey = new Map<string, Set<string>>()
+  for (const event of eventAllowlist) {
+    const key = permissionKeyForEvent(event)
+    if (key === null) continue
+    if (!eventsByKey.has(key)) eventsByKey.set(key, new Set())
+    eventsByKey.get(key)?.add(event)
+  }
+  const gaps: PermissionGap[] = []
+  for (const [permissionKey, events] of eventsByKey) {
+    const granted = installationPermissions[permissionKey] ?? null
+    if (granted === 'write' || granted === 'admin') continue
+    gaps.push({
+      permissionKey,
+      uiLabel: PERMISSION_UI_LABEL[permissionKey] ?? permissionKey,
+      granted,
+      events: [...events].sort(),
+      needsWrite: true,
+    })
+  }
+  return gaps.sort((a, b) => a.permissionKey.localeCompare(b.permissionKey))
+}

package/src/channels/adapters/github/inbound.ts

@@ -15,6 +15,10 @@ export type GithubWebhookHandlerOptions = {
   selfLogin: () => string | null
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
+  // Optional: resolves whether the bot is a member of the given team. When
+  // omitted, team-reviewer requests are silently dropped (the v1 fallback
+  // behavior). The adapter wires this in production; tests inject a fake.
+  isBotInTeam?: (input: { org: string; slug: string; login: string }) => Promise<boolean>
 }
 
 export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions): (req: Request) => Promise<Response> {
@@ -43,7 +47,10 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const author = readAuthor(payload)
     if (selfId !== null && author !== null && String(author.id) === selfId) return ok()
 
-    const classified = classifyGithubInbound(event, payload, options.selfLogin())
+    const teamIsBotMember = await resolveTeamMembership(event, payload, options)
+    const classified = classifyGithubInbound(event, payload, options.selfLogin(), {
+      teamIsBotMember,
+    })
     if (classified === null) return ok()
 
     if (delivery !== '') options.dedup.add(delivery)
@@ -64,6 +71,7 @@ export function classifyGithubInbound(
   event: string,
   payload: Record<string, unknown>,
   selfLogin: string | null,
+  options?: { teamIsBotMember?: boolean },
 ): InboundMessage | null {
   const repository = readRepository(payload)
   if (repository === null) return null
@@ -151,6 +159,18 @@ export function classifyGithubInbound(
     const number = readNumber(pr, 'number')
     const id = readNumber(pr, 'id') ?? number
     if (number === null || id === null) return null
+    const action = readString(payload, 'action')
+    if (action === 'review_requested' || action === 'review_request_removed') {
+      return classifyReviewRequest({
+        action,
+        payload,
+        pr,
+        number,
+        base,
+        selfLogin,
+        teamIsBotMember: options?.teamIsBotMember,
+      })
+    }
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
       pr.body,
@@ -197,6 +217,85 @@ export function classifyGithubInbound(
   return null
 }
 
+type ReviewRequestInput = {
+  action: 'review_requested' | 'review_request_removed'
+  payload: Record<string, unknown>
+  pr: Record<string, unknown>
+  number: number
+  base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
+  selfLogin: string | null
+  teamIsBotMember: boolean | undefined
+}
+
+function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null {
+  const { action, payload, pr, number, base, selfLogin, teamIsBotMember } = input
+  if (selfLogin === null) return null
+  const sender = readUser(payload.sender)
+  if (sender === null) return null
+  // Self-loop guard: if the bot itself requested (or un-requested) the
+  // review, drop the event. The bot adding itself as a reviewer would
+  // otherwise wake a fresh session every time it self-assigns.
+  if (sender.login === selfLogin) return null
+
+  const requestedUser = readUser(payload.requested_reviewer)
+  const requestedTeam = readReviewerTeam(payload.requested_team)
+
+  const isMeAsUser = requestedUser !== null && requestedUser.login === selfLogin
+  const isMyTeam = requestedTeam !== null && teamIsBotMember === true
+  if (!isMeAsUser && !isMyTeam) return null
+
+  const title = readString(pr, 'title') ?? `#${number}`
+  const head = readString(readRecord(pr.head), 'ref')
+  const baseRef = readString(readRecord(pr.base), 'ref')
+  const branchSegment = head !== null && baseRef !== null ? ` Branch: ${head} → ${baseRef}.` : ''
+  const verbed =
+    action === 'review_requested'
+      ? isMyTeam
+        ? `requested a review from team @${requestedTeam?.slug} (you're a member of) on PR #${number}: "${title}".`
+        : `requested your review on PR #${number}: "${title}".`
+      : isMyTeam
+        ? `removed the review request for team @${requestedTeam?.slug} on PR #${number}: "${title}".`
+        : `removed your review request on PR #${number}: "${title}".`
+  const closing =
+    action === 'review_requested'
+      ? ' Please review the changes line-by-line and post your feedback.'
+      : ' You can stop any in-progress review.'
+  const text = `@${sender.login} ${verbed}${branchSegment}${closing}`
+
+  // Synthesize a stable per-event externalMessageId. The PR's `updated_at`
+  // changes on every review-request mutation, so combining it with the PR id
+  // and the action keeps separate "requested → removed → requested again"
+  // events from collapsing into one dedup'd id.
+  const updatedAt = readString(pr, 'updated_at') ?? ''
+  const prId = readNumber(pr, 'id') ?? number
+  const externalMessageId = `pr-${prId}-${action}-${updatedAt}`
+
+  return {
+    ...base,
+    chat: `pr:${number}`,
+    thread: null,
+    text,
+    externalMessageId,
+    authorId: String(sender.id),
+    authorName: sender.login,
+    authorIsBot: sender.type === 'Bot',
+    isBotMention: true,
+    replyToBotMessageId: null,
+    ts: updatedAt !== '' ? Date.parse(updatedAt) || 0 : 0,
+  }
+}
+
+export type GithubReviewerTeam = { slug: string; id: number; org: string | null }
+
+export function readReviewerTeam(value: unknown): GithubReviewerTeam | null {
+  const team = readRecord(value)
+  const slug = readString(team, 'slug')
+  const id = readNumber(team, 'id')
+  if (slug === null || id === null) return null
+  const org = readString(readRecord(team?.organization), 'login')
+  return { slug, id, org }
+}
+
 function buildInbound(
   key: Pick<
     InboundMessage,
@@ -223,6 +322,32 @@ function buildInbound(
   }
 }
 
+async function resolveTeamMembership(
+  event: string,
+  payload: Record<string, unknown>,
+  options: GithubWebhookHandlerOptions,
+): Promise<boolean | undefined> {
+  if (event !== 'pull_request') return undefined
+  const action = readString(payload, 'action')
+  if (action !== 'review_requested' && action !== 'review_request_removed') return undefined
+  const team = readReviewerTeam(payload.requested_team)
+  if (team === null) return undefined
+  const selfLogin = options.selfLogin()
+  if (selfLogin === null) return false
+  if (options.isBotInTeam === undefined) return false
+  // The team payload sometimes omits `organization.login`. Fall back to the
+  // repository owner, which is the only org GitHub can legally route team
+  // reviewers from on a given PR.
+  const org = team.org ?? readRepository(payload)?.owner ?? null
+  if (org === null) return false
+  try {
+    return await options.isBotInTeam({ org, slug: team.slug, login: selfLogin })
+  } catch (err) {
+    options.logger.warn(`[github] team membership lookup failed: ${describe(err)}`)
+    return false
+  }
+}
+
 function readRepository(payload: Record<string, unknown>): { owner: string; name: string } | null {
   const repository = readRecord(payload.repository)
   const owner = readRecord(repository?.owner)

package/src/channels/adapters/github/index.ts

@@ -6,12 +6,19 @@ import type { GithubSecretsBlock } from '@/secrets/schema'
 import { buildAuthStrategy } from './auth'
 import { createGithubChannelNameResolver } from './channel-resolver'
 import { createDeliveryDedup } from './dedup'
+import { findPermissionGaps } from './event-permissions'
 import { createGithubFetchAttachmentCallback } from './fetch-attachment'
 import { createGithubHistoryCallback } from './history'
 import { createGithubWebhookHandler } from './inbound'
 import { applyManagedPath, buildManagedPath, resolveAgentId } from './managed-path'
 import { createGithubMembershipResolver } from './membership'
 import { createGithubOutboundCallback } from './outbound'
+import {
+  buildAppPermissionPreflightGuidance,
+  buildPermissionGuidance,
+  parseListHooksPermissionStatus,
+} from './permission-guidance'
+import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
 export type GithubAdapterLogger = {
@@ -35,6 +42,17 @@ export type GithubAdapterOptions = {
   // wrong)" so the skip-registration log can be precise and actionable.
   // Optional so tests that don't exercise the tunnel-status path can omit it.
   tunnelConfiguredForChannel?: () => boolean
+  // Sleep between learning the public webhook URL and telling GitHub about
+  // it. cloudflared prints the trycloudflare.com URL as soon as the control
+  // connection comes up, but the Cloudflare edge needs a beat to start
+  // routing traffic for that hostname. If we register with GitHub the
+  // instant we know the URL, GitHub's automatic `ping` delivery races the
+  // edge and lands "failed to connect to host". 2s is enough on every
+  // network we've tested; tests pass 0 to skip.
+  webhookRegistrationDelayMs?: number
+  // Test-only: replaces the wall-clock sleep used for the registration
+  // delay above. Production leaves it undefined and we use `setTimeout`.
+  sleep?: (ms: number) => Promise<void>
 }
 
 export type GithubAdapter = {
@@ -49,9 +67,13 @@ const consoleLogger: GithubAdapterLogger = {
   error: (m) => console.error(m),
 }
 
+const DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS = 2_000
+
 export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
   const logger = options.logger ?? consoleLogger
   const fetchImpl = options.fetchImpl ?? fetch
+  const webhookRegistrationDelayMs = options.webhookRegistrationDelayMs ?? DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS
+  const sleep = options.sleep ?? defaultSleep
   const auth = buildAuthStrategy({ auth: options.secrets.auth, fetchImpl })
   const webhookSecret = resolveSecret(options.secrets.webhookSecret, undefined, process.env)
   if (webhookSecret === undefined || webhookSecret.trim() === '') throw new Error('GitHub webhookSecret is missing')
@@ -72,7 +94,12 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     process.env.GH_TOKEN = t
     return t
   }
-  const outbound = createGithubOutboundCallback({ token: tokenFn, logger, fetchImpl })
+  const outbound = createGithubOutboundCallback({
+    token: tokenFn,
+    authType: options.secrets.auth.type,
+    logger,
+    fetchImpl,
+  })
   const history = createGithubHistoryCallback({
     token: tokenFn,
     fetchImpl,
@@ -84,12 +111,14 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   // No-op typing callback: GitHub has no typing indicator API.
   const typing = async (): Promise<void> => {}
   const dedup = createDeliveryDedup()
+  const isBotInTeam = createTeamMembershipChecker({ token: tokenFn, fetchImpl })
   const handler = createGithubWebhookHandler({
     webhookSecret,
     dedup,
     allowlist: () => options.configRef().eventAllowlist,
     selfId: () => selfId,
     selfLogin: () => selfLogin,
+    isBotInTeam,
     logger,
     route: (message) => {
       rememberWorkspace(message.workspace, message.chat)
@@ -140,6 +169,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       process.env.GH_TOKEN = await auth.token()
       started = true
       logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
+      // Best-effort: App-only preflight that compares the installation's granted
+      // permissions against the configured eventAllowlist and warns about gaps.
+      // Catches the most common misconfiguration (App installed with the default
+      // metadata-only permission set) before any event fires a 403.
+      await runAppPermissionPreflight(logger, auth, options.configRef().eventAllowlist)
       // Repository webhook registration is best-effort: failures are logged
       // per-repo, the adapter stays up. A misconfigured PAT or App that
       // can't manage hooks must not prevent the adapter from accepting
@@ -162,6 +196,12 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         })
       } else if (repos.length > 0) {
         const legacyProviderHostSuffix = detectLegacyProviderHostSuffix(effectiveUrl)
+        if (webhookRegistrationDelayMs > 0) {
+          logger.info(
+            `[github] waiting ${webhookRegistrationDelayMs}ms before registering webhook so the Cloudflare edge can warm up`,
+          )
+          await sleep(webhookRegistrationDelayMs)
+        }
         const registration = await registerGithubWebhooks({
           token: tokenFn,
           webhookUrl: effectiveUrl,
@@ -290,72 +330,22 @@ function logRegistrationOutcome(
   }
 }
 
-// Parses webhook-register errors of the shape `list hooks failed: <status> <body>`.
-// Returns the status code when it matches the two shapes GitHub emits for
-// missing access on the list-hooks endpoint:
-//   - 404 Not Found: the token cannot see the repo at all (private repo
-//     gated behind missing repository access — GitHub returns 404 instead of
-//     403 to avoid leaking the existence of private repos).
-//   - 403 Forbidden: the token sees the repo but lacks webhook-management
-//     permission, OR is blocked by an org SSO/SAML authorization gate.
-// Returns null for any other error (network, malformed slug, create-hook
-// failures, etc.) so the guidance only fires on the actual symptom.
-export function parseListHooksPermissionStatus(error: string): number | null {
-  const match = error.match(/^list hooks failed: (404|403)\b/)
-  if (match === null) return null
-  return Number(match[1])
-}
-
-// The labels below intentionally mirror github.com's current UI verbatim so a
-// user can grep their settings page for the exact string. If GitHub renames
-// any of these in a future redesign, update both here and the
-// `permissionGuidance` tests in lifecycle.test.ts.
-//
-//   Fine-grained PAT:
-//     Settings → Developer settings → Personal access tokens → Fine-grained tokens
-//     "Resource owner", "Repository access", "Repository permissions" → "Webhooks" → "Read and write", "Metadata" → "Read-only"
-//   GitHub App:
-//     Settings → Developer settings → GitHub Apps → <app> → Permissions & events
-//     "Repository permissions" → "Webhooks" → "Read and write"
-//     Install/configure on the org: <app settings> → Install App / Configure → "Repository access"
-//   Classic PAT (legacy, still supported by GitHub but we don't surface it in
-//     channel-add prompts):
-//     Settings → Developer settings → Personal access tokens (classic)
-//     Scope: "admin:repo_hook" (or full "repo" for private repositories)
-export function buildPermissionGuidance(
-  authType: 'pat' | 'app',
-  failures: ReadonlyArray<{ repo: string; status: number }>,
-): string {
-  const repoList = failures.map((f) => `${f.repo} (${f.status})`).join(', ')
-  const lines: string[] = [
-    `[github] webhook setup needs more access for: ${repoList}.`,
-    '  - 404 from GitHub means the token cannot see the repo (GitHub hides private repos behind 404 instead of 403).',
-    '  - 403 means the token sees the repo but lacks webhook permission, or is blocked by org SAML/SSO.',
-    '',
-  ]
-  if (authType === 'pat') {
-    lines.push(
-      '  Fix (fine-grained personal access token):',
-      '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
-      '    2. Under "Resource owner", select the org that owns the failing repos (e.g. the org in the slug above).',
-      '    3. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
-      '    4. Under "Repository permissions", set "Webhooks" to "Read and write" and "Metadata" to "Read-only".',
-      '    5. Save. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.',
-      '',
-      '  Or (classic personal access token): grant the "admin:repo_hook" scope (or "repo" for private repos),',
-      '  and on a SAML-protected org click "Authorize" next to the token.',
-    )
-  } else {
-    lines.push(
-      '  Fix (GitHub App):',
-      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
-      '    2. Under "Permissions & events" → "Repository permissions", set "Webhooks" to "Read and write". Save.',
-      '    3. From the app page, click "Install App" (or "Configure" if already installed) and select the org that owns the failing repos.',
-      '    4. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
-      '    5. If the app permissions changed in step 2, install owners must accept the updated permissions from the install page before the new access takes effect.',
-    )
+async function runAppPermissionPreflight(
+  logger: GithubAdapterLogger,
+  auth: ReturnType<typeof buildAuthStrategy>,
+  eventAllowlist: readonly string[],
+): Promise<void> {
+  if (auth.getInstallationGrants === undefined) return
+  let grants
+  try {
+    grants = await auth.getInstallationGrants()
+  } catch (err) {
+    logger.warn(`[github] permission preflight skipped: ${err instanceof Error ? err.message : String(err)}`)
+    return
   }
-  return lines.join('\n')
+  const gaps = findPermissionGaps(eventAllowlist, grants.permissions)
+  if (gaps.length === 0) return
+  logger.warn(buildAppPermissionPreflightGuidance(gaps))
 }
 
 function logDeregistrationOutcome(
@@ -368,3 +358,7 @@ function logDeregistrationOutcome(
     else logger.warn(`[github] webhook detach failed for ${h.repo}#${h.hookId}: ${h.error ?? 'unknown error'}`)
   }
 }
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}