switchroom 0.18.25 → 0.18.27

package/telegram-plugin/gateway/ms365-write-approval.ts

@@ -57,10 +57,27 @@ export interface Ms365WritePreview {
   /** Byte delta — present only for OneDrive uploads with known sizes. */
   sizeBytesBefore?: number;
   sizeBytesAfter?: number;
+  /**
+   * "start → end" human string for calendar events, resolved from Graph.
+   * Present only when the opaque event id resolved successfully (#3267).
+   */
+  eventWhen?: string;
+  /**
+   * Structural before→after diff for the fields the mutation changes
+   * (calendar body/location/time). Present only when resolved (#3267).
+   */
+  changes?: Ms365PreviewChange[];
   /** 1-line agent rationale — advisory; operator should not over-trust. */
   agentRationale?: string;
 }
 
+/** A single before→after change rendered on the card. */
+export interface Ms365PreviewChange {
+  field: string;
+  before?: string;
+  after?: string;
+}
+
 /**
  * Validate a wire payload into a typed Ms365WritePreview. Returns null
  * on malformed input (defense in depth — the hook is trusted but the
@@ -84,10 +101,32 @@ export function validateMs365Preview(input: unknown): Ms365WritePreview | null {
   if (typeof o.deepLink === "string") out.deepLink = o.deepLink;
   if (typeof o.sizeBytesBefore === "number") out.sizeBytesBefore = o.sizeBytesBefore;
   if (typeof o.sizeBytesAfter === "number") out.sizeBytesAfter = o.sizeBytesAfter;
+  if (typeof o.eventWhen === "string") out.eventWhen = o.eventWhen;
+  const changes = sanitizeChanges(o.changes);
+  if (changes) out.changes = changes;
   if (typeof o.agentRationale === "string") out.agentRationale = o.agentRationale;
   return out;
 }
 
+/**
+ * Validate the wire `changes` array into typed before→after entries. Drops
+ * malformed entries defensively; returns undefined when nothing usable.
+ */
+function sanitizeChanges(input: unknown): Ms365PreviewChange[] | undefined {
+  if (!Array.isArray(input)) return undefined;
+  const out: Ms365PreviewChange[] = [];
+  for (const raw of input) {
+    if (!raw || typeof raw !== "object") continue;
+    const c = raw as Record<string, unknown>;
+    if (typeof c.field !== "string" || c.field.length === 0) continue;
+    const entry: Ms365PreviewChange = { field: c.field };
+    if (typeof c.before === "string") entry.before = c.before;
+    if (typeof c.after === "string") entry.after = c.after;
+    out.push(entry);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Handler — DI shape mirrors DriveApprovalHandlerDeps
 // ────────────────────────────────────────────────────────────────────────
@@ -168,6 +207,9 @@ export function buildMs365CardText(p: Ms365WritePreview): string {
     lines.push(`ID:   ${truncate(p.itemId, 96)}`);
   }
   lines.push(`Account: ${truncate(p.accountEmail, 96)}`);
+  if (p.eventWhen) {
+    lines.push(`When: ${truncate(p.eventWhen, 96)}`);
+  }
   if (
     typeof p.sizeBytesBefore === "number" ||
     typeof p.sizeBytesAfter === "number"
@@ -181,13 +223,26 @@ export function buildMs365CardText(p: Ms365WritePreview): string {
   if (p.deepLink) {
     lines.push(`Link: ${truncate(p.deepLink, 256)}`);
   }
+  if (p.changes && p.changes.length > 0) {
+    lines.push("");
+    lines.push("Changes:");
+    for (const c of p.changes.slice(0, 8)) {
+      const before = c.before !== undefined ? truncate(c.before, 96) : "(none)";
+      const after = c.after !== undefined ? truncate(c.after, 96) : "(cleared)";
+      lines.push(`• ${c.field}: ${before} → ${after}`);
+    }
+  }
   if (p.agentRationale) {
     lines.push("");
     lines.push(`💬 ${truncate(p.agentRationale, 512)}`);
   }
   lines.push("");
+  // With a resolved structural diff present the operator is no longer
+  // approving a blind write; soften the attestation warning accordingly.
   lines.push(
-    "⚠️ Weak attestation (RFC §8 v1): operator should click through to verify the actual change before approving. Structural diff coming v1.5.",
+    p.changes && p.changes.length > 0
+      ? "⚠️ Attestation (RFC §8 v1.5): the diff above is derived from live Graph state + the mutation payload. Verify before approving."
+      : "⚠️ Weak attestation (RFC §8 v1): operator should click through to verify the actual change before approving. Structural diff coming v1.5.",
   );
   // hardenCardBreaks: labelled field lines (Agent:/Tool:/Item:/Account:/Size:…)
   // would soft-collapse into one blob under the GFM rich renderer; this card is
@@ -196,8 +251,15 @@ export function buildMs365CardText(p: Ms365WritePreview): string {
 }
 
 function truncate(s: string, n: number): string {
-  if (s.length <= n) return s;
-  return s.slice(0, n - 1) + "…";
+  // Collapse control whitespace (newline / carriage-return / tab) to a single
+  // space FIRST — every field on this card is single-line, and this card is a
+  // security decision surface. A Graph-sourced value like an event subject of
+  // `Team sync\nAccount: attacker@x` would otherwise inject a fake-looking
+  // labelled line onto the card (#3267 review Finding 2). Length-truncation
+  // alone does not defend against this.
+  const oneLine = s.replace(/[\r\n\t]+/g, " ");
+  if (oneLine.length <= n) return oneLine;
+  return oneLine.slice(0, n - 1) + "…";
 }
 
 function humanBytes(bytes: number): string {

package/telegram-plugin/gateway/subagent-handback-inbound-builder.ts

@@ -115,6 +115,18 @@ export function buildSubagentHandbackInbound(opts: {
     meta: {
       source: 'subagent_handback',
       outcome: opts.ctx.outcome,
+      // #3268 — round-trip the fabricated `ts` through `meta.message_id` so it
+      // survives to enqueue. `ev.messageId` at enqueue is parsed from the
+      // channel envelope's `message_id` attribute, which is rendered ONLY from
+      // `meta.message_id` — the top-level `messageId` field does NOT survive the
+      // bridge. Without this, enqueue's `deriveTurnId` returns null → the
+      // dead-air pre-turn card's identity-based adoption never matches (the card
+      // is orphaned + a false "handback never started" reap message fires on
+      // every SUCCESSFUL handback). Mirrors resume-inbound-builder.ts's
+      // `message_id: String(ts)` for the identical enqueue-round-trip reason. It
+      // is NEVER used as a Telegram reply anchor: `parseSourceMessageId` gates
+      // the 13-digit synthetic ts out of the reply-anchor path at enqueue.
+      message_id: String(ts),
       // meta.message_thread_id is the model-visible channel attribute
       // (mirrors the real-inbound shape) so the model's reply targets
       // the dispatching topic. Mirrors gateway.ts:10557.

package/telegram-plugin/gateway/turn-active-marker.ts

@@ -38,6 +38,24 @@ import { join } from "node:path";
 
 export const TURN_ACTIVE_MARKER_FILE = "turn-active.json";
 
+/**
+ * Absolute ceiling (ms) beyond which a turn-active signal cannot reflect a
+ * real in-flight turn. This is the marker sweep's `hardTtlMs` (`gateway.ts`
+ * `sweepStaleTurnActiveMarker` callsite). Exported so the `/model` & `/effort`
+ * busy-gate cross-checks the in-memory turn atom and the pending-approval hold
+ * against the SAME ceiling it sweeps the marker file at (#3262) — instead of
+ * the atom leaking past it and reading as a phantom "active turn" on an idle
+ * session.
+ */
+export const TURN_ACTIVE_HARD_TTL_MS = 10 * 60_000;
+
+/**
+ * Idle-sweep threshold (ms): the marker is swept this soon when the caller
+ * asserts no turn is in flight. Exported alongside the hard TTL so both
+ * bounds have a single source of truth.
+ */
+export const TURN_ACTIVE_IDLE_SWEEP_MS = 60_000;
+
 export interface TurnActiveMarker {
   turnKey: string;
   chatId: string;
@@ -196,3 +214,20 @@ export function readTurnActiveMarkerAgeMs(stateDir: string, now?: number): numbe
     return null; // ENOENT / unstattable → not working
   }
 }
+
+/**
+ * Effective age (ms) of a live turn for the phantom-turn cross-check (#3262):
+ * prefer the turn-active liveness marker's mtime age (touched on every
+ * tool_use / sub-agent activity, so a genuinely long turn keeps it small),
+ * falling back to `now - turnStartedAt` when the marker is absent (e.g. already
+ * swept away). Pure so the fallback branch is unit-testable with an injected
+ * clock. `markerAgeMs` is the result of `readTurnActiveMarkerAgeMs` (null when
+ * the marker is gone).
+ */
+export function effectiveTurnAgeMs(
+  markerAgeMs: number | null,
+  turnStartedAt: number,
+  now: number,
+): number {
+  return markerAgeMs ?? now - turnStartedAt;
+}

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