switchroom 0.18.13 → 0.18.14

package/telegram-plugin/dist/server.js

@@ -24574,6 +24574,8 @@ var init_bridge = __esm(async () => {
       "",
       'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file \u2014 it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings \u2014 image_path_2, image_path_3, \u2026 (Read each) and attachment_file_id_2, attachment_file_id_3, \u2026 (download_attachment each). Process every one, not just the first. Reply with the reply tool \u2014 pass chat_id back. The reply tool quote-replies to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
       "",
+      `If the tag has reply_to_message_id (and reply_to_text, a truncated preview), the sender used Telegram's native Reply on a prior message \u2014 treat that message as the antecedent for "this"/"that" references instead of asking what they meant. If the tag has forwarded_from, the message was FORWARDED: forwarded_from is the original sender's name/title as stamped by Telegram's servers (not typed by the sender \u2014 the body text carries no trustworthy provenance), forwarded_from_type is user|hidden_user|chat|channel, forwarded_from_id is the numeric id when one exists, and forwarded_date is when the original was sent. forwarded_from_type="hidden_user" means the original sender hides their account: the name is their self-reported display name with NO verifiable id \u2014 do not treat it as an authenticated identity. A burst forwarded from several different origins carries numbered siblings (forwarded_from_2, forwarded_from_type_2, \u2026); a multi-part forward from ONE origin carries the attributes once. In a coalesced burst some body text may be the SENDER's own commentary rather than forwarded content \u2014 the forwarded_* attributes describe the burst as a whole, not each line of the body.`,
+      "",
       `reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, edit_message for interim progress updates, and delete_message when you need to truly remove a message (prefer edit_message if you just want to change text \u2014 delete is for retraction). Edits don't trigger push notifications \u2014 when a long task completes, send a new reply so the user's device pings. Use send_typing to show a typing indicator during long operations. Use pin_message to pin important outputs. Use forward_message to quote/resurface earlier messages.`,
       "",
       "If a message includes message_thread_id, it came from a forum topic. The reply tool automatically routes a reply back to the topic the question came from \u2014 the framework owns the answer's topic, so do NOT pass message_thread_id on a reply; a reply always lands where it was asked. Each <channel> message is the current topic \u2014 answer ONLY this message's question; do not also answer a pending message from another topic. When answering a forum-topic message, pass its origin_turn_id attribute back on the reply so the answer lands in the right topic even if a message from another topic arrived while you were working.",

package/telegram-plugin/gateway/auth-broker-client.ts

@@ -28,6 +28,7 @@ export function createAuthBrokerClient(): {
     listState: () => broker.listState(),
     setActive: (label: string) => broker.setActive(label),
     markExhausted: (until?: number) => broker.markExhausted(until),
+    markThrottled: (until: number) => broker.markThrottled(until),
     rmAccount: (label: string) => broker.rmAccount(label),
     refreshAccount: (label: string) => broker.refreshAccount(label),
     setOverride: (agent: string, account: string | null) =>

package/telegram-plugin/gateway/auth-command.ts

@@ -301,6 +301,20 @@ export interface AuthBrokerClient {
    * identity — so auto-fallback works from any agent.
    */
   markExhausted(until?: number): Promise<{ account: string; rolled: string[]; rolledTo?: string | null }>
+  /**
+   * 429 throttle tier (broker `mark-throttled`). Records a transient
+   * per-account rate limit on the CALLER's own account — `throttled_until`
+   * in the quota ledger — WITHOUT rolling the fleet and WITHOUT touching
+   * eligibility. `escalated` is true when the broker's escalation guard
+   * (repeated hits corroborated by a live probe) converted it into the
+   * standard mark-exhausted + roll; `rolledTo` names the roll target then.
+   */
+  markThrottled(until: number): Promise<{
+    account: string
+    throttled_until: number
+    escalated: boolean
+    rolledTo?: string | null
+  }>
   rmAccount(label: string): Promise<{ label: string }>
   refreshAccount(label: string): Promise<{ account: string; expiresAt?: number }>
   setOverride(

package/telegram-plugin/gateway/forward-origin.ts

@@ -0,0 +1,235 @@
+/**
+ * Pure helpers for forwarded-message origin metadata — kept out of
+ * `gateway.ts` (same pattern as `coalesce-attachments.ts`) so the parsing,
+ * escaping, and numbered-sibling logic can be unit-tested without the
+ * gateway's `loadAccess()` / IPC machinery.
+ *
+ * When a user forwards a message to the bot, Telegram stamps
+ * `message.forward_origin` SERVER-side (Bot API 7.0+). Unlike the message
+ * body — which the forwarding user fully controls — the origin record
+ * cannot be forged by typing, so it is the trusted lane for "who
+ * originally sent this". The gateway surfaces it to the agent as
+ * `forwarded_*` channel-meta ATTRIBUTES only; origin info is never
+ * injected into the body text, keeping the attacker-influenceable body
+ * and the server-stamped provenance on separate lanes.
+ *
+ * Caveat surfaced via `forwarded_from_type="hidden_user"`: a sender who
+ * enabled forward privacy yields only a self-reported display name with
+ * NO verifiable id — agents can see the name but must not treat it as an
+ * authenticated identity.
+ */
+
+import type { MessageOrigin } from 'grammy/types'
+import { escapeXmlAttribute } from '../steering.js'
+
+/**
+ * Cap on the human-readable origin name/title. Names and titles are
+ * attacker-controlled (a hostile account can set a 4KB display name);
+ * mirror the REPLY_TO_TEXT_MAX truncate-then-escape pattern with a cap
+ * sized for names rather than message previews.
+ */
+export const FORWARDED_FROM_NAME_MAX = 100
+
+export type ForwardOriginType = 'user' | 'hidden_user' | 'chat' | 'channel'
+
+/**
+ * Normalized origin record. `name` is RAW (truncated but unescaped) so it
+ * can be persisted verbatim to the SQLite history buffer — the XML
+ * escaping happens at the channel-meta boundary in
+ * `buildForwardOriginMeta`, same split as `replyToText` /
+ * `replyToTextEscaped` in the gateway inbound handler.
+ */
+export interface ForwardOriginInfo {
+  /** Human-readable name/title of the original sender (raw, truncated). */
+  name: string
+  type: ForwardOriginType
+  /** Numeric id when the origin shape exposes one (user id / chat id). */
+  id?: number
+  /** Unix seconds of the original message (`forward_origin.date`). */
+  date?: number
+  /** Channel origins only: the message id inside the origin channel. */
+  messageId?: number
+}
+
+function truncateName(name: string): string {
+  return name.length > FORWARDED_FROM_NAME_MAX
+    ? name.slice(0, FORWARDED_FROM_NAME_MAX - 1) + '…'
+    : name
+}
+
+/** Join first/last name plus a trailing `(@username)` when present. */
+function personName(parts: {
+  first_name?: string
+  last_name?: string
+  username?: string
+}): string {
+  const name = [parts.first_name, parts.last_name]
+    .filter((p): p is string => typeof p === 'string' && p.length > 0)
+    .join(' ')
+  const handle = parts.username ? `(@${parts.username})` : ''
+  return [name, handle].filter((p) => p.length > 0).join(' ')
+}
+
+/** Chat/channel title plus a trailing `(@username)` when present. */
+function chatTitle(chat: {
+  title?: string
+  username?: string
+  first_name?: string
+  last_name?: string
+}): string {
+  // Defensive: `Chat` is a union — groups/channels carry `title`, a
+  // private chat carries first/last name instead. Fall through so a
+  // malformed/unexpected shape still yields whatever name exists.
+  if (chat.title && chat.title.length > 0) {
+    const handle = chat.username ? `(@${chat.username})` : ''
+    return [chat.title, handle].filter((p) => p.length > 0).join(' ')
+  }
+  return personName(chat)
+}
+
+/**
+ * Parse Telegram's `message.forward_origin` into a normalized record.
+ * Returns `undefined` for non-forwarded messages, unknown origin types,
+ * and records so malformed that no human-readable name can be recovered
+ * (the attrs are context, not a gate — degrading to "no origin metadata"
+ * is safe; inventing a name is not).
+ *
+ * Accepts `unknown`-ish input defensively: the origin arrives from the
+ * Telegram wire and future Bot API versions may add origin types this
+ * build doesn't know.
+ */
+export function parseForwardOrigin(
+  origin: MessageOrigin | undefined,
+): ForwardOriginInfo | undefined {
+  if (origin == null || typeof origin !== 'object') return undefined
+  const date = typeof origin.date === 'number' ? origin.date : undefined
+  switch (origin.type) {
+    case 'user': {
+      const u = origin.sender_user
+      if (u == null || typeof u !== 'object') return undefined
+      const name = personName(u)
+      if (name.length === 0) {
+        // No printable name at all — fall back to the (unforgeable) id.
+        if (typeof u.id !== 'number') return undefined
+        return { name: String(u.id), type: 'user', id: u.id, date }
+      }
+      return {
+        name: truncateName(name),
+        type: 'user',
+        ...(typeof u.id === 'number' ? { id: u.id } : {}),
+        date,
+      }
+    }
+    case 'hidden_user': {
+      // Forward-privacy senders: `sender_user_name` is a SELF-REPORTED
+      // display name with no verifiable id. The `hidden_user` type marker
+      // is the agent's signal to treat the name as unauthenticated.
+      const name = typeof origin.sender_user_name === 'string'
+        ? origin.sender_user_name
+        : ''
+      if (name.length === 0) return undefined
+      return { name: truncateName(name), type: 'hidden_user', date }
+    }
+    case 'chat': {
+      const c = origin.sender_chat
+      if (c == null || typeof c !== 'object') return undefined
+      const name = chatTitle(c)
+      if (name.length === 0) {
+        if (typeof c.id !== 'number') return undefined
+        return { name: String(c.id), type: 'chat', id: c.id, date }
+      }
+      return {
+        name: truncateName(name),
+        type: 'chat',
+        ...(typeof c.id === 'number' ? { id: c.id } : {}),
+        date,
+      }
+    }
+    case 'channel': {
+      const c = origin.chat
+      if (c == null || typeof c !== 'object') return undefined
+      const name = chatTitle(c)
+      const messageId = typeof origin.message_id === 'number' ? origin.message_id : undefined
+      if (name.length === 0) {
+        if (typeof c.id !== 'number') return undefined
+        return { name: String(c.id), type: 'channel', id: c.id, date, messageId }
+      }
+      return {
+        name: truncateName(name),
+        type: 'channel',
+        ...(typeof c.id === 'number' ? { id: c.id } : {}),
+        date,
+        messageId,
+      }
+    }
+    default:
+      // Unknown future origin type — no metadata beats wrong metadata.
+      return undefined
+  }
+}
+
+/**
+ * Identity key for burst dedup: same-typed origins with the same id are
+ * one origin; id-less shapes (hidden_user) fall back to the name.
+ */
+export function forwardOriginKey(o: ForwardOriginInfo): string {
+  return o.id != null ? `${o.type}:${o.id}` : `${o.type}:${o.name}`
+}
+
+/**
+ * Collapse the per-message origins of a coalesced burst into the DISTINCT
+ * origins in arrival order. A 10-part album forwarded from one channel
+ * yields ONE origin (attrs emitted once); a burst mixing forwards from two
+ * different senders yields two (the second gets `forwarded_from_2` etc.).
+ * Non-forwarded entries (`undefined`) are skipped. First occurrence wins,
+ * so the emitted `forwarded_date` is the first message's origin date.
+ */
+export function dedupeForwardOrigins(
+  origins: Array<ForwardOriginInfo | undefined>,
+): ForwardOriginInfo[] {
+  const seen = new Set<string>()
+  const out: ForwardOriginInfo[] = []
+  for (const o of origins) {
+    if (o == null) continue
+    const key = forwardOriginKey(o)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(o)
+  }
+  return out
+}
+
+/**
+ * Build the `forwarded_*` channel-meta fields. Fixed per-origin attribute
+ * order (documented here, tested in forward-origin.test.ts):
+ *   forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date
+ * The primary field is the human-readable NAME; the numeric id is
+ * supplementary and follows it. The first origin gets the bare keys;
+ * subsequent distinct origins get `_2`, `_3`, … suffixes — the same
+ * numbered-sibling convention as `image_path_2` / `attachment_file_id_2`.
+ *
+ * Names/titles are attacker-controlled, so every value that can carry
+ * user text goes through `escapeXmlAttribute` (the same escaper
+ * `formatReplyToText` uses) before landing in the channel tag.
+ */
+export function buildForwardOriginMeta(
+  origins: ForwardOriginInfo[],
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  origins.forEach((o, i) => {
+    const suffix = i === 0 ? '' : `_${i + 1}`
+    out[`forwarded_from${suffix}`] = escapeXmlAttribute(truncateName(o.name))
+    out[`forwarded_from_type${suffix}`] = o.type
+    if (o.id != null) out[`forwarded_from_id${suffix}`] = String(o.id)
+    if (o.date != null) {
+      out[`forwarded_date${suffix}`] = new Date(o.date * 1000).toISOString()
+    }
+  })
+  return out
+}
+
+/** ISO form of an origin date for the SQLite history record. */
+export function forwardOriginDateIso(o: ForwardOriginInfo | undefined): string | null {
+  if (o?.date == null) return null
+  return new Date(o.date * 1000).toISOString()
+}

package/telegram-plugin/gateway/gateway.ts

@@ -94,6 +94,13 @@ import {
   buildExtraAttachmentMeta,
   resolveCoalesceMaxAttachments,
 } from './coalesce-attachments.js'
+import {
+  parseForwardOrigin,
+  dedupeForwardOrigins,
+  buildForwardOriginMeta,
+  forwardOriginDateIso,
+  type ForwardOriginInfo,
+} from './forward-origin.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { DeferredDoneReactions } from '../reaction-defer.js'
 import { createWorkerActivityFeed, isWorkerActivityFeedEnabled } from '../worker-activity-feed.js'
@@ -310,7 +317,14 @@ import { recordOperatorEvent } from '../operator-events-history.js'
 import {
   formatModelUnavailableCard,
   resolveModelUnavailableFromOperatorEvent,
+  type ModelUnavailableDetection,
 } from '../model-unavailable.js'
+import {
+  decideThrottleTier,
+  isAccountScopedThrottle,
+  throttleRetryInPlaceMaxMs,
+} from '../throttle-tier.js'
+import { createThrottleTierRunner } from './throttle-tier-wiring.js'
 import { runFleetAutoFallback, renderFallbackFailureNotice, evaluateFallbackFailureNotice, evaluateAllBlockedNotice, type FallbackFailureNoticeState, type FallbackAllBlockedNoticeState } from '../auto-fallback-fleet.js'
 import { startRestartWatchdog } from './restart-watchdog.js'
 import { validateStringArray } from './access-validator.js'
@@ -7587,6 +7601,14 @@ type CoalescePayload = {
   attachment?: AttachmentMeta
   // Set only by `merge`: the 2nd..Nth attachments folded into this turn.
   extraAttachments?: CoalesceAttachment[]
+  // Forwarded-message origin of THIS entry (parsed at enqueue time from
+  // message.forward_origin). merged.ctx is the LAST entry's ctx, so a
+  // coalesced burst would otherwise lose the earlier entries' origins —
+  // each entry carries its own.
+  forwardOrigin?: ForwardOriginInfo
+  // Set only by `merge`: the distinct origins of the whole burst, arrival
+  // order, deduped (a single-origin album collapses to one entry).
+  forwardOrigins?: ForwardOriginInfo[]
 }
 
 // Count of attachment-bearing entries currently buffered per coalesce key.
@@ -7619,6 +7641,11 @@ const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
       (e) => e.downloadImage != null || e.attachment != null,
       coalesceMaxAttachments(),
     )
+    // Distinct forwarded-message origins across the burst, arrival order.
+    // A forwarded album (one origin, N parts) collapses to a single entry
+    // so the attrs are emitted once; a burst forwarded from two different
+    // senders keeps both (numbered forwarded_from_2 siblings downstream).
+    const forwardOrigins = dedupeForwardOrigins(entries.map((e) => e.forwardOrigin))
     return {
       // Drop empty texts (e.g. caption-less album parts) so the join doesn't
       // emit blank lines between attachments.
@@ -7629,6 +7656,7 @@ const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
       extraAttachments: extras.length > 0
         ? extras.map((e) => ({ downloadImage: e.downloadImage, attachment: e.attachment }))
         : undefined,
+      forwardOrigins: forwardOrigins.length > 0 ? forwardOrigins : undefined,
     }
   },
   onFlush: (key, merged) => {
@@ -7639,6 +7667,7 @@ const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
       merged.downloadImage,
       merged.attachment,
       merged.extraAttachments,
+      merged.forwardOrigins,
     )
   },
 })
