switchroom 0.16.29 → 0.16.46

package/telegram-plugin/tests/vault-request-access-card.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Render-safety pin for the agent-initiated vault-access approval card.
+ *
+ * Bug (card-ux fix 2): the vault key was interpolated into a `code span`
+ * WITHOUT defusing backtick / without leaking backslashes. A key with a
+ * backtick would prematurely close the span; the following `_why_` and
+ * `_footer_` markdown then paired against stray delimiters and the card
+ * rendered on top of itself. Keys with `_` (e.g. `openai/OPENAI_API_KEY`)
+ * must render literally inside the span (no visible `\_`).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { renderVaultRequestAccessCard } from '../gateway/vault-request-access-card.js'
+
+// Zero-width space codeSpanSafe inserts after a backtick to defuse it.
+const ZWSP = '​'
+
+/** Count top-level (outside code spans) markdown emphasis delimiters. */
+function unbalancedOutsideCodeSpans(text: string): {
+  underscores: number
+  asterisks: number
+} {
+  let inSpan = false
+  let underscores = 0
+  let asterisks = 0
+  for (const ch of text) {
+    if (ch === '`') {
+      inSpan = !inSpan
+      continue
+    }
+    if (inSpan) continue
+    if (ch === '_') underscores += 1
+    if (ch === '*') asterisks += 1
+  }
+  return { underscores, asterisks }
+}
+
+describe('renderVaultRequestAccessCard', () => {
+  it('renders an underscore-laden key literally inside the code span (no backslash leak)', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'openai/OPENAI_API_KEY',
+      scope: 'read',
+      reason: 'call the completions endpoint',
+      ttl_seconds: 7 * 86400,
+    })
+    // The key rides in a code span verbatim — underscores present, NOT escaped.
+    expect(text).toContain('`openai/OPENAI_API_KEY`')
+    // No visible backslash-escaping leaked into the span.
+    expect(text).not.toContain('OPENAI\\_API\\_KEY')
+  })
+
+  it('does not leave unbalanced markdown delimiters outside code spans', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'openai/OPENAI_API_KEY',
+      scope: 'write',
+      reason: 'rotate the key',
+      ttl_seconds: 3600,
+    })
+    const { underscores, asterisks } = unbalancedOutsideCodeSpans(text)
+    // The `_why_` + `_footer_` italic pairs and `**agent**` bold pair must
+    // each be even outside the spans — an underscore-key leaking out (the bug)
+    // makes this odd.
+    expect(underscores % 2).toBe(0)
+    expect(asterisks % 2).toBe(0)
+  })
+
+  it('defuses a backtick in the key so it cannot close the span early', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'svc/we`ird',
+      scope: 'read',
+      ttl_seconds: 86400,
+    })
+    // A raw backtick would have closed the span; codeSpanSafe splits it with a
+    // zero-width space so the parser sees `` `we` `` (empty-ish) then literal
+    // text, never an unterminated span breaking the following lines.
+    expect(text).toContain(`we\`${ZWSP}ird`)
+    // Every intentional code-span backtick is immediately followed by
+    // non-backtick content or a ZWSP — no bare `\`\`` that would swallow text.
+    expect(text).not.toContain('``')
+  })
+
+  it('renders "not provided" when reason omitted', () => {
+    const text = renderVaultRequestAccessCard({
+      agent: 'overlord',
+      key: 'svc/key',
+      scope: 'read',
+      ttl_seconds: 86400,
+    })
+    expect(text).toContain('why: _not provided_')
+  })
+})

package/telegram-plugin/tests/vault-request-access-tool.test.ts

@@ -163,3 +163,27 @@ describe('Fix B: vault_request_access standing-ACL-aware (#1487 follow-up)', ()
     expect(approveBlock).toMatch(/try\s*{[\s\S]*?listViaBroker\([\s\S]*?}\s*catch/)
   })
 })
