switchroom 0.18.25 → 0.18.26

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

package/telegram-plugin/render/inline-pairs-guard.ts

@@ -0,0 +1,171 @@
+// Outbound guard against ACCIDENTAL inline-pair typesetting — the sibling of the
+// dollar-math guard (#3252 follow-up). Mirrors that guard's doctrine exactly.
+//
+// ── Root cause (same seam, same class of bug) ─────────────────────────────
+// Since the Bot API 10.1 migration (#2669) every assistant reply is sent to
+// Telegram as RAW GFM markdown via `sendRichMessage({ markdown })`; Telegram
+// parses it server-side. Telegram's rich GFM parser honours several PAIRED
+// inline-formatting delimiters that ordinary prose can form by accident:
+//
+//   • `~text~` / `~~text~~`  → strikethrough
+//   • `==text==`             → highlight / "marked" (Telegram 10.1 supports it)
+//   • `||text||`             → spoiler
+//   • `` `text` ``           → code span
+//
+// switchroom's `escapeMarkdown` (format.ts) backslash-escapes exactly these
+// trigger chars (`` ` `` `*` `_` `~` `=` `|` `[` `]`) for DYNAMIC card content —
+// which is our IN-REPO EVIDENCE that Telegram's rich parser genuinely INTERPRETS
+// `~ = |` and `` ` `` as formatting (otherwise escaping them would be pointless).
+// But the assistant's free-form reply body is NOT run through escapeMarkdown
+// (that would nuke the agent's DELIBERATE `~~strike~~` / `||spoiler||` /
+// `` `code` `` formatting — Ken's rich-formatting directive). So an ordinary
+// reply like "trims it to ~10 units, down from ~20" can accidentally form a
+// `~…~` strikethrough span across "10 units, down from ".
+//
+// ── Which of the four we actually guard (and why) ─────────────────────────
+// Ranked by real-world likelihood in normal agent prose:
+//
+//  1. TILDE  `~`  — HIGH. Approximation tildes on numbers ("~10", "~$5M",
+//     "~.5s") are extremely common in agent prose and two of them form a
+//     strikethrough pair. GUARDED.
+//  2. MARK   `==` — MEDIUM. Equality/comparison operators in prose ("x==y",
+//     "if a==b and c==d") sit word-flanked and two of them form a highlight
+//     span. GUARDED.
+//  3. SPOILER `||` — LOW. Logical-OR in prose ("a||b || c||d"). Rare but the
+//     same word-flanked shape, same fix. GUARDED (cheap, precise).
+//  4. BACKTICK `` ` `` — SKIPPED as effectively-literal. A TRULY unpaired
+//     backtick renders LITERALLY per CommonMark (a backtick run with no
+//     equal-length closer is left as text — this is exactly what
+//     `findClosingBackticks` returns -1 for, so `splitCodeSegments` already
+//     leaves it in a PROSE segment untouched). The only case a stray backtick
+//     "mis-renders" is an ODD count where an earlier pair swallows prose into a
+//     code span — but that is INDISTINGUISHABLE from an intended `` `code` ``
+//     span plus a separate literal backtick, and the agent uses `` `code` ``
+//     deliberately. Per the false-negative-beats-false-positive rule we leave
+//     it. (Neutralising it would risk mangling real code spans, which the task
+//     forbids.) See the design note for the full verification.
+//
+// ── The heuristic — precision over recall, never touch intended formatting ──
+// The hard constraint: the agent DELIBERATELY emits `~~strike~~`, `||spoiler||`
+// and `` `code` `` as wanted formatting. We must neutralise ONLY the
+// unmistakably-accidental shape and leave every intended span byte-identical.
+//
+//  • TILDE: a `~` is accidental only when it is DIGIT-ADJACENT — immediately
+//    followed by an optional `$`/`.` and a digit (`~10`, `~$5`, `~.5`). Intended
+//    strikethrough wraps WORDS (`~~deprecated~~`, `~struck~`) → its tildes are
+//    letter-adjacent, never matched. We arm only when 2+ such digit-adjacent
+//    tildes exist in prose (one alone can never form a pair), then escape them.
+//    This also catches the inner tilde of a `~~10` double-open.
+//
+//  • MARK / SPOILER: the delimiter is accidental only when it is a binary
+//    OPERATOR — i.e. flanked by a word char on BOTH sides (`x==y`, `a||b`).
+//    An INTENDED `==mark==` / `||spoiler||` has its opening delimiter preceded
+//    by whitespace/line-start and its closing delimiter followed by
+//    whitespace/line-end, so it is NEVER word-flanked on both sides. We arm only
+//    when 2+ such both-word-flanked operators exist (a lone one cannot form a
+//    span, and a space-flanked `a == b` cannot open a span under CommonMark
+//    left/right-flanking rules, so both are correctly left alone), then escape.
+//
+// When in doubt we LEAVE IT: a missed neutralisation (reader sees an accidental
+// strike) is strictly better than shredding the agent's intended formatting.
+//
+// ── Mechanics (identical to the dollar guard) ─────────────────────────────
+//  • Code-span/fence aware: reuses `splitCodeSegments` from dollar-math-guard so
+//    NOTHING inside a `` `code` `` span or fenced block is ever touched.
+//  • Deterministic pure string transform; strict NO-OP unless a real signal is
+//    present (2+ of a construct in prose).
+//  • Idempotent: escaped output (`\~`, `\=\=`, `\|\|`) can never re-match the
+//    triggers (the `~` case uses a `(?<!\\)` negative-lookbehind; the `==`/`||`
+//    cases can't recur because the escaped form no longer contains two
+//    consecutive `=`/`|`), so running the guard twice is byte-for-byte stable.
+//
+// ── Telegram assumptions requiring live UAT (Vitest CANNOT cover these) ────
+//  (a) That Telegram's rich parser CONSUMES the backslash so the reader sees a
+//      literal `~` / `=` / `|` (not a visible `\`). Asserted by analogy to
+//      `escapeMarkdown`, which backslash-escapes these very chars and which the
+//      whole card system depends on Telegram stripping.
+//  (b) Whether a SINGLE `~` renders strikethrough on the rich path (GitHub GFM
+//      needs `~~`; Telegram MarkdownV2 uses single `~`). Our digit-adjacent
+//      heuristic is correct under BOTH readings, but the *likelihood* ranking of
+//      the tilde case depends on it.
+//  (c) That `==` highlight and `||` spoiler render for the word-flanked operator
+//      shape (left/right-flanking behaviour).
+// Send real prose through a live agent and confirm literal glyphs before merge.
+
+// `splitProtectedSegments` skips code spans/fences AND markdown link
+// destinations / autolinks / GFM table rows verbatim — so a `~`/`==`/`||` that
+// is STRUCTURAL (in a URL query like `?a==1`, or a table's empty cell `|a||b|`)
+// is never escaped. See code-segments.ts.
+import { splitProtectedSegments } from './code-segments.js'
+
+/** Digit-adjacent tilde: `~` directly before an optional `$`/`.` and a digit
+ *  (`~10`, `~$5`, `~.5`). The `(?<!\\)` keeps it idempotent — an already-escaped
+ *  `\~` is never re-escaped. Global: used for both counting and replacement. */
+const TILDE_APPROX = /(?<!\\)~(?=\$?\.?\d)/g
+
+/** A `==` acting as a binary operator: word char on BOTH sides (`x==y`). Never
+ *  matches an intended `==mark==` (whose delimiters are whitespace-flanked on
+ *  the outside). Idempotency is structural — the escaped `\=\=` holds no two
+ *  consecutive `=`, so it can never re-match. Global. */
+const MARK_OP = /(?<=\w)==(?=\w)/g
+
+/** A `||` acting as a binary operator: word char on BOTH sides (`a||b`). Never
+ *  matches an intended `||spoiler||`. Structurally idempotent like `MARK_OP`.
+ *  Global. */
+const SPOILER_OP = /(?<=\w)\|\|(?=\w)/g
+
+/** Count matches of a global regex in a string (throwaway, resets lastIndex via
+ *  match). */
+function countMatches(text: string, re: RegExp): number {
+  return text.match(re)?.length ?? 0
+}
+
+/**
+ * Neutralise ACCIDENTAL inline-pair formatting (`~…~` strikethrough,
+ * `==…==` highlight, `||…||` spoiler) that Telegram's rich GFM parser would
+ * typeset from ordinary prose.
+ *
+ * Operates on the FINAL rendered rich-markdown string (post-`render`), at the
+ * same `richMessage()` seam as `guardDollarMath`. A strict NO-OP unless the
+ * prose (non-code) content holds 2+ of a construct in its clearly-accidental
+ * shape (digit-adjacent tildes; word-flanked `==`/`||` operators). Code spans /
+ * fenced blocks are NEVER touched, and the agent's DELIBERATE `~~strike~~` /
+ * `||spoiler||` / `==mark==` / `` `code` `` formatting passes through untouched.
+ * Deterministic and idempotent.
+ */
+export function guardAccidentalInlinePairs(text: string): string {
+  // Fast bail: none of the guarded trigger chars are present.
+  if (!/[~=|]/.test(text)) return text
+
+  const segments = splitProtectedSegments(text)
+
+  // Arm each construct independently, counting only PROSE (never code). A single
+  // occurrence can never form a pair, so the threshold is 2.
+  let tildes = 0
+  let marks = 0
+  let spoilers = 0
+  for (const seg of segments) {
+    if (seg.code) continue
+    tildes += countMatches(seg.text, TILDE_APPROX)
+    marks += countMatches(seg.text, MARK_OP)
+    spoilers += countMatches(seg.text, SPOILER_OP)
+  }
+
+  const armTilde = tildes >= 2
+  const armMark = marks >= 2
+  const armSpoiler = spoilers >= 2
+  if (!armTilde && !armMark && !armSpoiler) return text
+
+  return segments
+    .map((seg) => {
+      if (seg.code) return seg.text
+      let out = seg.text
+      // `\~` — first tilde of an accidental pair can no longer pair.
+      if (armTilde) out = out.replace(TILDE_APPROX, () => '\\~')
+      // `\=\=` / `\|\|` — the operator can no longer open/close a span.
+      if (armMark) out = out.replace(MARK_OP, () => '\\=\\=')
+      if (armSpoiler) out = out.replace(SPOILER_OP, () => '\\|\\|')
+      return out
+    })
+    .join('')
+}

