typeclaw 0.28.1 → 0.28.2

package/package.json

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

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

@@ -171,6 +171,7 @@ export function createChannelReplyTool({
         thread: origin.thread,
         text,
         wantsResolve: params.resolve_review_thread === true,
+        isContinue: keepTurnAlive,
         getReviewState: (req) => router.getReviewState(req),
       })
       if (rereview.block) {

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

@@ -187,6 +187,7 @@ export function createChannelSendTool({
         thread: params.thread ?? null,
         text: bodyText,
         wantsResolve,
+        isContinue: false,
         getReviewState: (req) => router.getReviewState(req),
       })
       if (rereview.block) {

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,7 @@ 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'
@@ -160,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,
@@ -173,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 {
@@ -330,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

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] : [])),
+  }
+}

package/src/channels/adapters/github/review-state.ts

@@ -31,11 +31,20 @@ export function createGithubReviewStateResolver(deps: {
     }
 
     const token = await deps.token({ repoSlug: `${target.owner}/${target.repo}` })
-    const reviews = await fetchSelfReviews(fetchImpl, token, target, selfLogin)
+    const [reviews, reviewDecision] = await Promise.all([
+      fetchSelfReviews(fetchImpl, token, target, selfLogin),
+      fetchReviewDecision(fetchImpl, token, target),
+    ])
     if (!reviews.ok) return { ok: false, error: reviews.error, code: reviews.code }
+    if (!reviewDecision.ok) return { ok: false, error: reviewDecision.error, code: reviewDecision.code }
 
     const lastDecisive = reviews.states.filter(isDecisive).at(-1) ?? null
-    return { ok: true, selfBlocking: lastDecisive === 'CHANGES_REQUESTED', approve }
+    return {
+      ok: true,
+      selfBlocking: lastDecisive === 'CHANGES_REQUESTED',
+      approve,
+      ...(reviewDecision.reviewDecision !== null ? { reviewDecision: reviewDecision.reviewDecision } : {}),
+    }
   }
 }
 
@@ -55,6 +64,12 @@ type SelfReviewsResult =
   | { ok: true; states: string[] }
   | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
 
+type ReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED'
+
+type ReviewDecisionResult =
+  | { ok: true; reviewDecision: ReviewDecision | null }
+  | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
+
 async function fetchSelfReviews(
   fetchImpl: typeof fetch,
   token: string,
@@ -94,6 +109,47 @@ async function fetchSelfReviews(
   return { ok: true, states }
 }
 
+async function fetchReviewDecision(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: Target,
+): Promise<ReviewDecisionResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(`${GITHUB_API_BASE}/graphql`, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify({
+        query:
+          'query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewDecision}}}',
+        variables: { owner: target.owner, repo: target.repo, number: target.prNumber },
+      }),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    return {
+      ok: false,
+      error: `GitHub reviewDecision ${response.status}${text !== '' ? `: ${text}` : ''}`,
+      code: classifyStatus(response.status),
+    }
+  }
+  const raw = (await response.json().catch(() => null)) as ReviewDecisionResponse | null
+  if (raw === null) return { ok: false, error: 'GitHub reviewDecision returned non-JSON', code: 'transient' }
+  if (Array.isArray(raw.errors) && raw.errors.length > 0) {
+    return {
+      ok: false,
+      error: `GitHub reviewDecision errors: ${raw.errors.map(describeGraphqlError).join('; ')}`,
+      code: 'transient',
+    }
+  }
+  const value = raw.data?.repository?.pullRequest?.reviewDecision ?? null
+  if (value === null || isReviewDecision(value)) return { ok: true, reviewDecision: value }
+  return { ok: false, error: `GitHub reviewDecision returned unknown value: ${String(value)}`, code: 'transient' }
+}
+
 // A formal CHANGES_REQUESTED is sticky until a later APPROVED/DISMISSED; only
 // these three states decide the block. COMMENTED and PENDING are non-deciding
 // noise that must NOT shadow an earlier CHANGES_REQUESTED.
@@ -135,3 +191,16 @@ function classifyStatus(status: number): 'not-found' | 'permission-denied' | 'tr
 }
 
 type ReviewRow = { id?: number; state?: unknown; user?: { login?: string; type?: string } }
+
+type ReviewDecisionResponse = {
+  data?: { repository?: { pullRequest?: { reviewDecision?: unknown } | null } | null }
+  errors?: Array<{ message?: unknown }>
+}
+
+function isReviewDecision(value: unknown): value is ReviewDecision {
+  return value === 'APPROVED' || value === 'CHANGES_REQUESTED' || value === 'REVIEW_REQUIRED'
+}
+
+function describeGraphqlError(error: { message?: unknown }): string {
+  return typeof error.message === 'string' ? error.message : JSON.stringify(error)
+}

