switchroom 0.19.14 → 0.19.16

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -683,13 +683,36 @@ describe('selectFlushDeliveryText — deliver the terminal answer, strip only na
     expect(out).toBe('Here are the results:')
   })
 
-  it('decideTurnFlush delivers the narrowed answer, not the whole blob', () => {
+  // #3513 follow-up — decideTurnFlush now routes through the deterministic
+  // `selectBackstopDelivery` coalescer, NOT the wording heuristic. With NO
+  // structural provenance (no `capturedBlockMeta`, so no block was followed by a
+  // turn-continuing tool_use) EVERY block is part of the terminal run and is
+  // delivered joined — fail OPEN, never drop. The wording-based narration strip
+  // is gone on the backstop path (it was provably incomplete; #3513). When the
+  // structural signal IS present it, and only it, suppresses.
+  it('decideTurnFlush delivers the full terminal run when NO tool-follow provenance is present (fail-open)', () => {
     const decision = decideTurnFlush({
       chatId: 'chat1',
       replyCalled: false,
       capturedText: ['Let me check.', 'Now let me compose the reply.', answer],
     })
     expect(decision.kind).toBe('flush')
+    if (decision.kind === 'flush') {
+      expect(decision.text).toBe(`Let me check.\n\nNow let me compose the reply.\n\n${answer}`)
+    }
+  })
+
+  it('decideTurnFlush suppresses tool-followed blocks UNCONDITIONALLY (structural provenance drives the coalescer)', () => {
+    // The first two blocks were each followed by a turn-continuing tool_use →
+    // intra-turn narration → suppressed with NO length/wording gate. Only the
+    // terminal answer (not tool-followed) survives.
+    const decision = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: ['Let me check.', 'Now let me compose the reply.', answer],
+      capturedBlockMeta: [true, true, false],
+    })
+    expect(decision.kind).toBe('flush')
     if (decision.kind === 'flush') {
       expect(decision.text).toBe(answer)
       expect(decision.text).not.toContain('Let me check')
@@ -832,11 +855,20 @@ describe('selectFlushDeliveryText — structural provenance (followedByToolUse)
     // trailing ellipsis/colon — so only the structural flag could strip it.
     const wrapUp = 'Saved that to memory.'
     // meta[0]=true (a memory tool_use followed the real answer), [1]=false.
+    // The STANDALONE `selectFlushDeliveryText` (the old #3237 substance-gated
+    // function, unchanged and still exported) keeps the substantial block.
     const out = selectFlushDeliveryText([realAnswer, wrapUp], [true, false])
     expect(out).toBe(`${realAnswer}\n\n${wrapUp}`)
     expect(out).toContain('The migration completed cleanly')
 
-    // End-to-end through decideTurnFlush.
+    // #3513 follow-up — decideTurnFlush now routes through
+    // `selectBackstopDelivery`, which suppresses a tool-followed block
+    // UNCONDITIONALLY (no substantive-floor carve-out). This DELIBERATELY
+    // overturns #3237's substance-gate ON THE BACKSTOP PATH: a real answer the
+    // model followed with a turn-continuing tool_use is treated as intra-turn
+    // and excluded; only the terminal (non-tool-followed) block is delivered.
+    // The deterministic contract is "the terminal run wins" — the model keeps
+    // its answer by ending on it or calling the reply tool.
     const decision = decideTurnFlush({
       chatId: 'chat1',
       replyCalled: false,
@@ -845,7 +877,7 @@ describe('selectFlushDeliveryText — structural provenance (followedByToolUse)
     })
     expect(decision.kind).toBe('flush')
     if (decision.kind === 'flush') {
-      expect(decision.text).toBe(`${realAnswer}\n\n${wrapUp}`)
+      expect(decision.text).toBe(wrapUp)
     }
   })
 

package/telegram-plugin/tests/voice-normalize-text.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { normalizeForSpeech } from '../voice-normalize-text.js'
+import { normalizeForSpeech, decodeHtmlEntities } from '../voice-normalize-text.js'
 
 describe('normalizeForSpeech — reported markdown/symbol cases', () => {
   it('drops stray tildes (never spoken as "tilde")', () => {
@@ -254,3 +254,84 @@ describe('normalizeForSpeech — conservative, does not mangle real words', () =
     expect(normalizeForSpeech('   \n  ')).toBe('')
   })
 })
+
+describe('normalizeForSpeech — backslash escapes & HTML entities (voice trash)', () => {
+  it('strips a literal backslash-b (\\b) so it is never spoken as "backslash b"', () => {
+    // The exact operator report: the regex/escape "\b" was read as "slash b".
+    const out = normalizeForSpeech('the regex \\b word boundary')
+    expect(out).toBe('the regex b word boundary')
+    expect(out).not.toContain('\\')
+  })
+
+  it('unescapes MarkdownV2 punctuation escapes without leaving backslashes', () => {
+    expect(normalizeForSpeech('done\\. next\\! wait\\-')).toBe('done. next! wait-')
+    expect(normalizeForSpeech('a \\* b')).not.toContain('\\')
+  })
+
+  it('an escaped emphasis marker collapses to the inner word, not a backslash', () => {
+    expect(normalizeForSpeech('Use \\*literal\\* here')).toBe('Use literal here')
+  })
+
+  it('drops a Windows-path-style backslash run (C:\\build)', () => {
+    expect(normalizeForSpeech('path C:\\build\\out done')).toBe('path C:buildout done')
+  })
+
+  it('decodes HTML entities so & / < are not read as "amp" / "lt"', () => {
+    expect(normalizeForSpeech('Tom & Jerry')).toBe('Tom and Jerry')
+    expect(normalizeForSpeech('5 &lt; 10 &gt; 3')).toBe('5 < 10 > 3')
+    expect(normalizeForSpeech('it&#39;s here')).toBe("it's here")
+  })
+
+  it('produces clean plain speech for a rich mixed reply (end-to-end)', () => {
+    const reply =
+      '**Bold** and `code\\b` and a [label](https://example.com/x) ' +
+      'with Tom &amp; Jerry and a regex \\b\\.'
+    const out = normalizeForSpeech(reply)
+    expect(out).not.toContain('\\')
+    expect(out).not.toContain('`')
+    expect(out).not.toContain('*')
+    expect(out).not.toContain('&amp;')
+    expect(out).not.toContain('example.com')
+    expect(out).toContain('label')
+    expect(out).toContain('Tom and Jerry')
+  })
+
+  it('is idempotent: a second pass finds no backslashes/entities to change', () => {
+    const reply = 'a \\b and Tom &amp; Jerry \\. end'
+    const once = normalizeForSpeech(reply)
+    expect(normalizeForSpeech(once)).toBe(once)
+  })
+})
+
+describe('normalizeForSpeech — review findings (fixpoint decode, metachar, nits)', () => {
+  it('L2 parity: a double-encoded entity decodes to a fixpoint (depth-independent)', () => {
+    // Single decode and double decode must land on the SAME spoken char so the
+    // immediate voice-out and the lazy Listen tap never diverge.
+    const single = normalizeForSpeech('&amp;amp;lt;')
+    const doubled = normalizeForSpeech(normalizeForSpeech('&amp;amp;lt;'))
+    expect(single).toBe('<')
+    expect(doubled).toBe('<')
+    expect(normalizeForSpeech('&amp;amp;amp;')).toBe('&')
+  })
+
+  it('L1: an entity that decodes to a line-leading metachar keeps a spoken form', () => {
+    // &#35; → '#'. Naively re-fed to the heading stripper it would vanish; the
+    // user escaped it on purpose, so it must survive as spoken "hash".
+    expect(normalizeForSpeech('&#35; Heading')).toBe('hash Heading')
+    expect(normalizeForSpeech('2 &#42; 3')).toBe('2 asterisk 3')
+  })
+
+  it('nit: a dangling trailing backslash is dropped, never spoken', () => {
+    expect(normalizeForSpeech('ends here\\')).toBe('ends here')
+    expect(normalizeForSpeech('ends here\\')).not.toContain('\\')
+  })
+
+  it('nit: &#92; decodes to a backslash which is then stripped (no trash)', () => {
+    expect(normalizeForSpeech('X&#92;Y')).toBe('XY')
+    expect(normalizeForSpeech('X&#92;Y')).not.toContain('\\')
+  })
+
+  it('fixpoint does not over-decode entity-less text (Q&A stays literal)', () => {
+    expect(decodeHtmlEntities('Q&A test')).toBe('Q&A test')
+  })
+})

package/telegram-plugin/tts-normalize.ts

@@ -38,6 +38,8 @@
  *     ~5 → "about 5", > blockquote markers dropped.
  */
 
+import { decodeHtmlEntities, stripBackslashEscapes } from './voice-normalize-text'
+
 const NULL = '\x00'
 const INLINE_PH = `${NULL}TN_INLINE`
 
@@ -197,6 +199,16 @@ export function normalizeForTts(text: string): string {
 
   let s = text.replace(/\r\n?/g, '\n')
 
+  // -- HTML entities → char, then backslash escapes → the escaped char. The
+  //    last line of defence at the /tts body build: the Listen lazy path and
+  //    the pre-synth queue can synthesize from cache entries that predate the
+  //    normalizeForSpeech coverage, so these must be stripped here too. Both
+  //    are idempotent — if normalizeForSpeech already ran there is nothing
+  //    left to decode/unescape. Without this the engine speaks `\b` as
+  //    "backslash b" and `&` as "amp".
+  s = decodeHtmlEntities(s)
+  s = stripBackslashEscapes(s)
+
   // -- Code fences → spoken placeholder (before anything can see contents).
   s = s.replace(/(^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n[ \t]*\2[ \t]*(?=\n|$)/g, '$1code block omitted.')
   s = s.replace(/(^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*$/g, '$1code block omitted.')

package/telegram-plugin/turn-flush-safety.ts

@@ -19,6 +19,13 @@
  * and can be set to `0` / `false` / `off` to disable without a rebuild.
  */
 
+import {
+  isNarrationBlock,
+  isStructuralNarration,
+  selectBackstopDelivery,
+  SUBSTANTIVE_MIN_CHARS,
+} from './hooks/narration-classify.mjs'
+
 const SILENT_MARKERS = new Set(['NO_REPLY', 'HEARTBEAT_OK'])
 // Small buffer so `NO_REPLY.` with a stray period still counts as silent.
 const SILENT_MARKER_MAX_LEN = Math.max(
@@ -134,7 +141,7 @@ export function endsWithSilentMarker(text: string | undefined): boolean {
  * `hooks/silent-end-scan.mjs` — the same bar the codebase uses everywhere to
  * recognise "this text block is a real answer, not a short narration/closer".
  */
-export const FLUSH_SUBSTANTIVE_MIN_CHARS = 200
+export const FLUSH_SUBSTANTIVE_MIN_CHARS = SUBSTANTIVE_MIN_CHARS
 
 /**
  * Pick the text a turn-flush should actually DELIVER from the captured
@@ -203,9 +210,33 @@ export function selectFlushDeliveryText(
     .map((b, i) => ({ text: b.trim(), followedByToolUse: followedByToolUse?.[i] }))
     .filter(c => c.text.length > 0)
   if (candidates.length === 0) return ''
-  if (candidates.length === 1) return candidates[0].text
-  const answer = candidates[candidates.length - 1].text
-  const preceding = candidates.slice(0, -1)
+
+  // #3513 — the STRUCTURAL rule now applies to the TERMINAL block too, not only
+  // preceding blocks. A lone trailing block that a `tool_use` FOLLOWED (the
+  // model kept acting after writing it) is intra-turn narration by construction,
+  // never the terminal answer — so it must not be delivered as one. This is the
+  // primary fix for the observed leak ("Now checking the gateway logs…"),
+  // wording-independent where the opener regex fails. It stays substance-gated
+  // (correction 3): only a SHORT or narration-shaped block that a tool followed
+  // is suppressed — a SUBSTANTIVE, non-narration block followed by a
+  // non-delivering tool (react / pin / typing / edit) is NOT structural
+  // narration and still delivers.
+  //
+  // Only the STRUCTURAL signal (`followedByToolUse === true`) may strip the
+  // terminal block; the opener/trailer heuristic remains a residual tie-breaker
+  // for PRECEDING blocks only, so a provenance-less single block still delivers
+  // verbatim (#3276 finding 7 — a colon-terminated line that IS the whole answer
+  // is never dropped).
+  let cs = candidates
+  while (cs.length > 1 && isStructuralNarration(cs[cs.length - 1].text, cs[cs.length - 1].followedByToolUse)) {
+    cs = cs.slice(0, -1)
+  }
+  if (cs.length === 1) {
+    return isStructuralNarration(cs[0].text, cs[0].followedByToolUse) ? '' : cs[0].text
+  }
+
+  const answer = cs[cs.length - 1].text
+  const preceding = cs.slice(0, -1)
   // Deliver only the terminal answer when every earlier block is
   // intent-narration. Per block:
   //   - structural flag TRUE ⇒ a tool_use followed this block, but that alone
@@ -228,50 +259,15 @@ export function selectFlushDeliveryText(
         ? false
         : isNarrationBlock(c.text),
   )
-  return allNarration ? answer : candidates.map(c => c.text).join('\n\n')
+  return allNarration ? answer : cs.map(c => c.text).join('\n\n')
 }
 
-/**
- * Narration heuristic: a block that opens with a first-person "about to do X"
- * phrase the model emits BEFORE composing its real answer ("Let me check…",
- * "I'll look it up…", "Now let me…"). Deliberately NOT length-based — the
- * narration that shadowed the real answer in the observed bug was a LONG
- * (≥200-char) "Let me pull the numbers…" block, and short blocks are frequently
- * legitimate multi-paragraph answer content — so gating on length either drops a
- * short real answer or keeps a long narration. When earlier blocks don't match
- * this opener we keep the full joined text (never drop content we can't
- * confidently attribute to narration).
- */
-const NARRATION_OPENER =
-  /^(let me\b|lemme\b|i'?ll\b|i will\b|i am going to\b|i'?m going to\b|i'?m about to\b|going to\b|first,?\s+(?:let me|i'?ll|i will)\b|now,?\s+(?:let me|i'?ll|i will)\b|next,?\s+(?:let me|i'?ll|i will)\b|let'?s\b)/i
-
-/**
- * #3276 guard 8 — the `NARRATION_OPENER` regex alone misses common progress
- * narration that opens with a gerund/present-continuous verb and trails off
- * into an ellipsis or colon: "Checking now…", "Pulling the numbers:",
- * "Looking into that…". Relying on the opener regex leaked those blocks into
- * the delivered answer. This recognises a NON-terminal narration line
- * deterministically, WITHOUT re-gating on a min-char floor (a short real
- * answer like "Yes, done." must still deliver): a single short line that ends
- * with an ellipsis or a colon is progress narration, not the terminal answer.
- *
- * Kept conservative on purpose — only a SINGLE-line block (no internal
- * paragraph) under the substantive floor, ending in `…` / `...` / `:`, so a
- * genuine multi-paragraph answer that happens to end a paragraph with a colon
- * is never mistaken for narration.
- */
-const NARRATION_TRAILER = /(?:\.{3}|…|:)\s*$/
-
-function isTrailingNarrationLine(block: string): boolean {
-  const t = block.trim()
-  if (t.length === 0 || t.length >= FLUSH_SUBSTANTIVE_MIN_CHARS) return false
-  if (t.includes('\n')) return false
-  return NARRATION_TRAILER.test(t)
-}
-
-function isNarrationBlock(block: string): boolean {
-  return NARRATION_OPENER.test(block.trimStart()) || isTrailingNarrationLine(block)
-}
+// The narration heuristic (`isNarrationBlock` / openers / trailer) and the
+// structural rule (`isStructuralNarration`) now live in the ONE shared
+// classifier `hooks/narration-classify.mjs`, imported at the top of this file
+// and by the unbundled Stop hook (`hooks/silent-end-scan.mjs`) alike — so the
+// TS gateway side and the `.mjs` side can never drift (switchroom#3513
+// correction 2; retires the old "MUST stay in sync" hand-synced copies).
 
 export type FlushDecision =
   | { kind: 'flush'; text: string }
@@ -283,6 +279,11 @@ export type FlushSkipReason =
   | 'no-inbound-chat'
   | 'empty-text'
   | 'silent-marker'
+  // A prior BACKSTOP (E2 answer-ready flush, or an out-of-process E3/E4 machine
+  // across a crash/restart) already delivered this turn's answer — the durable
+  // exactly-once-among-backstops guard (#3513 follow-up, MF2). Set by the
+  // caller, not `decideTurnFlush`.
+  | 'already-delivered'
 
 export interface FlushDecisionInput {
   /** Inbound chat the turn was servicing. `null` means system-initiated /
@@ -375,14 +376,26 @@ export function decideTurnFlush(input: FlushDecisionInput): FlushDecision {
   // sentinel — treat the whole turn as intentionally silent rather than
   // flush the prose with the sentinel glued on.
   if (endsWithSilentMarker(joined)) return { kind: 'skip', reason: 'silent-marker' }
-  // Deliver only the substantive answer block, never the whole narration+answer
-  // blob (see `selectFlushDeliveryText`). The silent-marker / empty guards above
-  // still run on the full `joined` string so a partly-silent turn is classified
-  // correctly; only the DELIVERED text is narrowed to the answer.
-  return {
-    kind: 'flush',
-    text: selectFlushDeliveryText(input.capturedText, input.capturedBlockMeta),
+  // #3513 follow-up — deterministic, model-discipline-free coalescing. The
+  // DELIVERED text is the TERMINAL RUN (the suffix of blocks NOT followed by a
+  // turn-continuing tool_use); every tool-followed block is suppressed
+  // UNCONDITIONALLY (no length/wording gate), replacing #3515's substance-gated
+  // heuristic on this backstop path. `selectBackstopDelivery` returns null when
+  // nothing terminal survives (a short tool-followed fragment) — treat that as
+  // 'empty-text' so the turn routes to the Stop-hook re-prompt ladder rather
+  // than delivering an interim narration line. The silent-marker / empty guards
+  // above still run on the full `joined` string so a partly-silent turn is
+  // classified correctly.
+  const selected = selectBackstopDelivery(
+    input.capturedText.map((text, i) => ({
+      text,
+      followedByToolUse: input.capturedBlockMeta?.[i],
+    })),
+  )
+  if (selected == null || selected.text.trim().length === 0) {
+    return { kind: 'skip', reason: 'empty-text' }
   }
+  return { kind: 'flush', text: selected.text }
 }
 
 /**

package/telegram-plugin/voice-normalize-text.ts

@@ -53,6 +53,89 @@
 /** Replace a fenced code block with a spoken placeholder. */
 const CODE_BLOCK_PLACEHOLDER = 'code block omitted'
 
+/** Named HTML entities the reply text realistically carries. */
+const HTML_ENTITIES: Record<string, string> = {
+  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+}
+
+/**
+ * Markdown metacharacters that the block/emphasis/table stripper would
+ * silently consume at line-start or as a pair. When such a char arrives via
+ * an entity escape the user meant it LITERALLY (that is the whole point of
+ * escaping it), so instead of emitting the raw char — which the downstream
+ * stripper would then eat, losing the intent — we emit a neutral spoken form
+ * that survives every later pass. Deterministic; the spoken form contains no
+ * `&`/`;` so it can never re-enter the entity decoder.
+ */
+const METACHAR_SPOKEN: Record<string, string> = {
+  '#': ' hash ',
+  '*': ' asterisk ',
+  '_': ' underscore ',
+  '~': ' tilde ',
+  '`': ' backtick ',
+  '|': ' bar ',
+}
+
+/** One decode pass: named + numeric entities → char (or spoken metachar). */
+function decodeHtmlEntitiesOnce(input: string): string {
+  const toChar = (cp: number, raw: string): string => {
+    if (!(cp > 0 && cp <= 0x10ffff)) return raw
+    const ch = String.fromCodePoint(cp)
+    return METACHAR_SPOKEN[ch] ?? ch
+  }
+  return input
+    .replace(/&#x([0-9a-f]+);/gi, (m, hex: string) => toChar(parseInt(hex, 16), m))
+    .replace(/&#(\d+);/g, (m, dec: string) => toChar(Number(dec), m))
+    .replace(/&([a-z][a-z0-9]*);/gi, (m, name: string) => {
+      const ch = HTML_ENTITIES[name.toLowerCase()]
+      if (ch === undefined) return m
+      return METACHAR_SPOKEN[ch] ?? ch
+    })
+}
+
+/**
+ * Decode HTML entities (named + numeric) to their character so a TTS engine
+ * never reads `&amp;` as "amp". Unknown named entities are left untouched.
+ * Pure + deterministic.
+ *
+ * Iterates to a FIXPOINT: a double-encoded entity (`&amp;amp;lt;`) is decoded
+ * repeatedly until no entity remains, so this pass is depth-idempotent —
+ * applying it once yields the same result as applying it twice. That keeps
+ * every voice callsite in lockstep: the immediate voice-out path runs
+ * normalizeForSpeech THEN normalizeForTts, and the value the lazy Listen tap /
+ * pre-synth queue reads is itself already normalizeForSpeech'd before its own
+ * normalizeForTts — fixpoint decoding guarantees both speak an identical
+ * string regardless of how deep the original encoding was. The loop strictly
+ * shrinks the entity count each turn (and is capped) so it always terminates.
+ * Text WITHOUT a trailing `;` (e.g. `Q&A`) matches nothing and is returned
+ * untouched.
+ */
+export function decodeHtmlEntities(input: string): string {
+  let s = input
+  // A fully-decodable chain shrinks by at least one entity per pass; the cap
+  // is a belt-and-braces guard against any pathological crafted input.
+  for (let i = 0; i < 10; i++) {
+    const next = decodeHtmlEntitiesOnce(s)
+    if (next === s) break
+    s = next
+  }
+  return s
+}
+
+/**
+ * Remove markdown/MarkdownV2 backslash escapes so the spoken text carries no
+ * literal backslashes. A backslash before ANY single character is dropped,
+ * keeping the character (`\.` → ".", `\*` → "*", `\b` → "b"); a dangling
+ * trailing backslash is dropped. Pure + deterministic + idempotent (a second
+ * pass finds no backslashes). A real newline is preserved (only the escaping
+ * backslash is consumed).
+ */
+export function stripBackslashEscapes(input: string): string {
+  // `\X` → `X` for any following char (including an escaped `\\`), then drop
+  // any lone backslash the first pass left (an escaped backslash's survivor).
+  return input.replace(/\\([\s\S])/g, '$1').replace(/\\/g, '')
+}
+
 // ---------------------------------------------------------------------------
 // Number → words helpers (small, deterministic, English cardinal only).
 // Used by the numbers/units pass. Supports 0..999_999_999 which is far more
@@ -168,6 +251,23 @@ export function normalizeForSpeech(input: string): string {
   if (!input) return ''
   let s = input.replace(/\r\n?/g, '\n')
 
+  // 0a. HTML entities → their character. The reply text can carry entity
+  //     escapes (`&amp;`, `&lt;`, `&#39;`) that a TTS engine would otherwise
+  //     read as "amp" / "lt" / a digit run. Decode BEFORE markdown/symbol
+  //     passes so the recovered char is then handled naturally (e.g. a
+  //     decoded `&` becomes "and" in the symbols pass).
+  s = decodeHtmlEntities(s)
+
+  // 0b. Backslash escapes → the escaped character. Telegram MarkdownV2 and
+  //     CommonMark escape literal punctuation with a leading backslash
+  //     (`\.`, `\-`, `\*`), and a backslash before a non-punctuation char
+  //     (`\b`) is a literal backslash. Left in place the engine speaks
+  //     "backslash b" / "slash b" — exactly the operator's "trash" report.
+  //     Unescaping here (before the emphasis pass) restores the literal text
+  //     so genuine `*emphasis*` markers are still stripped downstream while
+  //     an escaped `\*` collapses to nothing spoken. Runs once; idempotent.
+  s = stripBackslashEscapes(s)
+
   // 0. Emoji & pictographs → dropped entirely, then whitespace collapsed.
   //    TTS reads an emoji as its long CLDR name ("grinning face"), which is
   //    noise. We also drop `:shortcode:` forms so nothing is read as

package/telegram-plugin/voice-ondemand.ts

@@ -311,3 +311,74 @@ export function mayInjectListenButton(
   if (rawKeyboard == null) return true
   return !rawKeyboard.some((row) => Array.isArray(row) && row.length > 0)
 }
+
+/** The voice-out plan fields the Listen-button decision depends on. A subset of
+ *  the gateway's full `VoiceOutPlan` so this pure helper carries no gateway
+ *  import. */
+export interface ListenButtonVoiceOutPlan {
+  engine: 'kokoro' | 'openai'
+  voice?: string
+  speed: number
+  replyMode: 'voice+text' | 'voice-only' | 'on-demand'
+  ttsChunks: string[]
+}
+
+/** The decision to inject a 🔊 Listen button on a message, plus the cache
+ *  payload the caller must persist so a tap can resynthesize. */
+export interface ListenButtonPlan {
+  /** The single-row Listen keyboard to attach as `reply_markup`. */
+  replyMarkup: {
+    inline_keyboard: Array<Array<{ text: string; callback_data: string }>>
+  }
+  /** The freshly minted token keying the keyboard callback + cache entry. */
+  token: string
+  /** The payload the caller stores under `token` in the VoiceOnDemandCache
+   *  (and enqueues for eager pre-synth). */
+  payload: VoiceOnDemandPayload
+}
+
+/**
+ * The SINGLE source of truth for "should this delivered message carry a 🔊
+ * Listen button, and if so which token/keyboard/cache payload?" — shared by
+ * BOTH the normal reply path (`sendReply` in outbound-send-path.ts) and the
+ * durable-outbox safety-net delivery (`outbox-sweep.ts` wiring), so a
+ * net-delivered final answer is indistinguishable from a normally-delivered
+ * one (switchroom #3502 regression: the sweep dropped the button).
+ *
+ * Returns null — no button — when any gate fails:
+ *  - no voice-out plan, or the plan is not kokoro on-demand (openai on-demand
+ *    synthesizes immediately and its taps would dead-end on the local sidecar);
+ *  - the TTS text is empty (nothing to speak — the empty-TTS guard);
+ *  - the agent supplied its own inline keyboard (single_use collision gate —
+ *    see mayInjectListenButton).
+ *
+ * Pure: it mints a token and builds the keyboard/payload but performs NO side
+ * effects (no cache write, no eager enqueue). The caller owns those so the
+ * token is only persisted when it decides to actually attach the button.
+ */
+export function planListenButton(params: {
+  voiceOutPlan: ListenButtonVoiceOutPlan | null
+  rawKeyboard: unknown[][] | undefined | null
+}): ListenButtonPlan | null {
+  const plan = params.voiceOutPlan
+  // on-demand Listen button is a LOCAL-engine (kokoro) feature only.
+  const useOnDemandButton =
+    plan != null && plan.replyMode === 'on-demand' && plan.engine === 'kokoro'
+  if (!useOnDemandButton) return null
+  // Empty-TTS guard: nothing to speak → no button.
+  if (!(plan.ttsChunks.length > 0 && plan.ttsChunks[0]!.length > 0)) return null
+  // Collision gate: agent supplied its own keyboard → skip.
+  if (!mayInjectListenButton(params.rawKeyboard)) return null
+
+  const token = mintVoiceOnDemandToken()
+  return {
+    replyMarkup: buildListenKeyboard(token),
+    token,
+    payload: {
+      // ttsChunks[0] is already normalizeForSpeech(reply) (kokoro path).
+      text: plan.ttsChunks[0]!,
+      ...(plan.voice != null ? { voice: plan.voice } : {}),
+      speed: plan.speed,
+    },
+  }
+}