switchroom 0.19.19 → 0.19.23

package/telegram-plugin/edit-flood-fuse.ts

@@ -0,0 +1,477 @@
+/**
+ * Edit-flood fuse — a LAST-RESORT rate ceiling installed at the one seam no
+ * outbound call can bypass (#3620).
+ *
+ * ── Why this exists ───────────────────────────────────────────────────────
+ * The send gate (`send-gate.ts`) is the primary pacer, and every call that
+ * goes through `robustApiCall` is admitted by it. But two properties make it
+ * a gate with side doors rather than a failsafe:
+ *
+ *   1. Its per-message protections (edit floor, last-write-wins coalescing,
+ *      no-op skip, long-horizon edit budget) are OPT-IN: `gate()` routes to
+ *      the edit path only when the caller passes BOTH `messageId` and
+ *      `editPayload` (send-gate.ts, `gate()`). A caller that forgets gets a
+ *      plain send — no floor, no coalescing.
+ *   2. An untagged call is admitted as `critical` (UNTAGGED_SEND_CLASS), the
+ *      class that is never shed and queues unbounded.
+ *
+ * That combination is exactly what earned agent `overlord` a 3713-second
+ * flood ban on 2026-07-25: the live activity card edited ONE message id with
+ * neither key nor class, so it ran at the per-chat bucket rate (60/min) for
+ * an hour. Keying that call site fixes that call site — it does not make the
+ * next unkeyed call site impossible.
+ *
+ * ── Why a grammY transformer ──────────────────────────────────────────────
+ * The gateway constructs exactly ONE `new Bot(TOKEN)`, and grammY routes
+ * 100% of outbound API traffic through that instance's transformer stack —
+ * `bot.api.*`, `ctx.api.*`, anything holding a reference to the `Api` object,
+ * wrapped or raw, gated or not. Installing here is therefore STRUCTURAL, not
+ * conventional: a new call site cannot opt out, because there is no code path
+ * to the network that skips the transformer stack. (`shared/bot-runtime.ts`
+ * already proves the seam with `installTgPostLogger`.)
+ *
+ * ── What it does (and deliberately does NOT do) ───────────────────────────
+ *   - EDITS of the same `${chat_id}:${message_id}` are capped at
+ *     `perMessageMaxPerWindow` per `perMessageWindowMs` (default 20/60s).
+ *     Over-budget edits WAIT for the window to slide, and while they wait a
+ *     newer edit to the same message SUPERSEDES them — last-write-wins at the
+ *     chokepoint, for every caller, including ones that never heard of the
+ *     send gate. A superseded or over-deferred edit is DROPPED (resolved as a
+ *     benign no-op), which is safe precisely because the next render of any
+ *     card carries full state.
+ *   - NON-EDIT sends are PACED (per-chat rolling ceiling) but NEVER dropped.
+ *     Dropping a reply would lose a user-visible answer; dropping a repaint
+ *     costs nothing. Pacing is capped at `maxDeferMs`, after which the call
+ *     passes through rather than blocking a reply for an unbounded time.
+ *   - On an observed 429 the ceilings TIGHTEN multiplicatively (AIMD) for
+ *     `tightenMs`, then restore. `retry-api-call.ts` sleeps `retry_after` and
+ *     resumes at FULL rate; nothing in the stack previously reduced the
+ *     sustained rate after a soft 429.
+ *
+ * ── Where the ceiling actually sits (review 2026-07-26, R1) ───────────────
+ * An earlier draft of this docblock claimed the fuse "sits ABOVE every
+ * legitimate cadence". That is FALSE and the claim mattered, so it is
+ * corrected here rather than deleted. The in-repo cadences are:
+ *
+ *   - send gate `editFloorMs` = 1500ms          ⇒ up to 40 edits/min/message
+ *   - send gate cosmetic budget 150 / 300s      ⇒ 30 edits/min/message
+ *   - worker feed's own floor 2500ms            ⇒ 24 edits/min/message
+ *
+ * The per-message ceiling here is 20/60s, i.e. BELOW all three. That is
+ * deliberate — Telegram's own per-group limit is ~20 messages/minute and
+ * edits count against it, so the *legitimate* cadences are themselves above
+ * what Telegram tolerates; that is precisely how `overlord` got banned while
+ * every in-repo pacer believed it was behaving. The fuse is therefore the
+ * BINDING constraint on a hot card, not a never-reached backstop.
+ *
+ * Because it binds routinely, "over budget" must never mean "silently
+ * lost". Two rules follow, and both are load-bearing:
+ *   - per-MESSAGE over-budget edits SUPERSEDE (newest wins, older frame is
+ *     discarded) — safe, because the frame that killed it will paint;
+ *   - per-CHAT over-budget edits may only be DROPPED while a NEWER frame for
+ *     that same message is still in flight to repaint it. When the waiting
+ *     frame is the only one for its card (a turn-final `finalize`, say) it is
+ *     RELEASED late instead of dropped. Dropping it would freeze the card
+ *     mid-run AND return `true` to the send gate, which would then record a
+ *     never-painted payload as on-screen and no-op-skip every retry.
+ */
+
+import type { Bot } from 'grammy'
+
+import type { Clock } from './send-gate.js'
+import { systemClock } from './send-gate.js'
+
+/** Methods that mutate an EXISTING message — droppable, coalescible. */
+const EDIT_METHODS: ReadonlySet<string> = new Set([
+  'editMessageText',
+  'editMessageCaption',
+  'editMessageMedia',
+  'editMessageReplyMarkup',
+  'editMessageLiveLocation',
+  // Review 2026-07-26 (R2): the checklist tools drive this one exactly like a
+  // card — `update_checklist` re-edits ONE message id in a loop
+  // (gateway.ts `_rawEditMessageChecklist`, called through `bot.api.raw`, which
+  // grammY routes through the transformer stack like everything else). Omitting
+  // it left a same-shaped flood path completely unfused.
+  'editMessageChecklist',
+])
+
+/** Methods that CREATE user-visible output — paced, never dropped. */
+const SEND_METHODS: ReadonlySet<string> = new Set([
+  'sendMessage', 'sendPhoto', 'sendDocument', 'sendMediaGroup', 'sendAnimation',
+  'sendVideo', 'sendVoice', 'sendAudio', 'sendSticker', 'sendLocation',
+  'forwardMessage', 'forwardMessages', 'copyMessage', 'copyMessages',
+  // Review 2026-07-26 (R3): `sendRichMessage` is the plugin's PRIMARY send —
+  // every rich reply, every activity-card OPEN, every stream finalisation goes
+  // through it (`rich-send.ts`, `narrative-lane.ts`, `stream-render.ts`).
+  // Leaving it out meant the "non-edit sends are paced" property applied to
+  // almost nothing that this gateway actually sends. Sends are never dropped,
+  // so this only ever adds a bounded (`maxDeferMs`) delay under real pressure.
+  // NOTE: `sendRichMessageDraft` is deliberately NOT here — an ephemeral
+  // 30s-preview draft is high-cadence by design and is not a persisted message.
+  'sendRichMessage',
+])
+
+export interface EditFloodFuseConfig {
+  /** Master switch. When false, `apply` is a pure passthrough. Default true. */
+  enabled?: boolean
+  clock?: Clock
+  /** Hard ceiling on edits to ONE message id. Default 20 per 60s. */
+  perMessageMaxPerWindow?: number
+  perMessageWindowMs?: number
+  /** Hard ceiling on edits to ONE chat across all messages. Default 30 per 60s. */
+  perChatEditMaxPerWindow?: number
+  /** Pacing ceiling on non-edit sends to ONE chat. Default 25 per 60s. */
+  perChatSendMaxPerWindow?: number
+  perChatWindowMs?: number
+  /** Longest a call may be held before it is dropped (edit) / released (send). Default 30s. */
+  maxDeferMs?: number
+  /** Multiplicative decrease applied to every ceiling after a 429. Default 0.5. */
+  tightenFactor?: number
+  /** How long a tightened ceiling stays in force. Default 10 minutes. */
+  tightenMs?: number
+  /** Observability hook; fired whenever the fuse binds. */
+  onTrip?: (info: { method: string; key: string; action: 'deferred' | 'dropped' | 'superseded' }) => void
+}
+
+export interface EditFloodFuseStats {
+  enabled: boolean
+  /** Calls the fuse held back waiting for a window to slide. */
+  deferred: number
+  /** Edits dropped because the window never opened inside `maxDeferMs`. */
+  dropped: number
+  /** Edits dropped because a NEWER edit to the same message arrived. */
+  superseded: number
+  /** 429s observed (each one tightens the ceilings). */
+  floodObserved: number
+  /** Whether a tightened ceiling is in force right now. */
+  tightened: boolean
+  /** Live per-message ceiling (post-AIMD). */
+  perMessageCeiling: number
+}
+
+export const EDIT_FLOOD_FUSE_DEFAULTS = {
+  perMessageMaxPerWindow: 20,
+  perMessageWindowMs: 60_000,
+  perChatEditMaxPerWindow: 30,
+  perChatSendMaxPerWindow: 25,
+  perChatWindowMs: 60_000,
+  maxDeferMs: 30_000,
+  tightenFactor: 0.5,
+  tightenMs: 600_000,
+} as const
+
+/** grammY resolves an edit with `true` when there is nothing to return. */
+const DROPPED_RESULT = true
+
+interface Window {
+  ts: number[]
+  /** The newest waiter on this key; a fresh waiter supersedes it. */
+  waiter: { kill: () => void } | null
+  /**
+   * How many calls for this key are currently inside `apply` (per-MESSAGE keys
+   * only). Read at the per-chat defer deadline: dropping is only honest while
+   * a NEWER frame for the same message is still in flight to repaint. See the
+   * docblock's "Where the ceiling actually sits" (R1).
+   */
+  inflight: number
+}
+
+/**
+ * The fuse as a pure, clock-injectable unit. `apply` has the grammY
+ * transformer shape so it can be handed straight to `bot.api.config.use`.
+ */
+export function createEditFloodFuse(config: EditFloodFuseConfig = {}) {
+  const enabled = config.enabled ?? true
+  const clock = config.clock ?? systemClock
+  const D = EDIT_FLOOD_FUSE_DEFAULTS
+  const perMessageMax = config.perMessageMaxPerWindow ?? D.perMessageMaxPerWindow
+  const perMessageWindowMs = config.perMessageWindowMs ?? D.perMessageWindowMs
+  const perChatEditMax = config.perChatEditMaxPerWindow ?? D.perChatEditMaxPerWindow
+  const perChatSendMax = config.perChatSendMaxPerWindow ?? D.perChatSendMaxPerWindow
+  const perChatWindowMs = config.perChatWindowMs ?? D.perChatWindowMs
+  const maxDeferMs = config.maxDeferMs ?? D.maxDeferMs
+  const tightenFactor = config.tightenFactor ?? D.tightenFactor
+  const tightenMs = config.tightenMs ?? D.tightenMs
+  const onTrip = config.onTrip
+
+  const windows = new Map<string, Window>()
+  const counters = { deferred: 0, dropped: 0, superseded: 0, floodObserved: 0 }
+  /** Timestamp until which the AIMD tightening is in force (0 = untightened). */
+  let tightenedUntil = 0
+
+  function isTightened(now: number): boolean {
+    return tightenedUntil > now
+  }
+
+  /**
+   * AIMD multiplicative decrease. Applied to every ceiling while tightened;
+   * floored at 1 so the fuse never deadlocks a surface completely.
+   */
+  function ceiling(base: number, now: number): number {
+    if (!isTightened(now)) return base
+    return Math.max(1, Math.floor(base * tightenFactor))
+  }
+
+  function win(key: string): Window {
+    let w = windows.get(key)
+    if (w === undefined) {
+      w = { ts: [], waiter: null, inflight: 0 }
+      windows.set(key, w)
+    }
+    return w
+  }
+
+  function prune(w: Window, now: number, windowMs: number): void {
+    const cutoff = now - windowMs
+    while (w.ts.length > 0 && w.ts[0]! <= cutoff) w.ts.shift()
+  }
+
+  /**
+   * Bounded LRU-ish eviction so a long-lived process cannot grow the map
+   * without limit. A window with no in-flight waiter and no timestamps inside
+   * the widest window is dead state.
+   */
+  let sinceEvict = 0
+  function evict(now: number): void {
+    if (windows.size < 4096) return
+    // Sweep at most once per 1024 admissions: an unconditional sweep would be
+    // O(n) on EVERY outbound call once the map is large, i.e. the fuse itself
+    // would become the latency problem it exists to prevent.
+    if (++sinceEvict < 1024) return
+    sinceEvict = 0
+    const widest = Math.max(perMessageWindowMs, perChatWindowMs)
+    for (const [k, w] of windows) {
+      // `inflight > 0` keeps a key whose caller is mid-wait: evicting it would
+      // hand that caller a stale Window object while a FRESH one (empty `ts`)
+      // took its place in the map, resetting the ceiling for everyone else.
+      if (w.waiter === null && w.inflight === 0
+        && (w.ts.length === 0 || w.ts[w.ts.length - 1]! <= now - widest)) {
+        windows.delete(k)
+      }
+    }
+  }
+
+  /** ms until `w` has room, or 0 if it has room now. */
+  function waitFor(w: Window, now: number, windowMs: number, max: number): number {
+    prune(w, now, windowMs)
+    if (w.ts.length < max) return 0
+    return Math.max(1, w.ts[0]! + windowMs - now)
+  }
+
+  function payloadKeys(payload: unknown): { chat: string | null; msg: string | null } {
+    const p = (payload ?? {}) as Record<string, unknown>
+    const chat = p.chat_id != null ? String(p.chat_id) : null
+    const msg = p.message_id != null ? String(p.message_id) : null
+    return { chat, msg }
+  }
+
+  /** Record a 429 (whatever shape it arrives in) and tighten. */
+  function noteFlood(now: number): void {
+    counters.floodObserved++
+    tightenedUntil = now + tightenMs
+  }
+
+  function looksLikeFlood(err: unknown): boolean {
+    const e = err as { error_code?: number; parameters?: { retry_after?: number } } | null
+    if (e != null && typeof e === 'object') {
+      if (e.error_code === 429) return true
+      if (e.parameters != null && typeof e.parameters.retry_after === 'number') return true
+    }
+    // Match on the SEMANTIC markers only. A bare "429" substring
+    // false-positives on ordinary server text (e.g. "message 429 not found"),
+    // and a false positive here halves every ceiling for ten minutes.
+    const msg = err instanceof Error ? err.message : String(err ?? '')
+    return /too many requests/i.test(msg) || /retry[ _-]?after/i.test(msg)
+  }
+
+/**
+   * How a call that finds no room behaves:
+   *   supersede — per-message edits: a newer edit to the SAME message kills it
+   *   drop      — per-chat edits: waits, then drops at the defer deadline
+   *   release   — sends: waits, then passes through (never lost)
+   */
+  type WaitMode = 'supersede' | 'drop' | 'release'
+
+  /** Give back a slot reserved by `awaitRoom` (used when a later tier denies). */
+  function unreserve(key: string, at: number): void {
+    const w = windows.get(key)
+    if (w === undefined) return
+    const i = w.ts.lastIndexOf(at)
+    if (i >= 0) w.ts.splice(i, 1)
+  }
+
+  /**
+   * Wait for room on `key` and RESERVE the slot on success. Reserving inside
+   * the same synchronous step as the check is what makes the ceiling hold
+   * under concurrency: N producers that all pass a check-then-act test in the
+   * same tick would each admit, and N parallel sub-agents is exactly the shape
+   * that turns a ceiling into N× the ceiling.
+   *
+   * Returns the reserved timestamp, or null when the call must be dropped.
+   */
+  async function awaitRoom(
+    key: string, windowMs: number, max: number, method: string, mode: WaitMode,
+    /**
+     * Consulted ONLY at the defer deadline for `mode: 'drop'`. Returning false
+     * converts the drop into a late release: this call is the last thing that
+     * will ever paint its message, so losing it is not "shedding a stale
+     * frame", it is freezing a card. Absent ⇒ drop unconditionally (the
+     * pre-review behaviour).
+     */
+    dropGuard?: () => boolean,
+  ): Promise<number | null> {
+    const w = win(key)
+    const deadline = clock.now() + maxDeferMs
+    let counted = false
+    for (;;) {
+      const now = clock.now()
+      const wait = waitFor(w, now, windowMs, ceiling(max, now))
+      if (wait === 0) {
+        w.ts.push(now)
+        return now
+      }
+      if (now >= deadline) {
+        // Held as long as we are willing to hold. An edit is dropped (the next
+        // render carries full state); a send is released (losing a reply is
+        // worse than a late one).
+        if (mode !== 'release' && (dropGuard === undefined || dropGuard())) {
+          counters.dropped++
+          onTrip?.({ method, key, action: 'dropped' })
+          return null
+        }
+        // A send — or an edit that nothing newer will repaint — is released
+        // rather than dropped, and still takes a slot so the window reflects
+        // what actually went out.
+        w.ts.push(now)
+        return now
+      }
+      if (!counted) {
+        counters.deferred++
+        counted = true
+        onTrip?.({ method, key, action: 'deferred' })
+      }
+      // Last-write-wins: a newer edit to the same message kills this one. Only
+      // valid on the per-MESSAGE tier — on a per-chat key the "newer" edit is
+      // usually to a DIFFERENT message, and killing an unrelated card's edit is
+      // not last-write-wins, it is data loss.
+      let killed = false
+      if (mode === 'supersede') {
+        w.waiter?.kill()
+        const superseded = new Promise<void>((resolve) => {
+          w.waiter = { kill: () => { killed = true; resolve() } }
+        })
+        await Promise.race([clock.sleep(Math.min(wait, deadline - now)), superseded])
+        if (killed) {
+          counters.superseded++
+          onTrip?.({ method, key, action: 'superseded' })
+          return null
+        }
+        w.waiter = null
+      } else {
+        await clock.sleep(Math.min(wait, deadline - now))
+      }
+    }
+  }
+
+  /** The grammY transformer body. */
+  async function apply<R>(
+    method: string,
+    payload: unknown,
+    next: () => Promise<R>,
+  ): Promise<R> {
+    if (!enabled) return next()
+
+    const isEdit = EDIT_METHODS.has(method)
+    const isSend = SEND_METHODS.has(method)
+    if (!isEdit && !isSend) return runObserved(next)
+
+    const { chat, msg } = payloadKeys(payload)
+    // Inline-message edits carry no chat/message id — nothing to key on, and
+    // they are not part of any card loop. Pass through (still observed).
+    if (chat == null) return runObserved(next)
+
+    const now = clock.now()
+    evict(now)
+
+    if (isEdit) {
+      if (msg == null) return runObserved(next)
+      const msgKey = `m:${chat}:${msg}`
+      const mw = win(msgKey)
+      // Counted BEFORE the first await so a frame that arrives while an older
+      // one is waiting is visible to that older one's `dropGuard`.
+      mw.inflight++
+      try {
+        const msgSlot = await awaitRoom(msgKey, perMessageWindowMs, perMessageMax, method, 'supersede')
+        if (msgSlot === null) return DROPPED_RESULT as unknown as R
+        const chatKey = `ce:${chat}`
+        const chatSlot = await awaitRoom(
+          chatKey, perChatWindowMs, perChatEditMax, method, 'drop',
+          // R1: only drop while something newer for THIS message is still in
+          // flight to repaint it. `> 1` = this frame plus at least one newer.
+          () => mw.inflight > 1,
+        )
+        if (chatSlot === null) {
+          // Denied by the second tier — hand the first tier's slot back so a
+          // dropped edit never consumes budget it did not use.
+          unreserve(msgKey, msgSlot)
+          return DROPPED_RESULT as unknown as R
+        }
+        return runObserved(next)
+      } finally {
+        mw.inflight--
+      }
+    }
+
+    const chatKey = `cs:${chat}`
+    await awaitRoom(chatKey, perChatWindowMs, perChatSendMax, method, 'release')
+    return runObserved(next)
+  }
+
+  /** Run the downstream call, tightening the ceilings if it floods. */
+  async function runObserved<R>(next: () => Promise<R>): Promise<R> {
+    try {
+      const res = await next()
+      // grammY throws on ok:false, but a transformer installed BELOW another
+      // one can still observe a raw ApiResponse — handle both shapes.
+      const r = res as unknown as { ok?: boolean; error_code?: number }
+      if (r != null && typeof r === 'object' && r.ok === false && r.error_code === 429) {
+        noteFlood(clock.now())
+      }
+      return res
+    } catch (err) {
+      if (looksLikeFlood(err)) noteFlood(clock.now())
+      throw err
+    }
+  }
+
+  function stats(): EditFloodFuseStats {
+    const now = clock.now()
+    return {
+      enabled,
+      deferred: counters.deferred,
+      dropped: counters.dropped,
+      superseded: counters.superseded,
+      floodObserved: counters.floodObserved,
+      tightened: isTightened(now),
+      perMessageCeiling: ceiling(perMessageMax, now),
+    }
+  }
+
+  return { apply, stats }
+}
+
+export type EditFloodFuse = ReturnType<typeof createEditFloodFuse>
+
+/**
+ * The bot handle the fuse installs on. Typed against grammY's own `Bot` so the
+ * transformer signature is checked by the compiler, not by convention.
+ */
+export type FuseInstallable = Bot
+
+export function installEditFloodFuse(bot: FuseInstallable, config: EditFloodFuseConfig = {}): EditFloodFuse {
+  const fuse = createEditFloodFuse(config)
+  bot.api.config.use(async (prev, method, payload, signal) =>
+    fuse.apply(method, payload, () => prev(method, payload, signal)))
+  return fuse
+}