package/telegram-plugin/render/line-start-guard.ts

@@ -0,0 +1,167 @@
+// Outbound guard against accidental LINE-START BLOCK CONSTRUCTS (issue #3252,
+// sibling of 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 that markdown server-side with a CommonMark/GFM-family parser. That
+// means a line of ordinary PROSE that merely happens to START with a markdown
+// block-construct trigger (`#`, `>`, `-`/`+`/`*`, or `N.`) can be silently
+// promoted to a heading / blockquote / bullet / ordered-list item the model
+// never intended:
+//   "> 50% of users"  → blockquote        ">2x faster" → blockquote
+//   "# of items"      → heading           "#1 priority" → (see below)
+//   "- 5 degrees"     → bullet            "2026. was a great year" → ol item
+//
+// ── Why this is the HARD, AMBIGUOUS guard family ─────────────────────────
+// Unlike the `$…$` currency case (where math typesetting of a two-dollar span
+// is NEVER wanted), the agent DELIBERATELY emits headings, bullets, ordered
+// lists and blockquotes — Ken's rich-formatting directive treats them as a
+// wanted feature. The SAME leading character means "format this" (intended)
+// or "literal prose" (accidental) depending purely on authorial intent, which
+// is not recoverable from the bytes. A blanket line-start escape would DESTROY
+// intended formatting and is unacceptable. So this guard is deliberately
+// CONSERVATIVE: it escapes ONLY the narrow sub-patterns that are unmistakably
+// accidental and can be disambiguated DETERMINISTICALLY from the byte stream,
+// and it leaves every plausibly-intended construct byte-for-byte untouched.
+// Everything that cannot be made safe is DEFERRED (see the block comment on
+// `escapeAccidentalLineStart` and guard-linestart-note.md), NOT guessed at.
+//
+// ── What this guard ACTUALLY escapes (the safe subset) ───────────────────
+//   1. Blockquote comparison-operator: a line-start `>` glued DIRECTLY to a
+//      digit or `=` (`>2x`, `>50%`, `>=3`). An INTENDED blockquote is always
+//      written `> ` WITH a space; `>` glued to a digit/`=` is a "greater than"
+//      comparison in prose, never a blockquote. Escaping only the no-space,
+//      digit/`=`-adjacent form leaves every real `> quoted line` untouched.
+//   2. Ordered-list with a 4+ digit "number": a line starting `2026. ` /
+//      `1999) ` — i.e. a YEAR or other 4+ digit integer followed by `.`/`)`
+//      and a space. No real numbered list is authored starting at item 2026;
+//      4+ digit leading integers are effectively always accidental years/
+//      quantities. Real lists (`1.`–`999.`) are LEFT ALONE.
+// Both are backslash-escaped (`\>`, `2026\.`) exactly like the dollar guard —
+// `>`, `.`, `)` are ASCII punctuation, escapable per CommonMark's "any ASCII
+// punctuation may be backslash-escaped" rule; Telegram's rich parser strips
+// the backslash the same way `escapeMarkdown` relies on for `~ = | * _`.
+//
+// ── What is DEFERRED (left to the rich-formatting workstream) ────────────
+//   • Heading `# ` (with the required space): indistinguishable from an
+//     INTENDED heading. `#1` / `#foo` (NO space) is not a GFM heading at all
+//     (ATX headings require `#`+space) → Telegram renders it literally → no
+//     guard needed. So there is no safely-guardable heading sub-case.
+//   • Bullet lists `-`/`+`/`*` + space (`- 5 degrees`): genuinely ambiguous
+//     with the heavily-used bullet construct; the glued form `-5` (no space)
+//     is not a list item → already literal → no guard needed. Escaping the
+//     spaced form would eat intended bullets, so the whole family is deferred.
+//   • Ordered-list with 1–3 digit numbers (`1. `, `42. `): ambiguous with a
+//     real numbered list. Decimals (`3.14`) have no space after the dot → not
+//     a list item → already literal.
+//
+// ── Where this runs ──────────────────────────────────────────────────────
+// Same seam as the dollar guard: `richMessage()` (rich-send.ts) — the ONE
+// adapter every `{ markdown }` wire send funnels through. Integration of this
+// function into that seam is done SEPARATELY by the integrator; this file only
+// exports the pure transform + its helpers. `plain`-mode degradations bypass
+// `richMessage` (no markdown parsing) and are correctly untouched.
+//
+// Idempotent: an already-escaped `\>` / `2026\.` no longer matches the
+// accidental patterns (the leading char is now `\`), so re-running is a strict
+// no-op. Code spans / fenced code blocks and 4-space indented code lines are
+// NEVER touched.
+//
+// ── Telegram-parser assumptions requiring live UAT (see note) ────────────
+// Vitest cannot cover server-side Telegram rendering. The two claims this
+// guard rests on — (a) Telegram promotes `>2x` (no space) and `2026. ` to
+// blockquote/ordered-list, and (b) it CONSUMES the escaping backslash so the
+// reader sees a literal `>` / `.` (not `\>` / `\.`) — are asserted by analogy
+// to CommonMark + the `escapeMarkdown` chars Telegram demonstrably strips.
+// Both need a live round-trip before merge. See guard-linestart-note.md.
+
+// Segment splitting is shared across all #3252 guards — one source of truth in
+// render/code-segments.ts. `splitProtectedSegments` skips code spans/fences AND
+// link destinations / autolinks / GFM table rows verbatim.
+import { splitProtectedSegments } from "./code-segments.js";
+
+/** Line-start `>` glued directly to a digit or `=` — the "greater than"
+ *  comparison-operator prose that Telegram wrongly quotes. NOT matched when a
+ *  space follows the `>` (that is an intended blockquote). */
+const ACCIDENTAL_BLOCKQUOTE = /^>[0-9=]/;
+
+/** Line-start 4+ digit integer followed by `.`/`)` then a space or end-of-line
+ *  — a year/quantity Telegram wrongly promotes to an ordered-list item. Real
+ *  lists (1–3 digit markers) are excluded by the `{4,}` bound. */
+const ACCIDENTAL_ORDERED_LIST = /^(\d{4,})([.)])(\s|$)/;
+
+/**
+ * Escape the accidental block-construct trigger at the start of ONE line
+ * (the string must NOT contain a newline). Applies only when the line is a
+ * true line start (the caller guarantees this). A no-op unless the line begins
+ * with one of the narrow, deterministically-accidental patterns above.
+ *
+ * Lines indented 4+ spaces are an indented-code context in CommonMark and are
+ * left verbatim.
+ */
+function escapeAccidentalLineStart(line: string): string {
+  const indent = /^ */.exec(line)![0];
+  // 4+ leading spaces => indented code block; never a block construct here.
+  if (indent.length >= 4) return line;
+  const rest = line.slice(indent.length);
+
+  // 1. Accidental blockquote (`>2x`, `>50%`, `>=3`). Idempotent: an already
+  //    escaped `\>` starts with `\`, so `rest` no longer starts with `>`.
+  if (ACCIDENTAL_BLOCKQUOTE.test(rest)) {
+    return indent + "\\" + rest;
+  }
+
+  // 2. Accidental ordered-list from a 4+ digit number (`2026. was`).
+  //    Idempotent: `2026\.` has a `\` where the delimiter was, so the
+  //    `(\d{4,})([.)])` shape no longer matches.
+  const ol = ACCIDENTAL_ORDERED_LIST.exec(rest);
+  if (ol) {
+    const digits = ol[1];
+    const delim = ol[2];
+    return indent + digits + "\\" + delim + rest.slice(digits.length + 1);
+  }
+
+  return line;
+}
+
+/**
+ * Neutralise accidental line-start block constructs (heading / blockquote /
+ * bullet / ordered-list promotion of prose) on the FINAL rendered rich-markdown
+ * string (post-`render`). CONSERVATIVE and deterministic: escapes ONLY the two
+ * unmistakably-accidental patterns documented above and leaves all plausibly
+ * intended formatting untouched. Code spans / fenced blocks / 4-space indented
+ * code are never touched. Idempotent and a strict no-op absent a real signal.
+ */
+export function guardAccidentalBlockConstructs(text: string): string {
+  // Cheap short-circuit: no `>` and no plausible 4+ digit list marker => no-op.
+  if (!text.includes(">") && !/\d{4,}[.)]/.test(text)) return text;
+
+  const segments = splitProtectedSegments(text);
+  let out = "";
+  // True at text start and immediately after any emitted `\n`.
+  let atLineStart = true;
+
+  for (const seg of segments) {
+    if (seg.code) {
+      out += seg.text;
+      // Code spans never contain a newline; fenced blocks end on backticks, not
+      // a newline. Either way the next char is on the same line unless the code
+      // text itself ends with a newline.
+      atLineStart = seg.text.endsWith("\n");
+      continue;
+    }
+    const lines = seg.text.split("\n");
+    for (let k = 0; k < lines.length; k++) {
+      // A prose segment can begin MID-LINE (right after an inline code span),
+      // so its first line is a real line start only if the running flag says so.
+      const lineIsAtStart = k === 0 ? atLineStart : true;
+      const processed = lineIsAtStart ? escapeAccidentalLineStart(lines[k]) : lines[k];
+      out += processed;
+      if (k < lines.length - 1) out += "\n";
+    }
+    atLineStart = seg.text.endsWith("\n");
+  }
+
+  return out;
+}

package/telegram-plugin/render/rich-render.ts

@@ -67,6 +67,13 @@ export function renderOutbound(
   maxLen: number = RICH_MESSAGE_MAX_CHARS,
 ): RenderResult {
   return renderSafe(parse(text), text, maxLen);
+  // #3252 note: the `$…$` currency-math neutraliser (`guardDollarMath`) is NOT
+  // applied here. It lives at the single wire seam — `richMessage()` in
+  // rich-send.ts — through which EVERY `{ markdown }` send funnels (the
+  // reply-tool final answer, the draft-stream previews this renderer feeds,
+  // cards, approvals). Applying it there guards every markdown-parsed outbound
+  // exactly once (F1), and `plain`-mode degradations correctly bypass it. See
+  // dollar-math-guard.ts for the rationale.
 }
 
 /**