switchroom 0.18.15 → 0.18.17

package/telegram-plugin/litellm-local-notice.ts

@@ -0,0 +1,189 @@
+/**
+ * litellm-local-notice.ts — debounced operator notice for LiteLLM-proxy-local
+ * 429s (pure module: state machine + text + config parsing, no IPC, no bot,
+ * no clock except the injected `now`).
+ *
+ * When an agent routes through the LiteLLM gateway and trips the proxy's OWN
+ * `tpm_limit`/`rpm_limit` limiter, `classify429Detail` (throttle-tier.ts)
+ * classifies the terminal 429 `litellm-local` and the gateway takes the calm
+ * path — no broker mark, no failover, no throttle tier (the request never
+ * reached Anthropic, so the condition says nothing about the account). But
+ * pre-notice the user-facing surface was the GENERIC "🚦 Rate limited" card,
+ * which reads like an Anthropic problem. This module owns the honest
+ * replacement:
+ *
+ *   - ONE calm notice per agent per cooldown window (default 15 min,
+ *     operator-tunable via channels.telegram.litellm_notice.window_ms in
+ *     switchroom.yaml, projected into access.json by scaffold).
+ *   - Further litellm-local 429s inside the window are counted SILENTLY;
+ *     the first notice after the window expires carries "throttled N more
+ *     times since the last notice".
+ *   - A notice only ever fires on an actual throttle event — a quiet agent
+ *     posts nothing (the state machine is evaluate-on-event, no timers).
+ *
+ * The copy must make clear this is the fleet token limiter (LiteLLM
+ * `tpm_limit`/`rpm_limit`), NOT an Anthropic account limit, and that the
+ * turn retries — no action needed.
+ *
+ * Side-effect sequencing lives in gateway/litellm-local-notice-wiring.ts.
+ * This module MUST NOT change classification, failover, or quota-ledger
+ * behavior — it only renders and debounces the notice.
+ */
+
+import { escapeMarkdown } from './card-format.js'
+import type { RateLimit429Classification } from './throttle-tier.js'
+import type { RuntimeMetricEvent } from './runtime-metrics.js'
+
+// ─── Cooldown window config ──────────────────────────────────────────────────
+
+/**
+ * Default per-agent notice cooldown. 15 minutes: long enough that a sustained
+ * burst produces a handful of notices per hour at most, short enough that the
+ * operator still sees the limiter working while it's working.
+ */
+export const LITELLM_LOCAL_NOTICE_WINDOW_MS_DEFAULT = 15 * 60_000
+
+/**
+ * Resolve the cooldown window from the raw access-file value
+ * (`access.litellmNoticeWindowMs`, projected by scaffold from
+ * channels.telegram.litellm_notice.window_ms). Any non-finite, non-positive,
+ * or non-number value falls back to the default — an operator typo must
+ * never produce a zero-width window (notice storm) or a NaN comparison
+ * (notices never fire again).
+ */
+export function parseLitellmNoticeWindowMs(raw: unknown): number {
+  if (typeof raw !== 'number') return LITELLM_LOCAL_NOTICE_WINDOW_MS_DEFAULT
+  if (!Number.isFinite(raw) || raw <= 0) return LITELLM_LOCAL_NOTICE_WINDOW_MS_DEFAULT
+  return raw
+}
+
+// ─── Per-agent cooldown state machine ────────────────────────────────────────
+
+export interface LitellmLocalNoticeState {
+  /** agent → unix ms of the last notice sent for it. */
+  lastSentAtMsByAgent: Record<string, number>
+  /** agent → litellm-local 429s counted silently since the last notice. */
+  suppressedCountByAgent: Record<string, number>
+}
+
+export function initialLitellmLocalNoticeState(): LitellmLocalNoticeState {
+  return { lastSentAtMsByAgent: {}, suppressedCountByAgent: {} }
+}
+
+export interface LitellmLocalNoticeVerdict {
+  send: boolean
+  /** Silent throttle events since the previous notice (0 on the first). Only
+   *  meaningful when `send` is true — the renderer adds the "N more times"
+   *  line when > 0. */
+  suppressedSinceLastNotice: number
+  next: LitellmLocalNoticeState
+}
+
+/**
+ * Evaluate one litellm-local 429 for `agent` at `now`.
+ *
+ *   - First event ever (or ≥ windowMs since the last notice) → send; the
+ *     verdict carries the silently-counted events since the previous notice
+ *     and the counter resets.
+ *   - Inside the window → suppress; the counter increments.
+ *
+ * Boundary is INCLUSIVE on expiry (elapsed === windowMs sends), matching
+ * `evaluateThrottleNotice` in throttle-tier.ts. Pure: returns the next
+ * state, never mutates `prev`.
+ */
+export function evaluateLitellmLocalNotice(
+  prev: LitellmLocalNoticeState,
+  agent: string,
+  now: number,
+  windowMs: number = LITELLM_LOCAL_NOTICE_WINDOW_MS_DEFAULT,
+): LitellmLocalNoticeVerdict {
+  const last = prev.lastSentAtMsByAgent[agent]
+  if (last == null || now - last >= windowMs) {
+    return {
+      send: true,
+      suppressedSinceLastNotice: prev.suppressedCountByAgent[agent] ?? 0,
+      next: {
+        lastSentAtMsByAgent: { ...prev.lastSentAtMsByAgent, [agent]: now },
+        suppressedCountByAgent: { ...prev.suppressedCountByAgent, [agent]: 0 },
+      },
+    }
+  }
+  return {
+    send: false,
+    suppressedSinceLastNotice: 0,
+    next: {
+      lastSentAtMsByAgent: prev.lastSentAtMsByAgent,
+      suppressedCountByAgent: {
+        ...prev.suppressedCountByAgent,
+        [agent]: (prev.suppressedCountByAgent[agent] ?? 0) + 1,
+      },
+    },
+  }
+}
+
+// ─── Notice rendering ────────────────────────────────────────────────────────
+
+/**
+ * The ONE calm notice for a litellm-local 429. Markdown (not HTML) per the
+ * card-format.ts convention. Copy contract (operator spec):
+ *   - names the fleet token limiter (LiteLLM `tpm_limit`/`rpm_limit`)
+ *   - explicitly NOT an Anthropic account limit — nothing exhausted, no
+ *     account touched
+ *   - the turn retries automatically; no action needed
+ *   - after a window with silent suppressions, says "throttled N more
+ *     time(s) since the last notice"
+ */
+export function renderLitellmLocalNotice(opts: {
+  agent: string
+  /** Silent litellm-local 429s since the previous notice (0 on the first). */
+  suppressedSinceLastNotice: number
+}): string {
+  const agent = escapeMarkdown(opts.agent)
+  const n = opts.suppressedSinceLastNotice
+  const lines = [
+    `🚦 **Fleet token limiter engaged** — **${agent}** hit the local LiteLLM proxy cap (\`tpm_limit\`/\`rpm_limit\`).`,
+    `This is switchroom's own fleet limiter smoothing a burst, not an Anthropic account limit — nothing is exhausted and no account was touched.`,
+  ]
+  if (n > 0) {
+    lines.push(`Throttled ${n} more ${n === 1 ? 'time' : 'times'} since the last notice.`)
+  }
+  lines.push(`_The turn retries automatically — no action needed._`)
+  return lines.join('\n')
+}
+
+// ─── Metric builder ──────────────────────────────────────────────────────────
+
+/**
+ * Build the `litellm_local_429_notice` runtime metric for one SENT notice.
+ * Distinct from `rate_limit_429_classified` (which fires on EVERY classified
+ * event): this one fires only when a notice actually posts, and carries how
+ * many events the window silently absorbed — the debounce's effectiveness in
+ * one number. Pure builder so the payload shape is unit-testable; the wiring
+ * emits the result via emitRuntimeMetric (PostHog + JSONL dual sink).
+ */
+export function buildLitellmLocalNoticeMetric(opts: {
+  agent: string
+  suppressedCount: number
+  windowMs: number
+}): Extract<RuntimeMetricEvent, { kind: 'litellm_local_429_notice' }> {
+  return {
+    kind: 'litellm_local_429_notice',
+    agent: opts.agent,
+    suppressed_count: opts.suppressedCount,
+    window_ms: opts.windowMs,
+  }
+}
+
+// ─── Classification guard ────────────────────────────────────────────────────
+
+/**
+ * True only for the `litellm-local` classification. The wiring runs this
+ * guard so "a notice never fires for non-litellm-local classifications" is a
+ * deterministic mechanism, not caller discipline — account-scoped 429s keep
+ * the throttle tier, generic transients keep the calm rate-limited card.
+ */
+export function isLitellmLocalNoticeEligible(
+  classification: RateLimit429Classification | null | undefined,
+): classification is 'litellm-local' {
+  return classification === 'litellm-local'
+}

