switchroom 0.16.23 → 0.16.27

package/telegram-plugin/permission-title.ts

@@ -18,6 +18,7 @@
  */
 
 import { basename } from "node:path";
+import { escapeMarkdown } from "./card-format.js";
 import { prettyMcpServer, type ScopeOption } from "./permission-rule.js";
 import { redact } from "./secret-detect/redact.js";
 
@@ -62,6 +63,9 @@ const MCP_TOOL_DESCRIPTIONS: Record<string, string> = {
   "mcp__hostd__agent_exec": "Run a read-only inspection inside another agent",
   "mcp__hostd__update_check": "Check what a fleet-wide update would do",
   "mcp__hostd__update_apply": "Apply a fleet-wide update (pull + recreate)",
+  "mcp__hostd__rollout": "Roll the fleet to a pinned version",
+  "mcp__hostd__config_propose_edit": "Propose an edit to switchroom.yaml",
+  "mcp__hostd__get_status": "Read the last fleet-update status",
   // hindsight — memory
   "mcp__hindsight__recall": "Recall relevant memories",
   "mcp__hindsight__retain": "Retain a memory",
@@ -96,10 +100,10 @@ const HOSTD_AGENT_TARGET_VERBS = new Set([
 /**
  * Build the multi-line card body for an approval prompt.
  *
- *   🔐 <b>Gymbro</b> wants to edit: supplement-log.md
- *   why: <i>logging today's lifts</i>
+ *   🔐 **Gymbro** wants to edit: supplement-log.md
+ *   why: _logging today's lifts_
  *
- * Output is HTML-escaped for `parse_mode: 'HTML'`. The agent name is
+ * Output is GFM markdown for the rich-message path (#2669). The agent name is
  * capitalized for the sentence; dropped (with "wants to") when null —
  * the bridge client can be anonymous during early-boot edge cases.
  *
@@ -127,10 +131,10 @@ export function formatPermissionCardBody(opts: {
 
   if (opts.agentName && opts.agentName.length > 0) {
     lines.push(
-      `🔐 <b>${escapeTgHtml(capFirst(opts.agentName))}</b> wants to ${escapeTgHtml(action)}`,
+      `🔐 **${escapeTgHtml(capFirst(opts.agentName))}** wants to ${escapeActionMarkdown(action)}`,
     );
   } else {
-    lines.push(`🔐 ${escapeTgHtml(capFirst(action))}`);
+    lines.push(`🔐 ${escapeActionMarkdown(capFirst(action))}`);
   }
 
   // why: the caller-supplied rationale (`reason`/`why` arg), never the
@@ -143,8 +147,8 @@ export function formatPermissionCardBody(opts: {
       : rawWhy;
   lines.push(
     truncatedWhy.length > 0
-      ? `why: <i>${escapeTgHtml(truncatedWhy)}</i>`
-      : `why: <i>not provided</i>`,
+      ? `why: _${escapeTgHtml(truncatedWhy)}_`
+      : `why: _not provided_`,
   );
 
   // Third line (REST-wrapper MCP writes only): a redaction-safe summary of
@@ -152,7 +156,7 @@ export function formatPermissionCardBody(opts: {
   // endpoint — e.g. "↳ to: lisa@…, subject: Priority access…".
   const argSummary = mcpArgSummary(opts.toolName, opts.inputPreview);
   if (argSummary) {
-    lines.push(`↳ <i>${escapeTgHtml(argSummary)}</i>`);
+    lines.push(`↳ _${escapeTgHtml(argSummary)}_`);
   }
 
   return lines.join("\n");
@@ -424,10 +428,10 @@ export function describeGrant(
  * the operator scrolls past — so this is the legible signal that the tap
  * landed and names the work being (re)started.
  *
- * Mirrors `formatPermissionCardBody`'s style ("🔐 <b>Gymbro</b> wants to
- * edit: log.md" → "▶️ <b>Gymbro</b> — got it, continuing: edit: log.md").
+ * Mirrors `formatPermissionCardBody`'s style ("🔐 **Gymbro** wants to
+ * edit: log.md" → "▶️ **Gymbro** — got it, continuing: edit: log.md").
  * `action` is a phrase from {@link naturalAction} (already operator-facing,
- * no tool ids). Output is HTML-escaped for `parse_mode: 'HTML'`.
+ * no tool ids). Output is GFM markdown for the rich-message path (#2669).
  *
  * `timeoutMinutes` marks the TTL auto-deny variant (no operator tapped —
  * the request aged out) so the wording reflects "no answer" rather than a
@@ -441,25 +445,25 @@ export function formatPermissionResumeMessage(opts: {
 }): string {
   const who =
     opts.agentName && opts.agentName.length > 0
-      ? `<b>${escapeTgHtml(capFirst(opts.agentName))}</b>`
-      : `<b>Agent</b>`;
+      ? `**${escapeTgHtml(capFirst(opts.agentName))}**`
+      : `**Agent**`;
   const act = (opts.action ?? "").trim();
   const hasAction = act.length > 0;
 
   if (opts.behavior === "allow") {
     return hasAction
-      ? `▶️ ${who} — got it, continuing: <i>${escapeTgHtml(act)}</i>`
+      ? `▶️ ${who} — got it, continuing: _${escapeActionMarkdown(act)}_`
       : `▶️ ${who} — got it, back to work.`;
   }
 
   // deny
   if (opts.timeoutMinutes != null) {
     return hasAction
-      ? `🚫 ${who} — no answer in ${opts.timeoutMinutes}m, continuing without it (<i>${escapeTgHtml(act)}</i>).`
+      ? `🚫 ${who} — no answer in ${opts.timeoutMinutes}m, continuing without it (_${escapeActionMarkdown(act)}_).`
       : `🚫 ${who} — no answer in ${opts.timeoutMinutes}m, continuing without it.`;
   }
   return hasAction
-    ? `🚫 ${who} — noted, I won't ${escapeTgHtml(lowerFirst(act))}. Continuing without it.`
+    ? `🚫 ${who} — noted, I won't ${escapeActionMarkdown(lowerFirst(act))}. Continuing without it.`
     : `🚫 ${who} — noted, continuing without it.`;
 }
 
@@ -520,12 +524,27 @@ function capFirst(text: string): string {
   return text.length > 0 ? text.charAt(0).toUpperCase() + text.slice(1) : text;
 }
 
-/** Minimal HTML escape for Telegram `parse_mode=HTML`. */
+/** Markdown escape for the rich-message path (#2669). */
 function escapeTgHtml(text: string): string {
+  return escapeMarkdown(text);
+}
+
+/**
+ * Escape a phrase that may itself contain DELIBERATE `` `code spans` ``
+ * (e.g. the hostd fleet-verb phrases name the target agent in a code span:
+ * "restart agent `carrie` in the fleet"). The structural backticks must NOT
+ * be escaped — that would render literal `` \`carrie\` `` to the operator
+ * (#2669 regression). Everything OUTSIDE a backtick span is still escaped so
+ * a hostile Bash command / filename can't inject emphasis. Content INSIDE a
+ * span is left verbatim — code spans render literally, so there is no
+ * injection risk there.
+ */
+function escapeActionMarkdown(text: string): string {
+  // Split on balanced single-backtick spans, keeping the delimiters.
   return text
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+    .split(/(`[^`]*`)/g)
+    .map((seg) => (seg.startsWith("`") && seg.endsWith("`") && seg.length >= 2 ? seg : escapeMarkdown(seg)))
+    .join("");
 }
 
 function parseInput(raw: string | undefined): Record<string, unknown> | null {

package/telegram-plugin/pty-partial-handler.ts

@@ -48,13 +48,6 @@ export interface PtyHandlerState {
   pendingPtyPartial: { text: string } | null
   /** Active streams, keyed by `chat_id:thread_id`. */
   activeDraftStreams: Map<string, DraftStreamHandle>
-  /**
-   * Parallel to activeDraftStreams: parseMode baked into each controller.
-   * Lets `handleStreamReply` detect and rotate streams whose parseMode no
-   * longer matches the caller's resolved format (bug 1). Optional for
-   * backwards compatibility.
-   */
-  activeDraftParseModes?: Map<string, 'HTML' | 'MarkdownV2' | undefined>
   /**
    * Chats whose PTY preview is claimed by an in-flight reply handler.
    * Partials for these chats are dropped to avoid duplicates.
@@ -67,8 +60,6 @@ export interface PtyHandlerState {
 export interface PtyHandlerDeps {
   bot: { api: StreamBotApi }
   retry?: RetryPolicy
-  /** Markdown → HTML renderer applied to the text before stream.update. */
-  renderText: (text: string) => string
   /** Optional structured event hook, called once per invocation. */
   logEvent?: (ev: {
     kind: 'pty_partial_received'
@@ -154,7 +145,10 @@ export function handlePtyPartialPure(
       bot: deps.bot,
       chatId,
       threadId,
-      parseMode: 'HTML',
+      // PTY-tail previews are raw terminal/TUI output, not authored
+      // markdown — send them literally so control glyphs and box-drawing
+      // characters aren't misinterpreted as markdown syntax (#2669).
+      literalText: true,
       disableLinkPreview: true,
       throttleMs: 600,
       retry: deps.retry,
@@ -177,11 +171,9 @@ export function handlePtyPartialPure(
         : {}),
     })
     state.activeDraftStreams.set(sKey, stream)
-    state.activeDraftParseModes?.set(sKey, 'HTML')
   }
 
-  const rendered = deps.renderText(text)
-  void stream.update(rendered).catch(() => { /* swallow — logged elsewhere */ })
+  void stream.update(text).catch(() => { /* swallow — logged elsewhere */ })
 
   return created ? 'update-new' : 'update-existing'
 }

package/telegram-plugin/quota-check.ts

@@ -250,21 +250,21 @@ export function formatResetRelative(target: Date | null, now: Date = new Date())
  */
 export function formatQuotaBlock(q: QuotaUtilization, now: Date = new Date()): string {
   const lines: string[] = [];
-  lines.push("<b>Claude plan quota</b>");
+  lines.push("**Claude plan quota**");
   lines.push("");
   lines.push(
-    `<b>5h window</b>  ${Math.round(q.fiveHourUtilizationPct)}% · ${formatResetRelative(q.fiveHourResetAt, now)}`,
+    `**5h window**  ${Math.round(q.fiveHourUtilizationPct)}% · ${formatResetRelative(q.fiveHourResetAt, now)}`,
   );
   lines.push(
-    `<b>7d window</b>  ${Math.round(q.sevenDayUtilizationPct)}% · ${formatResetRelative(q.sevenDayResetAt, now)}`,
+    `**7d window**  ${Math.round(q.sevenDayUtilizationPct)}% · ${formatResetRelative(q.sevenDayResetAt, now)}`,
   );
   if (q.representativeClaim) {
     lines.push("");
-    lines.push(`<i>Binding window: ${q.representativeClaim.replace(/_/g, " ")}</i>`);
+    lines.push(`_Binding window: ${q.representativeClaim.replace(/_/g, " ")}_`);
   }
   if (q.overageStatus && q.overageStatus !== "allowed") {
     const reason = q.overageDisabledReason ? ` (${q.overageDisabledReason})` : "";
-    lines.push(`<i>Overage: ${q.overageStatus}${reason}</i>`);
+    lines.push(`_Overage: ${q.overageStatus}${reason}_`);
   }
   return lines.join("\n");
 }

package/telegram-plugin/quota-watch.ts

@@ -498,12 +498,12 @@ function buildAllExhaustedMessage(
     ? `Earliest reset: ${formatRelative(new Date(earliest), new Date(now))}.`
     : `Reset time unknown (no window data).`;
   return [
-    `🔴 <b>All accounts exhausted</b>`,
+    `🔴 **All accounts exhausted**`,
     ``,
     `Every Anthropic account (${accounts.length}) is quota-walled — there is no healthy account to fail over to.`,
     resetLine,
     ``,
-    `<i>This is self-healing: agents resume and deferred scheduled jobs run automatically once a window resets. Nothing is lost. Add headroom with <code>/auth add</code> if this recurs.</i>`,
+    `_This is self-healing: agents resume and deferred scheduled jobs run automatically once a window resets. Nothing is lost. Add headroom with \`/auth add\` if this recurs._`,
   ].join("\n");
 }
 
@@ -511,11 +511,11 @@ function buildFleetRecoveredMessage(
   accounts: Array<{ label: string; exhausted: boolean }>,
 ): string {
   const healthy = accounts.filter((a) => !a.exhausted).map((a) => a.label);
-  const which = healthy.length > 0 ? ` (<code>${escapeHtml(healthy[0]!)}</code>)` : "";
+  const which = healthy.length > 0 ? ` (\`${escapeHtml(healthy[0]!)}\`)` : "";
   return [
-    `🟢 <b>Fleet recovered</b> — at least one account is healthy again${which}.`,
+    `🟢 **Fleet recovered** — at least one account is healthy again${which}.`,
     ``,
-    `<i>Agents are back; any deferred scheduled jobs will run on their next occurrence.</i>`,
+    `_Agents are back; any deferred scheduled jobs will run on their next occurrence._`,
   ].join("\n");
 }
 
@@ -535,21 +535,21 @@ function buildThrottlingMessage(agentName: string, snap: AccountSnapshot): strin
 
   const activeNote = snap.isActive
     ? ""
-    : `\nThis is a non-active account. Consider <code>/auth use ${escapeHtml(snap.label)}</code> to switch, or keep it as a fallback reserve.`;
+    : `\nThis is a non-active account. Consider \`/auth use ${escapeHtml(snap.label)}\` to switch, or keep it as a fallback reserve.`;
 
   const altNote = snap.isActive
-    ? `\nConsider <code>/auth use &lt;other-account&gt;</code> if you have a healthier account, or wait for the ${winLabel} window to refill${resetStr}.`
+    ? `\nConsider \`/auth use <other-account>\` if you have a healthier account, or wait for the ${winLabel} window to refill${resetStr}.`
     : "";
 
   return [
-    `🟡 <b>Quota approaching limit</b> — <code>${escapeHtml(snap.label)}</code>`,
+    `🟡 **Quota approaching limit** — \`${escapeHtml(snap.label)}\``,
     ``,
     `${fiveStr} of 5h  ·  ${sevenStr} of 7d`,
     `Binding window: ${winLabel}${resetStr}`,
     `${activeNote}${altNote}`,
     ``,
-    `<i>Threshold: ${THROTTLING_THRESHOLD_PCT}% on either window. Live-probe corroborated (#2495).</i>`,
-    `<i>Run /auth for full fleet status or /usage for the active account.</i>`,
+    `_Threshold: ${THROTTLING_THRESHOLD_PCT}% on either window. Live-probe corroborated (#2495)._`,
+    `_Run /auth for full fleet status or /usage for the active account._`,
   ]
     .join("\n")
     .replace(/\n\n\n+/g, "\n\n")
@@ -563,21 +563,16 @@ function buildRecoveryMessage(agentName: string, snap: AccountSnapshot): string
     : "Current quota data unavailable.";
 
   return [
-    `🟢 <b>Quota back in healthy range</b> — <code>${escapeHtml(snap.label)}</code>`,
+    `🟢 **Quota back in healthy range** — \`${escapeHtml(snap.label)}\``,
     ``,
     utilLine,
     ``,
-    `<i>Below ${THROTTLING_THRESHOLD_PCT}% on both windows.</i>`,
+    `_Below ${THROTTLING_THRESHOLD_PCT}% on both windows._`,
   ].join("\n");
 }
 
 function escapeHtml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
+  return s.replace(/([\\`*_~=\[\]|])/g, "\\$1");
 }
 
 // ─── State persistence ────────────────────────────────────────────────────────

package/telegram-plugin/recent-outbound-dedup.ts

@@ -15,8 +15,8 @@
  *      (raw markdown, since reply tools don't always render HTML).
  *
  * Smoking-gun evidence: klanker chat 12345, msgs 5025 + 5027,
- * 11s apart. msg=5025 had `<b>...</b>` (turn-flush + markdownToHtml).
- * msg=5027 had `**...**` (the raw markdown reply tool's payload).
+ * 11s apart. The two paths historically rendered identical content two
+ * different ways (one HTML-escaped, one raw markdown) and shipped both.
  * Same content, different formatting, two messages.
  *
  * Fix shape: maintain a small in-memory cache of "what we just sent"
@@ -188,9 +188,9 @@ function makeKey(chatId: string, threadId: number | undefined): string {
 
 /**
  * Normalise text for content equality. The bug we're defending
- * against produces the SAME content rendered two different ways:
- * one path runs `markdownToHtml` (so `**foo**` becomes `<b>foo</b>`),
- * the other doesn't. Both must hash identically.
+ * against produces the SAME content rendered two different ways
+ * (historically one HTML-rendered, the other raw markdown). Both must
+ * hash identically — so we strip both HTML tags and markdown markers.
  *
  * Steps:
  *   1. Strip HTML tags (`<b>foo</b>` → `foo`).

package/telegram-plugin/registry/turns-schema.ts

@@ -218,9 +218,14 @@ export function openTurnsDb(agentDir: string): SqliteDatabase {
   const db = new Database(path, { create: true })
   applySchema(db)
   try {
-    // 0o644 so the switchroom-web container (different UID, same host bind-mount)
-    // can read turn history for the Hermes Desktop history panel.
+    // 0o644 on all three SQLite files so the switchroom-web container
+    // (different UID, same host bind-mount) can read turn history.
+    // WAL mode requires read access to registry.db-shm and registry.db-wal
+    // in addition to the main file — all three must be world-readable.
     chmodSync(path, 0o644)
+    for (const suffix of ['-shm', '-wal']) {
+      try { chmodSync(path + suffix, 0o644) } catch { /* doesn't exist yet */ }
+    }
   } catch {
     /* ignore — chmod not supported on some FUSE mounts */
   }
@@ -498,11 +503,46 @@ export function findRecentTurnsForChat(
  *
  * `limit` defaults to 20, max 200.
  */
+/**
+ * Return distinct thread_ids (null = general topic) for a given chat_id.
+ * Used by the Hermes adapter to enumerate forum topics as separate sessions.
+ */
+export function listDistinctThreadIds(
+  db: SqliteDatabase,
+  chatId: string,
+): (string | null)[] {
+  const rows = db.prepare(`
+    SELECT DISTINCT thread_id FROM turns
+    WHERE chat_id = ?
+    ORDER BY thread_id ASC
+  `).all(chatId) as { thread_id: string | null }[]
+  return rows.map((r) => r.thread_id)
+}
+
 export function listTurnsForAgent(
   db: SqliteDatabase,
-  opts: { limit?: number } = {},
+  opts: { limit?: number; chatId?: string; threadId?: string | null } = {},
 ): Turn[] {
   const limit = Math.min(Math.max(1, opts.limit ?? 20), 200)
+  if (opts.chatId && 'threadId' in opts) {
+    // threadId may be a string ID or null (general topic)
+    const rows = db.prepare(`
+      SELECT * FROM turns
+      WHERE chat_id = ? AND thread_id IS ?
+      ORDER BY started_at DESC
+      LIMIT ?
+    `).all(opts.chatId, opts.threadId ?? null, limit) as RawTurnRow[]
+    return rows.map(mapRow)
+  }
+  if (opts.chatId) {
+    const rows = db.prepare(`
+      SELECT * FROM turns
+      WHERE chat_id = ?
+      ORDER BY started_at DESC
+      LIMIT ?
+    `).all(opts.chatId, limit) as RawTurnRow[]
+    return rows.map(mapRow)
+  }
   const rows = db.prepare(`
     SELECT * FROM turns
     ORDER BY started_at DESC

package/telegram-plugin/retry-api-call.ts

@@ -253,24 +253,59 @@ export async function retryWithThreadFallback<T>(
 
 /**
  * True when Telegram rejected a message because it couldn't parse the
- * HTML/entities we sent — our prevention (markdownToHtml +
- * sanitizeForTelegram + splitHtmlChunks) let something malformed
- * through anyway. These 400s are deliberately NOT swallowed or retried
- * by `retryApiCall` (only not-modified / not-found / thread-not-found
- * are) — they surface to the caller, which recovers by resending the
- * chunk as plain text (parse_mode unset). Same "caller-level fallback"
- * shape as the THREAD_NOT_FOUND contract above.
+ * markdown entities we sent on the rich-message path (#2669). There is no
+ * new rich-specific error class in grammy 1.44 — a malformed-markdown
+ * failure still throws `GrammyError` with the standard
+ * `{ ok:false, error_code:400, description }` shape, the same family as the
+ * legacy "can't parse entities" 400. These 400s are deliberately NOT
+ * swallowed or retried by `retryApiCall` (only not-modified / not-found /
+ * thread-not-found are) — they surface to the caller, which recovers by
+ * resending the chunk as plain text (no rich-message wrapper, so the
+ * parser never runs). Same "caller-level fallback" shape as the
+ * THREAD_NOT_FOUND contract above.
  */
 export function isHtmlParseRejectError(err: unknown): boolean {
   if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  // A too-long rejection is a LENGTH error (see isMessageTooLongError) — never
+  // route it through the plain-text parse-reject fallback, which would resend
+  // the same oversized body and fail again. The caller re-splits instead.
+  if (isMessageTooLongError(err)) return false
   const d = (err.description || '').toLowerCase()
   return (
     d.includes("can't parse entities") ||
     d.includes('can’t parse entities') ||
+    d.includes("can't parse") ||
+    d.includes('can’t parse') ||
+    d.includes('parse markdown') ||
+    d.includes('parse rich') ||
     d.includes('unsupported start tag') ||
     d.includes('unclosed start tag') ||
     d.includes("can't find end of the entity") ||
+    d.includes('can’t find end of the entity') ||
     // covers both "expected end tag" and "unexpected end tag"
     d.includes('expected end tag')
   )
 }
+
+/**
+ * True when Telegram rejected the message because the BODY WAS TOO LONG (over
+ * the rich-message wire cap), not because the markdown failed to parse.
+ *
+ * The rich path surfaces this as `RICH_MESSAGE_TEXT_TOO_LONG` (empirically the
+ * description for 32769+ chars); the legacy plain-text path used
+ * `MESSAGE_TOO_LONG` / "message is too long". A caller that hits this should
+ * re-split the body (`splitMarkdownChunks` at a smaller cap) and resend, NOT
+ * treat it as a parse-reject (which resends the same oversized payload as
+ * plain text). Mirrors rich-send.ts `isLengthError`.
+ */
+export function isMessageTooLongError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  const d = (err.description || '').toLowerCase()
+  return (
+    d.includes('rich_message_text_too_long') ||
+    d.includes('message_too_long') ||
+    d.includes('text_too_long') ||
+    d.includes('message is too long') ||
+    d.includes('text is too long')
+  )
+}

package/telegram-plugin/rich-send.ts

@@ -0,0 +1,86 @@
+/**
+ * Rich-message send/edit helpers (Bot API 10.1, #2669).
+ *
+ * Every outbound message in the plugin goes through `sendRichMessage` /
+ * `editMessageText({ markdown })` with raw GFM markdown. These two tiny
+ * helpers build the canonical call shape so the ~dozens of card surfaces
+ * and the gateway core all share ONE rendering path:
+ *
+ *   - `richMessage(text)` → `{ markdown: text }`, the `InputRichMessage`
+ *     accepted by both `sendRichMessage` and `editMessageText`.
+ *   - `isParseEntitiesError(err)` → true when Telegram rejected the body
+ *     because it couldn't parse the markdown entities. There is NO new
+ *     rich-specific error class in grammy 1.44 — a malformed-markdown
+ *     failure still throws `GrammyError` with the standard
+ *     `{ ok:false, error_code:400, description }` shape, the same family
+ *     as the legacy "can't parse entities" 400. Callers recover by
+ *     resending the SAME message id as plain text (no rich, no parse_mode).
+ */
+
+import { GrammyError } from 'grammy'
+
+/** The `InputRichMessage` shape grammy 1.44 accepts on send AND edit. */
+export interface InputRichMessageMarkdown {
+  markdown: string
+}
+
+/** Wrap raw GFM markdown into the rich-message input object. */
+export function richMessage(markdown: string): InputRichMessageMarkdown {
+  return { markdown }
+}
+
+/**
+ * True when Telegram rejected a message because it couldn't parse the
+ * markdown entities we sent. These 400s are deliberately NOT swallowed or
+ * retried by the retry policy — they surface to the caller, which recovers
+ * by resending the body as plain text (a literal string, no rich-message
+ * wrapper, so the parser never runs). Same "caller-level fallback" contract
+ * the old HTML path used.
+ */
+export function isParseEntitiesError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  // A too-long rejection is a LENGTH error, not a parse error — never let the
+  // length case fall through here (it would be "recovered" by resending the
+  // same oversized body as plain text, which fails again). Classify it
+  // separately via isLengthError so the caller re-splits instead.
+  if (isLengthError(err)) return false
+  const d = (err.description || '').toLowerCase()
+  return (
+    d.includes("can't parse entities") ||
+    d.includes('can’t parse entities') ||
+    d.includes("can't parse") ||
+    d.includes('can’t parse') ||
+    d.includes('parse markdown') ||
+    d.includes('parse rich') ||
+    d.includes("can't find end of the entity") ||
+    d.includes('can’t find end of the entity') ||
+    d.includes('unsupported start tag') ||
+    d.includes('unclosed start tag') ||
+    // covers both "expected end tag" and "unexpected end tag"
+    d.includes('expected end tag')
+  )
+}
+
+/**
+ * True when Telegram rejected the message because the BODY WAS TOO LONG (over
+ * the rich-message wire cap), as opposed to a markdown-parse failure.
+ *
+ * The rich path surfaces this distinctly: `RICH_MESSAGE_TEXT_TOO_LONG`
+ * (empirically the description for a body of 32769+ chars). The legacy
+ * plain-text path used `MESSAGE_TOO_LONG` / "message is too long" — both are
+ * matched here so a caller that hits either re-splits the body
+ * (`splitMarkdownChunks`) and resends, instead of misclassifying it as a parse
+ * error (and resending the same oversized payload as plain text) or surfacing
+ * the raw 400.
+ */
+export function isLengthError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  const d = (err.description || '').toLowerCase()
+  return (
+    d.includes('rich_message_text_too_long') ||
+    d.includes('message_too_long') ||
+    d.includes('text_too_long') ||
+    d.includes('message is too long') ||
+    d.includes('text is too long')
+  )
+}

package/telegram-plugin/secret-detect/vault-error.test.ts

@@ -80,7 +80,7 @@ describe("renderVaultCliError", () => {
     // appeared in output (so the operator knew which key triggered
     // the card). New copy keeps the key in <code>…</code> form via
     // htmlEscape — assert it.
-    expect(out.html).toContain("<code>my_key</code>");
+    expect(out.html).toContain("`my_key`");
   });
 
   it("renders sandbox_context for verb=set WITHOUT a key (defensive fallback)", () => {
@@ -92,7 +92,7 @@ describe("renderVaultCliError", () => {
       { verb: "set" },
     );
     expect(out.html).toMatch(/vault_request_save/);
-    expect(out.html).not.toContain("<code></code>");
+    expect(out.html).not.toContain("``");
   });
 
   it("renders sandbox_context for verb=get with /vault get", () => {
@@ -119,7 +119,7 @@ describe("renderVaultCliError", () => {
     );
     expect(out.suppressRaw).toBe(true);
     expect(out.html).toContain("operator approval required");
-    expect(out.html).toContain("<code>telegram_bot_token</code>");
+    expect(out.html).toContain("`telegram_bot_token`");
     expect(out.html).toMatch(/vault_request_save/);
     expect(out.html).not.toMatch(/on the way/i);
   });
@@ -175,12 +175,12 @@ describe("renderVaultCliError", () => {
     expect(out.html).toBe("");
   });
 
-  it("escapes HTML special characters in the key", () => {
+  it("keeps the key literal inside the code span (< > stay verbatim, #2669)", () => {
     const out = renderVaultCliError(
       { kind: "needs_approval", original: "x", key: "key<with>html" },
       { verb: "save" },
     );
-    expect(out.html).not.toContain("<with>");
-    expect(out.html).toContain("key&lt;with&gt;html");
+    // < > are literal in rich markdown and ride verbatim in the `code span`.
+    expect(out.html).toContain("`key<with>html`");
   });
 });