switchroom 0.19.41 → 0.19.43

package/telegram-plugin/outbox.ts

@@ -65,6 +65,19 @@ import {
 } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+// W1-d (#3865). The audience vocabulary and its resolution rule live in ONE
+// shared pure module because the unbundled Stop hooks (which stamp it) and this
+// bundled gateway code (which persists and enforces it) must agree exactly. A
+// hand-synced second copy here would be a leak waiting on a drift.
+import type { Audience } from './hooks/audience-classify.mjs'
+// #4141: the provenance-framing rule lives in the same shared pure module, for
+// the same reason — the decision must be one implementation, not two.
+import {
+  applyReplyThrowFraming,
+  shouldFrameReplyThrow,
+} from './hooks/audience-classify.mjs'
+
+export type { Audience }
 
 /** One captured, not-yet-delivered final message for a single main-session turn. */
 export interface OutboxRecord {
@@ -113,6 +126,42 @@ export interface OutboxRecord {
    * or in a sweep journal entry — is direct evidence of a regression.
    */
   replyAlreadyDeliveredThisTurn?: boolean
+  /**
+   * W1-d (#3865): WHO this text is addressed to, decided at capture time by
+   * `hooks/audience-classify.mjs` (`decideCaptureAudience`) — the only point in
+   * the pipeline that can still see the turn that produced it.
+   *
+   * `'internal'` means the text is the agent's own working notes (the #3861
+   * shape: the reply tool threw, nobody was waiting, and the structurally-
+   * selected terminal prose run is orchestration narration rather than an
+   * answer). Such a record is journaled and inspectable but MUST NEVER reach a
+   * chat — the sweep drops it at entry selection.
+   *
+   * OPTIONAL for legacy reasons: every record written before this field
+   * existed has no `audience`, and `resolveRecordAudience` maps missing (and
+   * any non-`'internal'` value) to `'user'`. Suppression requires an
+   * affirmative tag; absence is never evidence.
+   */
+  audience?: Audience
+  /**
+   * W1-d follow-up (#4141): did one of this turn's reply-tool calls come back
+   * `is_error: true`? Stamped at capture by `hooks/silent-end-scan.mjs` (which
+   * reads the `tool_result` blocks) and persisted here so the SWEEP — hours
+   * later, in another process, with the transcript long gone — can still state
+   * this text's provenance.
+   *
+   * This is the raw structural SIGNAL, not a verdict. `audience` already
+   * consumed it once (combined with the obligation state) to decide
+   * suppression; the sweep consumes it again, on its own, to decide FRAMING for
+   * the records suppression deliberately does NOT catch — the foreground case,
+   * where the reply threw but someone is provably still waiting, so the record
+   * is `'user'` and MUST deliver.
+   *
+   * OPTIONAL: absent on every pre-#4141 record and on gateway-authored records
+   * (`gateway/flood-reply-queue.ts`), both of which deliver unframed. Only an
+   * exact boolean `true` changes anything — see `shouldFrameReplyThrow`.
+   */
+  replyToolThrewThisTurn?: boolean
 }
 
 /** One line of the delivered-keys journal (`outbox/delivered.jsonl`). */
@@ -131,6 +180,30 @@ export interface DeliveredEntry {
   deliverySource?: 'sweep' | 'reply-tool' | 'flush'
   /** #3510 instrumentation: see `OutboxRecord.replyAlreadyDeliveredThisTurn`. */
   replyAlreadyDeliveredThisTurn?: boolean
+  /** W1-d (#3865): the record's audience, carried onto the journal line. */
+  audience?: Audience
+  /**
+   * W1-d (#3865): this journal line is a TERMINAL SUPPRESSION, not a delivery.
+   * The sweep withheld an `'internal'` record from the chat and wrote this line
+   * so the nonce is terminally claimed (a second tick sends nothing) and the
+   * decision is durably auditable.
+   *
+   * This is what keeps suppression honest: the outcome is recorded as an
+   * explicit, named state rather than as an absence. `tgMessageId` is absent on
+   * these lines because nothing was sent.
+   */
+  suppressedAudience?: Audience
+  /**
+   * W1-d follow-up (#4141): this delivery carried the reply-throw provenance
+   * banner (`REPLY_THROW_PROVENANCE_NOTICE`) in front of the captured prose.
+   *
+   * Durable and terminal, for the same reason `suppressedAudience` is: framing
+   * changes what a human sees, so the outcome is recorded as an explicit named
+   * state on the journal line rather than being inferable only from a log line
+   * that may have rotated away. `tgMessageId` IS present on these lines — a
+   * framed delivery is a delivery.
+   */
+  framedProvenance?: 'reply-throw'
 }
 
 export function sha256Hex(s: string): string {
@@ -439,6 +512,13 @@ export interface OutboxSweepDecision {
   action: OutboxSweepAction
   /** The text to deliver (with any "(delayed)"/"(from background task)" prefix). */
   text?: string
+  /**
+   * W1-d follow-up (#4141): `text` carries the reply-throw provenance banner.
+   * Surfaced on the decision (rather than left implicit in a string compare) so
+   * the caller can journal the outcome and emit telemetry without re-deriving
+   * the rule.
+   */
+  framedProvenance?: 'reply-throw'
 }
 
 /**
@@ -456,7 +536,10 @@ export interface OutboxSweepDecision {
  *   send-delayed    — older than max-age; deliver with a "(delayed)" prefix, never drop.
  */
 export function decideOutboxSweep(input: {
-  record: Pick<OutboxRecord, 'turnNonce' | 'text' | 'createdAt'>
+  record: Pick<
+    OutboxRecord,
+    'turnNonce' | 'text' | 'createdAt' | 'replyToolThrewThisTurn'
+  >
   now: number
   deliveredNonces: Set<string>
   textAlreadyDelivered: boolean
@@ -476,6 +559,13 @@ export function decideOutboxSweep(input: {
    * `normalizeOutboundBody` (it sends via `bot.api.sendMessage` directly).
    */
   shownLedgerHit?: boolean
+  /**
+   * W1-d follow-up (#4141) kill switch for the reply-throw provenance banner.
+   * `false` restores the pre-change body byte-for-byte; the default is ON.
+   * Passed in rather than read from env here so this core stays pure and the
+   * revert-check can flip it in-process.
+   */
+  provenanceFraming?: boolean
 }): OutboxSweepDecision {
   const {
     record,
@@ -487,6 +577,7 @@ export function decideOutboxSweep(input: {
     quietMs = OUTBOX_QUIET_MS,
     maxAgeMs = OUTBOX_MAX_AGE_MS,
     shownLedgerHit = false,
+    provenanceFraming = true,
   } = input
   if (deliveredNonces.has(record.turnNonce)) return { action: 'skip-journaled' }
   if (shownLedgerHit) return { action: 'skip-ephemeral-shown' }
@@ -496,7 +587,17 @@ export function decideOutboxSweep(input: {
   if (!routable) return { action: 'skip-unroutable' }
   const delayed = age > maxAgeMs
   const prefix = (delayed ? '(delayed) ' : '') + routePrefix
-  return { action: delayed ? 'send-delayed' : 'send', text: prefix + record.text }
+  // #4141: the banner sits BETWEEN the delivery prefixes and the body — the
+  // prefixes describe the DELIVERY ("(delayed)", "(from background task)"),
+  // the banner describes the TEXT. It is additive only: it can never turn a
+  // send into a skip, so this branch cannot manufacture silence.
+  const framed = shouldFrameReplyThrow(record, { frameEnabled: provenanceFraming })
+  const body = framed ? applyReplyThrowFraming(record.text) : record.text
+  return {
+    action: delayed ? 'send-delayed' : 'send',
+    text: prefix + body,
+    ...(framed && body !== record.text ? { framedProvenance: 'reply-throw' as const } : {}),
+  }
 }
 
 export interface ResolvedChat {

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

@@ -28,7 +28,11 @@
 
 import { parse } from "./parse.js";
 import { renderSafe, type RenderResult } from "./render.js";
-import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
+import {
+  PLAIN_TEXT_MAX_CHARS,
+  RICH_MESSAGE_MAX_CHARS,
+  splitMarkdownChunks,
+} from "../format.js";
 
 /**
  * The legacy plain-text `sendMessage` / `editMessageText` wire cap (4096
@@ -38,8 +42,12 @@ import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
  * 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.
+ *
+ * Defined in `format.ts` (#4043) so the parse-reject plain FALLBACKS in the
+ * send path can share the one constant without importing the renderer;
+ * re-exported here for this module's existing importers.
  */
-export const PLAIN_TEXT_MAX_CHARS = 4096;
+export { PLAIN_TEXT_MAX_CHARS };
 
 /** Parse the `SWITCHROOM_RICH_RENDER` kill-switch value. Default ON; disabled
  *  only by an explicit falsey/off token (`0`/`false`/`off`/`no`,

package/telegram-plugin/reply-quote.ts

@@ -0,0 +1,150 @@
+/**
+ * Surgical quote-reply parameters (`reply_parameters.quote`).
+ *
+ * The `reply` / `stream_reply` tools document a `quote_text` argument: quote a
+ * specific fragment of the message being replied to, so the reply visibly
+ * anchors on that fragment instead of the whole message.
+ *
+ * WIRE SHAPE — the bug this module exists to make unrepeatable
+ * ------------------------------------------------------------
+ * Bot API `ReplyParameters` (https://core.telegram.org/bots/api#replyparameters):
+ *
+ *   quote           String   Quoted part of the message to be replied to;
+ *                            0-1024 characters after entities parsing.
+ *   quote_parse_mode String  Mode for parsing entities in the quote.
+ *   quote_entities   Array   Entities in the quote.
+ *   quote_position   Integer Position of the quote in the original message in
+ *                            UTF-16 code units.
+ *
+ * `quote` is a **String** and `quote_position` is a **separate sibling
+ * Integer**. Both send sites used to emit `quote: { text, position: 0 }` — an
+ * object — so Telegram rejected every quoted reply with
+ * `400 Bad Request: field "quote" must be of type String`, the reply threw, and
+ * the agent re-attempted a payload that could never be accepted. A fleet sweep
+ * of `tg-post method=sendRichMessage … status=err` lines found 378 of 384 total
+ * send failures were this one error (agent `overlord`, 2026-07-29 → 07-30, in
+ * retry bursts). The feature had never worked.
+ *
+ * DELIBERATE OMISSIONS
+ * --------------------
+ * - **No `quote_position`.** Telegram locates the quote text on its own; a
+ *   fabricated `0` is what encouraged the object shape in the first place, and
+ *   neither send site has a real position source (the model supplies text, not
+ *   an offset). A wrong position is worse than none: it either mislocates the
+ *   highlight or 400s.
+ * - **No `quote_parse_mode` / `quote_entities`, and therefore NO HTML
+ *   escaping.** With no parse mode the quote is matched as literal text, which
+ *   is exactly what `quote_text` carries (plain text the model copied out of
+ *   the user's message). Escaping it (`&` → `&`) would make the string stop
+ *   being an exact substring of the original and guarantee a rejection.
+ *
+ * REJECTION HANDLING
+ * ------------------
+ * The quote must be an exact substring of the target message; Telegram 400s
+ * when it isn't found. That is a *quote* failure, not an answer failure — the
+ * reply body is still correct and must still be delivered. {@link
+ * isQuoteRejectionError} classifies it and {@link dropQuoteFromSendOpts}
+ * produces the same options with the quote removed, so callers can retry once
+ * and land the reply as an ordinary (unquoted) reply.
+ */
+
+import { GrammyError } from 'grammy'
+
+import { isHtmlParseRejectError, isMessageTooLongError } from './retry-api-call.js'
+
+/** Bot API cap: `quote` is 0-1024 characters after entities parsing. */
+export const QUOTE_MAX_CHARS = 1024
+
+/**
+ * Normalize a caller-supplied `quote_text` into the string Telegram accepts, or
+ * `null` when there is nothing worth quoting.
+ *
+ * - empty / whitespace-only ⇒ `null` (an empty quote highlights nothing and is
+ *   a guaranteed rejection).
+ * - longer than {@link QUOTE_MAX_CHARS} ⇒ truncated. A PREFIX of an exact
+ *   substring is still an exact substring, so truncation still matches the
+ *   original message, whereas an over-length quote is a certain 400. The cut
+ *   never splits a surrogate pair (a lone surrogate is not valid UTF-8 on the
+ *   wire).
+ * - otherwise verbatim — never escaped, never trimmed (leading/trailing spaces
+ *   are part of the substring the user may have selected).
+ */
+export function normalizeQuoteText(quoteText: string | null | undefined): string | null {
+  if (typeof quoteText !== 'string') return null
+  if (quoteText.trim().length === 0) return null
+  if (quoteText.length <= QUOTE_MAX_CHARS) return quoteText
+  let end = QUOTE_MAX_CHARS
+  const code = quoteText.charCodeAt(end - 1)
+  // High surrogate at the cut boundary ⇒ drop it rather than emit half a pair.
+  if (code >= 0xd800 && code <= 0xdbff) end -= 1
+  return quoteText.slice(0, end)
+}
+
+/**
+ * Build the `reply_parameters` object for a reply to `messageId`, optionally
+ * carrying a surgical quote.
+ *
+ * This is the ONLY place the `quote` field is constructed. Both send sites (the
+ * `reply` chunk loop in `gateway/outbound-send-path.ts` and the `stream_reply`
+ * controller in `stream-controller.ts`) call it, so the wire shape cannot drift
+ * apart again.
+ */
+export function buildReplyParameters(
+  messageId: number,
+  quoteText?: string | null,
+): { message_id: number; quote?: string } {
+  const quote = normalizeQuoteText(quoteText)
+  return { message_id: messageId, ...(quote != null ? { quote } : {}) }
+}
+
+/**
+ * True when Telegram rejected the send because of the QUOTE, not the body.
+ *
+ * Covers the "quote isn't in the original message" family (the documented
+ * failure mode) and any other 400 naming the quote — matched on the word rather
+ * than one exact phrase, because the Bot API's wording for this class has
+ * changed before (`QUOTE_TEXT_INVALID` vs the prose form) and a missed match
+ * costs the whole answer.
+ *
+ * A BODY error must never be claimed here, though, and the word alone is not
+ * enough to tell them apart: `<blockquote>` in a rich body produces
+ * `can't parse entities: Can't find end tag corresponding to start tag
+ * "blockquote"` / `Unsupported start tag "blockquote"` — 400s that contain the
+ * substring "quote" but are PARSE failures. Claiming one would drop the quote
+ * and resend the same unparseable body, hit the same 400, and throw straight
+ * out of the caller's fallback ladder — losing the answer that the plain-text
+ * rescue would otherwise have delivered. So defer to the body classifiers
+ * first, exactly as `isHtmlParseRejectError` defers to `isMessageTooLongError`
+ * (retry-api-call.ts) for the same reason. No false negative results: the real
+ * quote rejections (`QUOTE_TEXT_INVALID`, "message quote not found") contain
+ * neither a parse phrase nor a length phrase.
+ */
+export function isQuoteRejectionError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  if (isHtmlParseRejectError(err) || isMessageTooLongError(err)) return false
+  return (err.description || '').toLowerCase().includes('quote')
+}
+
+/** True when `opts` carries a `reply_parameters.quote`. Structural on purpose:
+ *  the reply path builds untyped `Record<string, unknown>` send options and the
+ *  stream path a typed `StreamSendOpts`, and both must be checkable. */
+export function sendOptsHaveQuote(opts: object): boolean {
+  const rp = (opts as { reply_parameters?: { quote?: unknown } }).reply_parameters
+  return rp != null && typeof rp === 'object' && rp.quote != null
+}
+
+/**
+ * Same send options with the surgical quote removed — the retry payload after a
+ * {@link isQuoteRejectionError}. Everything else (reply target, thread, markup,
+ * notification) is preserved, so the answer still lands as a reply to the right
+ * message; only the highlight is sacrificed.
+ */
+export function dropQuoteFromSendOpts<T extends object>(opts: T): T {
+  if (!sendOptsHaveQuote(opts)) return { ...opts }
+  const rp = { ...((opts as { reply_parameters: Record<string, unknown> }).reply_parameters) }
+  delete rp.quote
+  delete rp.quote_parse_mode
+  delete rp.quote_entities
+  delete rp.quote_position
+  return { ...opts, reply_parameters: rp }
+}

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

@@ -22,11 +22,206 @@
  *   | GrammyError 400 "message to edit not found"   | swallow, return undefined                 |
  *   | GrammyError 400 "message to delete not found" | swallow, return undefined                 |
  *   | GrammyError 400 "thread not found" (w/ opts)  | throw `THREAD_NOT_FOUND` wrapper          |
- *   | Network error (fetch failed / ECONN…)         | exponential backoff retry, 3 attempts     |
+ *   | HttpError (grammy transport failure)          | exponential backoff retry, 3 attempts     |
+ *   | Raw network error (fetch failed / ECONN…)     | exponential backoff retry, 3 attempts     |
+ *   | ENOSPC/EDQUOT/EIO/ENOMEM (local exhaustion)   | throw `LOCAL_RESOURCE_EXHAUSTED`, no retry|
  *   | Anything else                                 | rethrow immediately                       |
+ *
+ * The three "swallow" rows are the DEFAULT, not the law: a call site whose
+ * contract is "did the target message survive?" sets `rethrowBenign400: true`
+ * and gets the original `GrammyError` instead, so it can classify the failure
+ * itself. See that option's docblock for the #4065 inertness bug it exists for.
+ *
+ * The network row is classified by TYPE (`isTransientTransportError`), not by a
+ * substring of the message: grammy rewrites every transport failure's message
+ * to `Network request for '<method>' failed!`, so the substring form of this
+ * row never matched in production and the retry was dead code (#4123).
  */
 
-import { GrammyError } from 'grammy'
+import { GrammyError, HttpError } from 'grammy'
+import { AsyncLocalStorage } from 'async_hooks'
+
+// ─── retry-attempt context (#3931) ────────────────────────────────────────
+
+/**
+ * What the retry policy knows about the attempt currently on the wire.
+ *
+ * Published so the layer BELOW the policy — the `tg-post` observability
+ * transformer in `shared/bot-runtime.ts`, which runs inside `fn()` and
+ * therefore sees a failure *before* the policy decides what to do with it —
+ * can label a doomed-but-non-terminal attempt honestly instead of as a
+ * delivery failure. Without it, a 429 that the policy sleeps and retries
+ * SUCCESSFULLY still wrote `status=err` to the gateway log, and fleet-health's
+ * per-line `reply-delivery-failure` detector escalated a delivered reply
+ * (#3931).
+ */
+export interface TgAttemptContext {
+  /** 0-based index of the attempt currently executing. */
+  attempt: number
+  /** Total attempts this policy will make. */
+  maxRetries: number
+  /** Longest 429 `retry_after` the policy will sleep in-process. */
+  maxFloodSleepMs: number
+}
+
+const attemptStore = new AsyncLocalStorage<TgAttemptContext>()
+
+/** The attempt context of the enclosing `retryApiCall`, or undefined outside one. */
+export function _getTgAttemptContext(): TgAttemptContext | undefined {
+  return attemptStore.getStore()
+}
+
+/** Run `fn` with `ctx` visible to `_getTgAttemptContext()` for its whole async chain. */
+function withAttemptContext<T>(ctx: TgAttemptContext, fn: () => Promise<T>): Promise<T> {
+  return attemptStore.run(ctx, fn)
+}
+
+/**
+ * Substring classifier for a RAW transport error message (an undici/node error
+ * that has not been through grammy's wrapping).
+ *
+ * NOT sufficient on its own for anything that came out of `bot.api.*` — see
+ * `isTransientTransportError`, which is what the retry loop actually calls.
+ * grammy rewrites the message of every transport failure, so this predicate
+ * returns false for 100% of production send failures if used alone (#4123).
+ */
+export function isTransientNetworkMessage(msg: string): boolean {
+  return (
+    msg.includes('ECONNRESET') ||
+    msg.includes('ETIMEDOUT') ||
+    msg.includes('fetch failed') ||
+    msg.includes('ENOTFOUND')
+  )
+}
+
+/**
+ * True for a cancellation: `AbortController.abort()` surfaces as a
+ * `DOMException`/`Error` with `name === 'AbortError'` (node also sets
+ * `code === 'ABORT_ERR'`). Checked structurally rather than by `instanceof`
+ * because the shape differs across the fetch implementations grammy can be
+ * handed (undici, node-fetch, a test double).
+ */
+function isAbortError(err: unknown): boolean {
+  const e = err as { name?: unknown; code?: unknown } | null
+  return e?.name === 'AbortError' || e?.code === 'ABORT_ERR'
+}
+
+/**
+ * Is `err` a transient TRANSPORT failure the policy should back off and repeat?
+ *
+ * This is the single classifier the retry loop and `willRetryTelegramFailure`
+ * both call, so the policy and the logging tier cannot disagree about what
+ * counts as retryable (#3931).
+ *
+ * Why this is a TYPE test and not a message test (#4123): grammy funnels every
+ * fetch rejection through `toHttpError` (grammy 1.44.0, `out/core/client.js:58`
+ * → `out/core/error.js:76-83`), which throws away the original error text and
+ * renders `Network request for '<method>' failed!`. The underlying
+ * `fetch failed` / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` string is preserved
+ * only on `HttpError.error`, and is appended to the message only when
+ * `client.sensitiveLogs` is on — which we deliberately leave off, because it
+ * writes the bot-token URL into logs. So a substring match over the message
+ * matched NOTHING in production: the network-retry branch was dead code and a
+ * single connection blip terminally failed the send.
+ *
+ * The classes, and why each lands where it does:
+ *
+ *   - `GrammyError`  — an API-LEVEL rejection: Telegram answered, and said no.
+ *     Never part of the network class. 429 has its own sleep-and-retry branch
+ *     above; everything else (400/403/404/…) is terminal and must NOT be
+ *     retried. This is the invariant the old `!isGrammyErr` guard at the
+ *     callsite protected; it now lives here, in one place, next to the reason.
+ *   - local resource exhaustion — ENOSPC/EDQUOT/EIO/ENOMEM is a LOCAL disk or
+ *     memory failure. Retrying it in a tight loop is what tripped the per-bot
+ *     flood ban (#2923). Excluded even when grammy wrapped it.
+ *   - `HttpError`    — transport by construction: it exists only on the
+ *     "the fetch never produced a Telegram response" path (connection reset,
+ *     DNS failure, request timeout, unparseable proxy 5xx). Retryable.
+ *   - anything else  — a raw error that never went through grammy (or a nested
+ *     cause): fall back to the errno/message classifier.
+ */
+export function isTransientTransportError(err: unknown): boolean {
+  if (err instanceof GrammyError) return false
+  if (isLocalResourceError(err)) return false
+  if (err instanceof HttpError) {
+    // grammy stashes the original rejection on `.error`.
+    const inner = (err as HttpError).error
+    // A local disk failure during a multipart upload can surface here; it
+    // stays non-retryable (#2923).
+    if (isLocalResourceError(inner)) return false
+    // A CALLER-initiated cancellation is not a transient failure — retrying it
+    // only re-aborts three times and adds backoff sleeps to shutdown. grammy's
+    // own request TIMEOUT is NOT this case: `createTimeout` rejects the race
+    // with a plain `Error("Request to '<m>' timed out after Ns")` BEFORE it
+    // aborts the controller (grammy 1.44.0, out/core/client.js:168-178), so a
+    // timeout arrives as that Error and remains retryable. An `AbortError`
+    // here means something aborted the signal we were handed (`bot.stop()`).
+    if (isAbortError(inner)) return false
+    return true
+  }
+  const msg = err instanceof Error ? err.message : String(err ?? '')
+  if (isTransientNetworkMessage(msg)) return true
+  // One level of standard cause-chaining (`new Error(x, { cause })`), so a
+  // wrapper that preserves the transport error is still classified correctly.
+  const cause = (err as { cause?: unknown } | null)?.cause
+  if (cause == null || cause === err) return false
+  if (isLocalResourceError(cause)) return false
+  return isTransientNetworkMessage(cause instanceof Error ? cause.message : String(cause))
+}
+
+/** The parts of a Telegram failure that decide retryability. */
+export interface TgFailureShape {
+  /** Telegram `error_code`, or null/undefined for a transport-level error. */
+  errorCode?: number | null
+  /** Telegram `parameters.retry_after`, seconds. */
+  retryAfterSec?: number | null
+  /** Transport-level error message (only consulted when `errorCode` is absent). */
+  message?: string | null
+  /**
+   * The thrown error itself, when the caller has it.
+   *
+   * STRONGLY PREFERRED over `message` for anything that came out of `bot.api.*`:
+   * grammy rewrites the message of every transport failure, so a message-only
+   * shape cannot tell a retryable `HttpError` from a terminal one (#4123). Pass
+   * the error and the predicate classifies by type, exactly as the loop does.
+   */
+  cause?: unknown
+}
+
+/**
+ * Will the enclosing retry policy issue ANOTHER attempt after this failure?
+ *
+ * `true` means the failure is non-terminal: a later attempt may still deliver,
+ * so it must not be logged (or detected) as a delivery failure. `false` means
+ * either there is no retry policy above this call, or this attempt is the last
+ * one, or the error class is not retryable — i.e. the failure IS the outcome.
+ *
+ * Mirrors `createRetryApiCall`'s loop exactly:
+ *   - no enclosing policy                           ⇒ terminal
+ *   - last attempt (`attempt >= maxRetries-1`)      ⇒ terminal (loop falls through)
+ *   - 429 with `retry_after` over the sleep ceiling ⇒ terminal (FLOOD_WAIT_ACTIVE)
+ *   - 429 under the ceiling                         ⇒ retried
+ *   - transient transport error                     ⇒ retried
+ *   - anything else                                 ⇒ terminal (rethrown)
+ */
+export function willRetryTelegramFailure(
+  failure: TgFailureShape,
+  ctx: TgAttemptContext | undefined = _getTgAttemptContext(),
+): boolean {
+  if (ctx == null) return false
+  if (ctx.attempt >= ctx.maxRetries - 1) return false
+  if (failure.errorCode === 429) {
+    const retryAfter = Number(failure.retryAfterSec ?? 5)
+    const delayMs = (Number.isFinite(retryAfter) ? retryAfter : 5) * 1000
+    return delayMs <= ctx.maxFloodSleepMs
+  }
+  if (failure.errorCode != null) return false
+  // Classify by TYPE when the caller handed us the error (the seam that
+  // matters — see `isTransientTransportError`); fall back to the message only
+  // for shapes reconstructed from a log line, which have nothing else.
+  if (failure.cause != null) return isTransientTransportError(failure.cause)
+  return isTransientTransportError(new Error(failure.message ?? ''))
+}
 
 export interface RetryCallOpts {
   /**
@@ -90,6 +285,42 @@ export interface RetryCallOpts {
    * the authoritative statement.
    */
   priorityClass?: 'critical' | 'useful' | 'cosmetic'
+  /**
+   * Opt OUT of the benign-400 swallow for this one call (#4065 follow-up).
+   *
+   * By default `retryApiCall` treats the benign 400s
+   * (`classifyBenignTelegram400`: not-modified / message-to-edit-not-found /
+   * message-to-delete-not-found) as non-events and RESOLVES `undefined`. That
+   * is right for fire-and-forget card repaints, and wrong — silently, and in
+   * the worst direction — for any caller whose contract is "tell me whether
+   * the target message still exists".
+   *
+   * The concrete failure this exists for: the rollout narration card's edit
+   * relay (`gateway/rollout-status-edit.ts`) infers edit success from the
+   * ABSENCE of a throw and reports it to hostd. A seeded-resume narrator
+   * holding a carried `narration_message_id` for a card the operator deleted
+   * gets `400 "message to edit not found"` — which the default swallow turns
+   * into a resolved promise, so the handler replies `{ok:true}` and hostd
+   * records a frozen card as live and never re-posts. The `gone` signal — the
+   * whole reason that feature exists — is unreachable on the production path
+   * for its primary trigger. Classification has to happen where the error
+   * still exists, so the call site asks for the error instead of a
+   * lie-shaped success.
+   *
+   * When true, a benign 400 is RETHROWN unchanged (still `GrammyError`, with
+   * its `description` intact) after `observer.onBenign` fires, so the caller
+   * classifies it itself. Everything else — 429 handling, the flood breaker,
+   * network retries, `THREAD_NOT_FOUND` — is untouched. Default `false`:
+   * every existing call site keeps today's exact behaviour.
+   *
+   * Note this covers BOTH benign kinds deliberately. `not modified` also
+   * resolves `undefined` today, which coincidentally matches the intended
+   * semantics for an edit relay (the live card already carries this body =
+   * success) — but "coincidentally right" is not a contract. Rethrowing both
+   * puts ONE classifier in charge (the caller's), so the two kinds can never
+   * drift apart on the swallow boundary.
+   */
+  rethrowBenign400?: boolean
 }
 
 /**
@@ -133,7 +364,12 @@ export interface RetryObserver {
   onRetry?(info: { attempt: number; reason: 'flood_wait' | 'network'; delayMs: number }): void
   /** Fires when max retries is reached and the wrapper gives up. */
   onGiveUp?(info: { attempts: number; error: unknown }): void
-  /** Fires for each benign error we swallowed (not-modified, not-found). */
+  /**
+   * Fires for each benign 400 we CLASSIFIED (not-modified, not-found) —
+   * whether it was then swallowed (the default) or rethrown because the call
+   * set `rethrowBenign400`. The Telegram-side event is the same either way, so
+   * counting it must not depend on the disposition.
+   */
   onBenign?(info: { kind: BenignTelegram400Kind }): void
 }
 
@@ -379,7 +615,10 @@ export function createRetryApiCall(
         throw gated
       }
       try {
-        return await fn()
+        // #3931 — publish the attempt context for the duration of the wire
+        // call so the `tg-post` transformer underneath can tell a retried
+        // failure from a terminal one.
+        return await withAttemptContext({ attempt, maxRetries, maxFloodSleepMs }, fn)
       } catch (err) {
         const isGrammyErr = err instanceof GrammyError
         const msg = err instanceof Error ? err.message : String(err)
@@ -444,6 +683,11 @@ export function createRetryApiCall(
           : null
         if (benignKind !== null) {
           observer?.onBenign?.({ kind: benignKind })
+          // #4065 follow-up: a caller whose contract is "does the target
+          // message still exist?" opts out of the swallow, because a resolved
+          // promise is indistinguishable from a landed edit. Rethrow the
+          // ORIGINAL error so the caller classifies off `description`.
+          if (opts?.rethrowBenign400) throw err
           return undefined as unknown as T
         }
 
@@ -459,13 +703,12 @@ export function createRetryApiCall(
         }
 
         // Network-level transient errors — exponential backoff, bounded.
-        if (
-          !isGrammyErr &&
-          (msg.includes('ECONNRESET') ||
-            msg.includes('ETIMEDOUT') ||
-            msg.includes('fetch failed') ||
-            msg.includes('ENOTFOUND'))
-        ) {
+        // Classified by TYPE, not by message substring: grammy rewrites the
+        // message of every transport failure, so the old substring test never
+        // fired in production and this whole branch was dead (#4123). The
+        // `!isGrammyErr` guard that used to sit here now lives inside
+        // `isTransientTransportError`, which excludes GrammyError explicitly.
+        if (isTransientTransportError(err)) {
           if (attempt < maxRetries - 1) {
             const delayMs = Math.pow(2, attempt) * 1000
             log?.(