switchroom 0.21.7 → 0.21.9

package/telegram-plugin/gateway/self-improve-proposal-wiring.ts

@@ -21,20 +21,86 @@
 
 import type { Bot, Context } from 'grammy'
 import type { RetryCallOpts } from '../retry-api-call.js'
-import type { PostSkillProposalMessage, PostEvalCaseProposalMessage } from './ipc-protocol.js'
+import type { PostSkillProposalMessage, PostEvalCaseProposalMessage, InboundMessage } from './ipc-protocol.js'
 import { renderSkillProposalCard, skillProposalKeyboard } from './skill-proposal-card.js'
 import { renderEvalCaseProposalCard, evalCaseProposalKeyboard } from './eval-case-proposal-card.js'
 import {
   enqueueProposal as enqueueSkillProposal,
   isSuppressed as isSkillProposalSuppressed,
+  REJECTION_TTL_MS,
 } from '../../src/self-improve/skill-proposals.js'
-import { enqueueEvalCaseProposal } from '../../src/self-improve/eval-case-proposals.js'
+import {
+  enqueueEvalCaseProposal,
+  readEvalCaseProposals,
+} from '../../src/self-improve/eval-case-proposals.js'
 
 /** Collaborators the gateway injects into each handler. */
 export interface ProposalWiringDeps {
   bot: Bot<Context>
   assertAllowedChat: (chatId: string) => void
   swallowingApiCall: <T>(fn: () => Promise<T>, opts?: RetryCallOpts) => Promise<T | undefined>
+  /**
+   * Wake the proposing agent with a synthetic inbound (gateway.ts's
+   * `deliverResumeSyntheticOrBuffer`). REQUIRED, not optional: the suppressed
+   * branch below is a silent exit, and a call site that forgot to wire this
+   * would reinstate exactly the wait-forever bug it exists to prevent — so the
+   * type system forces every caller to supply it.
+   */
+  deliverResumeSyntheticOrBuffer: (agent: string, inbound: InboundMessage) => boolean
+}
+
+/**
+ * Build the synthetic inbound that tells a proposing agent its eval case was
+ * SUPPRESSED as a duplicate of one the operator already dismissed.
+ *
+ * WHY THIS EXISTS (cross-PR, #4662 + #4664). #4662 makes the agent's contract
+ * "fire `add-eval-case`, end your turn, wait for the outcome inbound". #4664
+ * adds a branch that posts NO card. The propose CLI is fire-and-forget — it
+ * prints `ok:true` for the IPC SEND, never for a card being posted
+ * (src/cli/self-improve-eval-case.ts) — so without this the agent would end its
+ * turn and wait for a tap that can never come: the exact silent block #4662
+ * exists to eliminate, re-entering through a new door.
+ *
+ * The tone is deliberate. Suppression is the system working as designed, not a
+ * failure, so the text says so plainly — an agent told only "no card" would
+ * reasonably retry, which is the nagging loop #4664 is removing.
+ *
+ * Co-located here rather than in #4662's `eval-case-proposal-inbound-builders.ts`
+ * because that module does not exist on this branch; consolidating the four
+ * builders once both PRs land is a tracked follow-up.
+ */
+export function buildEvalCaseSuppressedInbound(opts: {
+  agent: string
+  chatId: string
+  threadId?: number
+  skillSlug: string
+  fingerprint: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.chatId,
+    ...(opts.threadId != null ? { threadId: opts.threadId } : {}),
+    messageId: ts, // synthetic — no Telegram message id exists
+    user: 'self-improve',
+    userId: 0,
+    ts,
+    text:
+      `ℹ️ Your proposed eval case for \`${opts.skillSlug}\` was NOT posted as a ` +
+      `card: the operator already dismissed this exact case, and the dismissal ` +
+      `is still in effect. This is EXPECTED and is not an error or a failure on ` +
+      `your part — nothing was written and no card is pending, so do NOT wait ` +
+      `for an approval tap. Do NOT re-propose this case. Carry on with the ` +
+      `original task without it.`,
+    meta: {
+      source: 'eval_case_suppressed',
+      agent: opts.agent,
+      ...(opts.threadId != null ? { message_thread_id: String(opts.threadId) } : {}),
+      skill_slug: opts.skillSlug,
+      fingerprint: opts.fingerprint,
+    },
+  }
 }
 
 /**
@@ -113,6 +179,61 @@ export function handlePostSkillProposal(
   )
 }
 
+/**
+ * True iff the operator already DISMISSED this exact eval case within the
+ * rejection TTL — the eval-case twin of `isSuppressed` in skill-proposals.ts.
+ *
+ * Matching is deliberately TIGHTER than the skill path's. A skill proposal is
+ * free prose, so that check has to fuzzy-match (jaccard over content words,
+ * with the slug only relaxing the threshold). An eval case carries a
+ * precomputed `fingerprint` — `caseFingerprint(prompt)`, a hash of the
+ * normalized prompt — and the CLI's own dedup against a skill's applied
+ * evals.json compares those fingerprints EXACTLY
+ * (src/cli/self-improve-eval-case.ts). So this requires exact fingerprint
+ * equality AND same-slug, matching the CLI's per-skill dedup scope: no fuzzy
+ * bar to tune, and a different PROMPT can never be swallowed.
+ *
+ * KNOWN CONSEQUENCE — identity is the PROMPT, not the whole case.
+ * `caseFingerprint` hashes the normalized prompt ONLY; an `EvalCase` also
+ * carries `expected_output` and `expectations` (src/self-improve/eval-cases.ts),
+ * and neither is in the hash. So re-proposing the SAME prompt with a CORRECTED
+ * expected_output/expectations fingerprints identically to the dismissed one and
+ * stays suppressed for the full TTL. This is deliberate, not an oversight: it is
+ * the same identity the CLI's own evals.json dedup uses, so a looser rule here
+ * would disagree with the applier and re-admit cases the CLI would then reject.
+ * To land a revised assertion for an already-dismissed prompt, reword the prompt
+ * (a genuinely different input) or wait out REJECTION_TTL_MS.
+ *
+ * The TTL semantics ARE mirrored (a dismissal shouldn't suppress forever), on
+ * the same REJECTION_TTL_MS window. The eval-case store records no
+ * `rejected_at`, so age is measured from `created_at`, which is always <= the
+ * rejection time — the window therefore expires no LATER than a true
+ * rejected_at basis would, erring towards re-surfacing rather than
+ * over-suppressing. A record with an unparseable timestamp is treated as
+ * expired, same as the skill path.
+ */
+export function isEvalCaseProposalSuppressed(
+  stateDir: string,
+  candidate: { skillSlug: string; fingerprint: string },
+  opts: { now?: () => number; ttlMs?: number } = {},
+): boolean {
+  // A missing/empty fingerprint carries no identity — never suppress on it.
+  if (typeof candidate.fingerprint !== 'string' || candidate.fingerprint.length === 0) {
+    return false
+  }
+  const now = (opts.now ?? Date.now)()
+  const ttl = opts.ttlMs ?? REJECTION_TTL_MS
+  for (const p of readEvalCaseProposals(stateDir)) {
+    if (p.status !== 'rejected') continue
+    if (p.skill_slug !== candidate.skillSlug) continue
+    if (p.fingerprint !== candidate.fingerprint) continue
+    const age = now - new Date(p.created_at).getTime()
+    if (!Number.isFinite(age) || age > ttl) continue // expired
+    return true
+  }
+  return false
+}
+
 /**
  * RFC amendment §"corrections as eval cases" — persist an eval-case proposal
  * and post its Approve/Dismiss card. On Approve the callback runs the
@@ -124,7 +245,7 @@ export function handlePostEvalCaseProposal(
   msg: PostEvalCaseProposalMessage,
   deps: ProposalWiringDeps,
 ): void {
-  const { bot, assertAllowedChat, swallowingApiCall } = deps
+  const { bot, assertAllowedChat, swallowingApiCall, deliverResumeSyntheticOrBuffer } = deps
   const self = process.env.SWITCHROOM_AGENT_NAME
   if (self && msg.agentName !== self) {
     process.stderr.write(
@@ -145,6 +266,34 @@ export function handlePostEvalCaseProposal(
     process.stderr.write(`telegram gateway: post_eval_case_proposal: TELEGRAM_STATE_DIR unset, skipping\n`)
     return
   }
+  // Dedup against still-live dismissals — never re-surface an eval case the
+  // operator already tapped Dismiss on (the skill path's guard, which the
+  // eval-case path was missing: a dismissed case re-posted the same card on
+  // every subsequent correction, since the CLI only dedups against evals.json
+  // entries that were already APPLIED).
+  if (isEvalCaseProposalSuppressed(stateDir, {
+    skillSlug: msg.skillSlug,
+    fingerprint: msg.fingerprint,
+  })) {
+    // Tell the agent, or this becomes a silent exit it waits on forever (see
+    // buildEvalCaseSuppressedInbound). No card is posted and nothing is written
+    // — the operator's dismissal already decided this case.
+    const delivered = deliverResumeSyntheticOrBuffer(
+      msg.agentName,
+      buildEvalCaseSuppressedInbound({
+        agent: msg.agentName,
+        chatId: msg.chatId,
+        ...(msg.threadId != null ? { threadId: msg.threadId } : {}),
+        skillSlug: msg.skillSlug,
+        fingerprint: msg.fingerprint,
+      }),
+    )
+    process.stderr.write(
+      `telegram gateway: post_eval_case_proposal suppressed (dismissed before) ` +
+      `slug=${msg.skillSlug} fp=${msg.fingerprint} delivered=${delivered}\n`,
+    )
+    return
+  }
   const proposal = enqueueEvalCaseProposal(stateDir, {
     skill_slug: msg.skillSlug,
     skill_dir: msg.skillDir,

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

@@ -176,6 +176,25 @@ export const INBOUND_SOURCE_CLASSIFICATION: Record<string, { decoupledCompletion
   mental_model_proposal_failed: { decoupledCompletion: false },
   webhook: { decoupledCompletion: false },
   linear: { decoupledCompletion: false },
+  // Eval-case proposal outcomes (#4662) — the operator's Approve/Dismiss tap on
+  // an eval-case card wakes the PROPOSING agent with one of these, built in
+  // `eval-case-proposal-inbound-builders.ts` and injected via
+  // `deliverResumeSyntheticOrBuffer`. Exactly the `skill_proposal_apply` shape
+  // above: each 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 — it must NOT stamp. (Left unclassified, the fail-safe default
+  // stamps, holding the content gate chat-wide for 60 s after every eval-case
+  // decision and re-opening the reworded-own-answer visible dup in that window.)
+  eval_case_applied: { decoupledCompletion: false },
+  eval_case_rejected: { decoupledCompletion: false },
+  eval_case_apply_failed: { decoupledCompletion: false },
+  // Eval-case proposal SUPPRESSED (#4664): the gateway declined to post a card
+  // because the operator already dismissed this exact case, and tells the
+  // proposing agent so instead of exiting silently
+  // (buildEvalCaseSuppressedInbound, self-improve-proposal-wiring.ts). Delivered
+  // via `deliverResumeSyntheticOrBuffer` as its OWN live inbound turn, same as
+  // skill_proposal_apply above — it must NOT stamp.
+  eval_case_suppressed: { decoupledCompletion: false },
   // Buzz co-channel (Phase 1): a Nostr kind:9 group message the buzz sidecar
   // injects onto the gateway IPC queue as its OWN live inbound turn (anonymous
   // inject, `meta.source="buzz"`) — never a decoupled completion resolving a

package/telegram-plugin/package.json

@@ -31,7 +31,7 @@
     "@secretlint/core": "^12.2.0",
     "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
     "@xterm/headless": "^6.0.0",
-    "grammy": "^1.44",
+    "grammy": "^1.45",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-gfm": "^3.0.0",
     "micromark-extension-gfm": "^3.0.0",

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

@@ -73,6 +73,13 @@ export function splitCodeSegments(text: string): Segment[] {
 //   • 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.
+//   • inline-math `$…$` spans — Telegram's rich GFM parser typesets a `$…$`
+//     pair as a real mathematical_expression node (wire-verified 2026-08-13).
+//     A COMPACT span (whitespace-free inner run that is not a bare currency
+//     amount, e.g. `$x^2+y^2$`) is intentional math and must reach the wire
+//     byte-identical: no guard may escape its `$`, `^`, `_`, `*`, or `+`.
+//     Currency-shaped inners (`$5M-$`) are NOT protected, so the dollar-math
+//     guard still breaks accidental `$5M … $10M` currency pairs (#3252).
 // 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.
 //
@@ -93,6 +100,19 @@ function isTableCandidateLine(line: string): boolean {
   return /^\s*\|/.test(line);
 }
 
+/** A compact `$…$` inline-math pair: opening `$`, a whitespace-free inner run
+ *  with no nested `$`, closing `$`. Anchored — tested at the scanner's current
+ *  position only. */
+const COMPACT_MATH_PAIR = /^\$([^\s$]+)\$/;
+
+/** A currency-shaped inner run: digits plus amount punctuation and magnitude
+ *  suffix letters only (`5M-`, `0.5`, `10,000`, `5+`). Such a run between two
+ *  `$` is a pair of ADJACENT currency amounts (`$5M-$10M`), not math — it must
+ *  stay guardable so the dollar-math guard can break the accidental pair. A
+ *  run containing any other character (`x^2+y^2`, `\alpha`, `a_b`) is treated
+ *  as intentional math and protected. */
+const CURRENCY_SHAPED_INNER = /^[0-9.,+\-kKmMbB]+$/;
+
 /** 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,
@@ -185,6 +205,19 @@ function splitProseProtected(text: string): Segment[] {
         continue;
       }
     }
+    // 4. Compact inline-math pair `$…$` — a supported Telegram construct
+    //    (mathematical_expression, wire-verified 2026-08-13) that must reach
+    //    the wire verbatim. Currency-shaped inners are NOT math (they are two
+    //    adjacent amounts like `$5M-$10M`) and stay guardable.
+    if (ch === "$") {
+      const m = COMPACT_MATH_PAIR.exec(text.slice(i));
+      if (m && !CURRENCY_SHAPED_INNER.test(m[1])) {
+        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) });
@@ -193,10 +226,11 @@ function splitProseProtected(text: string): Segment[] {
 
 /** 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. */
