switchroom 0.19.13 → 0.19.15

package/telegram-plugin/tests/forwarded-rich-message.test.ts

@@ -0,0 +1,305 @@
+/**
+ * Outcome regression: forwarded-message body must reach the agent — never a
+ * placeholder (carrie history.db row message_id=944, 2026-07-24 06:03).
+ *
+ * THE BUG: a forwarded BOT message arrives as Bot API 10.1 `rich_message`
+ * content (the gateway sends everything via sendRichMessage) with NO
+ * top-level text/caption. Live gateway log (carrie, update_id=417526125):
+ *   content_keys=[forward_from,forward_date,rich_message] action=turn
+ * It matched no registered `message:*` handler, fell to the terminal
+ * catch-all, and the agent received
+ *   "(unhandled message content: forward_from)"
+ * instead of the forwarded token list. Two defects composed:
+ *   1. no `message:rich_message` registration (grammy ^1.44 supports it);
+ *   2. legacy `forward_*` wire keys were not in MESSAGE_ENVELOPE_KEYS, so
+ *      the placeholder was mislabeled with provenance, not content.
+ *
+ * These tests drive a REAL grammy 1.44 Bot through the REAL production
+ * modules (rich-message-handler + unhandled-message catch-all) in the
+ * gateway's registration order and assert the DELIVERED text — the outcome
+ * the agent actually receives. The key regression test was verified to FAIL
+ * on unfixed main (delivered text was the placeholder) and pass here.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Bot, type Context } from 'grammy'
+import type { Update } from 'grammy/types'
+import { makeMessageUpdate, resetUpdateCounters } from './update-factory.js'
+import { installUnhandledMessageCatchAll } from '../gateway/unhandled-message.js'
+import {
+  handleRichMessageMessage,
+  extractRichMessageText,
+  RICH_MESSAGE_EMPTY_TEXT,
+} from '../gateway/rich-message-handler.js'
+import type { MediaEnvelopeDeps } from '../gateway/media-message-handlers.js'
+import { parseForwardOrigin, buildForwardOriginMeta } from '../gateway/forward-origin.js'
+
+const UNHANDLED_PLACEHOLDER_RE = /^\(unhandled message content: /
+
+interface Delivered {
+  via: string
+  text: string
+}
+
+/** Wire a real grammy Bot in the gateway's registration order: message:text,
+ * message:rich_message (real production handler), terminal catch-all LAST. */
+function buildHarness() {
+  const delivered: Delivered[] = []
+  const logLines: string[] = []
+  const bot = new Bot('12345:TEST_TOKEN_NOT_REAL')
+  bot.botInfo = {
+    id: 999,
+    is_bot: true,
+    first_name: 'TestBot',
+    username: 'test_bot',
+    can_join_groups: true,
+    can_read_all_group_messages: false,
+    supports_inline_queries: false,
+    can_connect_to_business: false,
+    has_main_web_app: false,
+  }
+
+  bot.on('message:text', async ctx => {
+    delivered.push({ via: 'text', text: ctx.message.text })
+  })
+  const richDeps: MediaEnvelopeDeps = {
+    handleInbound: async (_ctx, text) => {
+      delivered.push({ via: 'rich_message', text })
+    },
+    handleAckOnly: async () => {},
+    handleRefusal: async () => {},
+    log: line => logLines.push(line),
+  }
+  bot.on('message:rich_message', ctx => handleRichMessageMessage(ctx, richDeps))
+  installUnhandledMessageCatchAll(
+    bot,
+    async (_ctx: Context, text: string) => {
+      delivered.push({ via: 'catch-all', text })
+    },
+    line => logLines.push(line),
+  )
+  return { bot, delivered, logLines }
+}
+
+/** The forwarded-bot-message shape observed live (update_id=417526125):
+ * forward_origin (modern) + legacy forward_from/forward_date siblings +
+ * rich_message content, NO top-level text/caption. */
+function makeForwardedRichUpdate(update_id: number, blocks: unknown[]): Update {
+  const originUser = { id: 8500000001, is_bot: true, first_name: 'Klanker', username: 'meken_klanker_bot' }
+  return {
+    update_id,
+    message: {
+      message_id: 944,
+      chat: { id: -1004223464247, type: 'supergroup', title: 'ProductOS', is_forum: true },
+      from: { id: 777, is_bot: false, first_name: 'Ken' },
+      date: 1784837003,
+      forward_origin: { type: 'user', date: 1784830000, sender_user: originUser },
+      forward_from: originUser,
+      forward_date: 1784830000,
+      rich_message: { blocks },
+    },
+  } as unknown as Update
+}
+
+const TOKEN_LIST_BLOCKS = [
+  { type: 'paragraph', text: 'Try these tokens' },
+  {
+    type: 'list',
+    items: [
+      { label: '-', blocks: [{ type: 'paragraph', text: [{ type: 'code', text: 'tok_alpha_123' }] }] },
+      { label: '-', blocks: [{ type: 'paragraph', text: [{ type: 'code', text: 'tok_beta_456' }] }] },
+    ],
+  },
+]
+
+describe('forwarded rich (bot) message — the row-944 regression oracle', () => {
+  beforeEach(() => resetUpdateCounters())
+
+  it('delivers the REAL forwarded body — not the unhandled placeholder, not empty', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(makeForwardedRichUpdate(417526125, TOKEN_LIST_BLOCKS))
+
+    expect(delivered).toHaveLength(1)
+    const turn = delivered[0]
+    // Bug-catcher oracle: real content in, real content out.
+    expect(turn.text.length).toBeGreaterThan(0)
+    expect(turn.text).not.toMatch(UNHANDLED_PLACEHOLDER_RE)
+    expect(turn.text).not.toContain('forward_from')
+    // The actual forwarded body the agent must receive.
+    expect(turn.text).toContain('Try these tokens')
+    expect(turn.text).toContain('tok_alpha_123')
+    expect(turn.text).toContain('tok_beta_456')
+  })
+
+  it('forward-origin metadata CO-ARRIVES on the trusted attr lane (not injected into the body)', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = makeForwardedRichUpdate(417526126, TOKEN_LIST_BLOCKS)
+    await bot.handleUpdate(update)
+
+    // The same server-stamped forward_origin the enqueue path parses
+    // (gateway.ts → parseForwardOrigin → buildForwardOriginMeta → meta attrs).
+    const origin = parseForwardOrigin(
+      (update as unknown as { message: { forward_origin: never } }).message.forward_origin,
+    )
+    const meta = buildForwardOriginMeta([origin!])
+    expect(meta.forwarded_from).toBe('Klanker (@meken_klanker_bot)')
+    expect(meta.forwarded_from_type).toBe('user')
+    expect(meta.forwarded_date).toBeDefined()
+    // Trusted-lane separation (#3162): the delivered BODY carries no
+    // provenance strings — those live only in the channel attrs.
+    expect(delivered[0].text).not.toContain('Klanker')
+  })
+
+  it('a rich message with genuinely no extractable text still yields an honest turn', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(
+      makeForwardedRichUpdate(417526127, [{ type: 'divider' }, { type: 'anchor', name: 'top' }]),
+    )
+    expect(delivered).toHaveLength(1)
+    // Divider renders as ---; a fully empty tree gets the honest fallback.
+    expect(delivered[0].via).toBe('rich_message')
+    expect(delivered[0].text).not.toMatch(UNHANDLED_PLACEHOLDER_RE)
+  })
+
+  it('a truly empty rich message delivers the named fallback, never the mislabeled placeholder', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(makeForwardedRichUpdate(417526128, []))
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0].text).toBe(RICH_MESSAGE_EMPTY_TEXT)
+  })
+
+  it('a NON-forwarded rich message (bot-to-bot, rich DM) also delivers its body', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = {
+      update_id: 417526129,
+      message: {
+        message_id: 950,
+        chat: { id: 777, type: 'private' },
+        from: { id: 777, is_bot: false, first_name: 'Ken' },
+        date: 1784837100,
+        rich_message: { blocks: [{ type: 'heading', size: 2, text: 'Release plan' }, { type: 'paragraph', text: 'Ship Friday.' }] },
+      },
+    } as unknown as Update
+    await bot.handleUpdate(update)
+    expect(delivered[0].text).toContain('Release plan')
+    expect(delivered[0].text).toContain('Ship Friday.')
+  })
+})
+
+describe('working shapes stay unchanged (no regression on existing forwards)', () => {
+  beforeEach(() => resetUpdateCounters())
+
+  it('plain user-text forward: full body via message:text + co-arriving origin meta', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = makeMessageUpdate({ text: 'here is the brief I forwarded', update_id: 7001 })
+    const msg = (update as unknown as { message: Record<string, unknown> }).message
+    msg.forward_origin = {
+      type: 'user',
+      date: 1_700_000_000,
+      sender_user: { id: 424242, is_bot: false, first_name: 'Ken', last_name: 'Thompson' },
+    }
+    await bot.handleUpdate(update)
+
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0]).toMatchObject({ via: 'text', text: 'here is the brief I forwarded' })
+    const meta = buildForwardOriginMeta([parseForwardOrigin(msg.forward_origin as never)!])
+    expect(meta.forwarded_from).toBe('Ken Thompson')
+    expect(meta.forwarded_date).toBeDefined()
+  })
+
+  it('hidden_user forward: full body, type=hidden_user, NO forwarded_from_id', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = makeMessageUpdate({ text: 'anon tip: check the logs', update_id: 7002 })
+    const msg = (update as unknown as { message: Record<string, unknown> }).message
+    msg.forward_origin = { type: 'hidden_user', date: 1_700_000_000, sender_user_name: 'Mystery Sender' }
+    await bot.handleUpdate(update)
+
+    expect(delivered[0].text).toBe('anon tip: check the logs')
+    const meta = buildForwardOriginMeta([parseForwardOrigin(msg.forward_origin as never)!])
+    expect(meta.forwarded_from).toBe('Mystery Sender')
+    expect(meta.forwarded_from_type).toBe('hidden_user')
+    expect(meta.forwarded_from_id).toBeUndefined()
+  })
+
+  it('channel caption/media forward: caption is the body and forwarded_message_id deep-links the post (G2)', () => {
+    // The photo handler's body contract is `caption ?? '(photo)'`
+    // (photo-message-handler.ts) — assert the origin-meta side here.
+    const origin = parseForwardOrigin({
+      type: 'channel',
+      date: 1_700_000_000,
+      message_id: 555,
+      chat: { id: -100400500, type: 'channel', title: 'Release Notes', username: 'relnotes' } as never,
+    })
+    const meta = buildForwardOriginMeta([origin!])
+    expect(meta.forwarded_from).toBe('Release Notes (@relnotes)')
+    expect(meta.forwarded_from_type).toBe('channel')
+    expect(meta.forwarded_message_id).toBe('555')
+  })
+})
+
+describe('rich block rendering — deterministic text extraction', () => {
+  it('renders headings, lists with checkboxes, pre blocks, quotes, and tables', () => {
+    const text = extractRichMessageText({
+      blocks: [
+        { type: 'heading', size: 1, text: 'Plan' },
+        {
+          type: 'list',
+          items: [
+            { label: '1.', blocks: [{ type: 'paragraph', text: 'first' }], has_checkbox: true, is_checked: true },
+            { label: '2.', blocks: [{ type: 'paragraph', text: 'second' }], has_checkbox: true },
+          ],
+        },
+        { type: 'pre', language: 'python', text: 'print(1)' },
+        { type: 'blockquote', blocks: [{ type: 'paragraph', text: 'quoted line' }], credit: 'someone' },
+        { type: 'table', cells: [[{ text: 'A', align: 'left', valign: 'top' }, { text: 'B', align: 'left', valign: 'top' }]] },
+        { type: 'photo', photo: [], caption: { text: 'the screenshot' } },
+      ],
+    })
+    expect(text).toContain('Plan')
+    expect(text).toContain('1. [x] first')
+    expect(text).toContain('2. [ ] second')
+    expect(text).toContain('```python\nprint(1)\n```')
+    expect(text).toContain('> quoted line')
+    expect(text).toContain('> — someone')
+    expect(text).toContain('A | B')
+    expect(text).toContain('[photo] the screenshot')
+  })
+
+  it('flattens nested inline rich text (bold/url/custom emoji/math) to content', () => {
+    const text = extractRichMessageText({
+      blocks: [{
+        type: 'paragraph',
+        text: [
+          'see ',
+          { type: 'bold', text: [{ type: 'url', text: 'the docs', url: 'https://x' }] },
+          ' ',
+          { type: 'custom_emoji', custom_emoji_id: '1', alternative_text: '👍' },
+          ' ',
+          { type: 'mathematical_expression', expression: 'E=mc^2' },
+        ],
+      }],
+    })
+    expect(text).toBe('see the docs 👍 E=mc^2')
+  })
+
+  it('an unknown future block type surfaces its text instead of vanishing', () => {
+    expect(extractRichMessageText({ blocks: [{ type: 'hologram', text: 'future words' }] }))
+      .toBe('future words')
+  })
+
+  it('malformed / hostile payloads return undefined instead of throwing', () => {
+    expect(extractRichMessageText(undefined)).toBeUndefined()
+    expect(extractRichMessageText('nope')).toBeUndefined()
+    expect(extractRichMessageText({ blocks: 'nope' })).toBeUndefined()
+    // Deep self-nesting stops at the recursion cap, no stack overflow.
+    const deep: { type: string; blocks: unknown[] } = { type: 'blockquote', blocks: [] }
+    let cur = deep
+    for (let i = 0; i < 200; i++) {
+      const next = { type: 'blockquote', blocks: [] as unknown[] }
+      cur.blocks.push(next)
+      cur = next
+    }
+    cur.blocks.push({ type: 'paragraph', text: 'buried' })
+    expect(() => extractRichMessageText({ blocks: [deep] })).not.toThrow()
+  })
+})

