switchroom 0.18.30 → 0.18.32

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

@@ -40,6 +40,12 @@ export class BackstopDeliveryLedger {
   private chunks = new Map<string, Map<number, number[]>>()
   /** turnId -> chunk indices with an in-flight (pre-ack) send (guard 6). */
   private pending = new Map<string, Set<number>>()
+  /** turnId -> chunk indices whose read-back probe CONFIRMED the message
+   *  actually exists in the chat (#3278). A chunk with a landed message id but
+   *  no confirmation is `landed-unconfirmed` — the Bot API accepted the send but
+   *  a server-side silent discard (flood/anti-spam) can return a fresh id for a
+   *  message the user never sees, so an id alone is NOT proof of delivery. */
+  private confirmed = new Map<string, Set<number>>()
 
   /**
    * Guard 5 — once-per-turn BACKSTOP double-fire latch. Returns `true` on the
@@ -99,6 +105,78 @@ export class BackstopDeliveryLedger {
     return (this.chunks.get(turnId)?.get(index)?.length ?? 0) > 0
   }
 
+  /** The landed message id(s) for one chunk (empty when unsent). The read-back
+   *  probe reads these to confirm every id of the chunk (guard A7 — a
+   *  length-resplit chunk lands >1 id and all must exist to count confirmed). */
+  chunkIds(turnId: string, index: number): number[] {
+    return (this.chunks.get(turnId)?.get(index) ?? []).slice()
+  }
+
+  /**
+   * #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`.
+   */
+  confirmChunk(turnId: string, index: number): void {
+    let set = this.confirmed.get(turnId)
+    if (set == null) {
+      set = new Set()
+      this.confirmed.set(turnId, set)
+    }
+    set.add(index)
+  }
+
+  /**
+   * #3278 — demote a chunk back to `unsent` on a POSITIVE absence read-back
+   * (Telegram `400 message to edit not found`): the send was silently dropped,
+   * so re-sending it is safe (it never reached the user). Clears the landed ids,
+   * the pending marker, and any stale confirmation. NEVER call this on an
+   * ambiguous probe (429/5xx/network) — that would risk a duplicate.
+   */
+  demoteChunk(turnId: string, index: number): void {
+    this.chunks.get(turnId)?.delete(index)
+    this.pending.get(turnId)?.delete(index)
+    this.confirmed.get(turnId)?.delete(index)
+  }
+
+  /** True only for a `landed-confirmed` chunk (read-back proved it exists). */
+  hasConfirmedChunk(turnId: string, index: number): boolean {
+    return this.confirmed.get(turnId)?.has(index) ?? false
+  }
+
+  /** Chunk indices that have landed at least one id but are NOT yet confirmed —
+   *  the set the read-back probe must resolve (confirm / demote / leave). */
+  landedUnconfirmedIndices(turnId: string, chunkCount: number): number[] {
+    const out: number[] = []
+    for (let i = 0; i < chunkCount; i++) {
+      if (this.hasChunk(turnId, i) && !this.hasConfirmedChunk(turnId, i)) out.push(i)
+    }
+    return out
+  }
+
+  /** True IFF every chunk 0..chunkCount-1 is `landed-confirmed`. `chunkCount===0`
+   *  is never "all confirmed" (nothing was delivered). */
+  allConfirmed(turnId: string, chunkCount: number): boolean {
+    if (chunkCount <= 0) return false
+    for (let i = 0; i < chunkCount; i++) {
+      if (!this.hasConfirmedChunk(turnId, i)) return false
+    }
+    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). */
+  confirmedIds(turnId: string): number[] {
+    const m = this.chunks.get(turnId)
+    const set = this.confirmed.get(turnId)
+    if (m == null || set == null) return []
+    const out: number[] = []
+    for (const index of Array.from(m.keys()).sort((a, b) => a - b)) {
+      if (set.has(index)) out.push(...(m.get(index) ?? []))
+    }
+    return out
+  }
+
   /** All landed message ids for this turn, in chunk-index order. */
   sentIds(turnId: string): number[] {
     const m = this.chunks.get(turnId)
@@ -137,9 +215,49 @@ export class BackstopDeliveryLedger {
     this.latched.delete(turnId)
     this.chunks.delete(turnId)
     this.pending.delete(turnId)
+    this.confirmed.delete(turnId)
   }
 }
 
+/**
+ * #3278 — the tri-state a read-back probe resolves a landed chunk into:
+ *  - `exists`    — a no-op `editMessageText` succeeded or returned "message is
+ *                  not modified" ⇒ the message is present at the chat_id ⇒
+ *                  `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).
+ *
+ * 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
+ * it, and it does NOT catch a wrong-thread/chat misroute (the edit succeeds
+ * because the message exists — just not where the operator is looking).
+ * Read-back is necessary-but-not-sufficient; it is paired with the correct
+ * chat/thread resolution already pinned by the backstop caller.
+ */
+export type ReadBackResult = 'exists' | 'absent' | 'ambiguous'
+
+/**
+ * Combine the per-id read-back results of ONE chunk into the chunk's verdict
+ * (guard A7 — a length-resplit chunk lands >1 message id and every id must be
+ * present for the chunk to count confirmed). Pure:
+ *  - ANY id `absent`               ⇒ `absent`   (the chunk is incomplete on the
+ *                                     wire → re-send the whole chunk)
+ *  - ALL ids `exists`              ⇒ `exists`
+ *  - otherwise (some `ambiguous`,
+ *    none `absent`)                ⇒ `ambiguous` (never re-send)
+ *  - empty id set                  ⇒ `ambiguous` (nothing to probe → don't
+ *                                     fabricate a confirmation OR a demotion)
+ */
+export function combineReadBackResults(perId: readonly ReadBackResult[]): ReadBackResult {
+  if (perId.length === 0) return 'ambiguous'
+  if (perId.some(r => r === 'absent')) return 'absent'
+  if (perId.every(r => r === 'exists')) return 'exists'
+  return 'ambiguous'
+}
+
 /**
  * Guard 7 — the RECEIPT gate. Given the raw delivered ids and the progress-card
  * message id (or null), return only the FRESH, non-card chat message ids. A
@@ -175,6 +293,25 @@ export interface BackstopDeliveryDeps {
   /** Record the delivered ids + aligned texts to history (called once, after
    *  the attempts resolve, with the full landed set). */
   recordOutbound?: (messageIds: number[], texts: string[]) => void
+  /**
+   * #3278 read-back confirmation. After a chunk lands a message id, a no-op
+   * `editMessageText` probe re-confirms the message ACTUALLY exists in the chat
+   * (a returned id is only an API accept, not proof of visibility). Returns the
+   * chunk's {@link ReadBackResult} — `exists` ⇒ landed-confirmed, `absent` ⇒
+   * demote to unsent + re-send, `ambiguous` ⇒ stay landed-unconfirmed and NEVER
+   * re-send. Runs once per landed chunk after the send attempts resolve, and is
+   * itself flood-window-paced by the caller (never a storm).
+   *
+   * When OMITTED, a landed chunk is confirmed on landing (pre-#3278 behavior) —
+   * still gated by the fresh-non-card receipt filter, so a card-only "delivery"
+   * is never counted. This is the hot-path default: read-back is scoped to the
+   * RARE backstop delivery, so the reply-tool path issues ZERO probes (§1.3).
+   */
+  readBack?: (
+    chunkIndex: number,
+    messageIds: readonly number[],
+    text: string,
+  ) => Promise<ReadBackResult>
   /** Optional stderr sink for progress/resume logging. */
   stderr?: (s: string) => void
 }