+ *  fenced code blocks, markdown link destinations, bare autolinks, GFM table
+ *  rows, and compact `$…$` inline-math spans. This is the link/table/math-aware
+ *  superset of `splitCodeSegments` that all the #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)) {

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

@@ -29,6 +29,20 @@
 // a `$…$` pair if only the leading-`$digit` token is escaped — so we escape the
 // lot once the currency signal + 2-dollar threshold are met.
 //
+// ── INTENTIONAL math is exempt (wire-verified 2026-08-13) ─────────────────
+// Telegram's rich path renders a `$…$` pair as a native mathematical_expression
+// node, and intentional math (`$x^2+y^2$`) must reach the wire byte-identical —
+// an escaped `\$x^2+y^2\$` destroys a SUPPORTED construct. The discrimination
+// lives in `splitProtectedSegments` (code-segments.ts): a COMPACT math span
+// (whitespace-free inner, not currency-shaped) is a protected segment, so this
+// guard neither counts its `$`s toward the 2+ threshold nor escapes them.
+// Currency amounts always sit next to whitespace/prose (`$5M and $10M`) or have
+// a digits-and-punctuation-only inner (`$5M-$10M`), so #3252-class accidental
+// pairs remain fully guarded. Known residual: a SPACED math span (`$a + b$`)
+// is indistinguishable from currency prose and is not exempted — it is escaped
+// when the message also carries a currency signal, rendering as literal text
+// (legible, not broken).
+//
 // 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
