typeclaw 0.27.0 → 0.28.1

package/src/bundled-plugins/github-cli-auth/review-recorder.ts

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises'
+
+import { recordReview } from '@/channels/github-review-turn-ledger'
+import type { ContentPart, ToolResult } from '@/plugin'
+
+import { detectReviewSubmission, type DetectedReview } from './gh-review-detect'
+
+// Bridges the bash `gh` interceptor to the false-receipt ledger: at tool.before
+// we detect a review-submission command (resolving its --input file), stash it by
+// callId, and at tool.after we credit the ledger ONLY if the command actually
+// succeeded. Strict success detection is the safe bias here — wrongly crediting a
+// review that never landed would re-open the false-receipt hole, so an ambiguous
+// result is treated as "not landed" and left uncredited.
+
+const pending = new Map<string, DetectedReview>()
+
+const MAX_INPUT_BYTES = 1_000_000
+
+export async function noteReviewCommand(args: { callId: string; command: string }): Promise<void> {
+  const inputFileContents = await readInputFile(args.command)
+  const detected = detectReviewSubmission({ command: args.command, inputFileContents })
+  if (detected !== null) pending.set(args.callId, detected)
+}
+
+export function commitReviewIfSucceeded(args: { sessionId: string; callId: string; result: ToolResult }): void {
+  const detected = pending.get(args.callId)
+  if (detected === undefined) return
+  pending.delete(args.callId)
+  if (!looksSucceeded(detected, collectText(args.result.content))) return
+  recordReview({
+    sessionId: args.sessionId,
+    workspace: detected.workspace,
+    prNumber: detected.prNumber,
+    verdict: detected.verdict,
+  })
+}
+
+async function readInputFile(command: string): Promise<string | null> {
+  const path = inputFilePath(command)
+  if (path === null) return null
+  try {
+    const buf = await readFile(path)
+    if (buf.byteLength > MAX_INPUT_BYTES) return null
+    return buf.toString('utf8')
+  } catch {
+    return null
+  }
+}
+
+function inputFilePath(command: string): string | null {
+  const m = /(?:^|\s)--input(?:=|\s+)(\S+)/.exec(command)
+  if (m === null) return null
+  const raw = m[1] as string
+  if (raw === '-') return null
+  return stripQuotes(raw)
+}
+
+function stripQuotes(value: string): string {
+  if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value[value.length - 1] === value[0]) {
+    return value.slice(1, -1)
+  }
+  return value
+}
+
+// Success markers are vector-specific. The REST endpoints echo the created
+// review JSON; the `gh pr review` porcelain prints a plain confirmation line
+// ("✓ Approved pull request OWNER/REPO#N" / "+ Requested changes to pull
+// request …", from cli/cli pkg/cmd/pr/review). Matching REST JSON markers
+// against porcelain output left every `gh pr review --approve` uncredited, so a
+// later "Approved" reply in the same turn was wrongly blocked.
+const API_SUCCESS_MARKERS = [
+  '"node_id":"PRR_',
+  '"state":"APPROVED"',
+  '"state":"CHANGES_REQUESTED"',
+  '"state": "APPROVED"',
+]
+const PR_REVIEW_SUCCESS_MARKERS = ['Approved pull request', 'Requested changes to pull request']
+const FAILURE_MARKERS = ['gh: ', 'HTTP 4', 'HTTP 5', 'Bad credentials', 'Not Found', 'Validation Failed']
+
+// Require a success marker AND no failure marker, so a partial/garbled capture
+// fails closed (uncredited).
+function looksSucceeded(detected: DetectedReview, text: string): boolean {
+  if (FAILURE_MARKERS.some((m) => text.includes(m))) return false
+  const markers = detected.source === 'pr-review' ? PR_REVIEW_SUCCESS_MARKERS : API_SUCCESS_MARKERS
+  return markers.some((m) => text.includes(m))
+}
+
+function collectText(content: readonly ContentPart[]): string {
+  return content
+    .filter((p): p is ContentPart & { type: 'text' } => p.type === 'text')
+    .map((p) => p.text)
+    .join('\n')
+}

package/src/bundled-plugins/guard/policies/managed-config.ts

@@ -71,7 +71,7 @@ function validateManagedContent(file: ManagedFile, content: string): { ok: true
     const result = parseConfigJson(content, { migrate: false })
     return result.ok ? { ok: true } : { ok: false, reason: result.reason }
   }