@@ -7659,6 +7688,72 @@ const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
 function emitGatewayOperatorEvent(event: OperatorEvent): void {
   const { agent, kind } = event
 
+  // ── 429 throttle tier (operator spec: "retry in place under 5 min, else
+  // mark + failover, honest reset messaging") ────────────────────────────
+  // A terminal TRANSIENT ACCOUNT-scoped 429 — kind `rate-limited` carrying
+  // wording that affirms the account's own rate limit ("would exceed your
+  // account's rate limit") — is decided BEFORE the per-kind cooldown gate:
+  // every hit must reach the broker's mark-throttled escalation counter, and
+  // the >threshold failover ACTION must fire, even when the user-facing card
+  // is cooldown-suppressed (a calm 529 card two minutes earlier arms that
+  // cooldown). Server-side transients (529 / "server is temporarily…") fall
+  // through to the existing calm rate-limited card unchanged — an
+  // account-scoped throttle would be the wrong action for a server-wide
+  // condition.
+  let throttleEscalation: ModelUnavailableDetection | null = null
+  let escalationFired = false
+  if (kind === 'rate-limited' && isAccountScopedThrottle(event.detail)) {
+    const throttleDecision = decideThrottleTier({
+      detail: event.detail,
+      now: Date.now(),
+      thresholdMs: throttleRetryInPlaceMaxMs(),
+    })
+    if (throttleDecision.action === 'throttle') {
+      // Reset is near (≤ threshold) or unparseable (60s default): DO NOT
+      // fail over. Record throttled_until broker-side, post ONE lightweight
+      // notice (per-account + fleet-wide dedup), nudge a retry after the
+      // reset. The runner owns the sequencing (throttle-tier-wiring.ts).
+      process.stderr.write(
+        `telegram gateway: throttle-tier staying-put agent=${agent} ` +
+          `until=${new Date(throttleDecision.throttledUntilMs).toISOString()} ` +
+          `parsedReset=${throttleDecision.resetParsed}\n`,
+      )
+      try {
+        recordOperatorEvent(event)
+      } catch { /* history is best-effort */ }
+      void throttleTierRunner.fire(
+        agent,
+        throttleDecision.throttledUntilMs,
+        throttleDecision.resetParsed,
+      )
+      return
+    }
+    if (throttleDecision.action === 'failover') {
+      // Reset beyond the retry-in-place threshold: the account is benched
+      // until then anyway, so escalate to the standard mark-exhausted +
+      // fleet-failover machinery — honest 'rate_limited' wording, parsed
+      // reset as the mark expiry. The ACTION fires HERE, before the
+      // per-kind card cooldown below can swallow it (the fleetFallbackGate
+      // provides the action-level dedup); only the card stays
+      // cooldown-bounded. The 'rate-limit' trigger tells the dispatcher to
+      // trust this terminal parsed-reset signal over the utilization probe
+      // (a transient 429 negates the usage-limit reading, so utilization
+      // typically looks healthy — the idempotency guard would self-cancel
+      // the swap).
+      const resetAt = new Date(throttleDecision.resetAtMs)
+      throttleEscalation = { kind: 'rate_limited', resetAt, raw: event.detail }
+      if (wouldFireFleetAutoFallback()) {
+        escalationFired = true
+        void fireFleetAutoFallback(
+          agent,
+          resolveExhaustUntil(resetAt.getTime()),
+          resetAt,
+          'rate-limit',
+        )
+      }
+    }
+  }
+
   if (!shouldEmitOperatorEvent(agent, kind)) {
     process.stderr.write(
       `telegram gateway: operator-event suppressed (cooldown) agent=${agent} kind=${kind}\n`,
@@ -7687,7 +7782,10 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   //     by the upstream classifier
   //   - detail string contains one of the model-unavailable text patterns
   //     (covers raw stderr that slipped past structured classification)
-  const modelUnavailable = resolveModelUnavailableFromOperatorEvent(event)
+  // Throttle-tier escalation (long-reset transient 429) takes precedence:
+  // resolveModelUnavailableFromOperatorEvent deliberately returns null for a
+  // bare rate-limited event, but this one is auto-fallback-eligible.
+  const modelUnavailable = throttleEscalation ?? resolveModelUnavailableFromOperatorEvent(event)
   let renderedText: string
   let renderedKeyboard: ReturnType<typeof renderOperatorEvent>['keyboard'] | undefined
   // #3031 PR 3 — when the card promises an in-flight auto-failover, record
@@ -7709,8 +7807,18 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     // it just produces a self-cancelling "probed healthy / Stale event?"
     // loop on every 529. Overload is handled by Claude Code's own
     // internal retry, not by switching accounts.
-    const isAutoKind = modelUnavailable.kind === 'quota_exhausted'
-    const willActuallyFire = isAutoKind && wouldFireFleetAutoFallback()
+    // 'rate_limited' is the throttle-tier escalation (transient 429 whose
+    // reset exceeds the retry-in-place threshold) — same failover mechanics
+    // as a quota wall, honest wording on the card. Its fire already happened
+    // ABOVE the cooldown gate (escalationFired) so the action can't be
+    // swallowed by the per-kind card cooldown; the card here only reports it.
+    const isAutoKind =
+      modelUnavailable.kind === 'quota_exhausted' ||
+      modelUnavailable.kind === 'rate_limited'
+    const willActuallyFire =
+      throttleEscalation != null
+        ? escalationFired
+        : isAutoKind && wouldFireFleetAutoFallback()
     process.stderr.write(
       `telegram gateway: operator-event suppressing-raw-stderr-for-model-unavailable agent=${agent} kind=${kind} detected=${modelUnavailable.kind} autoKind=${isAutoKind} willFire=${willActuallyFire}\n`,
     )
@@ -7734,9 +7842,14 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     // Pre-fix this called fireFleetAutoFallback(agent) with no until, so a
     // weekly wall that surfaced as a 429 got markExhausted's ~5h default and
     // the broker re-mirrored the still-walled account onto the fleet after 5h.
-    if (willActuallyFire) {
+    // Throttle-tier escalations (throttleEscalation != null) already fired
+    // above the cooldown gate — don't double-fire here.
+    if (willActuallyFire && throttleEscalation == null) {
       const untilMs = resolveExhaustUntil(modelUnavailable.resetAt?.getTime())
-      void fireFleetAutoFallback(agent, untilMs)
+      // Thread the RAW parsed reset (distinct from the floor-applied untilMs)
+      // so the fallback announcement can name it even when the live probe of
+      // the old account fails — honest reset messaging on the enriched card.
+      void fireFleetAutoFallback(agent, untilMs, modelUnavailable.resetAt)
     }
   } else {
     try {
@@ -11374,7 +11487,13 @@ const ipcServer: IpcServer = createIpcServer({
         (msg.resetAt == null ? ' (reset unparsed → +7d default)' : '') +
         ' — triggering fleet auto-fallback\n',
     )
-    void fireFleetAutoFallback(msg.agentName, untilMs)
+    void fireFleetAutoFallback(
+      msg.agentName,
+      untilMs,
+      // Enriched announcement: the sidecar-parsed reset (when present) keeps
+      // the recovery line honest even when the old account's probe fails.
+      msg.resetAt != null ? new Date(msg.resetAt) : undefined,
+    )
   },
 
   // Issue #2971 — read-only wedge-watchdog probe: is there a live pending
@@ -18070,7 +18189,15 @@ async function handleInboundCoalesced(
     ctx.message?.message_thread_id,
     String(from.id),
   )
-  const result = inboundCoalescer.enqueue(key, { text, ctx, downloadImage, attachment })
+  const result = inboundCoalescer.enqueue(key, {
+    text,
+    ctx,
+    downloadImage,
+    attachment,
+    // Parsed HERE (not in merge) because merge only sees the last ctx —
+    // each buffered entry keeps its own forwarded-message origin.
+    forwardOrigin: parseForwardOrigin(ctx.message?.forward_origin),
+  })
   // Coalescing disabled (window <= 0): flush immediately, preserving any
   // media this message carried.
   if (result.bypass) return handleInbound(ctx, text, downloadImage, attachment)
@@ -18149,6 +18276,11 @@ async function handleInbound(
   // resolved (photos downloaded) and surfaced as numbered meta fields
   // (image_path_2, attachment_file_id_2, …) alongside the primary.
   extraAttachments?: CoalesceAttachment[],
+  // Forwarded-message origins for a coalesced burst (deduped, arrival
+  // order — see the coalescer's merge). Left undefined by the direct /
+  // bypass call sites; handleInbound then parses THIS ctx's
+  // forward_origin itself, so single-message forwards work on every path.
+  coalescedForwardOrigins?: ForwardOriginInfo[],
 ): Promise<void> {
   markIdleActivity() // any inbound resets the idle auto-clear timer + re-arms
   const isTopicMessage = ctx.message?.is_topic_message ?? false
@@ -19367,6 +19499,19 @@ async function handleInbound(
     : undefined
   const replyToTextEscaped = formatReplyToText(replyToTextRaw, REPLY_TO_TEXT_MAX)
 
+  // Forwarded-message origin context. `forward_origin` is stamped by
+  // Telegram's servers (Bot API 7.0+) — the forwarding user cannot forge
+  // it via the message body, so it rides the trusted attrs lane and is
+  // NEVER folded into the body text. Coalesced bursts pass their deduped
+  // per-entry origins; direct/bypass paths parse this ctx's own origin.
+  // Same raw-vs-escaped split as reply_to_text: `forwardOrigins` carries
+  // raw (truncated) names for SQLite, `buildForwardOriginMeta` escapes at
+  // the channel-meta boundary.
+  const forwardOrigins = coalescedForwardOrigins
+    ?? dedupeForwardOrigins([parseForwardOrigin(ctx.message?.forward_origin)])
+  const forwardOriginMeta = buildForwardOriginMeta(forwardOrigins)
+  const primaryForwardOrigin = forwardOrigins[0]
+
   if (HISTORY_ENABLED) {
     try {
       recordInbound({
@@ -19380,6 +19525,11 @@ async function handleInbound(
         attachment_kind: attachment?.kind,
         reply_to_message_id: replyToMessageId ?? null,
         reply_to_text: replyToText ?? null,
+        forwarded_from: primaryForwardOrigin?.name ?? null,
+        forwarded_from_type: primaryForwardOrigin?.type ?? null,
+        forwarded_from_id: primaryForwardOrigin?.id != null ? String(primaryForwardOrigin.id) : null,
+        forwarded_date: forwardOriginDateIso(primaryForwardOrigin),
+        forwarded_message_id: primaryForwardOrigin?.messageId ?? null,
       })
     } catch (err) {
       process.stderr.write(`telegram gateway: history recordInbound failed: ${err}\n`)
@@ -19485,6 +19635,11 @@ async function handleInbound(
       // Use the XML-escaped form for the meta — the raw form is in the
       // SQLite buffer for verbatim retrieval via get_recent_messages.
       ...(replyToTextEscaped != null && replyToTextEscaped.length > 0 ? { reply_to_text: replyToTextEscaped } : {}),
+      // Forwarded-message origin (server-stamped, attrs-only — see above).
+      // forwarded_from / forwarded_from_type / forwarded_from_id /
+      // forwarded_date, plus numbered _2.. siblings for a multi-origin
+      // burst. Names are XML-escaped inside buildForwardOriginMeta.
+      ...forwardOriginMeta,
       // queued="true" when mid-turn with no steer prefix (new default), or
       // with explicit /queue or /q prefix (legacy alias).
       ...((isQueuedMidTurn || isQueuedPrefix) ? { queued: 'true' } : {}),
@@ -23203,9 +23358,14 @@ function wouldFireFleetAutoFallback(): boolean {
  * so the user sees the outcome inline with the original "Model
  * unavailable" card.
  */
-async function fireFleetAutoFallback(triggerAgent: string, untilMs?: number): Promise<void> {
+async function fireFleetAutoFallback(
+  triggerAgent: string,
+  untilMs?: number,
+  parsedResetAt?: Date,
+  trigger?: 'rate-limit',
+): Promise<void> {
   return fleetFallbackGate.fire(
-    () => doFireFleetAutoFallback(triggerAgent, untilMs),
+    () => doFireFleetAutoFallback(triggerAgent, untilMs, parsedResetAt, trigger),
     (err) => {
       process.stderr.write(
         `telegram gateway: [fleet-fallback] error agent=${triggerAgent}: ${(err as Error)?.message ?? err}\n`,
@@ -23214,6 +23374,45 @@ async function fireFleetAutoFallback(triggerAgent: string, untilMs?: number): Pr
   )
 }
 
+// ─── 429 throttle tier — side-effect wiring ─────────────────────────────────
+// Decision + notice text live in throttle-tier.ts (pure); the SEQUENCING
+// (broker mark → fleet-deduped notice → jittered retry nudge with the
+// live-turn safety guards) lives in throttle-tier-wiring.ts so it is
+// unit-testable with injected deps. This block only binds the real gateway
+// dependencies.
+const throttleTierRunner = createThrottleTierRunner({
+  agentName: process.env.SWITCHROOM_AGENT_NAME ?? '',
+  getBrokerClient: () =>
+    getAuthBrokerClient(process.env.SWITCHROOM_AGENT_NAME ?? ''),
+  listNoticeChats: () => loadAccess().allowFrom,
+  sendNotice: (chat_id, markdown) => {
+    // Status notice, not the user's answer — silence the ping (same posture
+    // as the fleet-fallback announcement).
+    void swallowingApiCall(
+      // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy)
+      () => bot.api.sendRichMessage(chat_id, richMessage(markdown), { disable_notification: true }),
+      { chat_id: String(chat_id), verb: 'throttle-tier:notify' },
+    )
+  },
+  resumeDecide: (ts) => fleetFallbackResumeGate.decide(ts),
+  newestActiveTurnStartedAtMs,
+  turnInFlight: () => turnInFlightForGate(),
+  deferRestartToTurnComplete: (agentName, reason) => {
+    // Same lever the schedule_restart IPC uses: the restart drains at the
+    // turn-complete gate (never SIGTERM-now under a live turn). Note the
+    // pending-restart drain cap (PENDING_RESTART_DRAIN_CAP_MS) still bounds
+    // a never-idling session — deliberate, matching scheduled restarts.
+    process.stderr.write(
+      `telegram gateway: [throttle-tier] restart deferred to turn-complete agent=${agentName} reason=${reason}\n`,
+    )
+    pendingRestarts.set(agentName, Date.now())
+  },
+  restartNow: (agentName, reason) => {
+    triggerSelfRestart(agentName, reason)
+  },
+  log: (m) => process.stderr.write(`telegram gateway: ${m}\n`),
+})
+
 /**
  * Broadcast a fleet-fallback FAILURE notice to every authorized chat.
  *
@@ -23275,7 +23474,12 @@ function broadcastFleetFallbackFailure(triggerAgent: string, reason: string): vo
  *  user-visible announcement was broadcast). False on no-op /
  *  error / idempotent-skip — caller uses this to decide whether to
  *  arm the post-fire suppression window. */
-async function doFireFleetAutoFallback(triggerAgent: string, untilMs?: number): Promise<boolean> {
+async function doFireFleetAutoFallback(
+  triggerAgent: string,
+  untilMs?: number,
+  parsedResetAt?: Date,
+  trigger?: 'rate-limit',
+): Promise<boolean> {
   try {
     const client = await getAuthBrokerClient(triggerAgent)
     if (!client) {
@@ -23324,6 +23528,16 @@ async function doFireFleetAutoFallback(triggerAgent: string, untilMs?: number):
       },
       triggerAgent,
       tz,
+      // Enriched card (429 throttle tier): the RAW reset parsed from the
+      // error prose, so the announcement names when the old account frees
+      // even when its live probe returned nothing.
+      parsedResetAt,
+      // Throttle-tier escalation: a terminal transient 429 with a long
+      // parsed reset NEGATES the usage-limit reading, so the old account's
+      // utilization probe typically classifies healthy — the idempotency
+      // guard would self-cancel the swap ("probed healthy / Stale event?").
+      // Trust the terminal parsed-reset signal over the utilization probe.
+      rateLimitTrigger: trigger === 'rate-limit',
     })
     process.stderr.write(
       `telegram gateway: [fleet-fallback] outcome=${outcome.kind} agent=${triggerAgent}` +