typeclaw 0.27.0 → 0.28.0

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/review-thread-resolver.ts

@@ -128,6 +128,69 @@ function parseDecimalId(value: string | undefined): number | null {
 }
 
 async function findThread(fetchImpl: typeof fetch, token: string, target: ResolveTarget): Promise<ThreadLookup> {
+  let lookup: ThreadLookup = { kind: 'absent' }
+  const outcome = await walkThreadPages(
+    fetchImpl,
+    token,
+    { owner: target.owner, repo: target.repo, prNumber: target.prNumber },
+    (nodes) => {
+      for (const node of nodes) {
+        if (node.rootCommentId === target.rootCommentId) {
+          lookup = { kind: 'found', thread: node }
+          return 'stop'
+        }
+      }
+      return 'continue'
+    },
+  )
+  if (outcome.kind === 'error') return { kind: 'error', result: outcome.result }
+  return lookup
+}
+
+export type UnresolvedSelfReviewThread = { threadId: string; rootCommentId: number }
+
+export type ListUnresolvedSelfReviewThreadsResult =
+  | { ok: true; threads: UnresolvedSelfReviewThread[] }
+  | { ok: false; error: string }
+
+// Reuses the same page-walk and authorship guard (`isSelfAuthor`) as the
+// single-thread resolver so the post-push "did my comments get addressed?"
+// sweep can never surface a human reviewer's thread as a resolve candidate.
+export async function listUnresolvedSelfReviewThreads(deps: {
+  token: string
+  selfLogin: string
+  owner: string
+  repo: string
+  prNumber: number
+  fetchImpl?: typeof fetch
+}): Promise<ListUnresolvedSelfReviewThreadsResult> {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  const threads: UnresolvedSelfReviewThread[] = []
+  const outcome = await walkThreadPages(
+    fetchImpl,
+    deps.token,
+    { owner: deps.owner, repo: deps.repo, prNumber: deps.prNumber },
+    (nodes) => {
+      for (const node of nodes) {
+        if (node.isResolved || node.rootCommentId === null) continue
+        if (!isSelfAuthor(node, deps.selfLogin)) continue
+        threads.push({ threadId: node.id, rootCommentId: node.rootCommentId })
+      }
+      return 'continue'
+    },
+  )
+  if (outcome.kind === 'error') return { ok: false, error: outcome.result.error }
+  return { ok: true, threads }
+}
+
+type WalkOutcome = { kind: 'done' } | { kind: 'error'; result: ReviewThreadResolveResult & { ok: false } }
+
+async function walkThreadPages(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: { owner: string; repo: string; prNumber: number },
+  onPage: (nodes: ReviewThreadNode[]) => 'stop' | 'continue',
+): Promise<WalkOutcome> {
   let after: string | null = null
   for (;;) {
     let response: Response
@@ -148,11 +211,8 @@ async function findThread(fetchImpl: typeof fetch, token: string, target: Resolv
     }
     const parsed = await parseThreadsPage(response)
     if (parsed.kind === 'error') return { kind: 'error', result: parsed.result }
-
-    for (const node of parsed.nodes) {
-      if (node.rootCommentId === target.rootCommentId) return { kind: 'found', thread: node }
-    }
-    if (!parsed.hasNextPage || parsed.endCursor === null) return { kind: 'absent' }
+    if (onPage(parsed.nodes) === 'stop') return { kind: 'done' }
+    if (!parsed.hasNextPage || parsed.endCursor === null) return { kind: 'done' }
     after = parsed.endCursor
   }
 }

package/src/channels/github-false-receipt.ts

