switchroom 0.18.7 → 0.18.9

package/telegram-plugin/pty-partial-handler.ts

@@ -32,6 +32,7 @@ export type PtyPartialAction =
   | 'dedup-skip' // same text as the previous partial; no-op
   | 'update-existing' // pushed into an already-live stream
   | 'update-new' // created a new stream and pushed into it
+  | 'error-suppressed' // raw API-error TUI line; dropped (issue #2922 Bug 3)
 
 export interface PtyHandlerState {
   /**
@@ -84,6 +85,32 @@ export interface PtyHandlerDeps {
   writeError?: (line: string) => void
 }
 
+/**
+ * Detect a raw API-error line scraped from Claude Code's TUI — issue #2922
+ * Bug 3. When the model 429s / errors, the CLI renders an `API Error: … ·
+ * b'{"type":"error",…}'` line into the terminal; the PTY tail would otherwise
+ * scrape it as the assistant reply and relay the raw bytes verbatim to chat.
+ * These lines are suppressed here so the model-unavailable operator-event
+ * pipeline owns the user-facing rendering (a clean ⚠️ card), not the raw tail.
+ *
+ * Kept deliberately tight (anchored error markers, not any mention of "error")
+ * so genuine assistant text that happens to discuss errors is NOT swallowed.
+ */
+export function looksLikeRawApiError(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const lower = text.toLowerCase()
+  return (
+    lower.includes('api error:')
+    || lower.includes('"type":"error"')
+    || lower.includes("'type': 'error'")
+    || lower.includes('rate_limit_error')
+    || lower.includes('overloaded_error')
+    || lower.includes('"is_error":true')
+    // The CLI's Python-style raw-body render: · b'{...}'
+    || / b'\{/.test(text)
+  )
+}
+
 function streamKey(chatId: string, threadId?: number): string {
   // Canonical chat-key derivation lives in gateway/chat-key.ts — keep this
   // expression in lockstep (treats 0/null/undefined the same). See #1564.
@@ -96,6 +123,13 @@ function streamKey(chatId: string, threadId?: number): string {
  *
  * Returns the action taken. All state mutation happens through the
  * supplied `state` object so callers can inspect before/after.
+ *
+ * NOTE on `looksLikeRawApiError` suppression (#2922 Bug 3): this is
+ * *preview-only* scope. PTY partials are the live-streaming terminal tail,
+ * never the authoritative reply (that flows through the operator-event /
+ * reply pipelines). So the worst case of an over-eager match here is a
+ * missing streaming flicker for one snapshot — NOT a dropped user answer.
+ * That asymmetry is why the matcher can stay aggressive on raw error shapes.
  */
 export function handlePtyPartialPure(
   text: string,
@@ -132,6 +166,11 @@ export function handlePtyPartialPure(
 
   if (suppressed) return 'suppressed'
 
+  // Drop raw API-error TUI lines so they never leak to chat as the reply —
+  // the model-unavailable card (operator-event pipeline) renders these
+  // instead. See issue #2922 Bug 3.
+  if (looksLikeRawApiError(text)) return 'error-suppressed'
+
   if (state.lastPtyPreviewByChat.get(sKey) === text) return 'dedup-skip'
 
   const isFirst = !state.lastPtyPreviewByChat.has(sKey)

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/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/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])
       }
     },
     {

package/telegram-plugin/tests/activity-card-store.test.ts

@@ -30,6 +30,7 @@
  */
 import { describe, it, expect } from 'vitest'
 import {
+  BOOT_UNPIN_MAX_ATTEMPTS,
   loadActivityCards,
   persistActivityCards,
   writeActivityCardRecord,
@@ -314,9 +315,10 @@ describe('runActivityCardBootReaper — transport-boundary outcome tests', () =>
     expect(loadActivityCards(PATH, fs)).toEqual([])
   })
 
-  it('a failing unpin (already unpinned / no rights) is non-fatal and does not re-run the edit', async () => {
+  it('retry-safe (#3001): a failing unpin is non-fatal, does not re-run the edit, and RETAINS the record for a next-boot unpin retry', async () => {
     const { fs } = memFs()
-    writeActivityCardRecord(PATH, fs, card())
+    const rec = card()
+    writeActivityCardRecord(PATH, fs, rec)
     let editCalls = 0
     const res = await runActivityCardBootReaper({
       path: PATH,
@@ -328,9 +330,52 @@ describe('runActivityCardBootReaper — transport-boundary outcome tests', () =>
       unpinCard: async () => {
         throw new Error('message to unpin not found')
       },
+      log: () => {},
     })
     expect(res).toEqual({ finalized: 1, vanished: 0, unpinned: 0, total: 1 })
     expect(editCalls).toBe(1)
+    // The record is retained (not forfeited) so the next boot retries the
+    // idempotent unpin — flagged so it can never re-run the finalize edit.
+    expect(loadActivityCards(PATH, fs)).toEqual([
+      { ...rec, finalizeAttempted: true, unpinAttempts: 1 },
+    ])
+
+    // Second boot: the retained record retries ONLY the unpin (edit stays
+    // at-most-once); on success the record is finally dropped.
+    let secondBootEdits = 0
+    const res2 = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        secondBootEdits++
+        return { ok: true }
+      },
+      unpinCard: async () => ({ ok: true }),
+      log: () => {},
+    })
+    expect(secondBootEdits).toBe(0)
+    expect(res2).toEqual({ finalized: 0, vanished: 0, unpinned: 1, total: 1 })
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('retry-safe (#3001): the unpin retry is forfeited at BOOT_UNPIN_MAX_ATTEMPTS', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(
+      PATH,
+      fs,
+      card({ finalizeAttempted: true, unpinAttempts: BOOT_UNPIN_MAX_ATTEMPTS - 1 }),
+    )
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => ({ ok: true }),
+      unpinCard: async () => {
+        throw new Error('still no rights')
+      },
+      log: () => {},
+    })
+    // Final attempt failed — record forfeited so it cannot re-fail every boot.
+    expect(res).toEqual({ finalized: 0, vanished: 0, unpinned: 0, total: 1 })
     expect(loadActivityCards(PATH, fs)).toEqual([])
   })