+
+describe('vault_request_access — `why` alias for `reason`', () => {
+  // The sibling tool vault_request_save uses `why`; agents cross-
+  // contaminate the two schemas. Without the alias the rationale
+  // silently drops off the approval card ("why: not provided") and
+  // operators tend to Deny.
+  it('gateway accepts args.why as a fallback when args.reason is absent', () => {
+    expect(gatewaySrc).toMatch(
+      /const reason =\s*\n?\s*typeof args\.reason === 'string' \? args\.reason : typeof args\.why === 'string' \? args\.why : undefined/,
+    )
+  })
+
+  it('bridge schema documents the alias on both fields', () => {
+    const block = bridgeSrc.split("name: 'vault_request_access'")[1]?.split("name: '")[0] ?? ''
+    expect(block).toMatch(/why:\s*{\s*type:\s*'string'/)
+    expect(block).toContain('Alias for `reason`')
+    expect(block).toContain('`why` is accepted as an alias')
+  })
+
+  it('reason wins when both are supplied (ordering: reason checked first)', () => {
+    const idx = gatewaySrc.indexOf("typeof args.reason === 'string' ? args.reason : typeof args.why === 'string'")
+    expect(idx).toBeGreaterThan(-1)
+  })
+})

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

@@ -0,0 +1,256 @@
+/**
+ * Unit tests for normalizeForSpeech — the speech-normalization pass applied
+ * to a reply BEFORE it is synthesized to a voice note. Covers every case the
+ * operator reported (tilde, asterisks, backticks, headings, links, code
+ * fences) plus the documented behavioural choices.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import { normalizeForSpeech } from '../voice-normalize-text.js'
+
+describe('normalizeForSpeech — reported markdown/symbol cases', () => {
+  it('drops stray tildes (never spoken as "tilde")', () => {
+    expect(normalizeForSpeech('It costs ~5 dollars')).toBe('It costs 5 dollars')
+    expect(normalizeForSpeech('done ~ ok')).toBe('done ok')
+  })
+
+  it('strips bold/italic asterisks and underscores, keeping the words', () => {
+    expect(normalizeForSpeech('This is **bold** text')).toBe('This is bold text')
+    expect(normalizeForSpeech('This is *italic* text')).toBe('This is italic text')
+    expect(normalizeForSpeech('This is _emphasis_ text')).toBe('This is emphasis text')
+    expect(normalizeForSpeech('***all*** three')).toBe('all three')
+  })
+
+  it('strips strikethrough ~~text~~ to plain text', () => {
+    expect(normalizeForSpeech('~~gone~~ kept')).toBe('gone kept')
+  })
+
+  it('removes backticks from inline code but keeps the content', () => {
+    expect(normalizeForSpeech('run `npm test` now')).toBe('run npm test now')
+  })
+
+  it('strips headings markers', () => {
+    expect(normalizeForSpeech('# Summary\nAll good')).toBe('Summary All good')
+    expect(normalizeForSpeech('### Deep heading')).toBe('Deep heading')
+  })
+
+  it('speaks link text and drops the URL', () => {
+    expect(normalizeForSpeech('see [the docs](https://example.com/x) here')).toBe(
+      'see the docs here',
+    )
+  })
+
+  it('drops a fenced code block and leaves a spoken placeholder', () => {
+    const input = 'Here is code:\n```js\nconst x = 1\nconsole.log(x)\n```\nDone.'
+    const out = normalizeForSpeech(input)
+    expect(out).toContain('code block omitted')
+    expect(out).not.toContain('const x')
+    expect(out).not.toContain('```')
+    expect(out).toContain('Done.')
+  })
+})
+
+describe('normalizeForSpeech — additional structures', () => {
+  it('converts list bullets and numbers to prose pauses', () => {
+    const out = normalizeForSpeech('Steps:\n- first\n- second\n1. third')
+    expect(out).not.toMatch(/[-*+]\s/)
+    expect(out).not.toMatch(/^\d+\./)
+    expect(out).toContain('first')
+    expect(out).toContain('second')
+    expect(out).toContain('third')
+  })
+
+  it('strips blockquote markers', () => {
+    expect(normalizeForSpeech('> quoted line')).toBe('quoted line')
+  })
+
+  it('turns tables into prose (no pipes or separator rows)', () => {
+    const table = '| A | B |\n| --- | --- |\n| 1 | 2 |'
+    const out = normalizeForSpeech(table)
+    expect(out).not.toContain('|')
+    expect(out).not.toContain('---')
+    expect(out).toContain('A')
+    expect(out).toContain('B')
+  })
+
+  it('converts arrows to the word "to"', () => {
+    expect(normalizeForSpeech('build -> deploy')).toBe('build to deploy')
+    expect(normalizeForSpeech('a => b')).toBe('a to b')
+    expect(normalizeForSpeech('x → y')).toBe('x to y')
+  })
+
+  it('replaces bare and autolink URLs with "a link"', () => {
+    expect(normalizeForSpeech('go to https://example.com now')).toBe('go to a link now')
+    expect(normalizeForSpeech('go to <https://example.com>')).toBe('go to a link')
+  })
+
+  it('drops images to their alt text', () => {
+    expect(normalizeForSpeech('![a cat](x.png) sits')).toBe('a cat sits')
+  })
+
+  it('collapses newlines and whitespace into sentence flow', () => {
+    expect(normalizeForSpeech('Line one.\n\nLine two.')).toBe('Line one. Line two.')
+    expect(normalizeForSpeech('a   b\nc')).toBe('a b c')
+  })
+
+  it('expands a minimal, safe set of abbreviations', () => {
+    expect(normalizeForSpeech('use it, e.g. here')).toBe('use it, for example, here')
+    expect(normalizeForSpeech('the tool, i.e. the interface')).toBe(
+      'the tool, that is, the interface',
+    )
+    expect(normalizeForSpeech('cats, dogs, etc.')).toBe('cats, dogs, and so on')
+  })
+
+  it('collapses excessive punctuation', () => {
+    expect(normalizeForSpeech('really?!?!')).toBe('really!')
+    expect(normalizeForSpeech('wow!!!')).toBe('wow!')
+  })
+})
+
+describe('normalizeForSpeech — emoji & pictographs', () => {
+  it('strips emoji and collapses the resulting whitespace', () => {
+    expect(normalizeForSpeech('done 🚀 shipping')).toBe('done shipping')
+    expect(normalizeForSpeech('great 👍🏽 job')).toBe('great job')
+    expect(normalizeForSpeech('🎉')).toBe('')
+  })
+
+  it('drops :shortcode: emoji forms', () => {
+    expect(normalizeForSpeech('nice :rocket: work')).toBe('nice work')
+  })
+
+  it('leaves ordinary colon usage alone', () => {
+    expect(normalizeForSpeech('note: this is fine')).toBe('note: this is fine')
+  })
+})
+
+describe('normalizeForSpeech — numbers, units & symbols', () => {
+  it('speaks percent', () => {
+    expect(normalizeForSpeech('up 20% today')).toBe('up 20 percent today')
+  })
+
+  it('speaks currency amounts', () => {
+    expect(normalizeForSpeech('costs $5')).toBe('costs five dollars')
+    expect(normalizeForSpeech('costs $5.50')).toBe('costs five dollars fifty')
+    expect(normalizeForSpeech('just $1')).toBe('just one dollar')
+  })
+
+  it('speaks standalone & as "and"', () => {
+    expect(normalizeForSpeech('cats & dogs')).toBe('cats and dogs')
+    expect(normalizeForSpeech('R&D team')).toBe('R and D team')
+  })
+
+  it('speaks + between words as "plus" and = as "equals"', () => {
+    expect(normalizeForSpeech('speed + power')).toBe('speed plus power')
+    expect(normalizeForSpeech('x = y')).toBe('x equals y')
+  })
+
+  it('speaks × / x multipliers as "times"', () => {
+    expect(normalizeForSpeech('12× faster')).toBe('twelve times faster')
+    expect(normalizeForSpeech('a 12x speedup')).toBe('a twelve times speedup')
+  })
+
+  it('speaks temperature degrees', () => {
+    expect(normalizeForSpeech('it is 30°C outside')).toBe(
+      'it is 30 degrees outside',
+    )
+    expect(normalizeForSpeech('72°F')).toBe('72 degrees')
+  })
+
+  it('expands number + time/size unit suffixes', () => {
+    expect(normalizeForSpeech('waited 2s')).toBe('waited two seconds')
+    expect(normalizeForSpeech('took 500ms')).toBe('took five hundred milliseconds')
+    expect(normalizeForSpeech('run 5m')).toBe('run five minutes')
+    expect(normalizeForSpeech('run 5min')).toBe('run five minutes')
+    expect(normalizeForSpeech('wait 2h')).toBe('wait two hours')
+    expect(normalizeForSpeech('wait 2hr')).toBe('wait two hours')
+    expect(normalizeForSpeech('in 3d')).toBe('in three days')
+    expect(normalizeForSpeech('10kb file')).toBe('ten kilobytes file')
+    expect(normalizeForSpeech('10KB file')).toBe('ten kilobytes file')
+    expect(normalizeForSpeech('a 5MB image')).toBe('a five megabytes image')
+    expect(normalizeForSpeech('a 2GB dump')).toBe('a two gigabytes dump')
+    expect(normalizeForSpeech('1s ping')).toBe('one second ping')
+  })
+
+  it('expands the "k" thousands shorthand', () => {
+    expect(normalizeForSpeech('100k users')).toBe('one hundred thousand users')
+  })
+
+  it('leaves number-glued-to-word identifiers alone', () => {
+    expect(normalizeForSpeech('my5thing works')).toBe('my5thing works')
+    expect(normalizeForSpeech('class5 room')).toBe('class5 room')
+  })
+})
+
+describe('normalizeForSpeech — abbreviations (phase 2)', () => {
+  it('expands vs / approx / w/', () => {
+    expect(normalizeForSpeech('cats vs dogs')).toBe('cats versus dogs')
+    expect(normalizeForSpeech('cats vs. dogs')).toBe('cats versus dogs')
+    expect(normalizeForSpeech('approx 10 items')).toBe('approximately 10 items')
+    expect(normalizeForSpeech('tea w/ milk')).toBe('tea with milk')
+  })
+})
+
+describe('normalizeForSpeech — acronyms', () => {
+  it('spells curated initialisms letter-by-letter', () => {
+    expect(normalizeForSpeech('the CI passed')).toBe('the C I passed')
+    expect(normalizeForSpeech('open a PR')).toBe('open a P R')
+    expect(normalizeForSpeech('call the API via HTTP')).toBe(
+      'call the A P I via H T T P',
+    )
+    expect(normalizeForSpeech('GPU and CPU load')).toBe('G P U and C P U load')
+    expect(normalizeForSpeech('parse the JSON')).toBe('parse the J S O N')
+  })
+
+  it('leaves word-style acronyms and unknown caps alone', () => {
+    expect(normalizeForSpeech('NASA launch')).toBe('NASA launch')
+    expect(normalizeForSpeech('the FBI report')).toBe('the FBI report')
+  })
+
+  it('does not touch caps inside a larger word', () => {
+    expect(normalizeForSpeech('myAPIkey stays')).toBe('myAPIkey stays')
+  })
+})
+
+describe('normalizeForSpeech — times & dates', () => {
+  it('speaks clock times', () => {
+    expect(normalizeForSpeech('meet at 12:45')).toBe('meet at twelve forty-five')
+    expect(normalizeForSpeech('at 09:05')).toBe('at nine oh five')
+    expect(normalizeForSpeech('at 14:00')).toBe("at fourteen o'clock")
+  })
+
+  it('speaks ISO dates', () => {
+    expect(normalizeForSpeech('on 2026-07-01 we ship')).toBe(
+      'on July first two thousand twenty-six we ship',
+    )
+    expect(normalizeForSpeech('2026-12-25')).toBe(
+      'December twenty-fifth two thousand twenty-six',
+    )
+  })
+})
+
+describe('normalizeForSpeech — conservative, does not mangle real words', () => {
+  it('leaves plain prose untouched', () => {
+    expect(normalizeForSpeech('The quick brown fox jumps.')).toBe(
+      'The quick brown fox jumps.',
+    )
+  })
+
+  it('leaves lowercase day/word tokens and a symbol-free sentence alone', () => {
+    expect(normalizeForSpeech('see you wednesday afternoon')).toBe(
+      'see you wednesday afternoon',
+    )
+    expect(normalizeForSpeech('The report covers three main areas.')).toBe(
+      'The report covers three main areas.',
+    )
+  })
+
+  it('preserves an underscore inside an identifier-like word', () => {
+    // A lone mid-word underscore is not emphasis; keep the token intact.
+    expect(normalizeForSpeech('the my_var name')).toBe('the my_var name')
+  })
+
+  it('returns empty for empty/whitespace input', () => {
+    expect(normalizeForSpeech('')).toBe('')
+    expect(normalizeForSpeech('   \n  ')).toBe('')
+  })
+})

package/telegram-plugin/tests/voice-ondemand.test.ts

@@ -0,0 +1,299 @@
+/**
+ * On-demand voice-out (reply_mode='on-demand') unit tests.
+ *
+ * gateway.ts is a 25k-line module with import-time side effects, so the
+ * on-demand primitives live in ../voice-ondemand.ts (imported by the gateway).
+ * These tests exercise those real primitives + reproduce the exact gateway
+ * decisions (button injection gate, no-synth-at-reply-time, callback routing)
+ * so the observable contract is covered without importing the gateway.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import {
+  VoiceOnDemandCache,
+  VOICE_ONDEMAND_CALLBACK_PREFIX,
+  mintVoiceOnDemandToken,
+  isVoiceOnDemandCallback,
+  parseVoiceOnDemandToken,
+  buildListenKeyboard,
+  mayInjectListenButton,
+} from '../voice-ondemand.js'
+import { parseAgentCallback } from '../inline-keyboard-callbacks.js'
+
+describe('on-demand: token + reserved callback prefix', () => {
+  it('mints an 8-hex-char token', () => {
+    const t = mintVoiceOnDemandToken()
+    expect(t).toMatch(/^[0-9a-f]{8}$/)
+  })
+
+  it('builds a single-button Listen keyboard with a voice: callback', () => {
+    const kb = buildListenKeyboard('deadbeef')
+    expect(kb.inline_keyboard).toHaveLength(1)
+    expect(kb.inline_keyboard[0]).toHaveLength(1)
+    const btn = kb.inline_keyboard[0]![0]!
+    expect(btn.text).toBe('🔊 Listen')
+    expect(btn.callback_data).toBe('voice:deadbeef')
+    expect(btn.callback_data.length).toBeLessThanOrEqual(64) // Telegram cap
+  })
+
+  it('recognises + parses voice: callbacks, rejects others', () => {
+    expect(isVoiceOnDemandCallback('voice:abc123')).toBe(true)
+    expect(isVoiceOnDemandCallback('agent:foo')).toBe(false)
+    expect(parseVoiceOnDemandToken('voice:abc123')).toBe('abc123')
+    expect(parseVoiceOnDemandToken('voice:')).toBeNull() // empty token
+    expect(parseVoiceOnDemandToken('agent:foo')).toBeNull()
+  })
+})
+
+describe('on-demand: callback routes internally, NOT to the agent inbound path', () => {
+  it('a voice: callback is NOT parsed as an agent callback', () => {
+    // The gateway checks isVoiceOnDemandCallback() BEFORE parseAgentCallback().
+    const data = `${VOICE_ONDEMAND_CALLBACK_PREFIX}${mintVoiceOnDemandToken()}`
+    expect(isVoiceOnDemandCallback(data)).toBe(true)
+    // Even if it reached agent routing, the raw voice: data must not be a
+    // valid agent callback (which requires the agent: prefix).
+    expect(parseAgentCallback(data)).toBeNull()
+  })
+})
+
+describe('on-demand: bounded TTL LRU cache', () => {
+  it('stores and retrieves a payload by token', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hello world', voice: 'af_bella', speed: 1.1 })
+    expect(cache.get('tok')).toEqual({ text: 'hello world', voice: 'af_bella', speed: 1.1 })
+  })
+
+  it('cache MISS returns null gracefully (no throw)', () => {
+    const cache = new VoiceOnDemandCache()
+    expect(() => cache.get('never-stored')).not.toThrow()
+    expect(cache.get('never-stored')).toBeNull()
+  })
+
+  it('expires entries past the TTL (miss → graceful null)', () => {
+    let now = 1_000
+    const cache = new VoiceOnDemandCache({ ttlMs: 100, maxEntries: 500, now: () => now })
+    cache.put('tok', { text: 'x', speed: 1 })
+    now = 1_050
+    expect(cache.get('tok')).not.toBeNull() // still fresh
+    now = 1_200
+    expect(cache.get('tok')).toBeNull() // expired → graceful miss
+  })
+
+  it('evicts the oldest entry past the size cap (LRU)', () => {
+    const cache = new VoiceOnDemandCache({ ttlMs: 60_000, maxEntries: 2 })
+    cache.put('a', { text: 'a', speed: 1 })
+    cache.put('b', { text: 'b', speed: 1 })
+    cache.put('c', { text: 'c', speed: 1 }) // evicts 'a'
+    expect(cache.size).toBe(2)
+    expect(cache.get('a')).toBeNull()
+    expect(cache.get('b')).not.toBeNull()
+    expect(cache.get('c')).not.toBeNull()
+  })
+})
+
+describe('on-demand: cache survives a restart (persistPath)', () => {
+  it('reloads tokens from disk so a Listen tap after restart still resolves', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'voice-ondemand-persist-'))
+    const persistPath = join(dir, 'voice-ondemand.json')
+    try {
+      // First "process": mint + store a token, then drop the instance
+      // (simulating a gateway restart wiping the in-memory Map).
+      const before = new VoiceOnDemandCache({ persistPath })
+      before.put('tok', { text: 'hello after restart', voice: 'af_bella', speed: 1.1 })
+      expect(existsSync(persistPath)).toBe(true)
+
+      // Second "process": a fresh instance backed by the same file must see it.
+      const after = new VoiceOnDemandCache({ persistPath })
+      expect(after.get('tok')).toEqual({
+        text: 'hello after restart',
+        voice: 'af_bella',
+        speed: 1.1,
+      })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('drops entries that expired while the gateway was down', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'voice-ondemand-expire-'))
+    const persistPath = join(dir, 'voice-ondemand.json')
+    try {
+      let now = 1_000
+      const before = new VoiceOnDemandCache({ ttlMs: 100, persistPath, now: () => now })
+      before.put('tok', { text: 'x', speed: 1 })
+      // Restart happens "later" — past the TTL.
+      now = 5_000
+      const after = new VoiceOnDemandCache({ ttlMs: 100, persistPath, now: () => now })
+      expect(after.get('tok')).toBeNull()
+      expect(after.size).toBe(0)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('preserves LRU insertion order + cap across a reload', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'voice-ondemand-lru-'))
+    const persistPath = join(dir, 'voice-ondemand.json')
+    try {
+      const before = new VoiceOnDemandCache({ maxEntries: 3, persistPath })
+      before.put('a', { text: 'a', speed: 1 })
+      before.put('b', { text: 'b', speed: 1 })
+      before.put('c', { text: 'c', speed: 1 })
+
+      // Reload with a SMALLER cap — the oldest ('a') must be dropped.
+      const after = new VoiceOnDemandCache({ maxEntries: 2, persistPath })
+      expect(after.size).toBe(2)
+      expect(after.get('a')).toBeNull()
+      expect(after.get('b')).not.toBeNull()
+      expect(after.get('c')).not.toBeNull()
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('a corrupt persistence file degrades to an empty cache (no throw)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'voice-ondemand-corrupt-'))
+    const persistPath = join(dir, 'voice-ondemand.json')
+    try {
+      writeFileSync(persistPath, '{ this is not valid json', 'utf8')
+      let cache: VoiceOnDemandCache | undefined
+      expect(() => {
+        cache = new VoiceOnDemandCache({ persistPath })
+      }).not.toThrow()
+      expect(cache!.size).toBe(0)
+      // Still usable — a fresh put + get round-trips and rewrites the file clean.
+      cache!.put('tok', { text: 'ok', speed: 1 })
+      expect(cache!.get('tok')).toEqual({ text: 'ok', speed: 1 })
+      // File is now valid JSON again.
+      expect(() => JSON.parse(readFileSync(persistPath, 'utf8'))).not.toThrow()
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('an in-memory cache (no persistPath) writes no file — unchanged behaviour', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'voice-ondemand-mem-'))
+    try {
+      const cache = new VoiceOnDemandCache()
+      cache.put('tok', { text: 'x', speed: 1 })
+      // Nothing under the tmp dir was written.
+      expect(existsSync(join(dir, 'voice-ondemand.json'))).toBe(false)
+      expect(cache.get('tok')).not.toBeNull()
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('on-demand: reply-time behaviour (gate + no synthesis)', () => {
+  it('reply_mode=on-demand + local engine → Listen button, no synth at reply time', () => {
+    // Reproduce the gateway reply path decision for reply_mode='on-demand':
+    // the voiceOgg synth loop is guarded to SKIP when replyMode==='on-demand',
+    // and a Listen button is injected instead.
+    const replyMode = 'on-demand' as 'voice+text' | 'voice-only' | 'on-demand'
+
+    let synthCalls = 0
+    const fakeSynth = () => {
+      synthCalls++
+    }
+    // gateway guard: `if (plan != null && plan.replyMode !== 'on-demand')`
+    if (replyMode !== 'on-demand') fakeSynth()
+    expect(synthCalls).toBe(0) // ZERO GPU/sidecar work at reply time
+
+    // No agent buttons → the Listen button is injected.
+    const rawKeyboard: unknown[][] | undefined = undefined
+    expect(mayInjectListenButton(rawKeyboard)).toBe(true)
+    const kb = buildListenKeyboard(mintVoiceOnDemandToken())
+    expect(kb.inline_keyboard[0]![0]!.callback_data.startsWith('voice:')).toBe(true)
+  })
+
+  it('ENGINE GATE: openai + on-demand does NOT inject a Listen button (falls back to immediate synth)', () => {
+    // The gateway computes:
+    //   useOnDemandButton = plan != null && replyMode==='on-demand' && engine==='kokoro'
+    // and both the reply-time synth-skip AND the button injection key on it.
+    // So an openai on-demand config must (a) NOT defer synthesis and (b) NOT
+    // mint a Listen button — its taps would dead-end on the local sidecar.
+    const useOnDemandButton = (
+      engine: 'kokoro' | 'openai',
+      replyMode: 'voice+text' | 'voice-only' | 'on-demand',
+    ) => replyMode === 'on-demand' && engine === 'kokoro'
+
+    // openai + on-demand: no button, immediate synth path runs.
+    expect(useOnDemandButton('openai', 'on-demand')).toBe(false)
+    // kokoro + on-demand: button injected, synth deferred.
+    expect(useOnDemandButton('kokoro', 'on-demand')).toBe(true)
+    // openai non-on-demand modes are unaffected (normal synth).
+    expect(useOnDemandButton('openai', 'voice+text')).toBe(false)
+    expect(useOnDemandButton('openai', 'voice-only')).toBe(false)
+
+    // Reproduce the reply-time synth guard: `if (plan != null && !useOnDemandButton)`.
+    // For openai on-demand it MUST enter the synth loop (fall back), unlike
+    // kokoro on-demand which skips it.
+    let openaiSynthRan = false
+    if (!useOnDemandButton('openai', 'on-demand')) openaiSynthRan = true
+    expect(openaiSynthRan).toBe(true)
+
+    let kokoroSynthRan = false
+    if (!useOnDemandButton('kokoro', 'on-demand')) kokoroSynthRan = true
+    expect(kokoroSynthRan).toBe(false)
+  })
+
+  it('GATE: agent-supplied inline_keyboard present → NO voice button injected', () => {
+    const agentKeyboard = [[{ text: 'Approve', callback_data: 'yes' }]]
+    expect(mayInjectListenButton(agentKeyboard)).toBe(false)
+
+    // An empty keyboard (no rows / empty rows) does not count as agent buttons.
+    expect(mayInjectListenButton([])).toBe(true)
+    expect(mayInjectListenButton([[]])).toBe(true)
+    expect(mayInjectListenButton(undefined)).toBe(true)
+  })
+})
+
+describe('on-demand: single-use — strip the Listen keyboard on success only', () => {
+  // Reproduce the callback handler's control flow. Each terminal branch in the
+  // gateway either returns EARLY (leaving the button intact so the user can
+  // retry) or falls through to the successful sendVoice + keyboard strip.
+  //
+  //   expired cache entry           → answerCallbackQuery + return (no strip)
+  //   sidecar unavailable           → answerCallbackQuery + return (no strip)
+  //   synth failure (!result.ok)    → answerCallbackQuery + return (no strip)
+  //   sendVoice success             → strip keyboard
+  //
+  // We model that as a pure decision so the observable contract — strip iff the
+  // audio was actually delivered — is pinned without importing the gateway.
+  type Outcome = 'expired' | 'sidecar-unavailable' | 'synth-failed' | 'sent'
+  const shouldStripListenKeyboard = (outcome: Outcome, cbMessageId: number | undefined): boolean =>
+    outcome === 'sent' && cbMessageId != null
+
+  it('strips the keyboard after a successful sendVoice', () => {
+    expect(shouldStripListenKeyboard('sent', 42)).toBe(true)
+  })
+
+  it('does NOT strip when the cache entry expired (user can retry)', () => {
+    expect(shouldStripListenKeyboard('expired', 42)).toBe(false)
+  })
+
+  it('does NOT strip when the voice sidecar is unavailable (user can retry)', () => {
+    expect(shouldStripListenKeyboard('sidecar-unavailable', 42)).toBe(false)
+  })
+
+  it('does NOT strip when synthesis failed (user can retry)', () => {
+    expect(shouldStripListenKeyboard('synth-failed', 42)).toBe(false)
+  })
+
+  it('cannot strip without a callback message id even on success', () => {
+    // The gateway guards the strip on `cbMessageId != null` (no message → no
+    // keyboard to edit).
+    expect(shouldStripListenKeyboard('sent', undefined)).toBe(false)
+  })
+
+  it('strips by clearing the inline keyboard (empty rows)', () => {
+    // The strip payload the handler sends: reply_markup with an empty
+    // inline_keyboard — the same shape the agent-button single_use strip uses.
+    const stripMarkup = { reply_markup: { inline_keyboard: [] as unknown[][] } }
+    expect(stripMarkup.reply_markup.inline_keyboard).toHaveLength(0)
+  })
+})