typeclaw 0.37.4 → 0.37.5

package/package.json

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

package/src/agent/doctor.ts

@@ -1,4 +1,9 @@
-import { isAbsolute, normalize } from 'node:path'
+import { posix } from 'node:path'
+
+// changedPaths are a wire format: agentDir-relative POSIX paths the container
+// emits and the host re-validates. Resolved with `path.posix` so a win32 test
+// runner keeps `/`-separators instead of rewriting `memory/x.md` to `memory\x.md`.
+const { isAbsolute, normalize } = posix
 
 import type {
   PluginCheckResult,

package/src/agent/subagents.ts

@@ -241,6 +241,11 @@ export type InvokeSubagentOptions = {
     sessionId: string | undefined
     abort: () => Promise<void>
   }) => void
+  // Sink for the subagent's captured final message (a reviewer `<review>` block,
+  // a researcher `<report>` block, or the last free-form assistant text).
+  // `runSession` owns the capture so the required-block guard can re-prompt
+  // before the result settles; `startSubagent` passes this to receive the output.
+  onFinalMessageCaptured?: (msg: string) => void
 }
 
 export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
@@ -261,6 +266,8 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
       normalizeSubagentSession(await createSessionForSubagent(subagent, sessionOptions))
     let aborted = false
     let drainWatch: SubagentDrainWatch | undefined
+    const requiredBlockTag = REQUIRED_FINAL_BLOCK[name]
+    const capture = attachFinalMessageCapture(session, requiredBlockTag, options.onFinalMessageCaptured ?? (() => {}))
     if (options.onSessionCreated !== undefined) {
       options.onSessionCreated({
         session,
@@ -312,6 +319,28 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
           cancelled: () => aborted,
         })
       }
+      // Required-block guard (mirrors the channel empty-response guard): a subagent
+      // that owes a result block but ended without one gets a bounded re-prompt to
+      // emit it as text, then an honest fallback — never a silent stale-preamble
+      // result or a loud failure. Runs strictly after the drain settles so it is a
+      // final contract-repair pass, not another research phase; it deliberately
+      // does NOT re-run the drain.
+      if (requiredBlockTag !== undefined) {
+        for (
+          let attempt = 1;
+          !aborted && !capture.hasRequiredBlock() && attempt <= MAX_REQUIRED_BLOCK_RETRIES;
+          attempt++
+        ) {
+          console.warn(
+            `[subagent] ${name} required_block_retry attempt=${attempt}/${MAX_REQUIRED_BLOCK_RETRIES} tag=${requiredBlockTag}`,
+          )
+          await session.prompt(`${renderTurnTimeAnchor()}\n\n${renderRequiredBlockRetryNudge(requiredBlockTag)}`)
+        }
+        if (!aborted && !capture.hasRequiredBlock()) {
+          console.warn(`[subagent] ${name} required_block_fallback tag=${requiredBlockTag}`)
+          capture.setSyntheticFinalMessage(renderMissingRequiredBlockFallback(name, requiredBlockTag))
+        }
+      }
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionIdle({
           sessionId,
@@ -432,6 +461,9 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
 
   const work = invokeSubagent(name, {
     ...options,
+    onFinalMessageCaptured: (msg) => {
+      finalMessage = msg
+    },
     onSessionCreated: (event) => {
       handleSettled = true
       abortSession = event.abort
@@ -439,9 +471,6 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
       if (options.onSession !== undefined) {
         options.onSession(event)
       }
-      attachFinalMessageCapture(event.session, (msg) => {
-        finalMessage = msg
-      })
     },
   })
     .then(() => ({ ok: true as const, ...(finalMessage !== undefined ? { finalMessage } : {}) }))
@@ -497,22 +526,102 @@ function raceSubagentCompletion(
   })
 }
 
