switchroom 0.18.30 → 0.18.32

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -35,6 +35,60 @@ import {
 import { scrubVoice } from '../text-voice-scrub.js'
 import { isMessageTooLongError, isHtmlParseRejectError } from '../retry-api-call.js'
 
+// ── send-orchestration façade imports (#2996 P2) ──
+// Pure/deterministic helpers are imported; stateful or side-effecting gateway
+// surfaces are injected via SendReplyGatewayDeps (see the DI contract below).
+import { statSync } from 'fs'
+import { extname } from 'path'
+import { GrammyError, InputFile, type Bot, type Context } from 'grammy'
+import {
+  combineReadBackResults,
+  type ReadBackResult,
+} from './backstop-delivery.js'
+import {
+  escapeMarkdown,
+} from '../format.js'
+import { richMessage } from '../rich-send.js'
+import { resolveChatIdFallback } from './chat-id-fallback.js'
+import { isFinalAnswerReply, isSubstantiveFinalReply } from '../final-answer-detect.js'
+import { decideOverPing, type OverPingDecision } from '../over-ping-safety-net.js'
+import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
+import { decideSupersedeCorrection, type FlushedTurnSupersedeRegistry } from '../flushed-turn-supersede.js'
+import { decideAnswerLatchSuppression } from '../reply-owner-resolve.js'
+import { deriveTelegraphTitle } from '../telegraph.js'
+import {
+  mintVoiceOnDemandToken,
+  buildListenKeyboard,
+  mayInjectListenButton,
+  type VoiceOnDemandCache,
+} from '../voice-ondemand.js'
+import { eagerVoiceEnabled, type PreSynthQueue } from '../voice-presynth.js'
+import { validateInlineKeyboard, type AnyButton } from '../telegram-button-constraints.js'
+import {
+  wrapAgentCallbacks,
+  redactAgentKeyboard,
+  extractAgentButtonMeta,
+  type AgentButtonMeta,
+} from '../inline-keyboard-callbacks.js'
+import { classifyPhotoFile, rerouteResultSuffix } from '../photo-precheck.js'
+import { retryWithThreadFallback, isPhotoDimensionRejectError, type RetryCallOpts } from '../retry-api-call.js'
+import { logStreamingEvent } from '../streaming-metrics.js'
+import type { RuntimeMetricEvent } from '../runtime-metrics.js'
+import {
+  settleCapturedProseDelivery,
+  silentEndFallbackText,
+  type SilentEndDeps,
+  type CapturedProseSendOutcome,
+} from '../silent-end.js'
+import type { OutboundDedupCache } from '../recent-outbound-dedup.js'
+import type { DraftStreamHandle } from '../draft-stream.js'
+import type { EmissionAuthority } from './emission-authority.js'
+import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
+// Type-only import from the gateway (erased at compile — no runtime cycle):
+// CurrentTurn/Access are the gateway's own turn + access.json shapes, so the
+// injected closures type EXACTLY as their gateway definitions.
+import type { CurrentTurn, Access } from './gateway.js'
+
 /** The redactor the caller injects. In gateway this is `redactOutboundText`,
  *  which wraps `redact()` and logs (never the secret value) when a mask fires.
  *  Injected rather than imported so the redaction structural-wiring test
@@ -375,3 +429,1961 @@ export async function sendReplyChunks(
 
   return { threadId, previewMessageId }
 }
+
+// ─── Read-back confirmation probe (#3278) ─────────────────────────────────
+//
+// A returned message_id proves Telegram ACCEPTED a send, not that the message
+// is VISIBLE: a server-side accept-then-silently-discard (flood/anti-spam)
+// returns a fresh id yet the user sees nothing. The only echo primitive the Bot
+// API offers (there is no getMessage) is a no-op `editMessageText` against the
+// returned id — a `400 message to edit not found` proves absence, an edit-ok /
+// `message is not modified` proves presence. This primitive classifies that
+// probe per id and combines a chunk's ids into one verdict; the backstop
+// delivery orchestrator (`runBackstopDelivery`) consumes the verdict to decide
+// confirm / demote-and-re-send / leave-unconfirmed. Scoped to the RARE backstop
+// path only — the hot reply-tool send path issues ZERO probes (#3278 §1.3/§1.5).
+
+/**
+ * Classify a single-id read-back `editMessageText` FAILURE into a
+ * {@link ReadBackResult}. Pure over the thrown error:
+ *  - `400 message to edit not found` ⇒ `absent`   (positive drop → safe re-send)
+ *  - `400 message is not modified`   ⇒ `exists`   (a no-op edit → message present)
+ *  - anything else (429 / 5xx / network / thread-not-found / parse) ⇒ `ambiguous`
+ *    (never re-send — a re-send would risk a duplicate).
+ *
+ * A read-back that RESOLVES (the edit applied) means the message existed and is
+ * classified `exists` by the caller — this helper only maps the error branch.
+ */
+export function classifyReadBackError(err: unknown): ReadBackResult {
+  if (err instanceof GrammyError && err.error_code === 400) {
+    const d = (err.description || '').toLowerCase()
+    if (d.includes('message to edit not found')) return 'absent'
+    if (d.includes('not modified')) return 'exists'
+  }
+  return 'ambiguous'
+}
+
+/** Injected per-id probe for {@link createBackstopReadBackProbe}. Resolves to the
+ *  chunk-id's {@link ReadBackResult} — the gateway wires this to a no-op
+ *  `editMessageText` paced through the send gate (cosmetic priority, so it sheds
+ *  under a flood window and never storms); a test supplies a scripted fake. */
+export interface BackstopReadBackDeps {
+  /** Probe ONE landed message id (edit it to `body`, its identical rich render). */
+  probeId: (messageId: number, body: unknown) => Promise<ReadBackResult>
+  /** rich-markdown wrapper (`richMessage`) — the probe edits to the SAME body the
+   *  chunk was sent with, so an existing message returns "not modified" (no
+   *  visible mutation) rather than actually changing the delivered answer. */
+  richMessage: (s: string) => unknown
+}
+
+/**
+ * Build the `readBack` dep injected into `runBackstopDelivery` (#3278). For each
+ * landed chunk it probes EVERY message id (a length-resplit chunk lands >1) and
+ * combines them (guard A7 — the chunk is confirmed only if ALL ids exist; ANY
+ * positive absence ⇒ re-send the whole chunk). An empty id set is `ambiguous`
+ * (nothing to probe → fabricate neither a confirmation nor a demotion).
+ */
+export function createBackstopReadBackProbe(
+  deps: BackstopReadBackDeps,
+): (chunkIndex: number, messageIds: readonly number[], text: string) => Promise<ReadBackResult> {
+  return async (_chunkIndex, messageIds, text) => {
+    if (messageIds.length === 0) return 'ambiguous'
+    const body = deps.richMessage(text)
+    const perId: ReadBackResult[] = []
+    for (const id of messageIds) {
+      perId.push(await deps.probeId(id, body))
+    }
+    return combineReadBackResults(perId)
+  }
+}
+
+/** Injected wiring for {@link createBackstopReadBack}. The gateway supplies its
+ *  raw send primitives; a test can drive the whole probe with fakes. */
+export interface BackstopReadBackWiring {
+  /** Raw `editMessageText` with the chat_id baked in by the caller — edits the
+   *  message to `body` with `apiOpts`; resolves grammy's result or throws the
+   *  raw grammy error (NOT swallowed, so not-found/not-modified stay
+   *  distinguishable via {@link classifyReadBackError}). */
+  editMessageText: (messageId: number, body: unknown, apiOpts: unknown) => Promise<unknown>
+  /** Send-gate wrapper — the probe routes through it at COSMETIC priority so it
+   *  sheds under a flood window (never storms) and paces like every other send. */
+  gate: <T>(fn: () => Promise<T>, opts: RetryCallOpts) => Promise<T>
+  /** `SEND_GATE_SHED` sentinel detector: a shed probe is `ambiguous` (never a
+   *  re-send), NOT a false `exists`. */
+  isShed: (r: unknown) => boolean
+  /** rich-markdown wrapper (`richMessage`). */
+  richMessage: (s: string) => unknown
+  chatId: string
+  threadId: number | undefined
+}
+
+/**
+ * Build the complete #3278 `readBack` dep for `runBackstopDelivery`, owning the
+ * per-id probe: a no-op `editMessageText` to the message's IDENTICAL body,
+ * paced cosmetic through the send gate. A resolved edit (or a `not modified`
+ * 400) ⇒ `exists`; a `message to edit not found` 400 ⇒ `absent`; a gate shed,
+ * 429/5xx/network, or any other throw ⇒ `ambiguous` (never re-send). Per-chunk
+ * ids are combined by {@link createBackstopReadBackProbe} (guard A7).
+ */
+export function createBackstopReadBack(
+  w: BackstopReadBackWiring,
+): (chunkIndex: number, messageIds: readonly number[], text: string) => Promise<ReadBackResult> {
+  const probeId = async (messageId: number, body: unknown): Promise<ReadBackResult> => {
+    // Match the SEND's link_preview_options so editing to the identical body is
+    // a genuine no-op ("message is not modified") and never visibly mutates the
+    // delivered answer. editMessageText targets a globally-unique message_id, so
+    // no message_thread_id is needed on the edit itself.
+    const editApiOpts = { link_preview_options: { is_disabled: true } }
+    // Retry/gate metadata (RetryCallOpts) — keys the gate's per-message edit
+    // floor + cosmetic shedding; NOT sent to Telegram as API params.
+    const gateOpts: RetryCallOpts = {
+      chat_id: w.chatId,
+      verb: 'backstop.readback',
+      priorityClass: 'cosmetic',
+      messageId,
+      editPayload: body,
+      ...(w.threadId != null ? { threadId: w.threadId } : {}),
+    }
+    try {
+      const r = await w.gate(() => w.editMessageText(messageId, body, editApiOpts), gateOpts)
+      return w.isShed(r) ? 'ambiguous' : 'exists'
+    } catch (err) {
+      return classifyReadBackError(err)
+    }
+  }
+  return createBackstopReadBackProbe({ probeId, richMessage: w.richMessage })
+}
+
+// ─── Send-orchestration façade (#2996 P2, Amendments 9/10) ────────────────
+//
+// `executeReply`'s full orchestration body and the `deliverCapturedProse`
+// silent-end-recovery send path, relocated VERBATIM from gateway.ts so the
+// send path is one invocable, testable primitive (see
+// send-reply-golden.test.ts). gateway.ts keeps thin wrappers that pin the
+// turn at entry and inject the live singletons + closures.
+//
+// DI contract (plan Amendment 9 — supersedes the original P2 contract):
+//   - `outboundDedup` is THE one live instance (#546 dedup cache). A re-`new`
+//     anywhere in this module is a hard review-fail: the stream-render (P4)
+//     surface records into the SAME cache, and a second instance reinstates
+//     the duplicate-reply class (Amendment 1).
+//   - BOTH the entry-pinned turn (`req.turn`, #1664 attribution) AND a live
+//     `getCurrentTurn()` accessor are provided. Each call site keeps its
+//     original pin-vs-live choice VERBATIM — the live re-reads (over-ping
+//     block, card-finalize, silent-anchor, dedup registry keys) are
+//     load-bearing: a turn that ends mid-send must skip card-finalize.
+//     Collapsing to pin-everywhere is a forbidden behavior change.
+//   - `backstopDeliveryLedger` and `sendGate` are deliberately NOT injected:
+//     0 references in this body (the ledger is the P4 stream surface's dep;
+//     the send gate lives inside the injected `robustApiCall`).
+//   - Pure helpers are IMPORTED; anything stateful, side-effecting, or
+//     gateway-configured is INJECTED (so the golden harness can fake it).
+//
+// The bodies below are byte-identical to the pre-move gateway.ts inline
+// bodies except for the 8 enumerated pin-vs-live spellings
+// (`currentTurn` -> `getCurrentTurn()` / `req.turn` /
+// `getLastActiveTurnChatId()`) and the deps destructure preamble. Do not
+// "clean up" while moving — bugfixes ship as separate PRs.
+
+/** The subset of the gateway's voice-out plan the send path consumes. */
+export interface VoiceOutPlan {
+  engine: 'kokoro' | 'openai'
+  voice?: string
+  speed: number
+  apiKeyRef?: string
+  replyMode: 'voice+text' | 'voice-only' | 'on-demand'
+  ttsChunks: string[]
+}
+
+export interface SendReplyRequest {
+  /** Raw `reply` tool args, exactly as the MCP dispatch received them. */
+  args: Record<string, unknown>
+  /** #1664 — the turn pinned at executeReply entry by the gateway wrapper.
+   *  Late writes (finalAnswerDelivered) attribute to THIS turn even if the
+   *  module-scope turn rolls over mid-call. */
+  turn: CurrentTurn | null
+}
+
+/** Gateway dependencies for {@link sendReply}. Function members use method
+ *  syntax deliberately (bivariant) so the gateway's more-precisely-typed
+ *  closures are assignable without adapter noise. */
+export interface SendReplyGatewayDeps {
+  // ── shared singletons — the ONE live instance each (Amendment 1/9) ──
+  outboundDedup: OutboundDedupCache
+  flushedTurnSupersede: FlushedTurnSupersedeRegistry
+  firstTextReplyLogged: Set<string>
+  suppressPtyPreview: Set<string>
+  activeDraftStreams: Map<string, DraftStreamHandle>
+  lastPtyPreviewByChat: Map<string, string>
+  voiceOnDemandCache: VoiceOnDemandCache
+  voicePreSynthQueue: PreSynthQueue
+  /** cross-turn pending-async ambient ticker (module-singleton namespace). */
+  pendingProgress: {
+    clearPending(key: string, reason: string): void
+    noteOutbound(key: string, anchor: { messageId: number; text: string; literalText: boolean }): void
+  }
+  /** outbound-gap / TTFO KPI tracker (module-singleton namespace). */
+  signalTracker: {
+    noteOutbound(key: string, at: number): void
+    noteSignal(key: string, at: number): void
+  }
+  /** silence-poke clock (module-singleton namespace). */
+  silencePoke: { noteOutbound(key: string, at: number): void }
+
+  // ── turn identity (Amendment 9: pin-vs-live preserved per call site) ──
+  getCurrentTurn(): CurrentTurn | null
+  getLastActiveTurnChatId(): string | undefined
+
+  // ── gateway config values ──
+  HISTORY_ENABLED: boolean
+  TURN_ORIGIN_ROUTING_ENABLED: boolean
+  AUTOCLASSIFY_MIDTURN_SHADOW: boolean
+  MAX_ATTACHMENT_BYTES: number
+  MAX_CHUNK_LIMIT: number
+  PHOTO_EXTS: Set<string>
+
+  // ── bot + retry policy (the send gate lives inside robustApiCall) ──
+  lockedBot: Bot<Context>
+  robustApiCall<T>(fn: () => Promise<T>, opts?: RetryCallOpts): Promise<T>
+  swallowingApiCall(fn: () => Promise<unknown>, meta: RetryCallOpts): Promise<unknown>
+
+  // ── gateway closures ──
+  loadAccess(): Access
+  redactOutboundText(text: string, site: string): string
+  assertAllowedChat(chatId: string | number): void
+  assertSendable(f: string): void
+  statusKey(chatId: string, threadId?: number | null): string
+  streamKey(chatId: string, threadId?: number | null): string
+  resolveReplyOwnerTurn(liveTurn: CurrentTurn | null, chatId: string, args: Record<string, unknown>): CurrentTurn | null
+  findTurnByOriginId(originTurnId: string | null | undefined): CurrentTurn | null
+  findTurnByQuotedMessageId(chatId: string, replyTo: unknown): CurrentTurn | null
+  resolveAnswerThreadWithLog(
+    chatId: string,
+    explicitThreadId: number | undefined,
+    originTurn: CurrentTurn | null,
+    originVia: 'echo' | 'quoted' | null,
+    liveTurn: CurrentTurn | null,
+    surface: 'reply' | 'stream_reply',
+  ): number | undefined
+  resolveThreadId(chatId: string, explicit?: string | number | null): number | undefined
+  getLatestInboundMessageId(chatId: string, threadId: number | null): number | null | undefined
+  recordOutbound(rec: {
+    chat_id: string
+    thread_id: number | null
+    message_ids: number[]
+    texts: string[]
+    attachment_kinds?: (string | null)[]
+  }): void
+  emissionAuthorityFor(turn: CurrentTurn): EmissionAuthority
+  clearActivitySummary(turn: CurrentTurn, finalHtmlOverride?: string | null): void
+  startTypingLoop(chatId: string, threadId?: number | null): void
+  stopTypingLoop(chatId: string, threadId?: number | null): void
+  logOutbound(
+    path: 'reply' | 'edit',
+    chatId: string,
+    messageId: number | null,
+    chars: number,
+    extra?: string,
+  ): void
+  closeObligationOnSubstantiveReply(
+    args: Record<string, unknown>,
+    liveTurn: CurrentTurn | null | undefined,
+    routedOriginTurn?: CurrentTurn | null,
+  ): void
+  finalizeStatusReaction(chatId: string, threadId: number | undefined, outcome: 'done'): void
+  releaseTurnBufferGate(key: string, endingTurn?: CurrentTurn): void
+  reapQueuedStatus(chatId: string, thread: number | undefined): void
+  noteAgentOutputAt(key: string, ts: number): void
+  rememberAgentButtonMeta(chatId: string | number, messageId: number, meta: Map<string, AgentButtonMeta>): void
+  resolveVoiceOutPlan(voiceOut: Access['voice_out'], replyText: string): VoiceOutPlan | null
+  synthesizeVoiceOut(plan: {
+    engine: 'kokoro' | 'openai'
+    voice?: string
+    speed?: number
+    apiKeyRef?: string
+    ttsText: string
+  }): Promise<Uint8Array | null>
+  publishToTelegraph(text: string, shortName: string, authorName?: string): Promise<string | null>
+  clearSilentEndState(key: string): void
+  emitRuntimeMetric(m: RuntimeMetricEvent): void
+  shadowEmit(ev: { kind: 'modelOutbound'; key: _ChatKey; at: number }): void
+  progressDriver: { recordOutboundDelivered(chatId: string, threadId?: string): void } | null
+}
+
+/**
+ * The reply send orchestration — `executeReply`'s body, verbatim.
+ * See the section comment above for the DI contract and the enumerated
+ * verbatim deviations.
+ */
+export async function sendReply(
+  deps: SendReplyGatewayDeps,
+  req: SendReplyRequest,
+): Promise<{ content: Array<{ type: string; text: string }> }> {
+  const {
+    outboundDedup, flushedTurnSupersede, firstTextReplyLogged, suppressPtyPreview,
+    activeDraftStreams, lastPtyPreviewByChat, voiceOnDemandCache, voicePreSynthQueue,
+    pendingProgress, signalTracker, silencePoke,
+    getCurrentTurn, getLastActiveTurnChatId, progressDriver,
+    HISTORY_ENABLED, TURN_ORIGIN_ROUTING_ENABLED, AUTOCLASSIFY_MIDTURN_SHADOW,
+    MAX_ATTACHMENT_BYTES, MAX_CHUNK_LIMIT, PHOTO_EXTS,
+    lockedBot, robustApiCall, swallowingApiCall,
+    loadAccess, redactOutboundText, assertAllowedChat, assertSendable,
+    statusKey, streamKey,
+    resolveReplyOwnerTurn, findTurnByOriginId, findTurnByQuotedMessageId,
+    resolveAnswerThreadWithLog, resolveThreadId,
+    getLatestInboundMessageId, recordOutbound,
+    emissionAuthorityFor, clearActivitySummary,
+    startTypingLoop, stopTypingLoop, logOutbound,
+    closeObligationOnSubstantiveReply, finalizeStatusReaction,
+    releaseTurnBufferGate, reapQueuedStatus, noteAgentOutputAt,
+    rememberAgentButtonMeta, resolveVoiceOutPlan, synthesizeVoiceOut,
+    publishToTelegraph, clearSilentEndState, emitRuntimeMetric, shadowEmit,
+  } = deps
+  const args = req.args
+  // #1664 — pin the turn this reply belongs to at entry. The
+  // finalAnswerDelivered write near the end of this function runs after
+  // several awaits; turn-pinning (the #1067 pattern used across the
+  // gateway) keeps the write attributed to THIS turn rather than reading
+  // module-scope currentTurn, which a future refactor could let roll over
+  // mid-call. (#2996 P2: the pin is taken by the gateway wrapper at call
+  // entry and passed in `req.turn` — same read, same position.)
+  const turn = req.turn
+  const _rawChatId = String(args.chat_id ?? '')
+  if (!_rawChatId) throw new Error('reply: chat_id is required')
+  // Non-Claude models (e.g. Gemini via LiteLLM sr-* routing) sometimes pass a
+  // chat_id that is not in the allowlist — either an int/string mismatch, or
+  // the model echoing the wrong identifier from context. When the raw value
+  // fails the allowlist check, fall back to the active (or last-known) turn's
+  // validated sessionChatId so the reply still lands correctly.
+  // Tier 1: live turn (currentTurn was non-null at reply entry).
+  // Tier 2: last-known turn (survives silence poke — Bug D fix; currentTurn is
+  //   null because clearTurnStarted fired ≥5 min of model silence, but the model
+  //   finally called reply after the poke).
+  const chat_id = (() => {
+    const resolved = resolveChatIdFallback(
+      _rawChatId,
+      loadAccess(),
+      turn?.sessionChatId,
+      getLastActiveTurnChatId(),
+      turn != null,
+    )
+    if (resolved.tier !== 'raw') {
+      process.stderr.write(
+        `telegram gateway: reply: model passed chat_id "${_rawChatId}" (not allowlisted) — ` +
+          `routing to ${resolved.tier} turn chat "${resolved.chatId}"\n`,
+      )
+    }
+    return resolved.chatId // raw tier → let assertAllowedChat throw the human-readable error
+  })()
+  const rawText = args.text as string | undefined
+  if (rawText == null || rawText === '') throw new Error('reply: text is required and cannot be empty')
+  // Repair LLM JSON-escape bungles, then promote lone prose paragraph breaks
+  // into GFM hard breaks so the rich path doesn't collapse them (lists/tables/
+  // code are left untouched — see normalizeParagraphBreaks).
+  // Outbound text pipeline (#2996 §3B): normalize → redact → punctuation/bold
+  // → voice-scrub, extracted verbatim into outbound-send-path.ts. The order is
+  // load-bearing (secret scrub BEFORE the punctuation/bold normalizers so a
+  // secret with an em-dash or `**` is matched literally; voice scrub last so
+  // retries see the scrubbed dedup key). The metric side effect (fired on a
+  // non-zero voice-scrub replacement) stays here — the pure module returns the
+  // replacement count and the gateway emits.
+  const _normalized = normalizeOutboundBody(rawText, 'reply', redactOutboundText)
+  let text = _normalized.text
+  if (_normalized.voiceReplaced > 0) {
+    emitRuntimeMetric({
+      kind: 'voice_scrub_applied',
+      chatKey: statusKey(chat_id, args.message_thread_id != null
+        ? Number(args.message_thread_id) : undefined),
+      replaced: _normalized.voiceReplaced,
+      site: 'reply',
+    })
+  }
+  process.stderr.write(`telegram channel: reply: invoked chatId=${chat_id} charCount=${text.length} preview=${JSON.stringify(text.slice(0, 80))}\n`)
+  // #2527: emit time_to_first_text_reply_ms on the FIRST text reply of each
+  // turn so operators can see how long users waited for any visible output.
+  // Only fires once per turn (firstTextReplyLogged guards the repeat).
+  if (turn != null) {
+    const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+    const replyKey = statusKey(chat_id, threadId)
+    if (!firstTextReplyLogged.has(replyKey)) {
+      firstTextReplyLogged.add(replyKey)
+      logStreamingEvent({
+        kind: 'turn_reply_timing',
+        chatId: chat_id,
+        threadId,
+        turnId: turn.turnId,
+        timeToFirstTextReplyMs: Date.now() - turn.gatewayReceiveAt,
+      })
+    }
+  }
+
+  // #546 dedup check: was this content just sent via turn-flush or
+  // a sibling reply path? Skip the actual send and return a
+  // plausible tool result so claude-code's retry loop closes
+  // cleanly. NOTE: only fires when content matches; legitimate
+  // late-replies with different content sail through.
+  {
+    const replyThreadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+    const dup = outboundDedup.check(chat_id, replyThreadId, text, Date.now(), getCurrentTurn()?.registryKey ?? null)
+    if (dup != null) {
+      process.stderr.write(
+        `telegram gateway: reply: deduped (#546) chatId=${chat_id} ` +
+        `ageMs=${dup.ageMs} preview=${JSON.stringify(dup.preview)}\n`,
+      )
+      return { content: [{ type: 'text', text: 'sent (deduped — same content sent via earlier path)' }] }
+    }
+  }
+
+  // 2026-07 duplicate-reply fix — turnId-keyed supersede (consumption side).
+  // If an earlier turn-flush (answer-ready quiescence OR the turn-end backstop)
+  // already posted THIS turn's terminal text and the model's REAL `reply` for
+  // the same turn is landing now (it was still composing the tool call when the
+  // flush fired, or claude-code replayed the tool_call after a bridge
+  // reconnect), delete the flushed message(s) so the canonical reply below
+  // delivers exactly one clean message instead of a second one. Keyed on the
+  // per-turn `turnId` nonce, so it fires even when the flushed narration+answer
+  // blob differs from the clean answer-only reply — the containment case the
+  // exact-text `outboundDedup` above structurally cannot catch. A reply for a
+  // DIFFERENT newer live turn never supersedes (decideSupersede → different-turn),
+  // so a fresh turn's answer is never clobbered.
+  //
+  // Reply-flicker fix: rather than delete the flushed message(s) HERE (which
+  // makes the user see delete+replace when the canonical reply sends fresh
+  // below), we DEFER the correction to the send site. Once chunk count / files /
+  // preview are known, `decideSupersedeCorrection` picks edit-in-place (edit the
+  // single flushed message into the canonical reply — no flicker, no re-ping)
+  // when the reply fits one plain-text message, and falls back to the legacy
+  // delete+resend otherwise. `supersedeFlushIds` carries the ids forward.
+  let supersedeFlushIds: number[] = []
+  {
+    const replyThreadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+    // 2026-07 double-reply-on-DM fix (Part 1) — resolve the turn this reply
+    // belongs to by IDENTITY, via the SAME full chain the thread-router uses
+    // (`resolveReplyOwnerTurn`): live `currentTurn`, then the model-echoed
+    // `origin_turn_id`, then the framework-owned quoted message id, then the
+    // chat's most-recently-ended turn. The prior chain stopped at
+    // `currentTurn ?? findTurnByOriginId`, so a DM late reply — `currentTurn`
+    // nulled by the flush's synthetic turn_end AND no `origin_turn_id` (a
+    // supergroup-only field) — resolved to a null owner. `decideSupersede`
+    // deliberately never lets a null live turn supersede a turnId-bearing flush
+    // record, so message A survived AND the reply shipped message B (the exact
+    // double-send). The quoted / latest-ended recoveries are precisely what the
+    // router already did for the same reply, so unifying here makes the two
+    // resolvers agree and the late-reply supersede fires by identity.
+    const ownerTurn = resolveReplyOwnerTurn(turn, chat_id, args)
+    const resolvedTurnId = ownerTurn?.turnId ?? null
+    const decision = flushedTurnSupersede.take(
+      chat_id,
+      replyThreadId,
+      { liveTurnId: resolvedTurnId, now: Date.now() },
+    )
+    if (decision.supersede) {
+      process.stderr.write(
+        `telegram gateway: reply: superseding flushed turn message(s) ` +
+        `chatId=${chat_id} ids=${JSON.stringify(decision.deleteMessageIds)}\n`,
+      )
+      // Deferred: the correction (edit-in-place vs delete+resend) is decided at
+      // the send site once chunk count / files / preview are known.
+      supersedeFlushIds = decision.deleteMessageIds
+      // Set the answer-delivered latch NOW, at record consumption — BEFORE the
+      // arg-validation throws between here and the correction site (file
+      // too-large ~L13699, inline_keyboard invalid ~L13782). Without this, a
+      // late reply that supersedes a flush AND carries an oversized file /
+      // invalid keyboard would throw before the correction runs (message A
+      // neither deleted nor edited), the model would retry `reply`, and — the
+      // supersede record already consumed by `take()` above — the retry would
+      // fall into the else/no-record branch below with no latch set, so
+      // suppression wouldn't fire and a fresh B would ship alongside the stale
+      // narration A (both visible). Latching here mirrors the else-branch's own
+      // `answerDelivered = true` and closes that resurrection window: the retry
+      // resolves the same ended owner turn, sees the latch, and is suppressed —
+      // exactly one message ever ships. The latch is idempotent and the normal
+      // (no-throw) path is unaffected: the correction below still ships B once.
+      if (ownerTurn != null) ownerTurn.answerDelivered = true
+    } else {
+      // 2026-07 double-reply-on-DM fix (Part 2) — answer-delivered race latch.
+      // Supersede found no record. Either there was no flush (normal reply), or
+      // the flush FIRED but has not yet recorded its message ids (the residual
+      // pre-record race Part 1's supersede cannot reach). The flush sets
+      // `answerDelivered = true` synchronously at fire time (before its async
+      // send AND before `record`), and it persists on the ended turn — so when
+      // this LATE, substantive reply resolves its owner turn and sees the latch
+      // already set, the flush's message A is already on its way out and this
+      // reply would ship a duplicate. Suppress it. Scoped to the substantive
+      // ≥`FLUSH_SUBSTANTIVE_MIN_CHARS` floor and the late-reply case so an
+      // interim sub-floor ack, a chunked multi-part answer, or a legitimate
+      // second in-turn substantive reply (live `currentTurn`) is never
+      // suppressed. `isSubstantiveFinalReply` reduces to the ≥200-char test on
+      // the `reply` path (no `done`); pass the model's original notification
+      // intent to mirror the #2533 decoupling call shape.
+      const replySubstantive = isSubstantiveFinalReply({
+        text: rawText,
+        disableNotification: args.disable_notification === true,
+      })
+      const suppressByLatch = decideAnswerLatchSuppression({
+        superseded: false,
+        replySubstantive,
+        isLateReply: turn == null,
+        ownerAnswerDelivered: ownerTurn?.answerDelivered ?? false,
+      })
+      if (suppressByLatch) {
+        process.stderr.write(
+          `telegram gateway: reply: suppressed by answer-delivered latch ` +
+          `(flush already delivered this turn's answer) chatId=${chat_id} ` +
+          `ownerTurnId=${JSON.stringify(resolvedTurnId)}\n`,
+        )
+        return { content: [{ type: 'text', text: 'sent (deduped — answer already delivered via turn-flush)' }] }
+      }
+      // A substantive answer is going out via this reply — set the latch on its
+      // owner turn so a later bridge-replayed / reworded duplicate of the same
+      // answer is caught by the branch above.
+      if (replySubstantive && ownerTurn != null) {
+        ownerTurn.answerDelivered = true
+      }
+    }
+  }
+
+  const files = (args.files as string[] | undefined) ?? []
+  const quoteOptIn = args.quote !== false
+  let reply_to = args.reply_to != null ? Number(args.reply_to) : undefined
+  const protectContent = args.protect_content === true
+  const quoteText = args.quote_text as string | undefined
+  const access = loadAccess()
+  // Outbound TTS plan (PR-C2). Resolved once here (engine gating + mode +
+  // plain-text TTS input); synthesis happens just before the send so a
+  // voice-only reply can suppress the text chunk loop on success. Voice is
+  // fully best-effort — every failure below falls back to the text reply.
+  const voiceOutPlan = resolveVoiceOutPlan(access.voice_out, text)
+  const configParseMode = access.parseMode ?? 'html'
+  const format = (args.format as string | undefined) ?? configParseMode
+  const disableLinkPreview = args.disable_web_page_preview != null
+    ? Boolean(args.disable_web_page_preview)
+    : (access.disableLinkPreview ?? true)
+  // #1122 conversational pacing: mid-turn updates pass disable_notification:true
+  // so only the final answer pings the device. Default false (pings) so
+  // existing call-sites and the typical "final answer" reply keep their
+  // current behaviour without an explicit flag.
+  let disableNotification = args.disable_notification === true
+  // #2527/#1664 — the over-ping safety net below may downgrade
+  // `disableNotification` ping→silent for ANTI-SPAM (one ping per turn). That
+  // delivery-channel decision must NOT pollute final-answer CLASSIFICATION: a
+  // final answer the model intended to ping is STILL the final answer even when
+  // the framework silences the actual ping. Classify on the model's original
+  // intent (what executeReply already does), so an over-ping-silenced
+  // final answer sets finalAnswerDelivered=true — fixing both a spurious
+  // silent-end re-prompt and a false 'undelivered' (😐) terminal reaction.
+  const modelDisableNotification = args.disable_notification === true
+
+  // #1675 over-ping safety net. The conversational-pacing contract
+  // (`reference/rfcs/conversational-pacing.md` beat 5) says EXACTLY ONE
+  // device ping per turn — the final answer. The model sometimes
+  // violates this by sending a substantive answer pinged + a wrap-up
+  // ("Delivered all three steps…", "Sent.", or meta-narration) ALSO
+  // pinged. Both messages then fire notifications. The fleet UAT on
+  // 2026-05-23 reproduced this (Step 3 + Delivered both pinged, two
+  // beeps for a turn that should have produced one). Framework owns
+  // the safety net: once the turn has emitted ONE pinged reply, every
+  // subsequent reply call in the same turn auto-downgrades to silent
+  // (disable_notification: true). Model intent ("I want this loud")
+  // is honoured for the first ping; subsequent pings are demoted with
+  // a stderr log so operators can see the safety net engage.
+  //
+  // The slot is claimed BEFORE the actual send to keep the logic
+  // sequential — a send that fails part-way leaves firstPingAt set
+  // and subsequent pings would be silenced. Acceptable trade-off (a
+  // failed first ping is an edge case; the alternative — claim after
+  // send — races concurrent reply calls).
+  // Tracks whether the over-ping safety net coerced this reply
+  // from ping→silent. Threaded into the silent-anchor predicate
+  // below: a demoted final-answer reply must NOT merge into the
+  // silent preamble bubble; it lands as a fresh silent bubble so
+  // the user can still find it (see #1674 / silent-anchor follow-up).
+  let wasOverPingSuppressed = false
+  {
+    const turn = getCurrentTurn()
+    if (turn != null) {
+      const now = Date.now()
+      // Notification ownership (R8 / PR-2): on the `reply` path,
+      // substantiveness is purely the ≥200-char (or `done`) backstop —
+      // `isSubstantiveFinalReply` is `done === true || text.length >= 200`
+      // and ignores the notification flag entirely. `reply` carries no
+      // `done`, so it reduces to the ≥200-char length test. We still pass
+      // `modelDisableNotification` (the MODEL's original intent, not the
+      // possibly-downgraded `disableNotification`) to mirror the #2533
+      // final-answer decoupling call shape, but that arg does NOT
+      // participate in classification here — it is inert on this path.
+      const replySubstantive = isSubstantiveFinalReply({
+        text: rawText,
+        disableNotification: modelDisableNotification,
+      })
+      // PR-4c: the over-ping DECISION relocates into the emission-authority
+      // façade, behind the kill-switch (default OFF), the same structural way
+      // PR-4b moved the OPEN gate. `decideOverPing` is already pure, so PR-4c
+      // extracts NOTHING new — it relocates the *call* into the façade's enabled
+      // branch and keeps the *effects* (stderr, metric, the atomic
+      // `firstPingAt`/`firstPingWasSubstantive` pair-set, the
+      // `disableNotification`/`wasOverPingSuppressed` outer-scope writes) HERE,
+      // parameterized by the decision the façade hands back via `applyDecision`.
+      //
+      //  - Disabled branch runs `disabledOverPing()` — its own LITERAL
+      //    `decideOverPing(...)` call + the full effects block, VERBATIM from
+      //    PR-4b-base (the disabled-path-is-byte-identical proof).
+      //  - Enabled branch: the façade computes the decision and hands it to
+      //    `applyOverPingDecision(decision)`, which performs the IDENTICAL
+      //    effects. Same pure inputs ⇒ same decision ⇒ flag-ON ≡ flag-OFF ≡ base.
+      //
+      // The effects block is shared between both thunks by closing over `decision`
+      // — but the disabled thunk computes it via its OWN literal `decideOverPing(`
+      // first, so the disabled path never depends on the façade for the decision.
+      const applyOverPingDecision = (decision: OverPingDecision): void => {
+        if (decision.suppress) {
+          process.stderr.write(
+            `telegram gateway: reply over-ping safety net — ` +
+            `downgrading disable_notification:false → true ` +
+            `(chat=${chat_id} thread=${args.message_thread_id ?? '-'} ` +
+            `firstPingAt=${turn.firstPingAt} sinceFirstPing_ms=${decision.sinceFirstPingMs})\n`,
+          )
+          // Observability: surface to the unified runtime-metrics
+          // fan-out so the cadence dashboard can track fleet-wide
+          // over-ping rate (leading indicator of model pacing drift).
+          emitRuntimeMetric({
+            kind: 'over_ping_suppressed',
+            key: statusKey(chat_id, args.message_thread_id != null
+              ? Number(args.message_thread_id) : undefined),
+            sinceFirstPingMs: decision.sinceFirstPingMs ?? 0,
+          })
+          disableNotification = true
+          wasOverPingSuppressed = true
+        } else if (decision.claimSlot) {
+          // Claim (first ping) OR upgrade (substantive answer pinging over an
+          // ack's slot). Set firstPingAt AND firstPingWasSubstantive ATOMICALLY
+          // (no await between) so a racing second reply reads a consistent pair.
+          turn.firstPingAt = now
+          turn.firstPingWasSubstantive = replySubstantive
+          if (decision.upgrade) {
+            process.stderr.write(
+              `telegram gateway: reply over-ping safety net — ` +
+              `UPGRADE: substantive answer pings over an ack's slot ` +
+              `(chat=${chat_id} thread=${args.message_thread_id ?? '-'})\n`,
+            )
+          }
+        }
+      }
+      emissionAuthorityFor(turn).claimOrDowngradePing(
+        { modelRequestedPing: !disableNotification, substantive: replySubstantive },
+        {
+          firstPingAt: turn.firstPingAt,
+          firstPingWasSubstantive: turn.firstPingWasSubstantive,
+          nowMs: now,
+        },
+        applyOverPingDecision,
+        () => {
+          // Disabled-path: literal `decideOverPing(` + effects, VERBATIM base.
+          const decision = decideOverPing({
+            modelRequestedPing: !disableNotification,
+            firstPingAt: turn.firstPingAt,
+            substantive: replySubstantive,
+            firstPingWasSubstantive: turn.firstPingWasSubstantive,
+            nowMs: now,
+          })
+          applyOverPingDecision(decision)
+        },
+      )
+    }
+  }
+
+  // Telegraph publish (#579). When the reply text is long enough AND
+  // the agent has telegraph enabled in access.json, publish to
+  // Telegraph + replace the local text with a single-message link.
+  // Telegram renders the link as a native Instant View card.
+  // Failure paths fall through to normal HTML chunking, so a flaky
+  // Telegraph backend never breaks the reply path.
+  const tg = access.telegraph
+  const tgThreshold = tg?.threshold ?? 3000
+  if (tg?.enabled && files.length === 0 && text.length > tgThreshold) {
+    const agentSlug = process.env.SWITCHROOM_AGENT_NAME ?? 'switchroom-agent'
+    const shortName = tg.short_name ?? agentSlug
+    const url = await publishToTelegraph(text, shortName, tg.author_name)
+    if (url != null) {
+      const title = deriveTelegraphTitle(text)
+      // Replace the local text with a one-line link. The first line
+      // is the chosen title (so the user sees the topic at a glance);
+      // the second line is the URL Telegram will Instant-View.
+      text = `**${escapeMarkdown(title)}**\n${url}`
+    }
+    // url null → fall through and chunk; the user still gets the
+    // long reply, just split across messages.
+  }
+
+  // Single rich-markdown path (#2669). The only fork is `format:'text'`,
+  // a literal/no-markdown send: the body bypasses the rich parser entirely
+  // (plain `sendMessage`, no rich wrapper). Everything else — the default —
+  // ships the raw GFM markdown via `sendRichMessage`. `effectiveText` is the
+  // raw text either way (no HTML/MarkdownV2 rendering happens here anymore).
+  const literalText = format === 'text'
+  // Paragraph-spacing fix (rich-message regression after #2669). The rich GFM
+  // renderer collapses a `\n\n` gap TIGHT, so multi-paragraph replies render
+  // jammed together — unlike the old HTML path. Inject a visible blank-line
+  // spacer into prose `\n\n` gaps on the rich path only. The literal
+  // (`format:'text'`) path must stay byte-exact, so it is left untouched.
+  const effectiveText: string = computeEffectiveText(text, literalText)
+
+  assertAllowedChat(chat_id)
+
+  // Thread resolution precedence (ANSWER path, component 3 — turn-origin
+  // routing): (1) explicit message_thread_id the model passed; else
+  // (2) the ORIGIN turn's thread — the turn that OWNS this reply, matched
+  // by origin_turn_id (the meta field the model echoes back). This is
+  // authoritative even after `currentTurn` has flipped to a successor (the
+  // Brevo→Meta late-reply bug). Else (3) the live turn's thread (legacy
+  // #1664 fallback when no origin turn is resolvable). Answer paths
+  // DELIBERATELY do NOT fall through to chatThreadMap last-seen — that
+  // heuristic is what mis-routed a late reply to whichever topic most
+  // recently received a message. DM: every tier is undefined → unchanged.
+  // Kill switch off → exact legacy resolveThreadId precedence.
+  // Hoist the resolved origin turn so the obligation-close path (below) can
+  // pass it into resolveCloseTarget as routedOriginId, closing re-presented
+  // obligations even when the model omitted origin_turn_id (Fix 1/2).
+  let replyRoutedOriginTurn: CurrentTurn | null = null
+  let threadId: number | undefined
+  if (TURN_ORIGIN_ROUTING_ENABLED) {
+    const explicit = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+    // Origin precedence: model echo first (authoritative), then the
+    // framework-owned quoted message_id (deterministic, no model thread
+    // assertion) as a fallback when the model omitted the echo.
+    const echoedTurn = findTurnByOriginId(args.origin_turn_id as string | undefined)
+    const quotedTurn = echoedTurn == null ? findTurnByQuotedMessageId(chat_id, args.reply_to) : null
+    const originTurn = echoedTurn ?? quotedTurn
+    replyRoutedOriginTurn = originTurn ?? null
+    threadId = resolveAnswerThreadWithLog(
+      chat_id,
+      Number.isFinite(explicit as number) ? (explicit as number) : undefined,
+      originTurn,
+      originTurn == null ? null : echoedTurn != null ? 'echo' : 'quoted',
+      turn,
+      'reply',
+    )
+  } else {
+    threadId = resolveThreadId(
+      chat_id,
+      (args.message_thread_id as string | undefined) ??
+        (turn?.sessionThreadId != null ? turn.sessionThreadId : undefined),
+    )
+  }
+
+  if (reply_to == null && quoteOptIn && HISTORY_ENABLED) {
+    try {
+      const latest = getLatestInboundMessageId(chat_id, threadId ?? null)
+      if (latest != null) reply_to = latest
+    } catch (err) {
+      process.stderr.write(`telegram gateway: quote-reply lookup failed: ${(err as Error).message}\n`)
+    }
+  }
+
+  for (const f of files) {
+    assertSendable(f)
+    const st = statSync(f)
+    if (st.size > MAX_ATTACHMENT_BYTES) {
+      throw new Error(`file too large: ${f} (${(st.size / 1024 / 1024).toFixed(1)}MB, max 50MB)`)
+    }
+  }
+
+  const limit = Math.max(1, Math.min(access.textChunkLimit ?? RICH_MESSAGE_MAX_CHARS, MAX_CHUNK_LIMIT))
+  const replyMode = access.replyToMode ?? 'first'
+  const chunks = computeReplyChunks({
+    effectiveText,
+    literalText,
+    limit,
+    chunkMode: access.chunkMode ?? 'length',
+  })
+  const sentIds: number[] = []
+
+  // Outbound TTS synthesis (PR-C2). Done BEFORE the text send so a
+  // voice-only reply can suppress the text chunks on success. ONE voice note
+  // per response for the kokoro path (ttsChunks is a single element — the
+  // whole normalized reply — synthesized in one /tts call). The OpenAI path
+  // may still produce several ordered notes (one per chunk) because of its
+  // input cap. Ken is often on a bike/driving and can't read the screen, so
+  // the full answer must be SPOKEN. Best-effort: a chunk that fails to
+  // synthesize is skipped; if NOTHING synthesizes the text path proceeds
+  // unchanged so the answer is never dropped.
+  // on-demand is a LOCAL-engine (kokoro) feature only: the tap handler
+  // synthesizes via the local sidecar, so a Listen button is only meaningful
+  // when the resolved engine is kokoro. resolveVoiceOutPlan already gated the
+  // local host verdict for kokoro, so engine==='kokoro' here implies the
+  // sidecar is available. For engine==='openai' + reply_mode='on-demand' we do
+  // NOT inject a button (its taps would dead-end on the local sidecar) — we
+  // fall through to the normal immediate-synth path so the openai reply behaves
+  // exactly like a normal openai voice reply.
+  const useOnDemandButton =
+    voiceOutPlan != null &&
+    voiceOutPlan.replyMode === 'on-demand' &&
+    voiceOutPlan.engine === 'kokoro'
+
+  const voiceOggs: Uint8Array[] = []
+  // Skip reply-time synthesis ONLY when we're actually deferring to a Listen
+  // button (kokoro on-demand). An openai on-demand config still synthesizes
+  // immediately below.
+  if (voiceOutPlan != null && !useOnDemandButton) {
+    for (const chunkText of voiceOutPlan.ttsChunks) {
+      const ogg = await synthesizeVoiceOut({
+        engine: voiceOutPlan.engine,
+        voice: voiceOutPlan.voice,
+        speed: voiceOutPlan.speed,
+        apiKeyRef: voiceOutPlan.apiKeyRef,
+        ttsText: chunkText,
+      })
+      // Skip a failed chunk but keep going — a partial spoken answer still
+      // beats silence; full-fail (no oggs at all) falls back to text below.
+      if (ogg != null) voiceOggs.push(ogg)
+    }
+    if (voiceOggs.length < voiceOutPlan.ttsChunks.length) {
+      process.stderr.write(
+        `telegram gateway: voice-out: synthesized ${voiceOggs.length}/${voiceOutPlan.ttsChunks.length} voice-note chunk(s)\n`,
+      )
+    }
+  }
+  // Suppress the text body ONLY when voice-only AND we synthesized the FULL
+  // set of chunks (every part of the answer is spoken). A partial or total
+  // synthesis failure leaves the text path running so the answer still
+  // lands in full — never drop the user's answer silently.
+  const suppressText =
+    voiceOutPlan?.replyMode === 'voice-only' &&
+    voiceOutPlan.ttsChunks.length > 0 &&
+    voiceOggs.length === voiceOutPlan.ttsChunks.length
+
+  // #271: validate inline_keyboard and namespace any callback_data with
+  // the `agent:` prefix so the gateway's callback_query dispatcher can
+  // round-trip taps back to this agent without colliding with
+  // infrastructure prefixes (auth:/op:/vd:/vg:/aq:/perm:). URL buttons
+  // pass through unchanged. Attached to the LAST chunk only so buttons
+  // appear on the final visible message.
+  let replyMarkup: { inline_keyboard: AnyButton[][] } | undefined
+  let replyButtonMeta: Map<string, AgentButtonMeta> | undefined
+  const rawKeyboard = args.inline_keyboard as AnyButton[][] | undefined
+  if (rawKeyboard != null) {
+    const validationErrors = validateInlineKeyboard(rawKeyboard)
+    if (validationErrors.length > 0) {
+      const summary = validationErrors
+        .map((e) => `${e.path}.${e.field}: ${e.reason}`)
+        .join('; ')
+      throw new Error(`inline_keyboard validation failed: ${summary}`)
+    }
+    // #3148 fast-follow: mask any secret an agent put in a visible button
+    // `text` label, its `ack_text` toast, or a `copy_text.text` clipboard
+    // payload BEFORE the keyboard is sent — the same outbound scrub the reply
+    // `text` body uses. `callback_data` (the routing key) is left exact.
+    // Feeding BOTH the meta extraction and the callback wrap from the redacted
+    // copy means the stashed toast, the tap echo (`button_text`), and the
+    // "✅ You chose: <label>" annotation (#789) all read already-masked bytes.
+    const redactedKeyboard = redactAgentKeyboard(rawKeyboard, (s) =>
+      redactOutboundText(s, 'reply_inline_keyboard'),
+    )
+    replyButtonMeta = extractAgentButtonMeta(redactedKeyboard)
+    replyMarkup = { inline_keyboard: wrapAgentCallbacks(redactedKeyboard) }
+  }
+
+  // on-demand voice: append a single '🔊 Listen' button that synthesizes the
+  // spoken reply only when tapped. The button carries a RAW `voice:<token>`
+  // callback_data (NOT wrapped with the agent: prefix) so the dispatcher
+  // handles it internally and never routes it to the agent as an inbound.
+  //
+  // Collision gate: inject ONLY when the reply carries no agent-authored
+  // buttons. If the agent supplied its own keyboard, the callback dispatcher's
+  // single_use strip (keyboardIsSingleUse) governs that whole message; adding
+  // a foreign single_use:false button would flip that message to a mixed
+  // keyboard and defeat the agent's double-fire protection. Keep it simple —
+  // agent buttons present → skip the Listen button for this message.
+  //
+  // useOnDemandButton already gates on engine==='kokoro': an openai on-demand
+  // config never reaches here (it synthesized immediately above), so a Listen
+  // button is never minted for an engine whose taps would dead-end on the
+  // local sidecar.
+  if (
+    useOnDemandButton &&
+    voiceOutPlan!.ttsChunks.length > 0 &&
+    voiceOutPlan!.ttsChunks[0]!.length > 0
+  ) {
+    if (!mayInjectListenButton(rawKeyboard)) {
+      process.stderr.write(
+        'telegram gateway: voice-out on-demand: agent supplied inline_keyboard — skipping Listen button (single_use collision gate)\n',
+      )
+    } else {
+      // Token is intentionally GLOBAL (not chat-keyed): under the single-tenant
+      // invariant the operator is the only authorized sender across all chats,
+      // and the tap handler re-checks access.allowFrom before synthesizing, so
+      // a token needs no per-chat scoping to be safe.
+      const token = mintVoiceOnDemandToken()
+      voiceOnDemandCache.put(token, {
+        // ttsChunks[0] is already normalizeForSpeech(reply) (kokoro path).
+        text: voiceOutPlan.ttsChunks[0]!,
+        ...(voiceOutPlan.voice != null ? { voice: voiceOutPlan.voice } : {}),
+        speed: voiceOutPlan.speed,
+      })
+      // The keyboard stays after the tap (never stripped) so it can be
+      // replayed. The gate above guarantees this is the ONLY button on the
+      // message, so keeping it is safe (no agent buttons to protect).
+      replyMarkup = buildListenKeyboard(token)
+      // #2763 eager pre-synthesis: kick a background synth of the same
+      // payload so the Listen tap attaches the pre-made file instantly.
+      // Local-engine only (useOnDemandButton already gates engine==='kokoro'
+      // — the cloud engine never eager-synthesizes). enqueue() is a
+      // synchronous array push; the drain is deferred + async and never
+      // awaited here, so the text sends below are never delayed and a synth
+      // failure can never affect message delivery (the tap just falls back
+      // to the lazy path).
+      if (eagerVoiceEnabled()) {
+        voicePreSynthQueue.enqueue({
+          token,
+          text: voiceOutPlan.ttsChunks[0]!,
+          ...(voiceOutPlan.voice != null ? { voice: voiceOutPlan.voice } : {}),
+          speed: voiceOutPlan.speed,
+        })
+      }
+    }
+  }
+
+  const replySKey = streamKey(chat_id, threadId)
+  suppressPtyPreview.add(replySKey)
+  let previewMessageId: number | null = null
+  const openStream = activeDraftStreams.get(replySKey)
+  if (openStream && !openStream.isFinal()) {
+    await openStream.finalize().catch(() => {})
+    previewMessageId = openStream.getMessageId()
+    activeDraftStreams.delete(replySKey)
+    lastPtyPreviewByChat.delete(replySKey)
+  }
+
+  // Pre-alloc placeholder consumption removed in #553 PR 5 — the
+  // gateway no longer pre-allocates a draft on inbound, so reply tools
+  // simply render fresh. The 👀 reaction (#568) and typing indicator
+  // (#585) provide the visual gap that the placeholder used to fill.
+
+  const deleteStalePreview = async (id: number): Promise<void> => {
+    // #1075: operates on a message in a (possibly-deleted) thread. The
+    // "delete not found" case is already swallowed by robustApiCall; on
+    // THREAD_NOT_FOUND, swallowingApiCall logs + returns undefined so the
+    // reply flow continues with a fresh send.
+    await swallowingApiCall(
+      () => lockedBot.api.deleteMessage(chat_id, id),
+      { chat_id, verb: 'reply.deleteStalePreview' },
+    )
+  }
+
+  logStreamingEvent({
+    kind: 'reply_called',
+    chatId: chat_id,
+    charCount: effectiveText.length,
+    replacedPreview: previewMessageId != null,
+    previewMessageId,
+  })
+  // #1122 KPI: a `reply` always produces a fresh user-visible outbound
+  // message — count it for the outbound-gap / TTFO KPI AND reset the
+  // silence-poke clock so the next poke is measured from this send.
+  signalTracker.noteOutbound(statusKey(chat_id, threadId), Date.now())
+  silencePoke.noteOutbound(statusKey(chat_id, threadId), Date.now())
+  // Mid-turn auto-classify recency clock: the agent just produced visible output
+  // in this chat/thread (cross-turn, unlike silencePoke's per-turn lastOutboundAt).
+  // Only maintained when the shadow flag is on → truly zero overhead by default.
+  if (AUTOCLASSIFY_MIDTURN_SHADOW) noteAgentOutputAt(statusKey(chat_id, threadId), Date.now())
+  // PR3b-cutover: feed lastOutboundAt to the delivery machine so its
+  // TTL `tick` suppresses the fallback for a long-but-active turn
+  // (model streaming past 5 min) — parity with silencePoke's own
+  // suppression, so the cutover gate doesn't clear a live turn.
+  shadowEmit({ kind: 'modelOutbound', key: statusKey(chat_id, threadId) as _ChatKey, at: Date.now() })
+  // #1741 — only clear silent-end state on a plausibly-final reply.
+  // An interim ack (disable_notification:true, short text, no done)
+  // must NOT clear the state file; otherwise a turn that ends with
+  // ack-only + answer-as-transcript leaves no state for the Stop
+  // hook to act on if `turn_end` never lands (the `turn_duration`
+  // system event is unreliable for trivial-prompt turns — see the
+  // executeReply finalize comments). Final-answer replies still
+  // clear; the main turn-end path also re-writes the state when
+  // finalAnswerDelivered=false, so this is a belt-and-braces gate
+  // for the turn_end-missing case (#1741).
+  if (isFinalAnswerReply({ text: rawText, disableNotification: modelDisableNotification })) {
+    clearSilentEndState(statusKey(chat_id, threadId))
+  }
+
+  // Lever 2 (design §9 lever 2): finalize the activity card BEFORE the reply
+  // chunks send, so the card keeps its (lower) message_id and the reply is
+  // structurally last on screen. ONLY for a *substantive* final — for an ack
+  // (non-substantive) do NOTHING: finalizing an ack early would
+  // close → reopen → emit MORE messages (the #2141 ack-then-work feed, R3).
+  // `clearActivitySummary` edits the existing card in place (no new send) and
+  // nulls `activityMessageId`; combined with the sticky latch set here it
+  // prevents any post-reply re-OPEN below the answer. Idempotent with the
+  // tool_use-event clear at the first-reply handoff (the existing backstop).
+  {
+    const finalizeTurn = getCurrentTurn()
+    if (
+      finalizeTurn != null
+      && isSubstantiveFinalReply({ text: rawText, disableNotification: modelDisableNotification })
+    ) {
+      // PR-4a: routed through the emission-authority façade (no-op delegates —
+      // the latch-set and the finalize run exactly as before).
+      const ea = emissionAuthorityFor(finalizeTurn)
+      ea.markSubstantiveFinalDelivered(() => {
+        finalizeTurn.finalAnswerEverDelivered = true
+        finalizeTurn.finalAnswerDeliveredAt = Date.now()
+      })
+      ea.finalizeCard(() => {
+        clearActivitySummary(finalizeTurn)
+      })
+    }
+  }
+
+  // Reply-flicker fix — apply the deferred flushed-turn correction now that
+  // chunk count / files / preview are all resolved. `edit-in-place` reuses the
+  // single-message edit lane below (`previewMessageId`): it edits the flushed
+  // message A into the canonical reply B with the SAME rich rendering a fresh
+  // reply uses, and `sendReplyChunks` falls back to delete+resend on any edit
+  // 400 (message too old / uneditable / gone) — so exactly one message with the
+  // canonical content always survives. We also forgo the quote (an edit can't
+  // carry a reply_parameters quote) by clearing `reply_to`, so the quote-delete
+  // guard just below does NOT delete our edit target. `delete-resend` keeps the
+  // legacy behaviour (delete the flushed message(s), then send fresh below).
+  if (supersedeFlushIds.length > 0) {
+    const correction = decideSupersedeCorrection({
+      flushMessageIds: supersedeFlushIds,
+      chunkCount: chunks.length,
+      hasFiles: files.length > 0,
+      suppressText,
+      hasOpenPreview: previewMessageId != null,
+    })
+    if (correction.mode === 'edit-in-place') {
+      previewMessageId = correction.editMessageId
+      reply_to = undefined
+      process.stderr.write(
+        `telegram gateway: reply: superseding flushed message via edit-in-place ` +
+        `chatId=${chat_id} id=${correction.editMessageId}\n`,
+      )
+    } else {
+      for (const id of correction.deleteMessageIds) {
+        await swallowingApiCall(
+          () => lockedBot.api.deleteMessage(chat_id, id),
+          { chat_id, verb: 'reply.supersedeFlushed' },
+        )
+      }
+    }
+  }
+
+  if (previewMessageId != null && reply_to != null && replyMode !== 'off') {
+    await deleteStalePreview(previewMessageId)
+    previewMessageId = null
+  }
+
+  startTypingLoop(chat_id, threadId ?? null)
+
+  // #1677 silent-reply auto-edit. Consecutive silent replies within
+  // a turn edit a single anchor message instead of stacking new
+  // bubbles. We branch BEFORE the chunk loop so the single-chunk
+  // common case takes an editMessageText path; everything else
+  // (multi-chunk, ping, files, buttons) falls through to fresh send
+  // and either captures a new anchor or doesn't, per the predicate.
+  let silentAnchorEditDone = false
+  {
+    const turn = getCurrentTurn()
+    // Skip the silent-anchor merge when a flushed-turn supersede is active: an
+    // edit-in-place correction has re-pointed `previewMessageId` at the flushed
+    // message (the chunk loop below edits it), and merging into a prior silent
+    // anchor instead would orphan the flushed message A (leaving BOTH A and the
+    // anchor visible — the exact duplicate this supersede exists to prevent).
+    if (turn != null && chunks.length === 1 && supersedeFlushIds.length === 0) {
+      const decision = decideSilentReplyAnchor({
+        effectivelySilent: disableNotification,
+        anchorMessageId: turn.silentAnchorMessageId,
+        anchorText: turn.silentAnchorText,
+        newReplyText: effectiveText,
+        hasFiles: files.length > 0,
+        hasButtons: replyMarkup != null,
+        wasOverPingSuppressed,
+      })
+      if (decision.kind === 'edit-anchor') {
+        const editParams: {
+          message_thread_id?: number
+          link_preview_options?: { is_disabled: boolean }
+        } = {
+          link_preview_options: { is_disabled: disableLinkPreview },
+        }
+        if (threadId != null) editParams.message_thread_id = threadId
+        try {
+          await robustApiCall(
+            () =>
+              lockedBot.api.editMessageText(
+                chat_id,
+                decision.messageId,
+                literalText ? decision.mergedText : richMessage(decision.mergedText),
+                editParams,
+              ),
+            {
+              chat_id,
+              verb: 'reply.silent-anchor-edit',
+              ...(threadId != null ? { threadId } : {}),
+            },
+          )
+          turn.silentAnchorText = decision.mergedText
+          sentIds.push(decision.messageId)
+          logOutbound(
+            'edit',
+            chat_id,
+            decision.messageId,
+            decision.mergedText.length,
+            'silent-anchor-merge',
+          )
+          process.stderr.write(
+            `telegram gateway: silent-reply auto-edit — ` +
+            `chat=${chat_id} anchor=${decision.messageId} ` +
+            `merged_len=${decision.mergedText.length}\n`,
+          )
+
+          // #1679 — side effects the chunk-loop completion path runs.
+          // The edit-anchor branch returns early below, so these must
+          // be wired here too. Skipping them silently causes:
+          //   - cross-turn ambient (`pending-work-progress.ts`) holds
+          //     a stale anchor text and OVERWRITES the model's
+          //     accumulated silent content with `still working (Nm)`
+          //     when async work is in flight (this is the load-bearing
+          //     fix);
+          //   - SQLite history (`get_recent_messages`) misses the
+          //     silent-anchor content;
+          //   - #1664 silent-end re-prompt fires even when the
+          //     accumulated silent content qualifies as substantive;
+          //   - retries within the dedup window may double-send.
+          // #1760 primary fix — clear any stale prior-turn ticker
+          // before re-anchoring on this silent-reply edit. See the
+          // matching comment at the executeReply finalize site below.
+          pendingProgress.clearPending(statusKey(chat_id, threadId), 'reply_finalize')
+          pendingProgress.noteOutbound(statusKey(chat_id, threadId), {
+            messageId: decision.messageId,
+            text: decision.mergedText,
+            literalText,
+          })
+          if (HISTORY_ENABLED) {
+            try {
+              recordOutbound({
+                chat_id,
+                thread_id: threadId ?? null,
+                message_ids: [decision.messageId],
+                texts: [decision.mergedText],
+                attachment_kinds: [null],
+              })
+            } catch (histErr) {
+              process.stderr.write(
+                `telegram gateway: history recordOutbound (silent-anchor-edit) failed: ${histErr instanceof Error ? histErr.message : String(histErr)}\n`,
+              )
+            }
+          }
+          if (
+            turn != null
+            && isFinalAnswerReply({
+              text: decision.mergedText,
+              disableNotification: modelDisableNotification,
+            })
+          ) {
+            turn.finalAnswerDelivered = true
+            // Feed-reopen refinement: a substantive merged silent-anchor
+            // answer must NOT re-open the feed on post-answer housekeeping.
+            turn.finalAnswerSubstantive = isSubstantiveFinalReply({
+              text: decision.mergedText,
+              disableNotification: modelDisableNotification,
+            })
+            // Sticky ordering latch (lever 1): a substantive final closes the
+            // card OPEN gate for the rest of the turn. NEVER cleared by reopen.
+            if (turn.finalAnswerSubstantive) turn.finalAnswerEverDelivered = true
+            if (turn.finalAnswerSubstantive && turn.finalAnswerDeliveredAt == null) turn.finalAnswerDeliveredAt = Date.now()
+            if (turn.finalAnswerSubstantive) closeObligationOnSubstantiveReply(args, turn, replyRoutedOriginTurn)
+          }
+          outboundDedup.record(
+            chat_id,
+            threadId,
+            decision.mergedText,
+            Date.now(),
+            turn?.registryKey ?? null,
+          )
+
+          silentAnchorEditDone = true
+        } catch (err) {
+          // Edit failed (e.g. message deleted, rate limit exhausted,
+          // parse error). Fall through to fresh-send below — the
+          // anchor will be overwritten by whatever lands.
+          process.stderr.write(
+            `telegram gateway: silent-reply auto-edit failed, ` +
+            `falling back to fresh send: ${err instanceof Error ? err.message : String(err)}\n`,
+          )
+        }
+      }
+    }
+  }
+
+  if (silentAnchorEditDone) {
+    // Skip the chunk loop entirely — the anchor edit IS the send.
+    // Match the normal exit path: stop typing, then return.
+    stopTypingLoop(chat_id, threadId ?? null)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `edited (id: ${sentIds[0]})`,
+        },
+      ],
+    }
+  }
+
+  // #2996 step 1 — the chunk-send loop (with its THREAD_NOT_FOUND / oversize
+  // re-split / parse-reject fallback ladder and partial-failure contract) is
+  // relocated verbatim to outbound-send-path.ts's `sendReplyChunks` so it is
+  // unit-testable against a fake bot API (gateway.ts is not importable —
+  // Bun.listen + boot logic run at import). The raw `bot.api.*` calls stay HERE
+  // as thin injected adapters (retry wrapping + allow-raw-bot-api markers
+  // preserved), so the module is bot-agnostic and the check-bot-api-wrapping
+  // allowlist is unchanged. The caller still builds the per-chunk option shape
+  // (byte-identical). `sentIds` is threaded by reference; `threadId` /
+  // `previewMessageId` come back for the file-send + history code below.
+  const chunkSendDeps: ReplyChunkSendDeps = {
+    sendRich: (opts, body, tid) =>
+      robustApiCall(
+        // allow-raw-bot-api: injected chunk-loop adapter — sendRichMessage routed through robustApiCall; THREAD_NOT_FOUND handled by sendReplyChunks' fallback ladder
+        () => lockedBot.api.sendRichMessage(chat_id, body as never, opts as never),
+        // #3084 PR 2: the final reply is CRITICAL — never shed; degraded mode
+        // fails fast (structured flood_wait) instead of blocking the MCP reply.
+        { threadId: tid, chat_id, priorityClass: 'critical' },
+      ),
+    sendLiteral: (opts, txt, tid) =>
+      robustApiCall(
+        // allow-raw-bot-api: injected chunk-loop adapter — literal format:'text' send routed through robustApiCall; THREAD_NOT_FOUND handled by sendReplyChunks
+        () => lockedBot.api.sendMessage(chat_id, txt, opts as never),
+        { threadId: tid, chat_id, priorityClass: 'critical' },
+      ),
+    sendLiteralRaw: (opts, txt) =>
+      // allow-raw-bot-api: literal last-resort fallback (plaintext parse-reject / length re-split); wrapping would re-enter the parse/length policy that just rejected the payload
+      lockedBot.api.sendMessage(chat_id, txt, opts as never),
+    sendRichRaw: (opts, body) =>
+      // allow-raw-bot-api: rich length-error re-split last resort; wrapping would re-enter the chunk-loop's own classification on an already-classified length failure
+      lockedBot.api.sendRichMessage(chat_id, body as never, opts as never),
+    editPreview: (mid, body, opts, tid) =>
+      robustApiCall(
+        // allow-raw-bot-api: preview edit-in-place routed through robustApiCall; thread fallback handled by sendReplyChunks
+        () => lockedBot.api.editMessageText(chat_id, mid, body as never, opts as never),
+        // Finalizing the reply into the preview message — still CRITICAL (this
+        // IS the answer). Pass messageId/editPayload so the gate's per-message
+        // floor + no-op skip engage on the edit (part3-design §4/§5, PR1 L1).
+        { threadId: tid, chat_id, priorityClass: 'critical', messageId: mid, editPayload: body },
+      ),
+    richMessage,
+    logOutbound,
+    deleteStalePreview,
+    stderr: (s: string) => { process.stderr.write(s) },
+  }
+  try {
+    const _sendResult = await sendReplyChunks(chunkSendDeps, {
+      chatId: chat_id,
+      chunks,
+      literalText,
+      suppressText,
+      threadId,
+      previewMessageId,
+      sentIds,
+      buildSendOpts: (i, isLastChunk, tid) => {
+        const shouldReplyTo =
+          reply_to != null && replyMode !== 'off' && (replyMode === 'all' || i === 0)
+        return {
+          ...(shouldReplyTo
+            ? {
+                reply_parameters: {
+                  message_id: reply_to,
+                  ...(quoteText != null ? { quote: { text: quoteText, position: 0 } } : {}),
+                },
+              }
+            : {}),
+          ...(tid != null ? { message_thread_id: tid } : {}),
+          ...(disableLinkPreview ? { link_preview_options: { is_disabled: true } } : {}),
+          ...(replyMarkup != null && isLastChunk ? { reply_markup: replyMarkup } : {}),
+          ...(protectContent ? { protect_content: true } : {}),
+          ...(disableNotification ? { disable_notification: true } : {}),
+        }
+      },
+      buildPreviewEditOpts: (isLastChunk) => {
+        const editOpts: Record<string, unknown> = {}
+        if (disableLinkPreview) editOpts.link_preview_options = { is_disabled: true }
+        if (replyMarkup != null && isLastChunk) editOpts.reply_markup = replyMarkup
+        return editOpts
+      },
+    })
+    threadId = _sendResult.threadId
+    previewMessageId = _sendResult.previewMessageId
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new Error(`reply failed after ${sentIds.length} of ${chunks.length} chunk(s) sent: ${msg}`)
+  } finally {
+    stopTypingLoop(chat_id, threadId ?? null)
+  }
+
+  // Outbound voice notes (PR-C2). Sent IN ORDER, AFTER the text body
+  // (voice+text) or INSTEAD of it (voice-only, where suppressText skipped
+  // the chunk loop). A long reply produces SEVERAL notes — each spoken in
+  // sequence so the whole answer is heard, never truncated. Best-effort and
+  // fully non-fatal: a sendVoice failure must NEVER break the text reply
+  // path. In voice-only mode a failure would leave the user with an
+  // incomplete spoken answer, so on the FIRST send failure we recover by
+  // sending the full text once and stop sending further notes.
+  for (let v = 0; v < voiceOggs.length; v++) {
+    const oggBytes = voiceOggs[v]!
+    const voiceOpts: Record<string, unknown> = {
+      // Quote the user's message only on the FIRST voice note (mirrors the
+      // text chunk loop's first-chunk reply behaviour).
+      ...(v === 0 && reply_to != null && replyMode !== 'off'
+        ? { reply_parameters: { message_id: reply_to } }
+        : {}),
+      ...(threadId != null ? { message_thread_id: threadId } : {}),
+      ...(disableNotification ? { disable_notification: true } : {}),
+    }
+    try {
+      const sentVoice = await retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
+        robustApiCall,
+        (tid) => {
+          const opts = { ...voiceOpts }
+          if (tid != null) opts.message_thread_id = tid
+          else delete opts.message_thread_id
+          // allow-raw-bot-api: adapter callback INSIDE retryWithThreadFallback→robustApiCall; the THREAD_NOT_FOUND fallback is handled by the wrapper.
+          return lockedBot.api.sendVoice(chat_id, new InputFile(Buffer.from(oggBytes)), opts as never)
+        },
+        { threadId, chat_id, verb: 'sendVoice' },
+      )
+      sentIds.push(sentVoice.message_id)
+      logOutbound(
+        'reply',
+        chat_id,
+        sentVoice.message_id,
+        voiceOutPlan?.ttsChunks[v]?.length ?? 0,
+        `voice-note=${v + 1}/${voiceOggs.length}`,
+      )
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(
+        `telegram gateway: voice-out: sendVoice ${v + 1}/${voiceOggs.length} failed (non-fatal): ${msg}\n`,
+      )
+      // voice-only fell over mid-stream with text suppressed → recover by
+      // sending the FULL text body once so the answer still lands, then
+      // stop sending further notes (the text now carries everything).
+      if (suppressText) {
+        try {
+          const opts: Record<string, unknown> = {
+            ...(reply_to != null && replyMode !== 'off'
+              ? { reply_parameters: { message_id: reply_to } }
+              : {}),
+            ...(threadId != null ? { message_thread_id: threadId } : {}),
+            ...(disableNotification ? { disable_notification: true } : {}),
+          }
+          // allow-raw-bot-api: voice-only recovery fallback — the rich path already ran/was skipped; send the source text plainly so the answer is never lost.
+          const sent = await lockedBot.api.sendMessage(chat_id, effectiveText, opts as never)
+          sentIds.push(sent.message_id)
+          logOutbound('reply', chat_id, sent.message_id, effectiveText.length, 'voice-only-text-recovery')
+        } catch (textErr) {
+          process.stderr.write(
+            `telegram gateway: voice-out: voice-only text recovery ALSO failed: ${textErr instanceof Error ? textErr.message : String(textErr)}\n`,
+          )
+        }
+        break
+      }
+    }
+  }
+
+  // #710: remember per-button agent meta (ack_text / single_use) keyed
+  // by the message that actually carries the keyboard — that's the last
+  // text chunk, since the keyboard is attached only on isLastChunk.
+  if (replyButtonMeta != null && replyButtonMeta.size > 0 && sentIds.length >= chunks.length) {
+    const keyboardMsgId = sentIds[chunks.length - 1]
+    if (typeof keyboardMsgId === 'number') {
+      rememberAgentButtonMeta(chat_id, keyboardMsgId, replyButtonMeta)
+    }
+  }
+
+  // #1445 cross-turn pending-async ambient. Capture the last text
+  // chunk as the anchor — if this turn ends with a pending async
+  // dispatch, the framework edits THIS message in place every 60s
+  // with a `— still working (Nm)` suffix until the user re-engages.
+  // Multi-chunk replies: anchor is the LAST chunk (edits append to
+  // the visually-trailing message; earlier chunks are left intact).
+  if (sentIds.length === chunks.length && chunks.length > 0) {
+    const anchorMsgId = sentIds[chunks.length - 1]
+    if (typeof anchorMsgId === 'number') {
+      // #1760 primary fix — clear any stale prior-turn ticker BEFORE
+      // re-anchoring. The canonical teardown wires (turn_end,
+      // subagent_handback, inbound) can be missed (e.g. SDK turn_end
+      // event dropped, as in the #1760 live evidence). Tearing down on
+      // every reply-finalize is idempotent and resilient: it's a no-op
+      // when nothing is active, and drops a stale ambient before the
+      // new turn captures its anchor.
+      pendingProgress.clearPending(statusKey(chat_id, threadId), 'reply_finalize')
+      pendingProgress.noteOutbound(statusKey(chat_id, threadId), {
+        messageId: anchorMsgId,
+        text: chunks[chunks.length - 1],
+        literalText,
+      })
+    }
+  }
+
+  // #1677 silent-reply auto-edit — anchor capture for the FIRST
+  // silent reply of a turn (or the silent reply that replaced the
+  // anchor on overflow). Only captures for the single-chunk,
+  // silent, no-files, no-buttons happy path; the edit-anchor path
+  // earlier in this function handles SUBSEQUENT silent replies by
+  // editing. The next silent reply this turn will see the captured
+  // anchor and edit it in place.
+  if (
+    chunks.length === 1
+    && disableNotification
+    && files.length === 0
+    && replyMarkup == null
+    && sentIds.length === 1
+  ) {
+    const turn = getCurrentTurn()
+    if (turn != null) {
+      turn.silentAnchorMessageId = sentIds[0]!
+      turn.silentAnchorText = effectiveText
+    }
+  }
+
+  // #3033 layer-2 (pre-send validation): probe each photo-extension file
+  // BEFORE it hits the wire and pre-route any that Telegram's photo path
+  // would reject (extreme aspect ratio, width+height over cap, >10MB) as
+  // documents. One bad photo fails a WHOLE sendMediaGroup album with an
+  // opaque 400 — catching it here keeps the good files deliverable and
+  // sends the offender as a document on the first attempt. Probe
+  // failures keep the photo route; the reactive #3022 fallback backstops.
+  const photoPrecheck = new Map<string, ReturnType<typeof classifyPhotoFile>>()
+  // #3038 polish: files that ultimately went out as documents despite a
+  // photo extension (precheck reroute or reactive fallback). Feeds two
+  // honesty surfaces: the reply tool result suffix (so the agent doesn't
+  // claim an inline image rendered) and attachment_kinds history (record
+  // what was actually sent).
+  const documentReroutes: Array<{ path: string; reason: string }> = []
+  const sentAsDocument = new Set<string>()
+  for (const f of files) {
+    if (!PHOTO_EXTS.has(extname(f).toLowerCase())) continue
+    const cls = classifyPhotoFile(f)
+    photoPrecheck.set(f, cls)
+    if (cls.route === 'document') {
+      documentReroutes.push({ path: f, reason: cls.reason })
+      sentAsDocument.add(f)
+      process.stderr.write(
+        `telegram gateway: photo-precheck rerouting ${f} as document (${cls.reason})\n`,
+      )
+    }
+  }
+  const sendableAsPhoto = (f: string) =>
+    PHOTO_EXTS.has(extname(f).toLowerCase()) && photoPrecheck.get(f)?.route !== 'document'
+
+  // #273: when files is 2-10 photos, batch them into a single
+  // sendMediaGroup album rather than N separate sendPhoto calls. The
+  // user's device fires one notification for the album instead of N
+  // (notification-budget protection per the issue's JTBD note). Falls
+  // back to the per-file path for any non-all-photo set.
+  //
+  // #3038 known tradeoff: ONE precheck-rerouted photo in the set drops
+  // the WHOLE album to per-file sends — the user gets N notifications
+  // instead of 1. Deliberate: sendMediaGroup can't mix photo and
+  // document media, and a partial album plus a stray document is more
+  // confusing than N files. Revisit only if mixed albums become common.
+  const allPhotos = files.length >= 2 && files.length <= 10
+    && files.every(sendableAsPhoto)
+  // #1075: thread-id-bearing file sends. Mirror the chunk-loop's
+  // THREAD_NOT_FOUND fallback (deleted topic → drop the thread and
+  // resend on the main chat) so an attachment-bearing reply doesn't
+  // crash when the user deletes the topic mid-flight.
+  const replyParams =
+    reply_to != null && replyMode !== 'off' ? { reply_parameters: { message_id: reply_to } } : {}
+  // Send one file as a document, routed through the same thread-fallback
+  // policy as the photo path. `InputFile` streams are single-use, so a
+  // document retry after a failed sendPhoto must build a FRESH InputFile
+  // from the path. Returns the sent message (with its echoed thread id).
+  const sendAsDocument = (f: string) =>
+    retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
+      robustApiCall,
+      (tid) => {
+        const baseOpts = {
+          ...replyParams,
+          ...(tid != null ? { message_thread_id: tid } : {}),
+        }
+        // allow-raw-bot-api: wrapped in retryWithThreadFallback (retry policy); topic-aware document fallback
+        return lockedBot.api.sendDocument(chat_id, new InputFile(f), baseOpts)
+      },
+      { threadId, chat_id, verb: 'sendDocument' },
+    )
+
+  if (allPhotos) {
+    const media = files.map((f) => ({
+      type: 'photo' as const,
+      media: new InputFile(f),
+    }))
+    let sent: Array<{ message_id: number; message_thread_id?: number }>
+    try {
+      sent = await retryWithThreadFallback(
+        robustApiCall,
+        (tid) => {
+          const baseOpts = {
+            ...replyParams,
+            ...(tid != null ? { message_thread_id: tid } : {}),
+          }
+          return lockedBot.api.sendMediaGroup(chat_id, media, baseOpts)
+        },
+        { threadId, chat_id, verb: 'sendMediaGroup' },
+      )
+    } catch (err) {
+      // Graceful fallback: one bad photo in the album (e.g. a tall phone
+      // screenshot → PHOTO_INVALID_DIMENSIONS) fails the WHOLE media group.
+      // Rather than surface an error, re-send each file individually as a
+      // document so the user still receives all of them. See #klanker
+      // 2026-07-10 incident + isPhotoDimensionRejectError.
+      if (!isPhotoDimensionRejectError(err)) throw err
+      process.stderr.write(
+        `telegram gateway: sendMediaGroup rejected the photo album ` +
+        `(${err instanceof Error ? err.message : String(err)}); ` +
+        `falling back to per-file sendDocument\n`,
+      )
+      sent = []
+      const albumReason = 'Telegram rejected the photo album; whole album re-sent as documents'
+      for (const f of files) {
+        sent.push(await sendAsDocument(f))
+        sentAsDocument.add(f)
+        documentReroutes.push({ path: f, reason: albumReason })
+      }
+    }
+    if (threadId != null) {
+      // If the fallback dropped the thread id, propagate that decision
+      // to subsequent calls in this reply (no further retries needed).
+      // We can't observe which branch resolved cleanly, so peek at the
+      // first sent message: Telegram echoes message_thread_id only when
+      // present in the request. Absent → fallback fired.
+      const first = sent[0] as { message_thread_id?: number } | undefined
+      if (first && first.message_thread_id == null) threadId = undefined
+    }
+    for (const m of sent) sentIds.push(m.message_id)
+  } else {
+    for (const f of files) {
+      const input = new InputFile(f)
+      // Photo-ext files that failed the pre-send probe route straight to
+      // sendDocument (see photoPrecheck above) instead of bouncing a 400.
+      const isPhoto = sendableAsPhoto(f)
+      let sent: { message_id: number; message_thread_id?: number }
+      try {
+        sent = await retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
+          robustApiCall,
+          (tid) => {
+            const baseOpts = {
+              ...replyParams,
+              ...(tid != null ? { message_thread_id: tid } : {}),
+            }
+            return isPhoto
+              ? lockedBot.api.sendPhoto(chat_id, input, baseOpts)
+              : lockedBot.api.sendDocument(chat_id, input, baseOpts)
+          },
+          { threadId, chat_id, verb: isPhoto ? 'sendPhoto' : 'sendDocument' },
+        )
+      } catch (err) {
+        // Graceful fallback: an image Telegram won't accept as a photo
+        // (dimensions out of range / too large — a tall phone screenshot
+        // is the canonical trigger, PHOTO_INVALID_DIMENSIONS) is re-sent
+        // as a document so the user still receives the file instead of
+        // getting nothing. Non-photo-dimension errors propagate as before.
+        if (!(isPhoto && isPhotoDimensionRejectError(err))) throw err
+        process.stderr.write(
+          `telegram gateway: sendPhoto rejected ${f} ` +
+          `(${err instanceof Error ? err.message : String(err)}); ` +
+          `falling back to sendDocument\n`,
+        )
+        sent = await sendAsDocument(f)
+        sentAsDocument.add(f)
+        documentReroutes.push({ path: f, reason: 'Telegram rejected it as a photo; re-sent as document' })
+      }
+      // Mirror the threadId-clear above so the *next* file in the
+      // loop skips the doomed thread without paying for another
+      // round trip + retry.
+      if (threadId != null && sent.message_thread_id == null) {
+        threadId = undefined
+      }
+      sentIds.push(sent.message_id)
+    }
+  }
+
+  // #3038: surface photo→document reroutes in the tool result — the
+  // agent otherwise only "sees" success and may tell the user an inline
+  // image rendered when it went out as a file attachment.
+  const result = (sentIds.length === 1
+    ? `sent (id: ${sentIds[0]})`
+    : `sent ${sentIds.length} parts (ids: ${sentIds.join(', ')})`)
+    + rerouteResultSuffix(documentReroutes)
+
+  if (HISTORY_ENABLED && sentIds.length > 0) {
+    try {
+      const fileCount = files.length
+      const textCount = sentIds.length - fileCount
+      const texts: string[] = []
+      const attachKinds: (string | null)[] = []
+      for (let i = 0; i < textCount; i++) { texts.push(chunks[i] ?? ''); attachKinds.push(null) }
+      for (let i = 0; i < fileCount; i++) {
+        const f = files[i] ?? ''
+        const ext = extname(f).toLowerCase()
+        // #3038: record what was ACTUALLY sent — a photo-extension file
+        // rerouted to sendDocument (precheck or reactive fallback) is a
+        // 'document' in history, not a 'photo' from its raw extension.
+        const kind = PHOTO_EXTS.has(ext) && !sentAsDocument.has(f) ? 'photo' : 'document'
+        texts.push(`(${kind}: ${f})`)
+        attachKinds.push(kind)
+      }
+      recordOutbound({ chat_id, thread_id: threadId ?? null, message_ids: sentIds, texts, attachment_kinds: attachKinds })
+    } catch (err) {
+      process.stderr.write(`telegram gateway: history recordOutbound (reply) failed: ${err}\n`)
+    }
+  }
+
+  // Issue #137: signal to the progress driver that an actual outbound
+  // landed, so a turn-end with replyToolCalled=true but zero deliveries
+  // can render the "⚠️ Reply attempted but not delivered" variant.
+  if (sentIds.length > 0) {
+    try {
+      progressDriver?.recordOutboundDelivered(
+        chat_id,
+        threadId != null ? String(threadId) : undefined,
+      )
+    } catch { /* best-effort signal */ }
+    // #203: fresh sendMessage from reply tool is a user-visible signal.
+    signalTracker.noteSignal(statusKey(chat_id, threadId), Date.now())
+    // #1713: the reply tool is a NON-EVENT for the status reaction
+    // WHEN IT'S AN INTERIM ACK. The reaction reflects current turn
+    // activity, not delivery state — interim acks must not collapse
+    // the working-state ladder to 👍.
+    //
+    // #1728 carve-out (2026-05-24): when this reply IS the final
+    // answer (`isFinalAnswerReply` returns true — same classifier
+    // #1664 uses for silent-end re-prompt gating), it IS effectively
+    // turn-end and we MUST finalize here. Rationale: Claude Code's
+    // `turn_duration` system event is unreliable for the trivial-
+    // prompt happy path (driver sends "what's 2+2", model replies
+    // "4", no `turn_duration` ever lands in the JSONL session tail).
+    // Pre-#1718 this wedge was masked by the legacy
+    // `endStatusReaction` shim running unconditionally on every
+    // reply (outcome='done'); #1718 removed that call site
+    // intending `turn_end` to be the sole terminal trigger. The
+    // contract was right in spirit but `turn_end` doesn't fire 100%
+    // of the time, so the buffer gate (activeTurnStartedAt) stays
+    // set forever and every subsequent inbound gets `held mid-turn`
+    // and never delivered. v0.13.27 shipped + reverted on this
+    // failure mode (#1728).
+    //
+    // Net contract:
+    //   - interim ack reply (isFinalAnswerReply === false)
+    //         → non-event, no reaction finalize, buffer gate stays
+    //   - final-answer reply (isFinalAnswerReply === true)
+    //         → finalize reaction (debounced 👍) + release buffer
+    //           gate via purgeReactionTracking (called inside
+    //           finalizeStatusReaction). currentTurn stays alive so
+    //           a subsequent `turn_end` still cleans up its share
+    //           idempotently.
+    //
+    // #1664 — `turn.finalAnswerDelivered = true` keeps the silent-
+    // end re-prompt from spuriously firing on a delivered final.
+    if (turn != null && isFinalAnswerReply({ text: rawText, disableNotification: modelDisableNotification })) {
+      turn.finalAnswerDelivered = true
+      // Feed-reopen refinement: track whether this final was substantive
+      // (≥200 chars or stream-done — not a short pinging ack) so post-answer
+      // housekeeping tool work does NOT re-open the feed / trip silent-end.
+      turn.finalAnswerSubstantive = isSubstantiveFinalReply({ text: rawText, disableNotification: modelDisableNotification })
+      // Sticky ordering latch (lever 1): set once a SUBSTANTIVE final lands;
+      // never cleared by reopen. The card OPEN gate keys on this, not the
+      // mutable finalAnswerDelivered above (which reopen toggles).
+      if (turn.finalAnswerSubstantive) turn.finalAnswerEverDelivered = true
+      if (turn.finalAnswerSubstantive && turn.finalAnswerDeliveredAt == null) turn.finalAnswerDeliveredAt = Date.now()
+      // #1728: release the buffer gate + emit terminal 👍. Mid-turn
+      // acks bypass this branch and remain non-events for the
+      // reaction (preserves #1713). The full turn-state teardown
+      // (nulling `currentTurn`, the per-turn cleanup) still runs in
+      // the `turn_end` handler when it lands; this only fires the
+      // observable side effects that #1718 deferred unconditionally.
+      finalizeStatusReaction(chat_id, threadId, 'done')
+      // PR2: close this origin's obligation on a SUBSTANTIVE final answer
+      // (after finalize so the reaction guard test's anchor window is stable).
+      if (turn.finalAnswerSubstantive) closeObligationOnSubstantiveReply(args, turn, replyRoutedOriginTurn)
+    }
+    // v0.13.30 follow-up — release the buffer gate on EVERY reply
+    // finalize, not just on `isFinalAnswerReply`. The narrow
+    // `finalizeStatusReaction` path above misses short replies that
+    // set `disable_notification: true` (the model mis-classifies a
+    // genuine answer as an interim ack — e.g. "4" for "what's
+    // 2+2"). Pre-fix the gate stayed set forever and every later
+    // inbound logged `held mid-turn ... will flush on turn-
+    // complete` — but turn-complete never came because Claude
+    // Code's `turn_duration` system event doesn't reliably land
+    // for trivial-prompt turns. v0.13.30 UAT showed the regression
+    // (msg 1873 reply at 13:02:46, msg 1874 held at 13:03:04, gate
+    // never released).
+    //
+    // The reaction controller stays alive (preserves #1713
+    // bidirectional ladder + the steer-vs-queue logic at
+    // gateway.ts:8322 which reads `activeStatusReactions`). Only
+    // the buffer gate flips.
+    //
+    // Component 1: pass the turn so the serialize gate sees this turn's
+    // `finalAnswerDelivered` (set just above for final-answer replies).
+    // An interim ack leaves it false → the cross-topic buffer does NOT
+    // drain yet; the real answer's reply releases it.
+    releaseTurnBufferGate(statusKey(chat_id, threadId), turn ?? undefined)
+    // Component 5: the final answer landed — reap the queued-status
+    // placeholder for THIS turn's topic. Key on the turn's own session
+    // thread (where the placeholder was posted / promoted), not the
+    // answer's possibly-overridden threadId.
+    if (turn?.finalAnswerDelivered === true) {
+      reapQueuedStatus(turn.sessionChatId, turn.sessionThreadId)
+    }
+  }
+
+  process.stderr.write(`telegram channel: reply: finalized chatId=${chat_id} messageIds=[${sentIds.join(',')}] chunks=${chunks.length}\n`)
+  // #546 dedup record: future reply / stream_reply / turn-flush
+  // calls with this same content within DEFAULT_DEDUP_TTL_MS will
+  // be suppressed.
+  if (sentIds.length > 0) {
+    outboundDedup.record(chat_id, threadId, text, Date.now(), getCurrentTurn()?.registryKey ?? null)
+  }
+  return { content: [{ type: 'text', text: result }] }
+}
+
+/** Gateway dependencies for {@link deliverCapturedProse}. */
+export interface DeliverCapturedProseDeps {
+  /** THE one live dedup instance — shared with {@link sendReply} and the
+   *  stream-render surface (Amendment 1/9). */
+  outboundDedup: OutboundDedupCache
+  bot: Bot<Context>
+  robustApiCall<T>(fn: () => Promise<T>, opts?: RetryCallOpts): Promise<T>
+  redactOutboundText(text: string, site: string): string
+  recordOutbound(rec: {
+    chat_id: string
+    thread_id: number | null
+    message_ids: number[]
+    texts: string[]
+  }): void
+  HISTORY_ENABLED: boolean
+  OBLIGATION_LEDGER_ENABLED: boolean
+  obligationLedger: { close(originTurnId: string): void }
+  clearSilentEndState(key: string): void
+  recordUndeliveredTurnEnd(
+    args: { chatId: string; threadId: number | null; turnKey: string },
+    deps?: SilentEndDeps,
+  ): { exhausted: boolean }
+  hasOutboundDeliveredSince(
+    chatId: string,
+    sinceMs: number,
+    threadId: number | null | undefined,
+    minCount?: number,
+  ): boolean
+}
+
+/**
+ * Silent-end recovery delivery (#3228) — `deliverCapturedProse`'s body,
+ * verbatim. A separate inline send path from the reply orchestration (it
+ * delivers the model's terminal prose recovered from the transcript scan when
+ * the turn ended silently); routed into this module so it shares the ONE
+ * injected `outboundDedup` instance and the golden harness (Amendment 2).
+ */
+export async function deliverCapturedProse(
+  deps: DeliverCapturedProseDeps,
+  args: {
+  chatId: string
+  threadId: number | undefined
+  statusKeyStr: string
+  registryKey: string | null
+  originTurnId: string
+  text: string
+  /** Turn elapsed for the honest "(waited Ns)" apology clause; optional. */
+  turnDurationMs?: number
+  },
+): Promise<void> {
+  const {
+    outboundDedup, bot, robustApiCall, redactOutboundText, recordOutbound,
+    HISTORY_ENABLED, OBLIGATION_LEDGER_ENABLED, obligationLedger,
+    clearSilentEndState, recordUndeliveredTurnEnd, hasOutboundDeliveredSince,
+  } = deps
+  const { chatId, threadId, statusKeyStr, registryKey, originTurnId, text, turnDurationMs } = args
+  const now = Date.now()
+  // #3228 Finding 1 — the three settlement points (sent / skipped-dedup /
+  // failed) all funnel through the pure `settleCapturedProseDelivery` core so
+  // the failure posture is deterministic and unit-tested. `outcome` is set on
+  // each branch and applied ONCE at the bottom.
+  let outcome: CapturedProseSendOutcome
+  const already = outboundDedup.check(chatId, threadId, text, now, registryKey)
+  if (already == null) {
+    let out = normalizeParagraphBreaks(repairEscapedWhitespace(text))
+    out = redactOutboundText(out, 'captured_prose')
+    const chunks = splitMarkdownChunks(out, RICH_MESSAGE_MAX_CHARS)
+    const sentIds: number[] = []
+    try {
+      let liveThreadId: number | undefined = threadId
+      for (const c of chunks) {
+        const sent = await retryWithThreadFallback(
+          robustApiCall,
+          (tid) => {
+            // Built as a variable (not an inline literal) so excess-property
+            // checks don't reject `link_preview_options` on sendRichMessage's
+            // narrow Other<> type — mirrors the turn-flush send site.
+            const opts = {
+              link_preview_options: { is_disabled: true },
+              ...(tid != null ? { message_thread_id: tid } : {}),
+            }
+            return bot.api.sendRichMessage(chatId, richMessage(c), opts)
+          },
+          { threadId: liveThreadId, chat_id: chatId, verb: 'captured-prose.sendMessage' },
+        )
+        if (liveThreadId != null && (sent as { message_thread_id?: number }).message_thread_id == null) {
+          liveThreadId = undefined
+        }
+        sentIds.push(sent.message_id)
+      }
+      if (HISTORY_ENABLED && sentIds.length > 0) {
+        try {
+          recordOutbound({
+            chat_id: chatId,
+            thread_id: threadId ?? null,
+            message_ids: sentIds,
+            texts: chunks,
+          })
+        } catch {}
+      }
+      // Record what we just sent so a late reply / stream_reply retry with the
+      // same content is deduped at its send site (the #546 dedup cache).
+      outboundDedup.record(chatId, threadId, text, now, registryKey)
+      process.stderr.write(
+        `telegram gateway: captured-prose delivery — sent ${out.length} chars recovered from ` +
+          `transcript scan (chat=${chatId} origin=${originTurnId})\n`,
+      )
+      outcome = 'sent'
+    } catch (err) {
+      // #3228 Finding 1 — the send threw, so the answer did NOT reach the user.
+      // The `failed` outcome routes to `settleCapturedProseDelivery`'s recovery
+      // path (recordUndelivered), NOT the close/clear path. This is load-bearing:
+      // the shared turn-end teardown (endCurrentTurnAtomic →
+      // decideObligationTurnEnd) already closes the obligation whenever
+      // `replyCalled === true` — exactly the interim-ack case that routes here —
+      // so "leaving the obligation open" is not a real net. Arming the Stop-hook
+      // re-prompt makes the failed send recoverable instead of silently lost.
+      process.stderr.write(
+        `telegram gateway: captured-prose delivery failed: ${(err as Error).message} — ` +
+          `arming the silent-end re-prompt net (recordUndeliveredTurnEnd) so the ` +
+          `answer is recoverable (chat=${chatId} origin=${originTurnId})\n`,
+      )
+      outcome = 'failed'
+    }
+  } else {
+    process.stderr.write(
+      `telegram gateway: captured-prose delivery skipped — this answer already went out ` +
+        `(dedup age=${already.ageMs}ms chat=${chatId} origin=${originTurnId}); settling bookkeeping\n`,
+    )
+    outcome = 'skipped-dedup'
+  }
+  // Apply the settlement bookkeeping through the pure core (#3228 Finding 1):
+  //   sent / skipped-dedup → close obligation + clear state (answer is with the
+  //                          user, so represent + exhausted fallback must not fire)
+  //   failed               → arm the Stop-hook re-prompt net (recordUndelivered),
+  //                          do NOT close/clear.
+  const settlement = settleCapturedProseDelivery(outcome, {
+    closeObligation: () => {
+      if (OBLIGATION_LEDGER_ENABLED) {
+        try { obligationLedger.close(originTurnId) } catch {}
+      }
+    },
+    clearState: () => clearSilentEndState(statusKeyStr),
+    recordUndelivered: () => {
+      try {
+        const silentEndDeps: SilentEndDeps | undefined = HISTORY_ENABLED
+          ? {
+              hasOutboundDeliveredSince: (cid, sinceMs, tid) =>
+                hasOutboundDeliveredSince(cid, sinceMs, tid, 1),
+            }
+          : undefined
+        return recordUndeliveredTurnEnd(
+          { chatId, threadId: threadId ?? null, turnKey: statusKeyStr },
+          silentEndDeps,
+        )
+      } catch (netErr) {
+        process.stderr.write(
+          `telegram gateway: captured-prose recovery-net arm failed: ${
+            (netErr as Error).message
+          } (chat=${chatId} origin=${originTurnId})\n`,
+        )
+        // Could not even record the undelivered turn — do NOT claim exhaustion
+        // (firing a fallback we can't justify). Fail safe: leave recovery to
+        // the obligation represent / next Stop hook.
+        return { exhausted: false }
+      }
+    },
+  })
+
+  // Exhaustion-boundary gap (#3228): the send FAILED on the attempt where the
+  // Stop-hook re-prompt budget was already spent, so recordUndeliveredTurnEnd
+  // cleared the state and the re-prompt can no longer recover the answer — and
+  // the obligation was already closed by the interim-ack teardown. Without this
+  // the user gets NEITHER the answer NOR the apology. Deliver a user-facing
+  // fallback, preferring the REAL answer as plain text (a non-rich send often
+  // survives the markdown/parse error the rich send threw on) before the
+  // generic apology.
+  if (outcome === 'failed' && settlement.exhausted) {
+    process.stderr.write(
+      `telegram gateway: WARN captured-prose exhausted-boundary fallback — rich send ` +
+        `failed with the re-prompt budget already spent; attempting a plain-text ` +
+        `delivery of the recovered answer before the generic apology ` +
+        `(chat=${chatId} origin=${originTurnId})\n`,
+    )
+    const plain = redactOutboundText(text, 'captured_prose')
+    const plainChunks = splitMarkdownChunks(plain, RICH_MESSAGE_MAX_CHARS)
+    try {
+      let liveThreadId: number | undefined = threadId
+      for (const c of plainChunks) {
+        // Plain sendMessage — NO parse_mode / rich rendering — so a markdown
+        // construct that made sendRichMessage 400 is sent verbatim instead.
+        const sent = await retryWithThreadFallback(
+          robustApiCall,
+          (tid) =>
+            bot.api.sendMessage(
+              chatId,
+              c,
+              tid != null ? { message_thread_id: tid } : {},
+            ),
+          { threadId: liveThreadId, chat_id: chatId, verb: 'captured-prose-plain-fallback.sendMessage' },
+        )
+        if (liveThreadId != null && (sent as { message_thread_id?: number }).message_thread_id == null) {
+          liveThreadId = undefined
+        }
+      }
+      // The real answer reached the user via plain text — record it so a late
+      // reply-tool retry with the same content is deduped at its send site.
+      outboundDedup.record(chatId, threadId, text, Date.now(), registryKey)
+      process.stderr.write(
+        `telegram gateway: captured-prose recovered via plain-text fallback ` +
+          `(chat=${chatId} origin=${originTurnId})\n`,
+      )
+    } catch (plainErr) {
+      // Plain text ALSO failed — post the generic apology so the turn is never
+      // silent (mirrors the non-captured exhausted path, gateway turn_end #1161).
+      process.stderr.write(
+        `telegram gateway: captured-prose plain-text fallback ALSO failed: ${
+          (plainErr as Error).message
+        } — posting the generic silent-end apology (chat=${chatId} origin=${originTurnId})\n`,
+      )
+      void retryWithThreadFallback(
+        robustApiCall,
+        (tid) =>
+          bot.api.sendMessage(
+            chatId,
+            silentEndFallbackText(turnDurationMs),
+            tid != null ? { message_thread_id: tid } : {},
+          ),
+        { threadId, chat_id: chatId, verb: 'captured-prose-apology-fallback.sendMessage' },
+      ).catch((err) => {
+        process.stderr.write(
+          `telegram gateway: captured-prose apology fallback send failed: ${
+            err instanceof Error ? err.message : String(err)
+          }\n`,
+        )
+      })
+    }
+  }
+}