typeclaw 0.18.0 → 0.20.0

package/src/channels/adapters/discord-bot.ts

@@ -42,6 +42,7 @@ import {
 // commands here is the documented extension point: declare the entry here,
 // then add the matching handler in createChannelRouter's command registry.
 const SLASH_COMMANDS: readonly DiscordCommandDeclaration[] = [
+  { name: 'help', description: 'List available commands' },
   { name: 'stop', description: 'Abort the current turn in this channel' },
 ]
 const SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(SLASH_COMMANDS.map((c) => c.name))
@@ -147,6 +148,116 @@ type DiscordGuildPreview = {
 
 type DiscordGuildMember = {
   user?: { id?: string; bot?: boolean }
+  roles?: string[]
+}
+
+type DiscordPermissionOverwrite = {
+  id?: string
+  type?: number
+  allow?: string
+  deny?: string
+}
+
+// Discord channel `type` values that are threads. A thread's own
+// permission_overwrites are empty and its `parent_id` points at its parent
+// channel (not a category), so the normal "compute from this channel's
+// overwrites" path would treat a thread as fully public. We refuse to count
+// threads channel-scoped and fall back instead — fail-closed.
+const DISCORD_THREAD_CHANNEL_TYPES: ReadonlySet<number> = new Set([10, 11, 12])
+
+type DiscordChannelObject = {
+  type?: number
+  permission_overwrites?: DiscordPermissionOverwrite[]
+}
+
+type DiscordRole = {
+  id?: string
+  permissions?: string
+}
+
+type DiscordGuildObject = {
+  owner_id?: string
+  roles?: DiscordRole[]
+}
+
+// Discord permission bits. Discord serialises permission bitsets as decimal
+// STRINGS that can exceed Number.MAX_SAFE_INTEGER, so all bit math is done in
+// BigInt. Only the two bits this resolver needs are named.
+const DISCORD_PERMISSION_VIEW_CHANNEL = 0x400n
+const DISCORD_PERMISSION_ADMINISTRATOR = 0x8n
+
+function parsePermissionBits(raw: string | undefined): bigint {
+  if (raw === undefined || raw === '') return 0n
+  try {
+    return BigInt(raw)
+  } catch {
+    return 0n
+  }
+}
+
+// Computes whether a single member can VIEW_CHANNEL on a normal guild channel,
+// following Discord's documented resolution order:
+//   base = @everyone role perms OR all of the member's role perms
+//   → owner or ADMINISTRATOR short-circuits to visible
+//   → @everyone channel overwrite (clear deny bits, then set allow bits)
+//   → all matching role overwrites combined (OR every deny, OR every allow;
+//     apply denies then allows)
+//   → member-specific overwrite (clear deny, set allow)
+// Returns null when the data is insufficient to decide (a member references a
+// role absent from the guild role map), so the caller can fail closed rather
+// than guess.
+function memberCanViewChannel(args: {
+  guildId: string
+  ownerId: string | undefined
+  rolePermissions: ReadonlyMap<string, bigint>
+  overwrites: ReadonlyMap<string, { allow: bigint; deny: bigint }>
+  memberId: string | undefined
+  memberRoleIds: readonly string[]
+}): boolean | null {
+  const { guildId, ownerId, rolePermissions, overwrites, memberId, memberRoleIds } = args
+
+  if (memberId !== undefined && ownerId !== undefined && memberId === ownerId) return true
+
+  // Discord's `@everyone` role id always equals the guild id, so the guild id
+  // keys both the base @everyone permissions and the @everyone overwrite.
+  let base = rolePermissions.get(guildId) ?? 0n
+  for (const roleId of memberRoleIds) {
+    const perms = rolePermissions.get(roleId)
+    if (perms === undefined) return null
+    base |= perms
+  }
+
+  if ((base & DISCORD_PERMISSION_ADMINISTRATOR) !== 0n) return true
+
+  let perms = base
+
+  const everyoneOverwrite = overwrites.get(guildId)
+  if (everyoneOverwrite !== undefined) {
+    perms &= ~everyoneOverwrite.deny
+    perms |= everyoneOverwrite.allow
+  }
+
+  let roleDeny = 0n
+  let roleAllow = 0n
+  for (const roleId of memberRoleIds) {
+    const overwrite = overwrites.get(roleId)
+    if (overwrite !== undefined) {
+      roleDeny |= overwrite.deny
+      roleAllow |= overwrite.allow
+    }
+  }
+  perms &= ~roleDeny
+  perms |= roleAllow
+
+  if (memberId !== undefined) {
+    const memberOverwrite = overwrites.get(memberId)
+    if (memberOverwrite !== undefined) {
+      perms &= ~memberOverwrite.deny
+      perms |= memberOverwrite.allow
+    }
+  }
+
+  return (perms & DISCORD_PERMISSION_VIEW_CHANNEL) !== 0n
 }
 
 export function createDiscordMembershipResolver(deps: {
@@ -206,14 +317,136 @@ export function createDiscordMembershipResolver(deps: {
       return members.failure
     }
 
-    let bots = 0
-    let humans = 0
-    for (const member of members.value) {
-      if (member.user?.bot === true) bots++
-      else humans++
+    // Guild `/members` returns the whole guild, not the channel. A bot or
+    // human that cannot VIEW_CHANNEL the target channel is not in the room and
+    // not a prompt-injection surface, so it must not be counted — otherwise a
+    // private channel of "operator + agent bot" inside a multi-bot guild reads
+    // as bots>1 and the grant_role relaxation (provesOnlyAgentBotPresent)
+    // false-refuses. Resolve channel visibility for each member; on ANY
+    // inability to decide, fall back rather than over- or under-count.
+    // `key.thread ?? key.chat` mirrors the history callback's channel-id
+    // resolution: today Discord stores a thread's own snowflake in `chat` with
+    // `thread` null, but a future caller that passes `chat=parent,
+    // thread=threadId` must scope visibility to the thread, not the parent.
+    const scoped = await scopeMembersToChannel({
+      fetchFn,
+      token: deps.token,
+      logger: deps.logger,
+      guildId: key.workspace,
+      channelId: key.thread ?? key.chat,
+      members: members.value,
+    })
+    if (scoped === 'fallback') return await fallback()
+
+    return scoped.everyHumanIdentified
+      ? {
+          humans: scoped.humans,
+          bots: scoped.bots,
+          fetchedAt: now(),
+          truncated: false,
+          humanMemberIds: scoped.humanMemberIds,
+        }
+      : { humans: scoped.humans, bots: scoped.bots, fetchedAt: now(), truncated: false }
+  }
+}
+
+type ScopedMembership = {
+  humans: number
+  bots: number
+  humanMemberIds: string[]
+  everyHumanIdentified: boolean
+}
+
+// Filters a guild member list down to those who can VIEW_CHANNEL the target
+// channel, then counts humans/bots over that visible set. Returns 'fallback'
+// when channel visibility cannot be computed completely (channel/guild fetch
+// failure, a member referencing an unknown role, or a thread channel whose
+// visibility this resolver does not model) — the caller then derives from
+// history (truncated:true), keeping every security consumer fail-closed.
+async function scopeMembersToChannel(args: {
+  fetchFn: typeof fetch
+  token: string
+  logger: DiscordBotAdapterLogger
+  guildId: string
+  channelId: string
+  members: readonly DiscordGuildMember[]
+}): Promise<ScopedMembership | 'fallback'> {
+  const { fetchFn, token, logger, guildId, channelId, members } = args
+
+  const [channel, guild] = await Promise.all([
+    fetchDiscordJson<DiscordChannelObject>(fetchFn, `${DISCORD_API_BASE}/channels/${channelId}`, token),
+    fetchDiscordJson<DiscordGuildObject>(fetchFn, `${DISCORD_API_BASE}/guilds/${guildId}`, token),
+  ])
+  if (!channel.ok) {
+    logger.warn(
+      `[discord-bot] membership channel=${channelId} fetch failed: ${channel.reason}; deriving from recent message authors`,
+    )
+    return 'fallback'
+  }
+  if (!guild.ok) {
+    logger.warn(
+      `[discord-bot] membership guild=${guildId} fetch failed: ${guild.reason}; deriving from recent message authors`,
+    )
+    return 'fallback'
+  }
+
+  if (channel.value.type !== undefined && DISCORD_THREAD_CHANNEL_TYPES.has(channel.value.type)) {
+    // A thread inherits visibility from its parent channel and (for private
+    // threads) an explicit member list; we do not model either here. Fall
+    // back rather than treat the thread as world-visible.
+    logger.warn(
+      `[discord-bot] membership channel=${channelId} is a thread; deriving from recent message authors instead of channel-scoped enumeration`,
+    )
+    return 'fallback'
+  }
+
+  const rolePermissions = new Map<string, bigint>()
+  for (const role of guild.value.roles ?? []) {
+    if (role.id !== undefined) rolePermissions.set(role.id, parsePermissionBits(role.permissions))
+  }
+
+  const overwrites = new Map<string, { allow: bigint; deny: bigint }>()
+  for (const overwrite of channel.value.permission_overwrites ?? []) {
+    if (overwrite.id === undefined) continue
+    overwrites.set(overwrite.id, {
+      allow: parsePermissionBits(overwrite.allow),
+      deny: parsePermissionBits(overwrite.deny),
+    })
+  }
+
+  let humans = 0
+  let bots = 0
+  const humanMemberIds: string[] = []
+  let everyHumanIdentified = true
+
+  for (const member of members) {
+    const visible = memberCanViewChannel({
+      guildId,
+      ownerId: guild.value.owner_id,
+      rolePermissions,
+      overwrites,
+      memberId: member.user?.id,
+      memberRoleIds: member.roles ?? [],
+    })
+    if (visible === null) {
+      logger.warn(
+        `[discord-bot] membership channel=${channelId} member references unknown role; deriving from recent message authors`,
+      )
+      return 'fallback'
+    }
+    if (!visible) continue
+
+    if (member.user?.bot === true) {
+      bots++
+      continue
     }
-    return { humans, bots, fetchedAt: now(), truncated: false }
+    humans++
+    const userId = member.user?.id
+    if (userId === undefined) everyHumanIdentified = false
+    else humanMemberIds.push(userId)
   }
+
+  return { humans, bots, humanMemberIds, everyHumanIdentified }
 }
 
 type DiscordFetchResult<T> =
@@ -508,7 +741,9 @@ export function createInteractionHandler(
       })
       const replyContent =
         result.kind === 'handled'
-          ? STOP_REPLY_ABORTED
+          ? // Dynamic commands (e.g. /help) carry their own reply; static
+            // control commands (/stop) fall back to the fixed confirmation.
+            (result.reply ?? STOP_REPLY_ABORTED)
           : result.kind === 'no-live-session'
             ? STOP_REPLY_NO_LIVE_SESSION
             : result.kind === 'permission-denied'

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

@@ -4,6 +4,7 @@ import type { InboundMessage } from '@/channels/types'
 
 import type { DeliveryDedup } from './dedup'
 import { isGithubEventAllowed } from './event-allowlist'
+import { encodeGithubReactionRef, type GithubReactionTarget } from './reactions'
 
 export type GithubInboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
 
@@ -13,8 +14,8 @@ export type GithubWebhookHandlerOptions = {
   allowlist: () => readonly string[]
   selfId: () => string | null
   selfLogin: () => string | null
-  // Defaults to 'pat' when omitted. Only 'app' promotes an opened PR to a
-  // review request; see classifyOpenedAsReview for why.
+  // Defaults to 'pat' when omitted. In 'app' mode classifyReviewRequest also
+  // matches the App's decoy reviewer login; see resolveDecoyReviewerLogin.
   authType?: () => 'pat' | 'app'
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
@@ -109,6 +110,7 @@ export function classifyGithubInbound(
       user,
       selfLogin,
       comment.created_at,
+      { kind: 'issue-comment', owner: repository.owner, repo: repository.name, commentId: id },
     )
   }
 
@@ -127,6 +129,7 @@ export function classifyGithubInbound(
       readUser(comment.user),
       selfLogin,
       comment.created_at,
+      { kind: 'pr-review-comment', owner: repository.owner, repo: repository.name, commentId: id },
     )
   }
 
@@ -144,6 +147,7 @@ export function classifyGithubInbound(
       readUser(comment.user),
       selfLogin,
       comment.created_at,
+      null,
     )
   }
 
@@ -160,6 +164,7 @@ export function classifyGithubInbound(
       readUser(issue.user),
       selfLogin,
       issue.created_at,
+      { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
     )
   }
 
@@ -178,17 +183,10 @@ export function classifyGithubInbound(
         number,
         base,
         selfLogin,
+        authType: options?.authType ?? 'pat',
         teamIsBotMember: options?.teamIsBotMember,
       })
     }
