switchroom 0.19.14 → 0.19.16

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

@@ -0,0 +1,241 @@
+/**
+ * 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 — renders the body and hands it to the
+ * normal COALESCING inbound pipeline, identical to `message:text`. It shares
+ * the cluster-A `MediaEnvelopeDeps` SHAPE, but gateway.ts binds this handler's
+ * `deps.handleInbound` to `handleInboundCoalesced` via an inline spread at the
+ * registration site — `{ ...mediaEnvelopeDeps, handleInbound: handleInboundCoalesced }`
+ * — NOT the bare `handleInbound` the media-envelope handlers use: a rich
+ * message is pure forwarded body text with no attachment, so a forwarded bot
+ * message arriving in the same sliding window as another inbound folds into one
+ * turn (same coalescing contract as `message:text`). Access gating +
+ * forward-origin parsing happen downstream, unchanged.
+ */
+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/silence-poke-session-event.ts

@@ -0,0 +1,89 @@
+// #1122 silence-poke session-event wiring.
+//
+// Extracted from gateway.ts (the file is under a hard line ratchet — see
+// switchroom#2996). Maps a parsed session event onto the silence-poke activity
+// registry so the 300s framework-fallback message wording is honest (thinking
+// vs working, plus the longest-running in-flight tool), threads the #1445
+// cross-turn pending-async ambient, and feeds the #3519 background-shell
+// liveness signal. Called once per session event from the gateway's event loop
+// while a turn is live (the caller owns the `currentTurn != null` guard and the
+// `key` derivation).
+import type { SessionEvent } from '../session-tail.js'
+import { isTelegramSurfaceTool } from '../tool-names.js'
+import { toolLabel } from '../tool-labels.js'
+import { applyBackgroundShellLiveness } from './background-shell-liveness.js'
+
+/** The silence-poke module namespace (kept as `typeof` so no surface drift). */
+type SilencePoke = typeof import('../silence-poke.js')
+/** The pending-work-progress module namespace. */
+type PendingProgress = typeof import('../pending-work-progress.js')
+
+/**
+ * Apply the activity signals carried by `ev` to silence-poke / pending-progress
+ * for the live turn identified by `key`. Behaviour is identical to the inline
+ * block this replaced — a pure extract/move.
+ */
+export function applySilencePokeSessionEvent(
+  silencePoke: SilencePoke,
+  pendingProgress: PendingProgress,
+  key: string,
+  ev: SessionEvent,
+): void {
+  if (ev.kind === 'thinking') {
+    silencePoke.noteThinking(key, Date.now())
+  } else if (ev.kind === 'tool_use') {
+    // #1292: track in-flight tool calls so the 300s framework
+    // fallback message can name the actual observable (e.g.
+    // "running Grep \"foo\" for 4m") instead of the dishonest
+    // generic "still working… no update in 5 min" when the agent
+    // is clearly busy on tool calls. Telegram-surface tools are
+    // excluded — their job IS the outbound message, the silence
+    // clock resets via noteOutbound when they fire. Sub-agent
+    // tool_use events (kind='sub_agent_tool_use') intentionally
+    // NOT tracked: the parent's Task tool_use is already on the
+    // map and represents the user-observable wait.
+    if (
+      ev.toolUseId != null
+      && ev.toolUseId.length > 0
+      && !isTelegramSurfaceTool(ev.toolName)
+    ) {
+      const label = toolLabel(
+        ev.toolName,
+        ev.input,
+        /*preamble*/ undefined,
+        ev.precomputedLabel,
+      )
+      silencePoke.noteToolStart(
+        key,
+        ev.toolUseId,
+        ev.toolName,
+        label.length > 0 ? label : null,
+        Date.now(),
+      )
+      // #1445 cross-turn pending-async ambient. Mark the chat as
+      // having dispatched background work this turn so a turn_end
+      // that follows activates the edit-in-place ambient line.
+      // Covers `Agent` / `Task` (the harness-managed async path
+      // — handback channel turn clears it) and `Bash` with
+      // run_in_background:true (model is expected to poll
+      // BashOutput; the ambient ticks until next inbound or the
+      // 30-min budget cap).
+      const evInput = ev.input as { run_in_background?: boolean } | undefined
+      if (
+        ev.toolName === 'Agent'
+        || ev.toolName === 'Task'
+        || (ev.toolName === 'Bash' && evInput?.run_in_background === true)
+      ) {
+        pendingProgress.noteAsyncDispatch(key)
+      }
+    }
+  } else if (ev.kind === 'tool_result') {
+    // #1292: drain the in-flight entry. Idempotent on unknown ids
+    // (covers Telegram-surface tools we skipped at start time).
+    if (ev.toolUseId != null && ev.toolUseId.length > 0) {
+      silencePoke.noteToolEnd(key, ev.toolUseId, Date.now())
+    }
+  }
+  // #3519 sharpen: feed background-shell liveness (ALIVE/DEAD) to silence-poke — see background-shell-liveness.ts.
+  applyBackgroundShellLiveness(silencePoke, key, ev)
+}

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

