switchroom 0.19.7 → 0.19.8

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.19.7", COMMIT_SHA = "2ddec4ae";
+var VERSION = "0.19.8", COMMIT_SHA = "c356d3ba";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -23861,7 +23861,8 @@ function getBuiltinDefaultSkillEntries() {
     "switchroom-health",
     "switchroom-runtime",
     "mental-model-curator",
-    "dev-protocol"
+    "dev-protocol",
+    "telegram-formatting"
   ];
   return [
     ...anthropic.map((key) => ({ key, optOutKey: key, source: "anthropic" })),
@@ -29440,6 +29441,11 @@ right answer at all. Structure exists for the reader, not the writer: a two-item
 bullet list is worse than a sentence, a heading on a three-line reply is noise. When
 in doubt, shorter and plainer wins.
 
+Full palette when a rich or long message earns it \u2014 expandable blockquotes, spoilers,
+highlight, code-fence language hints, tables, escaping and chunking rules: load the
+\`telegram-formatting\` skill. Reach for it only when you're actually composing that
+message, never for everyday replies.
+
 Every turn that answers a user message ends with a user-visible \`reply\`
 \u2014 Telegram is all the user sees; your terminal output
 never reaches them.`, TELEGRAM_ENV_PLACEHOLDER = `# Set your bot token: TELEGRAM_BOT_TOKEN=your-token-here

package/dist/host-control/main.js

@@ -26663,7 +26663,7 @@ import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:f
 import { dirname as dirname4, join as join7 } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.19.7";
+var VERSION = "0.19.8";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.7",
+  "version": "0.19.8",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/default/CLAUDE.md.hbs

@@ -72,11 +72,11 @@ The plugin's auto-retain (Stop hook) fires every turn, but in chunked mode each
 
 ### When to synthesize — concrete triggers
 
-Auto-recall and auto-retain keep the bank fed, but they never *synthesize* — that's on you, and it only happens if you act on these triggers. Each is paired with a deterministic backstop so nothing depends on you remembering:
+Auto-recall and auto-retain feed the bank but never *synthesize* — that's on you, only if you act on these triggers. Each has a backstop:
 
-- **Reflect instead of hand-assembling.** When a question needs an answer *across many past memories* — "what did we decide about X", "summarize where Y stands", "have I seen this before" — call `mcp__hindsight__reflect` rather than firing several `recall`s and stitching the fragments yourself. Rule of thumb: if you're about to make 2+ manual `recall` calls to reconstruct one answer, that's a `reflect`. (Backstop: auto-recall already injects the top hits every turn — reflect is the escalation when those aren't enough, not a replacement.)
-- **Propose a model when you keep re-deriving.** When you notice you've rebuilt the *same standing answer* two or three sessions running — the recurring state of your specialty a user keeps asking around — stop re-deriving and propose a mental model via `mcp__switchroom-telegram__mental_model_propose(name, source_query)` (or run the `mental-model-curator` skill to survey the bank and propose the earned few). One organic proposal beats ten reflexive recalls. Don't propose for a one-off fact — that's a `retain`; don't propose identity/"who is the user" — profile banks own that.
-- **Merge or retire directives when they pile up.** Directives are capped at `MAX_DIRECTIVES=15` active per bank — past that, the lowest-priority ones are silently truncated from the `<active_directives>` recall block and never reach you. When directives start overlapping or reading stale, run the `mental-model-curator` skill's directive merge/retire pass (it proposes; deletes stay operator-approved). (Backstop: `switchroom doctor` WARNs at >12 and FAILs at >15 active directives, so the pile-up surfaces on the issues card even if you don't notice it in-session.)
+- **Reflect instead of hand-assembling.** About to fire 2+ manual `recall`s for one answer ("summarize where Y stands")? Call `mcp__hindsight__reflect` instead. (Backstop: auto-recall injects the top hits every turn — reflect is the escalation.)
+- **Propose a model when you keep re-deriving.** Rebuilt the *same standing answer* across sessions? Propose a mental model via `mcp__switchroom-telegram__mental_model_propose(name, source_query)` (or run the `mental-model-curator` skill). Not for a one-off fact (`retain`) or identity (profile banks own that).
+- **Merge or retire directives when they pile up.** Directives cap at `MAX_DIRECTIVES=15` active per bank — past that the lowest-priority ones drop silently from recall. When they overlap or read stale, run the `mental-model-curator` merge/retire pass (deletes stay operator-approved). (Backstop: `switchroom doctor` WARNs at >12, FAILs at >15.)
 
 ## Sub-Agent Delegation
 

package/skills/telegram-formatting/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: telegram-formatting
+description: >
+  Use when composing a rich or long Telegram reply and you want the full
+  formatting palette with exact syntax — expandable blockquotes, spoilers,
+  highlight, code-fence language hints, GFM tables, nested lists — plus the
+  escaping rules and the framework's send-time chunking/normalizer behaviour.
+  Load it when a message genuinely needs structure, NOT for everyday short
+  replies (plain prose already wins there). Teaches judgment first: which
+  construct helps the reader vs when plain text is better. Do NOT use for
+  deciding whether to reply, or for non-Telegram output.
+---
+
+# Telegram formatting — the full palette
+
+Every outbound Switchroom message renders as raw GFM markdown over Telegram
+Bot API 10.1 rich messages (`telegram-plugin/rich-send.ts` `richMessage(md)` →
+`{ markdown }` → `sendRichMessage` / `editMessageText({ markdown })`). No HTML,
+no `parse_mode`. This skill is the depth reference behind the boot-injected
+floor card: the full construct vocabulary, correct syntax, escaping, and the
+send-time behaviour you can rely on.
+
+## Judgment first — reach for structure only when it helps the reader
+
+The floor card's stance is the law here too: **structure exists for the reader,
+not the writer.** Loading this skill does not mean "use everything below." Match
+the construct to the message.
+
+- **Short answers (a line or two): plain prose, no formatting.** "on it,
+  pulling the logs now" is already perfect. No bold, no bullets, no headings.
+  Most replies live here — don't dress them up.
+- **Default: light structure.** Bold ONLY the one key fact or answer, never
+  more. A list only for 3+ genuinely parallel items the reader will scan or
+  compare; two items or a flowing thought stay prose. `code spans` for
+  identifiers (filenames, commands, config keys, error codes) — tap-to-copy.
+- **Long / multi-section answers may add the rich constructs below** — tables,
+  headings, blockquotes, expandable blocks, fences — but only when they cut the
+  reader's effort. If the structure doesn't reduce scanning effort, drop it. A
+  two-item bullet list is worse than a sentence; a heading on a three-line reply
+  is noise. When in doubt, shorter and plainer wins.
+
+Over-bolded messages (most of the text bold, whole paragraphs/lists bolded) get
+their bold stripped at send time — so bold sparingly and deliberately.
+
+## Full rich vocabulary
+
+### Inline spans
+
+| Effect | Markdown | When / notes |
+| --- | --- | --- |
+| Bold | `**text**` | The one key fact or answer, not decoration. |
+| Italic | `*text*` or `_text_` | Light emphasis, labels, asides. |
+| Strikethrough | `~~text~~` | Retractions, "was X now Y". |
+| Spoiler | `\|\|text\|\|` | Only for an opt-in surprise or a reveal the reader chose to wait for (a punchline they want suspended) — NEVER to hide an answer someone is asking for or anxious about; when in doubt, show it plainly. Surfaces as a `spoiler` entity on the wire (live-verified 2026-07). |
+| Highlight / marked | `==text==` | Surfaces as a `marked` entity on the wire (live-verified 2026-07). `=` is an `escapeMarkdown` special, so dynamic text won't trigger it by accident. |
+| Inline code | `` `text` `` | Identifiers, tap-to-copy. Content is literal — no escaping inside. |
+| Link | `[label](https://…)` | Standard GFM link. |
+
+**Do NOT rely on these — they don't render as intended:**
+
+- **Underline** — there is NO underline token on this path. `__text__` renders
+  as **bold** (Telegram's rich-message markdown parser reads a `__…__` run
+  identically to `**…**`, live-verified against the Bot API 2026-07). Use `**`
+  for bold and don't reach for underline.
+- **Subscript** `~text~` (single tilde) and **superscript** `^text^` fall back
+  to literal text in rich messages — avoid (write "squared", not `x^2^`).
+- **Custom emoji** (premium custom-emoji entity) renders as a normal emoji for
+  non-premium viewers — don't rely on it to carry meaning.
+
+(Inline math `$…$`, HTML `<details>`/collapsible, and footnotes `[^1]` are NOT
+supported on this path — do not emit them; they degrade to literal or neutralised
+text.)
+
+### Block types
+
+- **Code fence** — ` ```lang ` … ` ``` `. Multi-line literal output (diffs,
+  logs, JSON, command blocks). The language hint (`diff`, `json`, `bash`, …)
+  sharpens syntax rendering — use it. Content inside is verbatim, never escape
+  it; the only hazard is an embedded ` ``` ` closing the block early, which the
+  framework defuses (`preBlock` in `shared/bot-runtime.ts`).
+- **Preformatted block** — a code fence with NO language, for fixed-width
+  non-code (ASCII tables, aligned columns).
+- **Bulleted list** — `- item` (also `*` / `+`). 3+ parallel items only.
+- **Numbered list** — `1. item`. Ordered steps or ranked items.
+- **Nested lists** — indent sub-items; tight (no blank lines) vs loose (blank
+  lines between items) both render. 3-level nesting is live-verified.
+- **Task list** — `- [ ] todo` / `- [x] done`.
+- **Table** — GFM pipe table (`| col | col |` + `| --- | --- |` separator),
+  optional per-column alignment (`:---`, `:---:`, `---:`). 2-D data ONLY (rows ×
+  columns) — not a substitute for prose. Chunk-safe: `splitMarkdownChunks` never
+  bisects a row.
+- **Blockquote** — `> quoted`. Quoted text or an indented continuation; the
+  right way to indent, because Telegram drops leading whitespace.
+- **Expandable blockquote** — `**> …` (Bot API 10.1). A long quote/aside the
+  reader can collapse and expand. The flagship rich construct — use it for a
+  long quotation, a stack trace, or a detailed aside you don't want dominating
+  the message. First line carries the `**> ` marker; continuation lines use `> `.
+- **Section heading** — `#` … `######`. Only in a genuinely long, multi-section
+  answer. Never on a short reply.
+- **Divider** — `---` (thematic break). Heavy horizontal rule between genuinely
+  separate sections. Use sparingly.
+- **Collage / album** — multiple images grouped in one message (media group).
+  Send via the attachment path, not markdown.
+
+## Escaping rules
+
+Dynamic content (filenames, ids, arbitrary user text) interpolated into a
+hand-built markdown card MUST be escaped so it renders LITERALLY instead of
+being parsed as formatting. Use `escapeMarkdown(value)` from
+`telegram-plugin/format.ts`.
+
+`escapeMarkdown` escapes exactly the characters that trigger INLINE formatting:
+backslash, `` ` ``, `*`, `_`, `~`, `=`, `[`, `]`, `|` — the set `` \`*_~=[]| ``.
+The backslash is escaped first so it never double-escapes a following special.
+It deliberately does **not** escape `.` `-` `+` `#` `(` `)` `{` `}` `!` `>`:
+those are only meaningful at line-start or in link/structure context, and
+escaping them mid-word would litter filenames (`foo.ts`), versions (`v1.2-rc`),
+and URLs with visible backslashes.
+
+- **Bold/italic a dynamic value:** `` `**${escapeMarkdown(value)}**` ``.
+- **Code-span a dynamic value:** `` `\`${value}\`` `` — code spans need NO
+  escaping (backtick content is already literal). This is the preferred, safest
+  way to render any identifier.
+
+## Send-time behaviour you can rely on
+
+- **Chunking.** Hard cap is `RICH_MESSAGE_MAX_CHARS = 32768` (32768 accepted,
+  32769 rejected — the single constant, never re-derive it). A longer body is
+  split by `splitMarkdownChunks(text, 32768)` in `format.ts`: it cuts at the
+  largest safe boundary (blank line → newline → space), **never bisects a fenced
+  code block** (`backOffOpenFence`) and **never bisects a table row**
+  (`backOffTableRow`). A single indivisible region larger than the cap is
+  emitted whole and re-split / hard-sliced at send time rather than hanging.
+  Long before 32768, ask whether a wall of text is the right answer at all.
+- **Typography normalizer (deterministic, every message).** Block spacing (one
+  blank line between distinct blocks), em/en dashes, and `•` bullet markers are
+  rewritten at send time. A LONE `\n` between two prose paragraphs is promoted
+  to a real visual break; runs of 3+ newlines collapse to `\n\n`; lists, tables,
+  code, and existing `\n\n` gaps are left exactly as written. Don't hand-tune
+  spacing or fight the normalizer — write the content, the gateway makes the
+  typography consistent.
+
+## The one rule that outranks everything here
+
+You loaded this skill to format a rich message well — but the best formatting is
+still the least that serves the reader. Use the palette to make a genuinely
+complex answer scannable, never to decorate a simple one.

package/telegram-plugin/dist/gateway/gateway.js

@@ -41612,6 +41612,7 @@ function shouldEmitShadowTrace(eventKind, effectCount, globalKind, verbose = gwT
 }
 
 // shared/bot-runtime.ts
+init_rich_send();
 var tgPostTagStore = new AsyncLocalStorage;
 function escapeHtmlForTg(text) {
   return text.replace(/([\\`*_~=\[\]|])/g, "\\$1");
@@ -62511,6 +62512,7 @@ import { createHash as createHash2 } from "crypto";
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 init_flood_circuit_breaker();
 init_format();
+init_rich_send();
 var tgPostTagStore2 = new AsyncLocalStorage2;
 function _getTgPostTags() {
   return tgPostTagStore2.getStore();
@@ -62555,6 +62557,21 @@ function installTgPostLogger(bot) {
     }
   });
 }
+function installRichMarkdownGuard(bot) {
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    if ((method === "sendRichMessage" || method === "editMessageText") && payload != null) {
+      const p = payload;
+      const rich = p.rich_message;
+      if (rich != null && typeof rich.markdown === "string") {
+        const guarded = guardAccidentalFormatting(rich.markdown);
+        if (guarded !== rich.markdown) {
+          p.rich_message = { ...rich, markdown: guarded };
+        }
+      }
+    }
+    return prev(method, payload, signal);
+  });
+}
 
 // flood-circuit-breaker.ts
 import {
@@ -93551,10 +93568,10 @@ function startGatewayHeartbeat(stateDir, intervalMs = GATEWAY_HEARTBEAT_INTERVAL
 }
 
 // ../src/build-info.ts
-var VERSION = "0.19.7";
-var COMMIT_SHA = "2ddec4ae";
-var COMMIT_DATE = "2026-07-20T19:59:43Z";
-var LATEST_PR = 3478;
+var VERSION = "0.19.8";
+var COMMIT_SHA = "c356d3ba";
+var COMMIT_DATE = "2026-07-20T23:16:37Z";
+var LATEST_PR = 3483;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -106426,6 +106443,7 @@ async function initGatewayBot() {
   }
   bot = new import_grammy15.Bot(TOKEN);
   installTgPostLogger(bot);
+  installRichMarkdownGuard(bot);
   installUpdateTap(bot, (line) => process.stderr.write(line));
   bot.api.config.use(async (prev, method, payload, signal) => {
     try {

package/telegram-plugin/gateway/gateway.ts

@@ -295,7 +295,7 @@ import {
 } from '../retry-api-call.js'
 import { createSendGate, sendGateConfigFromEnv, isSendGateShed } from '../send-gate.js'
 import { createStatsLogger, createFloodWindowObserver } from '../send-gate-observability.js'
-import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
+import { installTgPostLogger, installRichMarkdownGuard, withTgPostTags } from '../shared/bot-runtime.js'
 import {
   floodStatePath,
   floodWindowsPath,
@@ -22970,7 +22970,7 @@ async function initGatewayBot(): Promise<void> {
   }
 
   bot = new Bot(TOKEN)
-  installTgPostLogger(bot)
+  installTgPostLogger(bot); installRichMarkdownGuard(bot) // #3252/#3463: universal fmt guard installed after logger (composes outermost); see installRichMarkdownGuard docblock
 
   // Diagnostic update tap (#3300): one compact line per received update, logged
   // BEFORE any specific handler runs, so a routing-layer drop is diagnosable

package/telegram-plugin/render/ir.ts

@@ -1,38 +1,44 @@
-// Typed intermediate representation (IR) for the Telegram HTML render engine.
+// Typed intermediate representation (IR) for the Telegram rich-markdown render
+// engine. (Historical note: this file and render.ts were named for an "HTML
+// render engine" during Increment 1, before the Bot API 10.1 migration (#2669)
+// made GFM `{ markdown }` the live send path. There is NO HTML anywhere on the
+// outbound path today — the renderer in render.ts emits raw GFM markdown for
+// the `markdown` field of `InputRichMessageMarkdown`.)
 //
 // This is the parser <-> renderer contract. `parse()` (parse.ts) folds an
-// mdast tree into this shape; a later increment's renderer walks it and emits
-// Telegram Bot API HTML. Increment 1 lands ONLY the parser + this IR — there
-// is no renderer yet.
+// mdast tree into this shape; `render.ts` walks it and emits Telegram
+// rich-message GFM markdown.
 //
 // Every node carries `{ start, end }` UTF-16 source offsets copied verbatim
 // from mdast `position.start.offset` / `position.end.offset`. They are UTF-16
 // code-unit indices into the original markdown string, so
 // `source.slice(node.start, node.end)` round-trips to the node's source text.
 //
-// Telegram HTML tag mapping (for the next increment — NOT implemented here):
+// IR node -> emitted GFM markdown (see render.ts `renderInline`/block render):
 //
 //   Inline
-//     plain     -> (raw text, HTML-escaped)
-//     bold      -> <b>…</b>                 (markdown `**…**`)
-//     italic    -> <i>…</i>                 (markdown `*…*`)
-//     underline -> <u>…</u>                 (markdown `__…__`, Bot API 10.1)
-//     strike    -> <s>…</s>                 (markdown `~~…~~`)
-//     spoiler   -> <tg-spoiler>…</tg-spoiler> (markdown `||…||`)
-//     highlight -> <mark>…</mark>           (markdown `==…==`, Bot API 10.1)
-//     code      -> <code>…</code>
-//     link      -> <a href="…">…</a>
+//     plain     -> raw text (escapeMarkdown'd)
+//     bold      -> `**…**`
+//     italic    -> `*…*`
+//     underline -> `__…__`  — NOTE: the wire renders `__…__` as BOLD, not
+//                  underline. Telegram's rich-message markdown has no underline
+//                  token (live-verified, see reference/telegram-formatting-guide.md).
+//                  The node preserves the author's `__` bytes faithfully; it is
+//                  a distinct IR node but NOT a distinct wire style.
+//     strike    -> `~~…~~`
+//     spoiler   -> `||…||`
+//     highlight -> `==…==`  (Bot API 10.1 marked entity)
+//     code      -> `` `…` ``
+//     link      -> `[…](…)`
 //
 //   Block
 //     paragraph      -> children joined; blocks separated by "\n\n"
-//     heading        -> <b>…</b> (Telegram HTML has no <h1>…<h6>; bold + newlines)
-//     blockquote     -> <blockquote>…</blockquote>
-//                       (expandable === true -> <blockquote expandable>)
-//     code-block     -> <pre><code class="language-…">…</code></pre>
-//     list           -> rendered line-per-item with "•"/"1." bullets
-//                       (Telegram HTML has no <ul>/<ol>)
-//     thematic-break -> a horizontal-rule text line (e.g. "───")
-//     table          -> monospaced <pre> table (Telegram HTML has no <table>)
+//     heading        -> `#`…`######` line
+//     blockquote     -> `> …` (expandable === true -> `**> …` expandable blockquote)
+//     code-block     -> ```` ```lang … ``` ````
+//     list           -> line-per-item with `-`/`1.` markers
+//     thematic-break -> `---` thematic break
+//     table          -> GFM pipe table
 
 export interface Pos {
   /** UTF-16 code-unit offset of the node's first char (mdast position.start.offset). */
@@ -60,10 +66,12 @@ export interface ItalicNode extends Pos {
   children: Inline[];
 }
 
-/** Telegram underline (<u>…</u>). In Bot API 10.1 rich markdown the `__…__`
- *  double-underscore run is UNDERLINE — distinct from `**…**` bold, even though
- *  GFM/micromark folds both into a single `strong` mdast node. `parse.ts`
- *  disambiguates the two by looking at the run's source delimiter. */
+/** A `__…__` double-underscore run. `parse.ts` keeps it as a distinct node
+ *  (separate from `**…**` bold) by looking at the source delimiter, even though
+ *  GFM/micromark folds both into a single `strong` mdast node. NOTE: on the
+ *  Telegram wire this renders as BOLD, not a distinct underline style — Bot API
+ *  10.1 rich markdown has no underline entity here, so the round-trip is faithful
+ *  but the delivered text is bold. Kept distinct only to preserve authoring intent. */
 export interface UnderlineNode extends Pos {
   type: "underline";
   children: Inline[];

package/telegram-plugin/render/render.ts

@@ -1,6 +1,7 @@
-// IR -> Telegram rich-markdown renderer for the Telegram HTML render engine
-// (name kept for continuity with render/ir.ts + render/parse.ts; the actual
-// wire format is GFM markdown, NOT HTML — see the note below).
+// IR -> Telegram rich-markdown renderer. (The render/ir.ts + render/parse.ts
+// files were originally named for an "HTML render engine"; that name is
+// historical — the actual wire format is GFM markdown, NOT HTML. See the note
+// below and the refreshed header in render/ir.ts.)
 //
 // Increment 2 of the render pipeline: takes the typed IR produced by
 // `parse.ts` (per `ir.ts`) and emits a string suitable for the `markdown`
@@ -67,6 +68,11 @@ function renderInline(node: Inline, ctx: InlineCtx = {}): string {
     case "italic":
       return `*${renderInlineChildren(node.children, ctx)}*`;
     case "underline":
+      // The wire renders `__…__` as BOLD, not underline — Telegram's
+      // rich-message markdown has no underline token (live-verified; see
+      // reference/telegram-formatting-guide.md). We preserve the author's `__`
+      // bytes faithfully rather than rewriting them to `**`; the IR keeps
+      // underline as a distinct node, but it is NOT a distinct wire style.
       return `__${renderInlineChildren(node.children, ctx)}__`;
     case "strike":
       return `~~${renderInlineChildren(node.children, ctx)}~~`;
@@ -284,6 +290,9 @@ export const SUPPORTED_INLINE = [
   "plain",
   "bold",
   "italic",
+  // "underline" parses `__…__` into a distinct node and round-trips it, but the
+  // wire renders it as BOLD (no underline token on this path). Kept for faithful
+  // `__` byte round-trip, NOT because it is a distinct rendered style.
   "underline",
   "strike",
   "spoiler",

package/telegram-plugin/rich-send.ts

@@ -67,16 +67,22 @@ export function guardAccidentalFormatting(markdown: string): string {
 /**
  * Wrap raw GFM markdown into the rich-message input object.
  *
- * This is the ONE adapter every `{ markdown }` wire send funnels through
- * (`sendRichMessage` / `editMessageText({ markdown })`) — the reply-tool final
- * answer, draft-stream previews, cards, approvals, banners. It is therefore the
- * single deterministic seam for the #3252 accidental-formatting guards (F1):
- * applying `guardAccidentalFormatting` here guards EVERY markdown-parsed
- * outbound exactly once, without touching `plain`-mode degradations (which
- * bypass this wrapper and go straight to `sendMessage`, where no markdown
- * parsing happens). The composed guard is a strict no-op for any body without
- * an accidental-formatting signal and is idempotent, so callers that already
- * ran it (or the streaming path that renders then re-wraps) stay byte-identical.
+ * This is a CONVENIENCE adapter — NOT the universal seam. It applies
+ * `guardAccidentalFormatting` for the many callers that build a body through
+ * it (the reply-tool final answer, draft-stream previews, cards), but it is
+ * NOT the one place every `{ markdown }` wire send funnels through: several
+ * sites build a raw `{ markdown }` and call `sendRichMessage` /
+ * `editMessageText` directly, bypassing this wrapper (see the correctness
+ * audit's F1 list — banners, switchroomReply html, approval/folder-picker
+ * edits). The REAL universal seam for the #3252 accidental-formatting guards
+ * is the grammy API transformer `installRichMarkdownGuard`
+ * (`shared/bot-runtime.ts`), installed on the production Bot in gateway boot,
+ * which guards EVERY sendRichMessage/editMessageText payload regardless of the
+ * call site. This wrapper is kept belt-and-braces: the composed guard is a
+ * strict no-op for any body without an accidental-formatting signal and is
+ * idempotent, so a body guarded here and re-guarded by the transformer stays
+ * byte-identical. `plain`-mode degradations bypass both (they go straight to
+ * `sendMessage`, where no markdown parsing happens).
  */
 export function richMessage(markdown: string): InputRichMessageMarkdown {
   return { markdown: guardAccidentalFormatting(markdown) }

package/telegram-plugin/shared/bot-runtime.ts

@@ -32,6 +32,7 @@ import { createRetryApiCall } from '../retry-api-call.js'
 import { makeFloodWaitRecorder, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { shouldEmitTgPost } from './gw-trace-gate.js'
+import { guardAccidentalFormatting } from '../rich-send.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
 
@@ -147,6 +148,62 @@ export function installTgPostLogger(bot: Bot): void {
   })
 }
 
+/**
+ * Universal accidental-formatting guard, installed as a grammy API transformer
+ * on the single production Bot (#3252/#3463 follow-up). This is the REAL
+ * universal seam — not `richMessage()`. `richMessage()` only guards bodies its
+ * callers remember to wrap; the correctness audit found ~6 sites that build a
+ * raw `{ markdown }` and call `sendRichMessage` / `editMessageText` directly,
+ * bypassing it (`shared/bot-runtime.ts` switchroomReply html path,
+ * `slot-banner-driver.ts` OAuth banners, and edits in `folder-picker-handler`,
+ * `approval-callback`, `inline-keyboard-callbacks`). A transformer at the
+ * grammy `bot.api.config.use` layer sees every rich send regardless of the
+ * call site, `ctx.*` sugar, `lockedBot`, or `bot.api.raw`, so it closes the
+ * whole bypass class deterministically.
+ *
+ * Payload shape (verified against grammy 1.44.0 `out/core/api.js`, the pinned
+ * lockfile version):
+ *   - `sendRichMessage(chat_id, rich_message, ...)` → raw payload
+ *     `{ chat_id, rich_message: { markdown }, ... }`
+ *   - `editMessageText(chat_id, message_id, arg, ...)` → raw payload
+ *     `{ ..., rich_message: { markdown } }` when `arg` is an object, or
+ *     `{ ..., text }` when `arg` is a plain string.
+ * The markdown therefore lives at `payload.rich_message.markdown`, NOT
+ * `payload.markdown` (gating on the latter matches nothing — a silent no-op).
+ * Gating on `rich_message?.markdown` also structurally skips every literal /
+ * plain-string edit (they carry `text`, not `rich_message`), so those pass
+ * through byte-identical. `sendRichMessageDraft` is not wired in the repo
+ * (draft streaming uses sendMessage+editMessageText); extend the method gate
+ * here if a future draft adopter starts using it.
+ *
+ * The composed `guardAccidentalFormatting` is idempotent, so double-guarding a
+ * `richMessage()`-wrapped body that also passes through here is byte-identical
+ * (the internal guard in `richMessage()` is kept belt-and-braces).
+ *
+ * We clone `rich_message` before mutating: callers can share the object by
+ * reference (e.g. `richMessage()` output reused across a retry), and a
+ * transformer must not mutate the caller's input.
+ */
+export function installRichMarkdownGuard(bot: Bot): void {
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    if (
+      (method === 'sendRichMessage' || method === 'editMessageText') &&
+      payload != null
+    ) {
+      const p = payload as Record<string, unknown>
+      const rich = p.rich_message as { markdown?: unknown } | undefined
+      if (rich != null && typeof rich.markdown === 'string') {
+        const guarded = guardAccidentalFormatting(rich.markdown)
+        if (guarded !== rich.markdown) {
+          // Clone rather than mutate the caller's shared object.
+          p.rich_message = { ...rich, markdown: guarded }
+        }
+      }
+    }
+    return prev(method, payload, signal)
+  })
+}
+
 // ─── robustApiCall factory ────────────────────────────────────────────────
 
 /**

package/telegram-plugin/tests/format-guard-pins.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Pin tests for the accidental-formatting guard (#3252/#3463).
+ *
+ * Two internal-hardening assertions, no user-visible change:
+ *
+ *  1. Documents the `#{1,6}` cap in ACCIDENTAL_HEADING as intentional: a run of
+ *     7+ `#` glued to non-space is left UNescaped (CommonMark caps heading
+ *     promotion at 6 `#`, and the guard mirrors that). Correctness-audit F2
+ *     flagged this as asserted-but-untested.
+ *
+ *  2. A wiring assertion that PR1's `installRichMarkdownGuard` transformer is
+ *     actually installed on the production Bot in `initGatewayBot()`, so the
+ *     universal seam can't be silently dropped in a later refactor. Grammy's
+ *     installed transformers are anonymous fns (nothing to grip at runtime), so
+ *     this is a source-level AST assertion on the boot path — the same approach
+ *     `gateway-bot-construction-deferral.test.ts` uses.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+import { guardAccidentalFormatting } from '../rich-send.js'
+import { guardAccidentalHeading } from '../render/line-start-guard.js'
+
+describe('accidental-heading guard: #{1,6} cap is intentional (F2)', () => {
+  it('escapes a 6-# run glued to non-space (upper bound of the cap)', () => {
+    expect(guardAccidentalHeading('######x')).toBe('\\######x')
+    expect(guardAccidentalFormatting('######x')).toBe('\\######x')
+  })
+
+  it('leaves a 7-# run glued to non-space UNescaped (past the CommonMark cap)', () => {
+    expect(guardAccidentalHeading('#######x')).toBe('#######x')
+    expect(guardAccidentalFormatting('#######x')).toBe('#######x')
+  })
+
+  it('leaves an 8+-# run glued to non-space UNescaped', () => {
+    expect(guardAccidentalHeading('##########x')).toBe('##########x')
+    expect(guardAccidentalFormatting('##########x')).toBe('##########x')
+  })
+})
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
+const sourceFile = ts.createSourceFile(
+  GATEWAY_PATH,
+  GATEWAY_SRC,
+  ts.ScriptTarget.Latest,
+  true,
+  ts.ScriptKind.TS,
+)
+
+function findFunction(name: string): ts.FunctionDeclaration | undefined {
+  for (const s of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(s) && s.name?.text === name) return s
+  }
+  return undefined
+}
+
+function countCallsTo(root: ts.Node, name: string): number {
+  let count = 0
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === name
+    ) {
+      count++
+      // Installed on the constructed bot instance.
+      expect(node.arguments[0]?.getText(sourceFile)).toBe('bot')
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return count
+}
+
+describe('boot wiring: installRichMarkdownGuard is installed on the production Bot', () => {
+  it('imports installRichMarkdownGuard from ../shared/bot-runtime.js', () => {
+    // The import must exist for the boot call to resolve; a refactor that drops
+    // the import would break the seam.
+    expect(GATEWAY_SRC).toMatch(
+      /import\s*\{[^}]*\binstallRichMarkdownGuard\b[^}]*\}\s*from\s*'\.\.\/shared\/bot-runtime\.js'/,
+    )
+  })
+
+  it('calls installRichMarkdownGuard(bot) exactly once inside initGatewayBot()', () => {
+    const fn = findFunction('initGatewayBot')
+    expect(fn?.body).toBeDefined()
+    expect(countCallsTo(fn!.body!, 'installRichMarkdownGuard')).toBe(1)
+  })
+})

package/telegram-plugin/tests/render/underline-wire-outcome.test.ts

@@ -0,0 +1,32 @@
+/**
+ * Truth-pass pin (#3252 formatting-truth follow-up): the REAL wire outcome for
+ * a `__…__` run.
+ *
+ * The parser folds `__x__` into a distinct `underline` IR node and the renderer
+ * round-trips it back to `__x__` (asserted in parse.test.ts / render.test.ts).
+ * But Telegram's rich-message markdown has NO underline token: the wire renders
+ * `__x__` identically to `**x__` — i.e. as BOLD (live-verified 2026-07, see
+ * reference/telegram-formatting-guide.md).
+ *
+ * Decision (documented in the fmt-audit BUILD-LOG): we keep the underline node
+ * and faithfully preserve the author's `__` bytes rather than rewriting them to
+ * `**` — full removal would invert several green tests and change wire bytes for
+ * zero wire-visible benefit (both render as bold). This test pins the honest
+ * contract: `__x__` emits `__x__`, which the wire treats as bold, NOT a distinct
+ * underline style.
+ */
+import { describe, it, expect } from "vitest";
+import { parse } from "../../render/parse.js";
+import { render } from "../../render/render.js";
+
+describe("underline: real wire outcome for `__…__`", () => {
+  it("round-trips `__x__` to `__x__` on the wire (which Telegram renders as BOLD)", () => {
+    // The emitted bytes preserve the author's `__` delimiters verbatim.
+    expect(render(parse("__x__"))).toBe("__x__");
+  });
+
+  it("does NOT rewrite `__x__` to `**x**` (author bytes preserved, not normalised to bold syntax)", () => {
+    expect(render(parse("__underlined__"))).not.toContain("**");
+    expect(render(parse("__underlined__"))).toBe("__underlined__");
+  });
+});

package/telegram-plugin/tests/rich-markdown-guard-transformer.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Wire-level outcome tests for the universal accidental-formatting guard
+ * (`installRichMarkdownGuard`, #3252/#3463 follow-up).
+ *
+ * These MUST go through a REAL grammy `Bot` with a stubbed transport. The
+ * existing unit/golden harnesses (`tests/bot-api.harness.ts` etc.) mock the
+ * `api` object ABOVE the grammy transformer layer, so `api.config.use`
+ * transformers never run there — a test written through them is a FALSE guard
+ * (it stays green with the transformer absent or mis-gated). By stubbing
+ * `client.fetch` we capture the exact serialized wire body AFTER the
+ * transformer has mutated the raw payload, which is the only place the guard's
+ * effect is observable.
+ *
+ * Red-team F-R1: the markdown lives at `payload.rich_message.markdown`, NOT
+ * `payload.markdown`. A guard gating on the latter matches nothing and every
+ * one of these assertions would still fail — so these tests pin the correct
+ * field shape too.
+ */
+import { describe, it, expect } from 'vitest'
+import { Bot } from 'grammy'
+import { installTgPostLogger, installRichMarkdownGuard } from '../shared/bot-runtime.js'
+
+interface CapturedCall {
+  method: string
+  body: Record<string, unknown>
+}
+
+/**
+ * Build a real grammy Bot whose transport is stubbed: every API call is
+ * captured (method + parsed JSON body) and answered with a minimal ok
+ * response. `botInfo` is supplied so `bot.init()` never hits the network.
+ */
+function makeCapturingBot(): { bot: Bot; calls: CapturedCall[] } {
+  const calls: CapturedCall[] = []
+  const fakeFetch = (async (url: unknown, init?: { body?: unknown }) => {
+    const method = String(url).split('/').pop() ?? ''
+    let body: Record<string, unknown> = {}
+    if (typeof init?.body === 'string') {
+      body = JSON.parse(init.body) as Record<string, unknown>
+    }
+    calls.push({ method, body })
+    // Minimal Telegram ok envelope. `result` shape doesn't matter for these
+    // send/edit calls — grammy only reads `ok`/`result`.
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ ok: true, result: { message_id: 1, date: 0, chat: { id: 1, type: 'private' } } }),
+    } as unknown as Response
+  }) as unknown as typeof fetch
+
+  const bot = new Bot('123456:TEST_TOKEN', {
+    botInfo: {
+      id: 123456,
+      is_bot: true,
+      first_name: 'Test',
+      username: 'test_bot',
+      can_join_groups: false,
+      can_read_all_group_messages: false,
+      supports_inline_queries: false,
+      can_connect_to_business: false,
+      has_main_web_app: false,
+    },
+    client: { fetch: fakeFetch },
+  })
+  // Install exactly the production transformer stack ordering: logger first,
+  // then guard (guard composes outermost — grammy runs last-installed first).
+  installTgPostLogger(bot)
+  installRichMarkdownGuard(bot)
+  return { bot, calls }
+}
+
+function lastRichMarkdown(calls: CapturedCall[]): unknown {
+  const c = calls[calls.length - 1]
+  return (c.body.rich_message as { markdown?: unknown } | undefined)?.markdown
+}
+
+describe('installRichMarkdownGuard — universal wire seam', () => {
+  it('(a) escapes a raw { markdown } sendRichMessage on the wire', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.sendRichMessage(1, { markdown: '#3460 done' })
+    expect(calls[calls.length - 1].method).toBe('sendRichMessage')
+    expect(lastRichMarkdown(calls)).toBe('\\#3460 done')
+  })
+
+  it('(b) escapes an editMessageText object-arg { markdown } on the wire', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.editMessageText(1, 42, { markdown: '#3460 done' })
+    expect(calls[calls.length - 1].method).toBe('editMessageText')
+    expect(lastRichMarkdown(calls)).toBe('\\#3460 done')
+  })
+
+  it('(c) leaves a literalText / string-arg edit UNTOUCHED (carries text, not rich_message)', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.editMessageText(1, 42, '#3460 done')
+    const c = calls[calls.length - 1]
+    expect(c.method).toBe('editMessageText')
+    expect(c.body.text).toBe('#3460 done')
+    expect(c.body.rich_message).toBeUndefined()
+  })
+
+  it('(d) leaves a genuine heading byte-identical', async () => {
+    const { bot, calls } = makeCapturingBot()
+    await bot.api.sendRichMessage(1, { markdown: '# Title\n## Sub' })
+    expect(lastRichMarkdown(calls)).toBe('# Title\n## Sub')
+  })
+
+  it('(e) is idempotent on an already-guarded (richMessage-wrapped) body', async () => {
+    const { bot, calls } = makeCapturingBot()
+    // Simulate a body that already went through richMessage()'s internal guard.
+    await bot.api.sendRichMessage(1, { markdown: '\\#3460 done' })
+    expect(lastRichMarkdown(calls)).toBe('\\#3460 done')
+  })
+
+  it('does not mutate the caller\'s shared input object', async () => {
+    const { bot } = makeCapturingBot()
+    const input = { markdown: '#3460 done' }
+    await bot.api.sendRichMessage(1, input)
+    // Caller's object is unchanged; only the cloned wire payload is escaped.
+    expect(input.markdown).toBe('#3460 done')
+  })
+})