switchroom 0.19.14 → 0.19.16

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()
+  })
+})

package/telegram-plugin/tests/outbox-sweep-listen-button.test.ts

@@ -0,0 +1,253 @@
+/**
+ * Regression: switchroom #3502 — the durable-outbox safety net dropped the 🔊
+ * Listen button from a net-delivered final answer.
+ *
+ * PR #3502 / commit 1a531ebb added the outbox-sweep deliverer, which sent the
+ * captured final answer via a RAW `bot.api.sendMessage` with no voice-out
+ * resolution — so any answer the net delivered lost the Listen button that the
+ * normal `sendReply` path injects. The fix threads a shared `planListenButton`
+ * decision into the sweep's chunked send (`createOutboxSend`) so a net-delivered
+ * answer is indistinguishable from a normally-delivered one.
+ *
+ * These tests assert OUTCOMES, not code paths:
+ *  - the delivered message actually carries the Listen keyboard when kokoro
+ *    on-demand voice-out is enabled;
+ *  - it does NOT when the agent supplied its own keyboard, when the TTS text is
+ *    empty, or when voice-out is not kokoro-on-demand.
+ * A test that only walked the code without asserting `reply_markup` on the sent
+ * message would not fail on the pre-fix RAW-send bug, so we assert the exact
+ * bytes handed to `sendMessage`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createOutboxSend } from '../gateway/outbox-sweep.js'
+import { makeOutboxListenMarkupResolver } from '../gateway/outbox-listen-markup.js'
+import {
+  planListenButton,
+  type ListenButtonVoiceOutPlan,
+} from '../voice-ondemand.js'
+
+const kokoroOnDemand: ListenButtonVoiceOutPlan = {
+  engine: 'kokoro',
+  speed: 1.1,
+  replyMode: 'on-demand',
+  ttsChunks: ['the spoken answer'],
+}
+
+// A passthrough retry that simply invokes the send fn once (no flood/thread
+// fallback needed for the unit under test).
+const passthroughRetry = <U>(fn: () => Promise<U>): Promise<U> => fn()
+
+function fakeBot() {
+  const calls: Array<{ chatId: string; text: string; opts: Record<string, unknown> }> = []
+  let n = 100
+  return {
+    calls,
+    api: {
+      sendMessage: async (chatId: string, text: string, opts: object) => {
+        calls.push({ chatId, text, opts: opts as Record<string, unknown> })
+        return { message_id: n++ }
+      },
+    },
+  }
+}
+
+describe('planListenButton — shared Listen-button decision', () => {
+  it('injects for kokoro on-demand with non-empty TTS and no agent keyboard', () => {
+    const plan = planListenButton({ voiceOutPlan: kokoroOnDemand, rawKeyboard: undefined })
+    expect(plan).not.toBeNull()
+    expect(plan!.replyMarkup.inline_keyboard[0]![0]!.text).toBe('🔊 Listen')
+    expect(plan!.replyMarkup.inline_keyboard[0]![0]!.callback_data).toBe(`voice:${plan!.token}`)
+    expect(plan!.payload.text).toBe('the spoken answer')
+    expect(plan!.payload.speed).toBe(1.1)
+  })
+
+  it('does NOT inject when the agent supplied its own keyboard (collision gate)', () => {
+    const plan = planListenButton({
+      voiceOutPlan: kokoroOnDemand,
+      rawKeyboard: [[{ text: 'Approve', callback_data: 'ok' }]],
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('does NOT inject when the TTS text is empty (empty-TTS guard)', () => {
+    const plan = planListenButton({
+      voiceOutPlan: { ...kokoroOnDemand, ttsChunks: [''] },
+      rawKeyboard: undefined,
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('does NOT inject for openai on-demand (taps would dead-end on local sidecar)', () => {
+    const plan = planListenButton({
+      voiceOutPlan: { ...kokoroOnDemand, engine: 'openai' },
+      rawKeyboard: undefined,
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('does NOT inject when reply_mode is not on-demand', () => {
+    const plan = planListenButton({
+      voiceOutPlan: { ...kokoroOnDemand, replyMode: 'voice+text' },
+      rawKeyboard: undefined,
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('returns null when there is no voice-out plan', () => {
+    expect(planListenButton({ voiceOutPlan: null, rawKeyboard: undefined })).toBeNull()
+  })
+})
+
+describe('createOutboxSend — net-delivered answer carries the Listen button (#3502)', () => {
+  it('attaches the Listen keyboard as reply_markup when voice-out on-demand is enabled', async () => {
+    const bot = fakeBot()
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: () => planListenButton({ voiceOutPlan: kokoroOnDemand, rawKeyboard: undefined })!.replyMarkup,
+    })
+
+    await send('123', null, 'the final answer')
+
+    expect(bot.calls).toHaveLength(1)
+    const markup = bot.calls[0]!.opts.reply_markup as
+      | { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> }
+      | undefined
+    expect(markup).toBeDefined()
+    expect(markup!.inline_keyboard[0]![0]!.text).toBe('🔊 Listen')
+    // Guards against the pre-fix RAW send: no button would have been attached.
+  })
+
+  it('attaches the keyboard to the LAST chunk only (final visible message)', async () => {
+    const bot = fakeBot()
+    const markup = { inline_keyboard: [[{ text: '🔊 Listen', callback_data: 'voice:abcd1234' }]] }
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: () => markup,
+    })
+
+    // > 4000 chars → two chunks.
+    await send('123', null, 'x'.repeat(4500))
+
+    expect(bot.calls).toHaveLength(2)
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+    expect(bot.calls[1]!.opts.reply_markup).toEqual(markup)
+  })
+
+  it('delivers plain (no reply_markup) when the resolver returns undefined', async () => {
+    const bot = fakeBot()
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: () => undefined,
+    })
+
+    await send('123', 42, 'plain answer')
+
+    expect(bot.calls).toHaveLength(1)
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+    // thread id still threaded through
+    expect(bot.calls[0]!.opts.message_thread_id).toBe(42)
+  })
+
+  it('delivers plain when no resolver is wired at all (legacy behaviour preserved)', async () => {
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry })
+
+    await send('123', null, 'legacy answer')
+
+    expect(bot.calls).toHaveLength(1)
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+  })
+
+  it('empty text sends NOTHING and returns undefined (no empty-message retry wedge)', async () => {
+    // Telegram rejects an empty message body; a stray '' chunk would throw
+    // every sweep tick and wedge the record in a permanent retry. The send
+    // must short-circuit instead of calling sendMessage.
+    const bot = fakeBot()
+    const resolverCalls: string[] = []
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: (_c, _t, text) => {
+        resolverCalls.push(text)
+        return undefined
+      },
+    })
+
+    const result = await send('123', null, '')
+
+    expect(result).toBeUndefined()
+    expect(bot.calls).toHaveLength(0)
+    // No point resolving a Listen button for a body we never send.
+    expect(resolverCalls).toEqual([])
+  })
+})
+
+describe('gateway wiring — makeOutboxListenMarkupResolver end-to-end (#3502)', () => {
+  // Pins the ACTUAL gateway resolver: the sweep must obtain the Listen keyboard
+  // AND persist the tap token when kokoro on-demand voice-out is enabled. If a
+  // future change re-severs the sweep delivery from voice-out resolution (the
+  // PR #3502 / commit 1a531ebb raw-sendMessage regression), the delivered
+  // message loses its button and these assertions go red.
+  it('a net-delivered answer carries the button and the tap token is cached', async () => {
+    const cached: Array<{ token: string; text: string }> = []
+    const enqueued: string[] = []
+    const resolve = makeOutboxListenMarkupResolver({
+      resolveVoiceOutPlan: () => kokoroOnDemand,
+      cachePut: (token, payload) => cached.push({ token, text: payload.text }),
+      eagerVoiceEnabled: () => true,
+      enqueuePreSynth: (j) => enqueued.push(j.token),
+    })
+
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry, resolveReplyMarkup: resolve })
+    await send('123', null, 'the final answer the net is delivering')
+
+    const markup = bot.calls[0]!.opts.reply_markup as
+      | { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> }
+      | undefined
+    expect(markup).toBeDefined()
+    const btn = markup!.inline_keyboard[0]![0]!
+    expect(btn.text).toBe('🔊 Listen')
+    // The token on the button must be the one cached + eagerly pre-synthesized,
+    // so the tap resolves to real audio (not a dead token).
+    const token = btn.callback_data.replace('voice:', '')
+    expect(cached).toEqual([{ token, text: 'the spoken answer' }])
+    expect(enqueued).toEqual([token])
+  })
+
+  it('resolves to no button (and caches nothing) when voice-out is off', async () => {
+    const cached: string[] = []
+    const resolve = makeOutboxListenMarkupResolver({
+      resolveVoiceOutPlan: () => null,
+      cachePut: (token) => cached.push(token),
+      eagerVoiceEnabled: () => true,
+      enqueuePreSynth: () => {},
+    })
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry, resolveReplyMarkup: resolve })
+    await send('123', null, 'plain answer, voice-out disabled')
+
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+    expect(cached).toEqual([])
+  })
+
+  it('skips eager pre-synth when the kill switch is off but still shows the button', async () => {
+    const enqueued: string[] = []
+    const resolve = makeOutboxListenMarkupResolver({
+      resolveVoiceOutPlan: () => kokoroOnDemand,
+      cachePut: () => {},
+      eagerVoiceEnabled: () => false,
+      enqueuePreSynth: (j) => enqueued.push(j.token),
+    })
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry, resolveReplyMarkup: resolve })
+    await send('123', null, 'answer')
+
+    expect(bot.calls[0]!.opts.reply_markup).toBeDefined()
+    expect(enqueued).toEqual([])
+  })
+})