switchroom 0.18.12 → 0.18.14

package/telegram-plugin/gateway/throttle-tier-wiring.ts

@@ -0,0 +1,268 @@
+/**
+ * throttle-tier-wiring.ts — side-effect runner for the 429 throttle tier.
+ *
+ * The DECISION and notice text live in ../throttle-tier.ts (pure). This
+ * module owns the sequenced side effects, with every dependency injected so
+ * the wiring is unit-testable without importing gateway.ts:
+ *
+ *   1. Broker `mark-throttled` — records `throttled_until` in the quota
+ *      ledger (no roll, no eligibility change) and runs the broker-side
+ *      escalation guard (3 hits / 10 min → live probe → mark-exhausted when
+ *      corroborated). EVERY fire reaches the broker — the notice cooldown
+ *      below never suppresses the ledger write, because the escalation
+ *      counter is what corroborates a wall hiding behind transient wording.
+ *   2. ONE lightweight operator notice — deduped per account BOTH locally
+ *      (cooldown window) and FLEET-WIDE via the broker's claim-notification
+ *      verb (N agents sharing a throttled account produce one copy per chat,
+ *      not N). Claim failures FAIL OPEN (send anyway) per the claim
+ *      contract.
+ *   3. A delayed retry nudge — after `throttled_until` (+slack +jitter so N
+ *      agents don't restart-and-replay simultaneously into the just-cleared
+ *      account), replay the turn the 429 killed via the existing resume
+ *      lever (triggerSelfRestart → boot-resume). Guards, in order:
+ *        - a LIVE turn that started AFTER the throttle was armed supersedes
+ *          the dead turn — skip entirely (restarting would kill live work
+ *          and boot-resume would replay the WRONG turn);
+ *        - a live turn that started BEFORE the arm is the dead turn itself
+ *          still holding the in-flight gate — defer the restart to the
+ *          turn-complete drain (`pendingRestarts`) instead of SIGTERM-now;
+ *        - otherwise consult the SHARED fleet-fallback resume gate
+ *          (single-flight across throttle AND fallback resumes + staleness)
+ *          and restart on a 'resume' verdict.
+ *
+ * The escalated outcome (broker corroborated a wall and already rolled)
+ * posts its own announcement — gateway-side, per the reactive-path doctrine
+ * (`LastFleetRoll` docstring in src/auth/broker/server.ts), which also
+ * covers PINNED (non-fleet-active) account rolls — then nudges the resume
+ * immediately through the same turn-safety guards.
+ */
+
+import {
+  evaluateThrottleNotice,
+  renderThrottleEscalationNotice,
+  renderThrottleNotice,
+  THROTTLE_NOTICE_COOLDOWN_MS,
+  type ThrottleNoticeState,
+} from '../throttle-tier.js'
+
+/** Slack past throttled_until before the retry nudge fires. */
+export const THROTTLE_RETRY_NUDGE_SLACK_MS = 5_000
+
+/** Max random jitter added to the nudge so agents sharing the throttled
+ *  account stagger their restart-and-replay instead of stampeding the
+ *  just-cleared account. */
+export const THROTTLE_RETRY_NUDGE_JITTER_MAX_MS = 30_000
+
+/** The narrow broker surface the runner needs (structurally satisfied by
+ *  the gateway's AuthBrokerClient). */
+export interface ThrottleBrokerClient {
+  markThrottled(until: number): Promise<{
+    account: string
+    throttled_until: number
+    escalated: boolean
+    rolledTo?: string | null
+  }>
+  claimNotification(key: string, windowMs: number): Promise<{ granted: boolean }>
+}
+
+export interface ThrottleTierRunnerDeps {
+  /** This gateway's own agent (SWITCHROOM_AGENT_NAME). */
+  agentName: string
+  getBrokerClient(): Promise<ThrottleBrokerClient | null>
+  /** Chats the notice broadcasts to (access.allowFrom, resolved per call). */
+  listNoticeChats(): Array<string | number>
+  /** Fire-and-forget rich send (gateway wraps swallowingApiCall). */
+  sendNotice(chatId: string | number, markdown: string): void
+  /** THE shared fleet-fallback resume gate (single-flight + staleness). */
+  resumeDecide(failedTurnStartedAtMs: number | null): 'resume' | 'skip-inflight' | 'skip-stale'
+  newestActiveTurnStartedAtMs(): number | null
+  /** True while a turn is in flight (gateway turnInFlightForGate()). */
+  turnInFlight(): boolean
+  /** Defer the restart to the turn-complete drain (pendingRestarts). */
+  deferRestartToTurnComplete(agentName: string, reason: string): void
+  /** Restart now (gateway triggerSelfRestart). */
+  restartNow(agentName: string, reason: string): void
+  log(msg: string): void
+  now?: () => number
+  /** Timer seam (tests drive synchronously). Default setTimeout+unref. */
+  schedule?: (fn: () => void, ms: number) => { cancel(): void }
+  /** Jitter source (tests pin it). Default uniform 0..JITTER_MAX. */
+  jitterMs?: () => number
+}
+
+export interface ThrottleTierRunner {
+  /**
+   * Run the throttle path for one terminal transient 429. Fire-and-forget
+   * from the caller's perspective — never throws.
+   */
+  fire(triggerAgent: string, throttledUntilMs: number, resetParsed: boolean): Promise<void>
+  /** Test/debug view of internal state. */
+  inspect(): { noticeState: ThrottleNoticeState; nudgePending: boolean }
+}
+
+export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): ThrottleTierRunner {
+  const now = deps.now ?? (() => Date.now())
+  const schedule =
+    deps.schedule ??
+    ((fn: () => void, ms: number) => {
+      const t = setTimeout(fn, ms)
+      if (typeof t.unref === 'function') t.unref()
+      return { cancel: () => clearTimeout(t) }
+    })
+  const jitterMs =
+    deps.jitterMs ?? (() => Math.floor(Math.random() * THROTTLE_RETRY_NUDGE_JITTER_MAX_MS))
+
+  let noticeState: ThrottleNoticeState = { lastSentAtMsByAccount: {} }
+  /** The LATEST throttle owns the nudge — a newer hit replaces an armed
+   *  timer instead of stacking restarts. */
+  let pendingNudge: { cancel(): void } | null = null
+
+  /**
+   * Post `markdown` to every authorized chat, fleet-deduped per chat via the
+   * broker claim verb when a client + account are available. Fail-open: a
+   * claim error or missing broker never drops the notice.
+   */
+  async function broadcastDeduped(
+    client: ThrottleBrokerClient | null,
+    keyPrefix: string,
+    account: string | null,
+    markdown: string,
+  ): Promise<void> {
+    for (const chatId of deps.listNoticeChats()) {
+      let granted = true
+      if (client && account) {
+        try {
+          granted = (
+            await client.claimNotification(
+              `${keyPrefix}:${account}:${chatId}`,
+              THROTTLE_NOTICE_COOLDOWN_MS,
+            )
+          ).granted
+        } catch {
+          granted = true // fail open — a duplicated notice beats a dropped one
+        }
+      }
+      if (granted) {
+        deps.sendNotice(chatId, markdown)
+      } else {
+        deps.log(`[throttle-tier] notice suppressed (fleet claim) chat=${chatId}`)
+      }
+    }
+  }
+
+  /**
+   * Replay the dead turn via restart, with the turn-safety guards (see
+   * module docstring). `armedAtMs` anchors the "newer turn supersedes"
+   * check: a turn that started after the throttle was armed is live user
+   * work, never to be killed for a replay.
+   */
+  function nudgeResume(reason: string, armedAtMs: number): void {
+    const newest = deps.newestActiveTurnStartedAtMs()
+    if (deps.turnInFlight()) {
+      if (newest != null && newest > armedAtMs) {
+        deps.log(
+          `[throttle-tier] resume skipped (superseded by a live newer turn) reason=${reason}`,
+        )
+        return
+      }
+      // The in-flight gate is held by the dead throttled turn itself —
+      // defer to the turn-complete drain instead of SIGTERM-ing now.
+      deps.log(`[throttle-tier] resume deferred to turn-complete reason=${reason}`)
+      deps.deferRestartToTurnComplete(deps.agentName, reason)
+      return
+    }
+    const verdict = deps.resumeDecide(newest)
+    if (verdict === 'resume') {
+      deps.log(`[throttle-tier] resuming dead turn via self-restart reason=${reason}`)
+      deps.restartNow(deps.agentName, reason)
+    } else {
+      deps.log(`[throttle-tier] resume suppressed (${verdict}) reason=${reason}`)
+    }
+  }
+
+  async function fire(
+    triggerAgent: string,
+    throttledUntilMs: number,
+    resetParsed: boolean,
+  ): Promise<void> {
+    const armedAtMs = now()
+    let client: ThrottleBrokerClient | null = null
+    let account: string | null = null
+    let escalated = false
+    let rolledTo: string | null = null
+    try {
+      client = await deps.getBrokerClient()
+      if (client) {
+        const r = await client.markThrottled(throttledUntilMs)
+        account = r.account
+        escalated = r.escalated
+        rolledTo = r.rolledTo ?? null
+      } else {
+        deps.log(
+          `[throttle-tier] broker unreachable — notice only, no ledger record agent=${triggerAgent}`,
+        )
+      }
+    } catch (err) {
+      deps.log(
+        `[throttle-tier] markThrottled failed agent=${triggerAgent}: ${(err as Error)?.message ?? err}`,
+      )
+    }
+
+    if (escalated) {
+      // The broker corroborated a genuine wall via a live probe and already
+      // ran mark-exhausted + roll (fleet active AND pinned accounts alike).
+      // The RAISING gateway announces — reactive-path doctrine — fleet-
+      // deduped so N gateways sharing the account produce one copy per chat.
+      deps.log(
+        `[throttle-tier] escalated to wall account=${account ?? '?'} ` +
+          `rolledTo=${rolledTo ?? 'none (all blocked)'}`,
+      )
+      await broadcastDeduped(
+        client,
+        'throttle-escalation',
+        account,
+        renderThrottleEscalationNotice({ account, agent: triggerAgent, rolledTo }),
+      )
+      if (rolledTo) nudgeResume('throttle-escalation-resume', armedAtMs)
+      return
+    }
+
+    // ONE lightweight notice, deduped per account: locally by cooldown, then
+    // fleet-wide by broker claim. Unknown account (broker down) keys the
+    // local cooldown on the agent so the degraded path still can't spam.
+    const cooldownKey = account ?? `agent:${triggerAgent}`
+    const verdict = evaluateThrottleNotice(noticeState, cooldownKey, now())
+    if (verdict.send) {
+      noticeState = verdict.next
+      await broadcastDeduped(
+        client,
+        'throttle-notice',
+        account,
+        renderThrottleNotice({
+          account,
+          agent: triggerAgent,
+          throttledUntilMs,
+          resetParsed,
+          now: new Date(now()),
+        }),
+      )
+    } else {
+      deps.log(`[throttle-tier] notice suppressed (cooldown) key=${cooldownKey}`)
+    }
+
+    // Arm (or re-arm) the retry nudge: slack past the reset + jitter so
+    // agents sharing the account stagger their replays.
+    const delayMs =
+      Math.max(throttledUntilMs - now(), 0) + THROTTLE_RETRY_NUDGE_SLACK_MS + jitterMs()
+    if (pendingNudge) pendingNudge.cancel()
+    pendingNudge = schedule(() => {
+      pendingNudge = null
+      nudgeResume('throttle-retry-resume', armedAtMs)
+    }, delayMs)
+  }
+
+  return {
+    fire,
+    inspect: () => ({ noticeState, nudgePending: pendingNudge != null }),
+  }
+}

