typeclaw 0.28.0 → 0.28.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/provider-error.ts

@@ -13,7 +13,39 @@ import type { AgentSession } from './index'
 // not by this helper.
 
 export type DetectedProviderError = {
+  // Raw provider text. Safe for logs and operator-only surfaces (TUI,
+  // `typeclaw logs`), but NOT for channels — see `safeMessage`.
   message: string
+  // Redacted, user-facing variant for public/multi-user channels. Known-safe
+  // operational classes (rate/usage limit, billing/quota) map to a canonical
+  // sentence; everything else (malformed-response SDK dumps, unknown failures)
+  // collapses to a generic notice so provider response bodies, URLs, or tokens
+  // can never leak to a channel.
+  safeMessage: string
+}
+
+const GENERIC_SAFE_NOTICE = 'The upstream LLM provider failed. Operators can check `typeclaw logs` for details.'
+
+// Each entry pairs a narrow matcher against the raw provider text with the
+// canonical, leak-free sentence shown in channels. Matchers are intentionally
+// specific: a miss falls through to GENERIC_SAFE_NOTICE rather than echoing raw
+// text, so adding a new class is opt-in and never widens what we expose.
+const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
+  {
+    match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
+    safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',
+  },
+  {
+    match: /\b(billing|quota|insufficient.*(credit|fund|balance)|payment|account is not active)\b/i,
+    safe: 'The upstream LLM provider rejected the request for a billing/quota reason. Operators can check `typeclaw logs` for details.',
+  },
+]
+
+function toSafeMessage(raw: string): string {
+  for (const { match, safe } of SAFE_CLASSES) {
+    if (match.test(raw)) return safe
+  }
+  return GENERIC_SAFE_NOTICE
 }
 
 export function detectProviderError(message: unknown): DetectedProviderError | null {
@@ -25,7 +57,7 @@ export function detectProviderError(message: unknown): DetectedProviderError | n
   // ignore aborts (no surface to render them on).
   if (m.stopReason !== 'error') return null
   const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
-  return { message: text }
+  return { message: text, safeMessage: toSafeMessage(text) }
 }
 
 export type ProviderErrorListener = (error: DetectedProviderError) => void

package/src/agent/tools/channel-reply.ts

