switchroom 0.16.29 → 0.16.46

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

@@ -36,126 +36,38 @@
 // plain-English description or a domain label. This is the signal the
 // draft-mirror renders (option A: uniform across code + non-code agents).
 
-/** Strip a path to its basename for display. */
-function baseName(p: unknown): string | null {
-  if (typeof p !== "string" || p.length === 0) return null;
-  const parts = p.split("/").filter(Boolean);
-  return parts.length > 0 ? parts[parts.length - 1] : p;
-}
-
-/** Extract a bare hostname from a URL for display (no scheme/path). */
-function hostName(u: unknown): string | null {
-  if (typeof u !== "string" || u.length === 0) return null;
-  try {
-    return new URL(u).hostname.replace(/^www\./, "");
-  } catch {
-    return u.replace(/^https?:\/\//, "").split("/")[0] || null;
-  }
-}
-
-function clip(s: unknown, n: number): string | null {
-  if (typeof s !== "string") return null;
-  const t = s.trim();
-  if (t.length === 0) return null;
-  return t.length > n ? t.slice(0, n - 1) + "…" : t;
-}
+// (The per-tool wording helpers — basename/hostname/clip — live with the one
+// composer in hooks/tool-label-pretool.mjs. See describeToolUse below.)
+import { computeLabel } from './hooks/tool-label-pretool.mjs'
 
 /**
  * Render a single tool_use into a human-friendly, present-tense activity
  * line for the live draft preview — or null when the tool should NOT be
  * surfaced (the Telegram-plugin surface tools, which ARE the conversation).
  *
- * Leads with the model-authored descriptive field per the map above; falls
- * back to a domain label, then to a humanized tool name. Never emits raw
- * shell/query syntax.
+ * SINGLE-COMPOSER RULE: the wording itself lives in ONE place —
+ * `computeLabel` in hooks/tool-label-pretool.mjs, the same function the
+ * real-time PreToolUse sidecar runs at tool-call time. This function is a
+ * thin delegating wrapper, NOT a second vocabulary: before the delegation
+ * the two tables had drifted (Grep "Searching . for X" vs "Searching for
+ * X", WebFetch "Fetching host/path" vs "Reading host", retain "Saving
+ * memory" vs "Saving to memory"), so the live feed and the flush-time /
+ * nested-sub-agent / worker-card lines rendered the SAME action with
+ * different copy — the wording drift the know-what-my-agent-is-doing spec
+ * bars. `status-vocabulary-unification.test.ts` pins the delegation; do not
+ * re-fork the table here.
  */
 export function describeToolUse(
   toolName: string,
   input: Record<string, unknown> | undefined,
 ): string | null {
   if (!toolName) return null;
-  const inp = input ?? {};
-
-  const mcpMatch = /^mcp__(.+?)__(.+)$/.exec(toolName);
-  if (mcpMatch) {
-    const server = mcpMatch[1].toLowerCase();
-    const tool = mcpMatch[2].toLowerCase();
-    // Surface tools ARE the conversation — never mirror them.
-    // Use isTelegramSurfaceTool (regex-based, key-agnostic) so forks/renames work.
-    if (isTelegramSurfaceTool(toolName)) return null;
-    if (server === "hindsight") {
-      if (tool === "recall" || tool === "reflect") return "Searching memory";
-      if (tool === "retain" || tool === "update_memory" || tool === "sync_retain")
-        return "Saving to memory";
-      return "Working with memory";
-    }
-    if (
-      server === "google-workspace" ||
-      server === "claude_ai_google_calendar"
-    ) {
-      return "Checking your calendar";
-    }
-    if (server === "claude_ai_gmail") return "Checking your email";
-    if (server === "claude_ai_google_drive") return "Looking through your files";
-    if (server === "notion" || server === "claude_ai_notion") {
-      return "Checking your notes";
-    }
-    // Unknown MCP tool: prefer a model-authored field, else a humanized name.
-    const desc = clip(inp.description, 60) ?? clip(inp.query, 50) ?? clip(inp.title, 50);
-    if (desc) return desc;
-    return "Using " + tool.replace(/[-_]+/g, " ");
-  }
-
-  switch (toolName) {
-    case "Bash": {
-      // The model writes a plain-English description for every command.
-      return clip(inp.description, 70) ?? "Running a command";
-    }
-    case "BashOutput":
-    case "KillShell":
-      return "Managing a background command";
-    case "Read": {
-      const f = baseName(inp.file_path);
-      return f ? `Reading ${f}` : "Reading a file";
-    }
-    case "Edit":
-    case "MultiEdit":
-    case "NotebookEdit": {
-      const f = baseName(inp.file_path) ?? baseName(inp.notebook_path);
-      return f ? `Editing ${f}` : "Editing a file";
-    }
-    case "Write": {
-      const f = baseName(inp.file_path);
-      return f ? `Writing ${f}` : "Writing a file";
-    }
-    case "Grep":
-    case "Glob": {
-      const p = clip(inp.pattern, 40);
-      return p ? `Searching for ${p}` : "Searching files";
-    }
-    case "WebFetch": {
-      const h = hostName(inp.url);
-      return h ? `Reading ${h}` : "Reading a web page";
-    }
-    case "WebSearch": {
-      const q = clip(inp.query, 50);
-      return q ? `Searching the web for ${q}` : "Searching the web";
-    }
-    case "Task":
-    case "Agent": {
-      const d = clip(inp.description, 60);
-      return d ? `Delegating: ${d}` : "Delegating to a sub-agent";
-    }
-    case "TodoWrite":
-    case "TaskCreate":
-    case "TaskUpdate":
-    case "TaskList":
-      return "Updating the plan";
-    case "ToolSearch":
-      return "Finding the right tool";
-    default:
-      return "Working…";
-  }
+  // Surface tools ARE the conversation — never mirror them. computeLabel
+  // suppresses these too (its own key-agnostic regex); this guard stays as
+  // the TS-side belt so a hook-side refactor can't leak a reply label into
+  // the feed.
+  if (isTelegramSurfaceTool(toolName)) return null;
+  return computeLabel(toolName, input ?? {});
 }
 
 // ─── Accumulating activity feed (draft-mirror Phase 2) ──────────────────────
@@ -177,7 +89,7 @@ import {
   STATUS_LINE_MAX,
   NESTED_PREFIX,
 } from './status-no-truncate.js'
-import { escapeMarkdown, stripMarkdown, truncate } from './card-format.js'
+import { escapeMarkdown, stripMarkdown, truncate, stackCardLines } from './card-format.js'
 import { isTelegramSurfaceTool } from './tool-names.js'
 
 /**
@@ -304,7 +216,7 @@ function escapeStepLine(raw: string): string {
  *
  * `out`        — accumulator mutated in place
  * `steps`      — pre-cleaned + pre-escaped HTML step strings
- * `allDone`    — when true ALL steps render done (✓ italic); when false the
+ * `allDone`    — when true ALL steps render done (✓ struck italic); when false the
  *                newest renders in-progress (→ bold)
  * `liveSuffix` — appended INSIDE the newest in-progress line (heartbeat tick)
  */
@@ -320,7 +232,7 @@ export function renderStepFeed(
   if (hidden > 0) out.push(`_✓ +${hidden} earlier…_`)
   const lastIdx = shown.length - 1
   shown.forEach((s, i) => {
-    out.push(!allDone && i === lastIdx ? `**→ ${s}${liveSuffix}**` : `_✓ ${s}_`)
+    out.push(!allDone && i === lastIdx ? `**→ ${s}${liveSuffix}**` : `~~_✓ ${s}_~~`)
   })
 }
 
@@ -400,7 +312,7 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
     const shownParent = steps.slice(-STATUS_ROLLING_LINES)
     const hiddenParent = steps.length - shownParent.length
     if (hiddenParent > 0) out.push(`_✓ +${hiddenParent} earlier…_`)
-    for (const s of shownParent) out.push(`_✓ ${s}_`)
+    for (const s of shownParent) out.push(`~~_✓ ${s}_~~`)
     // Child block.
     const shownChild = children.slice(-STATUS_ROLLING_LINES)
     const hiddenChild = children.length - shownChild.length
@@ -410,7 +322,7 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
       out.push(
         i === lastChildIdx && !final
           ? `${NESTED_PREFIX}**→ ${s}${liveSuffix}**`
-          : `${NESTED_PREFIX}_${s}_`,
+          : `${NESTED_PREFIX}~~_${s}_~~`,
       )
     })
   } else {
@@ -429,7 +341,10 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
   // out always carries the two header lines, so it is never empty — but guard
   // against a degenerate header-less future caller.
   if (out.length === 0) return null
-  const joined = out.join('\n')
+  // Stack lines with GFM hard breaks (`  \n`) so the card's styled prose lines
+  // don't collapse onto one visual line in the rich-message renderer — see
+  // stackCardLines. This is what makes a card render identically to a reply.
+  const joined = stackCardLines(out)
   if (joined.length <= STATUS_CARD_CHAR_BUDGET) return joined
   return fitCardToBudget(opts, headerLines)
 }