-  const result = parseCronJson(content, { migrate: false })
+  const result = parseCronJson(content)
   return result.ok ? { ok: true } : { ok: false, reason: result.reason }
 }
 

package/src/bundled-plugins/memory/README.md

@@ -85,29 +85,11 @@ A `[dreaming] citation-superset violation: …` warning logs the dropped ids and
 
 - **`memory/topics/<slug>.md`** — per-topic shards with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, `tags?`) + body markdown. Runtime owns the frontmatter (recomputed after every dreaming run from the body's citations); dreaming subagent writes body only.
 - **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards.
-- **`memory/MEMORY.md.pre-shard.bak`** — one-shot pre-migration backup created by the boot migration. Safe to delete after verifying.
+- **`memory/MEMORY.md.pre-shard.bak`** — legacy pre-shard backup left by older TypeClaw versions. Safe to delete after verifying.
 - **`memory/skills/<name>/SKILL.md`** — muscle memory. Skills the dreaming subagent distills from repeated procedures. Auto-loaded as first-class skills.
 - **`memory/.dreaming-state.json`** — per-day dreamed-id sets.
 - **`memory/.retrieval-cache/<sessionId>.md`** — ephemeral retrieval summaries. Written by `memory-retrieval`, read by `loadMemory` on the next prompt of the same session, unlinked on `session.end`.
 
-## One-shot boot migration
-
-When the plugin boots against an agent folder with a root `MEMORY.md` and no `memory/topics/`, it runs `runShardingMigration`. Steps:
-
-1. Detect prerequisites.
-2. Reset `memory/.migrating/` if a previous run crashed mid-flight.
-3. Run the legacy `.md → .jsonl` daily-stream migration (existing behavior).
-4. Parse `MEMORY.md` via `parseTopicsWithBodies`.
-5. **Stage topic shards** in `memory/.migrating/topics/` (originals untouched).
-6. **Stage streams** by COPY (not rename) to `memory/.migrating/streams/`.
-7. Stage pre-shard backup by COPY.
-8. **Verify staging** via `checkCitationSupersetAcrossShards`. On failure, abort and KEEP `memory/.migrating/` for human inspection. Originals untouched.
-9. **Atomic finalization**: rename three dirs (`topics`, `streams`, `.pre-shard.bak`), then unlink originals.
-
-Crash-recovery branches at boot: stale `memory/.migrating/` with no `topics/` → cleanup + retry; leftover `memory/.migrating/` alongside complete `topics/` → cleanup only; orphan root `MEMORY.md` or `memory/<date>.jsonl` alongside the new layout → delete orphans.
-
-The migration is idempotent and crash-safe.
-
 ## How `session.idle` works
 
 Core fires `session.idle` immediately after every `session.prompt()` completion. The plugin owns the debounce: a `Map<sessionId, Timeout>` reset on every event. When the timer fires, the plugin spawns `memory-logger` for that session — unless the min-delta gate suppresses the spawn (see below).
@@ -132,9 +114,9 @@ Each `memory-logger` spawn captures the line count of `memory/streams/<today>.js
 
 ## Tests
 
-Test files in this directory (kebab-case, `.test.ts` neighbors): `paths`, `slug`, `frontmatter`, `topics`, `shard-snapshot`, `delete-tool`, `citations`, `citation-superset`, `migration`, `load-shards`, `load-memory`, `injection-plan`, `search-tool`, `memory-retrieval`, `memory-logger`, `dreaming`, `index`, `integration`. Plus guard policies in `../guard/policies/`: `memory-topics-delete`, `memory-topics-write`, `memory-retrieval-cache-write`.
+Test files in this directory (kebab-case, `.test.ts` neighbors): `paths`, `slug`, `frontmatter`, `topics`, `shard-snapshot`, `delete-tool`, `citations`, `citation-superset`, `load-shards`, `load-memory`, `injection-plan`, `search-tool`, `memory-retrieval`, `memory-logger`, `dreaming`, `index`, `integration`. Plus guard policies in `../guard/policies/`: `memory-topics-delete`, `memory-topics-write`, `memory-retrieval-cache-write`.
 
-## Migration notes (from before the plugin existed)
+## Notes from before the plugin existed
 
 - `memory.idleMs` and `memory.dreaming.schedule` already existed in core's `typeclaw.json` schema and moved into this plugin's `configSchema` verbatim.
 - `memory.dreaming.schedule` is now **restart-required** because plugin config is read once at boot.

package/src/bundled-plugins/memory/index.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { access, constants as fsConstants, mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { access, constants as fsConstants, mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import { CronExpressionParser } from 'cron-parser'
@@ -14,7 +14,6 @@ import { buildInjectionPlan, DEFAULT_INJECTION_BUDGET_BYTES, MIN_INJECTION_BUDGE
 import { loadAllShards } from './load-shards'
 import { createMemoryLoggerSubagent, type MemoryLoggerPayload } from './memory-logger'
 import { createMemoryRetrievalSubagent, type MemoryRetrievalPayload } from './memory-retrieval'
-import { runMigration, runShardingMigration } from './migration'
 import { preShardBackupPath, streamFilePath, streamsDir, topicsDir } from './paths'
 import { memorySearchTool } from './search-tool'
 
@@ -141,26 +140,6 @@ export default definePlugin({
     const retrievalSpawnTimeoutMs = ctx.config.retrievalSpawnTimeoutMs
     const dreamingSchedule = ctx.config.dreaming?.schedule ?? DEFAULT_DREAMING_SCHEDULE
 
-    const migrationResult = await runMigration({
-      agentDir: ctx.agentDir,
-      logger: ctx.logger,
-    })
-    if (migrationResult.migrated.length > 0) {
-      ctx.logger.info(`[memory] migrated ${migrationResult.migrated.length} daily stream(s) to JSONL`)
-    }
-
-    const shardingResult = await runShardingMigration({
-      agentDir: ctx.agentDir,
-      logger: ctx.logger,
-    })
-    if (shardingResult.migrated) {
-      ctx.logger.info(
-        `[memory] sharded ${shardingResult.topicCount} topics + ${shardingResult.streamCount} streams (pre-shard backup at memory/MEMORY.md.pre-shard.bak)`,
-      )
-    } else if (shardingResult.error !== undefined) {
-      ctx.logger.warn(`[memory] sharding migration aborted: ${shardingResult.error}`)
-    }
-
     const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
     const lastIdleEvent = new Map<string, { parentTranscriptPath: string | undefined; origin?: SessionOrigin }>()
     const bytesAtLastRun = new Map<string, number>()
@@ -548,133 +527,6 @@ export default definePlugin({
             }
           },
         },
-        'legacy-md-cleanup': {
-          description: 'Check for legacy .md daily stream files and un-migrated root MEMORY.md',
-          run: async (dctx) => {
-            const memoryDir = join(dctx.agentDir, 'memory')
-            // kept: pre-migration agents may still have a root MEMORY.md.
-            const rootMemoryPath = join(dctx.agentDir, 'MEMORY.md')
-            const hasRootMemory = existsSync(rootMemoryPath)
-            const hasTopicsDir = existsSync(topicsDir(dctx.agentDir))
-
-            let files: string[]
-            try {
-              files = await readdir(memoryDir)
-            } catch {
-              if (!hasRootMemory) return { status: 'ok', message: 'memory/ does not exist yet' }
-              return {
-                status: 'warning',
-                message: 'root MEMORY.md present but not sharded',
-                fix: {
-                  description: 'Run sharding migration to convert root MEMORY.md to topic shards',
-                  apply: async (fixCtx) => {
-                    const result = await runShardingMigration({ agentDir: fixCtx.agentDir, logger: fixCtx.logger })
-                    return {
-                      summary: result.migrated
-                        ? `sharded ${result.topicCount} topic(s) and ${result.streamCount} stream(s)`
-                        : `sharding migration did not run${result.error ? `: ${result.error}` : ''}`,
-                      changedPaths: result.migrated
-                        ? [
-                            join('memory', 'topics'),
-                            join('memory', 'streams'),
-                            join('memory', 'MEMORY.md.pre-shard.bak'),
-                          ]
-                        : [],
-                    }
-                  },
-                },
-              }
-            }
-
-            const mdFiles = files.filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
-
-            if (hasRootMemory) {
-              if (!hasTopicsDir) {
-                const mdMsg = mdFiles.length > 0 ? `; also ${mdFiles.length} legacy .md daily stream(s)` : ''
-                return {
-                  status: 'warning',
-                  message: `root MEMORY.md present but not sharded${mdMsg}`,
-                  fix: {
-                    description: 'Run sharding migration to convert root MEMORY.md to topic shards',
-                    apply: async (fixCtx) => {
-                      const result = await runShardingMigration({ agentDir: fixCtx.agentDir, logger: fixCtx.logger })
-                      return {
-                        summary: result.migrated
-                          ? `sharded ${result.topicCount} topic(s) and ${result.streamCount} stream(s)`
-                          : `sharding migration did not run${result.error ? `: ${result.error}` : ''}`,
-                        changedPaths: result.migrated
-                          ? [
-                              join('memory', 'topics'),
-                              join('memory', 'streams'),
-                              join('memory', 'MEMORY.md.pre-shard.bak'),
-                            ]
-                          : [],
-                      }
-                    },
-                  },
-                }
-              }
-              const mdMsg = mdFiles.length > 0 ? `; also ${mdFiles.length} legacy .md daily stream(s)` : ''
-              return {
-                status: 'warning',
-                message: `orphaned root MEMORY.md after sharding migration${mdMsg}`,
-                fix: {
-                  description: 'Delete the orphaned root MEMORY.md file',
-                  apply: async () => {
-                    await unlink(rootMemoryPath)
-                    return { summary: 'deleted orphaned root MEMORY.md', changedPaths: ['MEMORY.md'] }
-                  },
-                },
-              }
-            }
-
-            if (mdFiles.length === 0) return { status: 'ok', message: 'no legacy .md daily streams found' }
-
-            const caseA: string[] = []
-            const caseB: string[] = []
-
-            for (const mdFile of mdFiles) {
-              const date = mdFile.replace('.md', '')
-              const jsonlFile = `${date}.jsonl`
-              if (files.includes(jsonlFile)) {
-                caseB.push(date)
-              } else {
-                caseA.push(date)
-              }
-            }
-
-            if (caseA.length > 0 && caseB.length === 0) {
-              return {
-                status: 'warning',
-                message: `${caseA.length} legacy .md daily stream(s) still present; boot-time migration likely failed`,
-                fix: {
-                  description: 'Re-run migration to convert .md files to .jsonl',
-                  apply: async (fixCtx) => {
-                    const result = await runMigration({ agentDir: fixCtx.agentDir, logger: fixCtx.logger })
-                    return {
-                      summary: `migrated ${result.migrated.length} legacy .md daily stream(s) to .jsonl`,
-                      changedPaths: result.migrated.map((d) => `memory/${d}.jsonl`),
-                    }
-                  },
-                },
-              }
-            }
-
-            if (caseB.length > 0) {
-              const allDates = [...caseA, ...caseB]
-              return {
-                status: 'warning',
-                message: `Conflicting .md+.jsonl pair for dates: ${allDates.join(', ')}. Inspect manually: the .jsonl is the authoritative new format; if its contents match or supersede the .md, delete the .md by hand.`,
-                fix: {
-                  description: 'Manual inspection required. Delete the .md file if the .jsonl is correct.',
-                  // No apply — this is an operator decision
-                },
-              }
-            }
-
-            return { status: 'ok', message: 'no legacy .md daily streams found' }
-          },
-        },
         'pre-shard-backup-age': {
           description: 'Warn when pre-shard backup is older than 30 days',
           run: async (dctx) => {

package/src/bundled-plugins/security/policies/cron-promotion.ts

@@ -191,7 +191,7 @@ async function intendedContent(
 }
 
 function parseJobsFromContent(content: string): readonly ParsedCronJob[] | undefined {
-  const result = parseCronJson(content, { migrate: false })
+  const result = parseCronJson(content)
   if (!result.ok) return undefined
   return result.file.jobs
 }
@@ -203,7 +203,7 @@ async function readExistingJobs(targetPath: string): Promise<readonly ParsedCron
   } catch {
     return []
   }
-  const result = parseCronJson(raw, { migrate: true })
+  const result = parseCronJson(raw)
   if (!result.ok) return []
   return result.file.jobs
 }

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

@@ -8,6 +8,7 @@ import { removeRequestedReviewer } from './decoy-reviewer'
 import type { DeliveryDedup } from './dedup'
 import { isGithubEventAllowed } from './event-allowlist'
 import { encodeGithubReactionRef, type GithubReactionTarget } from './reactions'
+import { listUnresolvedSelfReviewThreads } from './review-thread-resolver'
 
 export type GithubInboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
 
@@ -80,6 +81,18 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
       return ok()
     }
 
+    // A push to an open PR (`synchronize`) is not a message to react to — it is
+    // a trigger to re-check whether the new commits addressed the bot's own
+    // still-open review threads. The check needs a GraphQL round-trip, so it
+    // runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
+    // session when there is at least one such thread. Returning here also keeps
+    // synchronize out of the generic awareness-only fallthrough below.
+    if (event === 'pull_request' && action === 'synchronize') {
+      if (delivery !== '') options.dedup.add(delivery)
+      scheduleReviewThreadRecheck({ payload, selfLogin, options })
+      return ok()
+    }
+
     const teamIsBotMember = await resolveTeamMembership(event, payload, options)
     const classified = classifyGithubInbound(event, payload, selfLogin, {
       teamIsBotMember,
@@ -171,6 +184,96 @@ function defaultScheduleBackgroundTask(task: () => Promise<void>): void {
   void task().catch(() => {})
 }
 
+function scheduleReviewThreadRecheck(input: {
+  payload: Record<string, unknown>
+  selfLogin: string | null
+  options: GithubWebhookHandlerOptions
+}): void {
+  const { payload, selfLogin, options } = input
+  if (selfLogin === null) return
+  const authToken = options.authToken
+  if (authToken === undefined) return
+
+  const repository = readRepository(payload)
+  const pr = readRecord(payload.pull_request)
+  const pullNumber = readNumber(pr, 'number')
+  if (repository === null || pullNumber === null) return
+  const headSha = readString(readRecord(pr?.head), 'sha')
+
+  const fetchImpl = options.fetchImpl ?? fetch
+  const schedule = options.scheduleBackgroundTask ?? defaultScheduleBackgroundTask
+  const target = `${repository.owner}/${repository.name}#${pullNumber}`
+  schedule(async () => {
+    try {
+      const token = await authToken({ repoSlug: `${repository.owner}/${repository.name}` })
+      const result = await listUnresolvedSelfReviewThreads({
+        token,
+        selfLogin,
+        owner: repository.owner,
+        repo: repository.name,
+        prNumber: pullNumber,
+        fetchImpl,
+      })
+      if (!result.ok) {
+        options.logger.warn(`[github] review-thread recheck failed for ${target}: ${result.error}`)
+        return
+      }
+      if (result.threads.length === 0) return
+      options.route(
+        buildRecheckInbound({
+          repository,
+          pullNumber,
+          headSha,
+          rootCommentIds: result.threads.map((t) => t.rootCommentId),
+          title: readString(pr, 'title'),
+        }),
+      )
+    } catch (err) {
+      options.logger.warn(
+        `[github] review-thread recheck failed for ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  })
+}
+
+function buildRecheckInbound(input: {
+  repository: { owner: string; name: string }
+  pullNumber: number
+  headSha: string | null
+  rootCommentIds: readonly number[]
+  title: string | null
+}): InboundMessage {
+  const { repository, pullNumber, headSha, rootCommentIds, title } = input
+  const titleSegment = title !== null && title.trim() !== '' ? `: "${title}"` : ''
+  const shaSegment = headSha !== null ? ` (now at ${headSha.slice(0, 7)})` : ''
+  const idList = rootCommentIds.join(', ')
+  const text =
+    `PR #${pullNumber}${titleSegment} received new commits${shaSegment}. ` +
+    `You have ${rootCommentIds.length} unresolved review thread(s) you authored on this PR ` +
+    `(root comment id(s): ${idList}). For each, check whether the new commits addressed your ` +
+    `concern. If addressed, reply on that thread via channel_send with a short acknowledgement ` +
+    `and resolve_review_thread: true (the thread id is the root comment id). If not addressed, ` +
+    `leave it open. If none are addressed, end your turn without replying.`
+
+  return {
+    adapter: 'github',
+    workspace: `${repository.owner}/${repository.name}`,
+    chat: `pr:${pullNumber}`,
+    thread: null,
+    text,
+    externalMessageId: `pr-${pullNumber}-recheck-${headSha ?? 'unknown'}`,
+    authorId: 'github-system',
+    authorName: 'github',
+    authorIsBot: false,
+    isBotMention: true,
+    replyToBotMessageId: null,
+    mentionsOthers: false,
+    replyToOtherMessageId: null,
+    isDm: false,
+    ts: 0,
+  }
+}
+
 export async function verifySignature(body: string, secret: string, sigHeader: string): Promise<boolean> {
   const expected = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
   const a = Buffer.from(expected)

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

@@ -21,6 +21,7 @@ import {
   parseListHooksPermissionStatus,
 } from './permission-guidance'
 import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
+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 +144,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.
@@ -195,6 +202,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 +218,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
@@ -334,6 +343,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/review-state.ts

@@ -0,0 +1,137 @@
+import type { ReviewStateResolver, ReviewStateResult } from '@/channels/types'
+
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// Answers the re-review stranding guard's question: is the bot's latest
+// EFFECTIVE formal review on this PR a sticky CHANGES_REQUESTED? GitHub clears a
+// same-reviewer CHANGES_REQUESTED only with a later APPROVED or DISMISSED from
+// the same reviewer — a later COMMENTED review does NOT clear it (the PR #644
+// trap). So we walk the bot's own reviews in chronological order, ignore
+// COMMENTED/PENDING, and read the last decisive one.
+export function createGithubReviewStateResolver(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  selfLogin: () => string | null
+  approve: () => boolean
+  fetchImpl?: typeof fetch
+}): ReviewStateResolver {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReviewStateResult> => {
+    const approve = deps.approve()
+    if (req.adapter !== 'github') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = parseTarget(req.workspace, req.chat)
+    if (target === null) {
+      return { ok: false, error: `unparseable github PR target (chat=${req.chat})`, code: 'transient' }
+    }
+    const selfLogin = deps.selfLogin()
+    if (selfLogin === null) {
+      return { ok: false, error: 'github self-identity not resolved; cannot read review state', code: 'transient' }
+    }
+
+    const token = await deps.token({ repoSlug: `${target.owner}/${target.repo}` })
+    const reviews = await fetchSelfReviews(fetchImpl, token, target, selfLogin)
+    if (!reviews.ok) return { ok: false, error: reviews.error, code: reviews.code }
+
+    const lastDecisive = reviews.states.filter(isDecisive).at(-1) ?? null
+    return { ok: true, selfBlocking: lastDecisive === 'CHANGES_REQUESTED', approve }
+  }
+}
+
+type Target = { owner: string; repo: string; prNumber: number }
+
+function parseTarget(workspace: string, chat: string): Target | null {
+  const [owner, repo, ...rest] = workspace.split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '' || rest.length > 0) return null
+  const m = /^pr:(\d+)$/.exec(chat)
+  if (m === null) return null
+  const prNumber = Number(m[1])
+  if (!Number.isSafeInteger(prNumber) || prNumber <= 0) return null
+  return { owner, repo, prNumber }
+}
+
+type SelfReviewsResult =
+  | { ok: true; states: string[] }
+  | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
+
+async function fetchSelfReviews(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: Target,
+  selfLogin: string,
+): Promise<SelfReviewsResult> {
+  const states: string[] = []
+  let url: string | null =
+    `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/pulls/${target.prNumber}/reviews?per_page=100`
+  while (url !== null) {
+    let response: Response
+    try {
+      response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+    } 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 reviews ${response.status}${text !== '' ? `: ${text}` : ''}`,
+        code: classifyStatus(response.status),
+      }
+    }
+    const page = (await response.json().catch(() => null)) as ReviewRow[] | null
+    if (page === null) return { ok: false, error: 'GitHub reviews returned non-JSON', code: 'transient' }
+    for (const row of page) {
+      if (typeof row.state !== 'string') continue
+      const login = row.user?.login ?? null
+      if (login === null) continue
+      const isBot = row.user?.type === 'Bot'
+      if (!isSelfReviewer(login, isBot, selfLogin)) continue
+      states.push(row.state)
+    }
+    url = nextLink(response.headers.get('link'))
+  }
+  return { ok: true, states }
+}
+
+// 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.
+const DECISIVE = new Set(['CHANGES_REQUESTED', 'APPROVED', 'DISMISSED'])
+
+function isDecisive(state: string): boolean {
+  return DECISIVE.has(state)
+}
+
+// A GitHub App's own login differs across REST (`slug[bot]`) and GraphQL (bare
+// `slug`). The REST reviews endpoint returns `slug[bot]` for the App, but the
+// suffix-strip must be gated on the reviewer actually being a Bot: a human User
+// can own the bare slug as a login, and stripping `[bot]` off the App's
+// selfLogin to match a human would wrongly attribute their review to the bot.
+const BOT_LOGIN_SUFFIX = '[bot]'
+
+function isSelfReviewer(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
+}
+
+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
+}
+
+function classifyStatus(status: number): 'not-found' | 'permission-denied' | 'transient' {
+  if (status === 401 || status === 403) return 'permission-denied'
+  if (status === 404) return 'not-found'
+  return 'transient'
+}
+
+type ReviewRow = { id?: number; state?: unknown; user?: { login?: string; type?: string } }