package/telegram-plugin/quota-watch.ts

@@ -192,10 +192,14 @@ export interface FleetRollInfo {
   /**
    * Trigger attribution (#3031 PR 2): "soft-avoid" = proactive
    * serving-preference roll off an account APPROACHING its limits;
-   * "hard-exhaustion" = the probe saw a genuine quota wall. Absent on
-   * pre-PR-2 brokers — rendered as hard exhaustion.
+   * "hard-exhaustion" = the probe saw a genuine quota wall;
+   * "model-tier-wall" = the flagship-tier (7d_oi) canary saw the account
+   * walled on the premium tier (#3176). Absent on pre-PR-2 brokers —
+   * rendered as hard exhaustion.
    */
-  reason?: "soft-avoid" | "hard-exhaustion";
+  reason?: "soft-avoid" | "hard-exhaustion" | "model-tier-wall";
+  /** #3176 — the binding tier bucket, set only when reason is model-tier-wall. */
+  bucket?: string;
 }
 
 export type FleetRollAnnounceDecision =
@@ -241,9 +245,17 @@ export function buildFleetRollMessage(roll: FleetRollInfo, now: number): string
       ? ` (resets ${formatRelative(new Date(roll.exhausted_until), new Date(now))})`
       : "";
   const softAvoid = roll.reason === "soft-avoid";
