switchroom 0.18.6 → 0.18.8

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

@@ -25,7 +25,18 @@
 
 import { parse } from "./parse.js";
 import { renderSafe, type RenderResult } from "./render.js";
-import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
+import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
+
+/**
+ * The legacy plain-text `sendMessage` / `editMessageText` wire cap (4096
+ * UTF-16 units). It does NOT apply to the rich path (`sendRichMessage`, up
+ * to `RICH_MESSAGE_MAX_CHARS`), but it DOES apply the moment `renderSafe`
+ * degrades a body to `mode: "plain"` — the send path then routes it through
+ * the plain `sendMessage` endpoint (see stream-controller `doSend`/`doEdit`).
+ * A degraded plain body larger than this is rejected by Telegram with
+ * `message is too long`, so `renderOutboundChunks` caps plain pieces here.
+ */
+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
@@ -70,3 +81,70 @@ export function maybeRenderOutbound(
   if (!richRenderEnabled(env)) return { text, mode: "markdown", degradations: [] };
   return renderOutbound(text, maxLen);
 }
+
+/**
+ * Flag-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
+ * (GFM-special chars gain a leading `\`) GROWS a chunk: a raw body sized just
+ * under `maxLen` can escape PAST it. `renderSafe` handles that by degrading
+ * the WHOLE document to `mode: "plain"` (raw source, no rich wrapper) — it
+ * never re-splits a multi-block body. The send path then ships that plain
+ * body through the 4096-capped `sendMessage` endpoint, so a ~32k plain body
+ * is rejected by Telegram (`message is too long`) and the answer is dropped.
+ *
+ * This function closes that gap: it returns an ARRAY of pieces, EACH of which
+ * is guaranteed to fit its own wire cap —
+ *   - a `markdown` piece is `<= maxLen` (`renderSafe`'s own guarantee), and
+ *   - a `plain` piece is `<= PLAIN_TEXT_MAX_CHARS` (the plain endpoint's cap).
+ * Pieces are cut only at `splitMarkdownChunks`' safe boundaries, so a fenced
+ * code block or a table row is NEVER bisected. Re-splitting the RAW source and
+ * re-rendering each piece also RECOVERS rich formatting the whole-document
+ * 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.
+ */
+export function renderOutboundChunks(
+  text: string,
+  env: NodeJS.ProcessEnv = process.env,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+  plainMax: number = PLAIN_TEXT_MAX_CHARS,
+): RenderResult[] {
+  if (!richRenderEnabled(env)) {
+    return [{ text, mode: "markdown", degradations: [] }];
+  }
+
+  const whole = renderOutbound(text, maxLen);
+  // `markdown` mode from renderSafe is already `<= maxLen`; a `plain` result
+  // that fits the plain cap is a single deliverable piece too. Common case.
+  if (whole.mode === "markdown" && whole.text.length <= maxLen) return [whole];
+  if (whole.mode === "plain" && whole.text.length <= plainMax) return [whole];
+
+  // Oversize: re-split the RAW source at safe boundaries and re-render each
+  // piece. Each sub-piece is `<= maxLen` in raw form, so it usually escapes
+  // back under `maxLen` and renders as rich markdown; a piece whose escaped
+  // form STILL overflows (or an indivisible plain blob) is emitted as plain,
+  // further split to `plainMax` so it fits the plain endpoint.
+  const out: RenderResult[] = [];
+  for (const rawPiece of splitMarkdownChunks(text, maxLen)) {
+    const rendered = renderOutbound(rawPiece, maxLen);
+    if (rendered.mode === "markdown" && rendered.text.length <= maxLen) {
+      out.push(rendered);
+      continue;
+    }
+    // Plain piece — cap at the plain-endpoint limit. `renderSafe` returned the
+    // raw source for a plain result, so split that source (safe boundaries,
+    // never bisecting a fence/table) into `<= plainMax` slices.
+    for (const plainPiece of splitMarkdownChunks(rendered.text, plainMax)) {
+      out.push({ text: plainPiece, mode: "plain", degradations: rendered.degradations });
+    }
+  }
+  // Defensive: a degenerate input that split to nothing still yields one piece.
+  return out.length > 0 ? out : [whole];
+}

package/telegram-plugin/retry-api-call.ts