-    // A GitHub App cannot be added to a PR's requested_reviewers, so it never
-    // receives a review_requested event targeting itself. The opened event is
-    // the only signal it can act on, so in App mode an opened PR is promoted to
-    // a review request. A PAT-backed bot is a real user that can be requested,
-    // so it waits for the explicit request instead of reviewing every PR.
-    if (action === 'opened' && options?.authType === 'app') {
-      return classifyOpenedAsReview({ payload, pr, number, base, selfLogin })
-    }
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
       pr.body,
@@ -196,6 +194,7 @@ export function classifyGithubInbound(
       readUser(pr.user),
       selfLogin,
       pr.created_at,
+      { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
     )
   }
 
@@ -213,6 +212,7 @@ export function classifyGithubInbound(
       readUser(review.user),
       selfLogin,
       review.submitted_at,
+      null,
     )
   }
 
@@ -229,6 +229,7 @@ export function classifyGithubInbound(
       readUser(discussion.user),
       selfLogin,
       discussion.created_at,
+      null,
     )
   }
 
@@ -242,23 +243,46 @@ type ReviewRequestInput = {
   number: number
   base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
   selfLogin: string | null
+  authType: 'pat' | 'app'
   teamIsBotMember: boolean | undefined
 }
 
+// A GitHub App can never be a `requested_reviewer` — that field only holds
+// real user accounts, and the App actor (`slug[bot]`) is not one. The
+// supported workaround is a decoy user account named after the App that an
+// operator requests instead (see docs/content/docs/internals/github-decoy-reviewer.mdx).
+// Its login is, by convention, the App slug — i.e. `selfLogin` with the
+// `[bot]` suffix removed (`my-app[bot]` → `my-app`). This is the single seam
+// where that login is resolved: when the decoy account's real login diverges
+// from the slug, a future config field replaces this derivation without
+// touching the matcher. PAT auth has no decoy (the bot IS a real user that can
+// be requested directly), so it returns null.
+const BOT_LOGIN_SUFFIX = '[bot]'
+
+function resolveDecoyReviewerLogin(selfLogin: string, authType: 'pat' | 'app'): string | null {
+  if (authType !== 'app') return null
+  if (!selfLogin.endsWith(BOT_LOGIN_SUFFIX)) return null
+  const slug = selfLogin.slice(0, -BOT_LOGIN_SUFFIX.length)
+  return slug !== '' ? slug : null
+}
+
 function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null {
-  const { action, payload, pr, number, base, selfLogin, teamIsBotMember } = input
+  const { action, payload, pr, number, base, selfLogin, authType, teamIsBotMember } = input
   if (selfLogin === null) return null
+  const decoyLogin = resolveDecoyReviewerLogin(selfLogin, authType)
   const sender = readUser(payload.sender)
   if (sender === null) return null
-  // Self-loop guard: if the bot itself requested (or un-requested) the
+  // Self-loop guard: if the bot (or its decoy) requested/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
+  if (sender.login === selfLogin || (decoyLogin !== null && sender.login === decoyLogin)) return null
 
   const requestedUser = readUser(payload.requested_reviewer)
   const requestedTeam = readReviewerTeam(payload.requested_team)
 
-  const isMeAsUser = requestedUser !== null && requestedUser.login === selfLogin
+  const isMeAsUser =
+    requestedUser !== null &&
+    (requestedUser.login === selfLogin || (decoyLogin !== null && requestedUser.login === decoyLogin))
   const isMyTeam = requestedTeam !== null && teamIsBotMember === true
   if (!isMeAsUser && !isMyTeam) return null
 
@@ -303,47 +327,6 @@ function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null
   }
 }
 