+  // #3176 — a model-tier wall binds on the flagship (premium) 7d_oi bucket, not
+  // the 5h/7d windows (which read healthy — the whole point of the bug), so it
+  // has no window/pct to cite. Name the flagship tier explicitly and reassure
+  // that opus/haiku on the walled account are unaffected (the mark is
+  // tier-scoped), rather than rendering a generic, misleading "quota window".
+  const modelTierWall = roll.reason === "model-tier-wall";
   const causeLine = softAvoid
     ? `Proactive switch — \`${codeSpanSafe(roll.from)}\` is approaching its limits (${winLabel}${pctPart})${resetPart}, so the fleet moved early instead of hitting the wall.`
-    : `${winLabel}${pctPart} on \`${codeSpanSafe(roll.from)}\`${resetPart}.`;
+    : modelTierWall
+      ? `Flagship (premium) tier weekly limit reached on \`${codeSpanSafe(roll.from)}\`${resetPart} — opus/haiku on that account are unaffected.`
+      : `${winLabel}${pctPart} on \`${codeSpanSafe(roll.from)}\`${resetPart}.`;
   return [
     `🔁 **Switched fleet to \`${codeSpanSafe(roll.to)}\`**`,
     ``,

package/telegram-plugin/runtime-metrics.ts

@@ -195,6 +195,22 @@ export type RuntimeMetricEvent =
       limit: number | null
       current_usage: number | null
     }
