switchroom 0.18.30 → 0.18.32

package/telegram-plugin/gateway/turn-flush-suppression.ts

@@ -0,0 +1,82 @@
+/**
+ * Turn-flush pre-delivery suppression decision (S1 fix, fable red-team
+ * 2026-07-17 — `~klanker/work/fable-redteam-delivery-20260717/REDTEAM.md`).
+ *
+ * Before the turn-flush backstop posts the captured terminal answer, it asks:
+ * "did a reply already land for this turn in the last ~2s?" (a race guard for
+ * a reply whose IPC signal hadn't registered when `decideTurnFlush` ran, and
+ * for answer-stream materializations that already delivered the answer text).
+ *
+ * The OLD predicate — `getRecentOutboundCount(chatId, 2) > 0` — counted ANY
+ * assistant row in the WHOLE chat: a background worker's `progress_update`, a
+ * command ack / restart notice, or a reply in a DIFFERENT forum topic all
+ * suppressed the flush, and the branch then CLOSED the delivery obligation —
+ * the user's real answer was dropped with no re-present. This module scopes
+ * the predicate to a SUBSTANTIVE (≥ `FINAL_ANSWER_MIN_CHARS`) outbound in the
+ * SAME thread, via the injected `hasSubstantiveOutbound` (the gateway wires
+ * `hasOutboundDeliveredSince`, whose thread/length semantics are pinned by
+ * `history.test.ts`).
+ *
+ * Residual (documented, accepted): a ≥200-char same-thread non-answer outbound
+ * (e.g. an unusually long progress update) inside the 2s window still
+ * suppresses — the history schema has no message-kind column to discriminate
+ * further. That residual is why the CALLER must NOT close the obligation on
+ * suppression: a genuine reply closes its own obligation idempotently, while a
+ * false-positive suppression leaves it open for the liveness floor / sweep.
+ */
+
+import { FINAL_ANSWER_MIN_CHARS } from '../final-answer-detect.js'
+
+/** How far back a just-landed reply can be and still suppress the flush. */
+export const FLUSH_SUPPRESSION_WINDOW_MS = 2000
+
+export interface FlushSuppressionDeps {
+  /** Durable substantive-outbound oracle — the gateway passes
+   *  `hasOutboundDeliveredSince` (thread-scoped, length-floored). */
+  hasSubstantiveOutbound(
+    chatId: string,
+    sinceMs: number,
+    threadId: number | null,
+    minChars: number,
+  ): boolean
+}
+
+export interface FlushSuppressionArgs {
+  chatId: string
+  /** The turn's origin thread. `null` = chat root / DM (matches the
+   *  `hasOutboundDeliveredSince` explicit-null semantics — never pass
+   *  `undefined`, which would match ANY thread and re-open the
+   *  cross-topic false positive this module exists to close). */
+  threadId: number | null
+  /** Length of the captured answer the flush is about to deliver. The
+   *  length floor is `min(FINAL_ANSWER_MIN_CHARS, answerLength)`: a row
+   *  can only suppress the flush if it is at least as long as the answer
+   *  itself (up to the 200-char substantive cap). A TERSE captured answer
+   *  ("Yes — done.") is therefore still suppressible by its own short
+   *  answer-stream materialization (avoiding a duplicate bubble), while a
+   *  short progress ping can never suppress a LONG composed answer. */
+  answerLength: number
+  nowMs: number
+}
+
+/**
+ * True iff the flush should be suppressed: a substantive same-thread outbound
+ * landed within the suppression window. Fails open (no suppression) on oracle
+ * errors — delivering a possible duplicate beats dropping the only copy.
+ */
+export function shouldSuppressTurnFlush(
+  deps: FlushSuppressionDeps,
+  args: FlushSuppressionArgs,
+): boolean {
+  const minChars = Math.max(1, Math.min(FINAL_ANSWER_MIN_CHARS, args.answerLength))
+  try {
+    return deps.hasSubstantiveOutbound(
+      args.chatId,
+      args.nowMs - FLUSH_SUPPRESSION_WINDOW_MS,
+      args.threadId,
+      minChars,
+    )
+  } catch {
+    return false
+  }
+}

package/telegram-plugin/pending-user-notice.ts

