switchroom 0.16.38 → 0.16.47

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

@@ -203,15 +203,27 @@ function restore(
  * Replace em / en dashes with context-appropriate punctuation.
  *
  * Rules, applied in order:
- *   1. ` — ` / ` – ` (flanked by single space) → `, ` if followed by a
- *      lowercase or open-paren character; otherwise `. ` if followed by
- *      an uppercase or end-of-string. Heuristic: lowercase = mid-clause
- *      continuation (comma reads naturally); uppercase = new sentence
- *      (period reads naturally).
+ *   1. ` — ` / ` – ` (flanked by single space) → `. ` + the following
+ *      word recapitalized, in the common case. A spaced em-dash in prose
+ *      almost always joins two INDEPENDENT clauses ("voice came back —
+ *      three PRs stacked"); degrading that to a comma produces a comma
+ *      splice ("voice came back, three PRs stacked"), which reads as
+ *      broken grammar. A period (full stop) is the substitution that
+ *      never corrupts meaning: two independent clauses become two
+ *      sentences. The genuine appositive/parenthetical use of a dash
+ *      ("the lead — a tall man — spoke") is the minority case and still
+ *      reads acceptably as two short sentences, so we default to the
+ *      period rather than risk a splice. A dash already followed by a
+ *      lowercased conjunction/pronoun that only makes sense mid-sentence
+ *      is the rare exception the heuristic can't recover; a clean period
+ *      beats a comma splice there too. Original PR #1683 used a comma for
+ *      lowercase continuations; that was the #2737-era source of splices
+ *      in real replies (fixed here).
  *   2. End-of-line dash (` —\n` / ` –\n`) → `.\n` — treat as full stop.
  *   3. Bare dash with no flanking spaces between word chars
- *      (e.g. "word—word") → `, ` — the missing-space form is rarer but
- *      semantically the same as #1.
+ *      (e.g. "word—word") → `. ` + recapitalized following word — the
+ *      missing-space form is rarer but semantically the same as #1, so it
+ *      gets the same splice-free full-stop treatment.
  *   4. Surviving dash (uncommon, e.g. at sentence start "— note") → `-`
  *      so the message still renders without the AI tell.
  */
@@ -219,14 +231,27 @@ function replaceDashes(text: string): { out: string; replaced: number } {
   let replaced = 0
   let out = text
 
-  // #1: spaced em-dash mid-prose. Decide between ", " and ". " on
-  // the leading character of the following token.
-  out = out.replace(/(\S) [—–] (\S)/g, (_m, before: string, after: string) => {
+  // Recapitalize the first ASCII-lowercase letter of `after` so the new
+  // sentence that a full-stop substitution creates reads correctly. A
+  // non-letter start (digit, `(`, quote) is left as-is. A lowercase-initial
+  // mixed-case brand token (iOS, eBay, iPhone, macOS — second char is
+  // uppercase) is ALSO left as-is: recapitalizing it to "IOS" corrupts the
+  // brand, and the token's own capitalization already reads as intentional.
+  const capFirst = (after: string): string => {
+    if (/^[a-z][A-Z]/.test(after)) return after
+    return after.replace(/^([a-z])/, (_m, ch: string) => ch.toUpperCase())
+  }
+
+  // #1: spaced em-dash mid-prose. A spaced dash joins two independent
+  // clauses far more often than it sets off an appositive, so degrade it
+  // to a full stop (never a comma — that produces a comma splice) and
+  // recapitalize the following word into a new sentence. A digit-flanked
+  // dash is a numeric range (10–20), not a clause break, so it's excluded
+  // here and falls through to rule #4 (→ ASCII hyphen, "10-20").
+  out = out.replace(/(\S) [—–] (\S)(\S?)/g, (m, before: string, after: string, peek: string) => {
+    if (/\d/.test(before) && /\d/.test(after)) return m
     replaced++
-    // If `after` is uppercase ASCII or one of a known sentence-starter
-    // set, treat as new sentence; otherwise a parenthetical comma.
-    const sentenceStart = /[A-Z]/.test(after)
-    return sentenceStart ? `${before}. ${after}` : `${before}, ${after}`
+    return `${before}. ${capFirst(after + peek)}`
   })
 
   // #2: dash at end of line. Treat as full stop.
@@ -235,11 +260,14 @@ function replaceDashes(text: string): { out: string; replaced: number } {
     return `.${ws}`
   })
 
-  // #3: bare dash between word chars (no flanking spaces). Treat as
-  // missing-space form of #1; comma is the safe fallback.
-  out = out.replace(/(\w)[—–](\w)/g, (_m, before: string, after: string) => {
+  // #3: bare dash between word chars (no flanking spaces). Missing-space
+  // form of #1 — same full-stop treatment so it can't create a splice. A
+  // digit-flanked dash (3–2) is a numeric range, not a clause break, so it's
+  // excluded and falls through to rule #4 (→ ASCII hyphen, "3-2").
+  out = out.replace(/(\w)[—–](\w)(\w?)/g, (m, before: string, after: string, peek: string) => {
+    if (/\d/.test(before) && /\d/.test(after)) return m
     replaced++
-    return `${before}, ${after}`
+    return `${before}. ${capFirst(after + peek)}`
   })
 
   // #4: anything still standing — convert to ASCII hyphen so no
@@ -266,6 +294,28 @@ function replaceDashes(text: string): { out: string; replaced: number } {
  * checked per call so an operator can flip it via env var without a
  * restart of an in-process test.
  */
+/**
+ * Dash-only normalization — the em/en-dash substitution from `scrubVoice`
+ * WITHOUT the opener-strip or the metric/result-object side effects.
+ *
+ * Exists so non-reply surfaces (progress cards, worker narration, PTY
+ * previews via card-format.ts) can close the em-dash leak on model-authored
+ * prose without pulling in the opener strip (which those paths must not do)
+ * and without duplicating the dash regexes. Reuses the exact same
+ * `park`/`replaceDashes`/`restore` mechanism as `scrubVoice`, so code spans
+ * and fenced blocks are masked identically and dashes inside them survive.
+ *
+ * Honors the same `SWITCHROOM_DISABLE_VOICE_SCRUB` kill switch. Returns the
+ * input unchanged when disabled, empty, or nothing changed.
+ */
+export function normalizeDashes(text: string): string {
+  if (!enabled() || text.length === 0) return text
+  const { parked, parts } = park(text)
+  const { out, replaced } = replaceDashes(parked)
+  if (replaced === 0) return text
+  return restore(out, parts)
+}
+
 export function scrubVoice(text: string): VoiceScrubResult {
   if (!enabled() || text.length === 0) {
     return { scrubbed: text, replaced: 0, openersStripped: 0 }

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) ──────────────────────

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