+  /**
+   * A litellm-local throttle NOTICE actually posted (litellm-local-notice.ts
+   * — the debounced "fleet token limiter engaged" message). Distinct from
+   * `rate_limit_429_classified`, which fires on EVERY classified 429: this
+   * fires once per sent notice, and `suppressed_count` is how many
+   * litellm-local 429s the cooldown window silently absorbed since the
+   * previous notice (0 on the first) — the debounce's effectiveness in one
+   * number. `window_ms` is the resolved cooldown window (default 15 min;
+   * channels.telegram.litellm_notice.window_ms).
+   */
+  | {
+      kind: 'litellm_local_429_notice'
+      agent: string
+      suppressed_count: number
+      window_ms: number
+    }
 
 /**
  * The JSONL sink lives under the runtime state dir so it's per-agent

package/telegram-plugin/send-gate-degraded.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { createSendGate, type Clock } from './send-gate.js'
+import { createSendGate, SEND_GATE_SHED, type Clock } from './send-gate.js'
 import { isFloodWaitActiveError } from './retry-api-call.js'
 
 /**
@@ -73,8 +73,10 @@ describe('send-gate PR2: cosmetic shedding', () => {
 
     const res = await gate.gate(fn('cosmetic'), { priorityClass: 'cosmetic' })
 
-    // Shed resolves undefined; fn never ran; the shed counter moved.
-    expect(res).toBeUndefined()
+    // Shed resolves the distinguishable sentinel (#3110 F1 — never a bare
+    // undefined, which is reserved for benign no-op drops); fn never ran;
+    // the shed counter moved.
+    expect(res).toBe(SEND_GATE_SHED)
     expect(calls).toHaveLength(0)
     expect(gate.stats().global.shed).toBe(1)
     expect(gate.stats().global.sent).toBe(0)
@@ -95,7 +97,7 @@ describe('send-gate PR2: cosmetic shedding', () => {
     const shed = await gate.gate(fn('b'), { chat_id: '5', priorityClass: 'cosmetic' })
 
     expect(calls.map((c) => c.label)).toEqual(['a'])
-    expect(shed).toBeUndefined()
+    expect(shed).toBe(SEND_GATE_SHED)
     expect(gate.stats().global.shed).toBe(1)
   })
 
@@ -128,7 +130,7 @@ describe('send-gate PR2: cosmetic shedding', () => {
       priorityClass: 'cosmetic',
     })
 
-    expect(res).toBeUndefined()
+    expect(res).toBe(SEND_GATE_SHED)
     expect(calls).toHaveLength(0)
     expect(gate.stats().global.shed).toBe(1)
   })
@@ -366,7 +368,7 @@ describe('send-gate PR2: H1 cross-chat message_id isolation', () => {
       priorityClass: 'cosmetic',
     })
 
-    expect(rA).toBeUndefined() // A shed
+    expect(rA).toBe(SEND_GATE_SHED) // A shed
     expect(rB).toBe('B-edit') // B sent
     expect(calls.map((c) => c.label)).toEqual(['B-edit'])
     expect(gate.stats().global.shed).toBe(1)
@@ -568,7 +570,7 @@ describe('send-gate PR2: opening a window from a 429, and persistence hook', ()
     expect(scopes).toEqual(['chat:7', 'global', 'group:7', 'msg-edit:7:3'])
     // After the window opens, a later cosmetic on the same chat sheds.
     const shed = await gate.gate(async () => 'x', { chat_id: '7', priorityClass: 'cosmetic' })
-    expect(shed).toBeUndefined()
+    expect(shed).toBe(SEND_GATE_SHED)
     expect(gate.stats().global.shed).toBe(1)
   })
 })

package/telegram-plugin/send-gate.ts

@@ -118,6 +118,32 @@ export type PriorityClass = 'critical' | 'useful' | 'cosmetic'
  */
 export const UNTAGGED_SEND_CLASS: PriorityClass = 'critical'
 
