switchroom 0.18.24 → 0.18.26

package/telegram-plugin/registry/turns-schema.ts

@@ -120,6 +120,26 @@ export interface Turn {
    * Null for turns that were never resumed.
    */
   resumed_at: number | null
+  /**
+   * The claude session id (the `<sessionId>.jsonl` transcript stem) that
+   * produced this turn's assistant output, stamped DURING the turn as soon as
+   * the first session event is observed (see `stampTurnSessionId`). Crash-
+   * survival redelivery uses this to resolve the EXACT transcript file for an
+   * interrupted turn, instead of `findActiveSessionFile`'s most-recent-mtime
+   * heuristic — which can shadow the new boot session's own transcript. Null
+   * until the turn produces its first session event (or for pre-migration rows).
+   */
+  session_id: string | null
+  /**
+   * Ms epoch at which the interrupted turn's captured-but-undelivered final
+   * answer was re-sent to the user at boot (crash-survival redelivery). This is
+   * the at-most-once ledger for redelivery — first-write-wins via
+   * `WHERE answer_redelivered_at IS NULL` (see `markAnswerRedelivered`). Kept on
+   * a SEPARATE marker from `resumed_at` because the two concerns have different
+   * correctness contracts (resume = at-most-once side-effect replay; redelivery
+   * = at-most-once answer send) and a turn can be both. Null until redelivered.
+   */
+  answer_redelivered_at: number | null
   created_at: number
   updated_at: number
 }
@@ -190,6 +210,15 @@ const PHASE3_MIGRATIONS = [
   `ALTER TABLE turns ADD COLUMN resumed_at INTEGER`,
 ]
 
