switchroom 0.19.16 → 0.19.18

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

@@ -29,9 +29,11 @@ describe('normalizeForSpeech — reported markdown/symbol cases', () => {
     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('strips headings markers and gives the heading a spoken full stop', () => {
+    // The heading is its own spoken sentence — without the terminator the
+    // newline-collapse ran the heading straight into the body text.
+    expect(normalizeForSpeech('# Summary\nAll good')).toBe('Summary. All good')
+    expect(normalizeForSpeech('### Deep heading')).toBe('Deep heading.')
   })
 
   it('speaks link text and drops the URL', () => {
@@ -118,6 +120,18 @@ describe('normalizeForSpeech — emoji & pictographs', () => {
     expect(normalizeForSpeech('nice :rocket: work')).toBe('nice work')
   })
 
+  // Digit-bodied shortcodes are real. A letter-only body left them in the
+  // text AND glued them to the previous word ("Nice:100: work").
+  it('drops a DIGIT-bodied :shortcode: without eating the space', () => {
+    expect(normalizeForSpeech('Nice :100: work')).toBe('Nice work')
+    expect(normalizeForSpeech('a :8ball: b')).toBe('a b')
+    expect(normalizeForSpeech('a :1st_place_medal: b')).toBe('a b')
+  })
+
+  it('the digit-bodied form still cannot eat a timestamp colon', () => {
+    expect(normalizeForSpeech('Ran at 14:30:46 ok')).toBe('Ran at 14:30:46 ok')
+  })
+
   it('leaves ordinary colon usage alone', () => {
     expect(normalizeForSpeech('note: this is fine')).toBe('note: this is fine')
   })
@@ -335,3 +349,198 @@ describe('normalizeForSpeech — review findings (fixpoint decode, metachar, nit
     expect(decodeHtmlEntities('Q&A test')).toBe('Q&A test')
   })
 })
+
+describe('normalizeForSpeech — list & heading pacing', () => {
+  it('speaks a 4-bullet list as 4 separate sentences', () => {
+    const out = normalizeForSpeech(
+      'Here are the steps:\n' +
+        '- Check the logs\n' +
+        '- Restart the container\n' +
+        '- Verify health\n' +
+        '- Report back',
+    )
+    expect(out).toBe(
+      'Here are the steps: Check the logs. Restart the container. ' +
+        'Verify health. Report back.',
+    )
+    // Four sentence-terminated spoken units after the lead-in.
+    const units = out
+      .split(/(?<=[.:])\s+/)
+      .filter((u) => u.trim().length > 0)
+    expect(units).toEqual([
+      'Here are the steps:',
+      'Check the logs.',
+      'Restart the container.',
+      'Verify health.',
+      'Report back.',
+    ])
+  })
+
+  it('separates ordered-list items into sentences', () => {
+    expect(normalizeForSpeech('1. first\n2. second\n3. third')).toBe(
+      'first. second. third.',
+    )
+  })
+
+  it('does not double punctuation when the item already ends in . ! or ?', () => {
+    const out = normalizeForSpeech('- Done.\n- Really?\n- Ship it!')
+    expect(out).toBe('Done. Really? Ship it!')
+    expect(out).not.toContain('..')
+    expect(out).not.toContain('. .')
+    expect(out).not.toContain('?.')
+    expect(out).not.toContain('!.')
+  })
+
+  it('terminates the line that introduces a list when it lacks punctuation', () => {
+    expect(normalizeForSpeech('Steps\n- one\n- two')).toBe('Steps. one. two.')
+  })
+
+  it('does not chop a wrapped list item mid-clause', () => {
+    expect(normalizeForSpeech('- a long item that\ncontinues here\n- second')).toBe(
+      'a long item that continues here. second.',
+    )
+  })
+
+  it('separates heading sections into sentences', () => {
+    expect(normalizeForSpeech('# One\nbody one\n\n# Two\nbody two')).toBe(
+      'One. body one. Two. body two',
+    )
+  })
+})
+
+describe('normalizeForSpeech — time guard (HH:MM:SS)', () => {
+  it('leaves a full HH:MM:SS timestamp as digits rather than half-reading it', () => {
+    expect(normalizeForSpeech('Done at 14:30:46 today')).toBe(
+      'Done at 14:30:46 today',
+    )
+  })
+
+  // `14:30:46` survives even an unguarded scan because `30` is not a legal
+  // HH. These are the timestamps whose TAIL is itself a legal HH:MM — the
+  // ones a missing lookbehind half-reads ("09:zero o'clock").
+  it('leaves an on-the-hour timestamp alone (lookbehind guard)', () => {
+    expect(normalizeForSpeech('t 09:00:00 z')).toBe('t 09:00:00 z')
+    expect(normalizeForSpeech('t 12:00:15 z')).toBe('t 12:00:15 z')
+    expect(normalizeForSpeech('t 01:02:03 y')).toBe('t 01:02:03 y')
+  })
+
+  it('still speaks a plain HH:MM clock time', () => {
+    expect(normalizeForSpeech('Meeting at 14:30 today')).toBe(
+      'Meeting at fourteen thirty today',
+    )
+    expect(normalizeForSpeech('at 9:05')).toBe("at nine oh five")
+  })
+})
+
+describe('normalizeForSpeech — thousands separators', () => {
+  it('speaks $1,000 as one thousand dollars (not "one dollar,000")', () => {
+    expect(normalizeForSpeech('It costs $1,000 up front')).toBe(
+      'It costs one thousand dollars up front',
+    )
+  })
+
+  it('speaks a millions-scale amount', () => {
+    expect(normalizeForSpeech('Budget $1,234,567 total')).toBe(
+      'Budget one million two hundred thirty-four thousand five hundred ' +
+        'sixty-seven dollars total',
+    )
+  })
+
+  it('does not regress plain currency or ordinary comma prose', () => {
+    expect(normalizeForSpeech('It costs $500')).toBe('It costs five hundred dollars')
+    expect(normalizeForSpeech('$5.50 each')).toBe('five dollars fifty each')
+    expect(normalizeForSpeech('a, b, 3')).toBe('a, b, 3')
+    expect(normalizeForSpeech('We saw 12,500 requests')).toBe(
+      'We saw 12,500 requests',
+    )
+  })
+
+  // The thousands guard must not mistake an ordinary SENTENCE comma for a
+  // partial digit group — that left a raw "$" unspoken.
+  it('still speaks currency followed by a sentence comma', () => {
+    expect(normalizeForSpeech('It costs $500, plus tax')).toBe(
+      'It costs five hundred dollars, plus tax',
+    )
+    expect(normalizeForSpeech('We paid $1,000, then left')).toBe(
+      'We paid one thousand dollars, then left',
+    )
+  })
+
+  it('still bails on a genuinely malformed amount', () => {
+    expect(normalizeForSpeech('$1,00 partial')).toBe('$1,00 partial')
+    expect(normalizeForSpeech('$5.203 odd')).toBe('$5.203 odd')
+  })
+})
+
+describe('normalizeForSpeech — file paths', () => {
+  it('speaks an absolute path as its last segment', () => {
+    expect(normalizeForSpeech('Check /var/log/syslog now')).toBe(
+      'Check syslog now',
+    )
+  })
+
+  it('handles ~/ and relative multi-segment paths', () => {
+    expect(normalizeForSpeech('Edit ~/.config/nvim/init.lua please')).toBe(
+      'Edit init.lua please',
+    )
+    expect(normalizeForSpeech('See src/telegram-plugin/gateway.ts')).toBe(
+      'See gateway.ts',
+    )
+  })
+
+  it('says "a path" when the final segment is unspeakable noise', () => {
+    expect(normalizeForSpeech('Path /tmp/a1b2c3d4e5f6a7b8 there')).toBe(
+      'Path a path there',
+    )
+  })
+
+  it('leaves a single-slash word/word pair for the downstream slash pass', () => {
+    expect(normalizeForSpeech('and/or maybe')).toBe('and/or maybe')
+  })
+
+  it('does not treat an all-numeric date as a path', () => {
+    expect(normalizeForSpeech('the date 12/25/2026 works')).toBe(
+      'the date 12/25/2026 works',
+    )
+  })
+
+  // "Two or more slashes ⇒ path" is false in English. Without a path-ish
+  // anchor the pass DELETES words from ordinary prose ("yes/no/maybe" →
+  // "maybe"). Each of these must survive verbatim for the downstream
+  // "word slash word" pass to speak.
+  it('never swallows a multi-slash PROSE run (no path anchor)', () => {
+    expect(normalizeForSpeech('yes/no/maybe')).toBe('yes/no/maybe')
+    expect(normalizeForSpeech('read/write/exec perms')).toBe(
+      'read/write/exec perms',
+    )
+    expect(normalizeForSpeech('he/she/they pronouns')).toBe(
+      'he/she/they pronouns',
+    )
+    expect(normalizeForSpeech('a client/server/proxy split')).toBe(
+      'a client/server/proxy split',
+    )
+    expect(normalizeForSpeech('reading input/output/error')).toBe(
+      'reading input/output/error',
+    )
+    expect(normalizeForSpeech('tests in unit/integration/e2e are green')).toBe(
+      'tests in unit/integration/e2e are green',
+    )
+  })
+})
+
+describe('normalizeForSpeech — extended acronym set', () => {
+  it('spells the newly-added initialisms letter-by-letter', () => {
+    expect(normalizeForSpeech('use HTTPS not HTTP')).toBe('use H T T P S not H T T P')
+    expect(normalizeForSpeech('over SSH via DNS')).toBe('over S S H via D N S')
+    expect(normalizeForSpeech('the CLI on AWS at UTC')).toBe(
+      'the C L I on A W S at U T C',
+    )
+    expect(normalizeForSpeech('MCP PDF VM LLM YAML RAM USB ID OK')).toBe(
+      'M C P P D F V M L L M Y A M L R A M U S B I D O K',
+    )
+  })
+
+  it('still leaves word-style all-caps tokens alone', () => {
+    expect(normalizeForSpeech('NASA ALWAYS SHOUTING')).toBe('NASA ALWAYS SHOUTING')
+  })
+})

package/telegram-plugin/tts-normalize.ts

@@ -292,10 +292,12 @@ export function normalizeForTts(text: string): string {
     return words.join(' ')
   })
 
