typeclaw 0.18.0 → 0.19.0

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

@@ -13,8 +13,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
@@ -178,17 +178,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,
@@ -242,23 +235,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 +319,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 {

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'
@@ -61,6 +62,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 +100,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 => {
@@ -176,17 +184,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 +213,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.
@@ -291,6 +315,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 +455,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' }

package/src/channels/adapters/slack-bot-slash-commands.ts

@@ -135,7 +135,9 @@ export const SLACK_SLASH_REPLY_AMBIGUOUS =
 export function commandResultReply(result: ExecuteCommandResult): string {
   switch (result.kind) {
     case 'handled':
-      return SLACK_SLASH_REPLY_ABORTED
+      // Dynamic commands (e.g. /help) carry their own reply; static control
+      // commands (/stop) leave it undefined and fall back to the fixed string.
+      return result.reply ?? SLACK_SLASH_REPLY_ABORTED
     case 'no-live-session':
       return SLACK_SLASH_REPLY_NO_LIVE_SESSION
     case 'permission-denied':

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

@@ -51,7 +51,7 @@ import { slackTsToMillis } from './slack-bot-time'
 // slash_commands events we route vs drop. The ui.test.ts manifest-drift
 // test asserts equality between this set and SLACK_APP_MANIFEST.features.
 // slash_commands so the two can never silently diverge.
-export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['stop'])
+export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop'])
 
 // Resolvers fall back to the raw id on failure, so a name equal to the id
 // means resolution failed; we render the bare id rather than `id(id)`. The
@@ -459,14 +459,14 @@ export function createSlackMembershipResolver(deps: {
     }
 
     let bots = 0
-    let humans = 0
+    const humanMemberIds: string[] = []
     for (const userId of members.value.members ?? []) {
       const cached = userBotCache.get(userId)
       const isBot = cached ?? (await resolveSlackUserIsBot(fetchFn, deps.token, userId, deps.logger, userBotCache))
       if (isBot) bots++
-      else humans++
+      else humanMemberIds.push(userId)
     }
-    return { humans, bots, fetchedAt: now(), truncated: false }
+    return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated: false, humanMemberIds }
   }
 }
 

package/src/channels/commands.ts

@@ -0,0 +1,10 @@
+import type { CommandInfo } from '@/commands'
+
+// Generated from registry metadata so the listing can never drift from the
+// actual command set. The `/` prefix is canonical across every surface; Slack
+// threads accept the `!` alias for the same names.
+export function formatChannelCommandHelp(commands: readonly CommandInfo[]): string {
+  if (commands.length === 0) return 'No commands are available.'
+  const lines = commands.map((command) => `/${command.name} — ${command.description}`)
+  return ['Available commands:', ...lines].join('\n')
+}

package/src/channels/engagement.ts

@@ -81,11 +81,25 @@ export type EngagementInput = {
 export function decideEngagement(input: EngagementInput): EngagementDecision {
   const { message, config, key, ledger, now, participants, selfAliases, botInThread } = input
 
+  // The human count drives both the sticky-credit gate (below) and the
+  // solo-human fallback (bottom). Compute it once, up front. Peer bots are
+  // excluded — a 1-human-N-bot room is still "solo" for engagement purposes.
+  const effectiveHumans = countEffectiveHumans(participants, input.membership, now)
+  const multiHumanGroup = isMultiHumanGroup(message.isDm, effectiveHumans)
+
   if (config.trigger.includes('dm') && message.isDm) return 'engage'
   if (config.trigger.includes('mention') && message.isBotMention) return 'engage'
   if (config.trigger.includes('reply') && message.replyToBotMessageId !== null) return 'engage'
 
-  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
+  // Sticky credit. ALWAYS consume when present (the credit stays one-shot,
+  // so a later membership change can't resurrect stale conversational
+  // credit), but only let it FORCE engagement outside a multi-human group.
+  // In a group, sticky alone no longer wakes the bot on every follow-up —
+  // the author must re-address us (mention/reply/alias) to re-engage. This
+  // narrows an existing permissive rule in the exact context where it's
+  // harmful; it is NOT a new bot-specific gate (peer bots and humans are
+  // treated identically, via `multiHumanGroup`). See engagement.mdx.
+  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now) && !multiHumanGroup) {
     return 'engage'
   }
 
@@ -169,13 +183,30 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // peer's first message it's caught forever.
   if (textTargetsAnyPeerBot(message.text, participants)) return 'observe'
 
-  const persistedHumans = participants.filter((p) => p.isBot !== true).length
-  const effectiveHumans = resolveEffectiveHumans(persistedHumans, input.membership, now)
   if (effectiveHumans <= 1 && !message.authorIsBot) return 'engage'
 
   return 'observe'
 }
 
