switchroom 0.18.13 → 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) {
@@ -349,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
 }
 
 /**
@@ -364,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
@@ -382,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/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
@@ -212,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"
@@ -459,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'
   }

package/telegram-plugin/render/rich-render.ts

@@ -1,21 +1,24 @@
-// Flag-gated wiring for the Bot API 10.1 rich renderer (parse.ts + render.ts)
-// into the live outbound send path.
+// Wiring for the Bot API 10.1 rich renderer (parse.ts + render.ts) into the
+// live outbound send path.
 //
 // The renderer (`render/render.ts`, PR #2930) and parser (`render/parse.ts`)
 // have full unit coverage but were, until this module, wired into NOTHING —
-// no outbound message ever flowed through them. This module is the single,
-// feature-flagged bridge: the gateway's rich send path (stream-controller.ts)
-// runs the assistant's raw markdown through `parse → renderSafe` before it
-// reaches `sendRichMessage`, but ONLY when the flag is on.
+// no outbound message ever flowed through them. This module is the single
+// bridge: the gateway's rich send path (stream-controller.ts) runs the
+// assistant's raw markdown through `parse → renderSafe` before it reaches
+// `sendRichMessage`, unless the escape hatch below disables it.
 //
-// Feature flag — `SWITCHROOM_RICH_RENDER`, default OFF:
-//   Mirrors the `SWITCHROOM_VISIBLE_ANSWER_STREAM` convention
-//   (`answer-stream-flag.ts`): an env var read at runtime, default off, opted
-//   in PER AGENT via the `env:` block in `switchroom.yaml` (propagated into
-//   the container `environment:` by `src/agents/compose.ts`). When off,
-//   `maybeRenderOutbound` returns the input untouched, so the live send path
-//   is byte-for-byte unchanged — no agent's behaviour moves until an operator
-//   explicitly flips the flag for a specific agent. Accepts `1/true/on/yes`.
+// Escape hatch — `SWITCHROOM_RICH_RENDER`, default ON:
+//   ON BY DEFAULT in every install — an escape hatch, not an opt-in feature,
+//   mirroring the send gate's convention (`sendGateEnabledFromEnv` in
+//   `send-gate.ts`, default-on since #3153; also `midTurnFloorEnabled`,
+//   `SWITCHROOM_RATE_LIMIT_OVERAGE=0`). Enabled unless the var is explicitly
+//   set to a falsey/off value (`0`/`false`/`off`/`no`, case-insensitive,
+//   trimmed) — per agent via the `env:` block in `switchroom.yaml`
+//   (propagated into the container `environment:` by
+//   `src/agents/compose.ts`). When disabled, `maybeRenderOutbound` returns
+//   the input untouched, so the live send path is byte-for-byte the
+//   pre-renderer behaviour (raw transcript markdown to `sendRichMessage`).
 //
 // Why route through `renderSafe` and not bare `render`:
 //   `renderSafe` guarantees the returned body is never a rich-markdown string
@@ -38,17 +41,19 @@ import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
  */
 export const PLAIN_TEXT_MAX_CHARS = 4096;
 
