switchroom 0.19.13 → 0.19.15

package/telegram-plugin/dist/server.js

@@ -24683,7 +24683,7 @@ var init_bridge = __esm(async () => {
       "",
       'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file \u2014 it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings \u2014 image_path_2, image_path_3, \u2026 (Read each) and attachment_file_id_2, attachment_file_id_3, \u2026 (download_attachment each). Process every one, not just the first. Reply with the reply tool \u2014 pass chat_id back. The reply tool quote-replies to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
       "",
-      `If the tag has reply_to_message_id (and reply_to_text, a truncated preview), the sender used Telegram's native Reply on a prior message \u2014 treat that message as the antecedent for "this"/"that" references instead of asking what they meant. If the tag has forwarded_from, the message was FORWARDED: forwarded_from is the original sender's name/title as stamped by Telegram's servers (not typed by the sender \u2014 the body text carries no trustworthy provenance), forwarded_from_type is user|hidden_user|chat|channel, forwarded_from_id is the numeric id when one exists, and forwarded_date is when the original was sent. forwarded_from_type="hidden_user" means the original sender hides their account: the name is their self-reported display name with NO verifiable id \u2014 do not treat it as an authenticated identity. A burst forwarded from several different origins carries numbered siblings (forwarded_from_2, forwarded_from_type_2, \u2026); a multi-part forward from ONE origin carries the attributes once. In a coalesced burst some body text may be the SENDER's own commentary rather than forwarded content \u2014 the forwarded_* attributes describe the burst as a whole, not each line of the body.`,
+      `If the tag has reply_to_message_id (and reply_to_text, a truncated preview), the sender used Telegram's native Reply on a prior message \u2014 treat that message as the antecedent for "this"/"that" references instead of asking what they meant. If the tag has forwarded_from, the message was FORWARDED: forwarded_from is the original sender's name/title as stamped by Telegram's servers (not typed by the sender \u2014 the body text carries no trustworthy provenance), forwarded_from_type is user|hidden_user|chat|channel, forwarded_from_id is the numeric id when one exists, forwarded_date is when the original was sent, and forwarded_message_id (channel origins only) is the post's id inside the origin channel \u2014 deep-linkable as t.me/<channel>/<id> for public channels. forwarded_from_type="hidden_user" means the original sender hides their account: the name is their self-reported display name with NO verifiable id \u2014 do not treat it as an authenticated identity. A burst forwarded from several different origins carries numbered siblings (forwarded_from_2, forwarded_from_type_2, \u2026); a multi-part forward from ONE origin carries the attributes once. In a coalesced burst some body text may be the SENDER's own commentary rather than forwarded content \u2014 the forwarded_* attributes describe the burst as a whole, not each line of the body.`,
       "",
       `reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, edit_message for interim progress updates, and delete_message when you need to truly remove a message (prefer edit_message if you just want to change text \u2014 delete is for retraction). Edits don't trigger push notifications \u2014 when a long task completes, send a new reply so the user's device pings. Use send_typing to show a typing indicator during long operations. Use pin_message to pin important outputs. Use forward_message to quote/resurface earlier messages.`,
       "",

package/telegram-plugin/gateway/forward-origin.ts

@@ -204,7 +204,8 @@ export function dedupeForwardOrigins(
 /**
  * Build the `forwarded_*` channel-meta fields. Fixed per-origin attribute
  * order (documented here, tested in forward-origin.test.ts):
- *   forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date
+ *   forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date,
+ *   forwarded_message_id (channel origins only)
  * The primary field is the human-readable NAME; the numeric id is
  * supplementary and follows it. The first origin gets the bare keys;
  * subsequent distinct origins get `_2`, `_3`, … suffixes — the same
@@ -232,6 +233,10 @@ export function buildForwardOriginMeta(
         resolveEnvTimezone(),
       )
     }
+    // Channel origins only: the message id inside the origin channel, so the
+    // agent can deep-link the source post (t.me/<channel>/<id>). Server-
+    // stamped numeric — no escaping surface.
+    if (o.messageId != null) out[`forwarded_message_id${suffix}`] = String(o.messageId)
   })
   return out
 }

package/telegram-plugin/gateway/gateway.ts

@@ -116,6 +116,7 @@ import {
   handlePaidMediaMessage,
   type MediaEnvelopeDeps,
 } from './media-message-handlers.js'
+import { handleRichMessageMessage } from './rich-message-handler.js'
 import {
   routeInbound,
   admitInbound,
@@ -22495,6 +22496,9 @@ bot.on('message:checklist_tasks_added' as Parameters<typeof bot.on>[0], (ctx) =>
   handleChecklistUpdate(ctx as unknown as Context, 'checklist_tasks_added', checklistHandlerDeps)
 })
 bot.on('message:pinned_message', ctx => handlePinnedMessage(ctx, pinnedMessageHandlerDeps))
+// Bot API 10.1 rich messages (forwarded bot messages carry these with NO
+// text/caption — see rich-message-handler.ts; MUST precede the catch-all).
+bot.on('message:rich_message', ctx => handleRichMessageMessage(ctx, mediaEnvelopeDeps))
 installUnhandledMessageCatchAll(
   bot,
   (ctx, text) => routeInbound(ctx, text, undefined, undefined, inboundRouterDeps),

package/telegram-plugin/gateway/narrative-lane.ts

@@ -49,6 +49,7 @@
 import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
 import { richMessage } from '../rich-send.js'
+import { appendShownBlock } from '../shown-ledger.js'
 import {
   appendActivityLabel, clipNarrative, formatStepSuffix, renderActivityFeedWithNested,
 } from '../tool-activity-summary.js'
@@ -186,6 +187,16 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
       {
         show: (text) => showNarrativeStep(turn, text),
         retractShown: (text) => retractNarrativeLine(turn, text),
+        // #3513 (correction 4): persist the ephemeral-shown mark keyed by the
+        // per-turn nonce so the out-of-process backstops (E3/E4) refuse to
+        // re-deliver this card-only narration. Envelope-bearing turns only —
+        // `turnId` is null for handback/background/cron, where the structural
+        // rule in the shared classifier is the sole guard (should-fix noted in
+        // shown-ledger.ts). Skip when null.
+        markDurableNarration: (text) => {
+          if (turn.turnId == null) return
+          appendShownBlock(turn.turnId, text)
+        },
       },
       {
         arm: (fn, ms) => {

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

@@ -1805,7 +1805,7 @@ export async function sendReply(
           // text differs. Gated so an interim-ack edit never journals the turn
           // nonce (which would suppress a later genuine answer for the turn).
           if (isFinalAnswerReply({ text: decision.mergedText, disableNotification: modelDisableNotification })) {
-            journalExternalDelivery({ turnNonce: turn?.turnId ?? null, text: decision.mergedText, tgMessageId: decision.messageId })
+            journalExternalDelivery({ turnNonce: turn?.turnId ?? null, text: decision.mergedText, tgMessageId: decision.messageId, replyAlreadyDeliveredThisTurn: true })
           }
 
           silentAnchorEditDone = true
@@ -2372,7 +2372,7 @@ export async function sendReply(
     // won't double-post it) while an interim ack never journals (so a later
     // genuinely-undelivered final answer is delivered by the sweep).
     if (shouldJournalReplySiteDelivery({ text: rawText, disableNotification: modelDisableNotification })) {
-      journalExternalDelivery({ turnNonce: t?.turnId ?? null, text, tgMessageId: sentIds[sentIds.length - 1] })
+      journalExternalDelivery({ turnNonce: t?.turnId ?? null, text, tgMessageId: sentIds[sentIds.length - 1], replyAlreadyDeliveredThisTurn: true })
     }
   }
   return { content: [{ type: 'text', text: result }] }
@@ -2483,7 +2483,13 @@ export async function deliverCapturedProse(
       outboundDedup.record(chatId, threadId, text, now, registryKey)
       // F1: captured-prose delivery journals + clears under the shared nonce
       // (`originTurnId` === turn.turnId === deriveTurnId, the hook's nonce).
-      journalExternalDelivery({ turnNonce: originTurnId, text, tgMessageId: sentIds[sentIds.length - 1] })
+      // #3510/#3511: the bridge only runs when NO genuine final answer was
+      // delivered this turn (`decideTurnEndGate` → 'reprompt' requires
+      // `finalAnswerDelivered === false`), so stamp `false` explicitly. A
+      // journal line from this site following a reply-tool line under the same
+      // nonce (replyAlreadyDeliveredThisTurn:true) is direct, journal-only
+      // proof of a bridge double-send.
+      journalExternalDelivery({ turnNonce: originTurnId, text, tgMessageId: sentIds[sentIds.length - 1], replyAlreadyDeliveredThisTurn: false })
       process.stderr.write(
         `telegram gateway: captured-prose delivery — sent ${out.length} chars recovered from ` +
           `transcript scan (chat=${chatId} origin=${originTurnId})\n`,

package/telegram-plugin/gateway/outbox-sweep.ts

@@ -42,6 +42,7 @@ import {
   sha256Hex,
   type OutboxRecord,
 } from '../outbox.js'
+import { isShownBlock } from '../shown-ledger.js'
 import { resolveSubagentOriginTurnKey } from '../registry/subagents-schema.js'
 import { createRetryApiCall, retryWithThreadFallback } from '../retry-api-call.js'
 
@@ -115,11 +116,32 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
       routable: resolved != null,
       routePrefix,
       quietMs: deps.quietMs ?? OUTBOX_QUIET_MS,
+      // #3513: suppress a record whose text was already surfaced on the ephemeral
+      // progress card for this turn (durable shown-ledger). The invariant forbids
+      // a second, out-of-process delivery of an ephemeral-shown block.
+      shownLedgerHit: isShownBlock(record.turnNonce, record.text, deps.stateDir),
     })
 
     if (decision.action !== 'send' && decision.action !== 'send-delayed') {
       summary.skipped++
-      if (decision.action === 'skip-journaled') {
+      if (decision.action === 'skip-ephemeral-shown') {
+        // Ephemeral-shown (#3513): the block already lives on the progress card.
+        // Journal the nonce and drop the record so the sweep never re-scans it
+        // and a racing machine also skips — same terminal bookkeeping as a dedup
+        // hit, but the reason is "assigned to the ephemeral surface".
+        appendDelivered(
+          {
+            turnNonce: record.turnNonce,
+            textSha256: record.textSha256,
+            ts: now,
+            deliverySource: 'sweep',
+            replyAlreadyDeliveredThisTurn: record.replyAlreadyDeliveredThisTurn === true,
+          },
+          deps.stateDir,
+        )
+        clearOutboxRecord(record.turnNonce, deps.stateDir)
+        log(`outbox-sweep: suppressed ephemeral-shown nonce=${record.turnNonce}\n`)
+      } else if (decision.action === 'skip-journaled') {
         // Already delivered under this nonce by another machine → drop the
         // pending record. clearOutboxRecord unlinks the `.json` (the pending
         // file) AND any `.sending` — the pre-fix `removeClaimed` only unlinked
@@ -133,7 +155,13 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
         // exactly-once, independent of cache lifetime and surviving a restart
         // (the record is gone from disk, the nonce is durably journaled).
         appendDelivered(
-          { turnNonce: record.turnNonce, textSha256: record.textSha256, ts: now },
+          {
+            turnNonce: record.turnNonce,
+            textSha256: record.textSha256,
+            ts: now,
+            deliverySource: 'sweep',
+            replyAlreadyDeliveredThisTurn: record.replyAlreadyDeliveredThisTurn === true,
+          },
           deps.stateDir,
         )
         clearOutboxRecord(record.turnNonce, deps.stateDir)
@@ -156,7 +184,18 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
         decision.text ?? record.text,
       )
       appendDelivered(
-        { turnNonce: record.turnNonce, textSha256: record.textSha256, tgMessageId: messageId, ts: now },
+        {
+          turnNonce: record.turnNonce,
+          textSha256: record.textSha256,
+          tgMessageId: messageId,
+          ts: now,
+          // #3510 instrumentation: a sweep delivery journals its machine and the
+          // record's capture-time reply-already-delivered flag, so a duplicate
+          // (deliverySource:'sweep' after a reply-tool delivery of the same
+          // turn) is provable from the journal alone.
+          deliverySource: 'sweep',
+          replyAlreadyDeliveredThisTurn: record.replyAlreadyDeliveredThisTurn === true,
+        },
         deps.stateDir,
       )
       removeClaimed(record.turnNonce, deps.stateDir)
@@ -266,14 +305,43 @@ export function startOutboxSweep(deps: {
  * Best-effort; never throws. A null/empty nonce is ignored (nothing to journal).
  */
 export function journalExternalDelivery(
-  args: { turnNonce: string | null; text: string; tgMessageId?: number },
+  args: {
+    turnNonce: string | null
+    text: string
+    tgMessageId?: number
+    /**
+     * #3510 instrumentation: whether a qualifying reply had already delivered
+     * this turn at the time of this delivery. Reply-send sites pass `true`
+     * (they ARE that delivery); the captured-prose bridge omits it (its turn
+     * shape is decided upstream). Journaled so a later sweep entry under the
+     * same nonce is provably a double-send from the journal alone.
+     */
+    replyAlreadyDeliveredThisTurn?: boolean
+    /**
+     * #3513 follow-up: which backstop/machine delivered. Defaults to
+     * `'reply-tool'` (the E0/E3 reply-path callers). The turn-flush backstop
+     * (E1/E2) passes `'flush'` so `backstopAlreadyDelivered` recognises it as a
+     * prior backstop and E3/E4 skip a duplicate durably (across a crash between
+     * the flush send and its journal write), not just via the in-memory dedup.
+     */
+    deliverySource?: 'sweep' | 'reply-tool' | 'flush'
+  },
   stateDir?: string,
   now: number = Date.now(),
 ): void {
   const nonce = args.turnNonce
   if (nonce == null || nonce === '') return
   appendDelivered(
-    { turnNonce: nonce, textSha256: sha256Hex(args.text), tgMessageId: args.tgMessageId, ts: now },
+    {
+      turnNonce: nonce,
+      textSha256: sha256Hex(args.text),
+      tgMessageId: args.tgMessageId,
+      ts: now,
+      deliverySource: args.deliverySource ?? 'reply-tool',
+      ...(args.replyAlreadyDeliveredThisTurn == null
+        ? {}
+        : { replyAlreadyDeliveredThisTurn: args.replyAlreadyDeliveredThisTurn }),
+    },
     stateDir,
   )
   clearOutboxRecord(nonce, stateDir)

package/telegram-plugin/gateway/rich-message-handler.ts

@@ -0,0 +1,235 @@
+/**
+ * Rich-message inbound handler (forwarded-body drop fix).
+ *
+ * THE BUG THIS CLOSES (evidence: carrie history.db row message_id=944,
+ * 2026-07-24 06:03; gateway-supervisor.log update_id=417526125
+ * `content_keys=[forward_from,forward_date,rich_message]`): a message whose
+ * content is a Bot API 10.1 `rich_message` — typically a FORWARDED bot
+ * message, since the gateway itself sends everything via `sendRichMessage` —
+ * carries NO top-level `text` or `caption`. It therefore matched none of the
+ * registered `message:text` / `:photo` / `:caption` handlers, fell through to
+ * the terminal catch-all (`unhandled-message.ts`), and the agent received the
+ * placeholder `(unhandled message content: forward_from)` instead of the real
+ * body. The forwarded content was silently dropped.
+ *
+ * grammy ^1.44 DOES ship a `message:rich_message` filter (see
+ * `@grammyjs/types` `RichMessage` / `RichBlock` / `RichText`) — the gateway
+ * simply never registered it. This module renders the inbound block tree to
+ * plain markdown-ish text deterministically and routes it through the SAME
+ * inbound pipeline as `message:text` (access gating + forward-origin parsing
+ * happen downstream, unchanged — origin metadata stays on the trusted
+ * `<channel>`-attr lane per #3162; nothing here injects provenance into the
+ * body).
+ *
+ * Registration stays in gateway.ts (order pinned by
+ * gateway-handler-registration-wiring.test.ts): `message:rich_message` is
+ * registered BEFORE the terminal catch-all, so the catch-all no longer sees
+ * these messages at all. `planUnhandledMessage` also imports
+ * `extractRichMessageText` as belt-and-braces for any future shape that
+ * carries a `rich_message` alongside unknown content.
+ */
+
+import type { Context, Filter } from 'grammy'
+import type { MediaEnvelopeDeps } from './media-message-handlers.js'
+
+/**
+ * Delivered body when a rich message renders to nothing extractable (e.g. a
+ * pure media/divider composition). Distinct from the catch-all's
+ * `(unhandled message content: …)` placeholder — this one names the actual
+ * situation and still yields a turn (fail-toward-delivery).
+ */
+export const RICH_MESSAGE_EMPTY_TEXT = '(rich message with no extractable text)'
+
+/** Recursion guard: the Bot API caps rich messages at 16 nesting levels; a
+ * hostile/malformed payload deeper than this is truncated, not stack-overflowed. */
+const MAX_DEPTH = 32
+
+interface RichTextNode {
+  type?: string
+  text?: unknown
+  expression?: string
+  alternative_text?: string
+  name?: string
+}
+
+/**
+ * Flatten a `RichText` union (string | RichText[] | typed node) to plain
+ * text. Inline formatting (bold/italic/…) is dropped — the agent needs the
+ * CONTENT; re-marking inline spans risks re-introducing accidental-formatting
+ * classes the render guards exist to kill. Leaf specials keep their readable
+ * payload: custom emoji → alternative text, math → LaTeX source, anchors →
+ * nothing.
+ */
+export function renderRichText(rt: unknown, depth = 0): string {
+  if (depth > MAX_DEPTH || rt == null) return ''
+  if (typeof rt === 'string') return rt
+  if (Array.isArray(rt)) return rt.map(t => renderRichText(t, depth + 1)).join('')
+  if (typeof rt !== 'object') return ''
+  const node = rt as RichTextNode
+  if (node.type === 'custom_emoji') return node.alternative_text ?? ''
+  if (node.type === 'mathematical_expression') {
+    return typeof node.expression === 'string' ? node.expression : ''
+  }
+  if (node.type === 'anchor') return ''
+  // Every other RichText node (bold, italic, url, mention, code, …) wraps a
+  // `text: RichText` payload — recurse into it.
+  if ('text' in node) return renderRichText(node.text, depth + 1)
+  return ''
+}
+
+interface RichBlockNode {
+  type?: string
+  text?: unknown
+  credit?: unknown
+  language?: string
+  expression?: string
+  summary?: unknown
+  blocks?: unknown
+  items?: Array<{ label?: string; blocks?: unknown; has_checkbox?: boolean; is_checked?: boolean }>
+  cells?: Array<Array<{ text?: unknown }>>
+  caption?: { text?: unknown; credit?: unknown } | unknown
+}
+
+function renderCaption(caption: unknown, depth: number): string {
+  if (caption == null || typeof caption !== 'object') return renderRichText(caption, depth)
+  const c = caption as { text?: unknown; credit?: unknown }
+  const text = renderRichText(c.text, depth)
+  const credit = renderRichText(c.credit, depth)
+  return [text, credit ? `— ${credit}` : ''].filter(Boolean).join(' ')
+}
+
+function renderBlocks(blocks: unknown, depth: number): string {
+  if (depth > MAX_DEPTH || !Array.isArray(blocks)) return ''
+  return blocks
+    .map(b => renderRichBlock(b, depth + 1))
+    .filter(s => s.length > 0)
+    .join('\n')
+}
+
+/** Render one `RichBlock` to a plain-text line/paragraph. Unknown block types
+ * degrade to their `text` / nested `blocks` when present (fail-toward-content:
+ * a future block type should surface its words, not vanish). */
+export function renderRichBlock(block: unknown, depth = 0): string {
+  if (depth > MAX_DEPTH || block == null || typeof block !== 'object') return ''
+  const b = block as RichBlockNode
+  switch (b.type) {
+    case 'paragraph':
+    case 'heading':
+    case 'footer':
+      return renderRichText(b.text, depth)
+    case 'pre': {
+      const body = renderRichText(b.text, depth)
+      return body.length > 0 ? `\`\`\`${b.language ?? ''}\n${body}\n\`\`\`` : ''
+    }
+    case 'divider':
+      return '---'
+    case 'mathematical_expression':
+      return typeof b.expression === 'string' ? b.expression : ''
+    case 'anchor':
+      return ''
+    case 'list': {
+      if (!Array.isArray(b.items)) return ''
+      return b.items
+        .map(item => {
+          const body = renderBlocks(item?.blocks, depth)
+          const check = item?.has_checkbox ? (item.is_checked ? '[x] ' : '[ ] ') : ''
+          const label = typeof item?.label === 'string' && item.label.length > 0 ? item.label : '-'
+          return body.length > 0 ? `${label} ${check}${body}` : ''
+        })
+        .filter(s => s.length > 0)
+        .join('\n')
+    }
+    case 'blockquote': {
+      const body = renderBlocks(b.blocks, depth)
+      const credit = renderRichText(b.credit, depth)
+      const quoted = body
+        .split('\n')
+        .map(line => `> ${line}`)
+        .join('\n')
+      return [quoted, credit ? `> — ${credit}` : ''].filter(s => s.length > 0).join('\n')
+    }
+    case 'pullquote': {
+      const body = renderRichText(b.text, depth)
+      const credit = renderRichText(b.credit, depth)
+      return [body, credit ? `— ${credit}` : ''].filter(Boolean).join(' ')
+    }
+    case 'details': {
+      const summary = renderRichText(b.summary, depth)
+      const body = renderBlocks(b.blocks, depth)
+      return [summary, body].filter(s => s.length > 0).join('\n')
+    }
+    case 'collage':
+    case 'slideshow': {
+      const body = renderBlocks(b.blocks, depth)
+      const caption = renderCaption(b.caption, depth)
+      return [body, caption].filter(s => s.length > 0).join('\n')
+    }
+    case 'table': {
+      if (!Array.isArray(b.cells)) return ''
+      const rows = b.cells
+        .map(row =>
+          Array.isArray(row)
+            ? row.map(cell => renderRichText(cell?.text, depth)).join(' | ')
+            : '',
+        )
+        .filter(s => s.length > 0)
+        .join('\n')
+      const caption = renderRichText((b as { caption?: unknown }).caption, depth)
+      return [caption, rows].filter(s => s.length > 0).join('\n')
+    }
+    case 'map':
+    case 'animation':
+    case 'audio':
+    case 'photo':
+    case 'video':
+    case 'voice_note': {
+      // Media blocks: the binary itself is not downloaded here (a forwarded
+      // rich message's media has no coalescing/attachment plumbing yet — see
+      // PR description follow-up); the caption text IS the readable content.
+      const caption = renderCaption(b.caption, depth)
+      const tag = `[${b.type}]`
+      return caption.length > 0 ? `${tag} ${caption}` : tag
+    }
+    case 'thinking':
+      return ''
+    default: {
+      // Unknown/future block type — surface any text-ish payload it carries.
+      const text = renderRichText(b.text, depth)
+      if (text.length > 0) return text
+      return renderBlocks(b.blocks, depth)
+    }
+  }
+}
+
+/**
+ * Extract the readable text of an inbound `message.rich_message`, or
+ * `undefined` when nothing extractable exists. Accepts `unknown` — the value
+ * arrives from the Telegram wire and must never throw the handler.
+ */
+export function extractRichMessageText(rich: unknown): string | undefined {
+  if (rich == null || typeof rich !== 'object') return undefined
+  const blocks = (rich as { blocks?: unknown }).blocks
+  const rendered = renderBlocks(blocks, 0)
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+  return rendered.length > 0 ? rendered : undefined
+}
+
+/**
+ * `message:rich_message` handler — same dispatch surface as the cluster-A
+ * media-envelope handlers: renders the body and hands it to the normal
+ * coalescing inbound pipeline (access gating + forward-origin parsing
+ * downstream, identical to `message:text`).
+ */
+export async function handleRichMessageMessage(
+  ctx: Filter<Context, 'message:rich_message'>,
+  deps: MediaEnvelopeDeps,
+): Promise<void> {
+  try {
+    const text = extractRichMessageText(ctx.message.rich_message) ?? RICH_MESSAGE_EMPTY_TEXT
+    deps.log(`telegram gateway: inbound rich_message from chat=${ctx.chat?.id ?? '?'} chars=${text.length}\n`)
+    await deps.handleInbound(ctx, text, undefined)
+  } catch (err) {
+    deps.log(`telegram gateway: rich_message handler error: ${(err as Error).message}\n`)
+  }
+}

package/telegram-plugin/gateway/stream-render.ts

@@ -59,11 +59,15 @@ import { normalizeOutboundBody } from './outbound-send-path.js'
 import { resolveEnvTimezone } from '../shared/local-time.js'
 import { hasOutboundDeliveredSince, recordOutbound } from '../history.js'
 import { isReplyTool } from '../narrative-dedup.js'
+import { isEphemeralTool } from '../hooks/narration-classify.mjs'
+import { backstopAlreadyDelivered } from '../outbox.js'
+import { journalExternalDelivery } from './outbox-sweep.js'
 import { NarrativeFlushController } from '../narrative-flush.js'
 import { recordTurnEnd, recordTurnStart } from '../registry/turns-schema.js'
 import { retryWithThreadFallback } from '../retry-api-call.js'
 import { richMessage } from '../rich-send.js'
 import { emitRuntimeMetric } from '../runtime-metrics.js'
+import { isShownBlock } from '../shown-ledger.js'
 import { CAPTURED_PROSE_MIN_CHARS, clearSilentEndState, decideCapturedProseDelivery, recordUndeliveredTurnEnd, silentEndFallbackText, writeSilentEndState } from '../silent-end.js'
 import { logStreamingEvent } from '../streaming-metrics.js'
 import { appendActivityLabel } from '../tool-activity-summary.js'
@@ -583,11 +587,21 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
     case 'tool_use': {
       const turn = getCurrentTurn()
       if (turn == null) return
-      // PR A — the model resumed work (surface or otherwise). Cancel any pending
-      // answer-ready quiescence flush: the turn is no longer quiescent. (Fire-time
-      // re-verification would also catch this, but disarming here avoids a wasted
-      // wakeup and matches the design's disarm-on-tool requirement.)
-      clearAnswerReadyFlushTimeout(turn)
+      // #3513 follow-up (MF1 + MF4b) — a TURN-CONTINUING tool_use (any tool NOT
+      // in the ephemeral surface set) is the deterministic signal that every text
+      // block captured so far in this turn was intra-turn narration, not the
+      // terminal answer. Retro-mark ALL existing captured blocks
+      // (`capturedBlockMeta.fill(true)`) so the cross-message shape
+      // ([text-only message] → [tool_use in the NEXT message]) is actually seen
+      // by `selectBackstopDelivery` — the per-message `!ev.lastInMessage` push at
+      // the `text` case under-detects it. The SAME ephemeral gate protects the
+      // E2 answer-ready fast path: a trailing ephemeral tool (answer, then
+      // react / pin / typing / edit / delete) must neither mark the answer
+      // interim NOR disarm the quiescence flush.
+      if (!isEphemeralTool(ev.toolName)) {
+        turn.capturedBlockMeta.fill(true)
+        clearAnswerReadyFlushTimeout(turn)
+      }
       // Narrative-dedup gate step 2 (JSONL-text-narrative primitive): a
       // narrative block was pending; this tool_use is the lookahead event
       // that decides it. reply/stream_reply with near-identical text ⇒
@@ -678,8 +692,13 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // PR A — a tool_label (real-time, ~250 ms) means the model is producing
       // work right now: cancel any pending answer-ready quiescence flush (the
       // turn is not quiescent). Fires ahead of the JSONL tool_use, so it disarms
-      // the timer at the earliest deterministic point.
-      clearAnswerReadyFlushTimeout(turn)
+      // the timer at the earliest deterministic point. MF4b: an EPHEMERAL surface
+      // tool (react / pin / typing / edit / delete fired after a terminal answer)
+      // must NOT disarm the quiescence flush — gate on the same ephemeral check as
+      // the tool_use reducer so answer-then-react keeps the E2 fast path.
+      if (!isEphemeralTool(ev.toolName)) {
+        clearAnswerReadyFlushTimeout(turn)
+      }
       // SECONDARY FIX: an active tool_label means the model is producing work
       // right now — re-arm the orphaned-reply fuse so a multi-phase tool turn
       // (write → compile → test → fix) that regularly emits labels doesn't let
@@ -826,6 +845,20 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
         // negation is the draft-then-send narration signal the turn-flush strip
         // uses (`selectFlushDeliveryText`) to keep a real answer intact instead
         // of truncating a paragraph that merely opens with "Let me explain…".
+        //
+        // NOTE (naming/approximation, #3515 review nit): downstream this value is
+        // consumed as `followedByToolUse`, but `!ev.lastInMessage` is a CONSERVATIVE
+        // APPROXIMATION of that predicate, not an exact match. It is true when the
+        // block is not the last block in its assistant message OR when a tool_use
+        // follows it in the same turn — i.e. it can over-flag: a block that is
+        // genuinely last-in-message may still be marked true. Over-approximation is
+        // SAFE here by construction: a `true` flag only ever makes a block a
+        // candidate for structural-narration suppression (selectFlushDeliveryText /
+        // isStructuralNarration), so the worst case is suppressing MORE narration —
+        // it can never promote an answer into the drop path. A real terminal answer
+        // is protected independently (it is never followed by a tool and survives
+        // the strip). Do not "tighten" this to the exact predicate expecting a
+        // behavioural change: the runtime value is deliberately conservative.
         turn.capturedBlockMeta.push(!ev.lastInMessage)
         // Narrative-dedup gate step 1 (JSONL-text-narrative primitive):
         // stage this text block for one lookahead step. If a previous block
@@ -1739,6 +1772,24 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
             } catch {}
           }
 
+          // #3513 follow-up (MF2) — DURABLE exactly-once-among-backstops read.
+          // The in-memory `backstopDeliveryLedger` (guard 5, below) only sees
+          // fires within THIS process; it cannot see a prior backstop delivery
+          // that landed in an earlier process (e.g. the Stop-hook captured-prose
+          // bridge E3, or the outbox sweep E4, delivered this turn's answer, then
+          // the gateway restarted and re-ran turn-flush). `backstopAlreadyDelivered`
+          // scans the durable delivered-keys journal counting ONLY prior BACKSTOP
+          // deliveries (sweep / flush / non-E0 reply-tool) for this nonce — it does
+          // NOT count an explicit E0 reply (#3510 recap), so a legitimate later
+          // explicit reply is never blocked by this guard. If a backstop already
+          // delivered, this fire is a durable no-op.
+          if (backstopAlreadyDelivered(turn.turnId, STATE_DIR)) {
+            process.stderr.write(
+              `telegram gateway: turn-flush skipped — turn ${turn.turnId} already delivered by a prior backstop (durable journal)\n`,
+            )
+            return
+          }
+
           // #3276 guard 5 — double-fire guard. If this turn already claimed the
           // delivery latch (a prior backstop fire — e.g. answer-ready quiescence
           // followed by the turn-end backstop for the same turn), do NOT deliver
@@ -1869,6 +1920,33 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
                 chunkCount,
                 cardMessageId: backstopCardMessageId,
               })
+              // #3513 follow-up (MF2) — DURABLE exactly-once-among-backstops
+              // WRITE. Journal this backstop delivery to the delivered-keys
+              // journal with `deliverySource:'flush'` so a later backstop in a
+              // DIFFERENT process (the Stop-hook bridge E3 or the outbox sweep E4,
+              // which read `backstopAlreadyDelivered`) recognises this turn's
+              // answer as already delivered and skips a duplicate durably — not
+              // only via the in-memory ledger, which does not survive a crash
+              // between this send and the next process's backstop. Journal ONLY on
+              // a receipt-gated `delivered` success. Best-effort: a journal-write
+              // failure must never demote the successful delivery.
+              if (delivered) {
+                try {
+                  journalExternalDelivery(
+                    {
+                      turnNonce: turn.turnId,
+                      text: capturedText,
+                      tgMessageId: sentIds.length > 0 ? sentIds[0] : undefined,
+                      deliverySource: 'flush',
+                    },
+                    STATE_DIR,
+                  )
+                } catch (err) {
+                  process.stderr.write(
+                    `telegram gateway: turn-flush delivered but journal write failed (non-fatal): ${(err as Error).message}\n`,
+                  )
+                }
+              }
               if (OBLIGATION_LEDGER_ENABLED) {
                 if (delivered) {
                   obligationLedger.close(turn.turnId)
@@ -2012,14 +2090,28 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
           const proseMinChars =
             !turn.replyCalled && gatewayCapturedEmpty ? 1 : CAPTURED_PROSE_MIN_CHARS
           const proseDecision = CAPTURED_PROSE_DELIVERY_ENABLED
-            ? decideCapturedProseDelivery({
-                turnKey: tKey,
-                // Per-turn nonce (#3228 Finding 3) — the persisted record must
-                // belong to THIS turn, not a stale carryover from a prior turn
-                // on the same chat/thread (tKey is not per-turn unique).
-                turnId: turn.turnId,
-                minChars: proseMinChars,
-              })
+            ? decideCapturedProseDelivery(
+                {
+                  turnKey: tKey,
+                  // Per-turn nonce (#3228 Finding 3) — the persisted record must
+                  // belong to THIS turn, not a stale carryover from a prior turn
+                  // on the same chat/thread (tKey is not per-turn unique).
+                  turnId: turn.turnId,
+                  minChars: proseMinChars,
+                },
+                {
+                  // #3513 (correction 1): refuse to bridge a block already
+                  // surfaced on the ephemeral card for this turn (shown-ledger).
+                  isBlockShown: (nonce, text) => isShownBlock(nonce ?? null, text),
+                  // #3513 follow-up (MF2): refuse to bridge a turn a prior
+                  // backstop (turn-flush E1/E2 flush, or the outbox sweep E4)
+                  // already delivered — durable exactly-once-among-backstops,
+                  // scoped to backstop deliveries only (never an explicit E0
+                  // reply, so a genuine later reply is unaffected).
+                  backstopDeliveredNonceHit: (nonce) =>
+                    backstopAlreadyDelivered(nonce ?? '', STATE_DIR),
+                },
+              )
             : { deliver: false as const, reason: 'no-state' as const }
           if (proseDecision.deliver && proseDecision.text != null) {
             // Deliver the recovered answer directly. This runs async and owns