+/**
+ * Distinguishable resolution value for a SHED call (#3110 review F1).
+ *
+ * `undefined` was overloaded three ways at the robustApiCall seam: a gate
+ * SHED (cosmetic call dropped under pressure — did NOT land), a gate no-op
+ * drop (identical payload already on screen — benign), and the retry
+ * policy's swallowed benign 400s ("message is not modified" — also benign).
+ * A caller that needs to know "did my edit land?" (the draft stream's
+ * shed-honesty handling in stream-controller.ts) could not tell these
+ * apart, and treating every `undefined` as a shed froze multi-piece
+ * streams on perfectly healthy chats.
+ *
+ * A shed now resolves THIS sentinel instead. `Symbol.for` keys it in the
+ * global symbol registry so duplicated module instances (server + gateway
+ * builds) agree on identity. The no-op drop and coalesced-revert drop keep
+ * resolving `undefined` — for those the payload IS on screen. Callers that
+ * ignore the result (reactions, typing, fire-and-forget card edits) are
+ * unaffected either way.
+ */
+export const SEND_GATE_SHED: unique symbol = Symbol.for('switchroom.send-gate.shed')
+
+/** True when a gate result is the {@link SEND_GATE_SHED} sentinel. */
+export function isSendGateShed(value: unknown): value is typeof SEND_GATE_SHED {
+  return value === SEND_GATE_SHED
+}
+
 /**
  * Extra metadata a call site can attach so the gate can key the right buckets.
  * All fields optional — a call with none still passes the global bucket. These
@@ -159,8 +185,9 @@ export interface BucketCounters {
   dropped: number
   /**
    * Cosmetic calls shed under pressure — no token free OR a flood window open
-   * (part3-design §2). A shed resolves as `undefined`; the next send carries
-   * full state.
+   * (part3-design §2). A shed resolves the SEND_GATE_SHED sentinel (F1 —
+   * distinguishable from a benign no-op drop's `undefined`); the next send
+   * carries full state.
    */
   shed: number
   /** Useful calls dropped because they exceeded their queue TTL (part3-design §2). */
@@ -913,7 +940,9 @@ export function createSendGate(config: SendGateConfig): SendGate {
       const msgWait = state.suppressedUntilMs > now ? state.suppressedUntilMs - now : 0
       if (wait > 0 || msgWait > 0) {
         counters.shed++
-        return Promise.resolve(undefined as unknown as T)
+        // Distinguishable from the no-op drop below (undefined): a shed did
+        // NOT land, and edit-driving callers must be able to tell (F1).
+        return Promise.resolve(SEND_GATE_SHED as unknown as T)
       }
     }
 