package/telegram-plugin/history.ts

@@ -108,6 +108,25 @@ export interface RecordedMessage {
    * Only emoji reactions are tracked — custom emoji are ignored for v1.
    */
   user_reaction: string | null
+  /**
+   * Set when the inbound user message was FORWARDED: the server-stamped
+   * `forward_origin` of the original message (Bot API 7.0+), so
+   * get_recent_messages can surface who originally sent the content the
+   * agent saw at delivery time. `forwarded_from` is the raw (truncated,
+   * unescaped) human-readable name/title; `forwarded_from_type` is
+   * user|hidden_user|chat|channel (hidden_user = self-reported display
+   * name, no verifiable id); `forwarded_from_id` is the numeric id when
+   * the origin shape exposes one; `forwarded_date` is the original
+   * message's ISO timestamp; `forwarded_message_id` is the message id
+   * inside the origin channel (channel origins only). For a multi-origin
+   * coalesced burst only the PRIMARY (first) origin is persisted here —
+   * origins 2+ exist only in the delivered channel tag's numbered attrs.
+   */
+  forwarded_from: string | null
+  forwarded_from_type: string | null
+  forwarded_from_id: string | null
+  forwarded_date: string | null
+  forwarded_message_id: number | null
 }
 
 export interface QueryOptions {
@@ -166,10 +185,20 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     CREATE INDEX IF NOT EXISTS idx_messages_recent
       ON messages (chat_id, thread_id, ts DESC)
   `)
-  // Migration: add reply_to columns to existing DBs that pre-date issue #119.
-  // SQLite has no IF NOT EXISTS for ALTER TABLE ADD COLUMN, so we tolerate
-  // "duplicate column name" errors and re-throw anything else.
-  for (const column of ["reply_to_message_id INTEGER", "reply_to_text TEXT", "user_reaction TEXT"]) {
+  // Migration: add reply_to columns to existing DBs that pre-date issue #119,
+  // and the forwarded_* origin columns (forward_origin metadata) to DBs that
+  // pre-date them. SQLite has no IF NOT EXISTS for ALTER TABLE ADD COLUMN, so
+  // we tolerate "duplicate column name" errors and re-throw anything else.
+  for (const column of [
+    "reply_to_message_id INTEGER",
+    "reply_to_text TEXT",
+    "user_reaction TEXT",
+    "forwarded_from TEXT",
+    "forwarded_from_type TEXT",
+    "forwarded_from_id TEXT",
+    "forwarded_date TEXT",
+    "forwarded_message_id INTEGER",
+  ]) {
     try {
       db.exec(`ALTER TABLE messages ADD COLUMN ${column}`)
     } catch (err) {
@@ -178,6 +207,57 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     }
   }
 
+  // Migration (review finding H5): make INSERT OR REPLACE idempotent for thread-less rows.
+  //
+  // The table's PRIMARY KEY is (chat_id, thread_id, message_id), but thread_id
+  // is nullable and SQLite treats NULL as DISTINCT from NULL in a PK/UNIQUE
+  // index. Every DM and every non-topic group message has thread_id = NULL, so
+  // two inserts of the same (chat_id, message_id) with NULL thread do NOT
+  // conflict — `INSERT OR REPLACE` APPENDS a duplicate row instead of replacing
+  // it. On the documented at-least-once boot replay / synthesized-resume
+  // re-record, an already-stored message is duplicated, inflating
+  // get_recent_messages and the getRecentOutboundCount / hasOutboundDeliveredSince
+  // counters that feed the silence / over-ping detectors.
+  //
+  // Fix: a UNIQUE index over COALESCE(thread_id, '') gives every logical
+  // (chat, thread-or-general, message_id) key a NON-null uniqueness value, so
+  // REPLACE conflict-resolves and dedupes thread-less rows too. INSERT OR
+  // REPLACE resolves against ANY unique index, so no writer change is needed.
+  // A forum-topic row (non-null thread) and a general row (NULL thread) that
+  // share a message_id keep DISTINCT keys (the topic id vs ''), so they stay
+  // separate. Stored thread_id values remain real NULLs, so every read path
+  // (`thread_id IS NULL` / `thread_id = ?`) is unchanged.
+  const LOGICAL_KEY_INDEX = 'idx_messages_logical_key'
+  const logicalKeyIndexExists =
+    db
+      .prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?`)
+      .get(LOGICAL_KEY_INDEX) != null
+  if (!logicalKeyIndexExists) {
+    // De-dupe rows an earlier (pre-fix) build already appended, keeping the
+    // NEWEST row per logical key (highest ts, then highest rowid = the last
+    // write, which is what INSERT OR REPLACE would have left). This MUST run
+    // before the UNIQUE index is created, or CREATE UNIQUE INDEX would fail on
+    // the existing duplicates. On a fresh/empty DB it is a harmless no-op.
+    db.exec(`
+      DELETE FROM messages
+      WHERE rowid NOT IN (
+        SELECT keep_rowid FROM (
+          SELECT rowid AS keep_rowid,
+                 ROW_NUMBER() OVER (
+                   PARTITION BY chat_id, COALESCE(thread_id, ''), message_id
+                   ORDER BY ts DESC, rowid DESC
+                 ) AS rn
+          FROM messages
+        )
+        WHERE rn = 1
+      )
+    `)
+    db.exec(
+      `CREATE UNIQUE INDEX IF NOT EXISTS ${LOGICAL_KEY_INDEX} ` +
+        `ON messages (chat_id, COALESCE(thread_id, ''), message_id)`,
+    )
+  }
+
   // 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.
