switchroom 0.16.28 → 0.16.38

package/telegram-plugin/gateway/status-pin-store.ts

@@ -0,0 +1,302 @@
+/**
+ * status-pin-store.ts — durable snapshot for the status-pin claim set.
+ *
+ * Why this exists: the gateway tracks the messages it has SILENTLY pinned
+ * (`channels.telegram.pin_status_while_working`) in an in-memory Map
+ * (`statusPinState` keyed by pinKey → PinState, plus a companion chatId map).
+ * A gateway/container restart empties that Map. If a session pins the per-turn
+ * status / `🛠 Worker` message and then crashes BEFORE the unpin reconcile runs,
+ * the message stays pinned in Telegram but the next boot has no record of it —
+ * so it never unpins the orphan, and the service-message-deletion handler can't
+ * recognise the orphan's pin as "ours" either. Result: a stale status pin from
+ * a dead session lingers.
+ *
+ * This makes cleanup self-contained across restart: every pin claim persists
+ * here; on boot the gateway loads the persisted set and unpins each entry
+ * (a status pin from a PRIOR session is stale by definition — the turn it
+ * represented is over or crashed), then clears the store. It does NOT re-adopt
+ * or re-pin — it only cleans up.
+ *
+ * Shape choice — SNAPSHOT, not append-log, mirroring obligation-store.ts. The
+ * claim set is tiny and bounded (one entry per in-flight pinned key, normally
+ * 0–2). Rewriting the whole set on each change is trivially cheap and needs no
+ * compaction. Crash-safety is write-tmp + atomic rename: a crash leaves EITHER
+ * the prior complete snapshot OR the new one, never a torn file. PURE w.r.t.
+ * the injected fs seam ⇒ unit-testable.
+ */
+
+export interface StatusPinStoreFsSeam {
+  readFileSync: (path: string) => string
+  writeFileSync: (path: string, data: string) => void
+  /** Atomic same-dir replace (POSIX rename) so a crash mid-write can't tear
+   *  the snapshot. */
+  renameSync: (from: string, to: string) => void
+  existsSync: (path: string) => boolean
+}
+
+/** One persisted pin claim: the pinKey, the chat it lives in, and the pinned
+ *  message id (so boot cleanup can unpin exactly that message).
+ *
+ *  Concurrency note: there is NO turn/worker-id dimension on the ownership guard
+ *  because the single-gateway startup mutex (acquireStartupLock) guarantees
+ *  exactly one live gateway per agent owns this shared file at a time — so a
+ *  pinKey (`fg:`/`wk:`) is unambiguous within the one owning process, and boot
+ *  cleanup only ever runs after winning that mutex.
+ *
+ *  `pending` marks a record written BEFORE the pin API call landed (persist-
+ *  intent-first). A crash in the window between the pin API call and the
+ *  confirming rewrite leaves a pending record on disk; next-boot cleanup unpins
+ *  pending records too, closing the persist-after-pin leak. Absent/false means
+ *  the pin was confirmed applied. Optional so a v1 snapshot (no field) still
+ *  loads fail-open as a confirmed pin. */
+export interface PersistedStatusPin {
+  pinKey: string
+  chatId: string
+  messageId: number
+  /** True while the pin API call is in-flight / unconfirmed (see above). */
+  pending?: boolean
+}
+
+/** Envelope version. v1 had no `pending` field; a v1 row loads as a confirmed
+ *  pin (pending undefined). v2 adds the optional `pending` flag. Both load
+ *  fail-open — an unknown/newer version yields []. */
+interface SnapshotEnvelope {
+  v: 1 | 2
+  pins: PersistedStatusPin[]
+}
+
+function isPinRow(x: unknown): x is PersistedStatusPin {
+  if (x == null || typeof x !== 'object') return false
+  const o = x as Record<string, unknown>
+  return (
+    typeof o.pinKey === 'string' &&
+    o.pinKey.length > 0 &&
+    typeof o.chatId === 'string' &&
+    o.chatId.length > 0 &&
+    typeof o.messageId === 'number' &&
+    (o.pending === undefined || typeof o.pending === 'boolean')
+  )
+}
+
+/**
+ * Load the persisted pin set. Returns [] on a missing, unreadable, or malformed
+ * file (fail-open to empty: a corrupt snapshot must never crash boot — worst
+ * case an orphaned pin isn't cleaned up this boot, strictly no worse than the
+ * pre-persistence behaviour).
+ */
+export function loadStatusPins(
+  path: string,
+  fs: StatusPinStoreFsSeam,
+): PersistedStatusPin[] {
+  if (!fs.existsSync(path)) return []
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path)
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed == null || typeof parsed !== 'object') return []
+  const env = parsed as Record<string, unknown>
+  if ((env.v !== 1 && env.v !== 2) || !Array.isArray(env.pins)) return []
+  return env.pins.filter(isPinRow)
+}
+
+/**
+ * Persist the pin set atomically (write sibling tmp → rename over the real
+ * path). Best-effort relative to fs availability: a write failure is logged but
+ * never thrown — a failing store degrades to in-memory-only (the pre-
+ * persistence behaviour), it must not break live pinning.
+ */
+export function persistStatusPins(
+  path: string,
+  fs: StatusPinStoreFsSeam,
+  snapshot: readonly PersistedStatusPin[],
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const env: SnapshotEnvelope = { v: 2, pins: [...snapshot] }
+  const tmp = path + '.tmp'
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(env))
+    fs.renameSync(tmp, path)
+  } catch (err) {
+    log(
+      `status-pin-store: persist FAILED path=${path}: ${(err as Error).message} — ` +
+        `durability degraded to in-memory\n`,
+    )
+  }
+}
+
+/**
+ * A single tracked live pin claim, as the gateway holds it in memory
+ * (statusPinState keyed by pinKey → PinState.messageId, plus the companion
+ * statusPinChatIds pinKey → chatId map). Flattened here so the ownership guard
+ * is a pure, unit-testable function decoupled from the gateway's Maps.
+ */
+export interface TrackedStatusPin {
+  chatId: string
+  messageId: number
+}
+
+/**
+ * CHAT-SCOPED ownership guard for a `pinned_message` service update.
+ *
+ * Telegram message_ids are per-chat small integers, and the gateway tracks
+ * many simultaneous pins across different chats/topics. Matching on messageId
+ * ALONE is a real bug: a pin update in chat B whose pinned id happens to equal
+ * a status-pin id tracked in chat A would pass, and the gateway would delete
+ * chat B's service message — including an operator's MANUAL pin notice. So the
+ * match REQUIRES both the messageId AND that the tracked entry lives in the
+ * SAME chat as the incoming update.
+ */
+export function pinnedMessageIsOurs(
+  tracked: Iterable<TrackedStatusPin>,
+  chatId: string,
+  pinnedMessageId: number,
+): boolean {
+  for (const t of tracked) {
+    if (t.messageId === pinnedMessageId && t.chatId === chatId) return true
+  }
+  return false
+}
+
+/**
+ * Boot-time orphan cleanup, extracted as a pure routine over injected seams so
+ * the ordering + best-effort contract is unit-testable against the REAL code
+ * (the gateway's thin wrapper just binds the live fs / unpin api / logger).
+ *
+ * Any pin persisted by a PRIOR session is stale by definition — its turn ended
+ * or the session crashed before its unpin reconcile ran. This includes records
+ * left `pending` (the persist-intent-first write from `reconcileAndPersist-
+ * StatusPin`): a crash between the pin API call and its confirming rewrite
+ * leaves a pending record whose pin MAY have landed in Telegram, so we must
+ * treat it exactly like a confirmed one and unpin it. We therefore best-effort
+ * unpin EVERY persisted entry (confirmed and pending alike — a failure is
+ * non-fatal) and then EMPTY the store regardless, so a permanently-
+ * undeliverable unpin can't re-run on every boot. We do NOT re-adopt or re-pin.
+ * Returns the counts for logging/testing.
+ *
+ * CRITICAL: the caller MUST only invoke this AFTER winning the startup mutex.
+ * The store is a shared per-agent file; on a double-boot a losing gateway
+ * running this would unpin the still-alive holder's legitimate pins.
+ */
+export async function runStatusPinBootCleanup(args: {
+  path: string
+  fs: StatusPinStoreFsSeam
+  unpin: (chatId: string, messageId: number) => Promise<unknown>
+  log?: (line: string) => void
+}): Promise<{ cleared: number; total: number }> {
+  const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const persisted = loadStatusPins(args.path, args.fs)
+  if (persisted.length === 0) return { cleared: 0, total: 0 }
+  let cleared = 0
+  for (const pin of persisted) {
+    try {
+      await args.unpin(pin.chatId, pin.messageId)
+      cleared++
+    } catch (err) {
+      log(
+        `status-pin-store: boot cleanup unpin failed ` +
+          `(chat=${pin.chatId} msg=${pin.messageId}): ${(err as Error).message}\n`,
+      )
+    }
+  }
+  // Empty the store regardless — these claims belong to a dead session; leaving
+  // them would re-attempt the same (already-tried) unpins on every future boot.
+  persistStatusPins(args.path, args.fs, [], log)
+  return { cleared, total: persisted.length }
+}
+
+/**
+ * The pin action the gateway wants to take for one key, distilled from
+ * `decidePinAction`. `pin` carries the target message id; `clear` covers both
+ * unpin and no-longer-pinned. The gateway's reconcile computes this and hands
+ * it here so the persist-BEFORE-pin ordering lives in one testable place.
+ */
+export type StatusPinPersistOp =
+  | { kind: 'pin'; messageId: number }
+  | { kind: 'clear' }
+
+/**
+ * Persist-ordering wrapper closing the persist-AFTER-pin leak window.
+ *
+ * THE BUG this fixes: previously the gateway pinned the Telegram message FIRST,
+ * then snapshotted the claim set to disk. A SIGKILL landing between the pin API
+ * call succeeding and the snapshot rename left a pin live in Telegram with NO
+ * on-disk record — so next-boot cleanup couldn't see it and the pin lingered
+ * forever.
+ *
+ * THE FIX: for a `pin`, write a `pending` record to disk BEFORE issuing the pin
+ * API call, then rewrite it as confirmed (pending cleared) once the pin lands
+ * — or drop it if the pin failed. Now a crash anywhere in the window leaves a
+ * pending record on disk, and boot cleanup unpins pending records too (see
+ * runStatusPinBootCleanup), so the orphan is recovered next boot.
+ *
+ * `snapshotOthers` returns the OTHER live claims (every key except `pinKey`) so
+ * the whole set is rewritten atomically each step — mirrors how the gateway
+ * snapshots its Map. `applyPin` performs the real Telegram pin/unpin (the
+ * gateway binds `reconcilePin`) and returns the next in-memory state so the
+ * caller can update its Map. Never throws — persistence is best-effort/fail-open
+ * and pin errors are already swallowed by `applyPin` (reconcilePin).
+ */
+export async function reconcileAndPersistStatusPin(args: {
+  path: string
+  fs: StatusPinStoreFsSeam
+  pinKey: string
+  chatId: string
+  op: StatusPinPersistOp
+  /** Live claims for every OTHER key (rewritten alongside on each step). */
+  snapshotOthers: () => PersistedStatusPin[]
+  /** Execute the real pin/unpin; returns the confirmed message id (pin) or
+   *  null (cleared). Must never throw — API errors are swallowed inside. */
+  applyPin: () => Promise<{ messageId: number } | null>
+  log?: (line: string) => void
+}): Promise<{ messageId: number } | null> {
+  const { path, fs, pinKey, chatId, op } = args
+  const log = args.log ?? ((l: string) => process.stderr.write(l))
+
+  if (op.kind === 'pin') {
+    // Persist INTENT first, marked pending — BEFORE the pin API call. If we
+    // crash after the pin lands but before the confirm rewrite, this pending
+    // record is what boot cleanup uses to unpin the orphan.
+    persistStatusPins(
+      path,
+      fs,
+      [
+        ...args.snapshotOthers(),
+        { pinKey, chatId, messageId: op.messageId, pending: true },
+      ],
+      log,
+    )
+    const next = await args.applyPin()
+    if (next == null) {
+      // Pin failed (claim NOT taken by reconcilePin). Clear the pending record
+      // so we don't leave a phantom claim for a pin that never landed.
+      persistStatusPins(path, fs, args.snapshotOthers(), log)
+      return null
+    }
+    // Pin confirmed — rewrite the record without the pending flag.
+    persistStatusPins(
+      path,
+      fs,
+      [
+        ...args.snapshotOthers(),
+        { pinKey, chatId, messageId: next.messageId },
+      ],
+      log,
+    )
+    return next
+  }
+
+  // clear: unpin (best-effort) THEN drop the record. Ordering is safe here —
+  // if we crash after the unpin but before the rewrite, the stale record just
+  // gets unpinned again next boot (idempotent), never a lingering pin.
+  const next = await args.applyPin()
+  persistStatusPins(path, fs, args.snapshotOthers(), log)
+  return next
+}