@@ -36,6 +36,25 @@ export interface PendingUserNotice {
   kind: string
   /** When the notice was scheduled (ms epoch). */
   atMs: number
+  /**
+   * TOPIC KEY (#3294) — `statusKey(chatId, threadId)` of the turn that was live
+   * when the error surfaced, or `undefined` when no turn was attributable (the
+   * error arrived between turns, or after a silence poke nulled the live turn).
+   *
+   * Why it exists: the api_error operator event is agent-level (its wire
+   * `chatId` is always empty), so the gate USED to collapse per-agent and let
+   * ANY turn end resolve the notice. Under the PR-4e keyed-liveness flag
+   * (concurrent per-topic turns) that is a bug: turn B's reply-less end would
+   * flush turn A's pending notice while A may still recover — a FALSE "couldn't
+   * complete" claim. Keying the notice by the live turn's topic means only a
+   * turn end on the SAME topic resolves it (see {@link
+   * PendingUserNoticeGate.resolveTurnEnd}).
+   *
+   * A notice with an UNDEFINED key keeps the legacy agent-wide resolution (any
+   * turn end resolves it), so single-turn gateways — the current norm, where
+   * there is only ever one topic — are byte-identical to the pre-#3294 gate.
+   */
+  key?: string
 }
 
 /** How long a scheduled notice may wait for a resolving turn end. */