+export function countEffectiveHumans(
+  participants: readonly ChannelParticipant[],
+  membership: MembershipCount | null,
+  now: number,
+): number {
+  const persistedHumans = participants.filter((p) => p.isBot !== true).length
+  return resolveEffectiveHumans(persistedHumans, membership, now)
+}
+
+// A multi-human group is the one place where the chatty "reply to every
+// follow-up" behavior (sticky credit, and the prompt's default eagerness) is
+// wrong. DMs — 1:1, or platform group-DMs reached via the `dm` trigger — and
+// solo-human channels keep the back-and-forth. The router reuses this to
+// decide both sticky suppression and the group-chat prompt nudge, so the two
+// stay in lockstep off one definition.
+export function isMultiHumanGroup(isDm: boolean, effectiveHumans: number): boolean {
+  return !isDm && effectiveHumans > 1
+}
+
 function textTargetsAnyPeerBot(text: string, participants: readonly ChannelParticipant[]): boolean {
   const haystack = text.toLocaleLowerCase()
   for (const p of participants) {

package/src/channels/github-token-bridge.ts

@@ -0,0 +1,42 @@
+// Decoupled from ChannelRouter on purpose: minting a token for an arbitrary
+// bash `gh` command is adjacent to channels but is not routing, and a global
+// singleton would leak resolver state across tests. One instance is created in
+// run/index.ts and threaded to both the plugin loader and the channel manager.
+
+export type GithubTokenResolveResult = { kind: 'token'; token: string } | { kind: 'unavailable'; reason: string }
+
+export type ResolveGithubTokenForRepo = (repoSlug: string) => Promise<GithubTokenResolveResult>
+
+export type GithubTokenBridge = {
+  resolveTokenForRepo: ResolveGithubTokenForRepo
+  registerResolver: (resolver: (repoSlug: string) => Promise<string>) => () => void
+}
+
+const NO_RESOLVER_REASON =
+  'GitHub App token unavailable; the GitHub channel adapter is not running or failed to start. ' +
+  'Check `typeclaw logs` and `secrets.json#channels.github`.'
+
+export function createGithubTokenBridge(): GithubTokenBridge {
+  let current: ((repoSlug: string) => Promise<string>) | null = null
+
+  return {
+    resolveTokenForRepo: async (repoSlug) => {
+      const resolver = current
+      if (resolver === null) return { kind: 'unavailable', reason: NO_RESOLVER_REASON }
+      try {
+        const token = await resolver(repoSlug)
+        return { kind: 'token', token }
+      } catch (err) {
+        return { kind: 'unavailable', reason: err instanceof Error ? err.message : String(err) }
+      }
+    },
+    registerResolver: (resolver) => {
+      current = resolver
+      return () => {
+        // Only clear if still the active resolver: a stop() racing a newer
+        // start() must not wipe the newer registration.
+        if (current === resolver) current = null
+      }
+    },
+  }
+}

package/src/channels/index.ts

@@ -1,4 +1,10 @@
 export { createChannelManager, type ChannelManager, type ChannelManagerOptions } from './manager'
+export {
+  createGithubTokenBridge,
+  type GithubTokenBridge,
+  type GithubTokenResolveResult,
+  type ResolveGithubTokenForRepo,
+} from './github-token-bridge'
 export {
   createChannelRouter,
   type ChannelRouter,

package/src/channels/manager.ts

@@ -12,6 +12,7 @@ import { createGithubAdapter, type GithubAdapter } from './adapters/github'
 import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
 import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
 import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
+import type { GithubTokenBridge } from './github-token-bridge'
 import { createChannelRouter, type ChannelRouter, type ClaimHandler, type CreateSessionForChannel } from './router'
 import {
   ADAPTER_IDS,
@@ -84,6 +85,10 @@ export type ChannelManagerOptions = {
   // Production wiring (`src/run/index.ts`) always passes the agent's
   // Stream; tests typically omit it.
   stream?: Stream
+  // Write-side of the GithubTokenBridge. The github adapter publishes its
+  // per-repo App token minter here on start (App auth only) so plugin hooks
+  // can resolve a token for ad-hoc `gh` commands. Tests omit it.
+  githubTokenBridge?: GithubTokenBridge
 }
 
 export type ChannelManager = {
@@ -199,6 +204,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
         logger,
         tunnelUrl: () => options.tunnelUrlForChannel?.('github') ?? null,
         tunnelConfiguredForChannel: () => options.tunnelConfiguredForChannel?.('github') ?? false,
+        ...(options.githubTokenBridge !== undefined ? { githubTokenBridge: options.githubTokenBridge } : {}),
       })
     }
     if (name === 'telegram-bot') {

package/src/channels/membership.ts

@@ -21,6 +21,15 @@ export type MembershipCount = {
   bots: number
   fetchedAt: number
   truncated: boolean
+  // Identities of the human members, present ONLY when the adapter enumerated
+  // the COMPLETE current membership and classified every listed member in the
+  // same pass that produced `humans`. When set, `humanMemberIds.length` equals
+  // `humans` by construction, so a consumer can prove "every human in the room
+  // is X" by resolving each id — something the bare `humans` count cannot do.
+  // Left undefined by approximate/truncated/history-derived reads and by
+  // adapters that cannot enumerate members (Telegram, KakaoTalk); consumers
+  // that need a completeness proof must fail closed when it is absent.
+  humanMemberIds?: readonly string[]
 }
 
 export type MembershipResolverFailure = { kind: 'transient' } | { kind: 'permanent' }