package/src/channels/github-rereview-guard.ts

@@ -1,4 +1,4 @@
-import { classifyReviewClaim } from './github-review-claim'
+import { classifyReviewClaim, isPositiveWarnCloseout } from './github-review-claim'
 import type { ReviewStateResult } from './types'
 
 // The re-review stranding guard. A bot that resolves a review thread (or posts a
@@ -17,6 +17,10 @@ export type RereviewGuardInput = {
   thread: string | null
   text: string | undefined
   wantsResolve: boolean
+  // A mid-turn status reply (continue:true) is not the turn's receipt, so it
+  // suppresses the warn-tier escalation below — but never the explicit resolve,
+  // which is a real mutation. Mirrors the false-receipt guard's continue rule.
+  isContinue: boolean
   getReviewState: (req: { adapter: 'github'; workspace: string; chat: string }) => Promise<ReviewStateResult>
   workspace: string
 }
@@ -32,14 +36,19 @@ export async function evaluateRereviewGuard(input: RereviewGuardInput): Promise<
   // a close-out ack in it ("Verified — that closes it") strands the block just
   // as a thread reply would. Only the resolve ACTION needs a thread; the
   // text-claim path fires regardless (caught by isCloseoutAttempt below).
-  if (!isCloseoutAttempt(input.wantsResolve, input.thread, input.text)) return ALLOW
+  if (!isCloseoutAttempt(input)) return ALLOW
 
   const state = await input.getReviewState({ adapter: 'github', workspace: input.workspace, chat: input.chat })
 
   // Fail closed: an unverifiable review state is treated as a live block, so the
   // bot never strands a re-review on a transient API failure.
   if (!state.ok) return { block: true, reason: unverifiableReason(state.error) }
-  if (!state.selfBlocking) return ALLOW
+  if (!state.selfBlocking) {
+    if (state.reviewDecision === 'REVIEW_REQUIRED' && isPositiveWarnCloseout(input.text ?? '')) {
+      return { block: true, reason: INITIAL_REVIEW_REQUIRED }
+    }
+    return ALLOW
+  }
 
   return { block: true, reason: state.approve ? STICKY_BLOCK_APPROVE_ENABLED : STICKY_BLOCK_APPROVE_DISABLED }
 }
@@ -47,11 +56,20 @@ export async function evaluateRereviewGuard(input: RereviewGuardInput): Promise<
 // Trigger when the model asks to resolve a thread (only meaningful with a
 // thread), OR when its reply reads as a close-out/verdict claim — the latter
 // strands the block whether or not it sits in a thread, so it fires for any PR