@@ -298,6 +378,19 @@ interface RecordInboundArgs {
    */
   reply_to_message_id?: number | null | undefined
   reply_to_text?: string | null | undefined
+  /**
+   * If the message was forwarded, the server-stamped origin metadata
+   * (Bot API 7.0 `forward_origin`). Populated from
+   * `ctx.message.forward_origin` in the gateway handler. `forwarded_from`
+   * is the RAW (truncated, unescaped) name — the XML-escaped form goes to
+   * the channel meta only. `forwarded_date` is the origin message's ISO
+   * timestamp; `forwarded_message_id` is set for channel origins only.
+   */
+  forwarded_from?: string | null | undefined
+  forwarded_from_type?: string | null | undefined
+  forwarded_from_id?: string | null | undefined
+  forwarded_date?: string | null | undefined
+  forwarded_message_id?: number | null | undefined
 }
 
 /**
@@ -313,8 +406,8 @@ export function recordInbound(args: RecordInboundArgs): void {
   if (args.message_id == null) return
   const stmt = requireDb().prepare(`
     INSERT OR REPLACE INTO messages
-      (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id, reply_to_message_id, reply_to_text)
-    VALUES (?, ?, ?, 'user', ?, ?, ?, ?, ?, NULL, ?, ?)
+      (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id, reply_to_message_id, reply_to_text, forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date, forwarded_message_id)
+    VALUES (?, ?, ?, 'user', ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?)
   `)
   // Defense-in-depth: never persist a detected secret to the message store.
   // The inbound gate (server.ts handleInbound) already deletes + vaults a
@@ -331,6 +424,13 @@ export function recordInbound(args: RecordInboundArgs): void {
     args.attachment_kind ?? null,
     args.reply_to_message_id ?? null,
     args.reply_to_text != null ? redact(args.reply_to_text) : (args.reply_to_text ?? null),
+    // Origin names/titles are user-controlled display strings; run them
+    // through the same secret-redaction backstop as message text.
+    args.forwarded_from != null ? redact(args.forwarded_from) : null,
+    args.forwarded_from_type ?? null,
+    args.forwarded_from_id ?? null,
+    args.forwarded_date ?? null,
+    args.forwarded_message_id ?? null,
   )
 }
 

package/telegram-plugin/inline-keyboard-callbacks.ts

@@ -30,6 +30,7 @@
 
 import {
   validateInlineKeyboard,
+  TELEGRAM_BUTTON_LIMITS,
   type AnyButton,
   type ButtonValidationError,
 } from './telegram-button-constraints.js'
@@ -114,6 +115,99 @@ export function wrapAgentCallbacks(keyboard: AnyButton[][]): AnyButton[][] {
   )
 }
 
+/**
+ * Redact agent-authored free-text on an inline keyboard BEFORE it is sent to
+ * Telegram (#3148 fast-follow secret-scrub coverage). `wrapAgentCallbacks`
+ * rewrites only `callback_data`; the visible `text` label, the `ack_text`
+ * toast, and any `copy_text.text` clipboard payload pass through VERBATIM. An
+ * agent that puts a secret in any of those transmits it unmasked, and it
+ * resurfaces on tap — the label is echoed back (`button_text`), re-rendered in
+ * the "✅ You chose: <label>" annotation (#789), and `ack_text` is shown as the
+ * toast. `switch_inline_query` / `switch_inline_query_current_chat` /
+ * `switch_inline_query_chosen_chat.query` are also agent-authored free text
+ * that Telegram pastes into a chat's input box on tap (the current chat for
+ * the `_current_chat` variant, a user-picked chat for `_chosen_chat` — both
+ * user-visible), so they carry the same leak class. Route every one of these free-text fields
+ * through the SAME outbound redactor the reply `text` body uses, at the
+ * outbound boundary, so every downstream resurface reads already-masked bytes.
+ *
+ * `callback_data` is the routing key and is NEVER touched — redacting it would
+ * break tap round-tripping. Button structure/order is preserved; the redactor
+ * (`redact()`) only replaces detected secret byte-ranges with a non-empty
+ * marker, so it never empties a label (the non-empty-text invariant holds).
+ * Returns a fresh keyboard; does not mutate the input. `redactFn` is injected
+ * so this stays pure + unit-testable and carries no gateway import cycle.
+ *
+ * Only agent-authored keyboards flow through here (the `reply` tool path);
+ * framework-internal keyboards (approval cards, vault wizard, model menus) are
+ * built separately and are NOT redacted by this function.
+ */
+export function redactAgentKeyboard(
+  keyboard: AnyButton[][],
+  redactFn: (s: string) => string,
+): AnyButton[][] {
+  // The keyboard is validated for length BEFORE redaction, but the redaction
+  // marker (`[REDACTED:...]`) can be longer than the secret it replaces, so a
+  // field that was within a Telegram cap can exceed it after masking. An
+  // over-limit button field makes sendMessage 400 → the WHOLE reply is dropped
+  // (worse than the leak we just closed), so clamp each masked free-text field
+  // to its cap. Truncating a marker is harmless — it's already non-secret.
+  const clamp = (s: string, max: number): string =>
+    s.length > max ? s.slice(0, max) : s
+  return keyboard.map((row) =>
+    row.map((btn) => {
+      const out: AnyButton = { ...btn }
+      if (typeof out.text === 'string') {
+        out.text = clamp(redactFn(out.text), TELEGRAM_BUTTON_LIMITS.TEXT_MAX)
+      }
+      // ack_text is a switchroom-side toast (answerCallbackQuery), not a
+      // sendMessage field, so an over-length value can't drop the reply — no
+      // clamp needed, but redact it all the same.
+      if (typeof out.ack_text === 'string') out.ack_text = redactFn(out.ack_text)
+      // switch_inline_query* paste agent free text into a chat input box on tap
+      // — same leak class as the label. URL-class fields (url/web_app/login_url)
+      // are deliberately left exact: a [REDACTED] marker would corrupt a URL.
+      const siq = (out as { switch_inline_query?: unknown }).switch_inline_query
+      if (typeof siq === 'string') {
+        (out as { switch_inline_query?: string }).switch_inline_query = clamp(
+          redactFn(siq), TELEGRAM_BUTTON_LIMITS.SWITCH_INLINE_QUERY_MAX)
+      }
+      const siqc = (out as { switch_inline_query_current_chat?: unknown })
+        .switch_inline_query_current_chat
+      if (typeof siqc === 'string') {
+        (out as { switch_inline_query_current_chat?: string })
+          .switch_inline_query_current_chat = clamp(
+            redactFn(siqc), TELEGRAM_BUTTON_LIMITS.SWITCH_INLINE_QUERY_MAX)
+      }
+      // switch_inline_query_chosen_chat.query is the third variant: agent free
+      // text pasted into a user-picked chat's input box on tap — same leak class.
+      const cc = (out as { switch_inline_query_chosen_chat?: unknown })
+        .switch_inline_query_chosen_chat
+      if (cc != null && typeof cc === 'object' &&
+          typeof (cc as { query?: unknown }).query === 'string') {
+        (out as { switch_inline_query_chosen_chat?: Record<string, unknown> })
+          .switch_inline_query_chosen_chat = {
+            ...(cc as Record<string, unknown>),
+            query: clamp(
+              redactFn((cc as { query: string }).query),
+              TELEGRAM_BUTTON_LIMITS.SWITCH_INLINE_QUERY_MAX),
+          }
+      }
+      const ct = out.copy_text
+      if (ct != null && typeof ct === 'object' &&
+          typeof (ct as { text?: unknown }).text === 'string') {
+        out.copy_text = {
+          ...(ct as Record<string, unknown>),
+          text: clamp(
+            redactFn((ct as { text: string }).text),
+            TELEGRAM_BUTTON_LIMITS.COPY_TEXT_MAX),
+        }
+      }
+      return out
+    }),
+  )
+}
+
 /**
  * Extract per-button {@link AgentButtonMeta} from a raw (pre-wrap)
  * keyboard. Returns a map keyed by the raw (unprefixed) callback_data

package/telegram-plugin/model-unavailable.ts

@@ -31,7 +31,20 @@ import { escapeMarkdown } from './card-format.js'
 
 // ─── Public types ────────────────────────────────────────────────────────────
 
-export type ModelUnavailableKind = 'overload' | 'quota_exhausted' | 'network'
+export type ModelUnavailableKind =
+  | 'overload'
+  | 'quota_exhausted'
+  | 'network'
+  /**
+   * 429 throttle tier — a TRANSIENT per-account 429 (explicit
+   * `transientUpstreamSignals` negation wording) whose parsed reset lies
+   * BEYOND the retry-in-place threshold, so the gateway escalates it to the
+   * standard mark-exhausted + fleet-failover machinery. Never produced by
+   * `detectModelUnavailable` (a transient-negation string classifies as
+   * `overload` there); constructed only by the gateway's throttle-tier
+   * branch so the card names the true cause instead of "quota exhausted".
+   */
+  | 'rate_limited'
 
 export interface ModelUnavailableDetection {
   kind: ModelUnavailableKind
@@ -41,6 +54,44 @@ export interface ModelUnavailableDetection {
   raw: string
 }
 
+// ─── Transient-burst signals (canonical, single source of truth) ─────────────
+
+/**
+ * Explicit markers of a TRANSIENT per-account burst / server-side throttle —
+ * a short-term RPM/burst 429 that Claude Code retries internally with backoff,
+ * NOT the 5h/7d subscription usage-limit wall. Anthropic emits these with a
+ * `rate_limit_error` whose wording explicitly NEGATES the account-quota reading
+ * ("not your usage limit" / "would exceed your account's rate limit … try again
+ * later"). Keyed on the explicit negation so a genuine wall that merely contains
+ * the word "limit" is never down-classified.
+ *
+ * Exported so `session-tail.ts` classifies a 429 by wording against THIS list
+ * rather than hand-rolling its own copy (keeps the two in sync — issue #2922).
+ */
+export const transientUpstreamSignals = [
+  'not your usage limit',
+  'not your account',
+  "not your account's",
+  'temporarily limiting requests',
+  'temporarily rate',
+  'server is temporarily',
+  'would exceed your account’s rate limit',
+  "would exceed your account's rate limit",
+]
+
+/**
+ * True when `text` carries an EXPLICIT transient-burst marker (see
+ * `transientUpstreamSignals`). Never throws on weird input. Used to keep the
+ * calm rate-limit path and the model-unavailable detector reading the same
+ * canonical signal list.
+ */
+export function isTransientUpstreamSignal(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+  return transientUpstreamSignals.some(s => lower.includes(s))
+}
+
 // ─── Detection ───────────────────────────────────────────────────────────────
 
 /**
@@ -77,17 +128,9 @@ export function detectModelUnavailable(
   // failover that self-cancels and leaves the turn dead. These are upstream
   // throttles Claude Code retries internally with backoff — classify them as
   // `overload` (the calm rate-limit path) BEFORE the quota substrings run, so
-  // the negation is honoured and no failover is announced.
-  const transientUpstreamSignals = [
-    'not your usage limit',
-    'not your account',
-    "not your account's",
-    'temporarily limiting requests',
-    'temporarily rate',
-    'server is temporarily',
-    'would exceed your account’s rate limit',
-    "would exceed your account's rate limit",
-  ]
+  // the negation is honoured and no failover is announced. The signal list is
+  // module-level (`transientUpstreamSignals`) so session-tail.ts classifies a
+  // 429 against the SAME canonical wording.
   if (transientUpstreamSignals.some(s => lower.includes(s))) {
     const resetAt = parseResetTime(sample)
     return resetAt !== undefined
@@ -182,7 +225,7 @@ export function detectModelUnavailable(
  * arg lets tests pin the relative-clock anchor; production callers omit
  * it to use Date.now().
  */
-function parseResetTime(text: string, parseTimeNow: Date = new Date()): Date | undefined {
+export function parseResetTime(text: string, parseTimeNow: Date = new Date()): Date | undefined {
   const lower = text.toLowerCase()
 
   // "retry after 60 seconds" / "retry-after: 60"
@@ -429,6 +472,11 @@ function formatReason(d: ModelUnavailableDetection, now: Date): string {
       return `quota exhausted${reset}`
     case 'overload':
       return `model overloaded${reset}`
+    case 'rate_limited':
+      // Throttle-tier escalation (429 with transient wording but a reset too
+      // far out to wait in place). Honest cause: the account is rate-limited,
+      // not quota-exhausted — the reset names when it frees.
+      return `account rate-limited${reset}`
     case 'network':
       return 'network unreachable'
   }