switchroom 0.19.14 → 0.19.15

package/telegram-plugin/outbox.ts

@@ -122,11 +122,13 @@ export interface DeliveredEntry {
   tgMessageId?: number
   ts: number
   /**
-   * #3510 instrumentation: which machine delivered — the outbox sweep, or the
+   * #3510 instrumentation: which machine delivered — the outbox sweep, the
    * gateway reply-path machinery (reply/stream_reply send, silent-anchor edit,
-   * captured-prose bridge). Absent on pre-#3510 journal lines.
+   * captured-prose bridge), or the turn-end / answer-ready quiescence flush
+   * (`'flush'`, added in the #3513 exactly-once-among-backstops follow-up).
+   * Absent on pre-#3510 journal lines.
    */
-  deliverySource?: 'sweep' | 'reply-tool'
+  deliverySource?: 'sweep' | 'reply-tool' | 'flush'
   /** #3510 instrumentation: see `OutboxRecord.replyAlreadyDeliveredThisTurn`. */
   replyAlreadyDeliveredThisTurn?: boolean
 }
@@ -307,6 +309,59 @@ export function outboxAlreadyDelivered(nonce: string, stateDir?: string): boolea
   return readDeliveredNonces(stateDir).has(nonce)
 }
 
+/**
+ * True iff a journal entry is a prior BACKSTOP delivery (turn-flush E1/E2,
+ * captured-prose bridge E3, outbox sweep E4) — NOT an explicit E0 `reply` /
+ * `stream_reply` send (#3513 follow-up, MF2).
+ *
+ *   - `deliverySource === 'sweep'`  → E4 backstop.
+ *   - `deliverySource === 'flush'`  → E1/E2 backstop.
+ *   - `deliverySource === 'reply-tool'` AND `replyAlreadyDeliveredThisTurn ===
+ *     false` → E3 captured-prose bridge (a backstop; the bridge only fires when
+ *     NO genuine final answer was delivered this turn).
+ *   - `deliverySource === 'reply-tool'` AND `replyAlreadyDeliveredThisTurn ===
+ *     true` → an explicit E0 reply send — NOT a backstop. E0 replies are
+ *     ungated by design (a turn may send N of them), so they must NOT satisfy a
+ *     backstop's exactly-once guard (else the guard would eat a legitimate
+ *     #3510 trailing recap or a multi-reply turn's later bridge).
+ *
+ * A pre-#3510 line with no `deliverySource` is treated conservatively as NOT a
+ * backstop (fail open — never suppress a backstop on ambiguous provenance).
+ */
+export function isBackstopDeliveredEntry(e: DeliveredEntry): boolean {
+  if (e.deliverySource === 'sweep' || e.deliverySource === 'flush') return true
+  if (e.deliverySource === 'reply-tool' && e.replyAlreadyDeliveredThisTurn === false) return true
+  return false
+}
+
+/**
+ * True iff `nonce` already has a prior BACKSTOP delivery journaled (see
+ * `isBackstopDeliveredEntry`). This is the BACKSTOP-SCOPED exactly-once read the
+ * turn-flush (E1/E2) and captured-prose bridge (E3) consult before delivering —
+ * unlike `outboxAlreadyDelivered` (any journal line) it does NOT count an
+ * explicit E0 reply, so it can never suppress a legitimate second explicit
+ * message (#3513 follow-up, MF2).
+ */
+export function backstopAlreadyDelivered(nonce: string, stateDir?: string): boolean {
+  if (nonce == null || nonce === '') return false
+  const path = join(resolveOutboxDir(stateDir), JOURNAL_FILE)
+  if (!existsSync(path)) return false
+  try {
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      if (!line) continue
+      try {
+        const e = JSON.parse(line) as DeliveredEntry
+        if (e.turnNonce === nonce && isBackstopDeliveredEntry(e)) return true
+      } catch {
+        /* skip corrupt line */
+      }
+    }
+  } catch {
+    /* best-effort */
+  }
+  return false
+}
+
 /**
  * Max delivered-keys kept in the journal. On exceeding `JOURNAL_ROTATE_AT` lines
  * the journal is compacted down to the newest `JOURNAL_KEEP` entries — bounding
@@ -378,6 +433,7 @@ export type OutboxSweepAction =
   | 'skip-quiet'
   | 'skip-dedup'
   | 'skip-unroutable'
+  | 'skip-ephemeral-shown'
 
 export interface OutboxSweepDecision {
   action: OutboxSweepAction
@@ -408,6 +464,18 @@ export function decideOutboxSweep(input: {
   routePrefix?: string
   quietMs?: number
   maxAgeMs?: number
+  /**
+   * #3513 (correction 1): was this record's text marked ephemeral-shown on the
+   * progress card for its turnNonce (the durable shown-ledger)? A hit means the
+   * block was already assigned to the ephemeral surface — the single-surface
+   * invariant forbids ANY delivery machine, including this out-of-process late
+   * sweep, from ALSO delivering it to chat. The ledger only ever contains
+   * STRUCTURAL narration (correction 4: never a possibly-terminal answer), so
+   * this can never suppress a genuine answer. Checked here (in the backstop
+   * decision itself) rather than only at a send seam, because the sweep bypasses
+   * `normalizeOutboundBody` (it sends via `bot.api.sendMessage` directly).
+   */
+  shownLedgerHit?: boolean
 }): OutboxSweepDecision {
   const {
     record,
@@ -418,8 +486,10 @@ export function decideOutboxSweep(input: {
     routePrefix = '',
     quietMs = OUTBOX_QUIET_MS,
     maxAgeMs = OUTBOX_MAX_AGE_MS,
+    shownLedgerHit = false,
   } = input
   if (deliveredNonces.has(record.turnNonce)) return { action: 'skip-journaled' }
+  if (shownLedgerHit) return { action: 'skip-ephemeral-shown' }
   const age = now - record.createdAt
   if (age < quietMs) return { action: 'skip-quiet' }
   if (textAlreadyDelivered) return { action: 'skip-dedup' }

package/telegram-plugin/shown-ledger.ts

@@ -0,0 +1,145 @@
+/**
+ * shown-ledger.ts — the durable "this block was surfaced on the ephemeral
+ * progress card, never deliver it to chat" mark (switchroom#3513 §4).
+ *
+ * ## Role in the single-surface invariant
+ * Every trailing plain-text block a turn produces is assigned to exactly one
+ * surface: the delivered chat answer, the ephemeral progress card, or
+ * suppression. In-process (E1/E2 turn-flush, the card) that assignment is made
+ * once by the shared structural classifier (`hooks/narration-classify.mjs`).
+ * But the out-of-process backstops — the Stop-hook captured-prose bridge (E3)
+ * and the durable outbox heartbeat sweep (E4) — run in a separate process / on
+ * a later tick and cannot share an in-memory decision. So the component that
+ * paints a block as ephemeral narration appends `{turnNonce, hash}` here, and
+ * E3/E4 treat a ledger hit exactly like a silent marker: not deliverable.
+ *
+ * ## Correction 4 — only structural narration is ever marked
+ * The writer (the mid-turn narrative paint in `gateway/narrative-lane.ts`) marks
+ * ONLY blocks that are provably followed by more turn activity (a new narrative
+ * block or a tool call), i.e. structural narration — NEVER a possibly-terminal
+ * block (the timer-paint / turn-end paint that could turn out to be the real
+ * answer). This keeps the invariant fail-open for answers: a genuine unsent
+ * answer is never in the ledger, so a ledger check can never suppress it (a drop
+ * is worse than a duplicate). The structural rule, not the ledger, is the sole
+ * guard for the answer path.
+ *
+ * ## Envelope-bearing-only (documented should-fix, #3513 §8)
+ * The ledger is keyed by the turnNonce (`deriveTurnId` → `${chatKey}#${msgId}`),
+ * which is reachable-matching ONLY for envelope-bearing turns — `deriveTurnId`
+ * returns null without a message_id (`gateway/derive-turn-id.ts`), and the
+ * outbox falls back to a sha nonce. So the ledger is a best-effort belt for
+ * envelope-bearing turns (the common Telegram-inbound shape); for envelope-less
+ * turns (handback / background / cron) the structural classifier is the sole
+ * guard. The writer skips a null turnId; the readers simply miss and fall
+ * through to the structural rule — never a false suppression.
+ *
+ * Best-effort throughout: a missing / unwritable ledger degrades to the
+ * structural-rule-only behaviour (leak possible, drop impossible).
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+  appendFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import { resolveOutboxDir } from './outbox.js'
+import { ledgerHashHex } from './hooks/narration-classify.mjs'
+
+const SHOWN_LEDGER_FILE = 'shown-ledger.jsonl'
+
+/** Bounded growth — compact to the newest KEEP entries past ROTATE_AT lines. */
+export const SHOWN_LEDGER_KEEP = 2_000
+export const SHOWN_LEDGER_ROTATE_AT = 4_000
+
+/** One appended shown-block entry. */
+export interface ShownLedgerEntry {
+  turnNonce: string
+  hash: string
+  ts: number
+}
+
+export function shownLedgerPath(stateDir?: string): string {
+  return join(resolveOutboxDir(stateDir), SHOWN_LEDGER_FILE)
+}
+
+/**
+ * Mark a block as ephemeral-shown for `turnNonce`. Correction 4: callers MUST
+ * only pass blocks that are structural narration (followed by more turn
+ * activity), never a possibly-terminal block. A null/empty turnNonce is ignored
+ * (envelope-less turn — the structural rule is the sole guard there).
+ * Best-effort; never throws.
+ */
+export function appendShownBlock(
+  turnNonce: string | null,
+  text: string,
+  stateDir?: string,
+  now: number = Date.now(),
+): void {
+  if (turnNonce == null || turnNonce === '') return
+  const trimmed = typeof text === 'string' ? text.trim() : ''
+  if (trimmed.length === 0) return
+  const dir = resolveOutboxDir(stateDir)
+  const path = shownLedgerPath(stateDir)
+  try {
+    mkdirSync(dir, { recursive: true })
+    const entry: ShownLedgerEntry = { turnNonce, hash: ledgerHashHex(trimmed), ts: now }
+    appendFileSync(path, JSON.stringify(entry) + '\n', { mode: 0o600 })
+    compactIfLarge(path)
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** The set of block hashes marked ephemeral-shown for `turnNonce`. */
+export function readShownHashes(turnNonce: string | null, stateDir?: string): Set<string> {
+  const set = new Set<string>()
+  if (turnNonce == null || turnNonce === '') return set
+  const path = shownLedgerPath(stateDir)
+  if (!existsSync(path)) return set
+  try {
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      if (!line) continue
+      try {
+        const e = JSON.parse(line) as ShownLedgerEntry
+        if (e.turnNonce === turnNonce && typeof e.hash === 'string') set.add(e.hash)
+      } catch {
+        /* skip corrupt line */
+      }
+    }
+  } catch {
+    /* best-effort */
+  }
+  return set
+}
+
+/**
+ * Was `text` marked ephemeral-shown for `turnNonce`? The out-of-process
+ * suppression check consumed by the E3 captured-prose decision and the E4 sweep.
+ */
+export function isShownBlock(
+  turnNonce: string | null,
+  text: string,
+  stateDir?: string,
+): boolean {
+  if (turnNonce == null || turnNonce === '') return false
+  const trimmed = typeof text === 'string' ? text.trim() : ''
+  if (trimmed.length === 0) return false
+  return readShownHashes(turnNonce, stateDir).has(ledgerHashHex(trimmed))
+}
+
+function compactIfLarge(path: string): void {
+  try {
+    const lines = readFileSync(path, 'utf8').split('\n').filter((l) => l.length > 0)
+    if (lines.length <= SHOWN_LEDGER_ROTATE_AT) return
+    const kept = lines.slice(lines.length - SHOWN_LEDGER_KEEP)
+    const tmp = `${path}.${process.pid}.compact`
+    writeFileSync(tmp, kept.join('\n') + '\n', { mode: 0o600 })
+    renameSync(tmp, path)
+  } catch {
+    /* best-effort */
+  }
+}

package/telegram-plugin/silent-end.ts

@@ -86,6 +86,29 @@ export interface SilentEndDeps {
   hasOutboundDeliveredSince?: (chatId: string, sinceMs: number, threadId?: number | null) => boolean
   /** Wall-clock now, ms. Defaults to `Date.now`; injectable for tests. */
   now?: () => number
+  /**
+   * #3513 (correction 1): was `text` marked ephemeral-shown on the progress card
+   * for `turnNonce` (the durable shown-ledger)? Injected so the captured-prose
+   * bridge (E3) — which sends via `bot.api.sendMessage` directly, bypassing
+   * `normalizeOutboundBody` — refuses to deliver a block that was already
+   * assigned to the ephemeral surface. The ledger only ever holds STRUCTURAL
+   * narration (correction 4: never a possibly-terminal answer), so this can
+   * never suppress a genuine answer. Omitted → the check is skipped (the
+   * structural classifier remains the guard).
+   */
+  isBlockShown?: (turnNonce: string | null | undefined, text: string) => boolean
+  /**
+   * #3513 follow-up (MF2): has a prior BACKSTOP already delivered this turn's
+   * answer, per the durable delivered-keys journal? Injected so the captured-
+   * prose bridge (E3) enforces exactly-once-among-backstops DURABLY — if the
+   * turn-flush backstop (E1/E2, `deliverySource:'flush'`) or the outbox sweep
+   * (E4, `'sweep'`) already delivered this nonce, the bridge must NOT deliver a
+   * second copy, even across a process boundary the in-memory ledger can't see.
+   * This counts ONLY backstop deliveries (via `backstopAlreadyDelivered`), never
+   * an explicit E0 reply (#3510 recap), so a legitimate later explicit reply is
+   * unaffected. Omitted → the check is skipped (never suppress on doubt).
+   */
+  backstopDeliveredNonceHit?: (turnNonce: string | null | undefined) => boolean
 }
 
 /**
@@ -306,6 +329,8 @@ export interface CapturedProseDecision {
     | 'turnkey-mismatch'
     | 'turnid-mismatch'
     | 'no-substantive-prose'
+    | 'ephemeral-shown'
+    | 'already-delivered'
 }
 
 /**
@@ -352,6 +377,23 @@ export function decideCapturedProseDelivery(
   }
   const text = typeof state.pendingText === 'string' ? state.pendingText : ''
   if (text.trim().length < minChars) return { deliver: false, reason: 'no-substantive-prose' }
+  // #3513: the persisted prose was already surfaced on the ephemeral progress
+  // card for this turn (durable shown-ledger) — the single-surface invariant
+  // forbids the bridge from ALSO delivering it to chat. The ledger only holds
+  // structural narration (never a possibly-terminal answer), so this can never
+  // suppress a genuine answer.
+  if (deps?.isBlockShown?.(state.turnId, text) === true) {
+    return { deliver: false, reason: 'ephemeral-shown' }
+  }
+  // #3513 follow-up (MF2): exactly-once-among-backstops. If a prior backstop
+  // (turn-flush E1/E2 or the outbox sweep E4) already delivered THIS turn's
+  // answer per the durable journal, the bridge must not deliver a duplicate —
+  // even across the process boundary the in-memory dedup can't see. Counts only
+  // backstop deliveries, never an explicit E0 reply, so a genuine later explicit
+  // reply is never blocked here.
+  if (deps?.backstopDeliveredNonceHit?.(state.turnId) === true) {
+    return { deliver: false, reason: 'already-delivered' }
+  }
   return { deliver: true, text, reason: 'captured-prose' }
 }
 

package/telegram-plugin/tests/backstop-exactly-once.test.ts

@@ -0,0 +1,335 @@
+/**
+ * backstop-exactly-once.test.ts — outcome-asserting regression suite for the
+ * switchroom#3513 FOLLOW-UP: the deterministic, model-discipline-free
+ * "exactly-once-among-backstops" outbound contract.
+ *
+ * The invariant under test:
+ *   - Any text block followed by a NON-ephemeral (turn-continuing) tool_use in
+ *     the SAME turn — including the cross-message shape ([text-only message] →
+ *     [tool_use in the NEXT message]) — is suppressed from the backstop delivery
+ *     UNCONDITIONALLY (no length / wording gate). This replaces #3515's
+ *     substance/wording heuristic on the backstop path.
+ *   - The delivered block is the TERMINAL RUN (the suffix of non-tool-followed
+ *     blocks), joined; a multi-paragraph terminal answer stays whole.
+ *   - The empty-terminal corner (last block was itself tool-followed) delivers
+ *     that last block IFF it clears the substantive floor, else nothing.
+ *   - An explicit reply-tool (E0) send is journaled with
+ *     `replyAlreadyDeliveredThisTurn=true` and is NOT counted by
+ *     `backstopAlreadyDelivered`, so a legitimate later explicit reply is never
+ *     blocked by the backstop exactly-once guard.
+ *   - An answer followed ONLY by an ephemeral surface tool (react / pin / typing
+ *     / edit / delete) still delivers — those tools are not turn-continuing.
+ *
+ * Every test asserts an OUTCOME and is written to be RED on the pre-fix logic
+ * (per-message provenance + substance-gated wording strip + no backstop-scoped
+ * durable read).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  selectBackstopDelivery,
+  isEphemeralTool,
+  EPHEMERAL_TOOLS,
+  SUBSTANTIVE_MIN_CHARS,
+} from '../hooks/narration-classify.mjs'
+import { scanTurnForFinalReply, scanForOutboxCapture } from '../hooks/silent-end-scan.mjs'
+import {
+  appendDelivered,
+  backstopAlreadyDelivered,
+  isBackstopDeliveredEntry,
+  outboxAlreadyDelivered,
+} from '../outbox.js'
+import { decideCapturedProseDelivery, writeSilentEndState } from '../silent-end.js'
+
+// ── Fixture builders (parity with silent-end-interrupt-stop-scan.test.ts) ────
+
+const ENQUEUE = JSON.stringify({
+  type: 'queue-operation',
+  operation: 'enqueue',
+  content: '<channel source="switchroom-telegram" chat_id="111" message_id="42">hi</channel>',
+})
+
+function assistantText(text: string) {
+  return JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text }] } })
+}
+function assistantToolUse(name: string, input: Record<string, unknown> = {}) {
+  return JSON.stringify({
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', id: `t-${name}`, name, input }] },
+  })
+}
+function jsonl(...lines: string[]) {
+  return lines.join('\n')
+}
+
+const BIG = (label: string) =>
+  `${label}: ` + 'X'.repeat(SUBSTANTIVE_MIN_CHARS + 20)
+
+// ── selectBackstopDelivery — the shared coalescer ────────────────────────────
+
+describe('selectBackstopDelivery — deterministic backstop coalescer (#3513 follow-up)', () => {
+  it('excludes a tool-followed block UNCONDITIONALLY, even a substantive one (no substance carve-out)', () => {
+    // Pre-fix: a ≥floor block followed by a tool was KEPT (the #3237 substance
+    // gate). New contract: suppressed unconditionally; only the terminal block
+    // survives. RED on the old substance-gated logic.
+    const answer = BIG('the real answer')
+    const closer = 'Saved that to memory.'
+    const out = selectBackstopDelivery([
+      { text: answer, followedByToolUse: true },
+      { text: closer, followedByToolUse: false },
+    ])
+    expect(out).not.toBeNull()
+    expect(out!.text).toBe(closer)
+    expect(out!.text).not.toContain('the real answer')
+  })
+
+  it('joins the maximal terminal suffix run of non-tool-followed blocks (multi-paragraph answer stays whole)', () => {
+    const p1 = 'First paragraph of the genuine answer.'
+    const p2 = 'Second paragraph, still part of the same answer.'
+    const out = selectBackstopDelivery([
+      { text: 'Let me look…', followedByToolUse: true }, // suppressed
+      { text: p1, followedByToolUse: false },
+      { text: p2, followedByToolUse: false },
+    ])
+    expect(out!.text).toBe(`${p1}\n\n${p2}`)
+  })
+
+  it('empty-terminal corner: last block was tool-followed → delivered IFF ≥ substantive floor', () => {
+    const big = BIG('trailing but substantive')
+    const overFloor = selectBackstopDelivery([{ text: big, followedByToolUse: true }])
+    expect(overFloor!.text).toBe(big)
+    const short = selectBackstopDelivery([{ text: 'ok…', followedByToolUse: true }])
+    expect(short).toBeNull()
+  })
+
+  it('undefined provenance fails OPEN — the block is delivered, never dropped', () => {
+    const out = selectBackstopDelivery([{ text: 'Let me check.' }, { text: 'the answer' }])
+    // No structural signal → both are the terminal run → joined (no wording strip).
+    expect(out!.text).toBe('Let me check.\n\nthe answer')
+  })
+
+  it('all-empty / no-blocks → null', () => {
+    expect(selectBackstopDelivery([])).toBeNull()
+    expect(selectBackstopDelivery([{ text: '   ', followedByToolUse: false }])).toBeNull()
+  })
+})
+
+// ── isEphemeralTool — MF4 exact set ─────────────────────────────────────────
+
+describe('isEphemeralTool — the exact ephemeral surface set (MF4)', () => {
+  it('recognises exactly {react, send_typing, pin_message, delete_message, edit_message}, MCP-prefixed or bare', () => {
+    expect([...EPHEMERAL_TOOLS].sort()).toEqual(
+      ['delete_message', 'edit_message', 'pin_message', 'react', 'send_typing'].sort(),
+    )
+    for (const t of EPHEMERAL_TOOLS) {
+      expect(isEphemeralTool(t)).toBe(true)
+      expect(isEphemeralTool(`mcp__switchroom-telegram__${t}`)).toBe(true)
+      expect(isEphemeralTool(`mcp__clerk-telegram__${t}`)).toBe(true)
+    }
+  })
+
+  it('progress_update is NOT ephemeral (MF4 — dropped from the set)', () => {
+    expect(isEphemeralTool('progress_update')).toBe(false)
+    expect(isEphemeralTool('mcp__switchroom-telegram__progress_update')).toBe(false)
+  })
+
+  it('work / reply tools are NOT ephemeral (turn-continuing)', () => {
+    for (const t of ['Bash', 'Read', 'retain', 'download_attachment', 'reply', 'stream_reply']) {
+      expect(isEphemeralTool(t)).toBe(false)
+    }
+  })
+})
+
+// ── Cross-message split-shape leak — the ROOT-CAUSE regression (MF1) ─────────
+
+describe('cross-message split-shape provenance (MF1 — RED on per-message logic)', () => {
+  it('scanTurnForFinalReply: substantive narration in msg1, work-tool in msg2, real answer in msg3 → ONLY the answer delivers (narration suppressed)', () => {
+    // Pre-fix: `followedByToolUse` was computed per-message, so the narration
+    // block — the LAST content of its OWN message — never saw the tool that
+    // arrived in the SEPARATE next message. Its provenance read `false`, so the
+    // wording heuristic (not a structural tool signal) decided its fate; a
+    // substantive narration that didn't LOOK like narration leaked, joined with
+    // the answer. The per-turn two-pass marks it tool-followed → the terminal-run
+    // coalescer excludes it UNCONDITIONALLY, leaving only the genuine answer.
+    const narration = BIG('checking the gateway logs to see what happened before I answer')
+    const answer = BIG('here is the settled, terminal answer the user asked for')
+    const text = jsonl(
+      ENQUEUE,
+      assistantText(narration), // msg1 — text only
+      assistantToolUse('Bash', { command: 'tail -f log' }), // msg2 — turn-continuing tool
+      assistantText(answer), // msg3 — the real terminal answer
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.pendingText).toBe(answer)
+    expect(r.pendingText).not.toContain('checking the gateway logs')
+  })
+
+  it('scanForOutboxCapture: same cross-message shape → captures ONLY the answer, never the narration', () => {
+    const narration = BIG('cross-referencing the ledger before summarising the result')
+    const answer = BIG('the durable, delivered-once answer for the outbox sweep')
+    const text = jsonl(
+      ENQUEUE,
+      assistantText(narration), // msg1
+      assistantToolUse('Read', { file_path: '/tmp/x' }), // msg2 — turn-continuing tool
+      assistantText(answer), // msg3 — terminal answer
+    )
+    const cap = scanForOutboxCapture(text)
+    expect(cap.capture).toBe(true)
+    if (cap.capture) {
+      expect(cap.text).toBe(answer.trim())
+      expect(cap.text).not.toContain('cross-referencing the ledger')
+    }
+  })
+
+  it('scanTurnForFinalReply: same shape but the trailing block IS terminal (no later tool) → delivered', () => {
+    // Control: when the substantive block is genuinely terminal (nothing follows
+    // it in the whole turn), it IS the answer and must deliver.
+    const answer = BIG('the genuine terminal answer')
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('Bash', { command: 'ls' }), // work happened first
+      assistantText(answer), // terminal — no tool after
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.pendingText).toBe(answer)
+  })
+})
+
+// ── answer-then-ephemeral-react still delivers (MF4b) ───────────────────────
+
+describe('answer-then-ephemeral-tool still delivers (MF4b)', () => {
+  it('a terminal answer followed ONLY by a react/pin/edit is NOT suppressed', () => {
+    const answer = BIG('the answer the user was waiting for')
+    // Ephemeral tools are not recorded as work-tool markers, so the answer stays
+    // terminal and delivers.
+    const text = jsonl(
+      ENQUEUE,
+      assistantText(answer),
+      assistantToolUse('mcp__switchroom-telegram__react', { emoji: '👍' }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.pendingText).toBe(answer)
+  })
+})
+
+// ── backstopAlreadyDelivered — exactly-once-among-backstops (MF2) ────────────
+
+describe('backstopAlreadyDelivered — backstop-scoped durable exactly-once (MF2)', () => {
+  let dir: string
+
+  it('classifies delivery sources: flush + sweep + non-E0 reply-tool are backstops; E0 reply is NOT', () => {
+    expect(isBackstopDeliveredEntry({ turnNonce: 'n', textSha256: 'x', ts: 0, deliverySource: 'flush' })).toBe(true)
+    expect(isBackstopDeliveredEntry({ turnNonce: 'n', textSha256: 'x', ts: 0, deliverySource: 'sweep' })).toBe(true)
+    // E3 captured-prose bridge journals as reply-tool with replyAlready=false → backstop.
+    expect(
+      isBackstopDeliveredEntry({
+        turnNonce: 'n', textSha256: 'x', ts: 0,
+        deliverySource: 'reply-tool', replyAlreadyDeliveredThisTurn: false,
+      }),
+    ).toBe(true)
+    // E0 explicit reply journals with replyAlready=true → NOT a backstop.
+    expect(
+      isBackstopDeliveredEntry({
+        turnNonce: 'n', textSha256: 'x', ts: 0,
+        deliverySource: 'reply-tool', replyAlreadyDeliveredThisTurn: true,
+      }),
+    ).toBe(false)
+  })
+
+  it('a prior FLUSH delivery is seen by backstopAlreadyDelivered; a prior E0 reply is NOT', () => {
+    dir = mkdtempSync(join(tmpdir(), 'backstop-once-'))
+    try {
+      // E0 reply for turn A — must NOT count as a backstop.
+      appendDelivered(
+        { turnNonce: 'A', textSha256: 'ha', ts: 1, deliverySource: 'reply-tool', replyAlreadyDeliveredThisTurn: true },
+        dir,
+      )
+      expect(backstopAlreadyDelivered('A', dir)).toBe(false)
+      // …but outboxAlreadyDelivered (the E4 sweep dedup, source-agnostic) DOES see it.
+      expect(outboxAlreadyDelivered('A', dir)).toBe(true)
+
+      // Flush backstop for turn B — must count.
+      appendDelivered({ turnNonce: 'B', textSha256: 'hb', ts: 2, deliverySource: 'flush' }, dir)
+      expect(backstopAlreadyDelivered('B', dir)).toBe(true)
+
+      // Unknown nonce → false.
+      expect(backstopAlreadyDelivered('C', dir)).toBe(false)
+      expect(backstopAlreadyDelivered('', dir)).toBe(false)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('E3 bridge decision skips when a prior backstop already delivered the nonce (already-delivered), but an E0 recap does NOT block it', () => {
+    dir = mkdtempSync(join(tmpdir(), 'backstop-e3-'))
+    try {
+      const turnKey = 'c:_'
+      const turnId = 'c:_#42'
+      const answer = BIG('the recovered answer')
+      writeSilentEndState({ chatId: 'c', threadId: null, turnKey }, { stateDir: dir })
+      // Persist pendingText onto the record so the bridge has something to deliver.
+      // (writeSilentEndState doesn't set pendingText; simulate the hook's write.)
+      appendDelivered({ turnNonce: turnId, textSha256: 'z', ts: 1, deliverySource: 'flush' }, dir)
+
+      // With a prior FLUSH backstop for this turnId, the bridge must refuse.
+      const blocked = decideCapturedProseDelivery(
+        { turnKey, turnId, minChars: 1 },
+        {
+          stateDir: dir,
+          backstopDeliveredNonceHit: (n) => backstopAlreadyDelivered(n ?? '', dir),
+        },
+      )
+      // The state file itself carries no pendingText here, so the decision is
+      // no-substantive-prose OR already-delivered — assert it does NOT deliver.
+      expect(blocked.deliver).toBe(false)
+
+      // A prior E0 reply recap for the same nonce must NOT trip the backstop guard.
+      const dir2 = mkdtempSync(join(tmpdir(), 'backstop-e0-'))
+      try {
+        appendDelivered(
+          { turnNonce: turnId, textSha256: 'z', ts: 1, deliverySource: 'reply-tool', replyAlreadyDeliveredThisTurn: true },
+          dir2,
+        )
+        expect(backstopAlreadyDelivered(turnId, dir2)).toBe(false)
+      } finally {
+        rmSync(dir2, { recursive: true, force: true })
+      }
+      void answer
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ── multi-substantive-block → one delivery; empty-terminal → one delivery ────
+
+describe('single-delivery selection through the scan (MF5)', () => {
+  it('multiple substantive terminal blocks → ONE joined delivery (never a second bubble)', () => {
+    const p1 = BIG('first half of the answer')
+    const p2 = BIG('second half of the answer')
+    const text = jsonl(ENQUEUE, assistantText(p1), assistantText(p2))
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.pendingText).toBe(`${p1}\n\n${p2}`)
+  })
+
+  it('empty terminal (last block tool-followed) → the prior substantive terminal run is delivered once', () => {
+    const answer = BIG('the settled answer')
+    const text = jsonl(
+      ENQUEUE,
+      assistantText(answer), // terminal? no — a tool follows in the next msg
+      assistantToolUse('retain', { text: 'note' }),
+    )
+    // answer is tool-followed → empty terminal run → rule 3 delivers it iff ≥floor.
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.pendingText).toBe(answer)
+  })
+})

package/telegram-plugin/tests/catch-all-unhandled-message.test.ts

@@ -195,6 +195,20 @@ describe('planUnhandledMessage — service-noise classification', () => {
     })
   })
 
+  it('legacy forward_* wire keys are envelope metadata — the placeholder names the CONTENT, never "forward_from" (row-944 mislabel)', () => {
+    const plan = planUnhandledMessage({
+      message_id: 944, chat: {}, date: 0,
+      forward_from: { id: 1, is_bot: true, first_name: 'Klanker' },
+      forward_date: 1784830000,
+      mystery_future_content: {},
+    })
+    expect(plan).toMatchObject({
+      action: 'turn',
+      text: '(unhandled message content: mystery_future_content)',
+    })
+    expect(plan.contentKeys).toEqual(['mystery_future_content'])
+  })
+
   it('a message mixing noise with real content still becomes a turn', () => {
     const plan = planUnhandledMessage({
       message_id: 1, chat: {}, date: 0,