switchroom 0.19.22 → 0.19.24

package/telegram-plugin/send-gate.ts

@@ -478,6 +478,16 @@ interface MessageEditState {
    * edit budget. Bounded by the budget cap; empty when the backstop is disabled.
    */
   editWindowTs: number[]
+  /**
+   * Set by the driver while it waits out a NON-critical admission, and fired by
+   * `handleEdit` when a `critical` edit is queued for this message meanwhile
+   * (#3716). Since cosmetic edits stopped shedding they now occupy the driver,
+   * so without this a critical edit arriving one tick after the driver dequeued
+   * a cosmetic one would inherit its unbounded wait — re-introducing the
+   * multi-hour reply wedge the critical fail-fast path exists to prevent.
+   * Null whenever no interruptible wait is in flight.
+   */
+  criticalWake: (() => void) | null
 }
 
 function hashPayload(payload: unknown): string {
@@ -669,6 +679,7 @@ export function createSendGate(config: SendGateConfig): SendGate {
         running: false,
         suppressedUntilMs: 0,
         editWindowTs: [],
+        criticalWake: null,
       }
       perMessage.set(key, state)
     }
@@ -826,9 +837,17 @@ export function createSendGate(config: SendGateConfig): SendGate {
    * without consuming if admission cannot happen before it — the caller drops
    * the call as stale (part3-design §2).
    */
-  async function admitLoop(buckets: TokenBucket[], deadline?: number): Promise<boolean> {
+  async function admitLoop(
+    buckets: TokenBucket[],
+    deadline?: number,
+    interrupt?: Interrupt,
+  ): Promise<boolean> {
     let counted = false
     for (;;) {
+      // Checked BEFORE the consume below so an interrupted admission never
+      // spends a token nobody uses (a leaked token would permanently shrink the
+      // bucket's effective rate).
+      if (interrupt?.fired) return false
       const now = clock.now()
       let wait = 0
       for (const b of buckets) wait = Math.max(wait, b.msUntilAvailable(now))
@@ -841,13 +860,17 @@ export function createSendGate(config: SendGateConfig): SendGate {
         counters.queued++
         counted = true
       }
-      await clock.sleep(deadline !== undefined ? Math.min(wait, deadline - now) : wait)
+      const nap = clock.sleep(deadline !== undefined ? Math.min(wait, deadline - now) : wait)
+      // An open flood window makes `wait` as long as the whole ban, so the nap
+      // must be raced rather than awaited outright — otherwise the interrupt is
+      // not observed until the ban has already elapsed.
+      await (interrupt ? Promise.race([nap, interrupt.promise]) : nap)
     }
   }
 
   /** Back-compat unbounded admission (used by the per-message edit driver). */
-  function admit(buckets: TokenBucket[]): Promise<boolean> {
-    return admitLoop(buckets)
+  function admit(buckets: TokenBucket[], interrupt?: Interrupt): Promise<boolean> {
+    return admitLoop(buckets, undefined, interrupt)
   }
 
   // Serializes `critical` sends that must probe the API during an open (short)
@@ -870,6 +893,36 @@ export function createSendGate(config: SendGateConfig): SendGate {
     })()
   }
 
+  /**
+   * One-shot abort handle for an in-flight admission wait (#3716). `fired` is
+   * the synchronous check (so the loop can bail before consuming a token) and
+   * `promise` is the async wake (so a nap covering a whole flood ban is cut
+   * short rather than run to completion).
+   */
+  interface Interrupt {
+    fired: boolean
+    promise: Promise<void>
+  }
+
+  /** Create an `Interrupt` plus the trigger that fires it exactly once. */
+  function makeInterrupt(): { interrupt: Interrupt; fire: () => void } {
+    let resolve!: () => void
+    const interrupt: Interrupt = {
+      fired: false,
+      promise: new Promise<void>((r) => {
+        resolve = r
+      }),
+    }
+    return {
+      interrupt,
+      fire: () => {
+        if (interrupt.fired) return
+        interrupt.fired = true
+        resolve()
+      },
+    }
+  }
+
   type AdmitOutcome =
     | { result: 'ok' }
     | { result: 'shed' }
@@ -1038,7 +1091,24 @@ export function createSendGate(config: SendGateConfig): SendGate {
           }
           // outcome.result === 'ok' → admitPriority already consumed the buckets.
         } else {
-          await admit(bucketsFor(opts))
+          // #3716: this wait is UNBOUNDED, and since cosmetic edits stopped
+          // shedding it is now reachable for them too — so a `critical` edit
+          // arriving while we sit here must be able to jump the queue instead
+          // of inheriting a whole flood ban's worth of waiting. Yield to it and
+          // re-loop; `p` is superseded rather than dropped, so no state is lost
+          // and its callers ride the send that actually goes out.
+          const { interrupt, fire } = makeInterrupt()
+          state.criticalWake = fire
+          let admitted: boolean
+          try {
+            admitted = await admit(bucketsFor(opts), interrupt)
+          } finally {
+            state.criticalWake = null
+          }
+          if (!admitted) {
+            supersede(state, p)
+            continue
+          }
         }
         // Reserve the send-start time BEFORE awaiting the network so the floor
         // is measured from send start (matches the per-message serialization).