package/telegram-plugin/gateway/turns-jsonl-rotate.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal size-cap rotation for the turn-record JSONL (`turns.jsonl`).
+ *
+ * emitTurnRecord appends one line per turn forever with no rotation, so the
+ * file grows unbounded on a long-lived agent. This keeps at most one rotated
+ * generation: when the live file exceeds the cap, it is renamed to
+ * `<path>.1` (overwriting any prior generation) and a fresh live file starts.
+ * Bounded disk: ≤ 2× the cap.
+ *
+ * Pure of the append itself — `maybeRotate` only decides + performs the rename.
+ * Best-effort: the fs hooks are injected so it's unit-testable and so a rotate
+ * failure can be swallowed by the caller (never break turn teardown).
+ */
+export const TURNS_JSONL_MAX_BYTES = 5 * 1024 * 1024 // 5 MiB
+
+export interface RotateFs {
+  statSize: (path: string) => number | undefined // undefined ⇒ file absent
+  rename: (from: string, to: string) => void
+}
+
+/**
+ * Rotate `path` → `path.1` if it is at/over `maxBytes`. Returns true if a
+ * rotation happened. Absent file (statSize undefined) ⇒ no rotation.
+ */
+export function maybeRotate(path: string, fs: RotateFs, maxBytes = TURNS_JSONL_MAX_BYTES): boolean {
+  const size = fs.statSize(path)
+  if (size == null || size < maxBytes) return false
+  fs.rename(path, `${path}.1`)
+  return true
+}