-type OpenedAsReviewInput = {
-  payload: Record<string, unknown>
-  pr: Record<string, unknown>
-  number: number
-  base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
-  selfLogin: string | null
-}
-
-function classifyOpenedAsReview(input: OpenedAsReviewInput): InboundMessage | null {
-  const { payload, pr, number, base, selfLogin } = input
-  if (selfLogin === null) return null
-  const sender = readUser(payload.sender)
-  if (sender === null) return null
-  if (sender.login === selfLogin) 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 text =
-    `@${sender.login} requested your review on PR #${number}: "${title}".${branchSegment}` +
-    ' Please review the changes line-by-line and post your feedback.'
-
-  const updatedAt = readString(pr, 'updated_at') ?? ''
-  const prId = readNumber(pr, 'id') ?? number
-
-  return {
-    ...base,
-    chat: `pr:${number}`,
-    thread: null,
-    text,
-    externalMessageId: `pr-${prId}-opened-${updatedAt}`,
-    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 {
@@ -365,6 +348,7 @@ function buildInbound(
   user: GithubUser | null,
   selfLogin: string | null,
   rawTs: unknown,
+  reactionTarget: GithubReactionTarget | null,
 ): InboundMessage | null {
   if (user === null) return null
   const text = typeof rawText === 'string' ? rawText : ''
@@ -372,6 +356,7 @@ function buildInbound(
     ...key,
     text,
     externalMessageId: String(id),
+    ...(reactionTarget !== null ? { reactionRef: encodeGithubReactionRef(reactionTarget) } : {}),
     authorId: String(user.id),
     authorName: user.login,
     authorIsBot: user.type === 'Bot',

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

@@ -1,3 +1,4 @@
+import type { GithubTokenBridge } from '@/channels/github-token-bridge'
 import type { ChannelRouter } from '@/channels/router'
 import type { ChannelAdapterConfig, GithubAdapterConfig } from '@/channels/schema'
 import { resolveSecret } from '@/secrets/resolve'
@@ -18,6 +19,7 @@ import {
   buildPermissionGuidance,
   parseListHooksPermissionStatus,
 } from './permission-guidance'
+import { createGithubReactionCallback } from './reactions'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
@@ -61,6 +63,12 @@ export type GithubAdapterOptions = {
   // Test-only: replaces `setInterval` so tests can control when the
   // background refresh fires without waiting on real wall-clock time.
   setInterval?: (handler: () => void, ms: number) => { clear: () => void }
+  // Write-side of the GithubTokenBridge. On App-auth start the adapter
+  // registers a per-repo minter here so plugin hooks can resolve a token for
+  // ad-hoc `gh` commands; it unregisters on stop and on start rollback. PAT
+  // auth does not register (the seeded GH_TOKEN already covers every repo a
+  // classic PAT can reach, and a fine-grained PAT cannot be re-minted per repo).
+  githubTokenBridge?: GithubTokenBridge
 }
 
 export type GithubAdapter = {
@@ -93,6 +101,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
   let tokenRefreshTimer: { clear: () => void } | null = null
+  let unregisterTokenBridge: (() => void) | null = null
   const workspaceByChat = new Map<string, string>()
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
@@ -111,6 +120,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     logger,
     fetchImpl,
   })
+  const reaction = createGithubReactionCallback({
+    token: authToken,
+    authType: options.secrets.auth.type,
+    fetchImpl,
+  })
   const history = createGithubHistoryCallback({
     token: authToken,
     fetchImpl,
@@ -153,6 +167,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // Register all callbacks before binding the HTTP listener so the router
       // is fully wired before any webhook can arrive.
       options.router.registerOutbound('github', outbound)
+      options.router.registerReaction('github', reaction)
       options.router.registerTyping('github', typing)
       options.router.registerHistory('github', history)
       options.router.registerMembership('github', membership)
@@ -164,6 +179,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         // Listener failed — roll back all registrations so stop() is a no-op
         // and the manager can report the failure cleanly.
         options.router.unregisterOutbound('github', outbound)
+        options.router.unregisterReaction('github', reaction)
         options.router.unregisterTyping('github', typing)
         options.router.unregisterHistory('github', history)
         options.router.unregisterMembership('github', membership)
@@ -176,17 +192,15 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         throw err
       }
       started = true
-      // GH_TOKEN is a single process-wide env var the container's `gh` CLI
-      // reads, but a GitHub App spanning multiple owners has no single correct
-      // token. Seed/refresh it only when exactly one repo is configured (PAT,
-      // or App with one unambiguous installation). With multiple repos we skip
-      // the global seed: ad-hoc `gh` calls must target a specific repo, and the
-      // adapter's own API calls always resolve a repo-scoped token via authToken.
-      const ghTokenRepo = ghTokenSeedRepo(options.configRef().repos ?? [])
-      const seedGhToken = async (): Promise<void> => {
-        process.env.GH_TOKEN = await auth.token(ghTokenRepo === null ? undefined : { repoSlug: ghTokenRepo })
-      }
-      if (ghTokenRepo !== null || options.secrets.auth.type === 'pat') {
+      // Seed the process-wide GH_TOKEN when it's unambiguous; skip otherwise.
+      // See ghTokenSeedDecision for why one owner is required. On skip, authToken
+      // still resolves a repo-scoped token per call for the adapter's own traffic.
+      const seed = ghTokenSeedDecision(options.secrets.auth.type, options.configRef().repos ?? [])
+      if (seed.kind === 'seed') {
+        const seedContext = seed.context
+        const seedGhToken = async (): Promise<void> => {
+          process.env.GH_TOKEN = await auth.token(seedContext)
+        }
         await seedGhToken()
         const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
         if (tokenRefreshIntervalMs > 0) {
@@ -207,10 +221,28 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         }
       } else {
         logger.info(
-          '[github] multiple repos configured across possibly-different owners; GH_TOKEN not seeded globally. ' +
-            'Ad-hoc `gh` commands should set a repo-scoped token explicitly.',
+          `${GH_TOKEN_SKIP_LOG[seed.reason]} Ad-hoc \`gh\` commands should set a repo-scoped token explicitly.`,
         )
       }
+      if (options.secrets.auth.type === 'app' && options.githubTokenBridge !== undefined) {
+        // Gate ad-hoc `gh` minting on the configured repos[]. The slug arrives
+        // from an attacker-controllable -R/--repo flag (untrusted PR/issue
+        // content can prompt-inject it); without this an injected `-R any/repo`
+        // would mint an installation-wide token for any repo the App is installed
+        // on — a cross-tenant leak under a multi-owner App. Enforced here, not in
+        // the parser, because this adapter is the authority that owns repos[].
+        unregisterTokenBridge = options.githubTokenBridge.registerResolver((repoSlug) => {
+          const allowed = new Set((options.configRef().repos ?? []).map(canonicalRepoSlug))
+          if (!allowed.has(canonicalRepoSlug(repoSlug))) {
+            throw new Error(
+              `repo \`${repoSlug}\` is not in this agent's configured \`channels.github.repos[]\`; ` +
+                'refusing to mint a GitHub App token for it. Target a configured repo, ' +
+                'or add it to `repos[]` if the agent is meant to operate there.',
+            )
+          }
+          return auth.token({ repoSlug })
+        })
+      }
       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.
@@ -268,6 +300,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       if (!started) return
       started = false
       options.router.unregisterOutbound('github', outbound)
+      options.router.unregisterReaction('github', reaction)
       options.router.unregisterTyping('github', typing)
       options.router.unregisterHistory('github', history)
       options.router.unregisterMembership('github', membership)
@@ -291,6 +324,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         tokenRefreshTimer.clear()
         tokenRefreshTimer = null
       }
+      if (unregisterTokenBridge !== null) {
+        unregisterTokenBridge()
+        unregisterTokenBridge = null
+      }
       await auth.dispose()
       delete process.env.GH_TOKEN
       server = null
@@ -427,11 +464,45 @@ function logDeregistrationOutcome(
   }
 }
 
-// Two repos under the same owner share an installation and could in principle
-// share a global GH_TOKEN, but the marginal value doesn't justify the special
-// case — only a single configured repo yields an unambiguous seed.
-function ghTokenSeedRepo(repos: readonly string[]): string | null {
-  return repos.length === 1 ? (repos[0] ?? null) : null
+type GhTokenSeedDecision =
+  | { kind: 'seed'; context?: GithubAuthContext }
+  | { kind: 'skip'; reason: 'no-repos' | 'multiple-owners' }
+
+const GH_TOKEN_SKIP_LOG: Record<'no-repos' | 'multiple-owners', string> = {
+  'no-repos':
+    '[github] no repos[] configured; GH_TOKEN not seeded globally (cannot prove which App installation to use).',
+  'multiple-owners': '[github] repos span multiple owners (multiple App installations); GH_TOKEN not seeded globally.',
+}
+
+// Decides how to seed the process-wide GH_TOKEN. PATs aren't installation-scoped
+// (seed context-free). For App auth we seed from a configured repo slug, which
+// resolves the installation via repos/{owner}/{repo}/installation — the only
+// lookup that works for both org- and user-owned repos. One owner is required:
+// no-repos can't prove an installation, multi-owner needs >1 token.
+function ghTokenSeedDecision(authType: 'pat' | 'app', repos: readonly string[]): GhTokenSeedDecision {
+  if (authType === 'pat') return { kind: 'seed' }
+  const slugs = [...new Set(repos.filter(isWellFormedSlug))].sort()
+  if (slugs.length === 0) return { kind: 'skip', reason: 'no-repos' }
+  const owners = new Set(slugs.map((slug) => slug.split('/')[0]))
+  if (owners.size > 1) return { kind: 'skip', reason: 'multiple-owners' }
+  return { kind: 'seed', context: { repoSlug: slugs[0] } }
+}
+
+function isWellFormedSlug(repo: string): boolean {
+  const [owner, name, ...rest] = repo.split('/')
+  return owner !== undefined && owner !== '' && name !== undefined && name !== '' && rest.length === 0
+}
+
+// Canonical form for repos[] allowlist comparison so the gate can't be bypassed
+// by case, a trailing slash, or a `.git` suffix (GitHub treats owner/name
+// case-insensitively). Applied identically to both configured repos[] and the
+// runtime slug before exact Set membership.
+function canonicalRepoSlug(repo: string): string {
+  return repo
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/\.git$/i, '')
+    .toLowerCase()
 }
 
 function defaultSleep(ms: number): Promise<void> {

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

@@ -28,6 +28,10 @@ export function createGithubMembershipResolver(options: {
         if (user.type === 'Bot') bots++
         else humans++
       }
+      // Counts only, no humanMemberIds: GitHub membership is the repo
+      // collaborator list, a different population from the authors that can
+      // comment into a PR/issue turn, so it is not a basis for the channel
+      // grant-role relaxation (see provesOnlyAgentBotPresent in grant-role.ts).
       return { humans, bots, fetchedAt: Date.now(), truncated: users.length >= 100 }
     } catch {
       return { kind: 'transient' }