package/telegram-plugin/tests/gateway-handler-registration-wiring.test.ts

@@ -107,6 +107,7 @@ const GOLDEN_REGISTRATIONS: readonly string[] = [
   'on:message:checklist_tasks_done',
   'on:message:checklist_tasks_added',
   'on:message:pinned_message',
+  'on:message:rich_message',
   'helper:installUnhandledMessageCatchAll',
   'on:message_reaction',
   'catch',

package/telegram-plugin/tests/narration-leak-3513.test.ts

@@ -0,0 +1,352 @@
+/**
+ * narration-leak-3513.test.ts — outcome-asserting regression suite for
+ * switchroom#3513 ("agent intent-narration leaks into the final Telegram reply
+ * as a real chat message").
+ *
+ * The single-surface invariant: every trailing plain-text block is assigned once
+ * to exactly one surface — delivered chat answer / ephemeral progress card /
+ * suppressed — by ONE shared classifier, and NO delivery path (E1 turn-flush,
+ * E2 quiescence, E3 captured-prose bridge, E4 outbox sweep) ever emits a block
+ * classified as structural narration; the one genuine unsent answer still
+ * delivers exactly once.
+ *
+ * Every test here asserts an OUTCOME (was the narration delivered? was the real
+ * answer delivered?), not merely that a code path ran, and each is written to be
+ * RED on the pre-fix code (which had two hand-synced regex classifiers and no
+ * structural/ledger guard).
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  isStructuralNarration,
+  isNarrationBlock,
+  ledgerHashHex,
+  SUBSTANTIVE_MIN_CHARS,
+} from '../hooks/narration-classify.mjs'
+import { selectFlushDeliveryText, FLUSH_SUBSTANTIVE_MIN_CHARS } from '../turn-flush-safety.js'
+import { decideOutboxSweep } from '../outbox.js'
+import { decideCapturedProseDelivery } from '../silent-end.js'
+import { appendShownBlock, isShownBlock, readShownHashes } from '../shown-ledger.js'
+import { NarrativeFlushController } from '../narrative-flush.js'
+
+const NARRATION = 'Now let me check the gateway logs to see what happened.'
+const REAL_ANSWER =
+  'The gateway crashed because the outbox sweep tried to deliver a record whose ' +
+  'turnNonce had already been journaled, and the dedup cache had been evicted, so ' +
+  'the exactly-once guard fell back to the text-dedup path which returned false. ' +
+  'The fix is to check the shown-ledger before the quiet window, not after.'
+
+// A substantive real message that the model happens to precede a NON-delivering
+// tool with (react / pin / typing). Must NOT be treated as narration.
+const SUBSTANTIVE_BEFORE_REACT = REAL_ANSWER
+
+describe('shared classifier — the ONE source of truth (correction 2 + 3)', () => {
+  it('short/narration-shaped block followed by a tool IS structural narration', () => {
+    expect(isStructuralNarration(NARRATION, true)).toBe(true)
+    expect(isStructuralNarration('On it — pulling the numbers…', true)).toBe(true)
+    expect(isStructuralNarration('', true)).toBe(true)
+  })
+
+  it('SUBSTANTIVE block followed by a tool is NOT narration (react/pin/typing still delivers)', () => {
+    // The #3237 asymmetry: a real answer preceding react/pin/typing must deliver.
+    expect(SUBSTANTIVE_BEFORE_REACT.length).toBeGreaterThan(SUBSTANTIVE_MIN_CHARS)
+    expect(isStructuralNarration(SUBSTANTIVE_BEFORE_REACT, true)).toBe(false)
+  })
+
+  it('a terminal block (nothing followed it) is NEVER structural narration', () => {
+    // followedByToolUse false OR absent → never structural (could be the answer).
+    expect(isStructuralNarration(NARRATION, false)).toBe(false)
+    expect(isStructuralNarration(NARRATION, undefined)).toBe(false)
+    expect(isStructuralNarration('Yes.', false)).toBe(false)
+  })
+
+  it('FLUSH_SUBSTANTIVE_MIN_CHARS is wired to the shared constant (no drift)', () => {
+    expect(FLUSH_SUBSTANTIVE_MIN_CHARS).toBe(SUBSTANTIVE_MIN_CHARS)
+  })
+})
+
+describe('E1/E2 turn-flush — narration never becomes the delivered answer', () => {
+  it('drops a trailing narration block that a tool followed, keeps the real answer', () => {
+    const out = selectFlushDeliveryText([REAL_ANSWER, NARRATION], [false, true])
+    expect(out).toContain(REAL_ANSWER)
+    expect(out).not.toContain(NARRATION)
+  })
+
+  it('drops a SHORT non-regex block a tool followed (the class the old regex missed)', () => {
+    // "The logs show three errors." matches NO wording heuristic (no opener, no
+    // trailing ellipsis/colon) — the pre-fix regex-only classifier would have
+    // DELIVERED it. It is structural narration only because a tool followed it
+    // AND it is under the substantive floor. This is the core #3513 discriminator.
+    const shortNonRegex = 'The logs show three errors.'
+    expect(isNarrationBlock(shortNonRegex)).toBe(false)
+    expect(shortNonRegex.length).toBeLessThan(SUBSTANTIVE_MIN_CHARS)
+    const out = selectFlushDeliveryText([REAL_ANSWER, shortNonRegex], [false, true])
+    expect(out).toContain(REAL_ANSWER)
+    expect(out).not.toContain(shortNonRegex)
+  })
+
+  it('zero-reply, narration-only turn (all blocks followed by tools) flushes NOTHING', () => {
+    const out = selectFlushDeliveryText(['Let me pull the logs.', NARRATION], [true, true])
+    expect(out).toBe('')
+  })
+
+  it('a genuine terminal answer with no provenance still flushes (fail-open)', () => {
+    // Provenance-less single block — conservative: deliver it.
+    expect(selectFlushDeliveryText(['Here are the results:'])).toBe('Here are the results:')
+  })
+
+  it('a SUBSTANTIVE answer followed by a non-delivering tool STILL flushes', () => {
+    const out = selectFlushDeliveryText([SUBSTANTIVE_BEFORE_REACT], [true])
+    expect(out).toBe(SUBSTANTIVE_BEFORE_REACT)
+  })
+})
+
+describe('E4 outbox sweep — a ledger-marked block is never re-delivered (correction 1)', () => {
+  const base = {
+    now: 10_000_000,
+    deliveredNonces: new Set<string>(),
+    textAlreadyDelivered: false,
+    routable: true,
+    quietMs: 0,
+  }
+
+  it('skips a record whose text was shown on the ephemeral card', () => {
+    const d = decideOutboxSweep({
+      ...base,
+      record: { turnNonce: 'c:_#5', text: NARRATION, createdAt: 0 },
+      shownLedgerHit: true,
+    })
+    expect(d.action).toBe('skip-ephemeral-shown')
+    expect(d.text).toBeUndefined()
+  })
+
+  it('delivers a real answer that was NOT shown on the card', () => {
+    const d = decideOutboxSweep({
+      ...base,
+      record: { turnNonce: 'c:_#5', text: REAL_ANSWER, createdAt: base.now },
+      shownLedgerHit: false,
+    })
+    expect(d.action).toBe('send')
+    expect(d.text).toContain(REAL_ANSWER)
+  })
+
+  it('the ledger hit is checked AFTER journaled (exactly-once wins) but BEFORE quiet', () => {
+    // Already-journaled record short-circuits regardless of ledger state.
+    const journaled = decideOutboxSweep({
+      ...base,
+      deliveredNonces: new Set(['c:_#5']),
+      record: { turnNonce: 'c:_#5', text: NARRATION, createdAt: 0 },
+      shownLedgerHit: true,
+    })
+    expect(journaled.action).toBe('skip-journaled')
+  })
+})
+
+describe('E4 outbox sweep × durable shown-ledger — end-to-end wiring (correction 1 + 4)', () => {
+  // Integration test: exercise the REAL ledger round-trip (append/markShown +
+  // isShownBlock/isBlockShown) keyed by turnNonce THROUGH the outbox-sweep
+  // decision, mirroring the production composition at
+  // gateway/outbox-sweep.ts:122 (`shownLedgerHit: isShownBlock(record.turnNonce,
+  // record.text, deps.stateDir)`). Unlike the unit tests above that pass a
+  // hand-set `shownLedgerHit` boolean, this drives the flag FROM the durable
+  // ledger file — so if the ledger wiring is removed (append becomes a no-op, or
+  // decideOutboxSweep stops consulting the hit), the skip assertion goes RED.
+  const base = {
+    now: 10_000_000,
+    deliveredNonces: new Set<string>(),
+    textAlreadyDelivered: false,
+    routable: true,
+    quietMs: 0,
+  }
+
+  it('a block marked shown for its turnNonce is skipped; a non-shown block delivers', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'outbox-ledger-'))
+    try {
+      const nonce = 'c:_#42'
+      // markShown: the mid-turn narrative paint appended this block to the
+      // durable ledger for THIS turn's nonce.
+      appendShownBlock(nonce, NARRATION, dir)
+
+      // Sweep the SAME (nonce, text): the production wiring derives the flag from
+      // the ledger, so the record must be skipped as ephemeral-shown.
+      const shown = decideOutboxSweep({
+        ...base,
+        record: { turnNonce: nonce, text: NARRATION, createdAt: 0 },
+        shownLedgerHit: isShownBlock(nonce, NARRATION, dir),
+      })
+      expect(isShownBlock(nonce, NARRATION, dir)).toBe(true)
+      expect(shown.action).toBe('skip-ephemeral-shown')
+      expect(shown.text).toBeUndefined()
+
+      // A NON-shown block (the genuine unsent answer, never appended) still
+      // delivers exactly once — the ledger miss falls through to send.
+      const notShown = decideOutboxSweep({
+        ...base,
+        record: { turnNonce: nonce, text: REAL_ANSWER, createdAt: base.now },
+        shownLedgerHit: isShownBlock(nonce, REAL_ANSWER, dir),
+      })
+      expect(isShownBlock(nonce, REAL_ANSWER, dir)).toBe(false)
+      expect(notShown.action).toBe('send')
+      expect(notShown.text).toContain(REAL_ANSWER)
+
+      // Cross-turn isolation: the SAME text under a DIFFERENT turnNonce is not a
+      // ledger hit, so it delivers (no cross-turn suppression through the sweep).
+      const otherTurn = decideOutboxSweep({
+        ...base,
+        record: { turnNonce: 'c:_#43', text: NARRATION, createdAt: base.now },
+        shownLedgerHit: isShownBlock('c:_#43', NARRATION, dir),
+      })
+      expect(otherTurn.action).toBe('send')
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('E3 captured-prose bridge — a shown block is refused (correction 1)', () => {
+  /** Write a real silent-end-pending.json into a temp stateDir. */
+  function withState(text: string, run: (deps: { stateDir: string }) => void): void {
+    const dir = mkdtempSync(join(tmpdir(), 'silent-end-'))
+    try {
+      writeFileSync(
+        join(dir, 'silent-end-pending.json'),
+        JSON.stringify({
+          chatId: 'c',
+          threadId: null,
+          turnKey: 'c:_',
+          turnId: 'c:_#5',
+          pendingText: text,
+          retryCount: 0,
+          timestamp: Date.now(),
+        }),
+      )
+      run({ stateDir: dir })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  }
+
+  it('refuses to bridge prose already surfaced on the card', () => {
+    withState(REAL_ANSWER, ({ stateDir }) => {
+      const d = decideCapturedProseDelivery(
+        { turnKey: 'c:_', turnId: 'c:_#5', minChars: 10 },
+        { stateDir, isBlockShown: () => true },
+      )
+      expect(d.deliver).toBe(false)
+      expect(d.reason).toBe('ephemeral-shown')
+    })
+  })
+
+  it('bridges a genuine unsent answer that was NOT shown (empty-capture divergence)', () => {
+    withState(REAL_ANSWER, ({ stateDir }) => {
+      const d = decideCapturedProseDelivery(
+        { turnKey: 'c:_', turnId: 'c:_#5', minChars: 10 },
+        { stateDir, isBlockShown: () => false },
+      )
+      expect(d.deliver).toBe(true)
+      if (d.deliver) expect(d.text).toContain(REAL_ANSWER)
+    })
+  })
+})
+
+describe('durable shown-ledger — round trip + envelope-less no-op (correction 4)', () => {
+  it('marks then recognises a structural narration block for its turnNonce', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'shown-ledger-'))
+    try {
+      appendShownBlock('c:_#7', NARRATION, dir)
+      expect(isShownBlock('c:_#7', NARRATION, dir)).toBe(true)
+      // A different turn's nonce must NOT match (no cross-turn suppression).
+      expect(isShownBlock('c:_#8', NARRATION, dir)).toBe(false)
+      // The stored hash matches the shared classifier hash.
+      expect(readShownHashes('c:_#7', dir).has(ledgerHashHex(NARRATION))).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('a null turnNonce (envelope-less handback/cron) is never written', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'shown-ledger-'))
+    try {
+      appendShownBlock(null, NARRATION, dir)
+      expect(isShownBlock(null, NARRATION, dir)).toBe(false)
+      expect(readShownHashes(null, dir).size).toBe(0)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+/** Fake at-most-one scheduler mirroring the real unref'd setTimeout wiring. */
+class FakeScheduler {
+  private fn: (() => void) | null = null
+  arm(fn: () => void): void {
+    this.fn = fn
+  }
+  disarm(): void {
+    this.fn = null
+  }
+  fire(): void {
+    const fn = this.fn
+    this.fn = null
+    fn?.()
+  }
+}
+
+describe('narrative controller — durable-mark ONLY mid-turn narration (correction 4)', () => {
+  function make() {
+    const show = vi.fn<[string], void>()
+    const retractShown = vi.fn<[string], void>()
+    const markDurableNarration = vi.fn<[string], void>()
+    const scheduler = new FakeScheduler()
+    const ctrl = new NarrativeFlushController(
+      { show, retractShown, markDurableNarration },
+      scheduler,
+      250,
+    )
+    return { ctrl, show, markDurableNarration, scheduler }
+  }
+
+  it('marks a block SHOWN mid-turn because another narration block followed it (stage)', () => {
+    const { ctrl, show, markDurableNarration } = make()
+    ctrl.stage('First, let me check the logs…')
+    ctrl.stage('Now scanning the outbox…') // lookahead → shows + marks the first
+    expect(show).toHaveBeenCalledWith('First, let me check the logs…')
+    expect(markDurableNarration).toHaveBeenCalledWith('First, let me check the logs…')
+  })
+
+  it('marks a block SHOWN mid-turn because a tool followed it (resolveOnTool)', () => {
+    const { ctrl, markDurableNarration } = make()
+    ctrl.stage(NARRATION)
+    ctrl.resolveOnTool('Bash', { command: 'grep' }) // non-reply tool lookahead
+    expect(markDurableNarration).toHaveBeenCalledWith(NARRATION)
+  })
+
+  it('NEVER marks the timer-painted terminal block (could be the real answer)', () => {
+    const { ctrl, show, markDurableNarration, scheduler } = make()
+    ctrl.stage(REAL_ANSWER)
+    scheduler.fire() // timer paints the LAST block early
+    expect(show).toHaveBeenCalledWith(REAL_ANSWER)
+    expect(markDurableNarration).not.toHaveBeenCalled()
+  })
+
+  it('NEVER marks the turn-end paint (terminal, could be the real answer)', () => {
+    const { ctrl, show, markDurableNarration } = make()
+    ctrl.stage(REAL_ANSWER)
+    ctrl.flushAtTurnEnd('') // no reply delivered → shows trailing prose, but never marks
+    expect(show).toHaveBeenCalledWith(REAL_ANSWER)
+    expect(markDurableNarration).not.toHaveBeenCalled()
+  })
+
+  it('does NOT mark a SUBSTANTIVE block even mid-turn (substance-gated, correction 3)', () => {
+    const { ctrl, markDurableNarration } = make()
+    ctrl.stage(SUBSTANTIVE_BEFORE_REACT)
+    ctrl.resolveOnTool('react', { emoji: '👍' }) // non-delivering tool
+    // Followed by a tool, but substantive → not structural narration → not marked,
+    // so a backstop could still deliver it if it were the genuine unsent answer.
+    expect(markDurableNarration).not.toHaveBeenCalled()
+  })
+})