+// Columns added for crash-survival redelivery. `session_id` pins the exact
+// transcript file for an interrupted turn (so redelivery never resolves the
+// wrong session via a most-recent-file heuristic); `answer_redelivered_at` is
+// the at-most-once redelivery ledger (stamped synchronously with the re-send).
+const PHASE4_MIGRATIONS = [
+  `ALTER TABLE turns ADD COLUMN session_id TEXT`,
+  `ALTER TABLE turns ADD COLUMN answer_redelivered_at INTEGER`,
+]
+
 function applySchema(db: SqliteDatabase): void {
   db.exec('PRAGMA journal_mode = WAL')
   db.exec('PRAGMA synchronous = NORMAL')
@@ -206,7 +235,7 @@ function applySchema(db: SqliteDatabase): void {
   // Run migrations. SQLite doesn't support "ADD COLUMN IF NOT EXISTS", so
   // we swallow the "duplicate column" error to stay idempotent on
   // pre-existing registry.db files.
-  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS]) {
+  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS, ...PHASE4_MIGRATIONS]) {
     try {
       db.exec(sql)
     } catch (err) {
@@ -283,6 +312,8 @@ interface RawTurnRow {
   tool_call_count: number | null
   interrupt_reason: string | null
   resumed_at: number | null
+  session_id: string | null
+  answer_redelivered_at: number | null
   created_at: number
   updated_at: number
 }
@@ -304,6 +335,8 @@ function mapRow(row: RawTurnRow): Turn {
     tool_call_count: row.tool_call_count,
     interrupt_reason: row.interrupt_reason,
     resumed_at: row.resumed_at,
+    session_id: row.session_id ?? null,
+    answer_redelivered_at: row.answer_redelivered_at ?? null,
     created_at: row.created_at,
     updated_at: row.updated_at,
   }
@@ -692,6 +725,61 @@ export function markTurnResumed(
   `).run(now, now, turnKey)
 }
 
+/**
+ * Stamp the claude `session_id` (the `<sessionId>.jsonl` transcript stem) on a
+ * turn the FIRST time it is observed, DURING the turn. First-write-wins via
+ * `WHERE session_id IS NULL` so the hot session-event path can call this on
+ * every event cheaply and idempotently. This must run while the turn is live
+ * (before any crash) so crash-survival redelivery can resolve the exact
+ * transcript file for an interrupted turn — never the most-recent-mtime file,
+ * which a fresh boot session would shadow. No-ops if `turnKey` is not found.
+ */
+export function stampTurnSessionId(
+  db: SqliteDatabase,
+  turnKey: string,
+  sessionId: string,
+  now: number = Date.now(),
+): void {
+  if (!sessionId) return
+  db.prepare(`
+    UPDATE turns
+    SET session_id = ?,
+        updated_at = ?
+    WHERE turn_key = ? AND session_id IS NULL
+  `).run(sessionId, now, turnKey)
+}
+
+/**
+ * Stamp `answer_redelivered_at` on an interrupted turn at the moment its
+ * captured-but-undelivered final answer has been re-sent at boot (crash-
+ * survival redelivery). This is the at-most-once ledger for redelivery: once
+ * stamped, the redelivery decision skips the turn on any later restart.
+ *
+ * Ordering: the caller stamps SYNCHRONOUSLY with the send (immediately after
+ * the send resolves), the same discipline as `markTurnResumed`. A residual
+ * race remains — the window between the Telegram send completing and this row
+ * (plus the send's own `role='assistant'` history row) becoming durable. A
+ * crash landing in that window could re-send on the next boot; the durable
+ * text-identity delivery oracle (matching the projected answer text against
+ * delivered `messages` rows) is what CATCHES that duplicate, so redelivery is
+ * at-most-once modulo detection, never a silent double-send of a fresh answer.
+ *
+ * Idempotent and first-write-wins (`WHERE answer_redelivered_at IS NULL`).
+ * No-ops if `turnKey` is not found.
+ */
+export function markAnswerRedelivered(
+  db: SqliteDatabase,
+  turnKey: string,
+  now: number = Date.now(),
+): void {
+  db.prepare(`
+    UPDATE turns
+    SET answer_redelivered_at = ?,
+        updated_at            = ?
+    WHERE turn_key = ? AND answer_redelivered_at IS NULL
+  `).run(now, now, turnKey)
+}
+
 /**
  * Return the single most-recently-started turn IFF it was interrupted
  * (`ended_at IS NULL`, or `ended_via` in {restart, sigterm, timeout,

package/telegram-plugin/render/code-segments.ts

@@ -0,0 +1,210 @@
+// Shared CommonMark-correct code-span / fenced-block splitter for the outbound
+// formatting guards (#3252). Every guard that neutralises accidental Telegram
+// markdown typesetting (dollar-math, emphasis, line-start block constructs,
+// inline pairs) must skip content inside code spans and fenced code blocks
+// verbatim. Rather than each guard forking its own copy of the splitter (the
+// dollar guard shipped one, the emphasis + line-start guards each duplicated
+// it), this is the ONE source of truth they all import.
+
+/** A contiguous slice of rendered markdown, tagged as code (verbatim, never
+ *  transformed) or prose (eligible for a guard's rewrite). */
+export interface Segment {
+  code: boolean;
+  text: string;
+}
+
+/** From index `from` (just past an opening run of `runLen` backticks), find the
+ *  index immediately AFTER the matching closing run of exactly `runLen`
+ *  backticks. Returns -1 when there is no matching close (a stray backtick), in
+ *  which case the opener is treated as literal prose. Equal-length matching is
+ *  the CommonMark rule for code spans and matches the balanced fences the
+ *  renderer emits for code blocks. */
+export function findClosingBackticks(text: string, from: number, runLen: number): number {
+  let i = from;
+  while (i < text.length) {
+    if (text[i] === "`") {
+      let j = i;
+      while (j < text.length && text[j] === "`") j++;
+      if (j - i === runLen) return j;
+      i = j;
+    } else {
+      i++;
+    }
+  }
+  return -1;
+}
+
+/** Split rendered markdown into alternating prose / code segments so a guard can
+ *  skip code spans and fenced code blocks entirely. */
+export function splitCodeSegments(text: string): Segment[] {
+  const out: Segment[] = [];
+  let i = 0;
+  let plainStart = 0;
+  while (i < text.length) {
+    if (text[i] === "`") {
+      let j = i;
+      while (j < text.length && text[j] === "`") j++;
+      const runLen = j - i;
+      const close = findClosingBackticks(text, j, runLen);
+      if (close !== -1) {
+        if (plainStart < i) out.push({ code: false, text: text.slice(plainStart, i) });
+        out.push({ code: true, text: text.slice(i, close) });
+        i = close;
+        plainStart = close;
+        continue;
+      }
+    }
+    i++;
+  }
+  if (plainStart < text.length) out.push({ code: false, text: text.slice(plainStart) });
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Link / autolink / table protection (#3252 — link-aware guards)
+// ---------------------------------------------------------------------------
+//
+// The four accidental-formatting guards must NOT escape inside content where
+// the trigger chars (`_ * ~ = | $`) are STRUCTURAL rather than prose:
+//   • markdown link destinations — the `(url)` (and `(url "title")`) target of
+//     a `[label](url)` link. Underscores / tildes / `==` in a URL path or query
+//     are part of the address; a backslash there can 404 the link. The link
+//     LABEL (`[...]`) is rendered prose and stays guarded.
+//   • bare autolinked URLs — `http(s)://…` and `www.…` runs Telegram auto-links.
+//   • GFM table rows — a table's structural pipes / empty cells (`|a||b|`) must
+//     survive; escaping inside a real table row corrupts the table.
+// Everything else is prose and stays fully guarded. This is the sibling of the
+// code-span skip: a PROTECTED segment (`code: true`) is emitted verbatim.
+//
+// Deterministic and linear-time: one left-to-right char scan per prose chunk
+// plus one line pre-pass for tables; no backtracking regexes.
+
+/** A GFM table delimiter row: only pipes / colons / dashes / spaces, with at
+ *  least one dash AND at least one pipe (a bare `---` is a thematic break, not a
+ *  table). This is what distinguishes a real table from prose that merely starts
+ *  with `|`. */
+function isTableDelimiterRow(line: string): boolean {
+  const t = line.trim();
+  return t.length > 0 && /^[\s|:-]+$/.test(t) && t.includes("-") && t.includes("|");
+}
+
+/** A candidate table line: after optional leading spaces it begins with `|`. */
+function isTableCandidateLine(line: string): boolean {
+  return /^\s*\|/.test(line);
+}
+
+/** Find the [start, end) char ranges (relative to `text`) of GFM table blocks —
+ *  maximal runs of 2+ consecutive `|`-leading lines that contain a delimiter
+ *  row. Each returned range spans whole lines INCLUDING their trailing newline,
+ *  so a table becomes ONE protected segment. A lone `|a||b|` line with no
+ *  delimiter row is NOT a real table → not protected → still guarded. */
+function findTableRanges(text: string): Array<[number, number]> {
+  const ranges: Array<[number, number]> = [];
+  const lines = text.split("\n");
+  let offset = 0;
+  let runStart = -1;
+  let runEnd = -1;
+  let runHasDelim = false;
+  let runLineCount = 0;
+  const flush = () => {
+    if (runStart !== -1 && runLineCount >= 2 && runHasDelim) {
+      ranges.push([runStart, runEnd]);
+    }
+    runStart = -1;
+    runEnd = -1;
+    runHasDelim = false;
+    runLineCount = 0;
+  };
+  for (let k = 0; k < lines.length; k++) {
+    const line = lines[k];
+    // char length of this line including its trailing newline (except the last).
+    const lineLen = line.length + (k < lines.length - 1 ? 1 : 0);
+    if (isTableCandidateLine(line)) {
+      if (runStart === -1) runStart = offset;
+      runEnd = offset + lineLen;
+      runLineCount += 1;
+      if (isTableDelimiterRow(line)) runHasDelim = true;
+    } else {
+      flush();
+    }
+    offset += lineLen;
+  }
+  flush();
+  return ranges;
+}
+
+/** Protect links / autolinks / table rows within a single PROSE chunk, returning
+ *  alternating prose / protected segments. */
+function splitProseProtected(text: string): Segment[] {
+  const out: Segment[] = [];
+  const tables = findTableRanges(text);
+  let tIdx = 0;
+  let i = 0;
+  let plainStart = 0;
+  const pushProtected = (from: number, to: number) => {
+    if (plainStart < from) out.push({ code: false, text: text.slice(plainStart, from) });
+    out.push({ code: true, text: text.slice(from, to) });
+    plainStart = to;
+  };
+  while (i < text.length) {
+    // Advance the table pointer past any range we've already scanned past.
+    while (tIdx < tables.length && tables[tIdx][1] <= i) tIdx++;
+    // 1. Table block — protect whole lines verbatim.
+    if (tIdx < tables.length && tables[tIdx][0] === i) {
+      const [, end] = tables[tIdx];
+      pushProtected(i, end);
+      i = end;
+      continue;
+    }
+    const ch = text[i];
+    // 2. Markdown link destination: `[label](dest)` — protect only `(dest)`.
+    if (ch === "[") {
+      const close = text.indexOf("]", i + 1);
+      if (close !== -1 && text[close + 1] === "(") {
+        const destClose = text.indexOf(")", close + 2);
+        if (destClose !== -1) {
+          // Protect the `(dest)` span; the `[label]` before it stays prose.
+          pushProtected(close + 1, destClose + 1);
+          i = destClose + 1;
+          continue;
+        }
+      }
+      i++;
+      continue;
+    }
+    // 3. Bare autolink: `http(s)://…` or `www.…`, left-flanked by a boundary.
+    if (
+      (ch === "h" || ch === "w") &&
+      (i === 0 || !/[A-Za-z0-9]/.test(text[i - 1]))
+    ) {
+      const m = /^(?:https?:\/\/|www\.)[^\s<>()\[\]]+/.exec(text.slice(i));
+      if (m) {
+        const end = i + m[0].length;
+        pushProtected(i, end);
+        i = end;
+        continue;
+      }
+    }
+    i++;
+  }
+  if (plainStart < text.length) out.push({ code: false, text: text.slice(plainStart) });
+  return out;
+}
+
+/** Split rendered markdown into prose / protected segments where a PROTECTED
+ *  (`code: true`) segment is any content a guard must emit verbatim: code spans,
+ *  fenced code blocks, markdown link destinations, bare autolinks, and GFM
+ *  table rows. This is the link/table-aware superset of `splitCodeSegments` that
+ *  all four #3252 guards route through. Prose segments (`code: false`) remain
+ *  guardable (including a link's `[label]` text). Deterministic, linear-time. */
+export function splitProtectedSegments(text: string): Segment[] {
+  const out: Segment[] = [];
+  for (const seg of splitCodeSegments(text)) {
+    if (seg.code) {
+      out.push(seg);
+      continue;
+    }
+    for (const sub of splitProseProtected(seg.text)) out.push(sub);
+  }
+  return out;
+}

package/telegram-plugin/render/dollar-math-guard.ts

@@ -0,0 +1,126 @@
+// Outbound guard against accidental TeX/inline-math typesetting of currency
+// amounts (issue #3252).
+//
+// ── Root cause ───────────────────────────────────────────────────────────
+// Since the Bot API 10.1 migration (#2669) every assistant reply is sent to
+// Telegram as RAW GFM markdown via `sendRichMessage({ markdown })` — Telegram
+// parses the markdown server-side. Telegram's rich GFM parser honours the GFM
+// inline-math extension: a `$...$` PAIR typesets the text between the two
+// dollar signs as math (math-italic, U+1D400-range glyphs on the reader's
+// screen). switchroom's renderer (`render.ts` → `escapeMarkdown`) escapes the
+// other inline-formatting triggers (`` ` `` `*` `_` `~` `=` `[` `]` `|`) but
+// NOT `$`. So a perfectly ordinary reply with TWO dollar amounts —
+//   "…ceiling is ~$0.5-0.9M but nearly all in small dealers … is ~$150-450k"
+// — accidentally forms a math span across everything between the two `$`, and
+// the reader sees the middle typeset as math-italic. history.db stores the
+// clean ASCII; switchroom emits clean ASCII; the math is produced downstream
+// by Telegram's rich-markdown parser from the unescaped `$…$` pair.
+//
+// ── Fix ──────────────────────────────────────────────────────────────────
+// Deterministically break the `$…$` pairing on the wire by backslash-escaping
+// EVERY prose `$` (`$` → `\$`) once the message looks like it carries currency
+// — i.e. the prose (non-code) content holds 2+ total `$` AND at least one of
+// them sits next to a digit (`$50`, `$.50`, or a trailing `50$`). A lone `$`
+// (single total, or no digit-adjacent `$` anywhere) can never form a currency
+// math span the way #3252 describes, so it is left byte-for-byte untouched.
+// Code spans / fenced code blocks are NEVER touched (verbatim). Escaping every
+// prose `$` (not just the `$digit` ones) is what closes the F3 false-negatives:
+// `"$50 or 50$"`, `"$10 … from $ yesterday"`, and `"$.50 and $5"` all still form
+// a `$…$` pair if only the leading-`$digit` token is escaped — so we escape the
+// lot once the currency signal + 2-dollar threshold are met.
+//
+// Idempotent (F5): the escape uses a negative-lookbehind (`(?<!\\)\$`) so an
+// already-escaped `\$` is never doubled to `\\$`. Running the guard twice (e.g.
+// the streaming path renders then this wrapper re-wraps) is a strict no-op the
+// second time.
+//
+// ── Where this runs (F1) ───────────────────────────────────────────────────
+// This guard is invoked from `richMessage()` (rich-send.ts) — the ONE adapter
+// every `{ markdown }` wire send funnels through (the `reply`-tool final answer
+// via computeReplyChunks/sendReplyChunks, the draft-stream previews, cards,
+// approvals, banners). That is the single deterministic seam that covers every
+// markdown-parsed outbound exactly once. `plain`-mode degradations bypass
+// `richMessage` (they go straight to `sendMessage`, no markdown parsing → no
+// math), so they are correctly left untouched.
+//
+// Why `\$` and not a zero-width joiner (U+2060):
+//   - It reuses the EXACT mechanism switchroom already relies on for every
+//     other formatting char (`escapeMarkdown` backslash-escapes `~ = | * _`
+//     etc.), which Telegram's rich parser demonstrably strips and renders
+//     literally — the whole card system depends on it. `$` is ASCII
+//     punctuation, so CommonMark's "any ASCII punctuation may be
+//     backslash-escaped" rule applies identically.
+//   - The reader sees a literal `$`; copy-paste yields exactly `$0.5-0.9M`
+//     (the backslash is consumed by the parser, never in the rendered text or
+//     the clipboard). No zero-width characters that could pollute search /
+//     copy / re-tokenisation.
+//   - Fully deterministic (pure string transform), and a strict no-op for any
+//     message with fewer than two `$digit` tokens.
+//
+// Tradeoff (UNVERIFIED — see F4): this relies on Telegram's server-side rich
+// GFM parser (a) recognising `$` as an escapable ASCII punctuation char and
+// (b) CONSUMING the backslash so the reader sees a literal `$` and copy-paste
+// yields `$0.5-0.9M` (no stray `\`). This is asserted by analogy to the
+// `` ~ = | * _ `` chars that `escapeMarkdown` (format.ts) already backslash-
+// escapes and that Telegram demonstrably strips — BUT note `escapeMarkdown`
+// pointedly does NOT include `$` in its escape set, so we have no in-repo
+// evidence that `\$` specifically round-trips. Vitest CANNOT cover this (it is
+// server-side Telegram behaviour). If Telegram does NOT consume the backslash,
+// guarded replies would show a visible `\$0.5-0.9M` — arguably worse than the
+// math bug. **This is the one residual risk requiring human UAT before merge:**
+// send a real two-dollar-amount message through a live agent and confirm it
+// renders as a literal `$` (not `\$`, not math-italic). See the PR's UAT note.
+
+// The code-span/fence splitter now lives in ONE shared module so every #3252
+// guard reuses the same CommonMark-correct implementation. Re-exported here for
+// backwards compatibility with any importer that reached for it via this file.
+import { splitCodeSegments, splitProtectedSegments, type Segment } from "./code-segments.js";
+export { splitCodeSegments, splitProtectedSegments, type Segment };
+
+/** Counts every `$` in a segment (the total-dollar threshold input). */
+const ANY_DOLLAR = /\$/g;
+
+/** The "this is currency, not a stray symbol" signal: a `$` sitting next to a
+ *  digit on either side — `$50` / `$.50` (leading) or `50$` (trailing), the
+ *  latter covering European / trailing-symbol conventions. One such token in
+ *  the prose is enough to arm the guard (combined with the 2+ total threshold).
+ *  Non-global: used only as a boolean `.test`. */
+const CURRENCY_SIGNAL = /\$\.?\d|\d\s?\$/;
+
+/** Every prose `$` that is NOT already backslash-escaped. The negative
+ *  lookbehind makes the escape idempotent (F5): a pre-existing `\$` is left
+ *  alone, so running the guard twice never produces `\\$`. Global for replace. */
+const UNESCAPED_DOLLAR = /(?<!\\)\$/g;
+
+/**
+ * Neutralise accidental `$…$` inline-math typesetting of currency amounts.
+ *
+ * Operates on the FINAL rendered rich-markdown string (post-`render`). A no-op
+ * unless the prose (non-code) content holds 2+ total `$` AND at least one of
+ * them is digit-adjacent (a currency signal). When armed, EVERY unescaped prose
+ * `$` is backslash-escaped so no two `$` can pair into a math span — this is
+ * what closes the F3 trailing-`$` / `$.50` false-negatives. Code spans / fenced
+ * blocks are never touched. Idempotent (F5) and deterministic.
+ */
+export function guardDollarMath(text: string): string {
+  if (!text.includes("$")) return text;
+  // Link-aware: a `$` inside a URL/table (rare but possible) is structural and
+  // must not be escaped. splitProtectedSegments skips code/links/autolinks/tables.
+  const segments = splitProtectedSegments(text);
+
+  let total = 0;
+  let hasCurrencySignal = false;
+  for (const seg of segments) {
+    if (seg.code) continue;
+    total += seg.text.match(ANY_DOLLAR)?.length ?? 0;
+    if (!hasCurrencySignal && CURRENCY_SIGNAL.test(seg.text)) hasCurrencySignal = true;
+  }
+  // Fewer than two dollars can never form a pair; without a digit-adjacent `$`
+  // the two dollars are (e.g.) `$foo`/`$bar` shell-var prose, which we leave
+  // alone to avoid escaping legitimate lone symbols (F3: no false positives).
+  if (total < 2 || !hasCurrencySignal) return text;
+
+  return segments
+    .map((seg) => (seg.code ? seg.text : seg.text.replace(UNESCAPED_DOLLAR, () => "\\$")))
+    .join("");
+}

package/telegram-plugin/render/emphasis-guard.ts

@@ -0,0 +1,158 @@
+// Outbound guard against accidental inline-emphasis typesetting from `_`/`*`
+// that the model never meant as formatting (issue #3252, sibling of the
+// `$…$` currency-math guard in dollar-math-guard.ts).
+//
+// ── Root cause ───────────────────────────────────────────────────────────
+// Since the Bot API 10.1 migration (#2669) every assistant reply is sent to
+// Telegram as RAW GFM markdown via `sendRichMessage({ markdown })` — Telegram
+// parses the markdown server-side. Telegram's rich GFM parser pairs `_`/`*`
+// delimiters into emphasis spans. The agent DELIBERATELY uses `**bold**`,
+// `*italic*` and `_italic_` (Ken's rich-formatting directive) — that is a
+// wanted feature and MUST survive untouched. But the same characters also
+// occur in prose the model never meant to format:
+//   - snake_case identifiers — `file_name_here` italicises "name" once two
+//     intra-word `_` pair up (and Telegram's `_` pairing is more liberal than
+//     strict CommonMark, which does not emphasise intra-word underscores);
+//   - inline multiplication — `a*b*c`, `2*3` — where two intra-word `*` pair
+//     and italicise the middle factor;
+//   - mid-word `_`/`*` in paths / variable names.
+// These are the direct sibling of the dollar bug: a delimiter that pairs up
+// across prose and typesets a span nobody meant.
+//
+// ── Fix ──────────────────────────────────────────────────────────────────
+// Deterministically break the pairing by backslash-escaping ONLY the clearly-
+// accidental delimiters, identified by a single unambiguous signal:
+//
+//   an INTRA-WORD delimiter — a single `_` or `*` with an ASCII alphanumeric
+//   character IMMEDIATELY on BOTH sides (`e_n`, `a*b`, `2_f`, `2*3`).
+//
+// This signal is chosen because intended emphasis can NEVER match it: an
+// intended opener (`*italic*`, `_italic_`) is flanked on its OUTER side by a
+// word boundary — whitespace, start-of-string, or punctuation — never by an
+// alphanumeric. So an alphanumeric-on-both-sides delimiter is, by
+// construction, not the opener or closer of an intended span. `**bold**` /
+// `__x__` double runs are excluded for free: the inner neighbour of each `*`
+// in `a**b` is another `*` (not alphanumeric), so neither half matches.
+//
+// What we DELIBERATELY LEAVE ALONE (conservative false-negatives, per the
+// "when in doubt, leave it" doctrine inherited from the dollar guard):
+//   - Space-flanked operators (`3 * 4`): a whitespace-flanked `*`/`_` is
+//     neither left- nor right-flanking under GFM, so it can never open or
+//     close emphasis — there is no bug to fix, and escaping it would be pure
+//     churn.
+//   - Boundary-flanked delimiters (`rm *`, `*.ts`, leading-`_` `_private`):
+//     these are INDISTINGUISHABLE from an intended `*glob*` / `_italic_`
+//     opener (`*.ts is a glob*` is a legitimate italic). Escaping them would
+//     risk breaking intended emphasis — the one thing this guard must never
+//     do — so a glob/leading-underscore that pairs into an accidental span is
+//     accepted as a rare false-negative rather than risked as a false-positive.
+//     (A future arm could target these behind live Telegram UAT; see below.)
+//
+// Idempotent: the escape is expressed as an intra-word match, so an
+// already-escaped `\_`/`\*` has a backslash (not an alphanumeric) immediately
+// before the delimiter and therefore never re-matches — running the guard
+// twice is a strict no-op. Code spans / fenced code blocks are NEVER touched
+// (verbatim), via the same splitCodeSegments logic the dollar guard uses.
+//
+// ── Where this runs ────────────────────────────────────────────────────────
+// Like the dollar guard, this is intended to be invoked from `richMessage()`
+// (rich-send.ts) — the single seam every `{ markdown }` wire send funnels
+// through. THIS commit only adds the pure function + its test; the seam
+// wiring is integrated separately (all guards in one pass) to avoid conflicts.
+//
+// ── UNVERIFIED (needs live Telegram UAT) ───────────────────────────────────
+// Same residual risk as the dollar guard: this relies on Telegram's server-
+// side rich GFM parser (a) recognising `\_` / `\*` as escapable ASCII
+// punctuation and (b) CONSUMING the backslash so the reader sees a literal
+// `_` / `*` and copy-paste yields `file_name` / `a*b` (no stray `\`). This is
+// asserted by analogy to the `` ~ = | * _ `` chars `escapeMarkdown`
+// (format.ts) already backslash-escapes and that Telegram demonstrably strips.
+// Vitest CANNOT cover server-side rendering; a real intra-word `_`/`*` message
+// through a live agent must confirm it renders literal (not `\_`, not italic).
+
+// Segment splitting (code spans / fences AND markdown link destinations /
+// autolinks / table rows) is shared across all #3252 guards — one source of
+// truth in render/code-segments.ts. Routing through `splitProtectedSegments`
+// (not the code-only `splitCodeSegments`) is what makes this guard link-aware:
+// an intra-word `_`/`*` inside a URL path (`.../a_b_c`) is STRUCTURAL, not
+// prose, and must never be escaped (the link would break). See code-segments.ts.
+import { splitProtectedSegments } from "./code-segments.js";
+
+/** An intra-word underscore: a single `_` with an ASCII alphanumeric on BOTH
+ *  immediate sides (`file_name`, `v2_final`). Intended `_italic_` never
+ *  matches — its opener is boundary-flanked on the outer side. The
+ *  alphanumeric lookbehind also makes the escape idempotent: an already-
+ *  escaped `\_` has `\` (not alnum) before the `_`, so it never re-matches. */
+const INTRA_WORD_UNDERSCORE = /(?<=[A-Za-z0-9])_(?=[A-Za-z0-9])/g;
+
+/** An intra-word asterisk: a single `*` with an ASCII alphanumeric on BOTH
+ *  immediate sides (`a*b`, `2*3`). Intended `*italic*` / `**bold**` never
+ *  match — italic openers are boundary-flanked, and in a `**` run the inner
+ *  neighbour is `*` (not alnum). Idempotent for the same reason as above. */
+const INTRA_WORD_ASTERISK = /(?<=[A-Za-z0-9])\*(?=[A-Za-z0-9])/g;
+
+/** Every unescaped `_` / `*` in prose (the pair-threshold input). An emphasis
+ *  span needs a MATCHING pair of the same delimiter, so a delimiter can only
+ *  mis-render when 2+ of it exist. The `(?<!\\)` keeps the count idempotent. */
+const ANY_UNDERSCORE = /(?<!\\)_/g;
+const ANY_ASTERISK = /(?<!\\)\*/g;
+
+/**
+ * Neutralise accidental inline emphasis produced by intra-word `_` / `*`.
+ *
+ * Operates on the FINAL rendered rich-markdown string (post-`render`).
+ *
+ * ── Threshold: 2+ of the delimiter (finding 4) ────────────────────────────
+ * A `_` (or `*`) escape only fires when the prose holds an intra-word
+ * occurrence of that delimiter AND 2+ TOTAL of it. Emphasis is a PAIRED
+ * construct — a single `_` (or `*`) in the whole message can never form a span,
+ * so escaping a lone intra-word delimiter is pure churn that only widens the
+ * false-positive surface (a stray `\` if Telegram ever failed to consume it),
+ * with zero correctness gain. Requiring 2+ matches the dollar / inline-pairs
+ * "a lone delimiter can't pair" doctrine. This is strictly SAFE: any real
+ * mis-render needs 2+ delimiters, and when 2+ exist (e.g. `file_name_here`, or
+ * an intra-word `file_name` sitting alongside an intended `_italic_` elsewhere —
+ * three underscores that Telegram could mis-pair) the intra-word delimiter IS
+ * escaped, so no accidental span survives. Only the provably-inert lone-`_`
+ * (`file_name` as the ONLY underscore in the message) is now left byte-identical.
+ *
+ * Intended `**bold**`, `*italic*` and `_italic_` are LEFT UNTOUCHED by
+ * construction (their delimiters are boundary-flanked, never intra-word).
+ * Code spans / fenced blocks, link destinations and autolinks are never touched
+ * (via `splitProtectedSegments`). Idempotent and deterministic.
+ */
+export function guardAccidentalEmphasis(text: string): string {
+  if (!text.includes("_") && !text.includes("*")) return text;
+  const segments = splitProtectedSegments(text);
+
+  // NO-OP guard: only rewrite when a real intra-word signal exists in prose AND
+  // 2+ of that delimiter exist (so a pair — hence a mis-render — is possible).
+  let hasIntraUnderscore = false;
+  let hasIntraAsterisk = false;
+  let underscoreCount = 0;
+  let asteriskCount = 0;
+  for (const seg of segments) {
+    if (seg.code) continue;
+    if (INTRA_WORD_UNDERSCORE.test(seg.text)) hasIntraUnderscore = true;
+    if (INTRA_WORD_ASTERISK.test(seg.text)) hasIntraAsterisk = true;
+    underscoreCount += seg.text.match(ANY_UNDERSCORE)?.length ?? 0;
+    asteriskCount += seg.text.match(ANY_ASTERISK)?.length ?? 0;
+  }
+  // Reset lastIndex — the /g regexes above are stateful across .test() calls.
+  INTRA_WORD_UNDERSCORE.lastIndex = 0;
+  INTRA_WORD_ASTERISK.lastIndex = 0;
+
+  const armUnderscore = hasIntraUnderscore && underscoreCount >= 2;
+  const armAsterisk = hasIntraAsterisk && asteriskCount >= 2;
+  if (!armUnderscore && !armAsterisk) return text;
+
+  return segments
+    .map((seg) => {
+      if (seg.code) return seg.text;
+      let out = seg.text;
+      if (armUnderscore) out = out.replace(INTRA_WORD_UNDERSCORE, "\\_");
+      if (armAsterisk) out = out.replace(INTRA_WORD_ASTERISK, "\\*");
+      return out;
+    })
+    .join("");
+}