switchroom 0.19.6 → 0.19.8

package/telegram-plugin/gateway/subagent-handback-marker.ts

@@ -1,18 +1,18 @@
 /**
- * Per-chat marker of the most recent gateway-synthesized `subagent_handback`
- * enqueue (fix/backstop-duplicate-reply).
+ * Per-chat-and-thread marker of the most recent gateway-synthesized
+ * `subagent_handback` enqueue (fix/backstop-duplicate-reply).
  *
  * A BACKGROUND sub-agent completion is a GATEWAY-SYNTHESIZED event, not model
  * output: when a background worker terminates the gateway wakes the agent with a
- * `subagent_handback` inbound. Recording WHEN one was enqueued, per chat, is the
- * ONE deterministic signal that distinguishes the two late-reply cases that both
- * resolve a flush-delivered ENDED turn via the latest-ended tier — the case the
- * owner-resolution tier alone cannot separate (a DM late reply has no
+ * `subagent_handback` inbound. Recording WHEN one was enqueued, per chat/thread,
+ * is the ONE deterministic signal that distinguishes the two late-reply cases
+ * that both resolve a flush-delivered ENDED turn via the latest-ended tier — the
+ * case the owner-resolution tier alone cannot separate (a DM late reply has no
  * live/origin/quoted attribution, so both land on latest-ended):
  *
  *   - CASE A — the flushed turn's OWN reworded reply landing late. NO
- *     `subagent_handback` was enqueued for this chat after the turn ended, so the
- *     reply is that turn's own answer → the supersede path collapses the
+ *     `subagent_handback` was enqueued for this chat/thread after the turn ended,
+ *     so the reply is that turn's own answer → the supersede path collapses the
  *     provisional flush REGARDLESS of the model's rewording (closes the #3429
  *     reworded-duplicate regression: agent:marko 2026-07-20, turns
  *     #1177/#1182/#1201 double-sent).
@@ -22,21 +22,200 @@
  *     and send fresh (two messages), never silently edit/delete the flushed
  *     answer.
  *
- * One entry per chat (overwritten on each enqueue), so bounded by chat count. No
- * clock reads beyond the caller-supplied `now`; the gateway wires the actual
- * enqueue site and the supersede-path read. Deterministic — keyed on a
- * gateway-emitted event, never on model discipline (Ken's controls-in-code rule).
+ * ## Why thread-keyed (F2, dup-audit 2026-07-21)
+ *
+ * The supersede registry this marker gates is keyed on `chatId|threadId`
+ * (`flushed-turn-supersede.ts` `makeKey`). Keying the marker on `chatId` ALONE
+ * was inconsistent: in a forum supergroup a background handback in topic A
+ * stamped the chat-wide marker, and a genuine CASE-A reworded own-reply in ANY
+ * other topic within the 60 s TTL then computed `handbackCouldOwnReply = true` →
+ * kept the content gate → shipped a second visible bubble instead of collapsing.
+ * The blast radius was every topic in the chat for 60 s per handback. Keying on
+ * `chatId + threadId` — the SAME lane the supersede registry uses — confines a
+ * handback's gate-hold to the topic it actually landed in, so an unrelated
+ * topic's CASE-A collapse is untouched. A DM (no thread) collapses to the
+ * chat-only key, so single-lane behaviour is unchanged.
+ *
+ * One entry per chat/thread (overwritten on each enqueue), so bounded by
+ * chat×topic count. No clock reads beyond the caller-supplied `now`; the gateway
+ * wires the actual enqueue site and the supersede-path read. Deterministic —
+ * keyed on a gateway-emitted event, never on model discipline (Ken's
+ * controls-in-code rule).
+ */
+/**
+ * ## The enforced invariant (F1, dup-audit 2026-07-21)
+ *
+ * The whole content-gate bypass rests on this premise: *a decoupled late reply
+ * (turn == null) carrying content that is NOT the flushed turn's own answer,
+ * resolving an ENDED flushed turn as its owner, can ONLY be a gateway-synthesized
+ * completion — and every such completion stamps this marker.* If that premise
+ * holds, then marker-ABSENCE in the window proves the late reply IS the flushed
+ * turn's own (possibly reworded) answer, so bypassing the content gate is safe
+ * (closes the marko duplicate). If a NEW synthesized-inbound source were ever
+ * able to land as a decoupled late reply with foreign content WITHOUT stamping,
+ * it would silently edit over a delivered answer (the #3429 failure).
+ *
+ * We make the premise an ENFORCED invariant rather than an architectural
+ * coincidence by routing the stamp decision through this ONE predicate at the ONE
+ * chokepoint every inbound funnels through (`pendingInboundBuffer.push` — live
+ * synthesis, boot-replay, and every future source alike). The membership of the
+ * decoupled-completion class is defined HERE and nowhere else:
+ *
+ *   - `subagent_handback` — the only source today that wakes the agent to emit a
+ *     reply with NO live gateway turn of its own (a background worker completion),
+ *     so its reply resolves a DIFFERENT, already-ended turn via the latest-ended
+ *     tier. It is the F1 vector.
+ *   - Every OTHER synthesized source (cron, resume_*, reaction, vault_*, …) lands
+ *     as its OWN live inbound turn, so its reply resolves the `live` tier for its
+ *     own turnId and structurally cannot supersede a different ended turn's flush
+ *     record (`decideSupersede` requires `record.turnId === liveTurnId`). Those
+ *     must NOT stamp — stamping them would needlessly hold the content gate open
+ *     for an unrelated own-reply in the window (a safe but avoidable visible dup).
+ *
+ * This predicate is therefore the SINGLE point of extension: any future feature
+ * that synthesizes an inbound which can land as a DECOUPLED late reply (no live
+ * turn) MUST add its `meta.source` here — and because the chokepoint consults
+ * this predicate, doing so is the whole wiring. A source that forgets to opt in
+ * cannot reach the bypass unnoticed: the negative outcome guard
+ * (`send-reply-golden.test.ts`) pins that a decoupled foreign-content reply on a
+ * non-live tier never silently edits over the flushed answer.
+ *
+ * ## Inbound meta.source classification registry (F1 durability — dup-audit
+ * MUST-FIX 3, Fable 2026-07-21)
+ *
+ * The old predicate was a bare `=== 'subagent_handback'` with NO tripwire and an
+ * UNSAFE default: adding a new decoupled-completion source tripped nothing — no
+ * stamp → content-gate bypass eligible → silent edit-over of a delivered answer.
+ * This registry makes the classification EXPLICIT, EXHAUSTIVE and FAIL-SAFE:
+ *
+ *   - Every known `meta.source` is listed with `decoupledCompletion`. Today ONLY
+ *     `subagent_handback` is true; every other synthesized source lands as its
+ *     OWN live inbound turn (live tier → cannot supersede a different ended
+ *     turn's record), so it must NOT stamp.
+ *   - An UNKNOWN / unclassified source FAILS SAFE: `stampsHandbackMarker` returns
+ *     `true`, so it STAMPS → the content gate is KEPT → the worst case is a
+ *     visible duplicate, NEVER a silent edit-over (inverted from the old
+ *     deny-default, which failed toward silent loss).
+ *   - The exhaustiveness test (`subagent-handback-marker.test.ts`) scans the
+ *     gateway for `source:` / `meta.source ===` literals and FAILS when a new one
+ *     is added without a registry entry — forcing a conscious classification.
+ *
+ * Defense-in-depth with the tier restriction (`outbound-send-path.ts`): the
+ * content-gate bypass is now limited to the `live` + `latest-ended` tiers, so
+ * model-steerable `quoted`/`origin` attributions can never bypass regardless of
+ * the marker. This registry closes the residual `latest-ended` vector for a
+ * FUTURE decoupled source, fail-safe.
  */