-// A complete <review>...</review> block. The reviewer's contract is that this
-// block IS its result; same-message preamble/trailing chatter or a later
-// summary turn must not become the captured final message. `[\s\S]` spans
-// newlines (the block is multi-line); non-greedy stops at the first close so an
-// incidental `<review>` literal in reviewed text cannot swallow real content.
-// Global so a message with several blocks yields the last (the revision).
-const REVIEW_BLOCK_RE = /<review>[\s\S]*?<\/review>/g
+// The tags a subagent can use to wrap its structured result: the reviewer's
+// `<review>`, the researcher's `<report>`. Fixed literals — never user input —
+// so the per-tag patterns below are injection-safe.
+type FinalBlockTag = 'review' | 'report'
+
+// A complete <TAG>...</TAG> block. The block IS the result: same-message
+// preamble/trailing chatter or a later summary turn must not become the captured
+// final message. `[\s\S]` spans newlines (the block is multi-line); non-greedy
+// stops at the first close so an incidental `<TAG>` literal in the wrapped text
+// cannot swallow real content. Global so a message with several blocks yields the
+// last (the revision).
+const FINAL_BLOCK_RE: Readonly<Record<FinalBlockTag, RegExp>> = {
+  review: /<review>[\s\S]*?<\/review>/g,
+  report: /<report>[\s\S]*?<\/report>/g,
+}
 