@@ -1084,6 +1154,70 @@ export function createSendGate(config: SendGateConfig): SendGate {
     }
   }
 
+  /**
+   * Hand a dequeued-but-unsent edit back to the queue after the driver yielded
+   * to a higher-priority one (#3716). `p` is by definition OLDER than whatever
+   * is queued now, so last-write-wins says its payload loses — but its callers
+   * must still settle, so they ride the newer edit's result exactly as if they
+   * had coalesced onto it in the first place. With nothing queued (the wake
+   * raced an empty slot) `p` simply goes back.
+   */
+  function supersede(state: MessageEditState, p: PendingEdit): void {
+    const next = state.pending
+    if (!next) {
+      state.pending = p
+      return
+    }
+    next.priorityClass = maxPriority(next.priorityClass, p.priorityClass)
+    next.promise.then(p.resolve, p.reject)
+  }
+
+  /**
+   * The condition that used to trigger the cosmetic-edit shed: no token in some
+   * bucket, or a window covering this message. Kept as the trigger — what
+   * changed in #3716 is the CONSEQUENCE (see `settleForCaller`).
+   */
+  function editUnderPressure(state: MessageEditState, opts: SendGateOpts, now: number): boolean {
+    if (state.suppressedUntilMs > now) return true
+    for (const b of bucketsFor(opts)) {
+      if (b.msUntilAvailable(now) > 0) return true
+    }
+    return false
+  }
+
+  /**
+   * What a queued edit returns to the caller that submitted it (#3716).
+   *
+   * Normally: the shared pending promise, settling with the coalesced send's
+   * outcome. Callers rely on that to pace their own painting, so this is the
+   * path whenever the gate is keeping up.
+   *
+   * Under pressure, a `cosmetic` edit instead settles its caller as soon as it
+   * is QUEUED. Callers serialize their own flushes, so a best-effort paint
+   * parked behind a flood ban would hold a subsequent critical edit hostage
+   * UPSTREAM of the gate — where the fail-fast path can never see it — wedging
+   * the reply path for the length of the ban. Releasing the caller keeps that
+   * path free while the edit itself stays queued and still lands carrying the
+   * newest payload. This is the same trigger the old shed used; the difference
+   * is that the state survives instead of being discarded.
+   */
+  function settleForCaller<T>(
+    state: MessageEditState,
+    pending: PendingEdit,
+    opts: SendGateOpts,
+    priority: PriorityClass,
+    now: number,
+  ): Promise<T> {
+    if (priority !== 'cosmetic' || !editUnderPressure(state, opts, now)) {
+      return pending.promise as Promise<T>
+    }
+    // Nobody may be left awaiting the shared promise, so absorb a rejection here
+    // to keep a failed background paint from surfacing as an unhandled rejection.
+    // (A later `critical`/`useful` coalesce still attaches its own handlers.)
+    void pending.promise.catch(() => {})
+    return Promise.resolve(undefined as unknown as T)
+  }
+
   function handleEdit<T>(fn: () => Promise<T>, opts: SendGateOpts): Promise<T> {
     const messageId = opts.messageId as number
     const key = messageKey(opts.chat_id, messageId)
@@ -1093,22 +1227,39 @@ export function createSendGate(config: SendGateConfig): SendGate {
     maybeEvict(now, existing === undefined)
     const state = existing ?? messageState(key)
 
-    // Cosmetic edits (part3-design §2) shed under pressure — a flood window
-    // covering the scope is open, or a bucket has no token free right now. A
-    // dropped edit costs nothing: the next edit carries the full state. Only an
-    // EXPLICITLY-cosmetic edit sheds; untagged edits keep PR 1's coalescing
-    // behaviour (default = useful), so this never changes an untagged caller.
-    if ((opts.priorityClass ?? 'useful') === 'cosmetic') {
-      let wait = 0
-      for (const b of bucketsFor(opts)) wait = Math.max(wait, b.msUntilAvailable(now))
-      const msgWait = state.suppressedUntilMs > now ? state.suppressedUntilMs - now : 0
-      if (wait > 0 || msgWait > 0) {
-        counters.shed++
-        // Distinguishable from the no-op drop below (undefined): a shed did
-        // NOT land, and edit-driving callers must be able to tell (F1).
-        return Promise.resolve(SEND_GATE_SHED as unknown as T)
-      }
-    }
+    // Cosmetic edits COALESCE under pressure; they are never shed (#3716).
+    //
+    // This previously dropped a cosmetic edit outright whenever a bucket had no
+    // free token or a flood window covered the scope, on the reasoning that "a
+    // dropped edit costs nothing: the next edit carries the full state". That
+    // holds for every edit in a burst EXCEPT the last one — and the last one is
+    // the only edit whose state is still on screen when the burst ends. Dropping
+    // it strands the card on a stale body indefinitely (a progress card frozen
+    // mid-run, a finished task still rendered as running). Pressure is exactly
+    // when bursts end, so the drop was biased toward stranding precisely the
+    // edits that mattered.
+    //
+    // Falling through to the last-write-wins coalescing below loses nothing and
+    // costs no extra flood budget: N queued edits collapse into ONE send that
+    // carries the newest payload, and the driver already paces that send against
+    // the token buckets, the per-message edit floor, and the rolling per-window
+    // cosmetic budget — which DEFERS an over-budget edit rather than dropping it.
+    // Flood safety comes from that pacing, never from discarding state.
+    //
+    // Cost of the change: under a long flood window a cosmetic edit now waits in
+    // the driver instead of resolving immediately as SEND_GATE_SHED. The pending
+    // slot is one-per-message and LRU-bounded by `maxMessageStates`, and the edit
+    // that eventually lands carries the newest state rather than a stale one.
+    // `SEND_GATE_SHED` remains the contract for NON-edit cosmetic sends (typing,
+    // reactions), which carry no state worth preserving.
+    //
+    // What that cost must NOT become is a wait the CALLER inherits. Callers
+    // serialize their own flushes (draft-stream awaits the in-flight paint before
+    // starting the next), so a cosmetic edit that blocked its caller for a whole
+    // flood ban would hold the critical finalize behind it — and the finalize
+    // would never reach the gate to fail fast, wedging the reply path for hours.
+    // That is precisely the failure the gate exists to prevent, so a cosmetic
+    // edit settles its caller as soon as it is QUEUED (see `settleForCaller`).
 
     // N1: the coalesce (last-write-wins) check runs BEFORE the no-op skip. When
     // a distinct edit is already queued, the newest payload always replaces it —
@@ -1135,7 +1286,10 @@ export function createSendGate(config: SendGateConfig): SendGate {
         state.pending.hash = hash
         state.pending.fn = fn as () => Promise<unknown>
       }
-      return state.pending.promise as Promise<T>
+      // The queued edit is critical now — cut short any non-critical admission
+      // the driver is waiting out for this message (#3716).
+      if (state.pending.priorityClass === 'critical') state.criticalWake?.()
+      return settleForCaller<T>(state, state.pending, opts, opts.priorityClass ?? 'useful', now)
     }
 
     // No edit queued → a repeat of the last payload we actually sent is a plain
@@ -1164,8 +1318,15 @@ export function createSendGate(config: SendGateConfig): SendGate {
       priorityClass: opts.priorityClass ?? 'useful',
     }
     state.pending = pending
-    if (!state.running) void drive(state, opts)
-    return promise as Promise<T>
+    if (state.running) {
+      // A driver is mid-flight. If it is waiting out a non-critical admission
+      // and THIS edit is critical, wake it so the critical work does not queue
+      // behind a cosmetic edit's unbounded wait (#3716).
+      if (pending.priorityClass === 'critical') state.criticalWake?.()
+    } else {
+      void drive(state, opts)
+    }
+    return settleForCaller<T>(state, pending, opts, pending.priorityClass, now)
   }
 
   async function gate<T>(fn: () => Promise<T>, opts?: SendGateOpts): Promise<T> {

package/telegram-plugin/tests/activity-card-send-gate.test.ts

@@ -239,10 +239,10 @@ describe('activity card ↔ send gate (#3620)', () => {
     }
   })
 