@@ -991,7 +1020,8 @@ export function createSendGate(config: SendGateConfig): SendGate {
     const outcome = await admitPriority(bucketsFor(opts), priority)
     if (outcome.result === 'shed') {
       counters.shed++
-      return undefined as unknown as T
+      // See SEND_GATE_SHED: distinguishable "did not land" resolution (F1).
+      return SEND_GATE_SHED as unknown as T
     }
     if (outcome.result === 'expired') {
       counters.expired++

package/telegram-plugin/stream-controller.ts

@@ -19,9 +19,14 @@
  * entire server.ts top-level initialization.
  */
 
-import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
+import {
+  createDraftStream,
+  makeDraftEditShedError,
+  type DraftStreamHandle,
+} from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
 import { renderOutboundChunks } from './render/rich-render.js'
+import { isSendGateShed, type SendGateOpts } from './send-gate.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -77,9 +82,21 @@ export interface StreamSendOpts {
   disable_notification?: boolean
 }
 
+/**
+ * Options a stream-controller call passes to its retry wrapper. A structural
+ * superset of `SendGateOpts` (send-gate.ts) plus the retry policy's own
+ * `threadId`, and assignable to `RetryCallOpts` (retry-api-call.ts) — so the
+ * production wrapper (`robustApiCall` = send gate over `createRetryApiCall`)
+ * receives `messageId` / `editPayload` / `priorityClass` and the gate's
+ * per-message edit floor, last-write-wins coalescing, no-op skip and
+ * cosmetic shedding govern the draft/answer stream (#3110; part3-design §4
+ * names rapid same-message editMessageText as the #1 flood-ban trigger).
+ */
+export type RetryPolicyOpts = SendGateOpts & { threadId?: number }
+
 export type RetryPolicy = <T>(
   fn: () => Promise<T>,
-  opts?: { threadId?: number; chat_id?: string },
+  opts?: RetryPolicyOpts,
 ) => Promise<T>
 
 export interface StreamControllerConfig {
@@ -251,6 +268,70 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     return bot.api.editMessageText(chatId, id, richMessage(piece.text), opts)
   }
 
+  // ---- Send-gate wiring for the edit path (#3110) -------------------------
+  //
+  // Every edit call passes `messageId` / `editPayload` / `priorityClass`
+  // through the retry wrapper so the send gate's per-message edit floor
+  // (>=1.5s), last-write-wins coalescing, and no-op skip govern the draft
+  // stream — previously these edits carried only `{ threadId, chat_id }`,
+  // so the gate treated them as ordinary sends and the stream's own 400 ms
+  // DM throttle drove same-message editMessageText well under the floor
+  // (the #1 documented flood-ban trigger, part3-design §4; production ban
+  // 2026-07-12 on #3110). The local per-surface throttle stays as a cheap
+  // pre-filter; the gate is the authority.
+  //
+  // Priority classes: intermediate draft edits are `cosmetic` (part3-design
+  // §2 lists "stream updates" there) — shed under pressure / an open flood
+  // window; the next flush carries full state. The FINALIZE flush (the edit
+  // that renders the completed answer) is `critical`, mirroring the reply
+  // path's preview-finalize convention (gateway.ts editPreview): never shed,
+  // waits out a short window, fails fast with a structured FLOOD_WAIT_ACTIVE
+  // on a long one. SENDS stay untagged (the gate admits untagged non-edit
+  // sends as `critical`) — a shed send would resolve the gate's shed
+  // sentinel instead of `{ message_id }` and break message-id capture, and
+  // the anchor/tail sends ARE the answer surface.
+  //
+  // `handleRef.isFinal()` is true from the moment finalize() is entered
+  // (draft-stream sets `final` before its last flush), so the closures below
+  // classify exactly the finalize flush — and anything after it — as
+  // critical. The ref is assigned right after createDraftStream returns,
+  // before any closure can run (closures only fire from update/finalize).
+  //
+  // KNOWN MISSED BENEFIT (review F5, deliberate): the gate's last-write-wins
+  // coalescing never engages for THIS surface, because draft-stream
+  // serializes its flushes — it awaits each edit before issuing the next, so
+  // at most one edit per message is ever inside the gate. Consequence: a
+  // stale draft sleeping on the gate's floor still lands (one API call the
+  // coalescer would have replaced) before the newer snapshot, and a finalize
+  // issued mid-floor can trail by up to ~2x editFloorMs (floor wait for the
+  // stale draft, then floor wait for the final). Correctness is unaffected —
+  // the latest state always lands, floor-paced — and the gate coalescing
+  // remains live protection for CONCURRENT writers to one message (e.g. a
+  // re-attached #626 controller racing its predecessor).
+  let handleRef: DraftStreamHandle | null = null
+  const editGateOpts = (id: number, payload: unknown): RetryPolicyOpts => ({
+    threadId,
+    chat_id: chatId,
+    messageId: id,
+    editPayload: payload,
+    priorityClass: handleRef?.isFinal() === true ? 'critical' : 'cosmetic',
+  })
+  // The rendered payload the gate hashes for the no-op skip / coalescing —
+  // exactly what goes over the wire (rich wrapper included), so a plain
+  // fallback of the same text never hashes equal to its rich form.
+  const piecePayload = (piece: { text: string; rich: boolean }): unknown =>
+    piece.rich ? richMessage(piece.text) : piece.text
+  // Shed detection (#3110 review F1): keyed EXACTLY off the gate's
+  // SEND_GATE_SHED sentinel — never off `undefined`, which is overloaded
+  // (gate no-op drop; robustApiCall's swallowed benign 400s like "message is
+  // not modified"). Those benign cases mean the payload is ALREADY on screen
+  // and are treated as delivered, exactly as before this wiring existed. A
+  // true shed means the edit did NOT land: draft-stream must not record the
+  // snapshot as on-screen (its dedupe would skip a later flush of the same
+  // text — the completed answer would never render), so the edit closure
+  // throws the marker error draft-stream recognizes and recovers from
+  // (`makeDraftEditShedError` → snapshot preserved for finalize, review F2).
+
   // Overflow-tail bookkeeping, shared across the send + edit closures for the
   // whole stream lifetime. A body large enough to split into several
   // wire-cap pieces anchors on piece[0] (edited in place by draft-stream) and
@@ -269,12 +350,25 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // text) thereafter. A non-parse failure is logged as a partial-delivery
   // warning and swallowed so the remaining tail pieces still get a chance to
   // land — never a silent drop, never an abort of pieces K..N (concern C1).
-  const upsertTail = async (ti: number, piece: { text: string; rich: boolean }): Promise<void> => {
+  //
+  // Returns TRUE when this piece's edit was SHED by the send gate (did not
+  // land): the caller must then report the whole flush as shed so
+  // draft-stream does not record the full body as delivered while a tail is
+  // stale (review F3). The piece's own tailLastText stays stale too, so the
+  // recovery flush re-attempts exactly the shed piece.
+  const upsertTail = async (
+    ti: number,
+    piece: { text: string; rich: boolean },
+  ): Promise<boolean> => {
     const existingId = tailIds[ti]
     if (existingId != null) {
-      if (tailLastText[ti] === piece.text) return // unchanged — skip the API call
+      if (tailLastText[ti] === piece.text) return false // unchanged — skip the API call
       try {
-        await retry(() => editPiece(existingId, piece, baseOpts), { threadId, chat_id: chatId })
+        const res = await retry(
+          () => editPiece(existingId, piece, baseOpts),
+          editGateOpts(existingId, piecePayload(piece)),
+        )
+        if (isSendGateShed(res)) return true // shed — stale; retried by the recovery flush
         tailLastText[ti] = piece.text
         onEdit?.(existingId, piece.text.length)
       } catch (err) {
@@ -282,10 +376,11 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           warn?.(
             `stream-controller: tail-piece #${ti + 1} edit parse-entities rejected — retrying same id=${existingId} as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
-          await retry(
+          const res = await retry(
             () => bot.api.editMessageText(chatId, existingId, piece.text, baseOpts),
-            { threadId, chat_id: chatId },
+            editGateOpts(existingId, piece.text),
           )
+          if (isSendGateShed(res)) return true // shed — stale; retried by the recovery flush
           tailLastText[ti] = piece.text
           onEdit?.(existingId, piece.text.length)
         } else {
@@ -296,7 +391,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           )
         }
       }
-      return
+      return false
     }
     // First emission of this tail piece → a fresh follow-up message.
     try {
@@ -324,9 +419,12 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
         )
       }
     }
+    // First-emission SENDS are untagged (critical) — the gate never sheds
+    // them, so this path can only land or fail (handled above).
+    return false
   }
 
-  return createDraftStream(
+  const handle = createDraftStream(
     async (text) => {
       // Render → 1+ cap-respecting pieces. The FIRST piece's message_id anchors
       // the stream (later edits target it); any overflow pieces are parked as
@@ -378,14 +476,26 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     async (id, text) => {
       const pieces = renderPieces(text)
       const head = pieces[0]
+      // Whether any piece of THIS flush was shed by the gate (did not land).
+      // Decided at the very end — AFTER the tail loop — so a benign anchor
+      // outcome (or even a shed anchor) never starves the tail pieces of
+      // their own upsert attempt (review F1: an anchor whose payload stopped
+      // changing resolves benignly every flush while only the tail grows).
+      let anchorShed = false
       // Edit the anchor message in place with the FIRST piece.
       try {
-        await retry(
-          () => editPiece(id, head, baseOpts),
-          { threadId, chat_id: chatId },
-        )
-        // C2: report the actual head-piece length, not the full body length.
-        onEdit?.(id, head.text.length)
+        const res = await retry(() => editPiece(id, head, baseOpts), editGateOpts(id, piecePayload(head)))
+        if (isSendGateShed(res)) {
+          // Shed by the gate (cosmetic under pressure / an open flood
+          // window) — did NOT land. Benign `undefined` resolutions (gate
+          // no-op drop, robustApiCall's swallowed "message is not modified")
+          // deliberately do NOT take this branch: the payload is already on
+          // screen and the flush proceeds as delivered.
+          anchorShed = true
+        } else {
+          // C2: report the actual head-piece length, not the full body length.
+          onEdit?.(id, head.text.length)
+        }
       } catch (err) {
         if (!literalText && head.rich && isParseEntitiesError(err)) {
           // Edit rejected because the markdown couldn't be parsed — DO NOT
@@ -400,11 +510,12 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           // contract). For a single-piece stream (common case) this is the
           // whole body; a rare oversize split edits the head piece's body.
           const fallbackBody = pieces.length === 1 ? text : head.text
-          await retry(
+          const res = await retry(
             () => bot.api.editMessageText(chatId, id, fallbackBody, baseOpts),
-            { threadId, chat_id: chatId },
+            editGateOpts(id, fallbackBody),
           )
-          onEdit?.(id, head.text.length)
+          if (isSendGateShed(res)) anchorShed = true
+          else onEdit?.(id, head.text.length)
         } else {
           throw err
         }
@@ -414,10 +525,20 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       // that only just came into existence) — we never re-send tails already
       // emitted on a prior flush. This is the fix for the duplicate-flood
       // blocker: the previous code re-sent pieces[1..n] as brand-new messages
-      // on each throttled edit tick.
+      // on each throttled edit tick. Runs BEFORE the shed decision below so a
+      // shed (or benign) anchor never starves the tails (review F1).
+      let anyTailShed = false
       for (let pi = 1; pi < pieces.length; pi++) {
-        await upsertTail(pi - 1, pieces[pi])
+        if (await upsertTail(pi - 1, pieces[pi])) anyTailShed = true
       }
+      // Review F3: ANY shed piece — anchor or tail — means this flush did not
+      // fully land. Throw the marker error so draft-stream does not record
+      // the body as delivered (its dedupe would freeze the shed piece
+      // forever) and instead preserves the snapshot for the finalize
+      // re-flush. Pieces that DID land are unaffected on that re-flush: the
+      // gate's no-op skip drops their identical payloads before the API, and
+      // landed tails short-circuit on tailLastText.
+      if (anchorShed || anyTailShed) throw makeDraftEditShedError(id)
     },
     {
       ...(throttleMs != null ? { throttleMs } : {}),
@@ -429,4 +550,6 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       chatId,
     },
   )
+  handleRef = handle
+  return handle
 }

package/telegram-plugin/stream-reply-handler.ts

@@ -516,10 +516,20 @@ export async function handleStreamReply(
     state.activeDraftStreams.set(sKey, stream)
   }
 
-  await stream.update(effectiveText)
+  if (!done) {
+    // Intermediate snapshot — an ordinary throttled draft update.
+    await stream.update(effectiveText)
+  }
 
   if (done) {
-    await stream.finalize()
+    // #3110: route the FINAL text through finalize(text) so the flush that
+    // renders the completed answer runs with the stream already final —
+    // stream-controller then classifies that edit `critical` for the send
+    // gate (never shed; fails fast with a structured FLOOD_WAIT_ACTIVE on a
+    // long flood window) while intermediate draft edits stay `cosmetic`
+    // (sheddable). The previous update()-then-finalize() pair flushed the
+    // final text inside update(), i.e. as an ordinary sheddable draft edit.
+    await stream.finalize(effectiveText)
     state.activeDraftStreams.delete(sKey)
     // #1713: stream_reply done=true is a NON-EVENT for the status
     // reaction. The reaction reflects current turn activity, not