@@ -2,6 +2,7 @@ import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { checkFalseReceipt } from '@/channels/github-false-receipt'
+import { evaluateRereviewGuard } from '@/channels/github-rereview-guard'
 import {
   containsKimiToolDelimiter,
   isNoReplySignal,
@@ -159,6 +160,28 @@ export function createChannelReplyTool({
       }
       const falseReceiptNotice = falseReceipt.kind === 'warn' ? falseReceipt.notice : null
 
+      // Re-review stranding guard: block a thread close-out / verdict ack while
+      // the bot still holds its own CHANGES_REQUESTED on this PR, so it can't
+      // silently leave the PR blocked (PR #644). Runs before the resolve so a
+      // blocked close-out never mutates the thread.
+      const rereview = await evaluateRereviewGuard({
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        text,
+        wantsResolve: params.resolve_review_thread === true,
+        isContinue: keepTurnAlive,
+        getReviewState: (req) => router.getReviewState(req),
+      })
+      if (rereview.block) {
+        logger.warn(formatChannelToolFailure('channel_reply', rereview.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${rereview.reason}` }],
+          details: { ok: false, error: rereview.reason },
+        }
+      }
+
       // Resolve BEFORE posting: a successful channel_reply ends the turn, so a
       // resolve attempted "after" the ack would never run (the exact bug this
       // flag fixes). Resolve-failure blocks the reply so the agent never posts

package/src/agent/tools/channel-send.ts

@@ -2,6 +2,7 @@ import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { checkFalseReceipt } from '@/channels/github-false-receipt'
+import { evaluateRereviewGuard } from '@/channels/github-rereview-guard'
 import { recordResolvedThread } from '@/channels/github-review-turn-ledger'
 import {
   containsKimiToolDelimiter,
@@ -176,6 +177,27 @@ export function createChannelSendTool({
       }
       const falseReceiptNotice = falseReceipt.kind === 'warn' ? falseReceipt.notice : null
 
+      // Re-review stranding guard (mirrors channel_reply): block a thread
+      // close-out / verdict ack while the bot still holds its own
+      // CHANGES_REQUESTED on this PR, before the resolve mutates the thread.
+      const rereview = await evaluateRereviewGuard({
+        adapter,
+        workspace: params.workspace,
+        chat: params.chat,
+        thread: params.thread ?? null,
+        text: bodyText,
+        wantsResolve,
+        isContinue: false,
+        getReviewState: (req) => router.getReviewState(req),
+      })
+      if (rereview.block) {
+        logger.warn(formatChannelToolFailure('channel_send', rereview.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${rereview.reason}` }],
+          details: { ok: false, error: rereview.reason },
+        }
+      }
+
       // Resolve BEFORE posting (mirrors channel_reply): a failed resolve must
       // block the acknowledgement so the bot never posts "addressed — resolving"
       // next to a still-open thread. The router enforces that only the bot's own

package/src/bundled-plugins/reviewer/reviewer.ts

@@ -94,7 +94,7 @@ The first thing you do for any review is:
 
 You can load more than one skill if the target genuinely spans domains (e.g. a design doc with code examples — load \`design\`-something AND \`code-review\`). Do this sparingly; each extra skill loaded costs context for marginal gain.
 
-Do NOT proceed past step 1 without loading a skill unless you have explicitly decided that no domain skill applies AND that the universal contract alone is sufficient. State the decision in your \`<summary>\` if you take this path.
+Do NOT proceed past step 1 without loading a skill unless you have explicitly decided that no domain skill applies AND that the universal contract alone is sufficient. This skill-selection decision is internal reasoning — keep it out of \`<summary>\`, which stays a terse, author-facing verdict justification per the output contract.
 
 ## Universal review philosophy
 
@@ -124,7 +124,7 @@ End every response with a single \`<review>\` block. Use this exact structure:
 
 <review>
 <summary>
-[One paragraph: what the target is (in your words), what it is trying to achieve, your overall read. Name the skill(s) you loaded and why. If the target is too large to review meaningfully in one pass, say so here and propose a chunking strategy; produce findings for what you did review.]
+[Two or three sentences, no more. State only your overall judgment and the one or two facts that justify it — the verdict's reasoning, not a recap. The parent may post this verbatim as the review body on an approval, so write it for the PR author, not for an operator: do NOT restate what the change does (they wrote the description), do NOT narrate your process ("I reviewed…", "I loaded the X skill because…", "I checked…"), do NOT list which skills you loaded. Lead with the substance. If the target is too large to review in one pass, say so here and propose a chunking strategy; produce findings for what you did review.]
 </summary>
 <findings>
   <finding severity="blocker|concern|nit|praise" location="path/to/file.ts:42, diff hunk, paragraph reference, or general">
@@ -167,7 +167,7 @@ export function createReviewerSubagent(): Subagent<ReviewerPayload> {
 Available skills:
 ${REVIEWER_SKILLS.map((s) => `- \`${s.name}\` — ${s.description}`).join('\n')}
 