package/telegram-plugin/format.ts

@@ -326,13 +326,25 @@ export function normalizeParagraphBreaks(text: string): string {
   //       it was the "stray blank line" seen in real replies. Collapse it.
   //
   // Deliberately ASCII-only: the `[ \t\r]` character class excludes U+00A0 by
-  // construction, so a line whose only content is a non-breaking space a user
-  // legitimately typed is left intact rather than silently collapsed. (This
-  // used to also protect the NBSP paragraph spacer that addParagraphSpacers
-  // injected downstream; that spacer pass was removed in the #2669 follow-up —
-  // paragraph gaps now rely on plain `\n\n` — but keeping this ASCII-only is
-  // still the conservative choice.) Runs on code-masked text, so a blank-ish
-  // line inside a fenced block is parked and never touched.
+  // construction, so a line whose only content is a non-breaking space is left
+  // intact rather than silently collapsed.
+  //
+  // That is load-bearing, not merely conservative. `addParagraphSpacers` (below)
+  // wedges a U+00A0-only line into every prose paragraph gap to force a VISIBLE
+  // gap (#2692) and is LIVE on the outbound path today — gateway/
+  // outbound-send-path.ts (`normalizeOutboundBody`) and gateway/gateway.ts (the
+  // rich `sendRichMessage` chunker). Within a single `normalizeOutboundBody`
+  // pass the spacer is injected AFTER this normalizer, so this pass usually does
+  // not see it — but the ASCII-only class is a deliberate, pinned invariant, not
+  // an accident of that ordering: tests/paragraph-normalizer.test.ts ("the
+  // deliberate U+00A0 spacer … is preserved") asserts
+  // `normalizeParagraphBreaks(spaced) === spaced`, so this function stays safe
+  // to re-enter over already-spacered text. Widening `[ \t\r]` to catch U+00A0
+  // would eat the spacer, fail that test, and regress #2692.
+  //
+  // It also leaves a non-breaking space a user legitimately typed alone. Runs on
+  // code-masked text, so a blank-ish line inside a fenced block is parked and
+  // never touched.
   let out = masked
     // Collapse any run of newlines interleaved with ASCII whitespace-only
     // interior lines down to a single clean `\n\n`. Requires at least one

package/telegram-plugin/gateway/backstop-delivery.ts

@@ -114,8 +114,10 @@ export class BackstopDeliveryLedger {
 
   /**
    * #3278 — transition a landed-unconfirmed chunk to `landed-confirmed` after a
-   * read-back probe proved the message exists in the chat. Only a confirmed
-   * chunk counts toward delivery / `complete`.
+   * read-back probe proved the message exists in the chat. Confirmation is the
+   * STRONGER of the two delivery states; the weaker `landed-unconfirmed` also
+   * counts as delivered (an inconclusive probe is not a failure — see
+   * `runBackstopDelivery`). Only a POSITIVE absence (`demoteChunk`) un-delivers.
    */
   confirmChunk(turnId: string, index: number): void {
     let set = this.confirmed.get(turnId)
@@ -164,8 +166,14 @@ export class BackstopDeliveryLedger {
     return true
   }
 
-  /** Landed message ids of CONFIRMED chunks only, in chunk-index order — the set
-   *  the delivery predicate counts (fresh non-card ids that are proven-present). */
+  /** Landed message ids of CONFIRMED chunks only, in chunk-index order — the
+   *  read-back view of the ledger (ids proven present in the chat). The delivery
+   *  predicate counts LANDED ids (`sentIds`), not these; this is the stronger
+   *  proven-present subset. Its production consumer is
+   *  {@link BackstopDeliveryResult.landedUnconfirmedIds} — `sentIds` minus these
+   *  is the landed-but-uncorroborated set that reaches `turns.jsonl` as
+   *  `landed_unconfirmed`, the counter that measures whether this module's
+   *  optimism about an inconclusive probe is ever wrong. */
   confirmedIds(turnId: string): number[] {
     const m = this.chunks.get(turnId)
     const set = this.confirmed.get(turnId)
@@ -226,9 +234,11 @@ export class BackstopDeliveryLedger {
  *                  `landed-confirmed` (counts toward delivery).
  *  - `absent`    — Telegram `400 message to edit not found` ⇒ positive absence
  *                  ⇒ demote to `unsent` (safe to re-send — it never landed).
- *  - `ambiguous` — 429 / 5xx / network / gate-shed / anything else ⇒ leave
- *                  `landed-unconfirmed`; NEVER re-send (a re-send would risk a
- *                  duplicate, and duplicate-risk beats missing-risk here).
+ *  - `ambiguous` — 429 / 5xx / network / gate-shed / gate no-op / anything else
+ *                  ⇒ leave `landed-unconfirmed`; NEVER re-send (a re-send would
+ *                  risk a duplicate, and duplicate-risk beats missing-risk
+ *                  here) and NEVER count it as a delivery failure either — the
+ *                  probe established nothing, so the landed-id evidence stands.
  *
  * NOTE (honest limitation, #3278 §1.4): a passing probe proves only that the
  * message EXISTS at that chat_id. It does NOT prove the human's client rendered
@@ -322,8 +332,36 @@ export interface BackstopDeliveryResult {
   sentIds: number[]
   /** Number of input chunks the answer was split into. */
   chunkCount: number
-  /** True IFF every chunk landed at least one fresh non-card id. */
+  /**
+   * True IFF every chunk landed at least one message id AND at least one of
+   * them is a fresh non-card chat id. This is the DELIVERY verdict the turn
+   * record, the obligation ledger and the status reaction key on.
+   *
+   * A read-back probe can only ever LOWER it, and only on POSITIVE absence: an
+   * `absent` verdict demotes the chunk back to `unsent`, so it stops counting as
+   * landed. An `ambiguous` probe carries no information and therefore does not
+   * move this flag — see {@link confirmed}.
+   */
   delivered: boolean
+  /**
+   * True IFF every chunk was read-back CONFIRMED (`exists`). Strictly stronger
+   * than {@link delivered} and purely observational — nothing keys a failure on
+   * it. `delivered && !confirmed` is the `landed-unconfirmed` state: the Bot API
+   * returned fresh ids for every chunk but the probe could not corroborate them.
+   */
+  confirmed: boolean
+  /**
+   * The landed message ids NO read-back corroborated — `sentIds` minus the
+   * confirmed subset, in chunk-index order. Empty when {@link confirmed}.
+   *
+   * This is the MEASURABLE form of this module's central bet: a landed id whose
+   * probe came back inconclusive is counted as delivered. Its count is stamped
+   * onto the turn record as `landed_unconfirmed` (see `buildTurnRecord`) so the
+   * fleet can tell how often that bet is being made — and, if a
+   * `landed_unconfirmed` turn is ever followed by a "you never answered me",
+   * that the bet was wrong. Purely observational: nothing keys a failure on it.
+   */
+  landedUnconfirmedIds: number[]
   /** How many attempts ran (1..maxAttempts). */
   attempts: number
   /** True when retries were exhausted without full delivery (terminal fail). */
@@ -345,9 +383,12 @@ export interface BackstopDeliveryResult {
  * is read-back-probed via `deps.readBack` (when provided): `exists` confirms it,
  * `absent` demotes it to `unsent` so the NEXT attempt re-sends only that chunk,
  * and `ambiguous` leaves it `landed-unconfirmed` — never re-sent (duplicate-risk
- * beats missing-risk). `delivered` now requires every chunk `landed-confirmed`,
- * so an API-ack'd-but-silently-dropped send (fresh id, absent on read-back) is
- * reported `delivered:false` and the caller leaves the obligation OPEN.
+ * beats missing-risk). An API-ack'd-but-silently-dropped send (fresh id, absent
+ * on read-back) is therefore reported `delivered:false` and the caller leaves
+ * the obligation OPEN — a correct mechanism that is INERT UNTIL #3703, because
+ * the probe is 100% shed in production and never resolves `absent`. An
+ * INCONCLUSIVE probe is not a failure: it leaves `delivered` alone and only
+ * clears `confirmed` (see `BackstopDeliveryResult`).
  *
  * `recordOutbound` (when provided) fires ONCE at the end with the full landed
  * set and a `texts` array ALIGNED to the actual sent ids (via `ledger.entries`).
@@ -449,12 +490,52 @@ export async function runBackstopDelivery(
   }
 
   const sentIds = ledger.sentIds(turnId)
-  // #3278 — delivered IFF every chunk is `landed-confirmed` AND at least one
-  // confirmed id is a fresh non-card chat id (the receipt gate, guard 7).
+  const confirmed = ledger.allConfirmed(turnId, chunkCount)
+  // The delivery verdict is EVIDENCE-BASED, not confirmation-gated.
+  //
+  // #3278 originally required every chunk to be `landed-confirmed`, so an
+  // `ambiguous` probe — which by definition establishes nothing — produced
+  // `delivered:false`. That inverted the guard it was meant to be: the turn was
+  // recorded `send_failed`, the status reaction painted error, and the delivery
+  // obligation was left OPEN for a re-present, all for an answer the user had
+  // demonstrably received. In production the probe is ambiguous essentially
+  // always (it is issued at cosmetic priority in the same millisecond as the
+  // send it probes, so the per-chat token bucket sheds it), so this turned a
+  // successful backstop delivery into a logged failure ~146 times in two weeks.
+  //
+  // Absence of evidence is not evidence of absence. The verdict is therefore:
+  // every chunk LANDED (guard 6) and at least one landed id is a fresh non-card
+  // chat id (the receipt gate, guard 7). A probe can still lower it — an
+  // `absent` verdict demotes the chunk to `unsent` above, so it is no longer
+  // landed — which keeps #3278's real contribution (a positive absence is
+  // caught and re-sent) while an inconclusive probe changes nothing.
+  //
+  // Honesty about what that contribution is worth TODAY: it is INERT UNTIL
+  // #3703. The probe is issued at cosmetic priority in the same millisecond as
+  // the send it probes, so the per-chat token bucket sheds it 100% of the time
+  // (146 `ambiguous` / 0 `absent` across the live fleet) and the `absent` branch
+  // is structurally unreachable in production. The demote-and-re-send path below
+  // is a correct mechanism with no live trigger; #3703 is the change that wakes
+  // the probe (and must first fix its resplit-overwrite hazard). Do not read
+  // this block as "absence is still caught in production" — it is not, yet.
+  const allLanded = chunkCount > 0 && ledger.unsentIndices(turnId, chunkCount).length === 0
   const delivered =
-    ledger.allConfirmed(turnId, chunkCount) &&
-    backstopReceiptIds(ledger.confirmedIds(turnId), cardMessageId).length > 0
+    allLanded && backstopReceiptIds(sentIds, cardMessageId).length > 0
   const exhausted = !delivered
+  // The landed-but-uncorroborated set (L2/L5): `sentIds` minus the read-back
+  // confirmed subset. Surfaced on the result so the caller can stamp
+  // `landed_unconfirmed` on the turn record — the only way to measure whether
+  // counting an inconclusive probe as delivered is ever wrong.
+  const confirmedSet = new Set(ledger.confirmedIds(turnId))
+  const landedUnconfirmedIds = sentIds.filter(id => !confirmedSet.has(id))
+  if (delivered && !confirmed) {
+    stderr(
+      `telegram gateway: backstop delivery landed-unconfirmed for turn ${turnId} — ` +
+      `every chunk returned a fresh message id but the read-back probe was ` +
+      `inconclusive for ${landedUnconfirmedIds.length} of ${sentIds.length} landed ` +
+      `id(s); counting it delivered (an ambiguous probe is not a failure)\n`,
+    )
+  }
 
   if (deps.recordOutbound && sentIds.length > 0) {
     const texts: string[] = []
@@ -468,5 +549,5 @@ export async function runBackstopDelivery(
     deps.recordOutbound(ids, texts)
   }
 
-  return { sentIds, chunkCount, delivered, attempts, exhausted }
+  return { sentIds, chunkCount, delivered, confirmed, landedUnconfirmedIds, attempts, exhausted }
 }