-function lastReviewBlock(text: string): string | null {
-  const matches = text.match(REVIEW_BLOCK_RE)
+function lastTaggedBlock(text: string, tag: FinalBlockTag): string | null {
+  const matches = text.match(FINAL_BLOCK_RE[tag])
   return matches === null ? null : (matches[matches.length - 1] ?? null)
 }
 
-function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg: string) => void): void {
+// Subagents whose result IS a REQUIRED tagged block — the parent must receive
+// that block or a loud failure, never a stale earlier turn. The researcher's
+// contract (src/bundled-plugins/researcher/researcher.ts) mandates a closing
+// `<report>` block; when an upstream provider retry loop ends the run on
+// unexecuted `write_report` tool calls, the researcher never emits it, and
+// without this gate the capture would silently return its earlier `<analysis>`
+// preamble as a "successful" result — the production regression this guards.
+// Keyed by the stable bundled-subagent registry name. This is STRICTER than the
+// reviewer's `<review>` (preferred, but falls back to free-form text): only the
+// subagents listed here fail loud when their block is absent.
+const REQUIRED_FINAL_BLOCK: Readonly<Record<string, FinalBlockTag>> = { researcher: 'report' }
+
+// Bounded re-prompt budget for the required-block guard, mirroring the channel
+// empty-response guard's MAX_EMPTY_TURN_RETRIES. A subagent that owes a result
+// block but ended without one is nudged at most this many times before the
+// honest fallback is installed.
+const MAX_REQUIRED_BLOCK_RETRIES = 2
+
+// The recovery nudge. It MUST forbid tools: the known failure mode is a provider
+// retry loop on the report-writing tool call, so re-driving the tool path would
+// just re-trigger the loop. Asking for the block as plain text is the repair.
+function renderRequiredBlockRetryNudge(tag: FinalBlockTag): string {
+  return `---
+**[SYSTEM MESSAGE — not from a human]**
+
+Your previous turn ended without the required <${tag}> block. This is an automated runtime recovery signal, not a human message.
+
+Emit the final <${tag}>...</${tag}> block NOW as plain assistant text. Do NOT call any tools — in particular do NOT call write_report. Do NOT continue researching or spawn more subagents.
+
+If the report file was not successfully written, still emit the block: set <report_file>none</report_file>, <confidence>low</confidence> (explain the report artifact was not completed), and note in <open_questions> that the run should be retried.
+
+Output exactly one <${tag}> block and nothing else.`
+}
+
+// The terminal graceful fallback when the nudges are exhausted. It fabricates NO
+// findings — only a structured, low-confidence "could not complete" notice — so
+// the parent gets a usable result instead of stale `<analysis>` or a hard error.
+function renderMissingRequiredBlockFallback(name: string, tag: FinalBlockTag): string {
+  if (tag === 'report') {
+    return `<report>
+<summary>
+The ${name} subagent could not complete a research report in this run: it ended without emitting the required <report> block (a known cause is the report tool not completing). Do not treat any earlier analysis text as findings — rerun the researcher or gather the sources directly if the answer is still needed.
+</summary>
+<report_file>
+none
+</report_file>
+<confidence>
+low — no complete research report artifact was produced.
+</confidence>
+<open_questions>
+The original research request remains unresolved; rerun the ${name} subagent or gather the sources directly.
+</open_questions>
+</report>`
+  }
+  return `<${tag}>\nThe ${name} subagent ended without emitting the required <${tag}> block and could not recover; rerun it or inspect the transcript.\n</${tag}>`
+}
+
+type SubagentCapture = {
+  // True once a required-block subagent (researcher) has emitted its `<report>`
+  // block; always false for subagents without a required block.
+  hasRequiredBlock: () => boolean
+  // Install a captured final message directly — used by the required-block guard
+  // to set an honest fallback when the block was never emitted, so the parent
+  // gets a structured result rather than stale preamble.
+  setSyntheticFinalMessage: (msg: string) => void
+}
+
+function attachFinalMessageCapture(
+  session: AgentSession,
+  requiredBlockTag: FinalBlockTag | undefined,
+  onFinalMessage: (msg: string) => void,
+): SubagentCapture {
   let lastAssistant: string | null = null
   let lastReview: string | null = null
+  let lastRequired: string | null = null
   try {
     session.subscribe((event: unknown) => {
       const ev = event as { type?: string; message?: { role?: string; content?: unknown } }
@@ -524,7 +633,23 @@ function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg:
       const text = extractFinalMessageText(ev.message?.content)
       if (text === null) return
       lastAssistant = text
-      const review = lastReviewBlock(text)
+
+      // Required-block contract (researcher): the result IS the block. A turn
+      // with text but no block — the `<analysis>` preamble, a process narrative —
+      // must NOT become the captured result, so `hasRequiredBlock` stays false and
+      // the guard in runSession re-prompts rather than returning stale preamble.
+      if (requiredBlockTag !== undefined) {
+        const block = lastTaggedBlock(text, requiredBlockTag)
+        if (block !== null) {
+          lastRequired = block
+          onFinalMessage(lastRequired)
+        }
+        return
+      }
+
+      // Preferred-block contract (reviewer) / free-form: a `<review>` block wins
+      // when present; otherwise the last free-form assistant text is the result.
+      const review = lastTaggedBlock(text, 'review')
       if (review !== null) lastReview = review
       onFinalMessage(lastReview ?? lastAssistant)
     })
@@ -532,6 +657,13 @@ function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg:
     // session.subscribe is a stable upstream API; defensive try is for test
     // doubles that don't implement it.
   }
+  return {
+    hasRequiredBlock: () => lastRequired !== null,
+    setSyntheticFinalMessage: (msg) => {
+      lastRequired = msg
+      onFinalMessage(msg)
+    },
+  }
 }
 
 function extractFinalMessageText(content: unknown): string | null {

package/src/agent/todo/scope.ts

@@ -51,6 +51,8 @@ export function resolveTodoScope(origin: SessionOrigin): TodoScope | null {
   }
 }
 
+const CHANNEL_SCOPE_SEPARATOR = ','
+
 function channelScopeKey(origin: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
   const parts = [
     encodeComponent(origin.adapter),
@@ -58,7 +60,7 @@ function channelScopeKey(origin: { adapter: string; workspace: string; chat: str
     encodeComponent(origin.chat),
     encodeComponent(origin.thread),
   ]
-  return `channel/${parts.join(':')}`
+  return `channel/${parts.join(CHANNEL_SCOPE_SEPARATOR)}`
 }
 
 // Encode one scope component injectively. Every component is emitted as a
@@ -69,7 +71,7 @@ function channelScopeKey(origin: { adapter: string; workspace: string; chat: str
 // confused: a null thread vs a literal "n" string, an empty string vs a
 // literal "_empty" string, and any value vs another whose unsafe chars happen
 // to map together. `encodeURIComponent` is itself injective and never emits
-// `/` or `:`, so the joined key is both a single filesystem-safe path segment
+// `/` or `,`, so the joined key is both a single filesystem-safe path segment
 // and a collision-free identity for the conversation whose todo file it names.
 function encodeComponent(value: string | null): string {
   if (value === null) return 'n'

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

@@ -78,15 +78,13 @@ export function createChannelReplyTool({
           },
         ),
       ),
-      continue: Type.Optional(
-        Type.Boolean({
-          description:
-            'Set `true` when this reply is a mid-turn status update (e.g. "working on it…") and you still have work to do THIS turn — fetching data, running a tool, spawning a subagent, then replying again. ' +
-            'Omitting it on such an ack silently truncates the turn: a successful reply ends the turn by default, so the fetch/subagent/answer you intended to do next never runs. ' +
-            'A normal final reply omits this (no wasted follow-up LLM call). ' +
-            'Do not set it just to seem responsive; only when genuine multi-step work follows in the same turn.',
-        }),
-      ),
+      continue: Type.Boolean({
+        description:
+          'REQUIRED on every channel_reply — you must explicitly choose, there is no default. Set `true` when this reply is a mid-turn status update (e.g. "working on it…") and you still have work to do THIS turn — fetching data, running a tool, spawning a subagent, then replying again; `true` keeps the turn alive so that follow-up actually runs. ' +
+          'Set `false` when this reply is your final message for the turn (the common case). ' +
+          'This choice is mandatory precisely because a missing value used to default to ending the turn silently: a successful reply ends the turn unless `continue` is `true`, so a `false` on an ack you meant to keep working from drops the work you promised. ' +
+          'Do not set `true` just to seem responsive; only when genuine multi-step work follows in the same turn.',
+      }),
       resolve_review_thread: Type.Optional(
         Type.Boolean({
           description:

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

@@ -155,12 +155,17 @@ const VECTOR_TURN_TOP_K = 10
 // without loading the ~279 MB model, or `hybridSearch` to fake retrieval while
 // testing hook orchestration — without leaking state across other tests in the
 // same worker. Production uses the real `embed` and `hybridSearch`.
-type MemoryPluginDeps = {
+export type MemoryPluginDeps = {
   hybridSearch: typeof hybridSearch
   queryEmbedFn: EmbedFn
+  openAppendVectorStore: (agentDir: string) => VectorStore
 }
 
-const defaultDeps: MemoryPluginDeps = { hybridSearch, queryEmbedFn: embed }
+const defaultDeps: MemoryPluginDeps = {
+  hybridSearch,
+  queryEmbedFn: embed,
+  openAppendVectorStore: (agentDir) => VectorStore.open(join(agentDir, 'memory', '.vectors', 'index.db')),
+}
 
 // Builds the per-turn user-prompt memory block for a vector agent. Non-channel
 // turns always use top-K hybrid search, regardless of total shard size. Repeated
@@ -231,7 +236,7 @@ async function renderVectorTurnMemory(
   }
 }
 
-function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
+export function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
   return definePlugin({
     configSchema: memoryConfigSchema,
     plugin: async (ctx) => {
@@ -401,9 +406,7 @@ function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
       }
 
       // Open a long-lived VectorStore for append-time indexing when vector is enabled.
-      const appendVectorStore = ctx.config.vector.enabled
-        ? VectorStore.open(join(ctx.agentDir, 'memory', '.vectors', 'index.db'))
-        : undefined
+      const appendVectorStore = ctx.config.vector.enabled ? deps.openAppendVectorStore(ctx.agentDir) : undefined
 
       return {
         subagents: {

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

@@ -6,6 +6,7 @@ import type { SessionOrigin } from '@/agent/session-origin'
 import { buildInjectionPlan, DEFAULT_INJECTION_BUDGET_BYTES, type InjectionPlan } from './injection-plan'
 import { loadAllShards, type TopicShard } from './load-shards'
 import { topicsDir } from './paths'
+import { slugIsHeadingEcho } from './slug'
 import type { DedupedRetrievedItem } from './turn-dedup'
 
 const MAX_FILE_BYTES = 12 * 1024
@@ -130,7 +131,7 @@ export function renderRetrievedMemorySection(
       lines.push(`## ${item.heading}`)
       lines.push(item.excerpt.trimEnd(), '')
     } else if (item.source === 'topic' || item.source === 'reference') {
-      lines.push(`- ${item.heading} \`${item.key}\``)
+      lines.push(topicIndexEntry(item.heading, item.key))
     } else {
       lines.push(`- ${item.heading} _(recent observation)_`)
     }
@@ -150,11 +151,24 @@ export function renderTopicIndexMemorySection(
   if (options.origin?.kind === 'channel') lines.push(...CHANNEL_MEMORY_BOUNDARY, '')
   lines.push(topicIndexDirective(options), '')
   for (const shard of shards) {
-    lines.push(`- ${shard.frontmatter.heading} \`${shard.slug}\``)
+    lines.push(topicIndexEntry(shard.frontmatter.heading, shard.slug))
   }
   return lines.join('\n').trimEnd()
 }
 
+// A topic-index line names a topic so the model can decide whether to open it
+// (the slug is the `memory_search({ topic })` key). When the slug is just a kebab
+// echo of the heading the heading adds no signal, so render the slug alone; keep
+// both when they diverge (e.g. `gh-api-labels-array-syntax` vs "GitHub API label
+// management in the agent environment") or when the heading has no ASCII form
+// (e.g. CJK), where `slugIsHeadingEcho` returns false and the readable name stays.
+function topicIndexEntry(heading: string, slug: string): string {
+  if (slugIsHeadingEcho(heading, slug)) {
+    return `- \`${slug}\``
+  }
+  return `- ${heading} \`${slug}\``
+}
+
 function topicIndexDirective(options: Pick<LoadMemoryOptions, 'origin'>): string {
   if (options.origin?.kind === 'channel') {
     return 'Memory shown as headings only in channels. Call `memory_search({ topic: "<slug>" })` with a slug below to read a full body.'

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

@@ -20,6 +20,25 @@ export function headingToSlug(heading: string, existingSlugs: Set<string>): stri
   return slug
 }
 
+// True only when `slug` is a clean kebab echo of `heading` (the readable form
+// adds nothing the slug doesn't). `headingToSlug` maps every non-ASCII letter,
+// ideograph, or symbol to `-` (or to an `untitled-<hash>` when nothing survives),
+// so a heading like `한글 memo` slugifies to `memo` and an all-CJK/emoji heading to
+// the fallback — collapsing either would drop the only human-readable name. Guard
+// by requiring the diacritic-folded heading to consist solely of ASCII
+// alphanumerics and separators/punctuation; any surviving CJK/emoji/symbol means
+// normalization discarded content, so it is never an echo. (Diacritics are
+// transliterated, not dropped — `café` → `cafe` stays a legitimate echo.)
+const ECHO_SAFE_HEADING = /^[A-Za-z0-9\s\p{P}]*$/u
+
+export function slugIsHeadingEcho(heading: string, slug: string): boolean {
+  const folded = heading.normalize('NFD').replace(/[\u0300-\u036f]/g, '')
+  if (!ECHO_SAFE_HEADING.test(folded)) {
+    return false
+  }
+  return headingToSlug(heading, new Set<string>()) === slug
+}
+
 function normalizeHeading(heading: string): string {
   let normalized = heading.normalize('NFD').replace(/[\u0300-\u036f]/g, '')
 

package/src/bundled-plugins/security/policies/private-surface-read.ts

@@ -178,7 +178,10 @@ function matchHidden(
   }
   for (const dir of deniedDirs) {
     const realDir = realpathRealIntendedPath(dir)
-    if (resolved === realDir || resolved.startsWith(`${realDir}/`)) return dir
+    // realpathRealIntendedPath joins with the platform separator, so the
+    // under-dir test must use path.sep too — a hardcoded "/" never matches the
+    // "\"-joined paths a win32 test runner produces.
+    if (resolved === realDir || resolved.startsWith(`${realDir}${path.sep}`)) return dir
   }
   return undefined
 }

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

@@ -61,56 +61,81 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     }
 
     const delivery = req.headers.get('x-github-delivery') ?? ''
-    if (delivery !== '' && options.dedup.has(delivery)) {
-      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
-      return ok()
-    }
-
     const event = req.headers.get('x-github-event') ?? ''
     const payload = parseJson(body)
     if (payload === null) return ok()
-    const action = readString(payload, 'action')
-    if (!isGithubEventAllowed(options.allowlist(), event, action)) return ok()
-
-    const selfId = options.selfId()
-    const selfLogin = options.selfLogin()
-    const author = readAuthor(event, payload)
-    if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
-      maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
-      options.logger.info(
-        `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
-      )
-      return ok()
-    }
+    // The HTTP request is only transport; event handling is the shared core.
+    await processVerifiedGithubDelivery(options, { event, delivery, payload })
+    return ok()
+  }
+}
 
-    // A push to an open PR (`synchronize`) is not a message to react to — it is
-    // a trigger to re-evaluate the bot's own outstanding review obligations on
-    // this PR: unresolved review threads it authored AND a sticky
-    // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
-    // verdict — the black hole this path closes). Both need an API round-trip,
-    // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
-    // session when an obligation is outstanding. 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)
-      scheduleReviewFollowup({ payload, selfLogin, options })
-      return ok()
+// Post-verification core shared by the live HTTP handler AND the missed-delivery
+// recovery sweep (recover-failed-deliveries.ts), which pulls lost payloads from
+// GitHub's authenticated deliveries API and re-injects them with no HTTP request
+// or signature. Routing both through this one function is the load-bearing
+// invariant: recovery must never become a second, divergent event pipeline.
+// `delivery` is the `X-GitHub-Delivery` GUID (stable across redeliveries, equal
+// to a delivery's `guid`) used as the dedup key, so a recovered event and its
+// later/duplicate live delivery collapse to one route. HMAC is the caller's job:
+// the live handler verifies the body; the sweep trusts the authenticated API.
+export async function processVerifiedGithubDelivery(
+  options: GithubWebhookHandlerOptions,
+  input: { event: string; delivery: string; payload: Record<string, unknown> },
+): Promise<void> {
+  const { event, delivery, payload } = input
+  if (delivery !== '') {
+    if (options.dedup.has(delivery)) {
+      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
+      return
     }
+    // Reserve the delivery id synchronously, BEFORE the awaits below, so a live
+    // webhook and the recovery sweep can never both clear the dedup gate for the
+    // same event and route it twice. JS is single-threaded: nothing else runs
+    // between this has-check and add, so the reservation is atomic. The awaits
+    // and classify that follow are all throw-safe, so reserving early cannot
+    // strand a routable event.
+    options.dedup.add(delivery)
+  }
 
-    const teamIsBotMember = await resolveTeamMembership(event, payload, options)
-    const reviewCommentParent = await resolveReviewCommentParent(event, payload, selfId, selfLogin, options)
-    const classified = classifyGithubInbound(event, payload, selfLogin, {
-      teamIsBotMember,
-      authType: options.authType?.() ?? 'pat',
-      reviewOn: options.reviewOn?.() ?? 'review_requested',
-      ...(reviewCommentParent !== null ? { reviewCommentParent } : {}),
-    })
-    if (classified === null) return ok()
-
-    if (delivery !== '') options.dedup.add(delivery)
-    options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
-    return ok()
+  const action = readString(payload, 'action')
+  if (!isGithubEventAllowed(options.allowlist(), event, action)) return
+
+  const selfId = options.selfId()
+  const selfLogin = options.selfLogin()
+  const author = readAuthor(event, payload)
+  if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+    maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
+    options.logger.info(
+      `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
+    )
+    return
   }
+
+  // A push to an open PR (`synchronize`) is not a message to react to — it is
+  // a trigger to re-evaluate the bot's own outstanding review obligations on
+  // this PR: unresolved review threads it authored AND a sticky
+  // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
+  // verdict — the black hole this path closes). Both need an API round-trip,
+  // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
+  // session when an obligation is outstanding. Returning here also keeps
+  // synchronize out of the generic awareness-only fallthrough below.
+  if (event === 'pull_request' && action === 'synchronize') {
+    scheduleReviewFollowup({ payload, selfLogin, options })
+    return
+  }
+
+  const teamIsBotMember = await resolveTeamMembership(event, payload, options)
+  const reviewCommentParent = await resolveReviewCommentParent(event, payload, selfId, selfLogin, options)
+  const classified = classifyGithubInbound(event, payload, selfLogin, {
+    teamIsBotMember,
+    authType: options.authType?.() ?? 'pat',
+    reviewOn: options.reviewOn?.() ?? 'review_requested',
+    ...(reviewCommentParent !== null ? { reviewCommentParent } : {}),
+  })
+  if (classified === null) return
+
+  options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
 }
 
 export const PR_APPROVAL_DISABLED_NOTE =