-  // -- Times HH:MM (24h) → spoken. The (?!:?\d) guard skips HH:MM:SS
-  //    entirely — a half-spoken time with a dangling ":46" reads worse
-  //    than leaving the digits as-is.
-  s = s.replace(/\b([01]?\d|2[0-3]):([0-5]\d)(?!:?\d)/g, (_m, hh: string, mm: string) => {
+  // -- Times HH:MM (24h) → spoken. The (?<![\d:]) / (?!:?\d) guards skip
+  //    HH:MM:SS entirely — a half-spoken time with a dangling ":46" reads
+  //    worse than leaving the digits as-is. The LOOKBEHIND is load-bearing:
+  //    without it the scan re-anchors INSIDE the timestamp (`09:00:00` →
+  //    "09:zero o'clock") because the trailing `00` is itself a legal HH:MM.
+  s = s.replace(/(?<![\d:])\b([01]?\d|2[0-3]):([0-5]\d)(?!:?\d)/g, (_m, hh: string, mm: string) => {
     const h = Number(hh)
     const min = Number(mm)
     const hw = belowThousand(h)

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

@@ -29,6 +29,14 @@
  *     ambiguous (strikethrough marker vs. approx) and dropping is the safest
  *     choice that never mangles a real word.
  *   - `->` / `=>` / `→` become the spoken word "to".
+ *   - Block boundaries (headings, bullets, ordered items) become SENTENCE
+ *     boundaries: the marker is replaced with terminating punctuation so a
+ *     multi-bullet reply is spoken as separate sentences with breath between
+ *     them, instead of the newline-collapse fusing it into one run-on.
+ *   - A multi-segment filesystem path (`/var/log/syslog`, `~/.config/x/y`,
+ *     `a/b/c`) is spoken as its LAST segment, or "a path" when that segment
+ *     is unspeakable noise. A single `word/word` is prose and is left for the
+ *     downstream "word slash word" pass in normalizeForTts.
  *   - A tiny, well-tested set of trivially-safe abbreviations is expanded
  *     ("e.g." → "for example", "i.e." → "that is", "etc." → "and so on",
  *     "vs" → "versus", "approx" → "approximately", "w/" → "with").
@@ -237,12 +245,141 @@ const UNIT_MAP: Record<string, { s: string; p: string }> = {
   tb: { s: 'terabyte', p: 'terabytes' },
 }
 
-/** Curated initialisms spoken letter-by-letter. Uppercase keys only. */
+/**
+ * Curated initialisms spoken letter-by-letter. Uppercase keys only.
+ *
+ * Only tokens in this set are ever expanded, so widening the set is safe:
+ * word-style acronyms (NASA, ALWAYS) still fall through untouched because the
+ * generic all-caps matcher consults this map before doing anything.
+ */
 const ACRONYMS = new Set([
   'CI', 'PR', 'API', 'URL', 'GPU', 'CPU', 'TTS', 'STT', 'HTTP', 'JSON',
   'SQL', 'UI',
+  // Common in agent replies; previously read as nonsense words ("hoops",
+  // "duh-ness", "mick-p") by the engine.
+  'HTTPS', 'SSH', 'DNS', 'CLI', 'AWS', 'UTC', 'MCP', 'PDF', 'ID', 'OK',
+  'VM', 'LLM', 'YAML', 'RAM', 'USB',
 ])
 
+/** Longest key in ACRONYMS — the all-caps matcher's upper length bound. */
+const ACRONYM_MAX_LEN = Math.max(...[...ACRONYMS].map((a) => a.length))
+
+/**
+ * A filesystem-path-shaped token: two or more `/`-separated segments, with an
+ * optional leading segment (`a/b/c`), `~` (`~/.config/foo`) or nothing
+ * (`/var/log/syslog`). Requiring TWO separators is deliberate — a single
+ * `word/word` is prose ("and/or") and is left for the downstream
+ * "word slash word" pass in tts-normalize.
+ */
+const PATH_TOKEN_RE =
+  /(?<![\w~./-])(?:~|\.{1,2}|[A-Za-z0-9_.@-]+)?(?:\/[A-Za-z0-9_.@+-]+){2,}\/?(?![\w/-])/g
+
+/**
+ * A path-shaped token needs an ANCHOR before we may swallow it: a leading
+ * `/`, `./`, `../` or `~/`, or a final segment carrying a file extension.
+ * "Two or more slashes ⇒ path" is false in English — `yes/no/maybe`,
+ * `read/write/exec`, `he/she/they`, `client/server/proxy` and
+ * `unit/integration/e2e` are all prose, and swallowing them DELETES words
+ * from the reply. Anything that is only a run of ordinary lowercase
+ * word-shaped segments is left for the downstream "word slash word" pass.
+ */
+function looksLikePath(m: string, segs: string[]): boolean {
+  if (/^(?:\/|\.{1,2}\/|~\/)/.test(m)) return true
+  const last = segs[segs.length - 1]!
+  if (/\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(last)) return true
+  // Every segment an ordinary lowercase word (letters, then optional digits)
+  // ⇒ prose, not a path.
+  return !segs.every((sg) => /^[a-z][a-z0-9]*$/.test(sg))
+}
+
+/** True when a path segment is worth speaking (a real name, not a blob). */
+function isSpeakableSegment(seg: string): boolean {
+  if (!/[A-Za-z]/.test(seg)) return false
+  if (seg.length > 32) return false
+  // A hex blob (sha, uuid chunk) reads as noise; prefer "a path".
+  if (/^[0-9a-f]{8,}$/i.test(seg)) return false
+  return true
+}
+
+/**
+ * Speak a filesystem path as just its final segment ("/var/log/syslog" →
+ * "syslog"), or "a path" when that segment carries no speakable name. Reading
+ * a full path aloud is the worst kind of TTS noise — a long run of "slash"
+ * between unpronounceable fragments. An all-numeric token run (a date like
+ * `12/25/2026`) is explicitly NOT a path and is returned untouched.
+ */
+function speakPaths(input: string): string {
+  return input.replace(PATH_TOKEN_RE, (m) => {
+    const segs = m.split('/').filter((sg) => sg.length > 0)
+    if (segs.length < 2) return m
+    if (segs.every((sg) => /^\d+$/.test(sg))) return m
+    if (!looksLikePath(m, segs)) return m
+    const last = segs[segs.length - 1]!
+    return isSpeakableSegment(last) ? last : 'a path'
+  })
+}
+
+/** A line whose leading markup starts a new block (heading / list item). */
+const BLOCK_MARKER_RE = /^[ \t]{0,3}(?:#{1,6}[ \t]+|[-*+][ \t]+|\d+[.)][ \t]+)/
+/** Heading subset — a heading never has continuation lines. */
+const HEADING_MARKER_RE = /^[ \t]{0,3}#{1,6}[ \t]+/
+
+/** Give a line sentence-terminating punctuation without doubling it. */
+function ensureTerminated(line: string): string {
+  const t = line.replace(/[ \t]+$/, '')
+  if (!t.trim()) return t
+  // Already terminal (or a natural pause) — leave it, never emit ".." / ". .".
+  if (/[.!?:;]$/.test(t)) return t
+  // A trailing comma at a block boundary is an artifact of list formatting.
+  if (/,$/.test(t)) return `${t.slice(0, -1)}.`
+  return `${t}.`
+}
+
+/**
+ * Strip heading / list markers AND turn each block boundary into a sentence
+ * boundary. Without this the later newline-collapse joins every bullet into
+ * one breathless run-on sentence — the single biggest voice-pacing complaint.
+ *
+ * A wrapped list item (a continuation line carrying no marker of its own) is
+ * terminated only at the END of the unit, so a sentence split across two
+ * source lines is not chopped mid-clause. The line immediately BEFORE a block
+ * starts is terminated too, so "Steps" + bullets doesn't read as
+ * "Steps first".
+ */
+function applyBlockPauses(input: string): string {
+  const lines = input.split('\n')
+  const isBlock = lines.map((l) => BLOCK_MARKER_RE.test(l))
+  const isHeading = lines.map((l) => HEADING_MARKER_RE.test(l))
+  const stripped = lines.map((l, i) =>
+    isBlock[i] ? l.slice(l.match(BLOCK_MARKER_RE)![0].length) : l,
+  )
+  // A line is "inside a block unit" if it starts one, or continues one. A
+  // heading owns exactly its own line — the prose under it is a new unit.
+  const inUnit: boolean[] = []
+  for (let i = 0; i < stripped.length; i++) {
+    inUnit[i] =
+      isBlock[i] === true ||
+      (i > 0 &&
+        inUnit[i - 1] === true &&
+        isHeading[i - 1] !== true &&
+        stripped[i]!.trim() !== '')
+  }
+  return stripped
+    .map((line, i) => {
+      const next = stripped[i + 1]
+      const nextIsBlock = isBlock[i + 1] === true
+      const unitEndsHere =
+        isHeading[i] === true ||
+        next === undefined ||
+        next.trim() === '' ||
+        nextIsBlock
+      if (inUnit[i] && unitEndsHere) return ensureTerminated(line)
+      if (nextIsBlock && line.trim() !== '') return ensureTerminated(line)
+      return line
+    })
+    .join('\n')
+}
+
 /**
  * Convert a Markdown/plain reply into clean text for a TTS engine.
  * Pure and deterministic — same input always yields the same output.
@@ -277,7 +414,12 @@ export function normalizeForSpeech(input: string): string {
     /[\u{1F000}-\u{1FAFF}\u{1F1E6}-\u{1F1FF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE00}-\u{FE0F}\u{200D}\u{2B50}\u{3030}\u{303D}\u{3297}\u{3299}\u{24C2}]/gu,
     '',
   )
-  s = s.replace(/:([a-z0-9][a-z0-9_+-]*):/gi, ' ')
+  //    Digit-bodied shortcodes are real (`:100:`, `:8ball:`,
+  //    `:1st_place_medal:`), so the body may start with a digit — the
+  //    timestamp protection is positional instead: the opening colon may not
+  //    follow a digit/colon and the closing colon may not precede a digit, so
+  //    the pass can never eat the colons out of `14:30:46`.
+  s = s.replace(/(?<![\w:]):([a-z0-9][a-z0-9_+-]*):(?!\d)/gi, ' ')
 
   // 1. Fenced code blocks first (```lang … ``` or ~~~ … ~~~) — drop the
   //    whole block before any inline processing can see its contents.
@@ -301,6 +443,11 @@ export function normalizeForSpeech(input: string): string {
   // Any residual backticks → drop.
   s = s.replace(/`/g, '')
 
+  // 5b. Filesystem paths → their last segment. Runs before the block/symbol
+  //     passes (and before the downstream "word slash word" pass in
+  //     normalizeForTts) so a path is never spelled out slash-by-slash.
+  s = speakPaths(s)
+
   // 6. Emphasis markers. Paired forms first (longest marker first), then
   //    strip residual markup-by-construction doubles. A LONE `*` or `_` in
   //    the middle of maths/words is left alone (see step 11).
@@ -316,10 +463,8 @@ export function normalizeForSpeech(input: string): string {
   // 7. Leading block markup, per line: headings, blockquotes, list markers.
   //    List bullets/numbers become a natural sentence pause rather than a
   //    spoken "dash" / "1 dot".
-  s = s.replace(/^[ \t]{0,3}#{1,6}[ \t]+/gm, '')
   s = s.replace(/^[ \t]{0,3}>[ \t]?/gm, '')
-  s = s.replace(/^[ \t]{0,3}[-*+][ \t]+/gm, '')
-  s = s.replace(/^[ \t]{0,3}\d+[.)][ \t]+/gm, '')
+  s = applyBlockPauses(s)
 
   // 8. Horizontal rules (---, ___, ***) on their own line → drop.
   s = s.replace(/^[ \t]{0,3}([-_*])\1{2,}[ \t]*$/gm, '')
@@ -360,7 +505,12 @@ export function normalizeForSpeech(input: string): string {
   })
   //     Clock time HH:MM (24h ok) → spoken. Guarded by word boundaries so a
   //     ratio like "3:2" or a bare number isn't caught (needs 2-digit MM).
-  s = s.replace(/\b([01]?\d|2[0-3]):([0-5]\d)\b/g, (m, hh, mm) => {
+  //     The (?<![\d:]) / (?!:?\d) guards skip HH:MM:SS entirely (parity with
+  //     normalizeForTts) — a half-spoken time with a dangling ":46" reads
+  //     worse than leaving the digits as-is. The LOOKBEHIND is load-bearing:
+  //     without it the scan re-anchors INSIDE the timestamp (`09:00:00` →
+  //     "09:zero o'clock") because the trailing `00` is itself a legal HH:MM.
+  s = s.replace(/(?<![\d:])\b([01]?\d|2[0-3]):([0-5]\d)(?!:?\d)/g, (m, hh, mm) => {
     const h = Number(hh)
     const min = Number(mm)
     const hw = belowThousand(h)
@@ -370,11 +520,18 @@ export function normalizeForSpeech(input: string): string {
 
   // 14. Numbers, units & symbols → spoken words. Each sub-pass is guarded so
   //     it only fires on a clear number+token, never mid-word.
-  //     Currency: $5 / $5.50 → "five dollars" / "five dollars fifty".
-  s = s.replace(/\$(\d{1,9})(?:\.(\d{2}))?\b/g, (m, dollars, cents) => {
-    const dw = numberToWords(Number(dollars))
+  //     Currency: $5 / $5.50 → "five dollars" / "five dollars fifty";
+  //     $1,000 → "one thousand dollars" (thousands separators consumed, so
+  //     the old "one dollar,000" misreading is impossible). The trailing
+  //     lookahead bails on odd cents ("$5.203") and partial thousands
+  //     ("$1,00") — the whole token is left unchanged rather than half-read.
+  //     The guard must NOT fire on an ordinary sentence comma ("$500, plus
+  //     tax") — only on a comma/period that STARTS another digit group.
+  s = s.replace(/\$(\d{1,3}(?:,\d{3})+|\d{1,9})(?:\.(\d{2}))?(?!\d|[.,]\d)/g, (m, dollarsRaw, cents) => {
+    const dollars = Number(String(dollarsRaw).replace(/,/g, ''))
+    const dw = numberToWords(dollars)
     if (!dw) return m
-    const noun = Number(dollars) === 1 && !cents ? 'dollar' : 'dollars'
+    const noun = dollars === 1 && !cents ? 'dollar' : 'dollars'
     if (cents && cents !== '00') {
       const cw = numberToWords(Number(cents))
       return `${dw} ${noun} ${cw}`
@@ -419,7 +576,7 @@ export function normalizeForSpeech(input: string): string {
   // 15. Acronyms → letter-by-letter for a curated set of initialisms. Only a
   //     standalone all-caps token that exactly matches the map is expanded;
   //     word-style acronyms (NASA) and sub-tokens of larger words are left.
-  s = s.replace(/\b[A-Z]{2,5}\b/g, (tok) =>
+  s = s.replace(new RegExp(`\\b[A-Z]{2,${ACRONYM_MAX_LEN}}\\b`, 'g'), (tok) =>
     ACRONYMS.has(tok) ? tok.split('').join(' ') : tok,
   )
 

package/vendor/hindsight-memory/CHANGELOG.md

@@ -4,6 +4,79 @@
 
 ### Changed (switchroom divergence)
 
+- **`MAX_DIRECTIVES` 15 → 30, and truncation is no longer SILENT**
+  (`scripts/lib/directives.py`). Live fleet active-directive counts were 24
+  (assistant), 17 (klanker), 15 (carrie) against a client-side cap of 15, so the
+  busiest bank had 9 of its hard rules dropped from every turn's prompt with no
+  signal anywhere: the `(+N more, omitted)` footer only tells the AGENT. 30
+  clears the observed fleet maximum with headroom while staying bounded (the
+  block is injected on EVERY turn — this is a per-turn token cost, not a free
+  knob; the constant is commented as such). `format_active_directives_block`
+  now also prints a `[Hindsight] directive truncation: …` warn line to stderr
+  whenever it drops directives, and `recall.py` records the dropped count as
+  `directives_omitted` on the recall_log row.
+
+  Visibility correction (2026-07-25 review): hook stderr is NOT an operator
+  channel. `docker logs --tail 20000` across all 12 live agent containers
+  returns ZERO `[Hindsight]` lines, and nothing under `~/.switchroom/logs/`
+  contains them either, despite months of runtime and several long-standing
+  stderr paths in `recall.py` — Claude Code swallows hook stderr on a zero
+  exit. The stderr line is kept as a last-resort breadcrumb; the channels that
+  actually reach an operator are the `directives_omitted` recall_log field and
+  `switchroom doctor`'s directive-count row. Paired switchroom-side:
+  `src/cli/doctor-memory.ts` `MAX_DIRECTIVES` 15 → 30 and
+  `DIRECTIVE_WARN_THRESHOLD` 12 → 24 (a drift-guard test pins the TS constant
+  to the Python one). The `MAX_DIRECTIVES` cost comment now states the real
+  mechanism (rebuilt every `UserPromptSubmit`, appended into the conversation,
+  so cost is per-turn CUMULATIVE) with the measured live figures. Acceptance:
+  `scripts/tests/test_directives.py`
+  (`test_cap_is_30_and_clears_the_observed_fleet_maximum`,
+  `test_truncation_emits_a_stderr_breadcrumb_naming_the_dropped_count`,
+  `test_count_omitted_directives_matches_the_rendered_footer`).
+
+- **`retainMission` rewritten with explicit, enumerated exclusions**
+  (`settings.json`). The extraction model is a small local `gpt-oss-20b`, and
+  the previous one-line "Ignore routine greetings and transient operational
+  details" did not hold: production banks contain pure transcript traces
+  ("The assistant used ToolSearch to query for hindsight bank statistics"),
+  hindsight's own batch failures with the UUID inline, restatements of the
+  then-current prompt, and undated transient state ("User has no unread mail",
+  which then recalls forever as a standing fact). The new mission enumerates
+  those noise classes as NEVER-extract bullets and adds a positive
+  counterweight ("a preference revealed by a request is durable") — without it,
+  an exclusion-only mission made the model return a degenerate/empty response
+  on chatty-but-real turns in a 6-window live sample. The text is pinned
+  byte-for-byte to switchroom's `DEFAULT_RETAIN_MISSION`
+  (`src/memory/hindsight.ts`) by a drift guard, because BOTH reach the same
+  extraction step: switchroom seeds the bank-side mission at scaffold, and the
+  plugin independently pushes this one via `lib/bank.py: ensure_bank_mission`
+  on a fresh state dir. Before this change the two texts differed.
+
+  One 2026-07-25 review correction folded in, itself corrected by the
+  re-review: the rewrite DID reach existing agents, but unsafely.
+  `ensure_bank_mission` short-circuits on the already-seeded flag in
+  `bank_missions.json`, so the plugin was never the propagation path — but
+  `switchroom apply` re-scaffolds every agent, and scaffold pushed
+  `retain_mission` unconditionally on every run. That is why all 24 live banks
+  carried the 2026-07-19 text even though no agent sets `retain_mission` in
+  yaml. The hazard was the unconditional overwrite, not a stuck mission.
+  Switchroom now routes BOTH of its bank-op sites (scaffold and
+  `reconcileAgent`) through `decideRetainMissionUpgrade`: the mission upgrades
+  only when the bank's current text byte-equals a known previous default
+  (`SUPERSEDED_RETAIN_MISSIONS`) or is unset, so a customized mission matches
+  nothing and is never clobbered.
+
+  A second proposed correction — narrowing the "Greetings, acknowledgements,
+  and routine operational chatter" bullet and adding a personal-preference
+  clause — was written and then REVERTED. Sampling did not reproduce the
+  preference loss it was meant to fix, and the narrowed mission extracted MORE
+  noise than both this text and the pre-PR default on a real operational
+  window (8 facts vs 0 vs 4, including in-flight worker narration its own
+  bullet forbids). The sampling method is also n=1-unreliable: identical input
+  under the identical narrowed mission gave 0, 6, 6. No extraction-quality
+  claim is made here in either direction; the mission-content question is
+  deferred to switchroom#3532 (profile-scoped retain missions).
+
 - **`recallContextTurns` default `1` → `2`** (switchroom hindsight-leverage
   PR2, workstream A2). A bare follow-up user message ("and the port?", "what
   about staging?") now embeds together with its antecedent human turn in the

package/vendor/hindsight-memory/scripts/lib/config.py

@@ -29,15 +29,20 @@ DEFAULTS = {
     # formatting. Set to 0 (or any non-positive value) to disable the cap
     # and inject everything Hindsight returns.
     "recallMaxMemories": 12,
-    # Switchroom-local: minimum lexical (Jaccard) overlap between the
+    # Switchroom-local: minimum lexical (containment) overlap between the
     # user's query terms and a memory's text terms. Memories below this
     # threshold are dropped before formatting. 0.0 disables the gate
     # (current behaviour: inject everything Hindsight returns up to the
     # count cap). NOTE: Hindsight's HTTP recall API DOES return per-result
     # relevance scores (`scores.final`, plus `.semantic`/`.keyword`/
     # `.reranker`) — verified at runtime — and recall.py now reads and
-    # sorts the merged set by `scores.final`. This Jaccard gate is a
-    # separate lexical-overlap quality filter layered on top — see #475.
+    # sorts the merged set by `scores.final`. This lexical gate is a
+    # separate quality filter layered on top — see #475. The metric is
+    # containment, `|Q n M| / |M|`, not Jaccard: dividing by the union made
+    # the score a function of prompt length rather than relevance — see
+    # #3541 and recall.py's design note. At the 0.10 fleet default this is
+    # close to a passthrough (a <=10-token memory clears it on one shared
+    # word); precision is the engine rerank's job, not this gate's.
     "recallMinOverlap": 0.0,
     "recallTypes": ["world", "experience"],
     # Switchroom-local: when True (default; Ken-approved ON) recall biases