typeclaw 0.10.0 → 0.11.1

package/src/channels/router.ts

@@ -29,11 +29,7 @@ import {
   saveChannelSessions,
   type ChannelSessionRecord,
 } from './persistence'
-import {
-  DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS,
-  QUOTED_REPLY_EXCERPT_MAX_CHARS,
-  type ChannelAdapterConfig,
-} from './schema'
+import { QUOTED_REPLY_EXCERPT_MAX_CHARS, type AdapterId, type ChannelAdapterConfig } from './schema'
 import type {
   ChannelHistoryMessage,
   ChannelKey,
@@ -66,6 +62,15 @@ export const TYPING_HEARTBEAT_MS = 8000
 // platform-side typing forever. Slack Assistant status in particular has a
 // documented 2-minute timeout, so repeatedly refreshing it after that point
 // turns a temporary status into a permanent-looking artifact.
+//
+// The cap is measured from `live.typingStartedAt`, which is refreshed by
+// two signals of life (see `bumpTypingActivity`):
+//   1. Each new `drain()` iteration (a new turn is starting).
+//   2. Each `tool_execution_end` from the agent session (a tool just
+//      completed — the prompt is progressing, not stuck).
+// A 2-minute bash command that emits no intermediate events still trips
+// the cap, but a chatty agent running long tools stays under it
+// indefinitely. The cap exists to catch *silence*, not duration.
 export const MAX_TYPING_HEARTBEAT_MS = 2 * 60 * 1000
 
 // Idle GC: a LiveSession whose `lastInboundAt` is older than
@@ -234,6 +239,19 @@ type ObservedInbound = {
   authorIsBot: boolean
   receivedAt: number
   ts: number
+  // Distinguishes scrollback that was bulk-loaded at session cold-start
+  // (`prefetch`) from messages that actually arrived in the channel after
+  // the session went live (`observed`). Both share the same in-memory
+  // shape because the model sees them identically in the prompt's
+  // "Recent context" block, but the quote-anchor decision must treat them
+  // differently: prefetched scrollback is HISTORICAL context, not new
+  // chatter that happened between the primary inbound and the agent's
+  // reply. Counting prefetch entries as "intervening" would fire the
+  // anchor on every fresh-thread first turn (the prefetch stamps
+  // `receivedAt = now()` AFTER the inbound was received during ensureLive,
+  // so by primary-vs-observed timestamp comparison they always look
+  // "later"). See captureQuoteCandidate.
+  source: 'prefetch' | 'observed'
 }
 
 type LiveSession = {
@@ -306,6 +324,31 @@ type LiveSession = {
   // future hard cap without picking a threshold out of thin air.
   sendTimestamps: Map<string, number[]>
   successfulChannelSends: number
+  // Monotonic per-LiveSession turn counter incremented just before each
+  // `live.session.prompt(...)` call in `drain()`. Used as a turn identity
+  // so `skip_response` can record "I skipped turn N" without leaking
+  // across turns. `validateChannelTurn` only honors `skippedTurn` when it
+  // equals `turnSeq`; a stale value from a crashed/aborted prior turn is
+  // ignored (defensive: an unmatched skippedTurn would otherwise silently
+  // drop the next user-facing reply). NOT cleared on drain finally — the
+  // counter is purely monotonic; the matching comparison is what protects
+  // against stale state.
+  turnSeq: number
+  // Snapshot of `successfulChannelSends` taken at turn start (same
+  // moment `turnSeq` increments). Lets `markTurnSkipped` detect "a
+  // channel send already landed in this turn" and reject the skip,
+  // making the rejection symmetric with the send-after-skip lock in
+  // `send()`: commit to silence or commit to replying, not both,
+  // regardless of which order the model tried them in. Updated only at
+  // turn start; reads against the live counter elsewhere are intentional.
+  successfulSendsAtTurnStart: number
+  // Stamped by `markTurnSkipped` (called from the `skip_response` tool)
+  // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
+  // if it matches the just-completed turn, recovery is skipped entirely
+  // (no NO_REPLY check, no Kimi leak check, no assistant-text recovery).
+  // The model has explicitly opted out of this turn and we honor that
+  // unconditionally. `null` when no skip has been recorded.
+  skippedTurn: { turnSeq: number; reason: string } | null
   // Captured by drain() at batch dequeue; read+cleared by send() on the
   // first tool-source send of the turn. The anchor decision (delay
   // threshold + intervening-observed check) is evaluated at SEND time
@@ -327,6 +370,7 @@ type LiveSession = {
   membershipFetch: Promise<MembershipCount | null> | null
   destroyed: boolean
   unsubProviderErrors: (() => void) | null
+  unsubTypingActivity: (() => void) | null
 }
 
 // `event` is null for command invocations that originated outside the inbound
@@ -369,6 +413,11 @@ export const TURN_CAP_ERROR =
   `Send-cap reached for this turn (${MAX_CHANNEL_SENDS_PER_TURN} messages already sent to this conversation). ` +
   'End your turn now. The user can prompt you again for more output.'
 
+export const SKIP_RESPONSE_LOCK_ERROR =
+  'You called `skip_response` earlier in this turn, which committed to staying silent. ' +
+  'Channel sends are blocked for the rest of this turn. End your turn now; if you have ' +
+  'something to say, send it on the next turn.'
+
 export type ChannelRouter = {
   route: (event: InboundMessage) => Promise<void>
   send: (msg: OutboundMessage, opts?: SendOptions) => Promise<SendResult>
@@ -434,6 +483,31 @@ export type ChannelRouter = {
     durationMs: number
     error?: string
   }) => { kind: 'delivered'; keyId: string } | { kind: 'no-live-session' }
+  // Record that the agent invoked `skip_response` during the current turn
+  // for the channel session identified by `parentSessionId`. The reason is
+  // logged at INFO level inside `validateChannelTurn` (single log line per
+  // skip, so operators see exactly one record per silent turn). Stamps the
+  // current `turnSeq` on the live session so a stale record from an earlier
+  // turn cannot drop a future legitimate reply.
+  //
+  // Returns:
+  //   - 'recorded'      — the live session was found and the skip was stamped
+  //   - 'send-already-happened' — a tool-source channel send already landed
+  //                       in this turn; the skip is refused (symmetric with
+  //                       the send-after-skip lock in `send()`) so the model
+  //                       cannot land a reply AND claim silence. The flag is
+  //                       NOT stamped, so the turn proceeds as a normal
+  //                       reply turn.
+  //   - 'no-live-session' — no matching channel session (e.g. tool fired
+  //                         outside a channel origin); the tool should
+  //                         still log the reason but cannot suppress.
+  markTurnSkipped: (args: {
+    parentSessionId: string
+    reason: string
+  }) =>
+    | { kind: 'recorded'; keyId: string }
+    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'no-live-session' }
   stop: () => Promise<void>
   liveCount: () => number
   __testing?: {
@@ -926,6 +1000,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         lastSentText: new Map(),
         sendTimestamps: new Map(),
         successfulChannelSends: 0,
+        turnSeq: 0,
+        successfulSendsAtTurnStart: 0,
+        skippedTurn: null,
         pendingQuoteCandidate: null,
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
@@ -933,10 +1010,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         membershipFetch,
         destroyed: false,
         unsubProviderErrors: null,
+        unsubTypingActivity: null,
       }
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
       })