package/telegram-plugin/gateway/unhandled-message.ts

@@ -22,6 +22,7 @@
  */
 
 import type { Bot, Context } from 'grammy'
+import { extractRichMessageText } from './rich-message-handler.js'
 
 /**
  * Top-level `message` envelope fields — identity/routing metadata, excluded
@@ -36,6 +37,14 @@ export const MESSAGE_ENVELOPE_KEYS: ReadonlySet<string> = new Set<string>([
   'business_connection_id', 'effect_id', 'has_protected_content',
   'is_from_offline', 'link_preview_options', 'show_caption_above_media',
   'entities', 'caption_entities', 'paid_star_count',
+  // Legacy (pre-Bot-API-7.0 spelling) forward metadata. Some wire payloads
+  // carry these ALONGSIDE `forward_origin` (observed live: carrie
+  // update_id=417526125, content_keys=[forward_from,forward_date,rich_message]).
+  // They are provenance metadata, not content — without this exclusion a
+  // forwarded unhandled message gets mislabeled `(unhandled message content:
+  // forward_from)` instead of naming its actual content type.
+  'forward_from', 'forward_from_chat', 'forward_from_message_id',
+  'forward_signature', 'forward_sender_name', 'forward_date',
 ])
 
 /**
@@ -88,6 +97,11 @@ export function planUnhandledMessage(msg: Record<string, unknown>): UnhandledMes
   const text =
     (typeof msg.text === 'string' ? msg.text : undefined) ??
     (typeof msg.caption === 'string' ? msg.caption : undefined) ??
+    // Belt-and-braces: `message:rich_message` has its own registered handler
+    // (rich-message-handler.ts), so a rich message normally never reaches the
+    // catch-all — but if one arrives ALONGSIDE unknown future content, its
+    // real body still beats a placeholder.
+    extractRichMessageText(msg.rich_message) ??
     `(unhandled message content: ${contentType})`
   return { action: 'turn', text, contentKeys }
 }

package/telegram-plugin/hooks/narration-classify.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Type declarations for the shared trailing-text narration classifier
+ * (switchroom#3513) so the bundled TypeScript surfaces — `turn-flush-safety.ts`,
+ * `shown-ledger.ts`, `narrative-flush.ts` — can import the ONE classifier from
+ * `narration-classify.mjs` without tsc resolution errors. The runtime module is
+ * plain ESM (it is also imported by the unbundled Stop-hook `.mjs`, which can
+ * only import sibling `.mjs` + node builtins), so it cannot be authored in TS.
+ */
+export const SUBSTANTIVE_MIN_CHARS: number
+export const NARRATION_OPENER: RegExp
+export const NARRATION_TRAILER: RegExp
+export function isTrailingNarrationLine(block: string): boolean
+export function isNarrationBlock(block: string): boolean
+export function isStructuralNarration(
+  text: string,
+  followedByToolUse: boolean | undefined,
+): boolean
+export const EPHEMERAL_TOOLS: Set<string>
+export function isEphemeralTool(name: string | null | undefined): boolean
+export function selectBackstopDelivery(
+  blocks: ReadonlyArray<{ text: string; followedByToolUse?: boolean }>,
+): { text: string } | null
+export function ledgerHashHex(text: string): string