+export const INBOUND_SOURCE_CLASSIFICATION: Record<string, { decoupledCompletion: boolean }> = {
+  // The ONE decoupled-completion source today: a background worker termination
+  // wakes the agent with no live turn of its own → its reply resolves a
+  // different, already-ended turn via the latest-ended tier. THE F1 vector.
+  subagent_handback: { decoupledCompletion: true },
+  // Everything below lands as its OWN live inbound turn (live tier), so its reply
+  // resolves the live tier for its own turnId and structurally cannot supersede a
+  // different ended turn's record → not a decoupled-completion vector, must not stamp.
+  cron: { decoupledCompletion: false },
+  reaction: { decoupledCompletion: false },
+  subagent_progress: { decoupledCompletion: false },
+  resume_interrupted: { decoupledCompletion: false },
+  resume_deferred: { decoupledCompletion: false },
+  resume_watchdog_timeout: { decoupledCompletion: false },
+  vault_grant_approved: { decoupledCompletion: false },
+  vault_grant_denied: { decoupledCompletion: false },
+  vault_grant_timeout: { decoupledCompletion: false },
+  vault_save_completed: { decoupledCompletion: false },
+  vault_save_discarded: { decoupledCompletion: false },
+  vault_save_failed: { decoupledCompletion: false },
+  vault_save_timeout: { decoupledCompletion: false },
+  secret_provided: { decoupledCompletion: false },
+  secret_declined: { decoupledCompletion: false },
+  secret_provide_failed: { decoupledCompletion: false },
+  secret_request_timeout: { decoupledCompletion: false },
+  mental_model_propose_timeout: { decoupledCompletion: false },
+  bridge_dead_restart: { decoupledCompletion: false },
+  obligation_represent: { decoupledCompletion: false },
+  missed_approval_retry: { decoupledCompletion: false },
+  skill_proposal_apply: { decoupledCompletion: false },
+  warmup: { decoupledCompletion: false },
+  // dup-audit pass-2 (Fable) — sources the widened exhaustiveness scanner now
+  // sees. Each lands as its OWN live inbound turn (not a decoupled completion
+  // resolving a DIFFERENT ended turn), so it must NOT stamp — else its fail-safe
+  // stamp would hold the content gate chat-wide for 60 s and re-open the
+  // reworded-own-answer visible dup in that window.
+  //   - mental_model_proposal_{applied,denied,failed}: resume-synthetic inbounds
+  //     injected via `deliverResumeSyntheticOrBuffer` as their own live turn.
+  //   - webhook / linear: built in `src/web/webhook-dispatch.ts`, delivered via
+  //     the gateway's `webhookInject` (`sendToAgent`, buffer on miss) as their
+  //     own live turn.
+  mental_model_proposal_applied: { decoupledCompletion: false },
+  mental_model_proposal_denied: { decoupledCompletion: false },
+  mental_model_proposal_failed: { decoupledCompletion: false },
+  webhook: { decoupledCompletion: false },
+  linear: { decoupledCompletion: false },
+}
+
+/**
+ * Whether an inbound of this `meta.source` must stamp the decoupled-completion
+ * marker. Null/undefined (a normal user inbound — not synthesized) → false.
+ * A known source → its registry classification. An UNKNOWN source → true
+ * (fail-safe: stamp, so an unclassified future decoupled source can only cause a
+ * visible dup, never a silent edit-over).
+ */
+export function stampsHandbackMarker(source: string | null | undefined): boolean {
+  if (source == null) return false
+  const known = INBOUND_SOURCE_CLASSIFICATION[source]
+  if (known == null) return true // fail-safe: unknown synthesized source stamps
+  return known.decoupledCompletion
+}
+
+/** Sentinel thread key for the no-thread (DM / bare-chat) lane. */
+const MAIN_THREAD_KEY = '<main>'
+
 export class SubagentHandbackMarker {
-  private readonly lastAtByChat = new Map<string, number>()
+  // chatId → (threadKey → last enqueue ms). Nested so the CONTENT-GATE read can
+  // query chat-wide (`lastAtInChat`) while the record stays thread-resolved.
+  private readonly byChat = new Map<string, Map<string, number>>()
+
+  private threadKey(threadId: number | undefined): string {
+    return threadId == null ? MAIN_THREAD_KEY : String(threadId)
+  }
+
+  /** Record that a `subagent_handback` was enqueued for `chatId`/`threadId` at
+   *  `now` (ms). Thread-resolved so the record retains the originating topic. */
+  record(chatId: string, threadId: number | undefined, now: number): void {
+    let inner = this.byChat.get(chatId)
+    if (inner == null) {
+      inner = new Map<string, number>()
+      this.byChat.set(chatId, inner)
+    }
+    inner.set(this.threadKey(threadId), now)
+  }
 
-  /** Record that a `subagent_handback` was enqueued for `chatId` at `now` (ms). */
-  record(chatId: string, now: number): void {
-    this.lastAtByChat.set(chatId, now)
+  /** Wall-clock ms of the most recent handback enqueue for a SPECIFIC
+   *  `chatId`/`threadId` lane, or null. (Diagnostics / unit tests.) */
+  lastAt(chatId: string, threadId: number | undefined): number | null {
+    return this.byChat.get(chatId)?.get(this.threadKey(threadId)) ?? null
   }
 
-  /** Wall-clock ms of the most recent handback enqueue for `chatId`, or null. */
-  lastAt(chatId: string): number | null {
-    return this.lastAtByChat.get(chatId) ?? null
+  /**
+   * Wall-clock ms of the most recent handback enqueue ANYWHERE in `chatId`
+   * (across every topic lane), or null. This is what the content-gate read uses
+   * (dup-audit MUST-FIX 2, Fable 2026-07-21): the owner-resolution latest-ended
+   * tier is CHAT-WIDE (`findLatestEndedTurnForChat` ignores thread), so a
+   * background handback in topic A can resolve — and supersede — topic B's
+   * ended turn. A thread-SPECIFIC gate read (the F2 regression) let a reply
+   * dodge that handback by carrying a different `message_thread_id`, silently
+   * editing over the answer. Querying chat-wide makes the gate un-steerable by
+   * the reply's own thread arg: any in-window handback in the chat keeps the
+   * content gate. The cost is the F2 visible-dup (a handback in one topic keeps
+   * the gate for a coinciding own-reply in another for ≤TTL) — a self-healing
+   * visible duplicate, which is strictly better than a silent edit-over.
+   */
+  lastAtInChat(chatId: string): number | null {
+    const inner = this.byChat.get(chatId)
+    if (inner == null || inner.size === 0) return null
+    let max = -Infinity
+    for (const ts of inner.values()) if (ts > max) max = ts
+    return max === -Infinity ? null : max
   }
 }

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