switchroom 0.16.22 → 0.16.24

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,7 +218,14 @@ export function openTurnsDb(agentDir: string): SqliteDatabase {
   const db = new Database(path, { create: true })
   applySchema(db)
   try {
-    chmodSync(path, 0o600)
+    // 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 */
   }
@@ -496,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,13 +253,16 @@ 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
@@ -267,9 +270,14 @@ export function isHtmlParseRejectError(err: unknown): boolean {
   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')
   )

package/telegram-plugin/rich-send.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+  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')
+  )
+}

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

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

@@ -127,10 +127,17 @@ export interface VaultErrorRendering {
 }
 
 function htmlEscape(s: string): string {
-  return s
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+  return s.replace(/([\\`*_~=\[\]|])/g, "\\$1");
+}
+
+/**
+ * Make a string safe to interpolate INSIDE a `code span` without escaping —
+ * content there is literal, so markdown-escaping a key would leak visible
+ * backslashes (e.g. `my\_key`). Only a backtick can prematurely close the
+ * span, so split it with a zero-width space (#2669).
+ */
+function codeSpanSafe(s: string): string {
+  return s.replace(/`/g, "`​");
 }
 
 /**
@@ -173,13 +180,13 @@ export function renderVaultCliError(
       return {
         suppressRaw: true,
         html:
-          `⚠️ <b>New vault key — operator approval required.</b>\n` +
+          `⚠️ **New vault key — operator approval required.**\n` +
           (key
-            ? `The agent tried to save <code>${htmlEscape(key)}</code>, but `
+            ? `The agent tried to save \`${codeSpanSafe(key)}\`, but `
             : `The agent tried to save a new key, but `) +
           `agents can only rotate existing keys via the broker; introducing ` +
           `a new key needs an operator action.\n\n` +
-          `<b>Ask the agent</b> to call its <code>vault_request_save</code> ` +
+          `**Ask the agent** to call its \`vault_request_save\` ` +
           `tool — it'll render an approval card in this chat with ` +
           `[✅ Save once] [🚫 Discard] [✏️ Rename] buttons. One tap saves the ` +
           `secret to the vault; no re-paste needed.`,
@@ -194,12 +201,12 @@ export function renderVaultCliError(
       return {
         suppressRaw: true,
         html:
-          `⚠️ <b>Vault broker isn't reachable.</b>\n` +
+          `⚠️ **Vault broker isn't reachable.**\n` +
           `From inside the agent sandbox there's no fallback path. ` +
           `Telegram-native broker recovery is tracked as a follow-up — ` +
           `for now, on the host:\n` +
-          `<pre>switchroom vault broker status</pre>\n` +
-          `<i>Or, if the broker is wedged: <code>docker compose -p switchroom restart vault-broker</code>.</i>`,
+          "```\nswitchroom vault broker status\n```\n" +
+          `_Or, if the broker is wedged: \`docker compose -p switchroom restart vault-broker\`._`,
       };
     case "broker_denied":
       // Telegram-native grant flow shipped in #969 P2b + #1012:
@@ -210,14 +217,14 @@ export function renderVaultCliError(
       return {
         suppressRaw: true,
         html:
-          `⚠️ <b>Vault broker refused the request.</b>\n` +
+          `⚠️ **Vault broker refused the request.**\n` +
           (key
-            ? `The agent isn't authorized to access <code>${htmlEscape(key)}</code>. `
+            ? `The agent isn't authorized to access \`${codeSpanSafe(key)}\`. `
             : `The agent isn't authorized to access this key. `) +
           `Grant access in two taps:\n` +
-          `• <code>/vault audit &lt;agent&gt;</code> in this chat → tap ` +
+          `• \`/vault audit <agent>\` in this chat → tap ` +
           `[🔓 Allow${key ? ` ${htmlEscape(key)}` : ""}] on the recent denial, OR\n` +
-          `• ask the agent to call <code>vault_request_access</code> — ` +
+          `• ask the agent to call \`vault_request_access\` — ` +
           `an approval card lands here with [✅ Approve] / [🚫 Deny].`,
       };
     case "other":
@@ -234,36 +241,36 @@ function renderSandboxContextSuggestion(
   verb: "set" | "get" | "list" | "init" | "remove" | "save",
   key: string | undefined,
 ): string {
-  const head = `⚠️ <b>Direct vault file IO isn't available from inside the agent sandbox.</b>\n`;
+  const head = `⚠️ **Direct vault file IO isn't available from inside the agent sandbox.**\n`;
   switch (verb) {
     case "set":
     case "save":
       return (
         head +
         (key
-          ? `<b>Ask the agent</b> to call its <code>vault_request_save</code> ` +
-            `tool for <code>${htmlEscape(key)}</code> — an approval card ` +
+          ? `**Ask the agent** to call its \`vault_request_save\` ` +
+            `tool for \`${codeSpanSafe(key)}\` — an approval card ` +
             `lands here with [✅ Save once] / [🚫 Discard] / [✏️ Rename] buttons.`
-          : `<b>Ask the agent</b> to call its <code>vault_request_save</code> ` +
+          : `**Ask the agent** to call its \`vault_request_save\` ` +
             `tool — an approval card lands here with [✅ Save once] / [🚫 Discard] / [✏️ Rename] buttons.`)
       );
     case "get":
       return (
         head +
-        `From this chat: <code>/vault get${key ? ` ${htmlEscape(key)}` : " &lt;key&gt;"}</code>`
+        `From this chat: \`/vault get${key ? ` ${codeSpanSafe(key)}` : " <key>"}\``
       );
     case "list":
-      return head + `From this chat: <code>/vault list</code>`;
+      return head + `From this chat: \`/vault list\``;
     case "remove":
       return (
         head +
         `Use the operator host CLI for now — Telegram-native delete is tracked as a follow-up. ` +
-        `<i>(Removing a vault key is a rare, irreversible operation; an in-chat confirmation card is on the punch list.)</i>`
+        `_(Removing a vault key is a rare, irreversible operation; an in-chat confirmation card is on the punch list.)_`
       );
     case "init":
       return (
         head +
-        `Vault bootstrap is a one-time host-shell step: <code>switchroom vault init</code>.`
+        `Vault bootstrap is a one-time host-shell step: \`switchroom vault init\`.`
       );
   }
 }

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

@@ -154,14 +154,25 @@ export function createRobustApiCall() {
   })
 }
 
-// ─── HTML escape helpers ─────────────────────────────────────────────────
+// ─── Markdown escape helpers (#2669) ──────────────────────────────────────
 
+/**
+ * Escape GFM-markdown specials in a dynamic value interpolated into prose.
+ * Kept under the legacy `escapeHtmlForTg` name so callers don't churn.
+ */
 export function escapeHtmlForTg(text: string): string {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
 }
 
+/**
+ * Wrap CLI / command output in a fenced code block. Inside a fence the
+ * content is literal (no escaping), so we pass `text` through verbatim —
+ * except a fence-closing ``` sequence in the content, which we defuse so it
+ * can't terminate the block early.
+ */
 export function preBlock(text: string): string {
-  return '<pre>' + escapeHtmlForTg(text) + '</pre>'
+  const safe = text.replace(/```/g, '`​``')
+  return '```\n' + safe + '\n```'
 }
 
 export function stripAnsi(text: string): string {
@@ -278,11 +289,17 @@ export function makeSwitchroomReply(
   ): Promise<void> {
     const chatId = String(ctx.chat!.id)
     const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
-    await ctx.reply(text, {
+    const opts = {
       ...(threadId != null ? { message_thread_id: threadId } : {}),
-      ...(options.html ? { parse_mode: 'HTML' as const, link_preview_options: { is_disabled: true } } : {}),
       ...(options.reply_markup ? { reply_markup: options.reply_markup } : {}),
-    })
+    }
+    // #2669: `options.html:true` now means "render `text` as GFM markdown via
+    // the rich-message path" (legacy field name kept). Plain otherwise.
+    if (options.html) {
+      await ctx.replyWithRichMessage({ markdown: text }, opts)
+    } else {
+      await ctx.reply(text, opts)
+    }
   }
 }
 

package/telegram-plugin/silence-poke.ts

@@ -377,17 +377,20 @@ export function silenceMsForKey(key: string, now: number): number | null {
 }
 
 /**
- * Verbatim framework-fallback text — the user-visible "still working / still
- * thinking" message the gateway sends at the 300s threshold when the model
- * hasn't broken its own silence. Wording is load-bearing (see
- * `reference/rfcs/conversational-pacing.md` § Safety net). Two principles:
+ * Framework-fallback text for the 300s silence threshold. Returns `null` for
+ * the pure-stall cases (the "still working / still thinking" / "running <Tool>
+ * for Nm" notice) — that timer-fired stall ping was a stop-gap from before the
+ * live-updating reply/draft carried the progress beats natively, and the
+ * operator has retired it (it's the exact cadence-based "still working" update
+ * the conversational-pacing RFC's Anti-patterns section bans). The 300s
+ * fallback's surviving job — unwedging a turn that produced no output at all —
+ * is the gateway's turn-teardown after this call, NOT a user-visible message,
+ * so dropping the stall send keeps the safety net's real work intact (see
+ * `reference/rfcs/conversational-pacing.md` § Silence-poke fallback).
  *
- *   1. The parenthetical `(no update from agent in N min)` is honest —
- *      distinguishes from "the agent said something" so users learn to trust
- *      real agent messages. `N` is derived from `silenceMs`, never hard-coded.
- *   2. The verb is `working` by default, `thinking` only when the session
- *      stream has emitted a `kind: 'thinking'` event in the last 30s. Picked
- *      by the caller via `fallbackKind`; this helper just formats.
+ * The ONE case that still returns a string is `blockedOnApproval`: the turn is
+ * parked on an approval card waiting for YOUR tap. That is not a stall — it
+ * tells the user the ball is in their court — so it keeps pinging.
  *
  * Extracted from the gateway's `onFrameworkFallback` callback so the wording
  * can be snapshot-tested in isolation. CC-4 in `docs/status-ask-cause-classes.md`.
@@ -397,73 +400,27 @@ export function formatFrameworkFallbackText(
   silenceMs: number,
   inFlightTools: ToolSnapshot[] = [],
   blockedOnApproval = false,
-): string {
+): string | null {
   const minutes = Math.max(1, Math.round(silenceMs / 60_000))
   // The turn isn't stalled — it's parked on an approval card waiting for YOUR
   // tap (the dominant live "wedge" class is benign approval-latency, not a
   // hang). Saying "still working…" here actively lies; name the real blocker so
   // the operator knows the ball is in their court. Takes precedence over the
-  // in-flight-tool framing (a tool awaiting approval isn't "running").
+  // in-flight-tool framing (a tool awaiting approval isn't "running"). This is
+  // the only branch that still emits a user-visible message.
   if (blockedOnApproval) {
     return `waiting for your approval — tap Approve or Deny on the card above (${minutes} min)`
   }
-  const suffix = `(no update from agent in ${minutes} min)`
-  // #1292 case (a): tools in flight. Name the longest-running one
-  // (entry[0] — caller pre-sorts by startedAt ascending). Avoid the
-  // "still working" framing #1292 explicitly calls out as dishonest:
-  // the agent IS doing work, we can see the tool. Format:
-  //   running Grep "foo" for 4m (no update from agent in 5 min)
-  //   running Grep "foo" + 2 more (4m) (no update from agent in 5 min)
-  //   running Grep (no label) for 4m (no update from agent in 5 min)
-  //
-  // Raw MCP tool names (`mcp__server__tool`) are technical identifiers
-  // and look like a leak when surfaced to a user. When the tool name
-  // matches that shape AND a human-friendly label is available, drop
-  // the raw name and lead with the label instead:
-  //   Searching memory for 4m (no update from agent in 5 min)
-  // Built-in tool names (Grep, Read, Bash) stay as-is — they ARE
-  // human-readable, and the label is supplementary detail (e.g. the
-  // search pattern) that reads naturally after the verb.
-  if (inFlightTools.length > 0) {
-    const longest = inFlightTools[0]!
-    const dur = formatDurationShort(longest.durationMs)
-    const labelTail = longest.label && longest.label.length > 0
-      ? ` ${truncateLabel(longest.label)}`
-      : ''
-    const more = inFlightTools.length > 1
-      ? ` + ${inFlightTools.length - 1} more`
-      : ''
-    const isMcpRawName = /^mcp__/.test(longest.name)
-    if (isMcpRawName && labelTail !== '') {
-      // Label-only: "Searching memory for 4m (…)". Drop the raw
-      // `mcp__server__tool` and the leading "running" because the
-      // label already reads as a gerund phrase.
-      return `${truncateLabel(longest.label!)}${more} for ${dur} ${suffix}`
-    }
-    return `running ${longest.name}${labelTail}${more} for ${dur} ${suffix}`
-  }
-  return fallbackKind === 'thinking'
-    ? `still thinking… ${suffix}`
-    : `still working… ${suffix}`
-}
-
-/** Compact m/s rendering for the fallback message. Anything under a
- *  minute reads as `${s}s`, otherwise `${m}m`. Always rounds toward the
- *  user-honest direction — "4m" for 4m 30s, "5m" for 4m 45s. */
-function formatDurationShort(ms: number): string {
-  const totalSec = Math.max(0, Math.round(ms / 1000))
-  if (totalSec < 60) return `${totalSec}s`
-  const minutes = Math.round(totalSec / 60)
-  return `${minutes}m`
-}
-
-/** Telegram lines are short on mobile. Clip the label to keep the
- *  fallback message readable. Truncation point is generous (60 chars)
- *  because tool labels are pre-truncated by `toolLabel()` already. */
-function truncateLabel(label: string): string {
-  const MAX = 60
-  if (label.length <= MAX) return label
-  return label.slice(0, MAX - 1) + '…'
+  // Stop-gap retired: the "still working… (no update from agent in N min)" /
+  // "running <Tool> for Nm" stall notice (including the #1292 tool-aware
+  // enrichment) no longer sends. The live draft + the model's own pacing beats
+  // carry progress; a timer-fired stall ping on top of that is the banned
+  // cadence-based update. `fallbackKind` and `inFlightTools` are now unused for
+  // the stall path but kept on the signature so the gateway's call sites — and
+  // the deterministic update-status / unwedge paths around them — are untouched.
+  void fallbackKind
+  void inFlightTools
+  return null
 }
 
 /** Snapshot in-flight tools sorted longest-running first — for the honest