switchroom 0.16.38 → 0.16.46

package/telegram-plugin/tests/telegram-format.test.ts

@@ -123,7 +123,10 @@ describe('splitMarkdownChunks', () => {
     // A long body with a fenced code block straddling the cap. The chunker
     // must move the whole fence to a single chunk so no chunk has an odd
     // number of fence delimiters (which would swallow the next chunk).
-    const fence = '```\n' + 'code line\n'.repeat(20) + '```'
+    // The fence FITS within the cap, so the chunker can move it whole to a
+    // single chunk and keep every chunk's fence count balanced. (An oversized
+    // fence that cannot fit is hard-sliced instead — see the F7 tests below.)
+    const fence = '```\n' + 'code line\n'.repeat(8) + '```'
     const text = 'intro paragraph '.repeat(15) + '\n\n' + fence + '\n\noutro paragraph'
     const chunks = splitMarkdownChunks(text, 180)
     for (const c of chunks) {
@@ -150,15 +153,37 @@ describe('splitMarkdownChunks', () => {
     }
   })
 
-  test('emits an oversized indivisible block whole rather than looping forever', () => {
-    // A single fenced block larger than maxLen has no safe interior cut —
-    // the chunker emits it whole (a louder, debuggable Telegram reject
-    // beats an infinite loop).
+  test('hard-slices an indivisible block that exceeds the cap (F7 — no oversized chunk)', () => {
+    // A single fenced block larger than maxLen has no safe interior cut. The
+    // OLD behaviour emitted it whole, which Telegram rejects with
+    // RICH_MESSAGE_TEXT_TOO_LONG and drops the entire answer. F7 delegates to
+    // hardSliceToCap so the region comes out as multiple <= cap character
+    // slices instead — degraded-but-delivered beats a hard reject.
     const giant = '```\n' + 'x'.repeat(500) + '\n```'
     const chunks = splitMarkdownChunks(giant, 100)
-    // It comes out as one (oversized) chunk, not split mid-fence.
-    expect(chunks.length).toBe(1)
-    expect(chunks[0]).toBe(giant)
+    expect(chunks.length).toBeGreaterThan(1)
+    for (const c of chunks) expect(c.length).toBeLessThanOrEqual(100)
+    // No content is dropped — the slices concatenate back to the original.
+    expect(chunks.join('')).toBe(giant)
+  })
+
+  test('hard-slices a single unbreakable >maxLen token run into <= cap chunks (F7)', () => {
+    // One giant pipe-bearing line with no space/newline boundary below the
+    // cap: neither the blank-line, newline, nor space heuristic can find a
+    // cut, and the table-row back-off cannot help either. This is the exact
+    // "cut <= 0" path — it must hard-slice, not emit an oversized chunk.
+    const runaway = 'a|b|'.repeat(200) // 800 chars, no spaces/newlines
+    const chunks = splitMarkdownChunks(runaway, 100)
+    expect(chunks.length).toBeGreaterThan(1)
+    for (const c of chunks) expect(c.length).toBeLessThanOrEqual(100)
+    expect(chunks.join('')).toBe(runaway)
+  })
+
+  test('an indivisible region larger than the real 32768 cap still slices to <= cap (F7)', () => {
+    const giant = 'z'.repeat(RICH_MESSAGE_MAX_CHARS + 5000)
+    const chunks = splitMarkdownChunks(giant) // default cap = RICH_MESSAGE_MAX_CHARS
+    expect(chunks.length).toBeGreaterThan(1)
+    for (const c of chunks) expect(c.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS)
   })
 
   // -------------------------------------------------------------------------

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

@@ -10,7 +10,95 @@
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
-import { scrubVoice } from '../text-voice-scrub.js'
+import { scrubVoice, normalizeDashes } from '../text-voice-scrub.js'
+
+/**
+ * Regression guard for the em-dash comma-splice bug seen in a real reply
+ * (the #2737-era voice scrub). The original #1683 rule degraded a
+ * clause-joining em-dash to a comma when the next word was lowercase, which
+ * joined two independent clauses with a comma — a comma splice ("voice came
+ * back, three PRs stacked"). The fix degrades to a full stop and recapitalizes
+ * the following word, so the output is never a splice. These tests use the
+ * verbatim failure strings from the stored bad message.
+ */
+describe('scrubVoice — em-dash between clauses never produces a comma splice', () => {
+  beforeEach(() => {
+    delete process.env.SWITCHROOM_DISABLE_VOICE_SCRUB
+    delete process.env.SWITCHROOM_VOICE_STRIP_OPENERS
+  })
+
+  it('lowercase-continued independent clause becomes two sentences, not a splice (real string 1)', () => {
+    const r = scrubVoice('**Why voice came back** — three PRs stacked')
+    // Was: "**Why voice came back**, three PRs stacked" (comma splice).
+    expect(r.scrubbed).toBe('**Why voice came back**. Three PRs stacked')
+    expect(r.scrubbed).not.toContain('**, three')
+    expect(r.replaced).toBe(1)
+  })
+
+  it('lowercase-continued independent clause becomes two sentences, not a splice (real string 2)', () => {
+    const r = scrubVoice(
+      'never reached the agents — this is what unblocked everything today.',
+    )
+    // Was: "...the agents, this is what unblocked..." (comma splice).
+    expect(r.scrubbed).toBe(
+      'never reached the agents. This is what unblocked everything today.',
+    )
+    expect(r.scrubbed).not.toContain('agents, this')
+    expect(r.replaced).toBe(1)
+  })
+
+  it('the scrubbed output contains no ", <lowercase clause>" splice for any spaced dash', () => {
+    const r = scrubVoice(
+      'first thing — second independent clause and — third one here',
+    )
+    // No comma directly joining the two independent clauses.
+    expect(r.scrubbed).toBe(
+      'first thing. Second independent clause and. Third one here',
+    )
+  })
+
+  it('normalizeDashes (card / worker-narration path) also avoids the splice', () => {
+    // The non-reply surfaces reuse normalizeDashes; same splice-free rule.
+    expect(normalizeDashes('came back — three PRs stacked')).toBe(
+      'came back. Three PRs stacked',
+    )
+  })
+
+  it('a dash before a NON-letter (digit / paren) is not wrongly recapitalized', () => {
+    // capFirst only touches an ASCII lowercase letter; a digit / punctuation
+    // start is left as-is after the full stop.
+    expect(normalizeDashes('the count — 3 items remain')).toBe(
+      'the count. 3 items remain',
+    )
+    expect(normalizeDashes('the note — (see appendix)')).toBe(
+      'the note. (see appendix)',
+    )
+  })
+
+  it('dashes inside code spans, fenced blocks, and URLs are still never touched', () => {
+    const input =
+      'prose — one\n' +
+      'inline `a — b — c` stays\n' +
+      '```\nfenced x — y — z stays\n```\n' +
+      'link https://ex.io/a—b—c stays too — end'
+    const r = scrubVoice(input)
+    expect(r.scrubbed).toContain('`a — b — c`')
+    expect(r.scrubbed).toContain('fenced x — y — z stays')
+    expect(r.scrubbed).toContain('https://ex.io/a—b—c')
+    // Only the two prose dashes were scrubbed (to full stops).
+    expect(r.scrubbed).toContain('prose. One')
+    expect(r.scrubbed).toContain('stays too. End')
+    expect(r.replaced).toBe(2)
+  })
+
+  it('a double-space inside inline code / a URL is left untouched by the scrub', () => {
+    // The scrub must not normalize whitespace inside protected regions.
+    const r = scrubVoice('keep `foo  bar` and http://h/a  b intact — done')
+    expect(r.scrubbed).toContain('`foo  bar`')
+    expect(r.scrubbed).toContain('http://h/a  b')
+    expect(r.scrubbed).toContain('intact. Done')
+  })
+})
 
 describe('scrubVoice — em / en dash replacement', () => {
   beforeEach(() => {
@@ -21,9 +109,13 @@ describe('scrubVoice — em / en dash replacement', () => {
   })
 
   describe('mechanical rewrite of spaced dashes', () => {
-    it('replaces a spaced em-dash before lowercase with a comma', () => {
+    it('replaces a spaced em-dash before lowercase with a full stop (no comma splice)', () => {
+      // #1683 originally emitted a comma here, which produced a comma splice
+      // between two independent clauses ("on it, checking the calendar"). The
+      // splice-free rule degrades the clause-joining dash to a period and
+      // recapitalizes the following word.
       const r = scrubVoice('on it — checking the calendar')
-      expect(r.scrubbed).toBe('on it, checking the calendar')
+      expect(r.scrubbed).toBe('on it. Checking the calendar')
       expect(r.replaced).toBe(1)
     })
 
@@ -34,22 +126,23 @@ describe('scrubVoice — em / en dash replacement', () => {
       expect(r.replaced).toBe(1)
     })
 
-    it('handles multiple em-dashes in one sentence', () => {
+    it('handles multiple em-dashes in one sentence (each becomes a full stop)', () => {
       const r = scrubVoice('one — two — three — done')
-      expect(r.scrubbed).toBe('one, two, three, done')
+      expect(r.scrubbed).toBe('one. Two. Three. Done')
       expect(r.replaced).toBe(3)
     })
 
     it('treats en-dash (–) identically to em-dash', () => {
       const r = scrubVoice('on it – checking the calendar')
-      expect(r.scrubbed).toBe('on it, checking the calendar')
+      expect(r.scrubbed).toBe('on it. Checking the calendar')
       expect(r.replaced).toBe(1)
     })
 
-    it('replaces unspaced word-dash-word as a comma', () => {
-      // Less common but seen in tightly-typed prose.
+    it('replaces unspaced word-dash-word with a full stop (no comma splice)', () => {
+      // Less common but seen in tightly-typed prose. Same splice-free rule as
+      // the spaced form: a period plus a recapitalized following word.
       const r = scrubVoice('flag—on or flag—off')
-      expect(r.scrubbed).toBe('flag, on or flag, off')
+      expect(r.scrubbed).toBe('flag. On or flag. Off')
       expect(r.replaced).toBe(2)
     })
 
@@ -66,6 +159,32 @@ describe('scrubVoice — em / en dash replacement', () => {
       expect(r.scrubbed).toBe('- note: ship it')
       expect(r.replaced).toBe(1)
     })
+
+    it('does not recapitalize a mixed-case brand token after a dash', () => {
+      // capFirst must leave a lowercase-initial mixed-case token (iOS, eBay,
+      // iPhone, macOS) alone — recapitalizing "iOS" to "IOS" corrupts the
+      // brand. A normal lowercase word still gets recapitalized.
+      const r = scrubVoice('foo—iOS build')
+      expect(r.scrubbed).toBe('foo. iOS build')
+      expect(r.replaced).toBe(1)
+
+      const spaced = scrubVoice('shipped — iPhone ready')
+      expect(spaced.scrubbed).toBe('shipped. iPhone ready')
+
+      const normal = scrubVoice('foo—done here')
+      expect(normal.scrubbed).toBe('foo. Done here')
+    })
+
+    it('preserves numeric ranges as ASCII hyphens, not full stops', () => {
+      // A digit-flanked dash is a range, not a clause break. It falls through
+      // to the catch-all rule and becomes an ASCII hyphen.
+      const unspaced = scrubVoice('10–20')
+      expect(unspaced.scrubbed).toBe('10-20')
+      expect(unspaced.replaced).toBe(1)
+
+      const tight = scrubVoice('scored 3–2')
+      expect(tight.scrubbed).toBe('scored 3-2')
+    })
   })
 
   describe('protected regions are left alone', () => {
@@ -73,33 +192,33 @@ describe('scrubVoice — em / en dash replacement', () => {
       const input = 'here is code:\n```bash\nfoo --bar — baz\n```\nand prose — done'
       const r = scrubVoice(input)
       expect(r.scrubbed).toBe(
-        'here is code:\n```bash\nfoo --bar — baz\n```\nand prose, done',
+        'here is code:\n```bash\nfoo --bar — baz\n```\nand prose. Done',
       )
       expect(r.replaced).toBe(1)
     })
 
     it('preserves dashes inside inline code', () => {
       const r = scrubVoice('the flag `--really — keep` matters — yes')
-      expect(r.scrubbed).toBe('the flag `--really — keep` matters, yes')
+      expect(r.scrubbed).toBe('the flag `--really — keep` matters. Yes')
       expect(r.replaced).toBe(1)
     })
 
     it('preserves dashes inside <code> HTML tags', () => {
       const r = scrubVoice('see <code>x — y</code> and note — ok')
-      expect(r.scrubbed).toBe('see <code>x — y</code> and note, ok')
+      expect(r.scrubbed).toBe('see <code>x — y</code> and note. Ok')
       expect(r.replaced).toBe(1)
     })
 
     it('preserves dashes inside <pre> HTML tags', () => {
       const r = scrubVoice('block:\n<pre>x — y\nz — w</pre>\nend — ok')
-      expect(r.scrubbed).toBe('block:\n<pre>x — y\nz — w</pre>\nend, ok')
+      expect(r.scrubbed).toBe('block:\n<pre>x — y\nz — w</pre>\nend. Ok')
       expect(r.replaced).toBe(1)
     })
 
     it('preserves dashes inside URLs', () => {
       const r = scrubVoice('see https://example.com/a—b for context — ok')
       expect(r.scrubbed).toBe(
-        'see https://example.com/a—b for context, ok',
+        'see https://example.com/a—b for context. Ok',
       )
       expect(r.replaced).toBe(1)
     })
@@ -110,7 +229,7 @@ describe('scrubVoice — em / en dash replacement', () => {
       const fence =
         '```\n# heading — title\nfunction f() {}\n```'
       const r = scrubVoice(fence + '\ntrailing — yes')
-      expect(r.scrubbed).toBe(fence + '\ntrailing, yes')
+      expect(r.scrubbed).toBe(fence + '\ntrailing. Yes')
       expect(r.replaced).toBe(1)
     })
   })
@@ -151,8 +270,8 @@ describe('scrubVoice — em / en dash replacement', () => {
         'Result: empty for Saturday — nothing scheduled. Anything else?'
       const r = scrubVoice(input)
       expect(r.scrubbed).toBe(
-        "I'll check the calendar, should take a few seconds. " +
-        'Result: empty for Saturday, nothing scheduled. Anything else?',
+        "I'll check the calendar. Should take a few seconds. " +
+        'Result: empty for Saturday. Nothing scheduled. Anything else?',
       )
       expect(r.replaced).toBe(2)
     })
@@ -164,9 +283,9 @@ describe('scrubVoice — em / en dash replacement', () => {
         'Ready to commit — go?'
       const r = scrubVoice(input)
       expect(r.scrubbed).toBe(
-        'Running `git status --short`, looks clean. ' +
+        'Running `git status --short`. Looks clean. ' +
         '```\nM file.ts — modified\n```\n' +
-        'Ready to commit, go?',
+        'Ready to commit. Go?',
       )
       expect(r.replaced).toBe(2)
     })
@@ -293,15 +412,16 @@ describe('scrubVoice — opener strip is OFF by default (prompt carries tone)',
 
   it('STILL normalizes em-dashes by default (punctuation, no content removed)', () => {
     const r = scrubVoice('on it — checking the calendar')
-    expect(r.scrubbed).toBe('on it, checking the calendar')
+    expect(r.scrubbed).toBe('on it. Checking the calendar')
     expect(r.replaced).toBe(1)
     expect(r.openersStripped).toBe(0)
   })
 
   it('an affirmation opener with an em-dash keeps the words, fixes only the dash', () => {
     const r = scrubVoice('Exactly right — the token had expired.')
-    // Opener preserved; the em-dash after it becomes a comma.
-    expect(r.scrubbed).toBe('Exactly right, the token had expired.')
+    // Opener preserved (strip is OFF); the em-dash between two independent
+    // clauses becomes a full stop, not a comma (no splice).
+    expect(r.scrubbed).toBe('Exactly right. The token had expired.')
     expect(r.openersStripped).toBe(0)
     expect(r.replaced).toBe(1)
   })

package/telegram-plugin/tests/tool-activity-summary.test.ts

@@ -241,10 +241,15 @@ describe("clipNarrative — narrative-step clip (JSONL-text-narrative primitive)
     const narrativeLines: string[] = [];
     const labelLines: string[] = [];
     const text = "Important find: no main branch yet — branching off origin.";
+    // F1: the feed renders through renderStatusCard → stripMarkdown, which now
+    // normalizes em/en-dashes on this card surface. A narrative and a label go
+    // through the exact same path, so the render is still byte-identical — the
+    // dash is scrubbed to a full stop (new sentence, recapitalized) in BOTH.
+    const scrubbed = "Important find: no main branch yet. Branching off origin.";
     const narrativeRender = appendActivityLabel(narrativeLines, clipNarrative(text));
     const labelRender = appendActivityLabel(labelLines, clipNarrative(text));
     expect(narrativeRender).toBe(labelRender);
-    expect(narrativeRender).toBe(`**→ ${text}**`);
+    expect(narrativeRender).toBe(`**→ ${scrubbed}**`);
   });
 
   it("empty string yields an empty clip (appendActivityLabel then drops it)", () => {

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

@@ -0,0 +1,242 @@
+/**
+ * Tests for tts-normalize.ts — deterministic L1 TTS normalization
+ * (issue #2760, Phase 1). Bun test (this dir uses bun test, not vitest).
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { normalizeForTts, ttsNormalizeEnabled } from '../tts-normalize.js'
+
+const KILL = 'SWITCHROOM_DISABLE_TTS_NORMALIZE'
+
+let savedKill: string | undefined
+
+beforeEach(() => {
+  savedKill = process.env[KILL]
+  delete process.env[KILL]
+})
+
+afterEach(() => {
+  if (savedKill === undefined) delete process.env[KILL]
+  else process.env[KILL] = savedKill
+})
+
+describe('gating', () => {
+  test('ON by default — normalizes with no env vars set', () => {
+    expect(ttsNormalizeEnabled()).toBe(true)
+    expect(normalizeForTts('**bold** $5.20')).toBe('bold five dollars twenty')
+  })
+
+  test('kill switch → byte-identical pass-through', () => {
+    process.env[KILL] = '1'
+    const input = '**bold** and $5.20 🚀 https://github.com/x'
+    expect(normalizeForTts(input)).toBe(input)
+    expect(ttsNormalizeEnabled()).toBe(false)
+  })
+
+  test('kill switch accepts "true"', () => {
+    process.env[KILL] = 'true'
+    expect(ttsNormalizeEnabled()).toBe(false)
+  })
+
+  test('empty input stays empty', () => {
+    expect(normalizeForTts('')).toBe('')
+  })
+})
+
+describe('markdown', () => {
+  test('bold/italic/strike markers removed', () => {
+    expect(normalizeForTts('**bold** and *italic* and ~~gone~~')).toBe(
+      'bold and italic and gone',
+    )
+  })
+
+  test('headings become plain text', () => {
+    expect(normalizeForTts('## Status report\nAll good')).toBe(
+      'Status report All good',
+    )
+  })
+
+  test('links become link text', () => {
+    expect(normalizeForTts('see [the docs](https://example.com/a/b) now')).toBe(
+      'see the docs now',
+    )
+  })
+
+  test('list markers dropped', () => {
+    expect(normalizeForTts('- first\n- second')).toBe('first second')
+  })
+
+  test('blockquote markers dropped', () => {
+    expect(normalizeForTts('> quoted line')).toBe('quoted line')
+  })
+
+  test('code fences become spoken placeholder', () => {
+    const out = normalizeForTts('before\n```ts\nconst x = 1\n```\nafter')
+    expect(out).toContain('code block omitted')
+    expect(out).not.toContain('const x')
+  })
+
+  test('inline code read as-is without backticks, content untouched', () => {
+    expect(normalizeForTts('run `deploy_5km_run` now')).toBe(
+      'run deploy_5km_run now',
+    )
+  })
+
+  test('unterminated fence swallows to end-of-input (deliberate)', () => {
+    // An opening ``` with no close drops everything after it — reading
+    // half a code block aloud is worse than omitting it. Pinned as the
+    // intended trade-off.
+    const out = normalizeForTts('before\n```ts\nconst secret = 1\nmore code')
+    expect(out).toBe('before code block omitted.')
+  })
+
+  test('tables summarized as table omitted', () => {
+    const out = normalizeForTts('| a | b |\n|---|---|\n| 1 | 2 |\n')
+    expect(out).toContain('table omitted')
+    expect(out).not.toContain('|')
+  })
+})
+
+describe('numbers', () => {
+  test('currency $5.20 → five dollars twenty', () => {
+    expect(normalizeForTts('that costs $5.20 today')).toBe(
+      'that costs five dollars twenty today',
+    )
+  })
+
+  test('whole-dollar and singular', () => {
+    expect(normalizeForTts('$1 fee')).toBe('one dollar fee')
+    expect(normalizeForTts('$300 total')).toBe('three hundred dollars total')
+  })
+
+  test('percent 12% → twelve percent', () => {
+    expect(normalizeForTts('up 12% overnight')).toBe('up twelve percent overnight')
+  })
+
+  test('ordinal 3rd → third', () => {
+    expect(normalizeForTts('the 3rd item and the 21st day')).toBe(
+      'the third item and the twenty-first day',
+    )
+  })
+
+  test('time 14:30 spoken', () => {
+    expect(normalizeForTts('meet at 14:30 sharp')).toBe(
+      'meet at fourteen thirty sharp',
+    )
+  })
+
+  test('ISO date spoken', () => {
+    expect(normalizeForTts('due 2026-07-04 ok')).toBe(
+      'due July fourth two thousand twenty-six ok',
+    )
+  })
+
+  test('phone-like digit run read as digits', () => {
+    expect(normalizeForTts('call 0412 345 678 now')).toBe(
+      'call zero four one two three four five six seven eight now',
+    )
+  })
+
+  test('international +-prefixed number read as digits', () => {
+    expect(normalizeForTts('call +61 412 345 678')).toBe(
+      'call plus six one four one two three four five six seven eight',
+    )
+  })
+
+  test('ordinary space-separated numbers stay untouched', () => {
+    expect(normalizeForTts('scores were 1024 2048 4096 today')).toBe(
+      'scores were 1024 2048 4096 today',
+    )
+  })
+
+  test('short digit groups without phone prefix stay untouched', () => {
+    // The unit pass may expand a trailing unit, but the digit groups
+    // themselves must never be read digit-by-digit.
+    const out = normalizeForTts('12 34 56 78 items')
+    expect(out).toBe('12 34 56 78 items')
+  })
+
+  test('currency with thousands separator: $1,000 → one thousand dollars', () => {
+    expect(normalizeForTts('paid $1,000 up front')).toBe(
+      'paid one thousand dollars up front',
+    )
+    expect(normalizeForTts('$12,345.67 total')).toBe(
+      'twelve thousand three hundred forty-five dollars sixty-seven total',
+    )
+  })
+
+  test('odd cents ($5.203) left unchanged rather than half-read', () => {
+    expect(normalizeForTts('value $5.203 today')).toBe('value $5.203 today')
+  })
+
+  test('HH:MM:SS left unchanged (no dangling seconds)', () => {
+    expect(normalizeForTts('at 12:34:56 sharp')).toBe('at 12:34:56 sharp')
+  })
+
+  test('units expand: 5km, 10GB, 500ms', () => {
+    expect(normalizeForTts('ran 5km')).toBe('ran five kilometres')
+    expect(normalizeForTts('used 10GB')).toBe('used ten gigabytes')
+    expect(normalizeForTts('took 500ms')).toBe('took five hundred milliseconds')
+  })
+
+  test('identifiers with digits are never touched', () => {
+    expect(normalizeForTts('rename class5 and my5thing')).toBe(
+      'rename class5 and my5thing',
+    )
+  })
+})
+
+describe('URLs', () => {
+  test('bare URL → spoken domain', () => {
+    expect(normalizeForTts('see https://github.com/switchroom/switchroom for code')).toBe(
+      'see github dot com link for code',
+    )
+  })
+
+  test('www prefix dropped from spoken domain', () => {
+    expect(normalizeForTts('at https://www.example.org/x')).toBe(
+      'at example dot org link',
+    )
+  })
+
+  test('IP-host URL degrades to a link', () => {
+    expect(normalizeForTts('at http://127.0.0.1:8080/x ok')).toBe('at a link ok')
+  })
+})
+
+describe('emoji', () => {
+  test('common emoji spoken via map', () => {
+    expect(normalizeForTts('great work 👍')).toBe('great work thumbs up')
+  })
+
+  test('other emoji stripped', () => {
+    expect(normalizeForTts('launch 🚀 now 🎉')).toBe('launch now')
+  })
+})
+
+describe('symbols', () => {
+  test('& → and, @ → at, # → hash', () => {
+    expect(normalizeForTts('cats & dogs')).toBe('cats and dogs')
+    expect(normalizeForTts('ping @ken')).toBe('ping at ken')
+    expect(normalizeForTts('see #general')).toBe('see hash general')
+  })
+
+  test('prose slash spoken', () => {
+    expect(normalizeForTts('yes/no answer')).toBe('yes slash no answer')
+  })
+
+  test('~ before a number → about', () => {
+    expect(normalizeForTts('~5 minutes left')).toBe('about 5 minutes left')
+  })
+})
+
+describe('conservatism', () => {
+  test('plain prose passes through unchanged', () => {
+    const input = 'The build finished and everything looks good.'
+    expect(normalizeForTts(input)).toBe(input)
+  })
+
+  test('deterministic: same input, same output', () => {
+    const input = '## Hi\n**bold** $5.20 at 14:30 👍 https://github.com/a'
+    expect(normalizeForTts(input)).toBe(normalizeForTts(input))
+  })
+})

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