@@ -482,7 +397,7 @@ function fitCardToBudget(opts: StatusCardOpts, headerLines: string[]): string {
     const lastIdx = shown.length - 1
     shown.forEach((esc, i) => lines.push(buildBullet(esc, i === lastIdx)))
     lines.push(...footerLines)
-    const candidate = lines.join('\n')
+    const candidate = stackCardLines(lines)
     if (candidate.length <= STATUS_CARD_CHAR_BUDGET) return candidate
   }
 
@@ -508,7 +423,7 @@ function fitCardToBudget(opts: StatusCardOpts, headerLines: string[]): string {
   if (parentMarker != null) lines.push(parentMarker)
   lines.push(newestLine)
   lines.push(...footerLines)
-  return lines.join('\n')
+  return stackCardLines(lines)
 }
 
 /**

package/telegram-plugin/tts-normalize.ts

@@ -0,0 +1,377 @@
+/**
+ * tts-normalize.ts — deterministic L1 text-normalization front-end for
+ * the voice sidecar (issue #2760, Phase 1).
+ *
+ * Kokoro ships almost no text normalization, so raw agent text (markdown,
+ * symbols, numbers, currency, emoji, URLs, code) gets read literally and
+ * sounds unnatural. This module is a PURE string→string pass applied in
+ * the gateway voice-out path immediately before the `POST /tts` body is
+ * built, mirroring the `text-voice-scrub.ts` precedent: deterministic
+ * transform, code-region park/restore, kill-switch env var, no network,
+ * no LLM (Phase 2 adds the optional local-LLM layer).
+ *
+ * It runs AFTER `normalizeForSpeech` (which already strips most markdown
+ * on the plan-building path) and is deliberately idempotent/overlapping
+ * with it: the Listen lazy path synthesizes from a persisted cache whose
+ * entries may predate normalizeForSpeech coverage, and this stage is the
+ * last line of defence at the actual /tts body build. Rules where both
+ * passes apply are no-ops the second time.
+ *
+ * Gating: ON BY DEFAULT (operator decision 2026-07-04 — Phase 1 ships
+ * default-on). The only gate is the kill switch:
+ * `SWITCHROOM_DISABLE_TTS_NORMALIZE=1` returns the input byte-identical —
+ * same shape as `SWITCHROOM_DISABLE_VOICE_SCRUB`; rollback is one env var.
+ *
+ * Rules (en locale, deterministic, conservative — when unsure, pass
+ * text through unchanged):
+ *   - Markdown: bold/italic/strike markers removed; headings → plain;
+ *     links → link text; bare URLs → spoken domain ("github dot com
+ *     link"); list markers dropped; tables → "table omitted"; code
+ *     fences → "code block omitted"; inline code read as-is without
+ *     backticks (content is parked so number/symbol expansion can never
+ *     mangle an identifier).
+ *   - Emoji: stripped (a small map speaks the common ones).
+ *   - Numbers: currency ($5.20 → "five dollars twenty"), percentages,
+ *     ordinals (3rd → "third"), times (14:30), ISO dates, phone-like
+ *     digit runs read digit-by-digit, units (km, GB, ms, …).
+ *   - Symbols: & → and, @ → at, # → hash, word/word → "word slash word",
+ *     ~5 → "about 5", > blockquote markers dropped.
+ */
+
+const NULL = '\x00'
+const INLINE_PH = `${NULL}TN_INLINE`
+
+/** On by default; the kill switch is the only gate. */
+export function ttsNormalizeEnabled(): boolean {
+  const kill = process.env.SWITCHROOM_DISABLE_TTS_NORMALIZE
+  return !(kill === '1' || kill === 'true')
+}
+
+// ---------------------------------------------------------------------------
+// Number → words (English cardinal, 0..999,999,999; larger stays digits so we
+// never emit a wrong reading).
+// ---------------------------------------------------------------------------
+const ONES = [
+  'zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight',
+  'nine', 'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen',
+  'sixteen', 'seventeen', 'eighteen', 'nineteen',
+]
+const TENS = [
+  '', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy',
+  'eighty', 'ninety',
+]
+
+function belowThousand(n: number): string {
+  if (n < 20) return ONES[n]!
+  if (n < 100) {
+    const t = TENS[Math.floor(n / 10)]!
+    const o = n % 10
+    return o ? `${t}-${ONES[o]}` : t
+  }
+  const h = `${ONES[Math.floor(n / 100)]} hundred`
+  const rest = n % 100
+  return rest ? `${h} ${belowThousand(rest)}` : h
+}
+
+function numberToWords(n: number): string | null {
+  if (!Number.isInteger(n) || n < 0 || n > 999_999_999) return null
+  if (n === 0) return 'zero'
+  const parts: string[] = []
+  const millions = Math.floor(n / 1_000_000)
+  const thousands = Math.floor((n % 1_000_000) / 1000)
+  const rest = n % 1000
+  if (millions) parts.push(`${belowThousand(millions)} million`)
+  if (thousands) parts.push(`${belowThousand(thousands)} thousand`)
+  if (rest) parts.push(belowThousand(rest))
+  return parts.join(' ')
+}
+
+/** Ordinal words for 0..99 ("third", "twenty-first"). null out of range. */
+function ordinalToWords(n: number): string | null {
+  if (!Number.isInteger(n) || n < 0 || n > 99) return null
+  const IRREGULAR: Record<number, string> = {
+    0: 'zeroth', 1: 'first', 2: 'second', 3: 'third', 5: 'fifth',
+    8: 'eighth', 9: 'ninth', 12: 'twelfth',
+  }
+  if (IRREGULAR[n]) return IRREGULAR[n]
+  if (n < 20) return `${ONES[n]}th`
+  const tens = Math.floor(n / 10)
+  const ones = n % 10
+  if (ones === 0) return `${TENS[tens]!.replace(/y$/, 'ie')}th`
+  return `${TENS[tens]}-${ordinalToWords(ones)}`
+}
+
+function yearToWords(y: number): string | null {
+  if (y < 1000 || y > 9999) return null
+  if (y >= 2000 && y < 2100) {
+    const lo = y % 100
+    return lo ? `two thousand ${belowThousand(lo)}` : 'two thousand'
+  }
+  const hi = Math.floor(y / 100)
+  const lo = y % 100
+  return lo === 0 ? `${belowThousand(hi)} hundred` : `${belowThousand(hi)} ${belowThousand(lo)}`
+}
+
+const MONTHS = [
+  '', 'January', 'February', 'March', 'April', 'May', 'June', 'July',
+  'August', 'September', 'October', 'November', 'December',
+]
+
+/** Unit suffixes → spoken units (singular/plural). Lowercased keys. */
+const UNIT_MAP: Record<string, { s: string; p: string }> = {
+  ms: { s: 'millisecond', p: 'milliseconds' },
+  s: { s: 'second', p: 'seconds' },
+  sec: { s: 'second', p: 'seconds' },
+  min: { s: 'minute', p: 'minutes' },
+  h: { s: 'hour', p: 'hours' },
+  hr: { s: 'hour', p: 'hours' },
+  d: { s: 'day', p: 'days' },
+  km: { s: 'kilometre', p: 'kilometres' },
+  m: { s: 'metre', p: 'metres' },
+  cm: { s: 'centimetre', p: 'centimetres' },
+  mm: { s: 'millimetre', p: 'millimetres' },
+  mi: { s: 'mile', p: 'miles' },
+  kg: { s: 'kilogram', p: 'kilograms' },
+  g: { s: 'gram', p: 'grams' },
+  kb: { s: 'kilobyte', p: 'kilobytes' },
+  mb: { s: 'megabyte', p: 'megabytes' },
+  gb: { s: 'gigabyte', p: 'gigabytes' },
+  tb: { s: 'terabyte', p: 'terabytes' },
+  ghz: { s: 'gigahertz', p: 'gigahertz' },
+  mhz: { s: 'megahertz', p: 'megahertz' },
+}
+
+/** Small spoken map for the most common emoji; everything else is dropped. */
+const EMOJI_SPOKEN: Record<string, string> = {
+  '👍': 'thumbs up',
+  '👎': 'thumbs down',
+  '✅': 'done',
+  '❤️': 'love',
+  '⚠️': 'warning',
+}
+
+/** Speak a URL's domain: "https://github.com/x/y" → "github dot com link". */
+function spokenUrl(url: string): string {
+  const m = /^https?:\/\/(?:www\.)?([^/\s:?#]+)/i.exec(url)
+  if (!m) return 'a link'
+  const host = m[1]!
+  // Only verbalize simple dotted hostnames; an IP or userinfo-laden host
+  // reads badly — fall back to "a link".
+  if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(host) || /^\d+\.\d+\.\d+\.\d+$/.test(host)) {
+    return 'a link'
+  }
+  return `${host.toLowerCase().split('.').join(' dot ')} link`
+}
+
+function parkInline(text: string): {
+  parked: string
+  parts: Array<{ idx: number; raw: string }>
+} {
+  const parts: Array<{ idx: number; raw: string }> = []
+  const parked = text.replace(/`([^`\n]+)`/g, (_m, content: string) => {
+    const idx = parts.length
+    // Park the CONTENT (backticks already dropped) so the spoken output
+    // reads the identifier as-is and no later pass can rewrite it.
+    parts.push({ idx, raw: content })
+    return `${INLINE_PH}${idx}${NULL}`
+  })
+  return { parked, parts }
+}
+
+function restoreInline(text: string, parts: Array<{ idx: number; raw: string }>): string {
+  let restored = text
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const p = parts[i]!
+    restored = restored.replace(`${INLINE_PH}${p.idx}${NULL}`, () => p.raw)
+  }
+  return restored
+}
+
+/**
+ * Normalize reply text for TTS. Pure + deterministic; returns the input
+ * unchanged when the feature flag is off, the kill switch is on, or the
+ * input is empty.
+ */
+export function normalizeForTts(text: string): string {
+  if (!ttsNormalizeEnabled() || text.length === 0) return text
+
+  let s = text.replace(/\r\n?/g, '\n')
+
+  // -- 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.')
+
+  // -- Park inline code (content spoken as-is, backticks gone).
+  const { parked, parts } = parkInline(s)
+  s = parked
+  s = s.replace(/`/g, '') // residual unpaired backticks
+
+  // -- Markdown tables → "table omitted." A table block = consecutive lines
+  //    with pipes that include a separator row (|---|---|).
+  s = s.replace(
+    /(?:^|\n)((?:[ \t]*\|[^\n]*\n)?[ \t]*\|?[ \t]*:?-{2,}:?[ \t]*(?:\|[ \t]*:?-{2,}:?[ \t]*)+\|?[ \t]*(?:\n[ \t]*\|[^\n]*)*)/g,
+    '\ntable omitted.',
+  )
+
+  // -- Images / links → text; autolinks + bare URLs → spoken domain.
+  s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+  s = s.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+  s = s.replace(/<(https?:\/\/[^>\s]+)>/gi, (_m, url: string) => spokenUrl(url))
+  s = s.replace(/\bhttps?:\/\/[^\s)]+/gi, (m) => spokenUrl(m))
+
+  // -- Emoji: speak the small common map, drop everything else.
+  for (const [emoji, spoken] of Object.entries(EMOJI_SPOKEN)) {
+    s = s.split(emoji).join(` ${spoken} `)
+  }
+  s = s.replace(
+    /[\u{1F000}-\u{1FAFF}\u{1F1E6}-\u{1F1FF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE00}-\u{FE0F}\u{200D}\u{2B50}]/gu,
+    '',
+  )
+
+  // -- Emphasis markers (paired forms, longest first), strikethrough.
+  s = s.replace(/\*\*\*(.+?)\*\*\*/g, '$1')
+  s = s.replace(/___(.+?)___/g, '$1')
+  s = s.replace(/\*\*(.+?)\*\*/g, '$1')
+  s = s.replace(/__(.+?)__/g, '$1')
+  s = s.replace(/\*(.+?)\*/g, '$1')
+  s = s.replace(/(?<![A-Za-z0-9])_(.+?)_(?![A-Za-z0-9])/g, '$1')
+  s = s.replace(/~~(.+?)~~/g, '$1')
+
+  // -- Block markup per line: headings, blockquote '>' markers, list
+  //    markers, horizontal rules.
+  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 = s.replace(/^[ \t]{0,3}([-_*])\1{2,}[ \t]*$/gm, '')
+
+  // -- ISO dates YYYY-MM-DD → "July fourth two thousand twenty-six".
+  //    MUST run before the phone-run pass (an ISO date is 8 digits with
+  //    hyphens and would otherwise be read digit-by-digit).
+  s = s.replace(/\b(\d{4})-(\d{2})-(\d{2})\b/g, (m, y: string, mo: string, da: string) => {
+    const month = Number(mo)
+    const day = Number(da)
+    if (month < 1 || month > 12 || day < 1 || day > 31) return m
+    const yw = yearToWords(Number(y))
+    const dw = ordinalToWords(day)
+    if (!yw || !dw) return m
+    return `${MONTHS[month]} ${dw} ${yw}`
+  })
+
+  // -- Phone-like digit runs → digit-by-digit. Fires ONLY on clearly
+  //    phone-shaped tokens: a leading + (international), or a leading 0
+  //    (national) with separator-delimited 2-4-digit grouping; 7-15
+  //    digits total. Ordinary space-separated numbers ("1024 2048 4096")
+  //    and short groupings without a phone prefix ("12 34 56 78") stay
+  //    untouched.
+  s = s.replace(/(?<![\w.])(\+?\d[\d\- ]{6,}\d)(?![\w.])/g, (m: string) => {
+    const digits = m.replace(/\D/g, '')
+    if (digits.length < 7 || digits.length > 15) return m
+    const groups = m.replace(/^\+/, '').split(/[- ]+/)
+    const phoneShaped =
+      m.startsWith('+') ||
+      (m.startsWith('0') &&
+        groups.length >= 2 &&
+        groups.every((g) => /^\d{2,4}$/.test(g)))
+    if (!phoneShaped) return m
+    const words: string[] = []
+    if (m.startsWith('+')) words.push('plus')
+    for (const ch of digits) words.push(ONES[Number(ch)]!)
+    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) => {
+    const h = Number(hh)
+    const min = Number(mm)
+    const hw = belowThousand(h)
+    if (min === 0) return `${hw} o'clock`
+    if (min < 10) return `${hw} oh ${ONES[min]}`
+    return `${hw} ${belowThousand(min)}`
+  })
+
+  // -- Currency: $5 → "five dollars"; $5.20 → "five dollars twenty";
+  //    $1,000 → "one thousand dollars" (thousands separators consumed).
+  //    The trailing lookahead bails on odd-cents ("$5.203") and partial
+  //    thousands ("$1,00") — the whole token is left unchanged rather
+  //    than half-read.
+  s = s.replace(
+    /\$(\d{1,3}(?:,\d{3})+|\d{1,9})(?:\.(\d{2}))?(?![\d,]|\.\d)/g,
+    (m, dollarsRaw: string, cents?: string) => {
+      const dollars = Number(dollarsRaw.replace(/,/g, ''))
+      const dw = numberToWords(dollars)
+      if (!dw) return m
+      const noun = dollars === 1 && !cents ? 'dollar' : 'dollars'
+      if (cents && cents !== '00') {
+        const cw = numberToWords(Number(cents))
+        if (!cw) return m
+        return `${dw} ${noun} ${cw}`
+      }
+      return `${dw} ${noun}`
+    },
+  )
+
+  // -- Percentages: 12% → "twelve percent"; 3.5% keeps digits + "percent".
+  s = s.replace(/\b(\d{1,9})%/g, (m, n: string) => {
+    const w = numberToWords(Number(n))
+    return w ? `${w} percent` : m
+  })
+  s = s.replace(/(\d)\s*%/g, '$1 percent')
+
+  // -- Ordinals: 3rd → "third" (guarded to matching suffix only).
+  s = s.replace(/\b(\d{1,2})(st|nd|rd|th)\b/gi, (m, n: string, suffix: string) => {
+    const num = Number(n)
+    const correct =
+      (num % 10 === 1 && num % 100 !== 11 && suffix.toLowerCase() === 'st') ||
+      (num % 10 === 2 && num % 100 !== 12 && suffix.toLowerCase() === 'nd') ||
+      (num % 10 === 3 && num % 100 !== 13 && suffix.toLowerCase() === 'rd') ||
+      (suffix.toLowerCase() === 'th' &&
+        !((num % 10 === 1 && num % 100 !== 11) || (num % 10 === 2 && num % 100 !== 12) || (num % 10 === 3 && num % 100 !== 13)))
+    if (!correct) return m
+    const w = ordinalToWords(num)
+    return w ?? m
+  })
+
+  // -- Number + unit suffix glued to the number (500ms, 5km, 10GB). Only a
+  //    known unit bounded by a non-letter, so identifiers never match.
+  s = s.replace(
+    /\b(\d{1,9})\s?(ms|sec|min|km|cm|mm|kg|kb|mb|gb|tb|ghz|mhz|hr|mi|s|m|h|d|g)(?![a-z])/gi,
+    (m, num: string, unitRaw: string) => {
+      const unit = UNIT_MAP[unitRaw.toLowerCase()]
+      if (!unit) return m
+      const n = Number(num)
+      const w = numberToWords(n)
+      if (!w) return m
+      return `${w} ${n === 1 ? unit.s : unit.p}`
+    },
+  )
+
+  // -- Symbols in prose.
+  s = s.replace(/(\s)&(\s)/g, '$1and$2')
+  s = s.replace(/(\w)&(\w)/g, '$1 and $2')
+  s = s.replace(/(^|\s)@(\w)/g, '$1at $2')
+  s = s.replace(/(^|\s)#(\w)/g, '$1hash $2')
+  // word/word in prose → "word slash word" (letters only, so paths/dates
+  // with digits are untouched).
+  s = s.replace(/\b([a-zA-Z]{2,})\/([a-zA-Z]{2,})\b/g, '$1 slash $2')
+  // ~ before a number → "about"; other tildes dropped.
+  s = s.replace(/~\s*(\d)/g, 'about $1')
+  s = s.replace(/~/g, '')
+  // Arrows → "to".
+  s = s.replace(/[=-]>/g, ' to ')
+  s = s.replace(/[→⇒]/g, ' to ')
+
+  // -- Restore parked inline-code contents verbatim.
+  s = restoreInline(s, parts)
+
+  // -- Whitespace → sentence flow.
+  s = s.replace(/[ \t]*\n[ \t]*\n[ \t]*/g, '. ')
+  s = s.replace(/\s*\n\s*/g, ' ')
+  s = s.replace(/[ \t]{2,}/g, ' ')
+  s = s.replace(/\.\s*\.(\s|$)/g, '.$1')
+  s = s.replace(/\s+([,.!?;:])/g, '$1')
+
+  return s.trim()
+}