package/telegram-plugin/gateway/unhandled-rejection-policy.ts

@@ -115,7 +115,18 @@ export function classifyRejection(
     // same family so a single bad chat id can't restart-loop the
     // process. The visible boot-probe-failed log is the primary
     // diagnostic; this is the can't-restart-loop guarantee.
-    desc.includes('chat not found')
+    desc.includes('chat not found') ||
+    // Pin-rights failure in a supergroup where the bot is not an admin (or
+    // lacks the "pin messages" right). Telegram returns this as a 400, not a
+    // 403: "not enough rights to manage pinned messages in the chat". The
+    // auto status-pin driver is best-effort and cosmetic — a bot that can't
+    // pin should skip the pin, never crash-loop the gateway. This was the
+    // exact 400 that took marko's gateway down (2026-07-01): the fire-and-
+    // forget `void reconcileStatusPin(...)` leaked the rejection and this
+    // handler shut the process down. reconcileStatusPin now absorbs its own
+    // errors (primary fix); this entry is defense-in-depth so ANY leaked
+    // pin-rights 400 from any path is log-only, not fatal.
+    desc.includes('not enough rights')
   ) {
     return 'log_only'
   }

package/telegram-plugin/gateway/vault-grant-inbound-builders.ts

@@ -132,6 +132,41 @@ export function buildVaultGrantDeniedInbound(opts: {
   }
 }
 