@@ -0,0 +1,87 @@
+import { classifyReviewClaim } from './github-review-claim'
+import { hasResolvedThread, hasReview } from './github-review-turn-ledger'
+
+// Decides whether a github PR reply is a false receipt: prose that CLAIMS a
+// formal verdict / thread close-out the agent never actually performed this turn.
+// Pure except for the ledger reads (module singletons); returns the action the
+// channel_reply tool should take. Block only the black-and-white cases; warn on
+// soft signals so casual chatter is never hard-denied.
+
+export type FalseReceiptDecision =
+  | { kind: 'allow' }
+  | { kind: 'block'; reason: string }
+  | { kind: 'warn'; notice: string }
+
+export type FalseReceiptInput = {
+  sessionId: string
+  adapter: string
+  workspace: string
+  chat: string
+  thread: string | null
+  text: string | undefined
+  isContinue: boolean
+  resolveReviewThread: boolean
+}
+
+export function checkFalseReceipt(input: FalseReceiptInput): FalseReceiptDecision {
+  if (input.adapter !== 'github') return { kind: 'allow' }
+  const prNumber = prNumberFromChat(input.chat)
+  if (prNumber === null) return { kind: 'allow' }
+
+  const claim = classifyReviewClaim(input.text ?? '')
+  if (claim === 'ignore') return { kind: 'allow' }
+  if (claim === 'warn') return { kind: 'warn', notice: SOFT_NOTICE }
+
+  // A turn the agent explicitly keeps alive (continue:true) is not yet a receipt
+  // — the real action may still be coming. Never block; nudge instead.
+  if (input.isContinue) return { kind: 'warn', notice: SOFT_NOTICE }
+
+  if (claim === 'block-resolve') {
+    if (input.thread === null) return { kind: 'allow' }
+    if (input.resolveReviewThread) return { kind: 'allow' }
+    if (
+      hasResolvedThread({
+        sessionId: input.sessionId,
+        workspace: input.workspace,
+        prNumber,
+        rootCommentId: input.thread,
+      })
+    ) {
+      return { kind: 'allow' }
+    }
+    return { kind: 'block', reason: RESOLVE_REASON }
+  }
+
+  const verdict = claim === 'block-approve' ? 'APPROVE' : 'REQUEST_CHANGES'
+  if (hasReview({ sessionId: input.sessionId, workspace: input.workspace, prNumber, verdict })) {
+    return { kind: 'allow' }
+  }
+  return { kind: 'block', reason: verdict === 'APPROVE' ? APPROVE_REASON : REQUEST_CHANGES_REASON }
+}
+
+function prNumberFromChat(chat: string): number | null {
+  const m = /^pr:(\d+)$/.exec(chat)
+  if (m === null) return null
+  const n = Number(m[1])
+  return Number.isSafeInteger(n) && n > 0 ? n : null
+}
+
+const APPROVE_REASON =
+  'This reply reads as a formal approval, but no APPROVE review was submitted on this PR this turn. ' +
+  'A chat comment is not a GitHub review — submit the formal review via `gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` ' +
+  '(event: APPROVE) first, then narrate if needed. If you are not actually approving, reword the reply.'
+
+const REQUEST_CHANGES_REASON =
+  'This reply reads as a formal "request changes", but no REQUEST_CHANGES review was submitted on this PR this turn. ' +
+  'Submit the formal review via `gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` (event: REQUEST_CHANGES) first. ' +
+  'If you are not actually requesting changes, reword the reply.'
+
+const RESOLVE_REASON =
+  'This reply reads as closing out a review thread, but `resolve_review_thread: true` was not set and the thread ' +
+  'was not resolved this turn. Pass `resolve_review_thread: true` on this reply to actually resolve it, ' +
+  'or reword if the thread should stay open.'
+
+const SOFT_NOTICE =
+  'Note: a chat comment does not create a formal GitHub review or resolve a thread. ' +
+  'If you mean to approve / request changes, submit a formal review via `gh api`; ' +
+  'to close a thread you authored, set `resolve_review_thread: true`.'

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

@@ -0,0 +1,91 @@
+// Deterministic phrase classifier for the false-receipt guard (channel-reply.ts):
+// how strongly does a github PR reply CLAIM a formal verdict/close-out it may not
+// have actually performed? The taxonomy errs toward WARN over BLOCK on purpose —
+// a false block breaks a legitimate reply; a missed soft-fake only loses a nudge.
+
+export type ReviewClaim = 'block-approve' | 'block-request-changes' | 'block-resolve' | 'warn' | 'ignore'
+
+// Word-boundary anchored so "approved" never fires inside "unapproved".
+const BLOCK_APPROVE: readonly RegExp[] = [
+  /\bapproved\b/,
+  /\bapproving\b/,
+  /\bi approve\b/,
+  /\bapproval (submitted|sent|posted)\b/,
+  /\bsubmitting (the )?approval\b/,
+  /\bformal approval\b/,
+  /\blgtm,? approved\b/,
+]
+
+const BLOCK_REQUEST_CHANGES: readonly RegExp[] = [
+  /\brequest(ing|ed)? changes\b/,
+  /\bchanges requested\b/,
+  /\bi request changes\b/,
+  /\bblocking (this|the|merge)\b/,
+  /\bthis is blocked\b/,
+]
+
+// Only consulted by the caller when thread!=null (a review thread). Bare
+// "resolved" is intentionally NOT here — it collides with the warn-tier "looks
+// resolved?"; resolve claims must carry a definite marker (marked/that/this/
+// thanks) or a verify clause.
+const BLOCK_RESOLVE: readonly RegExp[] = [
+  /\bmarked resolved\b/,
+  /\bthread resolved\b/,
+  /\bthat resolves it\b/,
+  /\bthis resolves it\b/,
+  /\bclosing this out\b/,
+  /\bconfirmed fixed\b/,
+  // verify clause + a fix/resolve verb, allowing a short gap ("verified at <sha>, that fixes it").
+  /\b(verified|confirmed)\b[^.!?]*\b(fix(es|ed)|resolv)/,
+  /\b(thanks,?|fixed,?) (looks )?resolved\b/,
+]
+
+// Casual phrasing that might be chatter, not a formal close-out: allow + nudge.
+const WARN: 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/,
+]
+
+// 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.
+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(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/,
+]
+
+export function classifyReviewClaim(rawText: string): ReviewClaim {
+  const text = normalize(rawText)
+  if (text === '') return 'ignore'
+
+  if (DEMOTE_TO_IGNORE.some((re) => re.test(text))) return 'ignore'
+
+  // Block-tier wins over warn-tier: an unambiguous "approved" in a casual message
+  // is still a formal claim.
+  if (BLOCK_APPROVE.some((re) => re.test(text))) return 'block-approve'
+  if (BLOCK_REQUEST_CHANGES.some((re) => re.test(text))) return 'block-request-changes'
+  if (BLOCK_RESOLVE.some((re) => re.test(text))) return 'block-resolve'
+  if (WARN.some((re) => re.test(text))) return 'warn'
+  return 'ignore'
+}
+
+// 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 {
+  return text
+    .toLowerCase()
+    .replace(/[*_`~#>]/g, ' ')
+    .replace(/[^\p{L}\p{N}\s'.!?]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}