switchroom 0.19.15 → 0.19.16

package/telegram-plugin/tests/silence-poke.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { projectTranscriptLine } from '../session-tail.js'
 import {
   startTurn,
   noteOutbound,
@@ -7,6 +10,9 @@ import {
   noteToolStart,
   noteToolEnd,
   noteToolLabel,
+  noteBackgroundShellAlive,
+  noteBackgroundShellDead,
+  __bgMarkerParserConfirmedForTests,
   endTurn,
   silenceMsForKey,
   silencePokeEnabled,
@@ -30,6 +36,7 @@ interface TestFixtures {
 function setupDeps(opts?: {
   thresholds?: Partial<typeof DEFAULT_THRESHOLDS> & { fallbackHardCeiling?: number }
   deferFallbackWhileToolInFlight?: boolean
+  isLegitimatelyWorking?: (key: string) => boolean
 }): TestFixtures {
   const fixtures: TestFixtures = { emitted: [], fallbacks: [] }
   __setDepsForTests({
@@ -42,6 +49,9 @@ function setupDeps(opts?: {
     ...(opts?.deferFallbackWhileToolInFlight != null
       ? { deferFallbackWhileToolInFlight: opts.deferFallbackWhileToolInFlight }
       : {}),
+    ...(opts?.isLegitimatelyWorking != null
+      ? { isLegitimatelyWorking: opts.isLegitimatelyWorking }
+      : {}),
   })
   return fixtures
 }
@@ -601,3 +611,273 @@ describe('silence-poke — Fix A: in-flight-tool defer', () => {
     expect(f.fallbacks).toHaveLength(0)
   })
 })
+
+// ─── #3519: CLI-side background-bash defer — the stacked-cards regression ─────
+// Root cause of the operator-visible bug: a single turn ran a foreground `Bash`
+// that the claude CLI auto-moved to the background at its foreground timeout.
+// The tool_result returned (draining `inFlightTools`), so every existing "still
+// working" signal — `isLegitimatelyWorking()`'s foreground/async-dispatch/
+// ask_user checks — went false while the process kept running and the model sat
+// silent waiting on it. At 300s the framework fallback fired: it nulled
+// `currentTurn` and tore down the pinned progress card (the `onFrameworkFallback`
+// callback → liveness-wiring.ts:427-441 `endCurrentTurnForKey`), and the next
+// tool burst minted a BRAND-NEW pinned card. Each > 300s gap repeated it →
+// 2..N stacked cards on ONE turn.
+//
+// These are OUTCOME assertions: `fixtures.fallbacks` counts every fallback fire,
+// and a fire is exactly a currentTurn-null + card teardown (the trigger for a
+// re-minted card). The production wiring is reproduced faithfully:
+// `isLegitimatelyWorking` IS wired (the gateway always wires it) and it returns
+// FALSE for the whole gap (the CLI-side background bash is invisible to it by
+// construction). Reverting the `sawBashThisTurn` defer turns these RED — the
+// fallback fires on every gap and multiple cards are minted.
+describe('silence-poke — #3519 background-bash defer (stacked-cards regression guard)', () => {
+  const PROD = {
+    thresholds: { fallbackHardCeiling: 900_000 }, // SILENCE_FALLBACK_HARD_MS
+    isLegitimatelyWorking: () => false,            // background bash is invisible
+  }
+
+  it('a foreground Bash moved to background does NOT tear down the card at 300s (mid-work)', () => {
+    const f = setupDeps(PROD)
+    startTurn('c:0', 0)
+    // Foreground bash starts, then auto-moves to background at ~120s: its
+    // tool_result returns so inFlightTools drains. isLegitimatelyWorking is
+    // false throughout — every existing signal says "idle".
+    noteToolStart('c:0', 't1', 'Bash', 'find / -name x', 5_000)
+    noteToolEnd('c:0', 't1', 125_000)
+    // The silent gap the model spends waiting on the background process.
+    __tickForTests(300_000)
+    __tickForTests(306_000) // well past the 300s base threshold
+    // BUG behaviour: fallback fires here (currentTurn nulled, card torn down).
+    // FIXED: deferred — the pinned card stays live, no re-mint.
+    expect(f.fallbacks).toHaveLength(0)
+  })
+
+  it('exactly ONE card survives a whole turn with two > 300s background-bash gaps', () => {
+    const f = setupDeps(PROD)
+
+    // Model the gateway's pinned-card lifecycle so the surviving card is
+    // asserted POSITIVELY, not merely inferred from zero teardowns. In
+    // production a fallback fire IS a card teardown (currentTurn nulled +
+    // pinned card unpinned, liveness-wiring.ts:427-441), and the next tool
+    // burst mints a BRAND-NEW pinned card — that re-mint is exactly the
+    // stacking. Here: mint one card when the turn starts, and replay a
+    // teardown + fresh re-mint for every fallback the silence-poke tick
+    // records. `mintedCards.length` is then the true number of cards that
+    // ever existed for the turn, and `pinnedCardId` is the live one.
+    const mintedCards: string[] = []
+    let pinnedCardId: string | null = null
+    const mintCard = (): void => {
+      const id = `card-${mintedCards.length + 1}`
+      mintedCards.push(id)
+      pinnedCardId = id
+    }
+    const syncCardsAfterTick = (): void => {
+      // Each recorded fallback == one teardown of the live card + a fresh
+      // re-mint by the resuming burst (the stacked-cards mechanism). Replay
+      // any teardown not yet modelled.
+      while (mintedCards.length - 1 < f.fallbacks.length) {
+        pinnedCardId = null // teardown unpins the live card
+        mintCard() // next tool burst mints a brand-new pinned card (a stack)
+      }
+    }
+
+    startTurn('c:0', 0)
+    mintCard() // the turn's first pinned progress card ("card-1")
+    // Gap 1 — first backgrounded find.
+    noteToolStart('c:0', 't1', 'Bash', 'find / -name a', 5_000)
+    noteToolEnd('c:0', 't1', 125_000)
+    __tickForTests(306_000)
+    syncCardsAfterTick()
+    expect(f.fallbacks).toHaveLength(0) // no Card B minted (zero teardowns)
+    // POSITIVE: the ORIGINAL pinned card is still the live one after gap 1,
+    // and it is the ONLY card that has ever existed.
+    expect(pinnedCardId).toBe('card-1')
+    expect(mintedCards).toHaveLength(1)
+    // Model resumes and updates the SAME pinned card (production resets the
+    // silence clock on that render), then launches a second backgrounded find.
+    noteProduction('c:0', 310_000)
+    noteToolStart('c:0', 't2', 'Bash', 'find / -name b', 315_000)
+    noteToolEnd('c:0', 't2', 435_000)
+    // Gap 2 — > 300s of silence since the last render (310_000).
+    __tickForTests(620_000)
+    syncCardsAfterTick()
+    expect(f.fallbacks).toHaveLength(0) // no Card C minted (zero teardowns)
+    // POSITIVE: still the same single original card, updated in place across
+    // BOTH gaps — no second/third card was ever minted (no stacking).
+    expect(pinnedCardId).toBe('card-1')
+    expect(mintedCards).toEqual(['card-1'])
+  })
+
+  it('still bounded: a genuinely wedged bash-turn unwedges ONCE at the hard ceiling (not 3×)', () => {
+    const f = setupDeps(PROD)
+    startTurn('c:0', 0)
+    noteToolStart('c:0', 't1', 'Bash', 'find /', 5_000)
+    noteToolEnd('c:0', 't1', 125_000)
+    __tickForTests(306_000)
+    expect(f.fallbacks).toHaveLength(0) // deferred, not fired 3×
+    __tickForTests(900_000) // crosses SILENCE_FALLBACK_HARD_MS
+    expect(f.fallbacks).toHaveLength(1) // exactly one bounded unwedge
+  })
+
+  it('the defer is Bash-specific: a non-Bash idle turn still fires at 300s (fix is scoped)', () => {
+    const f = setupDeps(PROD)
+    startTurn('c:0', 0)
+    noteToolStart('c:0', 't1', 'Grep', 'foo', 5_000)
+    noteToolEnd('c:0', 't1', 60_000) // Grep can't be a background process
+    __tickForTests(306_000)
+    expect(f.fallbacks).toHaveLength(1) // genuine silence → unwedges normally
+  })
+
+  it('honours the SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS=0 kill switch', () => {
+    const prev = process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS
+    process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS = '0'
+    try {
+      const f = setupDeps(PROD)
+      startTurn('c:0', 0)
+      noteToolStart('c:0', 't1', 'Bash', 'find /', 5_000)
+      noteToolEnd('c:0', 't1', 125_000)
+      __tickForTests(306_000)
+      expect(f.fallbacks).toHaveLength(1) // defer force-disabled → legacy fire
+    } finally {
+      if (prev != null) process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS = prev
+      else delete process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS
+    }
+  })
+})
+
+// ─── #3519 SHARPEN: PROVEN-alive defer, driven by REAL captured markers ───────
+// The coarse `sawBashThisTurn` guard above deferred EVERY bash-turn to the 900s
+// ceiling. This sharpens it: defer only while a background shell is PROVEN
+// alive (its structured `backgroundTaskId` launch marker seen, no completion
+// yet), and recover at ~300s the moment it finishes. The alive/dead facts here
+// are PARSED FROM REAL JSONL (tests/fixtures/bg-shell-liveness-3519.jsonl —
+// carrie session a6d2d33a-…, claude v2.1.197; line 109 auto-background launch,
+// line 175 `<task-notification>` completion — verbatim but for the operator username
+// scrubbed in both encodings per repo PII policy) through the SAME projectTranscriptLine
+// path the gateway uses, then fed to silence-poke exactly as the gateway feeds
+// it (tool_result.backgroundTaskId → noteBackgroundShellAlive; task_notification
+// → noteBackgroundShellDead). So every fixture value is traceable to a real byte.
+describe('silence-poke — #3519 sharpen: proven-alive defer (real markers)', () => {
+  const PROD = {
+    thresholds: { fallbackHardCeiling: 900_000 }, // SILENCE_FALLBACK_HARD_MS
+    isLegitimatelyWorking: () => false,            // background bash invisible to it
+  }
+  const FIXTURE = join(__dirname, 'fixtures', 'bg-shell-liveness-3519.jsonl')
+  const fxLines = readFileSync(FIXTURE, 'utf8').split('\n').filter(l => l.length > 0)
+  // Derive the REAL ids straight from the fixtures via the production parser.
+  const aliveEv = projectTranscriptLine(fxLines[0]).find(e => e.kind === 'tool_result')
+  const deadEv = projectTranscriptLine(fxLines[1])[0]
+  const LIVE_ID = aliveEv?.kind === 'tool_result' ? aliveEv.backgroundTaskId! : ''
+  const DEAD_ID = deadEv.kind === 'task_notification' ? deadEv.taskId : ''
+
+  it('sanity: the fixtures really carry a matching background-shell id', () => {
+    expect(LIVE_ID).toBe('bxa4sv3dq')
+    expect(DEAD_ID).toBe('bxa4sv3dq')
+  })
+
+  // (a) A shell PROVEN alive across a > 300s gap must NOT tear down the card —
+  //     and exactly ONE card survives (positive assertion, not inferred).
+  it('(a) live shell across a > 300s gap → no teardown, exactly one card', () => {
+    const f = setupDeps(PROD)
+    const mintedCards: string[] = []
+    let pinnedCardId: string | null = null
+    const mintCard = (): void => {
+      mintedCards.push(`card-${mintedCards.length + 1}`)
+      pinnedCardId = mintedCards[mintedCards.length - 1]
+    }
+    const syncCardsAfterTick = (): void => {
+      while (mintedCards.length - 1 < f.fallbacks.length) { pinnedCardId = null; mintCard() }
+    }
+
+    startTurn('c:0', 0)
+    mintCard() // the turn's first pinned progress card
+    // Foreground Bash auto-moved to background at ~120s: its tool_result
+    // returns (drains inFlightTools) carrying the real backgroundTaskId.
+    noteToolStart('c:0', 't1', 'Bash', 'find / -name x', 5_000)
+    noteToolEnd('c:0', 't1', 125_000)
+    noteBackgroundShellAlive('c:0', LIVE_ID) // gateway does this from the parsed event
+    __tickForTests(306_000)
+    syncCardsAfterTick()
+    __tickForTests(500_000) // still alive, still silent, still well past 300s
+    syncCardsAfterTick()
+    expect(f.fallbacks).toHaveLength(0)     // deferred — no teardown
+    expect(pinnedCardId).toBe('card-1')     // POSITIVE: original card still live
+    expect(mintedCards).toEqual(['card-1']) // and it is the ONLY card ever minted
+    expect(__bgMarkerParserConfirmedForTests()).toBe(true) // marker proven working
+  })
+
+  // (b) THE NEW capability: once the shell FINISHES (real completion marker),
+  //     a subsequent > 300s wedge recovers at ~300s — NOT held to 900s.
+  it('(b) shell went DEAD then a > 300s wedge → fallback fires at ~300s (fast recovery)', () => {
+    const f = setupDeps(PROD)
+    startTurn('c:0', 0)
+    noteToolStart('c:0', 't1', 'Bash', 'find / -name x', 5_000)
+    noteToolEnd('c:0', 't1', 125_000)
+    noteBackgroundShellAlive('c:0', LIVE_ID)   // backgrounded at ~120s
+    noteBackgroundShellDead('c:0', DEAD_ID)    // real <task-notification> completed at ~200s
+    // Model then goes silent on a genuine wedge. Because the CLI marker PARSED
+    // (confirmed), the coarse sawBash degradation is OFF, so the empty
+    // alive-set means this is real silence → recover at the 300s base window,
+    // not the 900s ceiling.
+    __tickForTests(306_000)
+    expect(f.fallbacks).toHaveLength(1) // FAST recovery restored (would be 0 under the old coarse guard)
+  })
+
+  // (c) SAFE DEGRADATION: if a future CLI renames the markers so NOTHING parses
+  //     (backgroundTaskId never resolves → parser never confirmed), we must not
+  //     regress to stacking — fall back to the 900s-bounded coarse guard.
+  it('(c) unmatched/changed CLI marker → degrades to the 900s-bounded guard', () => {
+    const f = setupDeps(PROD)
+    // Mutate the REAL alive line so neither the structured field nor the string
+    // matches — exactly what a marker rename looks like. Parse it as the gateway
+    // would; it yields NO backgroundTaskId, so noteBackgroundShellAlive is never
+    // called and the parser stays unconfirmed.
+    const mutated = JSON.parse(fxLines[0])
+    delete mutated.toolUseResult.backgroundTaskId
+    mutated.message.content[0].content = 'Task moved to background (id withheld by a newer CLI).'
+    const ev = projectTranscriptLine(JSON.stringify(mutated)).find(e => e.kind === 'tool_result')
+    expect(ev?.kind === 'tool_result' ? ev.backgroundTaskId : 'X').toBeUndefined()
+
+    startTurn('c:0', 0)
+    noteToolStart('c:0', 't1', 'Bash', 'find / -name x', 5_000) // sawBashThisTurn armed
+    noteToolEnd('c:0', 't1', 125_000)
+    // No alive registration (marker unparseable) → parser NOT confirmed.
+    expect(__bgMarkerParserConfirmedForTests()).toBe(false)
+    __tickForTests(306_000)
+    expect(f.fallbacks).toHaveLength(0) // still deferred by the coarse guard (no stacking)
+    __tickForTests(900_000)             // crosses the hard ceiling
+    expect(f.fallbacks).toHaveLength(1) // bounded unwedge — never hangs forever
+  })
+
+  // (d) Still bounded even while genuinely alive: a shell that never reports
+  //     dead still unwedges ONCE at the 900s ceiling (not indefinitely).
+  it('(d) a never-completing live shell still unwedges once at the 900s ceiling', () => {
+    const f = setupDeps(PROD)
+    startTurn('c:0', 0)
+    noteToolStart('c:0', 't1', 'Bash', 'find /', 5_000)
+    noteToolEnd('c:0', 't1', 125_000)
+    noteBackgroundShellAlive('c:0', LIVE_ID) // alive, never dies
+    __tickForTests(306_000)
+    expect(f.fallbacks).toHaveLength(0) // deferred while alive
+    __tickForTests(900_000)             // hard ceiling
+    expect(f.fallbacks).toHaveLength(1) // exactly one bounded unwedge
+  })
+
+  it('honours the SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS=0 kill switch even with a live shell', () => {
+    const prev = process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS
+    process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS = '0'
+    try {
+      const f = setupDeps(PROD)
+      startTurn('c:0', 0)
+      noteToolStart('c:0', 't1', 'Bash', 'find /', 5_000)
+      noteToolEnd('c:0', 't1', 125_000)
+      noteBackgroundShellAlive('c:0', LIVE_ID)
+      __tickForTests(306_000)
+      expect(f.fallbacks).toHaveLength(1) // force-disabled → no defer at all
+    } finally {
+      if (prev != null) process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS = prev
+      else delete process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS
+    }
+  })
+})

package/telegram-plugin/tests/tts-normalize.test.ts

@@ -4,6 +4,7 @@
  */
 import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
 import { normalizeForTts, ttsNormalizeEnabled } from '../tts-normalize.js'
+import { normalizeForSpeech } from '../voice-normalize-text.js'
 
 const KILL = 'SWITCHROOM_DISABLE_TTS_NORMALIZE'
 
@@ -240,3 +241,68 @@ describe('conservatism', () => {
     expect(normalizeForTts(input)).toBe(normalizeForTts(input))
   })
 })
+
+describe('normalizeForTts — backslash escapes & HTML entities (last-line defence)', () => {
+  test('strips a literal \\b so the engine never speaks "backslash b"', () => {
+    const out = normalizeForTts('the regex \\b boundary')
+    expect(out).toBe('the regex b boundary')
+    expect(out).not.toContain('\\')
+  })
+
+  test('unescapes MarkdownV2 punctuation escapes (\\. \\! \\-)', () => {
+    expect(normalizeForTts('done\\. next\\! wait\\-')).toBe('done. next! wait-')
+  })
+
+  test('decodes HTML entities (& < ')', () => {
+    expect(normalizeForTts('Tom & Jerry')).toBe('Tom and Jerry')
+    expect(normalizeForTts('5 &lt; 10')).toBe('5 < 10')
+    expect(normalizeForTts("it&#39;s here")).toBe("it's here")
+  })
+
+  test('rich mixed reply → clean spoken text (no backslash/backtick/entity)', () => {
+    const reply =
+      '**Bold** and `code\\b` and a [label](https://example.com/x) ' +
+      'with Tom &amp; Jerry and a regex \\b\\.'
+    const out = normalizeForTts(reply)
+    expect(out).not.toContain('\\')
+    expect(out).not.toContain('`')
+    expect(out).not.toContain('&amp;')
+    expect(out).toContain('label')
+    expect(out).toContain('Tom and Jerry')
+  })
+
+  test('kill switch still returns byte-identical input (escapes preserved)', () => {
+    process.env[KILL] = '1'
+    expect(normalizeForTts('a \\b &amp; b')).toBe('a \\b &amp; b')
+    delete process.env[KILL]
+  })
+
+  test('idempotent after normalizeForSpeech already unescaped', () => {
+    const reply = 'a \\b and Tom &amp; Jerry \\. end'
+    const once = normalizeForTts(reply)
+    expect(normalizeForTts(once)).toBe(once)
+  })
+})
+
+describe('normalizeForTts — review findings (fixpoint decode, metachar, nits)', () => {
+  test('L2 parity: immediate (speech+tts) and single-tts agree on a double-encoded entity', () => {
+    const x = '&amp;amp;lt;'
+    const immediate = normalizeForTts(normalizeForSpeech(x))
+    const singleTts = normalizeForTts(x)
+    expect(immediate).toBe('<')
+    expect(singleTts).toBe('<')
+    expect(immediate).toBe(singleTts)
+    expect(normalizeForTts('&amp;amp;amp;')).toBe('&')
+  })
+
+  test('L1: entity → line-leading metachar keeps a spoken form (hash/asterisk)', () => {
+    expect(normalizeForTts('&#35; Heading')).toBe('hash Heading')
+    expect(normalizeForTts('2 &#42; 3')).toBe('2 asterisk 3')
+  })
+
+  test('nit: dangling trailing backslash dropped; &#92; decodes then strips', () => {
+    expect(normalizeForTts('ends here\\')).toBe('ends here')
+    expect(normalizeForTts('X&#92;Y')).toBe('XY')
+    expect(normalizeForTts('X&#92;Y')).not.toContain('\\')
+  })
+})

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/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