+/**
+ * Build the raw GFM markdown for the "grant approved" confirmation the
+ * gateway edits the approval card into after the operator taps Approve.
+ *
+ * This is ONE markdown string, wrapped ONCE in `richMessage(...)` at the
+ * callsite. The bug this guards (the whole reason this helper exists):
+ * `richMessage(text)` returns an OBJECT `{ markdown }`, so concatenating a
+ * bare string in front of it — `"prefix " + richMessage("suffix")` —
+ * coerces the object via `toString()` and renders a literal
+ * `[object Object]` in the card. Keep the full message inside this builder
+ * and pass the whole thing to a single `richMessage()` call.
+ *
+ * @param agentEscaped  Agent name already run through `escapeHtmlForTg`.
+ * @param scope         'read' | 'write'.
+ * @param key           Vault key (rendered inline-code).
+ * @param days          Grant TTL in whole days.
+ * @param grantId       Broker-returned grant id.
+ * @param footer        Optional trailing footer (e.g. the telegram-id
+ *                      auth-mode note). Empty string when absent.
+ */
+export function buildVaultGrantApprovedCardText(opts: {
+  agentEscaped: string
+  scope: 'read' | 'write'
+  key: string
+  days: number
+  grantId: string
+  footer?: string
+}): string {
+  return (
+    `✅ Granted **${opts.agentEscaped}** ${opts.scope} access to ` +
+    `\`${opts.key}\` for ${opts.days}d. ` +
+    `(grant \`${opts.grantId}\`)` + (opts.footer ?? '')
+  )
+}
+
 /** Subset of PendingVaultRequestSave the save-outcome builders need.
  *  The `vault_request_save` flow has no scope/ttl (it stores a value,
  *  it doesn't mint a scoped grant). */