-/** Parse the `SWITCHROOM_RICH_RENDER` flag value. Default OFF; accepts the
- *  same truthy tokens as the other switchroom env flags. Pure so the default
- *  + parsing are unit-testable. */
+/** Parse the `SWITCHROOM_RICH_RENDER` kill-switch value. Default ON; disabled
+ *  only by an explicit falsey/off token (`0`/`false`/`off`/`no`,
+ *  case-insensitive, trimmed) — the same disable vocabulary as
+ *  `sendGateEnabledFromEnv`. Unset, empty, or unrecognised values → ON. Pure
+ *  so the default + parsing are unit-testable. */
 export function parseRichRenderEnabled(raw: string | undefined): boolean {
-  if (raw == null) return false;
+  if (raw == null) return true;
   const v = raw.trim().toLowerCase();
-  return v === "1" || v === "true" || v === "on" || v === "yes";
+  return !(v === "0" || v === "false" || v === "off" || v === "no");
 }
 
 /** Is the rich renderer enabled in this process? Reads the env flag live so a
- *  test can set/unset it per-case; defaults OFF. */
+ *  test can set/unset it per-case; defaults ON (escape hatch, not opt-in). */
 export function richRenderEnabled(
   env: NodeJS.ProcessEnv = process.env,
 ): boolean {
@@ -65,13 +70,14 @@ export function renderOutbound(
 }
 
 /**
- * Flag-gated transform for the live send path.
+ * Kill-switch-gated transform for the live send path.
  *
- *   - flag OFF (default): returns the input untouched, `mode: "markdown"` —
- *     identical to the pre-existing behaviour (raw transcript markdown sent
- *     straight to `sendRichMessage`). No behavioural change for any agent.
- *   - flag ON: returns `parse → renderSafe` output. `mode: "plain"` signals
- *     the caller to send WITHOUT the rich wrapper (oversized/unsafe content).
+ *   - enabled (default): returns `parse → renderSafe` output. `mode: "plain"`
+ *     signals the caller to send WITHOUT the rich wrapper (oversized/unsafe
+ *     content).
+ *   - disabled (`SWITCHROOM_RICH_RENDER=0`): returns the input untouched,
+ *     `mode: "markdown"` — identical to the pre-renderer behaviour (raw
+ *     transcript markdown sent straight to `sendRichMessage`).
  */
 export function maybeRenderOutbound(
   text: string,
@@ -83,7 +89,7 @@ export function maybeRenderOutbound(
 }
 
 /**
- * Flag-gated, CAP-ENFORCING transform for the live send path.
+ * Kill-switch-gated, CAP-ENFORCING transform for the live send path.
  *
  * `maybeRenderOutbound` returns ONE `RenderResult` and can only ever fit a
  * body into a single wire message. But `renderSafe`'s markdown re-escaping
@@ -104,11 +110,13 @@ export function maybeRenderOutbound(
  * plain degradation would have thrown away: the smaller pieces individually
  * escape under `maxLen` and come back as `markdown`.
  *
- *   - flag OFF (default): `[{ text, mode: "markdown", degradations: [] }]` —
- *     a single passthrough piece, identical to `maybeRenderOutbound`.
- *   - flag ON, body fits: `[renderSafe(...)]` — a single piece, identical to
- *     `maybeRenderOutbound` (byte-for-byte for the common case).
- *   - flag ON, body oversize: 2+ cap-respecting pieces in send order.
+ *   - disabled (`SWITCHROOM_RICH_RENDER=0`):
+ *     `[{ text, mode: "markdown", degradations: [] }]` — a single passthrough
+ *     piece, identical to `maybeRenderOutbound`.
+ *   - enabled (default), body fits: `[renderSafe(...)]` — a single piece,
+ *     identical to `maybeRenderOutbound` (byte-for-byte for the common case).
+ *   - enabled (default), body oversize: 2+ cap-respecting pieces in send
+ *     order.
  */
 export function renderOutboundChunks(
   text: string,

package/telegram-plugin/stream-controller.ts

@@ -228,8 +228,9 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // `maybeRenderOutbound` path; a body whose markdown-escaping pushed the
   // rendered form past the cap splits into several pieces, each of which fits
   // its own wire cap and never bisects a fenced block / table row (see
-  // `renderOutboundChunks`). Flag OFF (default) and a literal `format:'text'`
-  // stream both yield a single passthrough piece — no behavioural change.
+  // `renderOutboundChunks`). Rendering disabled (SWITCHROOM_RICH_RENDER=0)
+  // and a literal `format:'text'` stream both yield a single passthrough
+  // piece — byte-for-byte the pre-renderer send path.
   const renderPieces = (text: string): { text: string; rich: boolean }[] => {
     if (literalText) return [{ text, rich: false }]
     // A `plain`-mode piece (oversized/unsafe content renderSafe declined to

package/telegram-plugin/tests/auto-fallback-fleet.test.ts

@@ -118,6 +118,78 @@ describe('runFleetAutoFallback', () => {
     }
   });
 
+  it('parsedResetAt (429 throttle tier) names the recovery when the old probe carried no reset', async () => {
+    const failover = vi.fn(async () => ({ rolledTo: 'you@x', rolled: ['ken@x'] }));
+    const out = await runFleetAutoFallback({
+      state: state('ken@x', ['ken@x', 'you@x']),
+      quotas: [
+        // ken: walled, but the probe carried NO reset time — pre-fix the
+        // announcement's recovery line was silently dropped.
+        qOk({ fiveHourUtilizationPct: 100, representativeClaim: 'five_hour' }),
+        qOk({ fiveHourUtilizationPct: 8, sevenDayUtilizationPct: 20 }),
+      ],
+      failover,
+      triggerAgent: 'carrie',
+      now: NOW,
+      tz: 'UTC',
+      // Parsed from the error prose ("resets 5:50am") by the gateway.
+      parsedResetAt: new Date('2026-05-15T05:50:00Z'),
+    });
+
+    expect(out.kind).toBe('switched');
+    if (out.kind === 'switched') {
+      expect(out.announcement).toContain('recovers');
+      expect(out.announcement).toContain('in 4h 57m');
+    }
+  });
+
+  it('rateLimitTrigger: swaps even when the old account probes HEALTHY (the >threshold leg must execute)', async () => {
+    // A terminal transient 429 NEGATES the usage-limit reading, so healthy
+    // utilization is the EXPECTED state for the rate-limited account. The
+    // healthy-idempotency guard must not self-cancel this swap into a
+    // "probed healthy / Stale event?" no-op.
+    const failover = vi.fn(async () => ({ rolledTo: 'you@x', rolled: ['ken@x'] }));
+    const out = await runFleetAutoFallback({
+      state: state('ken@x', ['ken@x', 'you@x']),
+      quotas: [
+        qOk({ fiveHourUtilizationPct: 12, sevenDayUtilizationPct: 30 }), // healthy!
+        qOk({ fiveHourUtilizationPct: 8, sevenDayUtilizationPct: 20 }),
+      ],
+      failover,
+      triggerAgent: 'carrie',
+      now: NOW,
+      tz: 'UTC',
+      parsedResetAt: new Date('2026-05-15T02:53:00Z'),
+      rateLimitTrigger: true,
+    });
+
+    expect(out.kind).toBe('switched');
+    expect(failover).toHaveBeenCalledTimes(1);
+    if (out.kind === 'switched') {
+      // Honest headline: a rate limit, not a utilization-derived window cap.
+      expect(out.announcement).toContain('rate limit on ken@x');
+      expect(out.announcement).not.toContain('5-hour limit');
+      // Recovery line carries the parsed reset (no window was maxed).
+      expect(out.announcement).toContain('recovers');
+      expect(out.announcement).toContain('in 2h');
+    }
+  });
+
+  it('rateLimitTrigger stays subject to the broker outcome (all-blocked passes through)', async () => {
+    const failover = vi.fn(async () => ({ rolledTo: null, rolled: [] }));
+    const out = await runFleetAutoFallback({
+      state: state('ken@x', ['ken@x']),
+      quotas: [qOk({ fiveHourUtilizationPct: 12, sevenDayUtilizationPct: 30 })],
+      failover,
+      triggerAgent: 'carrie',
+      now: NOW,
+      tz: 'UTC',
+      rateLimitTrigger: true,
+    });
+    expect(out.kind).toBe('all-blocked');
+    expect(failover).toHaveBeenCalledTimes(1);
+  });
+
   it('idempotency: skips the swap WITHOUT calling failover when active probes healthy', async () => {
     const failover = vi.fn();
     const out = await runFleetAutoFallback({