@@ -63,8 +63,48 @@ export interface RetryApiCallConfig {
   observer?: RetryObserver
   /** Optional log sink for flood-wait / network lines. */
   log?: (line: string) => void
+  /**
+   * Fires whenever a Telegram 429 flood-wait is observed, BEFORE the sleep.
+   * The circuit-breaker (#2923) persists the flood-wait window here so that
+   * a container restart during an active ban can suppress non-essential
+   * sends (boot cards) instead of feeding the same per-bot-token flood
+   * counter and prolonging the ban. Best-effort; a throw here is swallowed.
+   */
+  onFloodWait?: (retryAfterSec: number) => void
+}
+
+/**
+ * True when the thrown error is a LOCAL resource-exhaustion failure —
+ * ENOSPC (disk/tmpfs full), EDQUOT (quota), EIO, or ENOMEM — rather than a
+ * remote Telegram API failure. Issue #2923: an agent's tmpfs filling up
+ * wedges the outbound send's local staging step; retrying that as if it
+ * were a transient REMOTE failure hammers the Bot API and trips a per-bot
+ * flood ban. A local disk error must NOT drive remote retries — surface it
+ * as a distinct, non-retryable degraded state instead.
+ */
+export function isLocalResourceError(err: unknown): boolean {
+  const code = (err as { code?: unknown })?.code
+  if (typeof code === 'string' && ['ENOSPC', 'EDQUOT', 'EIO', 'ENOMEM'].includes(code)) {
+    return true
+  }
+  const msg = err instanceof Error ? err.message : String(err ?? '')
+  return (
+    // Word-boundaried so a substring can't false-match; covers the same set
+    // as the errno code list above (ENOSPC/EDQUOT/EIO/ENOMEM).
+    /\b(ENOSPC|EDQUOT|EIO|ENOMEM)\b/.test(msg) ||
+    /no space left on device/i.test(msg) ||
+    /disk quota exceeded/i.test(msg)
+  )
 }
 
+/**
+ * Marker error thrown when `retryApiCall` refuses to retry a LOCAL
+ * resource-exhaustion failure (#2923). Callers can detect this to surface a
+ * "degraded: local disk full" state rather than treating it like a remote
+ * send failure worth retrying.
+ */
+export const LOCAL_RESOURCE_EXHAUSTED = 'LOCAL_RESOURCE_EXHAUSTED'
+
 const DEFAULT_SLEEP = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
 
 /**
@@ -83,6 +123,7 @@ export function createRetryApiCall(
   const sleep = config.sleep ?? DEFAULT_SLEEP
   const observer = config.observer
   const log = config.log
+  const onFloodWait = config.onFloodWait
 
   return async function retryApiCall<T>(
     fn: () => Promise<T>,
@@ -96,12 +137,33 @@ export function createRetryApiCall(
         const msg = err instanceof Error ? err.message : String(err)
         const desc = isGrammyErr ? (err as GrammyError).description : msg
 
+        // LOCAL resource exhaustion (#2923) — ENOSPC/EDQUOT/EIO/ENOMEM. This
+        // is a LOCAL disk/memory failure, not a remote API failure: retrying
+        // it in a tight loop is exactly what tripped the per-bot flood ban.
+        // Do NOT retry. Throw a distinct, non-retryable marker so the caller
+        // surfaces a degraded "local disk full" state and backs off hard.
+        if (isLocalResourceError(err)) {
+          log?.(
+            `telegram gateway: LOCAL resource exhaustion (${(err as { code?: string }).code ?? 'disk/mem'}) — ` +
+              `not retrying the send (would feed a flood ban); surfacing degraded state\n`,
+          )
+          observer?.onGiveUp?.({ attempts: attempt + 1, error: err })
+          throw Object.assign(new Error(LOCAL_RESOURCE_EXHAUSTED), { original: err })
+        }
+
         // Flood-wait — sleep retry_after and try again.
         if (isGrammyErr && (err as GrammyError).error_code === 429) {
           const retryAfter = Number(
             (err as GrammyError).parameters?.retry_after ?? 5,
           )
           const delayMs = retryAfter * 1000
+          // Persist the flood window so a restart during the ban can suppress
+          // non-essential sends instead of extending it (#2923 circuit breaker).
+          try {
+            onFloodWait?.(retryAfter)
+          } catch {
+            /* best-effort — never let the breaker hook break the retry path */
+          }
           log?.(`telegram gateway: 429 rate limited, waiting ${retryAfter}s\n`)
           observer?.onRetry?.({ attempt, reason: 'flood_wait', delayMs })
           await sleep(delayMs)