@@ -45,28 +64,55 @@ export class PendingUserNoticeGate {
   private pending: PendingUserNotice[] = []
 
   /**
-   * Schedule a notice for turn-end resolution. Collapses per agent — a burst
-   * of error lines within one turn holds ONE pending notice, not a stack.
+   * Schedule a notice for turn-end resolution. Collapses per (agent, topic key)
+   * — a burst of error lines within one turn holds ONE pending notice for that
+   * topic, not a stack. Distinct concurrent topics (keyed liveness) each keep
+   * their own pending notice, so one topic's burst never overwrites another's.
+   * (For a single-turn gateway every notice shares the one topic — or an
+   * undefined key — so the collapse is identical to the pre-#3294 per-agent one.)
    */
   schedule(notice: PendingUserNotice): void {
     this.prune(notice.atMs)
-    this.pending = this.pending.filter((p) => p.agent !== notice.agent)
+    this.pending = this.pending.filter(
+      (p) => !(p.agent === notice.agent && p.key === notice.key),
+    )
     this.pending.push(notice)
   }
 
   /**
-   * Resolve at turn end. `turnDeliveredReply` is the turn's outcome signal
-   * (the gateway passes `finalAnswerDelivered || replyCalled`):
-   *   - true  → the turn recovered; every pending notice is dropped, [] returned.
-   *   - false → the turn died without a reply; the un-expired pending notices
-   *     are returned EXACTLY ONCE for the caller to send.
-   * Either way the ledger is cleared (a notice never survives its turn end).
+   * Resolve at the end of the turn whose topic is `turnKey`. `turnDeliveredReply`
+   * is the turn's outcome signal (the gateway passes `finalAnswerDelivered ||
+   * replyCalled`).
+   *
+   * A pending notice is RESOLVED by this turn end iff it belongs to the ending
+   * turn's topic (`p.key === turnKey`) OR it is unattributed (`p.key ===
+   * undefined` — legacy agent-wide resolution, kept so single-turn gateways are
+   * unchanged). Notices scheduled for a DIFFERENT live topic stay pending until
+   * their own topic's turn ends (or the TTL expires) — this is the #3294 fix:
+   * turn B's end no longer flushes turn A's pending notice.
+   *
+   * Of the resolved notices:
+   *   - `turnDeliveredReply === true`  → the turn recovered; the resolved
+   *     notices are dropped and `[]` is returned.
+   *   - `turnDeliveredReply === false` → the turn died reply-less; the resolved,
+   *     un-expired notices are returned EXACTLY ONCE for the caller to send.
+   * Either way the resolved notices leave the ledger (a notice never survives
+   * the end of the turn it is keyed to).
    */
-  resolveTurnEnd(turnDeliveredReply: boolean, now: number = Date.now()): PendingUserNotice[] {
+  resolveTurnEnd(
+    turnKey: string | undefined,
+    turnDeliveredReply: boolean,
+    now: number = Date.now(),
+  ): PendingUserNotice[] {
     this.prune(now)
-    const out = turnDeliveredReply ? [] : [...this.pending]
-    this.pending = []
-    return out
+    const resolved: PendingUserNotice[] = []
+    const remaining: PendingUserNotice[] = []
+    for (const p of this.pending) {
+      if (p.key === turnKey || p.key === undefined) resolved.push(p)
+      else remaining.push(p)
+    }
+    this.pending = remaining
+    return turnDeliveredReply ? [] : resolved
   }
 
   /** True when at least one un-expired notice is pending (does not mutate). */

package/telegram-plugin/subagent-watcher.ts

@@ -855,13 +855,14 @@ const BACKFILL_RETRY_INTERVAL_MS = 3000
 
 /**
  * Fix #9a: cap on `terminatedAgentIds` (the re-discovery dedup guard in
- * `cleanupTerminalAgent` / `scanSubagentsDir`). Pre-fix the Set only grew
+ * `cleanupTerminalAgent` / `scanSubagentsDir`). Pre-fix the map only grew
  * (added on every terminal cleanup, only ever cleared wholesale in
  * `stop()`), so a long-lived gateway with sustained sub-agent throughput
- * accumulated ids without bound. A `Set` preserves insertion order, so once
+ * accumulated ids without bound. A `Map` preserves insertion order, so once
  * the cap is hit the OLDEST id is evicted on each new insert (simple ring
  * buffer semantics) — recently-terminated ids (the ones actually at risk of
- * a re-discovery race) always stay covered.
+ * a re-discovery race, or of a SendMessage resume — issue #3315) always stay
+ * covered.
  */
 const TERMINATED_AGENT_IDS_CAP = 5000
 
@@ -1861,18 +1862,26 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
   const historicalFiles = new Set<string>()
   /**
    * AgentIds that have transitioned to a terminal state and been swept
-   * out of `registry` by `cleanupTerminalAgent`. Issue #1116 (Bug B):
-   * the JSONL file outlives the registry entry — Claude Code leaves
-   * the file on disk after the sub-agent finishes. Without this guard,
-   * the next `rescanSubagentDirs` poll re-discovered the file, called
-   * `registerAgent`, the fresh entry read the terminal `turn_duration`
-   * line, and `maybySendStateTransition` fired a duplicate "Worker done"
-   * notification — looping forever every grace-window.
+   * out of `registry` by `cleanupTerminalAgent`, mapped to the JSONL byte
+   * SIZE at cleanup time. Issue #1116 (Bug B): the JSONL file outlives the
+   * registry entry — Claude Code leaves the file on disk after the sub-agent
+   * finishes. Without this guard, the next `rescanSubagentDirs` poll
+   * re-discovered the file, called `registerAgent`, the fresh entry read the
+   * terminal `turn_duration` line, and `maybySendStateTransition` fired a
+   * duplicate "Worker done" notification — looping forever every grace-window.
    *
-   * `scanSubagentsDir` consults this set and treats re-discovered
-   * terminal JSONLs as a no-op.
+   * Issue #3315 (SendMessage resume): a resumed sub-agent reuses the SAME
+   * `agent-<id>.jsonl`, appending a NEW turn to it — so the file's size grows
+   * PAST the size it had at terminal cleanup. `scanSubagentsDir` compares the
+   * live file size against this recorded terminal size: at/below it the JSONL
+   * is a static leftover and stays suppressed (#1116 Bug B); above it the
+   * worker resumed and is re-registered live (#3315) so its progress card
+   * updates again. Storing the size (not a bare membership flag) is what makes
+   * that distinction deterministic and lifecycle-driven rather than a
+   * heuristic. Map iteration order is insertion order, so the eviction ring
+   * buffer (Fix #9a) still evicts the oldest id.
    */
-  const terminatedAgentIds = new Set<string>()
+  const terminatedAgentIds = new Map<string, number>()
   /**
    * Issue #3023 (card resurrection). Per-worker record of a FALSE terminal
    * finish — a terminal state produced by silent-stall synthesis (NOT a real
@@ -1916,7 +1925,17 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
 
   // ─── Per-agent registration ─────────────────────────────────────────────
 
-  function registerAgent(filePath: string, agentId: string): void {
+  /**
+   * @param resumeFromCursor Issue #3315: when re-registering a worker whose
+   *   JSONL resumed growing after a terminal cleanup (a SendMessage resume),
+   *   start the tail cursor at the terminal byte boundary instead of 0. The
+   *   already-handed-back completed turn (its `sub_agent_turn_end` and all
+   *   prior events) is therefore never re-read — so the fresh entry stays
+   *   `running` on the NEW turn's content rather than instantly re-reading the
+   *   old terminal line and re-finalising. Omitted (⇒ 0) for every normal
+   *   registration, which reads from the start.
+   */
+  function registerAgent(filePath: string, agentId: string, resumeFromCursor?: number): void {
     if (registry.has(agentId)) return
     const n = nowFn()
     const isHistorical = historicalFiles.has(filePath)
@@ -1976,7 +1995,12 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     }
 
     const tail: SubTail = {
-      cursor: 0, // read from start to capture description
+      // Normally read from the start (to replay the full transcript); on a
+      // resume re-registration (#3315) start at the terminal boundary so only
+      // the new turn is read. A resumed cursor sits on a JSONL newline boundary
+      // (the prior turn ended with a complete `turn_end` line), so no partial
+      // line is straddled.
+      cursor: resumeFromCursor ?? 0,
       pendingPartial: '',
       hasEmittedStart: false,
       watcher: null,
@@ -2274,24 +2298,42 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       try { tail.watcher.close() } catch { /* ignore */ }
       tail.watcher = null
     }
-    tails.delete(agentId)
     const entry = registry.get(agentId)
+    // Issue #3315: snapshot the JSONL byte size at cleanup so a later
+    // SendMessage-resume — which appends a NEW turn to the SAME
+    // agent-<id>.jsonl — is detected by `scanSubagentsDir` as growth PAST this
+    // size and re-registered. The on-disk stat is the source of truth (it
+    // captures any bytes that landed during the terminal-cleanup grace window,
+    // so only genuinely post-cleanup writes trip a resume); fall back to the
+    // tail cursor, then 0, when the file is unreadable.
+    let terminalSize = tail?.cursor ?? 0
+    if (entry?.filePath) {
+      try {
+        terminalSize = fs.statSync(entry.filePath).size
+      } catch { /* keep the cursor-based fallback */ }
+    }
+    tails.delete(agentId)
     if (entry?.filePath) {
       knownFiles.delete(entry.filePath)
     }
     registry.delete(agentId)
     // Issue #1116 (Bug B): record that this agent has been fully
-    // processed so a rescan that rediscovers the still-present JSONL
-    // doesn't re-register and re-notify.
+    // processed so a rescan that rediscovers the still-present (unchanged)
+    // JSONL doesn't re-register and re-notify. The recorded value is the
+    // terminal byte size (issue #3315): `scanSubagentsDir` keeps suppressing
+    // while the file stays at/below it, and re-registers once it grows past it
+    // (a resume).
     //
-    // Fix #9a: bound the Set so it can't grow unboundedly over a long-lived
-    // gateway — evict the oldest id once the cap is hit (Set iteration
-    // order is insertion order, so `.values().next().value` is the oldest).
+    // Fix #9a: bound the Map so it can't grow unboundedly over a long-lived
+    // gateway — evict the oldest id once the cap is hit (Map iteration
+    // order is insertion order, so the first key is the oldest). A re-set of
+    // an existing key updates its value without moving it, so a re-completed
+    // (resumed-then-finished-again) agent just refreshes its terminal size.
     if (!terminatedAgentIds.has(agentId) && terminatedAgentIds.size >= terminatedAgentIdsCap) {
-      const oldest = terminatedAgentIds.values().next().value
+      const oldest = terminatedAgentIds.keys().next().value
       if (oldest != null) terminatedAgentIds.delete(oldest)
     }
-    terminatedAgentIds.add(agentId)
+    terminatedAgentIds.set(agentId, terminalSize)
     log?.(`subagent-watcher: cleaned up terminal agent ${agentId}`)
     // Authoritative terminal sweep → notify the worker-activity feed so its row
     // for this agent is removed even on the paths that never fire `onFinish`
@@ -2865,11 +2907,52 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       const filePath = join(subagentsPath, e)
       if (knownFiles.has(filePath)) continue
       const agentId = e.slice('agent-'.length, -'.jsonl'.length)
-      // Issue #1116 (Bug B): skip JSONLs whose agent already completed
-      // and was swept by cleanupTerminalAgent. Re-adding to knownFiles
-      // here would let a subsequent rescan re-register, fire a duplicate
-      // "Worker done", and loop forever every grace-window.
-      if (terminatedAgentIds.has(agentId)) continue
+      // Issue #1116 (Bug B) + issue #3315 (SendMessage resume). A rediscovered
+      // JSONL whose agent already went terminal + was swept is normally a
+      // static leftover Claude Code left on disk — re-registering it would
+      // re-read the terminal turn and re-fire a duplicate handback, looping
+      // every grace-window (#1116). BUT a SendMessage resume appends a NEW turn
+      // to the SAME agent-<id>.jsonl, growing the file PAST the size it had at
+      // terminal cleanup. That growth is the deterministic, lifecycle-driven
+      // signal (not a heuristic) that the worker resumed and must be tracked
+      // again so its progress card resumes updating. Distinguish the two by the
+      // recorded terminal size.
+      const terminalSize = terminatedAgentIds.get(agentId)
+      if (terminalSize !== undefined) {
+        // A worker whose terminal state was a FALSE finish (silent-stall
+        // synthesis) is owned by the issue-#3023 resurrection path
+        // (`checkResurrections`), which carries the bounded-chain +
+        // `onResurrect`/`onWorkerLost` semantics and re-reads from cursor 0 to
+        // rebuild the still-in-progress turn. Skipping it here avoids
+        // double-handling the same growth in one poll; this branch's concern is
+        // GENUINE terminal completions (real `turn_end`, no false-finish record)
+        // that were resumed via SendMessage (issue #3315). A false finish that
+        // has since been evicted from `falseFinishTracker` (512-cap) is no
+        // longer double-handled, so falling through to re-register it live here
+        // is correct.
+        if (falseFinishTracker.has(agentId)) continue
+        let currentSize: number
+        try {
+          currentSize = fs.statSync(filePath).size
+        } catch {
+          continue // unreadable — nothing to resume; keep suppressing
+        }
+        // At/below the terminal snapshot ⇒ static leftover file (#1116 Bug B):
+        // stay suppressed, do NOT re-register.
+        if (currentSize <= terminalSize) continue
+        // Grew past it ⇒ the worker resumed (#3315). Re-register as a fresh
+        // LIVE worker, reading only from the terminal boundary so the
+        // already-completed turn is not replayed. At-most-once per resume:
+        // dropping the id from terminatedAgentIds means the next completion
+        // re-adds it with the new (larger) terminal size, so one resume yields
+        // exactly one re-registration.
+        log?.(`subagent-watcher: agent ${agentId} resumed after terminal cleanup — JSONL grew ${terminalSize} → ${currentSize} bytes (SendMessage resume); re-registering as live so its progress card resumes (issue #3315)`)
+        terminatedAgentIds.delete(agentId)
+        historicalFiles.delete(filePath)
+        knownFiles.add(filePath)
+        registerAgent(filePath, agentId, terminalSize)
+        continue
+      }
       knownFiles.add(filePath)
       // During the initial boot scan, mark every discovered file as
       // historical so stall-detection and completion notifications are

package/telegram-plugin/tests/backstop-delivery.test.ts

@@ -5,6 +5,8 @@ import {
   backstopReceiptIds,
   backstopDelivered,
   runBackstopDelivery,
+  combineReadBackResults,
+  type ReadBackResult,
 } from '../gateway/backstop-delivery.js'
 import {
   backstopSendOutcomeGated,
@@ -248,3 +250,168 @@ describe('runBackstopDelivery — integration oracle over the delivery wiring',
     expect(recorded[0].ids).toHaveLength(recorded[0].texts.length)
   })
 })