+      live.unsubTypingActivity = subscribeTypingActivity(created.session, live)
       liveSessions.set(keyId, live)
 
       if (isColdStart) {
@@ -1019,6 +1098,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           authorIsBot: item.message.isBot,
           receivedAt: now(),
           ts: item.message.ts,
+          source: 'prefetch',
         })
       } else {
         observed.push({
@@ -1028,6 +1108,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           authorIsBot: true,
           receivedAt: now(),
           ts: 0,
+          source: 'prefetch',
         })
       }
     }
@@ -1080,9 +1161,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     )
   }
 
+  const bumpTypingActivity = (live: LiveSession): void => {
+    if (live.typingTimer === null) return
+    live.typingStartedAt = now()
+  }
+
+  const subscribeTypingActivity = (session: AgentSession, live: LiveSession): (() => void) => {
+    return session.subscribe((event) => {
+      if (event.type !== 'tool_execution_end') return
+      bumpTypingActivity(live)
+    })
+  }
+
   const startTypingHeartbeat = (live: LiveSession): void => {
     if (live.typingTimedOut || live.typingStopPromise) return
-    if (live.typingTimer || live.destroyed) return
+    if (live.destroyed) return
+    if (live.typingTimer) {
+      bumpTypingActivity(live)
+      return
+    }
     live.typingStartedAt = now()
     // Fire immediately so the indicator appears on the very first inbound,
     // not 8 seconds later.
@@ -1093,7 +1190,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         return
       }
       if (now() - live.typingStartedAt >= MAX_TYPING_HEARTBEAT_MS) {
-        logger.warn(`[channels] ${live.keyId}: typing heartbeat timed out after ${MAX_TYPING_HEARTBEAT_MS}ms`)
+        logger.warn(
+          `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms with no activity; prompt still in flight`,
+        )
         live.typingTimedOut = true
         void stopTypingHeartbeat(live)
         return
@@ -1218,6 +1317,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const observed = live.contextBuffer.splice(0, live.contextBuffer.length)
         const reminders = live.pendingSystemReminders.splice(0, live.pendingSystemReminders.length)
         const text = composeTurnPrompt(observed, batch, {
+          adapter: live.key.adapter,
           loopGuardActive: live.loopGuardActive,
           systemReminders: reminders,
         })
@@ -1227,7 +1327,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
           live.consecutiveSends.clear()
           live.lastSentText.clear()
-          live.pendingQuoteCandidate = captureQuoteCandidate(batch, observed)
+          live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
         } else if (live.lastTurnAuthorId !== null) {
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
           // restore the author identity from the prior turn so author-
@@ -1259,6 +1359,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${live.keyId} prompting batch=${batch.length} text_len=${text.length}`)
         const promptStart = now()
         const successfulSendsBeforePrompt = live.successfulChannelSends
+        live.turnSeq++
+        live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
         await fireSessionTurnStart(live, text)
         try {
           await live.session.prompt(text)
@@ -1538,6 +1640,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       authorIsBot: event.authorIsBot,
       receivedAt: now(),
       ts: event.ts,
+      source: 'observed',
     })
     if (live.contextBuffer.length > CONTEXT_BUFFER_SIZE) {
       live.contextBuffer.splice(0, live.contextBuffer.length - CONTEXT_BUFFER_SIZE)
@@ -1711,17 +1814,17 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const live = liveSessions.get(keyId)
     const sendKey = consecutiveSendKey(msg.chat, msg.thread)
     // Tool-source sends consume the captured quote candidate exactly
-    // once per turn — the decision (delay threshold + intervening-
-    // observed check) runs HERE against the live clock so the relevant
-    // signal is real wall-time between inbound and reply landing, not
-    // drain-vs-send timing artifacts. System sources (recovery, role-
+    // once per turn — the intervening-observed check runs HERE against
+    // the live buffer so the relevant signal is actual channel chatter
+    // between inbound and reply landing, not drain-vs-send timing
+    // artifacts. System sources (recovery, role-
     // claim) skip so they can't accidentally swallow the candidate
     // before the model's own first reply lands. Even when the decision
-    // returns null (delay below threshold, nothing intervened), the
-    // candidate is cleared — a multi-part reply that crosses the
-    // threshold mid-flight must not retroactively anchor chunk 2.
+    // returns null (nothing intervened), the candidate is cleared — a
+    // multi-part reply must not retroactively anchor chunk 2.
     if (live && source === 'tool' && live.pendingQuoteCandidate !== null) {
-      const anchor = decideQuoteAnchor(live.pendingQuoteCandidate, now(), options.configForAdapter(msg.adapter))
+      const quoteCandidate = refreshQuoteCandidate(live.pendingQuoteCandidate, live.contextBuffer)
+      const anchor = decideQuoteAnchor(quoteCandidate, now(), options.configForAdapter(msg.adapter))
       if (anchor !== null) msg = { ...msg, text: prependQuoteAnchor(msg.text ?? '', anchor) }
       live.pendingQuoteCandidate = null
     }
@@ -1739,6 +1842,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     let priorLastSentText: string | undefined
     let reserved = false
     if (live && source === 'tool') {
+      // Tool-source send after `skip_response` for the same turn is a contract
+      // violation: the model already committed to silence. Reject before any
+      // state mutation so the model gets a clear error and the channel stays
+      // silent. System-source sends (recovery, role-claim) are not affected.
+      if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+        return { ok: false, error: SKIP_RESPONSE_LOCK_ERROR, code: 'skip-locked' }
+      }
       const currentCount = live.consecutiveSends.get(sendKey) ?? 0
       if (currentCount >= MAX_CHANNEL_SENDS_PER_TURN) {
         return { ok: false, error: TURN_CAP_ERROR, code: 'turn-cap' }
@@ -1825,6 +1935,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   }
 
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
+    // `skip_response` short-circuit. Must run before the `successfulChannelSends`
+    // check so a model that called both `skip_response` and a channel tool in
+    // the same turn still resolves as "skipped" — the rejection inside `send()`
+    // means the channel tool returned an error and never actually delivered.
+    // Stale-flag protection: only honor when stamped on the just-completed
+    // turn. A flag set by a previous turn that crashed before validation
+    // would otherwise drop the next legitimate user-facing reply.
+    if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+      const { reason } = live.skippedTurn
+      live.skippedTurn = null
+      logger.info(`[channels] ${live.keyId} skipped_by_tool reason=${JSON.stringify(reason)}`)
+      return
+    }
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
     const candidate = recoverableAssistantText(live.session)
@@ -1934,6 +2057,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     live.debounceTimer = null
     live.unsubProviderErrors?.()
     live.unsubProviderErrors = null
+    live.unsubTypingActivity?.()
+    live.unsubTypingActivity = null
     await stopTypingHeartbeat(live)
     try {
       await live.session.abort()
@@ -2071,6 +2196,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return { kind: 'no-live-session' }
   }
 
+  const markTurnSkipped = (args: {
+    parentSessionId: string
+    reason: string
+  }):
+    | { kind: 'recorded'; keyId: string }
+    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'no-live-session' } => {
+    for (const live of liveSessions.values()) {
+      if (live.destroyed) continue
+      if (live.sessionId !== args.parentSessionId) continue
+      if (live.successfulChannelSends > live.successfulSendsAtTurnStart) {
+        return { kind: 'send-already-happened', keyId: live.keyId }
+      }
+      live.skippedTurn = { turnSeq: live.turnSeq, reason: args.reason }
+      return { kind: 'recorded', keyId: live.keyId }
+    }
+    return { kind: 'no-live-session' }
+  }
+
   return {
     route,
     send,
@@ -2093,6 +2237,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     executeCommand,
     getSelfAliases: computeSelfAliases,
     injectSubagentCompletionReminder,
+    markTurnSkipped,
     stop,
     liveCount: () => liveSessions.size,
     __testing: {
@@ -2119,7 +2264,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           return
         }
         if (now() - live.typingStartedAt >= MAX_TYPING_HEARTBEAT_MS) {
-          logger.warn(`[channels] ${live.keyId}: typing heartbeat timed out after ${MAX_TYPING_HEARTBEAT_MS}ms`)
+          logger.warn(
+            `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms with no activity; prompt still in flight`,
+          )
           live.typingTimedOut = true
           await stopTypingHeartbeat(live)
           return
@@ -2159,8 +2306,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
-  state: { loopGuardActive: boolean; systemReminders?: readonly string[] } = { loopGuardActive: false },
+  state: { adapter?: AdapterId; loopGuardActive: boolean; systemReminders?: readonly string[] } = {
+    loopGuardActive: false,
+  },
 ): string {
+  const adapter = state.adapter ?? 'discord-bot'
   const parts: string[] = []
   // System reminders (subagent-completion wakeups today) lead the turn body
   // because they are typically what triggered the drain — when the prompt
@@ -2226,7 +2376,7 @@ function composeTurnPrompt(
   if (observed.length > 0) {
     parts.push('## Recent context (not addressed to you, for awareness only)')
     for (const o of observed) {
-      parts.push(formatAuthorLine(o.ts, o.authorId, o.authorName, o.authorIsBot, o.text))
+      parts.push(formatAuthorLine(o.ts, adapter, o.authorId, o.authorName, o.authorIsBot, o.text))
     }
     parts.push('')
   }
@@ -2244,7 +2394,7 @@ function composeTurnPrompt(
       )
     }
     for (const b of batch) {
-      parts.push(formatAuthorLine(b.ts, b.authorId, b.authorName, b.authorIsBot, b.text))
+      parts.push(formatAuthorLine(b.ts, adapter, b.authorId, b.authorName, b.authorIsBot, b.text))
     }
   }
   return parts.join('\n')
@@ -2252,6 +2402,7 @@ function composeTurnPrompt(
 
 function formatAuthorLine(
   ts: number,
+  adapter: AdapterId,
   authorId: string,
   authorName: string,
   authorIsBot: boolean,
@@ -2259,15 +2410,44 @@ function formatAuthorLine(
 ): string {
   const tag = authorIsBot ? ' [bot]' : ''
   const stamp = ts > 0 ? `[${new Date(ts).toISOString()}] ` : ''
-  return `${stamp}<@${authorId}> (${authorName})${tag}: ${text}`
+  return `${stamp}${formatAuthorReference(adapter, authorId, authorName)} (${authorName})${tag}: ${text}`
 }
 
 export type QuoteAnchorSource = {
+  adapter: AdapterId
+  authorId: string
   authorName: string
   text: string
 }
 
-// Renders the single-line `> @name: excerpt` blockquote prepended to
+// Picks the right author syntax for the platform so prompts and rendered
+// quote anchors use the same form the user would type in that channel.
+// Slack/Discord need id mentions (`<@U…>`), GitHub needs handle mentions
+// (`@login`) because inbound author ids are numeric, and adapters without
+// stable id-only mention syntax fall back to plain display names.
+//
+// Notification semantics: Slack and Discord both render `<@…>` as a
+// styled mention link inside blockquotes; whether the mentioned user is
+// PINGED is a separate platform-level UX (Slack pings on first appearance
+// in the message regardless of position, Discord respects the
+// `allowed_mentions` field which defaults to "ping everyone parsed").
+// This matches PR #374's intent — the user IS being notified that the
+// agent replied to them, which is the whole point of a quote anchor.
+function formatAuthorReference(adapter: AdapterId, authorId: string, authorName: string): string {
+  const displayName = authorName.trim() !== '' ? authorName.trim() : authorId
+  switch (adapter) {
+    case 'slack-bot':
+    case 'discord-bot':
+      return `<@${authorId}>`
+    case 'github':
+      return displayName.startsWith('@') ? displayName : `@${displayName}`
+    case 'telegram-bot':
+    case 'kakaotalk':
+      return displayName
+  }
+}
+
+// Renders the single-line `> @mention: excerpt` blockquote prepended to
 // outbound replies when the router decides the reply needs an anchor.
 // Collapses newlines to spaces so a multi-line user message renders on
 // one quoted line (markdown blockquote semantics: a blank line ends the
@@ -2286,17 +2466,27 @@ export function renderQuoteAnchor(source: QuoteAnchorSource): string {
       : collapsed.length > QUOTED_REPLY_EXCERPT_MAX_CHARS
         ? `${collapsed.slice(0, QUOTED_REPLY_EXCERPT_MAX_CHARS - 1)}…`
         : collapsed
-  return `> @${source.authorName}: ${excerpt}`
+  const mention = formatAuthorReference(source.adapter, source.authorId, source.authorName)
+  return `> ${mention}: ${excerpt}`
 }
 
+// Separates the anchor from the reply with a blank line (`\n\n`), not a
+// single `\n`. In standard GFM and Slack's `markdown` block, a single
+// `\n` inside a paragraph is a soft break rendered as whitespace, which
+// keeps the `>` blockquote styling running visually through the next
+// line — i.e. the agent's reply text gets swallowed into the quote. The
+// blank line forces a paragraph boundary that unambiguously ends the
+// blockquote on every renderer (CommonMark, GFM, Slack mrkdwn, Discord
+// markdown).
 export function prependQuoteAnchor(replyText: string, source: QuoteAnchorSource): string {
   const anchor = renderQuoteAnchor(source)
   if (replyText === '') return anchor
-  return `${anchor}\n${replyText}`
+  return `${anchor}\n\n${replyText}`
 }
 
 type QuoteAnchorBatchEntry = {
   text: string
+  authorId: string
   authorName: string
   authorIsBot: boolean
   receivedAt: number
@@ -2304,6 +2494,7 @@ type QuoteAnchorBatchEntry = {
 
 type QuoteAnchorObservedEntry = {
   receivedAt: number
+  source: 'prefetch' | 'observed'
 }
 
 export type QuoteAnchorCandidate = {
@@ -2312,42 +2503,86 @@ export type QuoteAnchorCandidate = {
   hadInterveningObserved: boolean
 }
 
+// Strips `[<Adapter> message with ...]` placeholders that adapter
+// classifiers synthesize for non-text inbounds (KakaoTalk stickers,
+// Slack/Discord/Telegram attachments). The quote anchor is a UX
+// affordance pointing the human at *their words* — quoting a sticker as
+// `> Alice: [KakaoTalk message with sticker (sticker_ani) pack=... path=...]`
+// is noise, and for mixed inbounds like `사진 [KakaoTalk message with
+// photo 1254x1254 ...]` the human only wrote `사진`, so the placeholder
+// is the wrong thing to surface. The callsite (captureQuoteCandidate)
+// treats an empty residue as "no quote anchor"; mixed inbounds keep the
+// human-written portion. renderQuoteAnchor later collapses whitespace
+// so residual double-spaces from mid-string strips are harmless.
+const CHANNEL_MEDIA_PLACEHOLDER_RE = /\[(?:KakaoTalk|Slack|Discord|Telegram) message with [^\]]*\]/g
+
+export function stripChannelMediaPlaceholders(text: string): string {
+  return text
+    .replace(CHANNEL_MEDIA_PLACEHOLDER_RE, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .trim()
+}
+
 // Snapshot the primary inbound + observed-buffer state at drain time so
 // the send-side decision has the data it needs without holding a
 // reference to the batch arrays. Returns null when there's nothing
-// anchorable (empty batch, primary is a bot).
+// anchorable (empty batch, primary is a bot, or primary is a non-text
+// inbound with no residual human-written text after stripping the
+// adapter's media placeholder).
+//
+// `hadInterveningObserved` counts ONLY live observations (`source ===
+// 'observed'`), not prefetched scrollback. Prefetch stamps `receivedAt =
+// now()` inside ensureLive — wall-clock-later than the primary inbound
+// that triggered ensureLive — so without this gate, every cold-start
+// first turn would see "intervening observed" entries and fire the
+// quote anchor even when the reply lands within milliseconds. The
+// signal we actually want is "did real new chatter arrive between the
+// user's inbound and the agent's reply", which only live observations
+// represent.
 export function captureQuoteCandidate(
+  adapter: AdapterId,
   batch: readonly QuoteAnchorBatchEntry[],
   observed: readonly QuoteAnchorObservedEntry[],
 ): QuoteAnchorCandidate | null {
   if (batch.length === 0) return null
   const primary = batch[batch.length - 1]!
   if (primary.authorIsBot) return null
-  const hadInterveningObserved = observed.some((o) => o.receivedAt >= primary.receivedAt)
+  const cleaned = stripChannelMediaPlaceholders(primary.text)
+  if (cleaned === '') return null
   return {
-    source: { authorName: primary.authorName, text: primary.text },
+    source: { adapter, authorId: primary.authorId, authorName: primary.authorName, text: cleaned },
     primaryReceivedAt: primary.receivedAt,
-    hadInterveningObserved,
+    hadInterveningObserved: hasInterveningObserved(primary.receivedAt, observed),
   }
 }
 
+function refreshQuoteCandidate(
+  candidate: QuoteAnchorCandidate,
+  observed: readonly QuoteAnchorObservedEntry[],
+): QuoteAnchorCandidate {
+  if (candidate.hadInterveningObserved) return candidate
+  if (!hasInterveningObserved(candidate.primaryReceivedAt, observed)) return candidate
+  return { ...candidate, hadInterveningObserved: true }
+}
+
+function hasInterveningObserved(primaryReceivedAt: number, observed: readonly QuoteAnchorObservedEntry[]): boolean {
+  return observed.some((o) => o.source === 'observed' && o.receivedAt >= primaryReceivedAt)
+}
+
 // Send-time decision: given a captured candidate and the current clock,
 // returns the source to anchor against or null. Skips when:
 //   - quotedReply is disabled in config
-//   - delay is under threshold AND no observed messages came between
-//     primary inbound and now (the "felt instantaneous" path)
+//   - no observed messages came between primary inbound and now
 // A null candidate (no batch yet, or batch was bot-only) always skips.
 export function decideQuoteAnchor(
   candidate: QuoteAnchorCandidate | null,
-  nowMs: number,
+  _nowMs: number,
   adapterConfig: ChannelAdapterConfig | undefined,
 ): QuoteAnchorSource | null {
   if (candidate === null) return null
   const config = adapterConfig?.quotedReply
   if (config !== undefined && config.enabled === false) return null
-  const threshold = config?.queueDelayMs ?? DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS
-  const delay = nowMs - candidate.primaryReceivedAt
-  if (delay < threshold && !candidate.hadInterveningObserved) return null
+  if (!candidate.hadInterveningObserved) return null
   return candidate.source
 }
 

package/src/channels/schema.ts

@@ -87,13 +87,12 @@ const historySchema = z
     },
   })
 