@@ -204,6 +341,14 @@ export interface BackstopDeliveryResult {
  * so the caller can leave the delivery obligation OPEN for the liveness floor
  * to re-present — instead of the old silent `send_failed` drop.
  *
+ * #3278 — after each attempt's sends resolve, every `landed-unconfirmed` chunk
+ * 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.
+ *
  * `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`).
  * The ledger is NOT cleared here — the caller clears it only after success or
@@ -223,37 +368,92 @@ export async function runBackstopDelivery(
 
   for (let attempt = 1; attempt <= Math.max(1, maxAttempts); attempt++) {
     attempts = attempt
+    // 1. SEND the `unsent` chunks (never-landed OR demoted by a prior absent
+    //    read-back), resuming in chunk-index order. Guard 6 keeps a chunk that
+    //    already landed from being re-sent.
     const resume = ledger.unsentIndices(turnId, chunkCount)
-    if (resume.length === 0) break // everything already landed
-    if (attempt > 1) {
-      stderr(
-        `telegram gateway: backstop delivery retry ${attempt}/${maxAttempts} — ` +
-        `resuming at unsent chunk(s) [${resume.join(', ')}] for turn ${turnId}\n`,
-      )
-    }
     let attemptThrew = false
-    try {
-      for (const i of resume) {
-        // Guard 6 — never re-send a chunk that already landed for this turn.
-        if (ledger.hasChunk(turnId, i)) continue
-        ledger.markPending(turnId, i)
-        const ids = await deps.sendChunk(i, chunks[i])
-        ledger.recordChunk(turnId, i, ids)
+    if (resume.length > 0) {
+      if (attempt > 1) {
+        stderr(
+          `telegram gateway: backstop delivery retry ${attempt}/${maxAttempts} — ` +
+          `resuming at unsent chunk(s) [${resume.join(', ')}] for turn ${turnId}\n`,
+        )
+      }
+      try {
+        for (const i of resume) {
+          if (ledger.hasChunk(turnId, i)) continue
+          ledger.markPending(turnId, i)
+          const ids = await deps.sendChunk(i, chunks[i])
+          ledger.recordChunk(turnId, i, ids) // → landed-unconfirmed
+        }
+      } catch (err) {
+        attemptThrew = true
+        stderr(
+          `telegram gateway: backstop delivery attempt ${attempt}/${maxAttempts} failed: ` +
+          `${err instanceof Error ? err.message : String(err)}\n`,
+        )
       }
-    } catch (err) {
-      attemptThrew = true
-      stderr(
-        `telegram gateway: backstop delivery attempt ${attempt}/${maxAttempts} failed: ` +
-        `${err instanceof Error ? err.message : String(err)}\n`,
-      )
     }
-    if (!attemptThrew && ledger.unsentIndices(turnId, chunkCount).length === 0) break
+
+    // 2. CONFIRM landed-unconfirmed chunks via read-back (#3278). Without a probe
+    //    wired, landing IS confirmation (pre-#3278) — the fresh-non-card receipt
+    //    filter below still rejects a card-only "delivery".
+    let demotedAny = false
+    for (const i of ledger.landedUnconfirmedIndices(turnId, chunkCount)) {
+      if (deps.readBack == null) {
+        ledger.confirmChunk(turnId, i)
+        continue
+      }
+      let verdict: ReadBackResult
+      try {
+        verdict = await deps.readBack(i, ledger.chunkIds(turnId, i), chunks[i])
+      } catch (err) {
+        // A probe adapter that itself throws must NEVER trigger a re-send.
+        verdict = 'ambiguous'
+        stderr(
+          `telegram gateway: backstop read-back probe threw for chunk ${i} ` +
+          `(turn ${turnId}) — treating as ambiguous: ` +
+          `${err instanceof Error ? err.message : String(err)}\n`,
+        )
+      }
+      if (verdict === 'exists') {
+        ledger.confirmChunk(turnId, i)
+      } else if (verdict === 'absent') {
+        // Positive absence — the send was silently dropped. Safe to re-send.
+        ledger.demoteChunk(turnId, i)
+        demotedAny = true
+        stderr(
+          `telegram gateway: backstop read-back — chunk ${i} not found in chat ` +
+          `(turn ${turnId}); demoting to unsent for re-send\n`,
+        )
+      } else {
+        // Ambiguous (429/5xx/network/gate-shed) — leave landed-unconfirmed and
+        // NEVER re-send it (would risk a duplicate).
+        stderr(
+          `telegram gateway: backstop read-back — chunk ${i} ambiguous ` +
+          `(turn ${turnId}); left landed-unconfirmed, not re-sending\n`,
+        )
+      }
+    }
+
+    // 3. Fully confirmed ⇒ done.
+    if (ledger.allConfirmed(turnId, chunkCount)) break
+    // 4. Another attempt ONLY re-sends chunks demoted to `unsent`. If nothing is
+    //    unsent, the remaining non-confirmed chunks are all `landed-unconfirmed`
+    //    (ambiguous) — re-sending them would duplicate, so stop here.
+    if (ledger.unsentIndices(turnId, chunkCount).length === 0) break
+    // 5. Guard against a spin: if this attempt neither sent, threw, nor demoted
+    //    anything, another identical attempt is pointless.
+    if (resume.length === 0 && !attemptThrew && !demotedAny) break
   }
 
   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 delivered =
-    chunkCount > 0 && ledger.unsentIndices(turnId, chunkCount).length === 0 &&
-    backstopReceiptIds(sentIds, cardMessageId).length > 0
+    ledger.allConfirmed(turnId, chunkCount) &&
+    backstopReceiptIds(ledger.confirmedIds(turnId), cardMessageId).length > 0
   const exhausted = !delivered
 
   if (deps.recordOutbound && sentIds.length > 0) {

package/telegram-plugin/gateway/captured-answer-resume.ts

@@ -0,0 +1,259 @@
+/**
+ * captured-answer-resume.ts — durable captured-answer resume for a partially
+ * delivered turn-flush backstop (#3282).
+ *
+ * ── The bug this closes ──────────────────────────────────────────────────────
+ * When the turn-flush backstop (`deliverAnswer` → `runBackstopDelivery`) lands
+ * chunks 0,1 of a 3-chunk answer but chunk 2 exhausts its bounded retries, the
+ * turn-flush IIFE historically (a) cleared the per-chunk `BackstopDeliveryLedger`
+ * unconditionally and (b) left the delivery obligation OPEN. The liveness floor
+ * then re-presented the obligation as a FRESH must-answer model turn, which
+ * REGENERATED the whole answer — re-posting chunks 0,1's content the user already
+ * received. Result: the user sees the head of the answer twice after a partial
+ * failure (or after a restart mid-delivery). #3282.
+ *
+ * ── The fix (design-of-record §2.2) ─────────────────────────────────────────
+ * Make the re-present a *byte-identical captured-answer resume* of ONLY the
+ * not-yet-`landed-confirmed` tail — never a regeneration — so a chunk that
+ * already reached the chat is provably never re-posted:
+ *
+ *   1. On a partial (`!delivered`) turn-flush, persist a {@link
+ *      CapturedDeliverySnapshot} (the split chunks + each landed chunk's ids and
+ *      confirmed flag) onto the durable obligation record, keyed by
+ *      `originTurnId`. This rides the obligation ledger's existing atomic
+ *      snapshot, so it survives a gateway/container restart.
+ *   2. The obligation sweep's `represent` branch becomes source-aware: when the
+ *      obligation carries a captured-delivery snapshot it drives THIS resume
+ *      (re-run `runBackstopDelivery` for the SAME `turnId` and the SAME captured
+ *      chunks, resuming at the first non-`landed-confirmed` index) instead of
+ *      pushing a fresh-generation inbound. No snapshot ⇒ the genuine "model wrote
+ *      nothing / never fired a backstop" case falls through to fresh generation
+ *      unchanged.
+ *   3. The in-memory ledger is rehydrated from the snapshot AND reconciled against
+ *      the durable outbound-text oracle (`hasOutboundWithText`), so a chunk that
+ *      landed a durable history row is confirmed even if the snapshot's flag was
+ *      not yet flushed when the process died (crash-idempotency, design §2.3/A5).
+ *
+ * Chunk identity is the chunk INDEX within `turnId`, stable across the represent
+ * boundary and across restart because the resume re-delivers the exact captured
+ * chunks (not a regenerated answer). #3278's per-chunk state machine
+ * (`unsent → pending → landed-unconfirmed → {landed-confirmed | unsent}`) binds
+ * here too: the resume re-PROBES `landed-unconfirmed` chunks (never re-sends
+ * them) and re-SENDS only `unsent` ones, so a confirmed chunk is never duplicated
+ * by either the in-fire retry OR the cross-represent resume.
+ *
+ * This module is PURE state + orchestration over injected effects — no Telegram,
+ * no SQLite, no gateway module state — so the resume decision is unit-testable
+ * (see tests/captured-answer-resume.test.ts). The gateway owns the real
+ * `deliver` (via `deliverAnswer`), the durable oracle, and the obligation I/O.
+ */
+
+import { hasOutboundWithText } from '../history.js'
+import type { BackstopDeliveryLedger } from './backstop-delivery.js'
+import type { CapturedDeliverySnapshot, Obligation } from './obligation-ledger.js'
+
+/**
+ * Build the durable {@link CapturedDeliverySnapshot} from the live per-chunk
+ * ledger after a partial `runBackstopDelivery`. Captures every LANDED chunk's
+ * message ids + confirmed flag so the resume can (a) never re-send a confirmed
+ * chunk and (b) re-PROBE a landed-unconfirmed chunk instead of blindly re-sending
+ * it. Chunks that never landed (send threw) are simply absent → the resume treats
+ * them as `unsent` and re-sends them. Pure.
+ */
+export function buildCapturedDeliverySnapshot(
+  ledger: BackstopDeliveryLedger,
+  turnId: string,
+  chunks: readonly string[],
+): CapturedDeliverySnapshot {
+  const chunkStates = ledger.entries(turnId).map(({ index, messageIds }) => ({
+    index,
+    messageIds,
+    confirmed: ledger.hasConfirmedChunk(turnId, index),
+  }))
+  return { chunks: [...chunks], chunkStates }
+}
+
+/**
+ * Rehydrate a `BackstopDeliveryLedger` for a captured-answer resume from a
+ * durable snapshot, reconciled against the durable outbound-text oracle. For each
+ * landed chunk in the snapshot:
+ *   - re-record its landed message id(s) so `unsentIndices` excludes it (the
+ *     resume never re-sends a chunk that already landed);
+ *   - mark it `landed-confirmed` when the snapshot flag says so OR the oracle
+ *     proves its text is a durable outbound row (crash-idempotency, §2.3/A5) —
+ *     a confirmed chunk is neither re-probed nor re-sent.
+ * Chunks absent from the snapshot stay `unsent` (re-sent by the resume). Pure over
+ * the injected `hasLanded` oracle.
+ */
+export function hydrateResumeLedger(
+  ledger: BackstopDeliveryLedger,
+  turnId: string,
+  snapshot: CapturedDeliverySnapshot,
+  hasLanded: (chunkText: string, index: number) => boolean,
+): void {
+  for (const st of snapshot.chunkStates) {
+    if (st.messageIds.length === 0) continue // never actually landed → leave unsent
+    ledger.recordChunk(turnId, st.index, [...st.messageIds])
+    if (st.confirmed || hasLanded(snapshot.chunks[st.index] ?? '', st.index)) {
+      ledger.confirmChunk(turnId, st.index)
+    }
+  }
+}
+
+/** The args the module hands the gateway's `deliverAnswer` to run a resume. */
+export interface CapturedResumeArgs {
+  chatId: string
+  threadId: number | undefined
+  text: string
+  turnId: string
+  cardMessageId: number | null
+  replyToMessageId: number | null
+  resume: {
+    snapshot: CapturedDeliverySnapshot
+    hydrate: (ledger: BackstopDeliveryLedger, turnId: string) => void
+  }
+}
+
+/**
+ * The RAW gateway singletons the dispatcher wires. Structural (no gateway class
+ * imports) and kept minimal so the gateway injection stays a handful of lines
+ * under the gateway.ts line ratchet — the module builds every resume closure
+ * (the `deliverAnswer` resume args, the oracle-reconciled hydrate, the supersede
+ * record) itself.
+ */
+export interface CapturedResumePorts {
+  /** The gateway's `deliverAnswer`, invoked in RESUME mode (byte-identical tail,
+   *  no card gate). Only `delivered`/`sentIds` are read. */
+  deliverAnswer: (args: CapturedResumeArgs) => Promise<{ delivered: boolean; sentIds: number[] }>
+  /** The single obligation ledger. `markRepresented` consumes one represent-budget
+   *  unit + stamps the per-represent grace (bounding the resume ladder exactly
+   *  like a fresh-generation represent → escalate at the cap); `close` drops the
+   *  captured snapshot once fully delivered. */
+  obligationLedger: {
+    markRepresented: (originTurnId: string) => unknown
+    close: (originTurnId: string) => unknown
+  }
+  /** The per-chunk backstop ledger — GC'd for a fully delivered turn. */
+  backstopDeliveryLedger: { clear: (turnId: string) => void }
+  /** flushedTurnSupersede — feed the resume's fresh chat ids in so a late reply
+   *  after the resumed tail still corrects the delivered set (design §4). */
+  flushedTurnSupersede: {
+    record: (
+      chatId: string,
+      threadId: number | undefined,
+      rec: { turnId: string; messageIds: number[]; text: string },
+      nowMs: number,
+    ) => void
+  }
+  /** True when history is queryable (else the durable-text oracle reconcile that
+   *  gives crash-idempotency — §2.3/A5 — is skipped). */
+  historyEnabled: boolean
+  stderr?: (s: string) => void
+}
+
+export interface CapturedResumeDispatcher {
+  /** Fire a captured-answer resume for `o` (fire-and-forget; the sweep is sync).
+   *  De-duped per `originTurnId` so two sweeps never launch concurrent resumes;
+   *  a no-op when `o` carries no non-empty captured snapshot (the caller should
+   *  then fall through to fresh generation). */
+  dispatch: (o: Obligation) => void
+  /** In-flight origin ids (test introspection). */
+  inFlight: () => string[]
+}
+
+/**
+ * The obligation-sweep's captured-answer resume driver. Owns the in-flight guard
+ * + the deliver→close/leave-open orchestration so the gateway sweep stays a
+ * two-line dispatch. On each dispatch it consumes one represent-budget unit
+ * (bounding the ladder → escalate), re-delivers only the non-confirmed tail, and:
+ *   - fully delivered ⇒ record the supersede tail, close the obligation, GC the
+ *     ledger (the represent ladder stops);
+ *   - still partial / error ⇒ leave the obligation OPEN so the next eligible
+ *     sweep (after the per-represent grace) retries, until the represent cap
+ *     escalates it to the operator nudge — no infinite loop.
+ */
+export function createCapturedResumeDispatcher(ports: CapturedResumePorts): CapturedResumeDispatcher {
+  const stderr = ports.stderr ?? (() => {})
+  const inFlight = new Set<string>()
+
+  /** Re-deliver the non-confirmed tail of `o`'s captured answer, byte-identical,
+   *  by rehydrating the per-chunk ledger from the snapshot reconciled against the
+   *  durable text oracle. Never regenerates. */
+  function deliver(o: Obligation, snapshot: CapturedDeliverySnapshot): Promise<{ delivered: boolean; sentIds: number[] }> {
+    return ports.deliverAnswer({
+      chatId: o.chatId,
+      threadId: o.threadId,
+      text: '',
+      turnId: o.originTurnId,
+      cardMessageId: null,
+      replyToMessageId: o.messageId,
+      resume: {
+        snapshot,
+        hydrate: (ledger, turnId) =>
+          hydrateResumeLedger(ledger, turnId, snapshot, (txt) =>
+            ports.historyEnabled &&
+            hasOutboundWithText(o.chatId, txt, o.threadId ?? null, o.openedAt),
+          ),
+      },
+    })
+  }
+
+  /** Record the resume's FULL delivered id set (rehydrated-confirmed + freshly
+   *  re-sent — `runBackstopDelivery` returns `ledger.sentIds`, i.e. all landed
+   *  ids in index order) into the supersede lane, keyed by the turn id. This
+   *  REPLACES the partial turn-flush record in place with the complete set, so a
+   *  late reply for this turn corrects the WHOLE delivered answer (design §4) —
+   *  no-op when nothing has landed. */
+  function supersede(o: Obligation, snapshot: CapturedDeliverySnapshot, sentIds: number[]): void {
+    if (sentIds.length === 0) return
+    ports.flushedTurnSupersede.record(
+      o.chatId,
+      o.threadId,
+      { turnId: o.originTurnId, messageIds: sentIds, text: snapshot.chunks.join('') },
+      Date.now(),
+    )
+  }
+
+  async function run(o: Obligation, snapshot: CapturedDeliverySnapshot): Promise<void> {
+    try {
+      const { delivered, sentIds } = await deliver(o, snapshot)
+      supersede(o, snapshot, sentIds)
+      if (delivered) {
+        ports.obligationLedger.close(o.originTurnId)
+        ports.backstopDeliveryLedger.clear(o.originTurnId)
+        stderr(
+          `telegram gateway: captured-answer resume delivered — origin=${o.originTurnId} ` +
+            `${sentIds.length} chunk(s) confirmed; obligation closed\n`,
+        )
+      } else {
+        // Tail still not confirmed — leave the obligation OPEN for the next paced
+        // sweep / escalation (bounded by the represent cap).
+        stderr(
+          `telegram gateway: captured-answer resume partial — origin=${o.originTurnId} ` +
+            `tail still not confirmed; left OPEN for retry\n`,
+        )
+      }
+    } catch (err) {
+      stderr(
+        `telegram gateway: captured-answer resume error — origin=${o.originTurnId}: ` +
+          `${err instanceof Error ? err.message : String(err)}\n`,
+      )
+    } finally {
+      inFlight.delete(o.originTurnId)
+    }
+  }
+
+  return {
+    dispatch(o: Obligation): void {
+      const snapshot = o.capturedDelivery
+      if (snapshot == null || snapshot.chunks.length === 0) return
+      if (inFlight.has(o.originTurnId)) return
+      inFlight.add(o.originTurnId)
+      // Consume represent budget + arm the per-represent grace up front so the
+      // ladder is bounded and the sweep can't immediately re-dispatch mid-flight.
+      ports.obligationLedger.markRepresented(o.originTurnId)
+      void run(o, snapshot)
+    },
+    inFlight: () => [...inFlight],
+  }
+}

package/telegram-plugin/gateway/disconnect-flush.ts

@@ -37,17 +37,6 @@ export interface DisconnectFlushDeps<Ctrl extends { finalize: (reason?: 'done' |
   activeReactionMsgIds: Map<string, { chatId: string; messageId: number }>
   /** Mirror map: same keys → turn-start timestamps. */
   activeTurnStartedAt: Map<string, number>
-  /** PR3b: keys claude has actually been handed (delivered, not just
-   *  received). Cleared on disconnect for the same reason as
-   *  activeTurnStartedAt — the bridge just died, every turn it
-   *  was handed is dead by definition. */
-  claudeBusyKeys: Set<string>
-  /** #2787: insertion-timestamp map for `claudeBusyKeys`, backing the orphan
-   *  reaper. MUST stay in lockstep with `claudeBusyKeys` at every clear site —
-   *  a stale timestamp surviving a clear makes a later re-marked key look
-   *  >TTL-old and get reaped against a live delivery. Deleted alongside every
-   *  `claudeBusyKeys.delete`/`.clear` below. */
-  claudeBusyKeySince: Map<string, number>
 
   /** Open draft-stream handles keyed by chat:thread:replyId. */
   activeDraftStreams: Map<string, Stream>
@@ -96,8 +85,6 @@ export function flushOnAgentDisconnect<
     activeStatusReactions,
     activeReactionMsgIds,
     activeTurnStartedAt,
-    claudeBusyKeys,
-    claudeBusyKeySince,
     activeDraftStreams,
     clearActiveReactions,
     disposeProgressDriver,
@@ -125,8 +112,6 @@ export function flushOnAgentDisconnect<
     activeStatusReactions.delete(key)
     activeReactionMsgIds.delete(key)
     activeTurnStartedAt.delete(key)
-    claudeBusyKeys.delete(key)
-    claudeBusyKeySince.delete(key) // #2787: keep orphan-TTL map in lockstep
   }
   clearActiveReactions()
 
@@ -146,8 +131,6 @@ export function flushOnAgentDisconnect<
     for (const k of danglingKeys) {
       activeTurnStartedAt.delete(k)
       activeReactionMsgIds.delete(k)
-      claudeBusyKeys.delete(k)
-      claudeBusyKeySince.delete(k) // #2787: keep orphan-TTL map in lockstep
     }
     log(
       `telegram gateway: disconnect-flush swept ${danglingKeys.length} dangling turn key(s) ` +
@@ -156,33 +139,12 @@ export function flushOnAgentDisconnect<
     onDanglingTurnsSwept?.(danglingKeys)
   }
 
-  // PR3b orphan-sweep (#1880 follow-up): claudeBusyKeys can hold keys
-  // that activeTurnStartedAt does NOT — specifically when a synthetic
-  // inbound (cron via onInjectInbound, reaction dispatch, vault
-  // grant-approved / -denied / save-discarded / -failed / -completed,
-  // button-callback) was delivered. Those paths bypass handleInbound's
-  // fresh-turn branch (which is what would set activeTurnStartedAt),
-  // so the sweep loop above wouldn't notice them. Pre-PR3b this was
-  // invisible because the fleet gate read activeTurnStartedAt.size —
-  // synthetic-only turns never registered. PR3b's claudeBusyKeys.add
-  // is the more-accurate "claude is busy on this" gate, which means
-  // a synthetic-delivered turn that dies WITHOUT turn_end leaves an
-  // orphan that the activeTurnStartedAt-keyed sweep can't see.
-  // Cure: clear any leftover busy keys here. Bridge died → every
-  // busy key is dead by definition. Same justification as the
-  // dangling-sweep above for activeTurnStartedAt.
-  if (claudeBusyKeys.size > 0) {
-    const orphanCount = claudeBusyKeys.size
-    const orphanKeys = [...claudeBusyKeys]
-    claudeBusyKeys.clear()
-    // #2787: keep the orphan-TTL map in lockstep with the set it shadows.
-    for (const k of orphanKeys) claudeBusyKeySince.delete(k)
-    log(
-      `telegram gateway: disconnect-flush cleared ${orphanCount} orphan claudeBusyKeys ` +
-      `entr${orphanCount === 1 ? 'y' : 'ies'} (synthetic-inbound deliveries that never turn_ended)` +
-      ` keys=${orphanKeys.join(',')}`,
-    )
-  }
+  // (#2996 P1) The PR3b `claudeBusyKeys` orphan-sweep that lived here was
+  // deleted with the set itself: the delivery machine's `bridgeDown` event
+  // — emitted by the gateway's onClientDisconnected alongside this flush —
+  // resets the machine to bridge_dead, which structurally clears the
+  // turn-in-flight gate for synthetic-delivered turns that died without a
+  // turn_end (the case the sweep existed for).
 
   // Stop coalesce timers that could emit into a finalized draft stream, but
   // preserve chats with pendingCompletion=true — those have background