typeclaw 0.10.0 → 0.11.1

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))
+}

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

@@ -1,11 +1,18 @@
 import type { OutboundCallback, OutboundMessage, SendResult } from '@/channels/types'
 
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import {
+  buildOutboundPermissionGuidance,
+  type GithubAuthType,
+  isOutboundPermissionDenial,
+  type OutboundEndpointKind,
+} from './permission-guidance'
 
 export type GithubOutboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
 
 export function createGithubOutboundCallback(deps: {
   token: () => Promise<string>
+  authType: GithubAuthType
   logger: GithubOutboundLogger
   fetchImpl?: typeof fetch
 }): OutboundCallback {
@@ -22,19 +29,35 @@ export function createGithubOutboundCallback(deps: {
     if (target === null) return { ok: false, error: `invalid GitHub chat: ${msg.chat}` }
 
     if (target.kind === 'discussion') {
-      return await postDiscussionComment({ ...deps, fetchImpl, repo, discussionNumber: target.number, body })
+      return await postDiscussionComment({
+        ...deps,
+        fetchImpl,
+        repo,
+        discussionNumber: target.number,
+        body,
+      })
     }
 
-    const endpoint =
-      target.kind === 'pr' && msg.thread !== null && msg.thread !== undefined && msg.thread !== ''
-        ? `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/pulls/${target.number}/comments/${encodeURIComponent(msg.thread)}/replies`
-        : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${target.number}/comments`
-    return await postJson(fetchImpl, await deps.token(), endpoint, { body })
+    const isPrReviewReply = target.kind === 'pr' && msg.thread !== null && msg.thread !== undefined && msg.thread !== ''
+    const endpoint = isPrReviewReply
+      ? `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/pulls/${target.number}/comments/${encodeURIComponent(msg.thread ?? '')}/replies`
+      : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${target.number}/comments`
+    return await postJson(
+      fetchImpl,
+      await deps.token(),
+      endpoint,
+      { body },
+      {
+        authType: deps.authType,
+        endpointKind: isPrReviewReply ? 'pr-review-reply' : 'issue-comment',
+      },
+    )
   }
 }
 
 async function postDiscussionComment(options: {
   token: () => Promise<string>
+  authType: GithubAuthType
   fetchImpl: typeof fetch
   repo: RepoRef
   discussionNumber: number
@@ -43,14 +66,21 @@ async function postDiscussionComment(options: {
   const discussionId = await fetchDiscussionId(options)
   if (!discussionId.ok) return discussionId
   const mutation = `mutation($discussionId:ID!,$body:String!){addDiscussionComment(input:{discussionId:$discussionId,body:$body}){comment{id}}}`
-  return await postGraphql(options.fetchImpl, await options.token(), mutation, {
-    discussionId: discussionId.id,
-    body: options.body,
-  })
+  return await postGraphql(
+    options.fetchImpl,
+    await options.token(),
+    mutation,
+    {
+      discussionId: discussionId.id,
+      body: options.body,
+    },
+    { authType: options.authType, endpointKind: 'discussion-comment' },
+  )
 }
 
 async function fetchDiscussionId(options: {
   token: () => Promise<string>
+  authType: GithubAuthType
   fetchImpl: typeof fetch
   repo: RepoRef
   discussionNumber: number
@@ -65,6 +95,7 @@ async function fetchDiscussionId(options: {
       name: options.repo.name,
       number: options.discussionNumber,
     },
+    { authType: options.authType, endpointKind: 'discussion-comment' },
   )
   if (!result.ok) return result
   const id = result.data.repository?.discussion?.id
@@ -76,8 +107,9 @@ async function postGraphql(
   token: string,
   query: string,
   variables: Record<string, unknown>,
+  guidance: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
 ): Promise<SendResult> {
-  const result = await graphql(fetchImpl, token, query, variables)
+  const result = await graphql(fetchImpl, token, query, variables, guidance)
   return result.ok ? { ok: true } : { ok: false, error: result.error }
 }
 
@@ -86,6 +118,7 @@ async function graphql<T>(
   token: string,
   query: string,
   variables: Record<string, unknown>,
+  guidance: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
 ): Promise<{ ok: true; data: T } | { ok: false; error: string }> {
   try {
     const response = await fetchImpl(`${GITHUB_API_BASE}/graphql`, {
@@ -95,10 +128,15 @@ async function graphql<T>(
     })
     const raw = (await response.json()) as { data?: T; errors?: Array<{ message?: string }> }
     if (!response.ok || raw.errors !== undefined) {
-      return {
-        ok: false,
-        error: raw.errors?.map((e) => e.message ?? 'unknown').join('; ') ?? `HTTP ${response.status}`,
-      }
+      // GraphQL errors carry a permission-denial in their `errors[].type` =
+      // 'FORBIDDEN' or message text. Match on either the HTTP 403 (rare for
+      // GraphQL) or the literal denial string in any error message.
+      const message = raw.errors?.map((e) => e.message ?? 'unknown').join('; ') ?? `HTTP ${response.status}`
+      const baseError = response.ok ? message : `GitHub API ${response.status}: ${message}`
+      const decorated = isOutboundPermissionDenial(response.ok ? 403 : response.status, message)
+        ? `${baseError}${buildOutboundPermissionGuidance(guidance)}`
+        : baseError
+      return { ok: false, error: decorated }
     }
     if (raw.data === undefined) return { ok: false, error: 'GraphQL response missing data' }
     return { ok: true, data: raw.data }
@@ -107,7 +145,13 @@ async function graphql<T>(
   }
 }
 
-async function postJson(fetchImpl: typeof fetch, token: string, url: string, payload: unknown): Promise<SendResult> {
+async function postJson(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  payload: unknown,
+  guidance: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
+): Promise<SendResult> {
   try {
     const response = await fetchImpl(url, {
       method: 'POST',
@@ -116,7 +160,11 @@ async function postJson(fetchImpl: typeof fetch, token: string, url: string, pay
     })
     if (response.ok) return { ok: true }
     const text = await response.text().catch(() => '')
-    return { ok: false, error: `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}` }
+    const baseError = `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}`
+    const decorated = isOutboundPermissionDenial(response.status, text)
+      ? `${baseError}${buildOutboundPermissionGuidance(guidance)}`
+      : baseError
+    return { ok: false, error: decorated }
   } catch (err) {
     return { ok: false, error: describe(err) }
   }