-// When the agent's first send of a turn lands ≥ this many ms after the
-// inbound was received, OR there were intervening observed messages
-// between the inbound and the reply, the router prepends a `> @author:
-// ...` blockquote line referencing the inbound so the user can see which
-// message the reply is anchored to even after the channel has scrolled.
-// 10s is the empirical "felt instantaneous" ceiling — anything faster
-// reads as real-time and needs no anchor.
+// Legacy quote-delay knob retained for config compatibility. Quote anchors
+// are now driven by channel ordering instead: when another live-observed
+// message lands between the inbound and the agent's first reply, the router
+// prepends a platform-specific `> author: ...` blockquote line referencing
+// the inbound. If nothing intervened, the reply is adjacent enough in the
+// channel timeline that it needs no anchor regardless of elapsed wall time.
 export const DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS = 10_000
 
 // Long enough to disambiguate; short enough that a multi-paragraph user
@@ -126,6 +125,8 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'discussion_comment.created',
   'issues.opened',
   'pull_request.opened',
+  'pull_request.review_requested',
+  'pull_request.review_request_removed',
   'discussion.created',
   'pull_request_review.submitted',
 ] as const

package/src/channels/types.ts

@@ -84,7 +84,7 @@ export type OutboundMessage = {
   attachments?: OutboundAttachment[]
 }
 
-export type SendErrorCode = 'duplicate' | 'turn-cap' | 'no-adapter' | 'callback-rejected'
+export type SendErrorCode = 'duplicate' | 'turn-cap' | 'no-adapter' | 'callback-rejected' | 'skip-locked'
 
 export type SendResult = { ok: true } | { ok: false; error: string; code?: SendErrorCode }