package/telegram-plugin/gateway/vault-request-access-card.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure renderer for the agent-initiated vault-access approval card (#1012).
+ *
+ * Extracted from gateway.ts so it can be unit-tested without dragging in the
+ * whole gateway module. The card is sent via the rich-message path (GFM
+ * markdown), so:
+ *
+ *   - Non-code-span interpolations (`**agent**`, `_why_`) are markdown-escaped
+ *     via `escapeHtmlForTg` so a stray `*`/`_`/`[` in the agent name or reason
+ *     can't break the surrounding emphasis.
+ *   - Code-span interpolations (`key`, `scope`, `duration`) are LITERAL inside
+ *     the span, so they must NOT be markdown-escaped (that would leak visible
+ *     backslashes, e.g. `openai/OPENAI\_API\_KEY`). The only char that can
+ *     prematurely close a code span is a backtick, so `codeSpanSafe` defuses
+ *     just that one (mirrors approval-card.ts's scope span, #2669). Without
+ *     this, a key whose value closes the span early lets the following
+ *     `_why_` / `_footer_` markdown pair against stray delimiters and the card
+ *     renders on top of itself.
+ */
+
+import { escapeHtmlForTg } from '../shared/bot-runtime.js'
+import { codeSpanSafe } from './approval-card.js'
+
+/** Minimal shape the card needs — a subset of PendingVaultRequestAccess. */
+export interface VaultRequestAccessCardInput {
+  agent: string
+  key: string
+  scope: string
+  reason?: string
+  ttl_seconds: number
+}
+
+export function renderVaultRequestAccessCard(
+  req: VaultRequestAccessCardInput,
+): string {
+  const lines: string[] = []
+  const scopeLabel = req.scope === 'write' ? 'write' : 'read'
+  const days = Math.round(req.ttl_seconds / 86400)
+  const durationLabel =
+    days >= 1 ? `${days}d` : `${Math.round(req.ttl_seconds / 3600)}h`
+  lines.push(`🔐 **${escapeHtmlForTg(req.agent)}** wants vault access`)
+  // Code-span content is literal — defuse only the backtick, never
+  // markdown-escape (see file header).
+  lines.push(`key: \`${codeSpanSafe(req.key)}\``)
+  lines.push(
+    `scope: \`${codeSpanSafe(scopeLabel)}\` · duration: \`${codeSpanSafe(durationLabel)}\``,
+  )
+  // #1790 — always render the why-line, even when the agent omitted `reason`.
+  // Rendering "not provided" makes a missing rationale visibly an agent-side
+  // failure rather than a card-template choice.
+  if (req.reason && req.reason.length > 0) {
+    lines.push(`why: _${escapeHtmlForTg(req.reason)}_`)
+  } else {
+    lines.push(`why: _not provided_`)
+  }
+  lines.push('')
+  lines.push(
+    `_Tap Approve to mint a scoped grant token (same flow as \`switchroom vault grant\`). Tap Deny to refuse — the agent will receive a denial result._`,
+  )
+  return lines.join('\n')
+}

package/telegram-plugin/history.ts

@@ -25,7 +25,7 @@
  * chat exists in the DB.
  */
 
-import { chmodSync, mkdirSync } from 'fs'
+import { chmodSync, existsSync, mkdirSync } from 'fs'
 import { join } from 'path'
 import { redact } from './secret-detect/redact.js'
 
@@ -121,6 +121,7 @@ const DEFAULT_LIMIT = 10
 const MAX_LIMIT = 50
 
 let db: SqliteDatabase | null = null
+let dbPath: string | null = null
 
 /**
  * Open (or create) the history DB and run migrations + retention sweep.
@@ -133,6 +134,7 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
   const Database = loadDatabaseClass()
   mkdirSync(stateDir, { recursive: true, mode: 0o700 })
   const path = join(stateDir, 'history.db')
+  dbPath = path
   db = new Database(path, { create: true })
   // WAL is friendlier for concurrent reads while a long transaction writes,
   // and survives crashes more cleanly than rollback journal.
@@ -171,12 +173,13 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     }
   }
 
-  // Lock the file to owner-only. Same pattern the plugin uses for .env at
-  // server.ts:52. No-op on Windows (would need ACLs).
-  try {
-    chmodSync(path, 0o600)
-  } catch {
-    /* ignore — chmod not supported, e.g. some FUSE mounts */
+  // Readable by owner and others so the web dashboard (different uid than the
+  // agent) can stream replies back to Hermes Desktop. The WAL sidecar files
+  // (-shm/-wal) are also chmod'd so SQLite readonly opens succeed for uid=1000.
+  // 0644 is safe: the per-agent state dir is already operator-accessible.
+  for (const suffix of ['', '-shm', '-wal']) {
+    const f = path + suffix
+    if (existsSync(f)) { try { chmodSync(f, 0o644) } catch { /* ignore */ } }
   }
 
   if (retentionDays > 0) {
@@ -213,6 +216,13 @@ export function checkpointWal(): boolean {
   if (db == null) return false
   try {
     db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').run()
+    // Re-apply permissions after WAL truncation (SQLite may recreate -wal/-shm)
+    if (dbPath) {
+      for (const suffix of ['-shm', '-wal']) {
+        const f = dbPath + suffix
+        if (existsSync(f)) { try { chmodSync(f, 0o644) } catch { /* ignore */ } }
+      }
+    }
     return true
   } catch {
     return false

package/telegram-plugin/idle-footer.ts

@@ -58,8 +58,8 @@ export function formatIdleFooter(rows: ReadonlyArray<TurnRow>, now: number): str
   const latest = rows.reduce((best, row) => (row.startedAt > best.startedAt ? row : best));
 
   if (latest.endedAt == null) {
-    return `⚙️ working since ${formatAgo(latest.startedAt, now)}`;
+    return `⚙️ working since **${formatAgo(latest.startedAt, now)}**`;
   }
 
-  return `🟢 idle · last reply ${formatAgo(latest.endedAt, now)}`;
+  return `🟢 idle · last reply **${formatAgo(latest.endedAt, now)}**`;
 }

package/telegram-plugin/issues-card.ts

@@ -17,7 +17,7 @@
  */
 
 import { readFileSync, writeFileSync } from "node:fs";
-import { escapeMarkdown } from "./card-format.js";
+import { escapeMarkdown, stackCardLines } from "./card-format.js";
 import type { IssueEvent, IssueSeverity } from "../src/issues/index.js";
 
 export interface BotApiForIssuesCard {
@@ -99,26 +99,31 @@ export function renderIssuesCard(opts: RenderIssuesCardOpts): string | null {
   const overflow = sorted.length - visible.length;
 
   const now = opts.now ?? Date.now();
-  const rows = visible.map((e) => {
+  // Build a flat list of SINGLE lines (a row may contribute a head line plus a
+  // remediation line) so stackCardLines can promote every inter-line break to a
+  // GFM hard break — otherwise the rows collapse onto one visual line in the
+  // rich-message renderer (the same bug stackCardLines fixes for status cards).
+  const rowLines: string[] = [];
+  for (const e of visible) {
     const emoji = SEVERITY_EMOJI[e.severity];
     const occ = e.occurrences > 1 ? ` _(×${e.occurrences})_` : "";
     const ago = relTime(now - e.last_seen);
-    const head = `${emoji} \`${e.fingerprint}\`  ${escapeMarkdown(e.summary)}${occ} — _${ago}_`;
+    rowLines.push(`${emoji} \`${e.fingerprint}\`  ${escapeMarkdown(e.summary)}${occ} — _${ago}_`);
     // Render the `detail` line below the summary when present and short
     // enough to be a remediation hint (not a multi-line stderr tail).
     // Convention from the cron prompt template: agents put "Fix: <cmd>"
     // or "→ <cmd>" in detail. Long stderr details are omitted from the
     // card to keep the layout tight; users can run /issues to see them.
     const remediation = formatRemediation(e.detail);
-    return remediation == null ? head : `${head}\n  → _${escapeMarkdown(remediation)}_`;
-  });
+    if (remediation != null) rowLines.push(`  → _${escapeMarkdown(remediation)}_`);
+  }
 
-  const lines = [header, "", ...rows];
+  const lines = [header, "", ...rowLines];
   if (overflow > 0) {
     lines.push("");
     lines.push(`_+${overflow} more not shown — run \`/issues\`_`);
   }
-  return lines.join("\n");
+  return stackCardLines(lines);
 }
 
 /**

package/telegram-plugin/model-unavailable.ts

@@ -27,6 +27,7 @@
  */
 
 import { formatResetRelative } from './quota-check.js'
+import { escapeMarkdown } from './card-format.js'
 
 // ─── Public types ────────────────────────────────────────────────────────────
 
@@ -366,10 +367,10 @@ export function formatModelUnavailableCard(
   opts: FormatCardOptions = {},
 ): string {
   const now = opts.now ?? new Date()
-  const slotPart = opts.slot ? ` (slot **${escHtml(opts.slot)}**)` : ''
+  const slotPart = opts.slot ? ` (slot **${escapeMarkdown(opts.slot)}**)` : ''
   const reason = formatReason(detection, now)
   const lines = [
-    `⚠️ **Model unavailable** on agent **${escHtml(agent)}**${slotPart}`,
+    `⚠️ **Model unavailable** on agent **${escapeMarkdown(agent)}**${slotPart}`,
     `Reason: ${reason}`,
     '',
   ]
@@ -469,7 +470,3 @@ export function resolveModelUnavailableFromOperatorEvent(
 }
 
 // ─── HTML escape (mirrors operator-events.ts) ────────────────────────────────
-
-function escHtml(text: string): string {
-  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
-}

package/telegram-plugin/operator-events.ts

@@ -12,6 +12,8 @@
  *    including the quota-exhausted strings migrated from auto-fallback.ts.
  */
 
+import { escapeMarkdown } from './format.js'
+
 // ─── Taxonomy ────────────────────────────────────────────────────────────────
 
 export type OperatorEventKind =
@@ -210,8 +212,8 @@ export interface RenderResult {
  * `:` or other delimiter characters.
  */
 export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
-  const agent = escHtml(ev.agent)
-  const detail = escHtml(ev.detail)
+  const agent = escapeMarkdown(ev.agent)
+  const detail = escapeMarkdown(ev.detail)
 
   switch (ev.kind) {
     case 'credentials-expired':
@@ -412,7 +414,3 @@ export function resetAllCooldowns(): void {
 }
 
 // ─── Markdown escape (#2669) ──────────────────────────────────────────────────
-
-function escHtml(text: string): string {
-  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
-}

package/telegram-plugin/quota-check.ts

@@ -253,10 +253,10 @@ export function formatQuotaBlock(q: QuotaUtilization, now: Date = new Date()): s
   lines.push("**Claude plan quota**");
   lines.push("");
   lines.push(
-    `**5h window**  ${Math.round(q.fiveHourUtilizationPct)}% · ${formatResetRelative(q.fiveHourResetAt, now)}`,
+    `**5h window**  \`${Math.round(q.fiveHourUtilizationPct)}%\` · \`${formatResetRelative(q.fiveHourResetAt, now)}\``,
   );
   lines.push(
-    `**7d window**  ${Math.round(q.sevenDayUtilizationPct)}% · ${formatResetRelative(q.sevenDayResetAt, now)}`,
+    `**7d window**  \`${Math.round(q.sevenDayUtilizationPct)}%\` · \`${formatResetRelative(q.sevenDayResetAt, now)}\``,
   );
   if (q.representativeClaim) {
     lines.push("");