package/telegram-plugin/session-tail.ts

@@ -42,6 +42,7 @@ function isMultiAgentEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
 }
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
 import { createToolLabelSidecar, type ToolLabelSidecar } from './tool-label-sidecar.js'
+import { isModelSentinel } from './model-label.js'
 
 /** Match Claude Code's cli.js VX() function. */
 export function sanitizeCwdToProjectName(cwd: string): string {
@@ -92,6 +93,13 @@ export type SessionEvent =
   | { kind: 'enqueue'; chatId: string | null; messageId: string | null; threadId: string | null; rawContent: string; isSync?: boolean }
   | { kind: 'dequeue' }
   | { kind: 'thinking' }
+  // Live model in use for the MAIN session, extracted from `message.model` on
+  // each `type:"assistant"` transcript line (the exact model that served that
+  // API call). Emitted FIRST among a line's events so a card rendered on the
+  // same batch already reflects the current model. Sentinels (`<synthetic>` on
+  // compaction lines, fixture junk) are filtered at projection — see
+  // isModelSentinel — so this only ever carries a real resolved model id.
+  | { kind: 'model'; model: string }
   | { kind: 'tool_use'; toolName: string; toolUseId?: string | null; input?: Record<string, unknown>; precomputedLabel?: string }
   // Real-time tool label from the PreToolUse-hook sidecar — fires when the
   // hook writes the label (synchronous at tool-call time), independent of
@@ -115,6 +123,11 @@ export type SessionEvent =
   // filename stem (e.g. "aac6f1…"). Routed through the same ingest path
   // as parent events; the reducer fans them out to per-sub-agent state.
   | { kind: 'sub_agent_started'; agentId: string; firstPromptText: string; subagentType?: string }
+  // Live model in use for a SUB-AGENT, extracted from `message.model` on each
+  // of its `type:"assistant"` transcript lines. Same contract as the main
+  // `model` kind (sentinel-filtered, emitted first) but agent-scoped so the
+  // watcher can track it per WorkerEntry and thread it onto the worker card.
+  | { kind: 'sub_agent_model'; agentId: string; model: string }
   | { kind: 'sub_agent_tool_use'; agentId: string; toolUseId: string | null; toolName: string; input?: Record<string, unknown>; precomputedLabel?: string }
   // Same shared contract as the main-agent `text` kind — see its doc above
   // (including the `lastInMessage` projection-artifact note). The wire-kind
@@ -320,6 +333,15 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     const content = message?.content as Array<Record<string, unknown>> | undefined
     if (!Array.isArray(content)) return []
     const events: SessionEvent[] = []
+    // Live model capture: `message.model` is the exact resolved model that
+    // served THIS assistant API call. Emit it FIRST (before the content events)
+    // so a card rendered on the same read batch already carries the current
+    // model. Sentinels (`<synthetic>` on compaction lines, fixture junk) are
+    // skipped — the reducer keeps the last real value.
+    const mainModel = message?.model
+    if (typeof mainModel === 'string' && !isModelSentinel(mainModel)) {
+      events.push({ kind: 'model', model: mainModel })
+    }
     // Text→narrative projection comes from the ONE shared kernel
     // (projectAssistantTextBlocks): it owns the empty-drop + blockIndex +
     // lastInMessage contract. We emit its events at their source positions
@@ -468,6 +490,12 @@ export function projectSubagentLine(
     const content = message?.content as Array<Record<string, unknown>> | undefined
     if (!Array.isArray(content)) return []
     const events: SessionEvent[] = []
+    // Live model capture (sub-agent tier): same contract as the main-agent
+    // branch — emit the sub-agent's resolved model first, sentinel-filtered.
+    const subModel = message?.model
+    if (typeof subModel === 'string' && !isModelSentinel(subModel)) {
+      events.push({ kind: 'sub_agent_model', agentId, model: subModel })
+    }
     // Text→narrative projection comes from the SAME shared kernel as the
     // main agent (projectAssistantTextBlocks): one source for the empty-drop
     // + blockIndex + lastInMessage contract. The `make` adapter only changes

package/telegram-plugin/shared/bot-runtime.ts

@@ -29,6 +29,7 @@ import { createHash } from 'crypto'
 import { AsyncLocalStorage } from 'async_hooks'
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
 import { createRetryApiCall } from '../retry-api-call.js'
+import { makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
@@ -149,9 +150,15 @@ export function installTgPostLogger(bot: Bot): void {
  * Usage:
  *   const robustApiCall = createRobustApiCall()
  */
-export function createRobustApiCall() {
+export function createRobustApiCall(opts: { floodStatePath?: string } = {}) {
   return createRetryApiCall({
     log: (line) => process.stderr.write(line),
+    // #2923: persist every observed 429 flood-wait window so a restart during
+    // the ban can suppress non-essential sends (boot cards) instead of feeding
+    // the per-bot flood counter and prolonging the ban.
+    ...(opts.floodStatePath
+      ? { onFloodWait: makeFloodWaitRecorder(opts.floodStatePath) }
+      : {}),
   })
 }
 

package/telegram-plugin/silence-poke.ts

@@ -423,6 +423,20 @@ export function formatFrameworkFallbackText(
   return null
 }
 
+/**
+ * #2995 — the LONGEST-running in-flight tool for a turn key, or null when
+ * none is tracked. Read-only accessor over `inFlightTools` for the
+ * mid-flight busy-ack: the gateway needs the blocking step's name/label
+ * and its age to decide whether (and how) to ack a buffered mid-turn
+ * inbound. Does not touch the silence clock.
+ */
+export function longestInFlightTool(key: string, now: number): ToolSnapshot | null {
+  const s = state.get(key)
+  if (s == null) return null
+  const snaps = snapshotInFlight(s, now)
+  return snaps.length > 0 ? snaps[0]! : null
+}
+
 /** Snapshot in-flight tools sorted longest-running first — for the honest
  *  floor/fallback message body. */
 function snapshotInFlight(s: SilencePokeState, now: number): ToolSnapshot[] {

package/telegram-plugin/silent-end.ts

@@ -60,6 +60,8 @@ export interface SilentEndDeps {
    * never suppress on doubt.
    */
   hasOutboundDeliveredSince?: (chatId: string, sinceMs: number, threadId?: number | null) => boolean
+  /** Wall-clock now, ms. Defaults to `Date.now`; injectable for tests. */
+  now?: () => number
 }
 
 /**
@@ -80,6 +82,31 @@ export interface SilentEndDeps {
  */
 export const SILENT_END_MAX_RETRIES = 2
 
+/**
+ * Fix #8 (adversarial-validation progress-card fix pass): `turnKey` is the
+ * STABLE `statusKey(chatId, threadId)` — it never changes across turns on
+ * the same chat/thread — so `writeSilentEndState`'s "inherit retryCount IFF
+ * turnKey matches" rule has no per-turn discriminator on its own. Normally
+ * that's fine because `clearSilentEndState` always fires the moment a reply
+ * lands, wiping the exhausted record before the next turn starts. But if the
+ * gateway's own exhaust-read-and-clear is bypassed (crash/interrupt mid-turn,
+ * `gateway.ts` ~turn_end handler never runs), an exhausted
+ * (`retryCount >= SILENT_END_MAX_RETRIES`) record can survive into a LATER,
+ * unrelated turn. That later turn's first silent-end would then misread the
+ * old record as "this turn already exhausted its ladder" and skip its own
+ * re-prompt entirely.
+ *
+ * A record legitimately re-written within one turn's own retry ladder is
+ * always fresh (each Stop-hook block re-writes `timestamp`), so bounding by
+ * age is a safe, cheap staleness signal that doesn't require a new identity
+ * field: any record older than a turn's plausible lifetime could not still
+ * be "this turn's" in-flight retry state, and is therefore stale-carryover,
+ * not an active ladder. 30 minutes comfortably exceeds any real single-turn
+ * Stop-hook retry cycle (seconds, not minutes) while staying well inside the
+ * fleet's other staleness bounds (e.g. the 3h boot-resume window).
+ */
+export const SILENT_END_STALE_RECORD_MAX_AGE_MS = 30 * 60_000
+
 /**
  * User-facing fallback text delivered when a user-message turn ends with no
  * final answer AND the deterministic Stop-hook re-prompt has already been
@@ -313,12 +340,30 @@ export function recordSilentTurnEnd(
     // If so, the record is satisfied-but-misdetected — drop it silently
     // and let this dark turn start its OWN fresh retry cycle instead of
     // inheriting someone else's spent budget.
-    if (deps?.hasOutboundDeliveredSince?.(args.chatId, prev.timestamp, args.threadId)) {
+    // Fix #8: age-based staleness bound. `turnKey` has no per-turn nonce
+    // (see SILENT_END_STALE_RECORD_MAX_AGE_MS doc), so a record whose
+    // `timestamp` is older than a turn's plausible lifetime cannot belong to
+    // THIS dark turn's own retry ladder even absent any delivery evidence —
+    // it's carryover from a prior turn whose gateway-side clear was
+    // bypassed (crash/interrupt). Check this before (and independent of)
+    // the delivery-based check below so a bypassed-clear record is caught
+    // even when no reply was ever delivered on the chat/thread at all.
+    const now = deps?.now?.() ?? Date.now()
+    const staleByAge = now - prev.timestamp > SILENT_END_STALE_RECORD_MAX_AGE_MS
+    if (
+      staleByAge ||
+      deps?.hasOutboundDeliveredSince?.(args.chatId, prev.timestamp, args.threadId)
+    ) {
       emitLog(
         deps,
-        `silent-end: stale exhausted record for turnKey=${args.turnKey} ` +
-          `(retryCount=${prev.retryCount}) but a reply was delivered since ` +
-          `${prev.timestamp} — treating as satisfied-but-misdetected, not exhausted\n`,
+        staleByAge
+          ? `silent-end: stale exhausted record for turnKey=${args.turnKey} ` +
+              `(retryCount=${prev.retryCount}, age=${now - prev.timestamp}ms > ` +
+              `${SILENT_END_STALE_RECORD_MAX_AGE_MS}ms) — treating as carryover ` +
+              `from a prior turn, not exhausted\n`
+          : `silent-end: stale exhausted record for turnKey=${args.turnKey} ` +
+              `(retryCount=${prev.retryCount}) but a reply was delivered since ` +
+              `${prev.timestamp} — treating as satisfied-but-misdetected, not exhausted\n`,
       )
       // MUST clear before writing (adversarial review of #2892):
       // writeSilentEndState re-inherits retryCount whenever the on-disk

package/telegram-plugin/stream-controller.ts

@@ -21,7 +21,7 @@
 
 import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
-import { maybeRenderOutbound } from './render/rich-render.js'
+import { renderOutboundChunks } from './render/rich-render.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -223,81 +223,199 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // `format:'text'` stream (plain sendMessage, no rich wrapper).
   // sendRichMessage does NOT accept link_preview_options (rich messages
   // control previews via entity detection), so strip it for the rich path.
-  const doSend = (text: string, opts: StreamSendOpts) => {
-    if (literalText) return bot.api.sendMessage(chatId, text, opts)
-    // Flag-gated rich render (`SWITCHROOM_RICH_RENDER`, default OFF — returns
-    // the text untouched as markdown when off, so this is a no-op for every
-    // agent until an operator opts in). A `plain` result (oversized/unsafe
-    // content renderSafe declined to emit as rich) sends WITHOUT the wrapper.
-    const rendered = maybeRenderOutbound(text)
-    if (rendered.mode === 'plain') return bot.api.sendMessage(chatId, rendered.text, opts)
+  // Render the outbound body into 1+ wire-cap-respecting pieces. The common
+  // case is a SINGLE piece whose output is identical to the pre-existing
+  // `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.
+  const renderPieces = (text: string): { text: string; rich: boolean }[] => {
+    if (literalText) return [{ text, rich: false }]
+    // A `plain`-mode piece (oversized/unsafe content renderSafe declined to
+    // emit as rich) sends WITHOUT the rich wrapper.
+    return renderOutboundChunks(text).map((r) => ({ text: r.text, rich: r.mode !== 'plain' }))
+  }
+  // Send ONE rendered piece. Rich pieces go through sendRichMessage (with
+  // link_preview_options stripped — rich messages control previews via entity
+  // detection); plain pieces (and literal streams) through sendMessage.
+  const sendPiece = (piece: { text: string; rich: boolean }, opts: StreamSendOpts) => {
+    if (!piece.rich) return bot.api.sendMessage(chatId, piece.text, opts)
     const richOpts = { ...opts }
     delete richOpts.link_preview_options
-    return bot.api.sendRichMessage(chatId, richMessage(rendered.text), richOpts)
+    return bot.api.sendRichMessage(chatId, richMessage(piece.text), richOpts)
   }
-  const doEdit = (id: number, text: string, opts: StreamSendOpts) => {
-    if (literalText) return bot.api.editMessageText(chatId, id, text, opts)
-    const rendered = maybeRenderOutbound(text)
-    if (rendered.mode === 'plain') return bot.api.editMessageText(chatId, id, rendered.text, opts)
-    return bot.api.editMessageText(chatId, id, richMessage(rendered.text), opts)
+  const editPiece = (id: number, piece: { text: string; rich: boolean }, opts: StreamSendOpts) => {
+    if (!piece.rich) return bot.api.editMessageText(chatId, id, piece.text, opts)
+    return bot.api.editMessageText(chatId, id, richMessage(piece.text), opts)
+  }
+
+  // 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
+  // parks pieces[1..n] as follow-up messages. The draft-stream edit callback
+  // fires on EVERY throttled flush as a streamed answer grows, so we MUST NOT
+  // re-send those tails each tick (that flooded the chat with duplicates — the
+  // blocker this fix closes). Instead we remember each tail's message_id the
+  // first time it is emitted and edit it in place on later flushes; a tail that
+  // did not exist on a prior flush (the piece count grew) is sent fresh once.
+  // End state after finalize: anchor + one message per tail piece, no dupes.
+  const tailIds: number[] = []
+  const tailLastText: string[] = []
+
+  // Emit or update a single tail piece (0-based index `ti` = piece index - 1).
+  // Sends a fresh message the first time; edits in place (skipping unchanged
+  // 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> => {
+    const existingId = tailIds[ti]
+    if (existingId != null) {
+      if (tailLastText[ti] === piece.text) return // unchanged — skip the API call
+      try {
+        await retry(() => editPiece(existingId, piece, baseOpts), { threadId, chat_id: chatId })
+        tailLastText[ti] = piece.text
+        onEdit?.(existingId, piece.text.length)
+      } catch (err) {
+        if (!literalText && piece.rich && isParseEntitiesError(err)) {
+          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(
+            () => bot.api.editMessageText(chatId, existingId, piece.text, baseOpts),
+            { threadId, chat_id: chatId },
+          )
+          tailLastText[ti] = piece.text
+          onEdit?.(existingId, piece.text.length)
+        } else {
+          // Best-effort continue: leave tailLastText[ti] stale so the next
+          // flush retries this piece, and surface the partial delivery loudly.
+          warn?.(
+            `stream-controller: tail-piece #${ti + 1} edit FAILED (id=${existingId}) — partial delivery, this piece may be stale (${err instanceof Error ? err.message : String(err)})`,
+          )
+        }
+      }
+      return
+    }
+    // First emission of this tail piece → a fresh follow-up message.
+    try {
+      const sent = await retry(() => sendPiece(piece, sendOpts), { threadId, chat_id: chatId })
+      tailIds[ti] = sent.message_id
+      tailLastText[ti] = piece.text
+      onSend?.(sent.message_id, piece.text.length)
+    } catch (err) {
+      if (!literalText && piece.rich && isParseEntitiesError(err)) {
+        warn?.(
+          `stream-controller: tail-piece #${ti + 1} send parse-entities rejected — sending as plain text (${err instanceof Error ? err.message : String(err)})`,
+        )
+        const sent = await retry(
+          () => bot.api.sendMessage(chatId, piece.text, sendOpts),
+          { threadId, chat_id: chatId },
+        )
+        tailIds[ti] = sent.message_id
+        tailLastText[ti] = piece.text
+        onSend?.(sent.message_id, piece.text.length)
+      } else {
+        // Best-effort continue: no id recorded, so the next flush re-attempts
+        // this piece rather than silently dropping pieces K..N (concern C1).
+        warn?.(
+          `stream-controller: tail-piece #${ti + 1} send FAILED — partial delivery, this and later pieces may be missing this flush (${err instanceof Error ? err.message : String(err)})`,
+        )
+      }
+    }
   }
 
   return 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
+      // follow-up messages via upsertTail. For the common single-piece case
+      // this is exactly one send.
+      const pieces = renderPieces(text)
+      const head = pieces[0]
+      let anchorId: number | undefined
       try {
         const sent = await retry(
-          () => doSend(text, sendOpts),
+          () => sendPiece(head, sendOpts),
           { threadId, chat_id: chatId },
         )
-        onSend?.(sent.message_id, text.length)
-        return sent.message_id
+        anchorId = sent.message_id
       } catch (err) {
-        if (!literalText && isParseEntitiesError(err)) {
-          // First send rejected because the markdown couldn't be parsed.
-          // There is no message_id to edit (the send 400'd before any
-          // message was created), so a single fresh send as PLAIN text
-          // (no rich wrapper, so the parser never runs) is the correct
-          // recovery — see issue #657. The raw markdown source is itself
-          // readable, so we send it verbatim.
+        if (!literalText && head.rich && isParseEntitiesError(err)) {
+          // Piece rejected because its markdown couldn't be parsed. There is
+          // no message_id to edit (the send 400'd before any message was
+          // created), so recover with a single fresh PLAIN send of the same
+          // body (no rich wrapper, so the parser never runs) — see issue #657.
           warn?.(
             `stream-controller: send parse-entities rejected — retrying once as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
+          // Resend the RAW source verbatim (readable, and the exact
+          // pre-existing #657 contract) rather than the escaped/rendered
+          // body. For a single-piece stream (the common case) this is the
+          // whole message; for a rare oversize split the head falls back to
+          // its own body and each tail to its own body below.
+          const fallbackBody = pieces.length === 1 ? text : head.text
           const sent = await retry(
-            () => bot.api.sendMessage(chatId, text, sendOpts),
+            () => bot.api.sendMessage(chatId, fallbackBody, sendOpts),
             { threadId, chat_id: chatId },
           )
-          onSend?.(sent.message_id, text.length)
-          return sent.message_id
+          anchorId = sent.message_id
+        } else {
+          throw err
         }
-        throw err
       }
+      // C2: report the ACTUAL emitted anchor-piece length, not the full body
+      // length — the anchor only holds the head piece, and the tails report
+      // their own lengths via upsertTail.
+      onSend?.(anchorId as number, head.text.length)
+      // Park overflow pieces (first-time send records their ids for reuse).
+      for (let pi = 1; pi < pieces.length; pi++) {
+        await upsertTail(pi - 1, pieces[pi])
+      }
+      return anchorId as number
     },
     async (id, text) => {
+      const pieces = renderPieces(text)
+      const head = pieces[0]
+      // Edit the anchor message in place with the FIRST piece.
       try {
         await retry(
-          () => doEdit(id, text, baseOpts),
+          () => editPiece(id, head, baseOpts),
           { threadId, chat_id: chatId },
         )
-        onEdit?.(id, text.length)
+        // C2: report the actual head-piece length, not the full body length.
+        onEdit?.(id, head.text.length)
       } catch (err) {
-        if (!literalText && isParseEntitiesError(err)) {
+        if (!literalText && head.rich && isParseEntitiesError(err)) {
           // Edit rejected because the markdown couldn't be parsed — DO NOT
           // send a fresh message. The whole point of issue #657 is that the
           // previous implementation sent a duplicate message every time a
           // parse rejection fired. Retry the edit on the SAME message_id as
-          // PLAIN text (no rich wrapper, so the parser never runs). The raw
-          // markdown source is itself readable, so we send it verbatim.
+          // PLAIN text (no rich wrapper, so the parser never runs).
           warn?.(
             `stream-controller: edit parse-entities rejected — retrying same id=${id} as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
+          // Re-edit the SAME id with the RAW source verbatim (the exact #657
+          // 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(
-            () => bot.api.editMessageText(chatId, id, text, baseOpts),
+            () => bot.api.editMessageText(chatId, id, fallbackBody, baseOpts),
             { threadId, chat_id: chatId },
           )
-          onEdit?.(id, text.length)
-          return
+          onEdit?.(id, head.text.length)
+        } else {
+          throw err
         }
-        throw err
+      }
+      // Oversize tail: the anchor message holds only the first piece. On EVERY
+      // edit flush we UPDATE the parked tail messages in place (or send a tail
+      // 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.
+      for (let pi = 1; pi < pieces.length; pi++) {
+        await upsertTail(pi - 1, pieces[pi])
       }
     },
     {