+
+/**
+ * #3278 — read-back confirmation of an accepted-but-dropped send.
+ *
+ * A returned message_id proves Telegram ACCEPTED the send, not that the message
+ * is VISIBLE (a flood/anti-spam silent discard returns a fresh id yet the user
+ * sees nothing). These assert the deterministic OUTCOMES of the per-chunk state
+ * machine `unsent → pending → landed-unconfirmed → {landed-confirmed | unsent}`
+ * driven by a no-op editMessageText read-back — NOT code-path execution.
+ */
+describe('#3278 read-back — the ledger confirmation state machine', () => {
+  it('confirmChunk transitions landed-unconfirmed → landed-confirmed', () => {
+    const l = new BackstopDeliveryLedger()
+    l.recordChunk('#t', 0, [900]) // landed-unconfirmed
+    expect(l.hasChunk('#t', 0)).toBe(true)
+    expect(l.hasConfirmedChunk('#t', 0)).toBe(false)
+    expect(l.landedUnconfirmedIndices('#t', 1)).toEqual([0])
+    l.confirmChunk('#t', 0)
+    expect(l.hasConfirmedChunk('#t', 0)).toBe(true)
+    expect(l.landedUnconfirmedIndices('#t', 1)).toEqual([])
+    expect(l.allConfirmed('#t', 1)).toBe(true)
+    expect(l.confirmedIds('#t')).toEqual([900])
+  })
+
+  it('demoteChunk resets a landed(-unconfirmed) chunk back to unsent (safe re-send)', () => {
+    const l = new BackstopDeliveryLedger()
+    l.recordChunk('#t', 0, [901])
+    l.confirmChunk('#t', 0)
+    l.demoteChunk('#t', 0) // positive-absence read-back
+    expect(l.hasChunk('#t', 0)).toBe(false)
+    expect(l.hasConfirmedChunk('#t', 0)).toBe(false)
+    expect(l.unsentIndices('#t', 1)).toEqual([0]) // resume set includes it again
+    expect(l.confirmedIds('#t')).toEqual([])
+  })
+
+  it('allConfirmed is false while any chunk is only landed-unconfirmed', () => {
+    const l = new BackstopDeliveryLedger()
+    l.recordChunk('#t', 0, [1]); l.confirmChunk('#t', 0)
+    l.recordChunk('#t', 1, [2]) // landed-unconfirmed
+    expect(l.allConfirmed('#t', 2)).toBe(false)
+    expect(l.landedUnconfirmedIndices('#t', 2)).toEqual([1])
+  })
+
+  it('confirmedIds returns ONLY confirmed chunk ids, in index order', () => {
+    const l = new BackstopDeliveryLedger()
+    l.recordChunk('#t', 0, [10]); l.confirmChunk('#t', 0)
+    l.recordChunk('#t', 1, [11]) // unconfirmed
+    l.recordChunk('#t', 2, [12, 13]); l.confirmChunk('#t', 2)
+    expect(l.confirmedIds('#t')).toEqual([10, 12, 13])
+  })
+})
+
+describe('#3278 combineReadBackResults — per-chunk id combine (guard A7)', () => {
+  it('ANY absent id ⇒ absent (re-send the whole chunk)', () => {
+    expect(combineReadBackResults(['exists', 'absent'])).toBe('absent')
+    expect(combineReadBackResults(['absent', 'ambiguous'])).toBe('absent')
+  })
+  it('ALL exist ⇒ exists', () => {
+    expect(combineReadBackResults(['exists', 'exists'])).toBe('exists')
+  })
+  it('some ambiguous, none absent ⇒ ambiguous (never re-send)', () => {
+    expect(combineReadBackResults(['exists', 'ambiguous'])).toBe('ambiguous')
+  })
+  it('empty id set ⇒ ambiguous (fabricate neither confirm nor demote)', () => {
+    expect(combineReadBackResults([])).toBe('ambiguous')
+  })
+})
+
+describe('#3278 runBackstopDelivery — read-back drives the delivery outcome', () => {
+  it('exists probe ⇒ landed-confirmed, delivered=true, ONE probe, no re-send', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const sendChunk = vi.fn(async () => [960])
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => 'exists')
+    const res = await runBackstopDelivery(ledger, '#ok', ['the answer'], null, { sendChunk, readBack }, 3)
+    expect(res.delivered).toBe(true)
+    expect(res.exhausted).toBe(false)
+    expect(sendChunk).toHaveBeenCalledTimes(1) // never re-sent
+    expect(readBack).toHaveBeenCalledTimes(1) // exactly one probe per chunk
+    expect(ledger.hasConfirmedChunk('#ok', 0)).toBe(true)
+  })
+
+  it('400/absent probe ⇒ demote → RE-SENT EXACTLY ONCE, then confirmed', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    let sends = 0
+    const sendChunk = vi.fn(async () => { sends++; return [900 + sends] })
+    let probes = 0
+    // First probe: the send was silently dropped (absent). After the re-send the
+    // message is present (exists).
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => {
+      probes++
+      return probes === 1 ? 'absent' : 'exists'
+    })
+    const res = await runBackstopDelivery(ledger, '#drop', ['answer'], null, { sendChunk, readBack }, 3)
+    expect(sendChunk).toHaveBeenCalledTimes(2) // initial + exactly one re-send
+    expect(res.delivered).toBe(true)
+    expect(ledger.hasConfirmedChunk('#drop', 0)).toBe(true)
+  })
+
+  it('429/ambiguous probe ⇒ NOT re-sent, stays landed-unconfirmed, delivered=false', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const sendChunk = vi.fn(async () => [950])
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => 'ambiguous')
+    const res = await runBackstopDelivery(ledger, '#amb', ['answer'], null, { sendChunk, readBack }, 3)
+    expect(sendChunk).toHaveBeenCalledTimes(1) // never re-sent on ambiguous
+    expect(res.delivered).toBe(false)
+    expect(res.exhausted).toBe(true)
+    expect(ledger.hasConfirmedChunk('#amb', 0)).toBe(false)
+    expect(ledger.landedUnconfirmedIndices('#amb', 1)).toEqual([0]) // still landed-unconfirmed
+  })
+
+  it('a read-back adapter THAT THROWS is treated as ambiguous — never re-sent', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const sendChunk = vi.fn(async () => [951])
+    const readBack = vi.fn(async () => { throw new Error('boom') })
+    const res = await runBackstopDelivery(ledger, '#throw', ['answer'], null, { sendChunk, readBack }, 3)
+    expect(sendChunk).toHaveBeenCalledTimes(1)
+    expect(res.delivered).toBe(false)
+  })
+
+  it('#3278 CORE: API-ack fresh id but read-back ABSENT ⇒ send_failed, NOT complete', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const cardId = 500
+    // The Bot API returns a fresh non-card id (an accept) every time...
+    const sendChunk = vi.fn(async () => [970])
+    // ...but the read-back proves the message is not actually in the chat
+    // (flood/anti-spam silent discard). It never confirms.
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => 'absent')
+    const res = await runBackstopDelivery(ledger, '#ghost', ['answer'], cardId, { sendChunk, readBack }, 3)
+    expect(res.delivered).toBe(false) // pre-#3278 this was true → false `complete`
+    expect(res.exhausted).toBe(true)
+    // The exact input the gateway feeds the turn record: delivered=false ⇒ the
+    // status is send_failed and the obligation is left OPEN — the answer is NOT
+    // silently marked complete.
+    const turn: { finalAnswerDelivered: boolean; deliveryOutcome?: 'delivered' | 'failed' | 'suppressed' } = {
+      finalAnswerDelivered: true,
+    }
+    finalizeBackstopSendGated(turn, {
+      threw: !res.delivered, sentIds: res.sentIds, chunkCount: res.chunkCount, cardMessageId: cardId,
+    })
+    expect(computeTurnStatus(turn)).toBe('send_failed')
+  })
+
+  it('scope guard: NO readBack dep ⇒ ZERO probes, legacy confirm-on-landing preserved', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const readBack = vi.fn()
+    const sendChunk = vi.fn(async () => [980])
+    // deliberately omit `readBack` — the hot path / opt-out shape.
+    const res = await runBackstopDelivery(ledger, '#noprobe', ['answer'], null, { sendChunk })
+    expect(readBack).not.toHaveBeenCalled()
+    expect(res.delivered).toBe(true) // confirmed on landing (receipt-gated)
+    expect(ledger.hasConfirmedChunk('#noprobe', 0)).toBe(true)
+  })
+
+  it('partial: chunk 0 confirmed, chunk 1 ambiguous ⇒ delivered=false, chunk 0 not re-sent', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const calls: number[] = []
+    const sendChunk = vi.fn(async (i: number) => { calls.push(i); return [700 + i] })
+    const readBack = vi.fn(async (i: number): Promise<ReadBackResult> => (i === 0 ? 'exists' : 'ambiguous'))
+    const res = await runBackstopDelivery(ledger, '#part', ['c0', 'c1'], null, { sendChunk, readBack }, 3)
+    expect(res.delivered).toBe(false)
+    expect(calls.filter(i => i === 0)).toHaveLength(1) // confirmed chunk never re-sent
+    expect(ledger.hasConfirmedChunk('#part', 0)).toBe(true)
+    expect(ledger.hasConfirmedChunk('#part', 1)).toBe(false)
+  })
+})