-// chat. Plain discussion replies (ignore/warn) do not fire.
-function isCloseoutAttempt(wantsResolve: boolean, thread: string | null, text: string | undefined): boolean {
-  if (wantsResolve && thread !== null) return true
-  const claim = classifyReviewClaim(text ?? '')
-  return claim === 'block-resolve' || claim === 'block-approve'
+// chat. Unlike the pure false-receipt classifier, this guard has the objective
+// review state available, so an approval-shaped warn reply ("looks good"/"lgtm")
+// is escalated to a closeout too: it only blocks when the bot actually holds a
+// live CHANGES_REQUESTED, so casual approval-shaped chatter on an unblocked PR
+// still posts. Only POSITIVE warn phrases escalate — negative ones ("needs
+// changes", "still needs work") re-assert a block rather than strand it, so they
+// stay non-firing. `continue:true` exempts the warn escalation (mid-turn
+// planning, not the receipt), but never the explicit resolve action. Plain
+// `ignore` text never fires.
+function isCloseoutAttempt(input: RereviewGuardInput): boolean {
+  if (input.wantsResolve && input.thread !== null) return true
+  const claim = classifyReviewClaim(input.text ?? '')
+  if (claim === 'block-resolve' || claim === 'block-approve') return true
+  return !input.isContinue && isPositiveWarnCloseout(input.text ?? '')
 }
 
 function unverifiableReason(error: string): string {
@@ -74,3 +92,9 @@ const STICKY_BLOCK_APPROVE_DISABLED =
   'dismiss your prior review via ' +
   '`gh api -X PUT /repos/<owner>/<repo>/pulls/<N>/reviews/<review_id>/dismissals -f message="..." -f event=DISMISS` ' +
   'if the blockers are fixed (or submit REQUEST_CHANGES if not), THEN resolve the thread / reply.'
+
+const INITIAL_REVIEW_REQUIRED =
+  'This PR still requires a formal GitHub review. A flat `LGTM` / `looks good` PR comment does not create ' +
+  'review state, so it leaves the PR awaiting review. Submit the reviewer verdict via ' +
+  '`gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` with event `APPROVE` when approval is enabled, ' +
+  'or event `COMMENT` when approval is disabled, then narrate only if needed.'

package/src/channels/github-review-claim.ts

@@ -41,19 +41,26 @@ const BLOCK_RESOLVE: readonly RegExp[] = [
   /\b(thanks,?|fixed,?) (looks )?resolved\b/,
 ]
 
-// Casual phrasing that might be chatter, not a formal close-out: allow + nudge.
-const WARN: readonly RegExp[] = [
+// Approval/resolve-shaped warn phrases: casual chatter that, on a PR the bot is
+// still blocking, READS as a close-out and so can strand the block. Split out so
+// the re-review guard can escalate only these — never the negative warn phrases
+// below, which re-assert a block rather than strand it.
+const WARN_POSITIVE_CLOSEOUT: readonly RegExp[] = [
   /\blgtm\b/,
   /\blooks good\b/,
   /\blooks fine\b/,
   /\bseems fine\b/,
   /\bshould be (fine|good)\b/,
-  /\bneeds changes\b/,
-  /\bstill needs work\b/,
   /\blooks resolved\b/,
   /\bseems resolved\b/,
 ]
 
+// Negative warn phrases re-assert a block ("not done yet") instead of closing it
+// out, so they are NOT close-out attempts — the re-review guard must ignore them.
+const WARN_NEGATIVE: readonly RegExp[] = [/\bneeds changes\b/, /\bstill needs work\b/]
+
+const WARN: readonly RegExp[] = [...WARN_POSITIVE_CLOSEOUT, ...WARN_NEGATIVE]
+
 // Negation / future-intent / past-reference markers DEMOTE a positive match to
 // ignore. Blocking "I haven't approved" / "I'll approve" / "approved it earlier"
 // (answering a question) is the worst false-positive class, so it is checked first.
@@ -61,15 +68,40 @@ const DEMOTE_TO_IGNORE: readonly RegExp[] = [
   /\b(haven'?t|have not|did ?n'?t|did not|not yet|never)\b[^.!?]*\b(approv|request|resolv|block)/,
   /\b(can'?t|cannot|won'?t|will not|wouldn'?t)\b[^.!?]*\b(approv|request|resolv|block)/,
   /\bnot (approved|resolved|blocked|requesting)\b/,
+  /\b(not|no longer|hardly|barely)\b[^.!?]*\b(lgtm|looks good|looks fine|seems fine|should be (fine|good)|looks resolved|seems resolved)\b/,
   /\b(i'?ll|i will|going to|gonna|about to|planning to)\b[^.!?]*\b(approv|review|request|resolv)/,
   /\b(approved|resolved|requested changes)\b[^.!?]*\b(earlier|already|yesterday|before|last (review|time)|previously)\b/,
+  /\b(pre|self|co|re|un|non|ai|admin|user|machine|auto) approved\b/,
 ]
 
+const QUESTION_CONTEXT =
+  /(?:^|\b)(who|what|when|where|why|how|was|were|is|are|did|do|does|has|have|can|could|would|should)\b[^.!?]*\?/
+
 export function classifyReviewClaim(rawText: string): ReviewClaim {
-  const text = normalize(rawText)
-  if (text === '') return 'ignore'
+  const segments = claimSegments(rawText)
+  if (segments.length === 0) return 'ignore'
+
+  const claims = segments.map(classifySegment)
+
+  if (claims.includes('block-approve')) return 'block-approve'
+  if (claims.includes('block-request-changes')) return 'block-request-changes'
+  if (claims.includes('block-resolve')) return 'block-resolve'
+  if (claims.includes('warn')) return 'warn'
+  return 'ignore'
+}
 
+// True only for warn-tier replies whose phrasing reads as an approval/resolve
+// close-out (e.g. "looks good", "lgtm"), excluding negative warn phrases like
+// "needs changes" that re-assert a block. The re-review guard uses this to
+// escalate just the stranding-shaped warns, not the whole warn bucket.
+export function isPositiveWarnCloseout(rawText: string): boolean {
+  if (classifyReviewClaim(rawText) !== 'warn') return false
+  return claimSegments(rawText).some((segment) => WARN_POSITIVE_CLOSEOUT.some((re) => re.test(segment)))
+}
+
+function classifySegment(text: string): ReviewClaim {
   if (DEMOTE_TO_IGNORE.some((re) => re.test(text))) return 'ignore'
+  if (QUESTION_CONTEXT.test(text)) return 'ignore'
 
   // Block-tier wins over warn-tier: an unambiguous "approved" in a casual message
   // is still a formal claim.
@@ -80,6 +112,21 @@ export function classifyReviewClaim(rawText: string): ReviewClaim {
   return 'ignore'
 }
 
+function claimSegments(text: string): string[] {
+  return redactQuotedAndCode(text)
+    .split(/(?<=[.!?])\s+|\n+/)
+    .map(normalize)
+    .filter((segment) => segment !== '')
+}
+
+function redactQuotedAndCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ')
+    .replace(/"[^"\n]*"|“[^”\n]*”|‘[^’\n]*’/g, ' ')
+    .replace(/^\s*>.*$/gm, ' ')
+}
+
 // Strips markdown/emoji noise so "**Approved!**" and "approved" classify alike,
 // keeping apostrophes + sentence punctuation that the negation regexes rely on.
 function normalize(text: string): string {

package/src/channels/router.ts

@@ -1422,8 +1422,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         unsubTypingActivity: null,
         unsubTodoOutcome: null,
       }
+      // Tracks the `turnSeq` a provider-error notice was last POSTED for, so the
+      // channel surfaces at most one notice per turn. The upstream SDK retries
+      // internally, and each retry emits its own `message_end` with
+      // `stopReason: 'error'` — without this gate a single failing turn posts N
+      // identical "⚠️ upstream provider failed" notices (one per retry). Logs
+      // still record every attempt; only the user-facing notice is deduped.
+      let lastProviderErrorNoticeTurn: number | undefined
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
+        // Suppress duplicate notices for the SAME turn (retry storm). Set the
+        // marker BEFORE the async send so a synchronous burst of retry events
+        // can't each slip past the check and enqueue their own notice.
+        if (lastProviderErrorNoticeTurn === live.turnSeq) return
+        lastProviderErrorNoticeTurn = live.turnSeq
         // A provider soft-error (rate/usage limit, billing, malformed response)
         // ends the turn with no assistant text, so the human otherwise sees
         // silence. Surface the REDACTED `safeMessage` (never the raw provider

package/src/channels/schema.ts

@@ -192,8 +192,9 @@ export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
 // prefix is implied by this field living under the review config); `off` is the
 // disable sentinel, matching the `engagement.stickiness: 'off'` convention:
 //   - 'review_requested' — review only when the bot is requested (default)
-//   - 'opened'           — review every non-draft PR as soon as it opens; draft
-//                          PRs are skipped until an explicit review_requested
+//   - 'opened'           — review every non-draft PR as soon as it opens; a draft
+//                          PR wakes no session and is reviewed once it turns ready
+//                          (ready_for_review) or the bot is explicitly requested
 //   - 'off'              — disable code review entirely
 export const GITHUB_REVIEW_ON_VALUES = ['review_requested', 'opened', 'off'] as const
 

package/src/channels/types.ts

@@ -395,19 +395,24 @@ export type ReviewStateRequest = {
   chat: string
 }
 
-// `selfBlocking` is the answer the guard acts on: true means the bot's latest
-// effective formal review is its own CHANGES_REQUESTED (COMMENTED reviews are
-// ignored — they never clear the sticky block, GitHub's own rule). `approve`
-// mirrors `channels.github.review.approve` so the guard's denial text can tell
-// the model whether to land a fresh APPROVE or to DISMISS its prior review.
+// `selfBlocking` is the answer the guard acts on for re-reviews: true means the
+// bot's latest effective formal review is its own CHANGES_REQUESTED (COMMENTED
+// reviews are ignored — they never clear the sticky block, GitHub's own rule).
+// `reviewDecision` is GitHub's aggregate PR review status when GraphQL can
+// provide it; REVIEW_REQUIRED means an approval-shaped flat comment would still
+// leave the PR awaiting a formal review. `approve` mirrors
+// `channels.github.review.approve` so the guard's denial text can tell the model
+// whether to land a fresh APPROVE or to DISMISS its prior review.
 //
 // On `ok: false` the caller MUST fail closed: an unverifiable review state is
 // treated like a live block, so the bot never claims close-out when the runtime
 // could not confirm the platform-side verdict.
 export type ReviewStateResult =
-  | { ok: true; selfBlocking: boolean; approve: boolean }
+  | { ok: true; selfBlocking: boolean; approve: boolean; reviewDecision?: GithubReviewDecision }
   | { ok: false; error: string; code?: 'unsupported' | 'not-found' | 'permission-denied' | 'transient' }
 
+export type GithubReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED'
+
 // Registered per-adapter on the ChannelRouter, last-write-wins like the
 // review-thread resolver. Adapters that never register one make `getReviewState`
 // answer `unsupported`.

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -189,7 +189,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
 A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
-- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
+- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **Post the `<summary>` verbatim — do not pad it back into a play-by-play.** The reviewer's contract already makes the summary a terse, author-facing verdict justification (no process narration, no "I loaded the X skill", no recap of what the PR does); your job is to forward it, not re-expand it. **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
 - `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
 - `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.