-  it('a shed card edit is not treated as painted — the newest render survives for the next drain', async () => {
+  it('a card edit starved of tokens is HELD, not shed — the newest render still lands (#3716)', async () => {
     // A one-token-per-minute chat bucket: the card open consumes it, so the
-    // next COSMETIC card edit sheds.
-    const { lane, calls, clock } = makeGatedLane({ perChatPerSec: 1 / 60, perChatBurst: 1 })
+    // next COSMETIC card edit cannot be admitted.
+    const { lane, calls, clock, gate } = makeGatedLane({ perChatPerSec: 1 / 60, perChatBurst: 1 })
     const turn = makeLaneTurn(lane)
 
     lane.showNarrativeStep(turn, 'Opening the card')
@@ -250,17 +250,17 @@ describe('activity card ↔ send gate (#3620)', () => {
     await turn.activityInFlight
     expect(calls.filter((c) => c.method === 'sendRichMessage')).toHaveLength(1)
 
-    lane.showNarrativeStep(turn, 'A shed update')
+    lane.showNarrativeStep(turn, 'An update with no token available')
     await clock.advance(10)
     await turn.activityInFlight
-    // Shed → nothing hit the API, and the render is still PENDING (not
-    // mis-recorded as sent), so it is not silently lost.
+    // Nothing hits the API while the bucket is empty — unchanged. What changed
+    // is that the edit is now QUEUED rather than discarded, so the card can no
+    // longer be stranded on a stale body by a burst that ends under pressure.
     expect(calls.filter((c) => c.method === 'editMessageText')).toHaveLength(0)
-    expect(turn.activityPendingRender).not.toBeNull()
-    expect(turn.activityPendingRender).not.toBe(turn.activityLastSentRender)
+    expect(gate.stats().global.shed).toBe(0)
 
     // Once the bucket refills, the next drain paints the NEWEST body — not the
-    // shed intermediate one.
+    // superseded intermediate one.
     lane.showNarrativeStep(turn, 'The newest update')
     await clock.advance(120_000)
     await turn.activityInFlight

package/telegram-plugin/tests/agent-state-dir-preload.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+
+/**
+ * Runtime alarm for the BUN half of the state-dir hermeticity guard.
+ *
+ * vitest loads `tests/vitest-setup/agent-state-dir-guard.mjs` via
+ * `test.setupFiles`; `bun test` loads the same file via `[test] preload` in
+ * bunfig.toml (repo root) and telegram-plugin/bunfig.toml (CI's bun-test-run
+ * has `working-directory: telegram-plugin`, and bun reads the bunfig in its CWD
+ * only). Without the bun half, ~75 bun-run test files still default every agent
+ * state writer to `/state/agent` — inside an agent container that is a LIVE
+ * agent's bind-mounted state dir, which is exactly how 356 synthetic turn rows
+ * ended up in production `turns.jsonl` files and were scored as real drift by
+ * the fleet-health sensor.
+ *
+ * `npm run lint:agent-state-dir-hermeticity` pins the WIRING statically; this
+ * pins the EFFECT, so a bunfig that is present but no longer loading the guard
+ * (wrong relative path, bun config-discovery change) fails a test rather than
+ * silently un-protecting the runner.
+ */
+describe('bun test runs with the agent state dir redirected', () => {
+  for (const k of ['SWITCHROOM_AGENT_STATE_DIR', 'SWITCHROOM_RUNTIME_STATE_DIR']) {
+    it(`${k} points at a tmp dir, not a live agent state dir`, () => {
+      const v = process.env[k]
+      expect(v, `${k} unset — bunfig.toml \`[test] preload\` did not run`).toBeTruthy()
+      expect(v).not.toBe('/state/agent')
+      expect(v!.startsWith(tmpdir())).toBe(true)
+      expect(existsSync(v!)).toBe(true)
+    })
+  }
+})

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

@@ -10,6 +10,7 @@ import {
 } from '../gateway/backstop-delivery.js'
 import {
   backstopSendOutcomeGated,
+  buildTurnRecord,
   finalizeBackstopSendGated,
   computeTurnStatus,
 } from '../gateway/turn-record-status.js'
@@ -348,25 +349,29 @@ describe('#3278 runBackstopDelivery — read-back drives the delivery outcome',
     expect(ledger.hasConfirmedChunk('#drop', 0)).toBe(true)
   })
 
-  it('429/ambiguous probe ⇒ NOT re-sent, stays landed-unconfirmed, delivered=false', async () => {
+  it('429/ambiguous probe ⇒ NOT re-sent, stays landed-unconfirmed, still DELIVERED', 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)
+    // An inconclusive probe establishes nothing, so the landed-id evidence
+    // stands: the answer IS in the chat and the turn is not a failure.
+    expect(res.delivered).toBe(true)
+    expect(res.confirmed).toBe(false) // landed-unconfirmed, honestly reported
+    expect(res.exhausted).toBe(false)
     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 () => {
+  it('a read-back adapter THAT THROWS is ambiguous — never re-sent, never a failure', 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)
+    expect(res.delivered).toBe(true)
+    expect(res.confirmed).toBe(false)
   })
 
   it('#3278 CORE: API-ack fresh id but read-back ABSENT ⇒ send_failed, NOT complete', async () => {
@@ -403,15 +408,207 @@ describe('#3278 runBackstopDelivery — read-back drives the delivery outcome',
     expect(ledger.hasConfirmedChunk('#noprobe', 0)).toBe(true)
   })
 
-  it('partial: chunk 0 confirmed, chunk 1 ambiguous ⇒ delivered=false, chunk 0 not re-sent', async () => {
+  it('partial: chunk 0 confirmed, chunk 1 ambiguous ⇒ both landed ⇒ delivered, 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(res.delivered).toBe(true) // every chunk landed a fresh id
+    expect(res.confirmed).toBe(false) // ...but chunk 1 was never corroborated
     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)
   })
+
+  // ── The measurement bug this PR fixes ────────────────────────────────────
+  //
+  // The probe is issued at cosmetic priority in the same millisecond as the
+  // send it probes, so the per-chat token bucket (1/sec, just consumed by that
+  // very send) sheds it: in production it resolved `ambiguous` 146 times in two
+  // weeks and `absent` ZERO times. Under the old confirmation-gated verdict each
+  // of those became `delivered:false` → `send_failed` on a turn whose answer the
+  // user had received, plus an error reaction and a still-OPEN obligation.
+  it('AMBIGUOUS probe ⇒ turn record `complete`, NOT send_failed (the fixed bug)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const cardId = 500
+    const sendChunk = vi.fn(async () => [971]) // a fresh, non-card chat id
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => 'ambiguous')
+    const res = await runBackstopDelivery(ledger, '#shed', ['answer'], cardId, { sendChunk, readBack }, 3)
+    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('complete')
+  })
+
+  it('an ambiguous probe on a CARD-ONLY delivery is still send_failed (guard 7 holds)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const cardId = 501
+    // The only id that landed IS the progress card — swept ~60-90s later, so
+    // the user receives nothing. Ambiguity must not rescue this.
+    const sendChunk = vi.fn(async () => [cardId])
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => 'ambiguous')
+    const res = await runBackstopDelivery(ledger, '#cardonly', ['answer'], cardId, { sendChunk, readBack }, 3)
+    expect(res.delivered).toBe(false)
+    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('an ambiguous probe on a chunk that never landed is still NOT delivered', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    // chunk 0 lands; chunk 1 throws on every attempt → never landed.
+    const sendChunk = vi.fn(async (i: number) => {
+      if (i === 1) throw new Error('flood')
+      return [800 + i]
+    })
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => 'ambiguous')
+    const res = await runBackstopDelivery(ledger, '#gap', ['c0', 'c1'], null, { sendChunk, readBack }, 2)
+    expect(res.delivered).toBe(false)
+    expect(res.exhausted).toBe(true)
+  })
+
+  // Mixed sequence: the two probe states that MOVE the verdict, composed in one
+  // run. Chunk 0's first send is silently discarded (`absent` ⇒ demote ⇒
+  // re-send) and the probe on the RE-SEND is shed (`ambiguous`). Under the old
+  // confirmation-gated verdict the re-sent chunk was never `landed-confirmed`,
+  // so the whole turn came out `delivered:false` — a `send_failed` for an answer
+  // that had just been successfully re-sent. Demote-and-re-send and
+  // ambiguity-is-not-failure must compose.
+  it('absent ⇒ demote ⇒ re-send, then AMBIGUOUS on the re-send ⇒ delivered, sent exactly twice', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    let sends = 0
+    const sendChunk = vi.fn(async () => { sends++; return [990 + sends] })
+    let probes = 0
+    const readBack = vi.fn(async (): Promise<ReadBackResult> => {
+      probes++
+      return probes === 1 ? 'absent' : 'ambiguous'
+    })
+    const res = await runBackstopDelivery(ledger, '#mixed', ['answer'], null, { sendChunk, readBack }, 3)
+    expect(sendChunk).toHaveBeenCalledTimes(2) // initial + exactly one re-send
+    expect(readBack).toHaveBeenCalledTimes(2) // probed once per landing
+    expect(res.delivered).toBe(true) // the re-send landed a fresh id; ambiguity proves nothing
+    expect(res.confirmed).toBe(false) // ...and is honestly reported as uncorroborated
+    expect(res.sentIds).toEqual([992]) // the demoted first id is gone; the re-send's id stands
+    expect(res.landedUnconfirmedIds).toEqual([992])
+    // The outcome the user actually experiences: a `complete` turn record.
+    const turn: { finalAnswerDelivered: boolean; deliveryOutcome?: 'delivered' | 'failed' | 'suppressed' } = {
+      finalAnswerDelivered: true,
+    }
+    finalizeBackstopSendGated(turn, {
+      threw: !res.delivered, sentIds: res.sentIds, chunkCount: res.chunkCount, cardMessageId: null,
+    })
+    expect(computeTurnStatus(turn)).toBe('complete')
+  })
+})
+
+// ── The observability of the new optimism (#3702 L2/L5/L6a) ─────────────────
+//
+// Counting an inconclusive probe as delivered is a BET. These pin the two
+// artifacts that let the fleet find out if it is ever wrong: the per-delivery
+// stderr line, and the `landed_unconfirmed` field on the turns.jsonl row.
+describe('#3702 landed-unconfirmed is MEASURED, not silently assumed', () => {
+  it('a delivered-but-unconfirmed turn writes the diagnostic stderr line', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const lines: string[] = []
+    const res = await runBackstopDelivery(
+      ledger, '#obs', ['answer'], null,
+      {
+        sendChunk: async () => [1001],
+        readBack: async (): Promise<ReadBackResult> => 'ambiguous',
+        stderr: (s) => lines.push(s),
+      },
+      3,
+    )
+    expect(res.delivered).toBe(true)
+    expect(res.confirmed).toBe(false)
+    const diag = lines.filter(l => l.includes('backstop delivery landed-unconfirmed'))
+    expect(diag).toHaveLength(1)
+    expect(diag[0]).toContain('#obs')
+    expect(diag[0]).toContain('1 of 1 landed id(s)') // the measured quantity, not just a warning
+  })
+
+  it('a fully CONFIRMED delivery writes NO landed-unconfirmed line (no false alarm)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const lines: string[] = []
+    const res = await runBackstopDelivery(
+      ledger, '#conf', ['answer'], null,
+      {
+        sendChunk: async () => [1002],
+        readBack: async (): Promise<ReadBackResult> => 'exists',
+        stderr: (s) => lines.push(s),
+      },
+      3,
+    )
+    expect(res.confirmed).toBe(true)
+    expect(res.landedUnconfirmedIds).toEqual([])
+    expect(lines.filter(l => l.includes('backstop delivery landed-unconfirmed'))).toHaveLength(0)
+  })
+
+  it('landedUnconfirmedIds is exactly the uncorroborated subset of sentIds', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    // chunk 0 confirmed, chunk 1 landed-unconfirmed (shed probe).
+    const res = await runBackstopDelivery(
+      ledger, '#subset', ['c0', 'c1'], null,
+      {
+        sendChunk: async (i: number) => [1100 + i],
+        readBack: async (i: number): Promise<ReadBackResult> => (i === 0 ? 'exists' : 'ambiguous'),
+      },
+      3,
+    )
+    expect(res.sentIds).toEqual([1100, 1101])
+    expect(res.landedUnconfirmedIds).toEqual([1101]) // c0 is corroborated; c1 is the bet
+    expect(res.delivered).toBe(true)
+    expect(res.confirmed).toBe(false)
+  })
+
+  it('the count reaches turns.jsonl: a complete turn carries `landed_unconfirmed`', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const res = await runBackstopDelivery(
+      ledger, '#row', ['c0', 'c1'], null,
+      {
+        sendChunk: async (i: number) => [1200 + i],
+        readBack: async (): Promise<ReadBackResult> => 'ambiguous',
+      },
+      3,
+    )
+    const turn = {
+      agent: 'test-agent',
+      startedAt: 1_000_000,
+      toolCallCount: 0,
+      turnId: '#row',
+      finalAnswerDelivered: true,
+      deliveryOutcome: 'delivered' as const,
+      landedUnconfirmed: res.landedUnconfirmedIds.length,
+    }
+    const row = buildTurnRecord(turn, 1_002_000)
+    // The status is honest AND the bet is visible on the same row — that pairing
+    // is the point: a `complete` we could not corroborate is countable.
+    expect(row.status).toBe('complete')
+    expect(row.landed_unconfirmed).toBe(2)
+  })
+
+  it('an ordinary confirmed turn omits the field entirely (row shape unchanged)', () => {
+    const row = buildTurnRecord(
+      {
+        agent: 'test-agent',
+        startedAt: 1_000_000,
+        toolCallCount: 0,
+        turnId: '#plain',
+        finalAnswerDelivered: true,
+        deliveryOutcome: 'delivered',
+        landedUnconfirmed: 0,
+      },
+      1_002_000,
+    )
+    expect(row.status).toBe('complete')
+    expect('landed_unconfirmed' in row).toBe(false)
+  })
 })

package/telegram-plugin/tests/backstop-readback-probe.test.ts

@@ -141,4 +141,16 @@ describe('#3278 createBackstopReadBack — full gate+edit+classify wiring', () =
     const readBack = createBackstopReadBack(wiring({ gate, editMessageText }))
     expect(await readBack(0, [55], 'answer')).toBe('ambiguous')
   })
+
+  test('gate NO-OP drop (resolves undefined) ⇒ ambiguous, NOT a false exists', async () => {
+    // The gate's edit path drops a repeat of the last payload it actually sent
+    // (`counters.dropped`) and drops an expired queue entry, resolving
+    // `undefined` in both cases. Nothing reached Telegram, so nothing was
+    // proven — classifying it `exists` would fabricate a confirmation from a
+    // call that never happened.
+    const gate = vi.fn(async () => undefined)
+    const editMessageText = vi.fn(async () => true)
+    const readBack = createBackstopReadBack(wiring({ gate, editMessageText }))
+    expect(await readBack(0, [55], 'answer')).toBe('ambiguous')
+  })
 })