@@ -100,7 +114,8 @@ const UNESCAPED_DOLLAR = /(?<!\\)\$/g;
  * 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.
+ * blocks AND compact intentional-math `$…$` spans (protected segments, see
+ * code-segments.ts) are never touched. Idempotent (F5) and deterministic.
  */
 export function guardDollarMath(text: string): string {
   if (!text.includes("$")) return text;

package/telegram-plugin/render/ir.ts

@@ -30,11 +30,21 @@
 //     highlight -> `==…==`  (Bot API 10.1 marked entity)
 //     code      -> `` `…` ``
 //     link      -> `[…](…)`
+//     tg-entity -> `![…](tg://…)`  (Bot API date_time / custom-emoji entity)
+//     raw       -> source bytes verbatim (never escaped) — footnote markers
+//                  `[^1]` and definition lines `[^1]: …`, which Telegram's
+//                  rich parser renders natively and escapeMarkdown would break
 //
 //   Block
 //     paragraph      -> children joined; blocks separated by "\n\n"
 //     heading        -> `#`…`######` line
-//     blockquote     -> `> …` (expandable === true -> `**> …` expandable blockquote)
+//     blockquote     -> `> …` on every line. `expandable === true` records that
+//                       the SOURCE carried the legacy `**> ` marker, but it is
+//                       NOT a distinct wire style: `**>` is MarkdownV2-only
+//                       syntax that the rich markdown path renders as literal
+//                       text (wire-verified 2026-08-13), so the renderer
+//                       degrades it to a plain quote. Authors wanting a real
+//                       collapsible use `<details><summary>…</summary>…</details>`.
 //     code-block     -> ```` ```lang … ``` ````
 //     list           -> line-per-item with `-`/`1.` markers
 //     thematic-break -> `---` thematic break
@@ -109,6 +119,40 @@ export interface LinkNode extends Pos {
   children: Inline[];
 }
 
+/** A Telegram rich-markdown INLINE entity written in mdast IMAGE position.
+ *  The "Rich Markdown style" grammar (https://core.telegram.org/bots/api,
+ *  quoted in `reference/telegram-formatting-guide.md`) lists exactly two:
+ *
+ *    ![](tg://emoji?id=5368324170671202286)                  custom emoji
+ *    ![22:45 tomorrow](tg://time?unix=1647531900&format=wDT) date_time
+ *
+ *  (the `date_time` MessageEntity is Bot API 9.5, March 1 2026; the rich-message
+ *  `RichTextDateTime` class is 10.1, June 11 2026 — both in the Bot API
+ *  changelog.) `parse.ts` folds ONLY those two `tg:` hrefs into this node;
+ *  every other image url keeps the historical demote-to-`plain` fallback,
+ *  because an http(s) `![](…)` is a Telegram MEDIA block — "Media can be
+ *  specified only as a separate block" (same doc) — not an inline entity, and
+ *  switchroom does not emit media blocks.
+ *
+ *  `label` is the DECODED alternative text (mdast `image.alt`, empty for the
+ *  emoji form); `href` is the `tg:` URL. Both are re-escaped on render, same
+ *  as `LinkNode`. */
+export interface TgEntityNode extends Pos {
+  type: "tg-entity";
+  label: string;
+  href: string;
+}
+
+/** Verbatim wire passthrough: the node's SOURCE bytes are already the exact
+ *  syntax Telegram's rich parser expects, so the renderer must emit them
+ *  unescaped (escapeMarkdown would corrupt them). Used for GFM footnote
+ *  reference markers (`[^1]`) and footnote definition lines (`[^1]: …`) —
+ *  both natively supported on the rich path (wire-verified 2026-08-13). */
+export interface RawNode extends Pos {
+  type: "raw";
+  text: string;
+}
+
 export type Inline =
   | PlainNode
   | BoldNode
@@ -118,7 +162,9 @@ export type Inline =
   | SpoilerNode
   | HighlightNode
   | CodeNode
-  | LinkNode;
+  | LinkNode
+  | TgEntityNode
+  | RawNode;
 
 // ---------------------------------------------------------------------------
 // Block nodes
@@ -139,7 +185,11 @@ export interface HeadingNode extends Pos {
 export interface BlockquoteNode extends Pos {
   type: "blockquote";
   children: Block[];
-  /** Telegram <blockquote expandable>. Always false in Increment 1 — see parse.ts. */
+  /** True when the source carried the LEGACY switchroom `**> ` expandable
+   *  marker (see parse.ts markExpandableQuotes). Records authoring intent
+   *  only: `**>` is MarkdownV2 syntax with no rich-markdown equivalent
+   *  (wire-verified 2026-08-13), so the renderer emits a plain `> ` quote
+   *  either way. */
   expandable: boolean;
 }
 

package/telegram-plugin/render/parse.ts

@@ -37,12 +37,18 @@
 //   own reading of the delimiters.
 //
 // Blockquote expandable handling:
-//   The IR carries `expandable: boolean` for Telegram's expandable blockquote
-//   (Bot API 10.1). GFM has no expandable marker; the switchroom render path
-//   emits `**> ` on the FIRST line of an expandable quote (`render.ts` /
-//   `reference/telegram-formatting-guide.md`). micromark does NOT understand
-//   `**> ` as a blockquote — the leading `**` makes the line a paragraph with
-//   an unclosed strong-emphasis run — so this module pre-transforms each
+//   The IR carries `expandable: boolean` for the LEGACY switchroom `**> `
+//   expandable-quote encoding. `**>` was believed to be the Bot API 10.1
+//   expandable-blockquote marker; wire probes (2026-08-13) proved it is
+//   MarkdownV2-only syntax that the rich markdown path renders as LITERAL
+//   `**>` text, so `render.ts` no longer emits it — an expandable node renders
+//   as a plain `> ` quote. Recognition here is kept as INPUT REPAIR: agent
+//   output (and Hindsight memories) trained on the old floor card still
+//   contains `**> ` quotes, and without this rewrite such a line would reach
+//   the wire as a broken literal-`**>` paragraph. micromark does NOT
+//   understand `**> ` as a blockquote — the leading `**` makes the line a
+//   paragraph with an unclosed strong-emphasis run — so this module
+//   pre-transforms each
 //   `**>` marker into a plain `  >` marker of IDENTICAL length (`**` → two
 //   spaces) before handing the text to mdast. Length preservation keeps every
 //   UTF-16 source offset (and therefore the never-lose-text round-trip
@@ -90,15 +96,35 @@ function slice(source: string, node: MdastNode): string {
   return source.slice(start, end);
 }
 
-/** The Bot API 10.1 expandable-blockquote marker: `**>` at the very start of
- *  a line (column 0). This is exactly what the render path emits
- *  (`render.ts` writes `**> ` on the first line of an expandable quote; see
- *  `reference/telegram-formatting-guide.md`). Matching only at column 0 keeps
+/** The LEGACY switchroom expandable-blockquote marker: `**>` at the very
+ *  start of a line (column 0). The render path no longer emits it (it is
+ *  MarkdownV2-only syntax, not rich markdown — see `render.ts`
+ *  renderBlockquote), but it is still RECOGNISED on input so a legacy `**> `
+ *  line is repaired into a real blockquote instead of shipping as literal
+ *  `**>` text. Matching only at column 0 keeps
  *  the length-preserving rewrite (`**` → two spaces) inside CommonMark's
  *  3-space blockquote-indent budget — allowing leading indent here would push
  *  the rewritten `  >` past 3 spaces and turn it into an indented code block. */
 const EXPANDABLE_MARKER_RE = /^\*\*>/;
 
+/** The `tg:` hrefs Telegram's "Rich Markdown style" grammar accepts in IMAGE
+ *  position — `![label](tg://…)`. Exactly two are documented
+ *  (https://core.telegram.org/bots/api): `tg://emoji?id=…` (custom emoji) and
+ *  `tg://time?unix=…[&format=…]` (the `date_time` entity). Deliberately an
+ *  ALLOWLIST rather than a bare `tg:` scheme test: an undocumented `tg://…` in
+ *  image position is not known-good syntax, and demoting it to literal text
+ *  (the historical behaviour) is safer than shipping a construct Telegram may
+ *  parse-reject. */
+const TG_INLINE_ENTITY_HREFS = ["tg://emoji", "tg://time"] as const;
+
+/** True when an mdast `image` url is one of the documented inline `tg:`
+ *  entities. Scheme/host comparison is case-insensitive (URLs are), but the
+ *  ORIGINAL href is what gets re-emitted — we never rewrite the author's bytes. */
+function isTgInlineEntityHref(href: string): boolean {
+  const h = href.toLowerCase();
+  return TG_INLINE_ENTITY_HREFS.some((base) => h === base || h.startsWith(`${base}?`));
+}
+
 /** Pre-transform expandable-blockquote markers so mdast can parse them as
  *  ordinary blockquotes, WITHOUT shifting any source offset. Each line that
  *  opens with `**>` has its two `*` characters replaced by two spaces
@@ -170,8 +196,30 @@ function foldInline(node: PhrasingContent, source: string): Inline {
         children: foldInlineChildren(node, source),
         ...pos(node),
       };
-    // Not in the palette (break, image, html, footnoteReference, …): keep the
-    // raw source text so no content is lost.
+    case "image": {
+      // GFM's image syntax doubles as Telegram's INLINE-entity syntax:
+      // `![22:45 tomorrow](tg://time?unix=…&format=…)` (date_time) and
+      // `![](tg://emoji?id=…)` (custom emoji). Fold those two into a
+      // `tg-entity` node so the renderer re-emits the construct verbatim
+      // instead of escaping the brackets to literal text. Every OTHER image
+      // url — notably the http(s) MEDIA forms, which Telegram accepts only as
+      // a SEPARATE block — falls through to the demote-to-`plain` default
+      // below, unchanged.
+      if (isTgInlineEntityHref(node.url)) {
+        return { type: "tg-entity", label: node.alt ?? "", href: node.url, ...pos(node) };
+      }
+      return { type: "plain", text: slice(source, node), ...pos(node) };
+    }
+    // GFM footnote reference marker (`[^1]`): natively supported by Telegram's
+    // rich markdown path (wire-verified 2026-08-13 — renders as the full
+    // superscript + anchor + reference_link machinery). The source bytes ARE
+    // the wire syntax, so fold to a `raw` node the renderer emits verbatim;
+    // a `plain` node would be escapeMarkdown'd (`\[^1\]`) and break the
+    // construct on the wire.
+    case "footnoteReference":
+      return { type: "raw", text: slice(source, node), ...pos(node) };
+    // Not in the palette (break, non-`tg:` image, html, …): keep the raw
+    // source text so no content is lost.
     default:
       return { type: "plain", text: slice(source, node), ...pos(node) };
   }
@@ -332,8 +380,19 @@ function foldBlock(
         ...pos(node),
       };
     }
-    // Not in the palette (html, definition, footnoteDefinition, …): degrade to
-    // a paragraph carrying the raw source slice so no content is dropped.
+    // GFM footnote DEFINITION (`[^1]: body`): natively supported on the wire
+    // (2026-08-13 probe — pairs with the reference marker into footer/anchor
+    // nodes). Emit the raw source slice VERBATIM via a `raw` inline: a `plain`
+    // fold would escapeMarkdown the `[`/`]` (`\[^1\]: body`) and orphan the
+    // reference.
+    case "footnoteDefinition":
+      return {
+        type: "paragraph",
+        children: [{ type: "raw", text: slice(source, node), ...pos(node) }],
+        ...pos(node),
+      };
+    // Not in the palette (html, definition, …): degrade to a paragraph
+    // carrying the raw source slice so no content is dropped.
     default:
       return {
         type: "paragraph",

package/telegram-plugin/render/render.ts

@@ -16,10 +16,11 @@
 // "HTML" }`. There is no HTML anywhere on the current outbound path (see
 // `reference/telegram-formatting-guide.md`). This renderer therefore targets
 // the ACTUAL contract: GFM markdown with the Bot API 10.1 extensions
-// documented in the formatting guide (expandable blockquote via `**> `,
-// spoiler via `||…||`, GFM pipe tables, etc). This module is NOT wired into
-// the live send path yet — that is a later increment, per the RFC's phased
-// rollout (rich rendering stays gated off by default until then).
+// documented in the formatting guide (spoiler via `||…||`, GFM pipe tables,
+// `<details>` collapsibles passed through as HTML, etc). NOTE: `**> ` is NOT
+// part of that contract — it is MarkdownV2-only syntax the rich path renders
+// as literal text (wire-verified 2026-08-13); this renderer no longer emits
+// it anywhere (see renderBlockquote).
 //
 // Round-trip note: `parse.ts` folds inline text (`PlainNode.text`,
 // `CodeNode.text`, `code-block` `text`, link `href`) into DECODED strings —
@@ -59,6 +60,14 @@ interface InlineCtx {
   inTableCell?: boolean;
 }
 
+/** Collapse any whitespace run containing a newline down to a single space.
+ *  Used for a `tg-entity` label: `![` … `]` must stay on ONE line or the
+ *  construct is not an entity any more. mdast decodes a soft line break inside
+ *  the alt text to a literal `\n`, which is exactly the case this flattens. */
+function collapseLabelBreaks(label: string): string {
+  return label.replace(/[ \t]*\r?\n[ \t\r\n]*/g, " ");
+}
+
 function renderInline(node: Inline, ctx: InlineCtx = {}): string {
   switch (node.type) {
     case "plain":
@@ -91,6 +100,25 @@ function renderInline(node: Inline, ctx: InlineCtx = {}): string {
       // Escape the href so a literal `)` in the URL can't terminate the
       // destination early and break the link (F3).
       return `[${renderInlineChildren(node.children, ctx)}](${escapeLinkHref(node.href)})`;
+    case "tg-entity":
+      // `![label](tg://time?unix=…&format=…)` / `![](tg://emoji?id=…)`.
+      // The label is PROSE (the alternative text Telegram shows when it can't
+      // render the entity), so it is escaped exactly like a `plain` node —
+      // without that, a label containing `]` or a formatting delimiter
+      // (`![see [22:45]](tg://time?…)`) closes the label early and smuggles
+      // raw bracket syntax past the renderer. A newline inside the label would
+      // split the construct across lines, so runs of whitespace spanning one
+      // are collapsed to a single space first. The href gets the same
+      // `escapeLinkHref` treatment a link's does (a no-op for the paren-free
+      // `tg:` URLs in practice, load-bearing if one ever carries a `)`).
+      return `![${escapeMarkdown(collapseLabelBreaks(node.label))}](${escapeLinkHref(node.href)})`;
+    case "raw":
+      // Verbatim wire passthrough — the source bytes ARE the wire syntax
+      // (footnote reference markers `[^1]` / definition lines `[^1]: …`,
+      // which Telegram's rich parser renders natively; escapeMarkdown would
+      // escape their `[`/`]` and break the construct — the exact bug this
+      // node type exists to prevent).
+      return node.text;
     default: {
       // Exhaustiveness guard — the IR union is closed; a new variant must be
       // handled above rather than silently dropped.
@@ -118,17 +146,20 @@ function prefixLines(text: string, prefix: string): string {
 
 function renderBlockquote(node: BlockquoteNode): string {
   const inner = renderBlocks(node.children);
-  // Bot API 10.1 expandable blockquote: `**> ` on the first quoted line.
-  // Plain blockquote: `> ` on every line.
-  if (node.expandable) {
-    const lines = inner.split("\n");
-    return lines
-      .map((line, i) => {
-        const marker = i === 0 ? "**> " : "> ";
-        return line.length > 0 ? `${marker}${line}` : marker.trimEnd();
-      })
-      .join("\n");
-  }
+  // Always a plain `> ` blockquote — including for `expandable: true` nodes.
+  //
+  // This renderer USED to emit `**> ` on the first line of an expandable
+  // quote, believing it to be the Bot API 10.1 expandable-blockquote marker.
+  // That belief was falsified by raw sendRichMessage wire probes (2026-08-13):
+  // `**>` is MarkdownV2 syntax; the rich markdown path renders it as a LITERAL
+  // `**> …` paragraph followed by a detached plain quote. The `expandable`
+  // flag is retained on the IR (parse.ts still repairs legacy `**>` input into
+  // a real blockquote instead of letting the literal `**>` reach the wire),
+  // but it is NOT a distinct wire style — the faithful degradation is a plain
+  // quote, which shows the full content. An author who wants a genuine
+  // collapsible writes `<details><summary>…</summary>…</details>`, which the
+  // rich path renders natively (typed `details` node, wire-verified) and which
+  // passes through this pipeline verbatim.
   return prefixLines(inner, "> ");
 }
 
@@ -299,6 +330,13 @@ export const SUPPORTED_INLINE = [
   "highlight",
   "code",
   "link",
+  // `![…](tg://time?…)` / `![…](tg://emoji?id=…)` — the two inline `tg:`
+  // entities in Telegram's Rich Markdown grammar. Emitted verbatim (label and
+  // href re-escaped); any OTHER image url stays a `plain` node.
+  "tg-entity",
+  // Verbatim passthrough for constructs whose SOURCE bytes are the wire syntax
+  // (footnote markers/definitions). Never escaped, never rewritten.
+  "raw",
 ] as const;
 
 export const SUPPORTED_BLOCK = [