-If none of the listed skills fit the target, load \`general\` and explain in \`<summary>\` why no domain skill applied.`,
+If none of the listed skills fit the target, load \`general\`. Keep the skill-selection decision internal — do NOT narrate which skill you loaded or why in \`<summary>\`, per the output contract.`,
   })
 
   return {

package/src/bundled-plugins/reviewer/skills/general.ts

@@ -20,7 +20,7 @@ You have been asked to review something that does not clearly fit a specific dom
 
 A general review is the hardest because there are no domain shortcuts. Replace shortcuts with discipline:
 
-1. **State the target's purpose in your own words.** What is the artifact trying to achieve? Who is it for? Put this in \`<summary>\`. If you cannot state it after reading, that itself is a finding — the artifact does not communicate its purpose.
+1. **State the target's purpose in your own words — to yourself, as a comprehension check.** What is the artifact trying to achieve? Who is it for? If you cannot state it after reading, that itself is a finding — the artifact does not communicate its purpose. This is your private grounding, not summary copy: keep the restatement out of \`<summary>\`, which stays a terse verdict justification per the output contract.
 2. **Identify the load-bearing claims.** What does the artifact assert that, if wrong, would invalidate the whole thing? List them mentally before looking for issues.
 3. **Stress-test the load-bearing claims.** For each one: is the evidence sufficient? Are the assumptions stated? Are the counter-arguments addressed?
 4. **Stress-test the boundaries.** Where does the artifact's argument or design stop applying? Does it acknowledge that boundary, or does it overgeneralize?

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

@@ -411,6 +411,13 @@ export function classifyGithubInbound(
     // the PR is non-draft once ready — preserving "review when no longer draft".
     const isOpenLike = action === 'opened' || action === 'ready_for_review'
     if (isOpenLike && reviewOn === 'opened') {
+      // Draft opened under `review.on: "opened"`: skip cleanly (null wakes no
+      // session) and wait for the `ready_for_review` trigger. Must NOT fall
+      // through to the awareness path below, where a multi-collaborator repo
+      // silently `observed`s it — a draft whose `ready_for_review` delivery is
+      // later lost would then never get reviewed (huxley#1721). `review_requested`
+      // on a draft is unaffected: it returns above via classifyReviewRequest.
+      if (readBoolean(pr, 'draft') === true) return null
       const trigger = classifyOpenedReviewTrigger({
         payload,
         pr,
@@ -644,12 +651,6 @@ function classifyOpenedReviewTrigger(input: OpenedReviewTriggerInput): InboundMe
   const decoyLogin = resolveDecoyReviewerLogin(selfLogin, authType)
   if (sender.login === selfLogin || (decoyLogin !== null && sender.login === decoyLogin)) return null
 
-  // A draft PR is work-in-progress, so the automatic `opened` path skips it: null
-  // here drops to awareness-only context (like a non-`opened` reviewOn) instead of
-  // waking a review. An explicit `review_requested` still triggers on a draft via
-  // classifyReviewRequest, preserving "skip until explicitly requested".
-  if (readBoolean(pr, 'draft') === true) return null
-
   const title = readString(pr, 'title') ?? `#${number}`
   const head = readString(readRecord(pr.head), 'ref')
   const baseRef = readString(readRecord(pr.base), 'ref')

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

@@ -1,7 +1,7 @@
 import type { GithubTokenBridge } from '@/channels/github-token-bridge'
 import type { ChannelRouter } from '@/channels/router'
 import type { ChannelAdapterConfig, GithubAdapterConfig } from '@/channels/schema'
-import type { ChannelSelfIdentityResolver } from '@/channels/types'
+import type { ChannelSelfIdentityResolver, InboundMessage } from '@/channels/types'
 import { resolveSecret } from '@/secrets/resolve'
 import type { GithubSecretsBlock } from '@/secrets/schema'
 
@@ -21,6 +21,8 @@ import {
   parseListHooksPermissionStatus,
 } from './permission-guidance'
 import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
+import { reconcileOpenPrs } from './reconcile-open-prs'
+import { createGithubReviewStateResolver } from './review-state'
 import { createGithubReviewThreadResolver } from './review-thread-resolver'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
@@ -143,6 +145,12 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfLogin: () => selfLogin,
     fetchImpl,
   })
+  const reviewStateResolver = createGithubReviewStateResolver({
+    token: authToken,
+    selfLogin: () => selfLogin,
+    approve: () => options.configRef().review.approve,
+    fetchImpl,
+  })
   const channelNameResolver = createGithubChannelNameResolver({ token: authToken, fetchImpl })
   // GitHub addresses by `@login`, not the numeric id, so `username` carries
   // the login the model should type; the id is kept for completeness.
@@ -153,6 +161,19 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   const typing = async (): Promise<void> => {}
   const dedup = createDeliveryDedup()
   const isBotInTeam = createTeamMembershipChecker({ token: authToken, fetchImpl })
+  // Shared inbound entry. Both the live webhook handler and the startup
+  // reconciliation pass route through this so a replayed PR takes the exact
+  // same path a real delivery would.
+  const routeInbound = (message: InboundMessage): void => {
+    rememberWorkspace(message.workspace, message.chat)
+    // Ack-first: wrap in Promise.resolve so a synchronous throw inside
+    // router.route() cannot prevent the 200 response from being returned.
+    void Promise.resolve()
+      .then(() => options.router.route(message))
+      .catch((err: unknown) => {
+        logger.error(`[github] route failed: ${err instanceof Error ? err.message : String(err)}`)
+      })
+  }
   const handler = createGithubWebhookHandler({
     webhookSecret,
     dedup,
@@ -166,16 +187,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     authToken,
     fetchImpl,
     logger,
-    route: (message) => {
-      rememberWorkspace(message.workspace, message.chat)
-      // Ack-first: wrap in Promise.resolve so a synchronous throw inside
-      // router.route() cannot prevent the 200 response from being returned.
-      void Promise.resolve()
-        .then(() => options.router.route(message))
-        .catch((err: unknown) => {
-          logger.error(`[github] route failed: ${err instanceof Error ? err.message : String(err)}`)
-        })
-    },
+    route: routeInbound,
   })
 
   return {
@@ -195,6 +207,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       options.router.registerChannelNameResolver('github', channelNameResolver)
       options.router.registerSelfIdentity('github', selfIdentityResolver)
       options.router.registerReviewThreadResolver('github', reviewThreadResolver)
+      options.router.registerReviewStateResolver('github', reviewStateResolver)
       options.router.registerFetchAttachment('github', fetchAttachment)
       try {
         server = (options.httpListenImpl ?? listenWithBun)(options.configRef().webhookPort, handler)
@@ -210,6 +223,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         options.router.unregisterChannelNameResolver('github', channelNameResolver)
         options.router.unregisterSelfIdentity('github', selfIdentityResolver)
         options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
+        options.router.unregisterReviewStateResolver('github', reviewStateResolver)
         options.router.unregisterFetchAttachment('github', fetchAttachment)
         await auth.dispose()
         delete process.env.GH_TOKEN
@@ -321,6 +335,26 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         )
         logRegistrationOutcome(logger, registration, options.secrets.auth.type)
       }
+      // Catch up on PRs whose opened/ready_for_review/review_requested delivery
+      // was missed (tunnel-URL churn, dropped delivery, downtime). Best-effort
+      // and last so a failure here never blocks the adapter from coming up; the
+      // helper swallows per-repo errors internally. Runs on every start(), so a
+      // tunnel-driven restart re-checks too. `off` short-circuits inside.
+      if (repos.length > 0) {
+        await reconcileOpenPrs({
+          repos,
+          reviewOn: cfg.review.on,
+          selfLogin,
+          authType: options.secrets.auth.type,
+          token: authToken,
+          route: routeInbound,
+          logger,
+          isBotInTeam,
+          fetchImpl,
+        }).catch((err: unknown) => {
+          logger.warn(`[github] reconcile pass failed: ${err instanceof Error ? err.message : String(err)}`)
+        })
+      }
     },
     async stop(): Promise<void> {
       if (!started) return
@@ -334,6 +368,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       options.router.unregisterChannelNameResolver('github', channelNameResolver)
       options.router.unregisterSelfIdentity('github', selfIdentityResolver)
       options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
+      options.router.unregisterReviewStateResolver('github', reviewStateResolver)
       options.router.unregisterFetchAttachment('github', fetchAttachment)
       await server?.stop()
       // Detach hooks AFTER closing the listener so any in-flight deliveries

package/src/channels/adapters/github/reconcile-open-prs.ts

@@ -0,0 +1,306 @@
+import type { GithubReviewOn } from '@/channels/schema'
+import type { InboundMessage } from '@/channels/types'
+
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import type { TeamMembershipChecker } from './team-membership'
+
+// Catches up on review work that a live webhook delivery missed. The github
+// adapter only acts on deliveries it receives, so a `pull_request.opened` /
+// `ready_for_review` dropped while the tunnel URL was churning (cloudflare-quick
+// mints a fresh host every restart) leaves an open PR permanently un-reviewed —
+// nothing wakes the bot for it again. This pass runs on every adapter start()
+// (cold boot AND tunnel-driven restart) and replays the PRs that still need a
+// review as synthetic inbounds through the same router path a real webhook uses.
+//
+// It is intentionally NOT a substitute for webhooks: it is a floor, not the
+// primary path. Drift between a missed delivery and the next start() is the
+// reconciliation window; webhooks remain the low-latency path when delivery
+// works.
+
+export type ReconcileOpenPrsOptions = {
+  repos: readonly string[]
+  reviewOn: GithubReviewOn
+  selfLogin: string | null
+  authType: 'pat' | 'app'
+  token: (context?: GithubAuthContext) => Promise<string>
+  route: (message: InboundMessage) => void
+  logger: { info: (m: string) => void; warn: (m: string) => void }
+  // Resolves whether the bot is a member of a requested team, gating
+  // team-requested reviews under review.on 'review_requested' (mirrors the
+  // live webhook path's isMyTeam check in classifyReviewRequest). Omitted in
+  // tests that don't exercise team requests; treated as "not a member".
+  isBotInTeam?: TeamMembershipChecker
+  fetchImpl?: typeof fetch
+}
+
+export type ReconcileOutcome = { repo: string; scanned: number; replayed: number } | { repo: string; error: string }
+
+const BOT_LOGIN_SUFFIX = '[bot]'
+
+export async function reconcileOpenPrs(options: ReconcileOpenPrsOptions): Promise<ReconcileOutcome[]> {
+  // `off` disables code review entirely, so there is nothing to catch up on.
+  if (options.reviewOn === 'off') return []
+  if (options.selfLogin === null) return []
+  const fetchImpl = options.fetchImpl ?? fetch
+  const selfLogin = options.selfLogin
+  const decoyLogin = resolveDecoyLogin(selfLogin, options.authType)
+
+  const outcomes: ReconcileOutcome[] = []
+  for (const repo of new Set(options.repos)) {
+    const target = parseRepo(repo)
+    if (target === null) {
+      outcomes.push({ repo, error: 'malformed repo slug' })
+      continue
+    }
+    try {
+      const outcome = await reconcileRepo(target, options, selfLogin, decoyLogin, fetchImpl)
+      outcomes.push(outcome)
+      if (outcome.replayed > 0) {
+        options.logger.info(`[github] reconcile ${repo}: replayed ${outcome.replayed}/${outcome.scanned} open PR(s)`)
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      options.logger.warn(`[github] reconcile ${repo} failed: ${message}`)
+      outcomes.push({ repo, error: message })
+    }
+  }
+  return outcomes
+}
+
+async function reconcileRepo(
+  target: RepoTarget,
+  options: ReconcileOpenPrsOptions,
+  selfLogin: string,
+  decoyLogin: string | null,
+  fetchImpl: typeof fetch,
+): Promise<{ repo: string; scanned: number; replayed: number }> {
+  const repo = `${target.owner}/${target.repo}`
+  const token = await options.token({ repoSlug: repo })
+  const prs = await fetchOpenPrs(fetchImpl, token, target)
+
+  let replayed = 0
+  for (const pr of prs) {
+    const needs = await prNeedsReview({ pr, options, target, token, selfLogin, decoyLogin, fetchImpl })
+    if (!needs) continue
+    options.route(buildSyntheticInbound(pr, target))
+    replayed += 1
+  }
+  return { repo, scanned: prs.length, replayed }
+}
+
+async function prNeedsReview(input: {
+  pr: OpenPr
+  options: ReconcileOpenPrsOptions
+  target: RepoTarget
+  token: string
+  selfLogin: string
+  decoyLogin: string | null
+  fetchImpl: typeof fetch
+}): Promise<boolean> {
+  const { pr, options, target, token, selfLogin, decoyLogin, fetchImpl } = input
+  if (isSelfAuthored(pr, selfLogin, decoyLogin)) return false
+
+  if (options.reviewOn === 'review_requested') {
+    // Only the explicit request wakes a review under this mode. A draft can
+    // still carry a request, so draft state is irrelevant here. Mirrors the
+    // live path's `isMeAsUser || isMyTeam`: a direct user request, OR a team
+    // request the bot is a member of.
+    if (isUserReviewRequestedFromSelf(pr, selfLogin, decoyLogin)) return true
+    return await isTeamReviewRequestedFromSelf(pr, target, selfLogin, options.isBotInTeam)
+  }
+
+  // reviewOn === 'opened': a non-draft PR the bot has not yet reviewed. Draft
+  // PRs wait for the ready_for_review trigger, matching the live-webhook path.
+  if (pr.draft) return false
+  return !(await botAlreadyReviewed(fetchImpl, token, target, pr.number, selfLogin))
+}
+
+async function isTeamReviewRequestedFromSelf(
+  pr: OpenPr,
+  target: RepoTarget,
+  selfLogin: string,
+  isBotInTeam: TeamMembershipChecker | undefined,
+): Promise<boolean> {
+  if (isBotInTeam === undefined || pr.requestedTeamSlugs.length === 0) return false
+  for (const slug of pr.requestedTeamSlugs) {
+    if (await isBotInTeam({ org: target.owner, slug, login: selfLogin })) return true
+  }
+  return false
+}
+
+function buildSyntheticInbound(pr: OpenPr, target: RepoTarget): InboundMessage {
+  const branchSegment = pr.headRef !== null && pr.baseRef !== null ? ` Branch: ${pr.headRef} → ${pr.baseRef}.` : ''
+  const text =
+    `@${pr.authorLogin} opened PR #${pr.number}: "${pr.title}".${branchSegment}` +
+    ' Please review the changes line-by-line and post your feedback.'
+  // Distinct from the live `pr-<id>-opened-<updatedAt>` id so a replay never
+  // collides with a real opened delivery, while repeated reconciles for the
+  // same unchanged PR dedupe against each other (same updatedAt).
+  const externalMessageId = `pr-${pr.id}-reconcile-${pr.updatedAt}`
+  return {
+    adapter: 'github',
+    workspace: `${target.owner}/${target.repo}`,
+    chat: `pr:${pr.number}`,
+    thread: null,
+    text,
+    externalMessageId,
+    authorId: String(pr.authorId),
+    authorName: pr.authorLogin,
+    authorIsBot: pr.authorIsBot,
+    isBotMention: true,
+    replyToBotMessageId: null,
+    mentionsOthers: false,
+    replyToOtherMessageId: null,
+    isDm: false,
+    ts: pr.updatedAt !== '' ? Date.parse(pr.updatedAt) || 0 : 0,
+  }
+}
+
+type RepoTarget = { owner: string; repo: string }
+
+type OpenPr = {
+  number: number
+  id: number
+  title: string
+  draft: boolean
+  authorLogin: string
+  authorId: number
+  authorIsBot: boolean
+  headRef: string | null
+  baseRef: string | null
+  updatedAt: string
+  requestedReviewerLogins: string[]
+  requestedTeamSlugs: string[]
+}
+
+function parseRepo(slug: string): RepoTarget | null {
+  const [owner, repo, ...rest] = slug.trim().split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '' || rest.length > 0) return null
+  return { owner, repo }
+}
+
+async function fetchOpenPrs(fetchImpl: typeof fetch, token: string, target: RepoTarget): Promise<OpenPr[]> {
+  const prs: OpenPr[] = []
+  let url: string | null = `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/pulls?state=open&per_page=100`
+  while (url !== null) {
+    const response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+    if (!response.ok) {
+      const body = await response.text().catch(() => '')
+      throw new Error(`GitHub pulls ${response.status}${body !== '' ? `: ${body}` : ''}`)
+    }
+    const page = (await response.json().catch(() => null)) as PrRow[] | null
+    if (page === null) throw new Error('GitHub pulls returned non-JSON')
+    for (const row of page) {
+      const parsed = parsePrRow(row)
+      if (parsed !== null) prs.push(parsed)
+    }
+    url = nextLink(response.headers.get('link'))
+  }
+  return prs
+}
+
+async function botAlreadyReviewed(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: RepoTarget,
+  prNumber: number,
+  selfLogin: string,
+): Promise<boolean> {
+  let url: string | null =
+    `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/pulls/${prNumber}/reviews?per_page=100`
+  while (url !== null) {
+    const response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+    if (!response.ok) {
+      const body = await response.text().catch(() => '')
+      throw new Error(`GitHub reviews ${response.status}${body !== '' ? `: ${body}` : ''}`)
+    }
+    const page = (await response.json().catch(() => null)) as ReviewRow[] | null
+    if (page === null) throw new Error('GitHub reviews returned non-JSON')
+    for (const row of page) {
+      const login = row.user?.login ?? null
+      if (login === null) continue
+      if (isSelfLogin(login, row.user?.type === 'Bot', selfLogin)) return true
+    }
+    url = nextLink(response.headers.get('link'))
+  }
+  return false
+}
+
+function isUserReviewRequestedFromSelf(pr: OpenPr, selfLogin: string, decoyLogin: string | null): boolean {
+  return pr.requestedReviewerLogins.some(
+    (login) => isSelfLogin(login, login.endsWith(BOT_LOGIN_SUFFIX), selfLogin) || login === decoyLogin,
+  )
+}
+
+function isSelfAuthored(pr: OpenPr, selfLogin: string, decoyLogin: string | null): boolean {
+  return isSelfLogin(pr.authorLogin, pr.authorIsBot, selfLogin) || pr.authorLogin === decoyLogin
+}
+
+// Mirrors review-state.ts isSelfReviewer: a GitHub App's REST login is
+// `slug[bot]`, so the `[bot]` suffix-strip comparison is gated on the actor
+// actually being a Bot to avoid attributing a human who owns the bare slug.
+function isSelfLogin(login: string, isBot: boolean, selfLogin: string): boolean {
+  if (isBot) return normalizeBotLogin(login) === normalizeBotLogin(selfLogin)
+  return login === selfLogin
+}
+
+function normalizeBotLogin(login: string): string {
+  return login.endsWith(BOT_LOGIN_SUFFIX) ? login.slice(0, -BOT_LOGIN_SUFFIX.length) : login
+}
+
+// A GitHub App actor's REST login is `slug[bot]`; the decoy account an operator
+// requests for App-auth reviews is the bare slug. PAT auth has no decoy.
+function resolveDecoyLogin(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 nextLink(linkHeader: string | null): string | null {
+  if (linkHeader === null) return null
+  for (const part of linkHeader.split(',')) {
+    const m = /<([^>]+)>;\s*rel="next"/.exec(part)
+    if (m !== null) return m[1] ?? null
+  }
+  return null
+}
+
+type PrRow = {
+  number?: unknown
+  id?: unknown
+  title?: unknown
+  draft?: unknown
+  updated_at?: unknown
+  user?: { login?: unknown; id?: unknown; type?: unknown }
+  head?: { ref?: unknown }
+  base?: { ref?: unknown }
+  requested_reviewers?: Array<{ login?: unknown }>
+  requested_teams?: Array<{ slug?: unknown }>
+}
+
+type ReviewRow = { user?: { login?: string; type?: string } }
+
+function parsePrRow(row: PrRow): OpenPr | null {
+  const number = typeof row.number === 'number' ? row.number : null
+  const id = typeof row.id === 'number' ? row.id : null
+  const authorLogin = typeof row.user?.login === 'string' ? row.user.login : null
+  if (number === null || id === null || authorLogin === null) return null
+  return {
+    number,
+    id,
+    title: typeof row.title === 'string' ? row.title : `#${number}`,
+    draft: row.draft === true,
+    authorLogin,
+    authorId: typeof row.user?.id === 'number' ? row.user.id : 0,
+    authorIsBot: row.user?.type === 'Bot',
+    headRef: typeof row.head?.ref === 'string' ? row.head.ref : null,
+    baseRef: typeof row.base?.ref === 'string' ? row.base.ref : null,
+    updatedAt: typeof row.updated_at === 'string' ? row.updated_at : '',
+    requestedReviewerLogins: (row.requested_reviewers ?? []).flatMap((r) =>
+      typeof r.login === 'string' ? [r.login] : [],
+    ),
+    requestedTeamSlugs: (row.requested_teams ?? []).flatMap((t) => (typeof t.slug === 'string' ? [t.slug] : [])),
+  }
+}