switchroom 0.18.31 → 0.18.33

package/telegram-plugin/tests/button-tap-turn-gated.test.ts

@@ -115,9 +115,9 @@ describe("agent button taps use the turn-gate (mid-turn → buffer)", () => {
     });
 
     it("buffers + spools on bridge-offline (existing behaviour intact)", () => {
-      // The idle-branch send missed → the reservation is released in lockstep
-      // and the tap is spooled to the pending-inbound buffer for replay.
-      expect(body).toMatch(/claudeBusyKeys\.delete\(reservedBusyKey\)/);
+      // The idle-branch send missed → the tap is spooled to the
+      // pending-inbound buffer for replay. (#2996 P1: the legacy busy-key
+      // reservation/release pair was deleted with the claudeBusyKeys set.)
       expect(body).toMatch(/return 'buffered-bridge-offline'/);
       // The bridge-offline buffer push is the LAST push (after the send miss),
       // so it always spools before returning the offline outcome.
@@ -129,30 +129,39 @@ describe("agent button taps use the turn-gate (mid-turn → buffer)", () => {
   });
 
   describe("the agent: callback handler routes through the helper", () => {
+    // #2996 P6: the agent-callback family moved to
+    // agent-button-callback-handler.ts (handleAgentButtonCallback); the
+    // structural pins now scrape the extracted module. The injected
+    // deliverButtonTapInbound + restarting-notice bindings stay in gateway.ts.
+    const moduleSrc = readFileSync(
+      resolve(__dirname, "..", "gateway", "agent-button-callback-handler.ts"),
+      "utf8",
+    );
     it("delivers the tap via deliverButtonTapInbound, not a raw sendToAgent", () => {
-      // Locate the agent-callback handler block.
-      const anchor = gatewaySrc.indexOf("const agentCb = parseAgentCallback(data)");
+      const anchor = moduleSrc.indexOf("const agentCb = parseAgentCallback(data)");
       expect(anchor, "agent-callback handler missing").toBeGreaterThan(0);
-      const handler = gatewaySrc.slice(anchor, gatewaySrc.indexOf("// Permission request buttons.", anchor));
+      const handler = moduleSrc.slice(anchor);
       // The tap is routed through the turn-safe helper...
-      expect(handler).toMatch(/await deliverButtonTapInbound\(selfAgentBtn, inboundMsg\)/);
+      expect(handler).toMatch(/await deps\.deliverButtonTapInbound\(selfAgentBtn, inboundMsg\)/);
       // ...and NOT via a raw ungated sendToAgent of the tap inbound (the
       // regressed path that stranded the tap mid-turn).
       expect(handler).not.toMatch(/ipcServer\.sendToAgent\(selfAgentBtn, inboundMsg\)/);
+      // The gateway binding still wires the real helper.
+      expect(gatewaySrc).toMatch(/deliverButtonTapInbound,/);
     });
 
     it("still shows the restart notice only on bridge-offline", () => {
-      const anchor = gatewaySrc.indexOf("const agentCb = parseAgentCallback(data)");
-      const handler = gatewaySrc.slice(anchor, gatewaySrc.indexOf("// Permission request buttons.", anchor));
+      const handler = moduleSrc;
       // The restart notice is gated on the bridge-offline outcome — a mid-turn
       // buffered tap must NOT nag the user (it will be actioned at idle).
       expect(handler).toMatch(/btnOutcome === 'buffered-bridge-offline'/);
-      expect(handler).toMatch(/button-tap-restarting-notice/);
+      // The notice text + verb live in the gateway's injected binding.
+      expect(gatewaySrc).toMatch(/button-tap-restarting-notice/);
     });
 
     it("preserves the ack toast and single-use keyboard strip (UX unchanged)", () => {
-      const anchor = gatewaySrc.indexOf("const agentCb = parseAgentCallback(data)");
-      const handler = gatewaySrc.slice(anchor, gatewaySrc.indexOf("// Permission request buttons.", anchor));
+      const anchor = moduleSrc.indexOf("const agentCb = parseAgentCallback(data)");
+      const handler = moduleSrc.slice(anchor);
       // Ack toast fires FIRST (before delivery) so the tap always registers…
       const ackIdx = handler.indexOf("answerCallbackQuery({ text: ackText })");
       const deliverIdx = handler.indexOf("deliverButtonTapInbound(");

package/telegram-plugin/tests/callback-query-handlers.test.ts

@@ -32,6 +32,8 @@ import {
   type CallbackQueryHandlersDeps,
   type PendingVaultRequestAccess,
   type PendingVaultRequestSave,
+  type PendingSecretRequest,
+  type ArmedSecretCapture,
   type PendingMentalModelPropose,
   type DeferredSecret,
   type PendingVaultOp,
@@ -200,6 +202,12 @@ function makeDeps(overrides: Partial<CallbackQueryHandlersDeps> = {}) {
       expire: () => () => {},
       log: () => () => {},
     }),
+    pendingSecretRequests: createSweepableCardStore<PendingSecretRequest>({
+      isExpired: () => false,
+      expire: () => () => {},
+      log: () => () => {},
+    }),
+    armedSecretCaptures: createSweepableStore<ArmedSecretCapture>(() => false),
     pendingMentalModelProposes: createSweepableCardStore<PendingMentalModelPropose>({
       isExpired: () => false,
       expire: () => () => {},
@@ -455,6 +463,98 @@ describe('handleVaultDeferCallback', () => {
   })
 })
 
+// ── vsp:* — request_secret (agent asks operator to PROVIDE a secret) ─────
+
+function stagedSecretRequest(over: Partial<PendingSecretRequest> = {}): PendingSecretRequest {
+  return {
+    agent: 'worker',
+    chat_id: '111',
+    card_message_id: 42,
+    key: 'openai/api_key',
+    reason: 'need it to call the API',
+    staged_at: Date.now(),
+    ...over,
+  }
+}
+
+describe('handleSecretRequestCallback', () => {
+  it('refuses a sender not on allowFrom (never touches state)', async () => {
+    const { deps } = makeDeps()
+    deps.pendingSecretRequests.set('s1', stagedSecretRequest())
+    const h = createCallbackQueryHandlers(deps)
+    const { ctx, raw } = makeCtx({ senderId: '999' })
+    await h.handleSecretRequestCallback(ctx, 'vsp:provide:s1')
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith({ text: 'Not authorized.' })
+    // Auth gate runs before any capture is armed.
+    expect(deps.armedSecretCaptures.has('111')).toBe(false)
+  })
+
+  // Race pin (#2996 P5 mandate — verdict-during-expiry): a tap that lands after
+  // the card's TTL sweep already dropped the pending request must degrade to
+  // the expired toast, NOT arm a capture or wake the agent.
+  it('a tap on an already-expired/unknown stage toasts "This request expired." and changes nothing', async () => {
+    const { deps, injected } = makeDeps()
+    const h = createCallbackQueryHandlers(deps)
+    const { ctx, raw } = makeCtx()
+    await h.handleSecretRequestCallback(ctx, 'vsp:provide:gone')
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith({ text: 'This request expired.' })
+    expect(deps.armedSecretCaptures.has('111')).toBe(false)
+    expect(injected).toHaveLength(0)
+  })
+
+  it('provide: arms the capture keyed by chat_id and swaps the card to the send-now prompt', async () => {
+    const { deps } = makeDeps()
+    deps.pendingSecretRequests.set('s1', stagedSecretRequest({ threadId: 7 }))
+    const h = createCallbackQueryHandlers(deps)
+    const { ctx, raw } = makeCtx()
+    await h.handleSecretRequestCallback(ctx, 'vsp:provide:s1')
+    const armed = deps.armedSecretCaptures.get('111')
+    expect(armed?.key).toBe('openai/api_key')
+    expect(armed?.stageId).toBe('s1')
+    expect(armed?.threadId).toBe(7)
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith({
+      text: 'Send the value now — it auto-deletes.',
+    })
+    // Card edited to the "send the value" prompt with the keyboard stripped.
+    expect(raw.api.editMessageText).toHaveBeenCalled()
+    // The pending request survives until the value actually arrives.
+    expect(deps.pendingSecretRequests.has('s1')).toBe(true)
+  })
+
+  it('decline: drops the stage, clears any armed capture, edits the card, wakes the agent', async () => {
+    const { deps, injected } = makeDeps()
+    deps.pendingSecretRequests.set('s1', stagedSecretRequest())
+    deps.armedSecretCaptures.set('111', {
+      key: 'openai/api_key',
+      agent: 'worker',
+      stageId: 's1',
+      armed_at: Date.now(),
+    })
+    const h = createCallbackQueryHandlers(deps)
+    const { ctx, raw } = makeCtx()
+    await h.handleSecretRequestCallback(ctx, 'vsp:decline:s1')
+    expect(deps.pendingSecretRequests.has('s1')).toBe(false)
+    expect(deps.pendingCardStore.remove).toHaveBeenCalledWith('s1')
+    expect(deps.armedSecretCaptures.has('111')).toBe(false)
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith({ text: 'Declined.' })
+    expect(raw.api.editMessageText).toHaveBeenCalled()
+    expect(injected).toHaveLength(1)
+    expect(injected[0]!.agent).toBe('worker')
+    expect(injected[0]!.text).toContain('openai/api_key')
+  })
+
+  it('an unknown action just acknowledges without mutating state', async () => {
+    const { deps, injected } = makeDeps()
+    deps.pendingSecretRequests.set('s1', stagedSecretRequest())
+    const h = createCallbackQueryHandlers(deps)
+    const { ctx, raw } = makeCtx()
+    await h.handleSecretRequestCallback(ctx, 'vsp:bogus:s1')
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith()
+    expect(deps.pendingSecretRequests.has('s1')).toBe(true)
+    expect(injected).toHaveLength(0)
+  })
+})
+
 // ── mmp:* — mental-model proposal ───────────────────────────────────────
 
 function stagedPropose(over: Partial<PendingMentalModelPropose> = {}): PendingMentalModelPropose {
@@ -748,6 +848,7 @@ describe('authorization gate parity', () => {
     ['vrd', (h, ctx) => h.handleVaultRecentDenialCallback(ctx, 'vrd:worker:k')],
     ['vra', (h, ctx) => h.handleVaultRequestAccessCallback(ctx, 'vra:approve:s1')],
     ['vrs', (h, ctx) => h.handleVaultRequestSaveCallback(ctx, 'vrs:save:s1')],
+    ['vsp', (h, ctx) => h.handleSecretRequestCallback(ctx, 'vsp:provide:s1')],
     ['vd', (h, ctx) => h.handleVaultDeferCallback(ctx, 'vd:unlock:111:7')],
     ['vg', (h, ctx) => h.handleVaultGrantCallback(ctx, 'vg:cancel')],
     ['mmp', (h, ctx) => h.handleMentalModelProposeCallback(ctx, 'mmp:approve:m1')],

package/telegram-plugin/tests/captured-answer-resume.test.ts

@@ -0,0 +1,358 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+// The dispatcher's resume closure reaches for the durable outbound-text oracle
+// (history.hasOutboundWithText) to reconcile crash-idempotency. Mock it so these
+// stay pure vitest unit tests (no bun:sqlite / real DB) and we can control the
+// "did this chunk's text land durably?" answer per scenario.
+let mockOracle: (chatId: string, text: string, threadId: number | null, since: number) => boolean = () => false
+vi.mock('../history.js', () => ({
+  hasOutboundWithText: (chatId: string, text: string, threadId: number | null, since: number) =>
+    mockOracle(chatId, text, threadId, since),
+}))
+
+import {
+  BackstopDeliveryLedger,
+  runBackstopDelivery,
+  type ReadBackResult,
+} from '../gateway/backstop-delivery.js'
+import { ObligationLedger, type Obligation } from '../gateway/obligation-ledger.js'
+import {
+  buildCapturedDeliverySnapshot,
+  hydrateResumeLedger,
+  createCapturedResumeDispatcher,
+  type CapturedResumeArgs,
+} from '../gateway/captured-answer-resume.js'
+
+/**
+ * #3282 — a partial turn-flush backstop that left an obligation OPEN used to be
+ * re-presented as a FRESH model generation, re-posting chunks that already
+ * landed (the user saw the head of the answer twice). These assert the
+ * deterministic OUTCOME of the fix — the represent is now a byte-identical
+ * captured-answer RESUME of ONLY the non-`landed-confirmed` tail:
+ *   (a) 3-chunk answer, tail fails ⇒ resume sends EXACTLY the unlanded tail,
+ *       chunk 0 is NEVER re-sent, and the chat ends with each chunk once;
+ *   (b) a restart between landing and confirmation does NOT re-send a chunk the
+ *       durable oracle proves landed;
+ *   (c) a fully-landed answer's represent sends NOTHING.
+ * A test that would still pass if the resume re-sent a confirmed chunk is not a
+ * test — every scenario asserts the exact `sendChunk` index set.
+ */
+
+beforeEach(() => {
+  mockOracle = () => false
+})
+
+function obligation(over: Partial<Obligation> = {}): Obligation {
+  return {
+    originTurnId: '#t1',
+    chatId: '900',
+    threadId: undefined,
+    messageId: 42,
+    text: 'the question',
+    openedAt: 1000,
+    representCount: 0,
+    ...over,
+  }
+}
+
+/** Simulate the ORIGINAL partial backstop delivery into `ledger`, then snapshot
+ *  it — the exact input the represent resume consumes. `landPlan(i)` returns the
+ *  per-chunk behavior: 'ok' (lands + confirms), 'throw' (send fails → unsent),
+ *  or 'unconfirmed' (lands but read-back ambiguous → landed-unconfirmed). */
+async function seedPartial(
+  ledger: BackstopDeliveryLedger,
+  turnId: string,
+  chunks: string[],
+  landPlan: (i: number) => 'ok' | 'throw' | 'unconfirmed',
+): Promise<void> {
+  await runBackstopDelivery(
+    ledger,
+    turnId,
+    chunks,
+    null,
+    {
+      sendChunk: async (i: number) => {
+        if (landPlan(i) === 'throw') throw new Error('FLOOD_WAIT_ACTIVE')
+        return [5000 + i]
+      },
+      readBack: async (i: number): Promise<ReadBackResult> =>
+        landPlan(i) === 'unconfirmed' ? 'ambiguous' : 'exists',
+    },
+    1, // a single attempt → a genuine partial (no in-fire retry masking it)
+  )
+}
+
+/** A fake `deliverAnswer` that faithfully replicates the gateway's RESUME path:
+ *  run the injected `hydrate`, then `runBackstopDelivery` over the captured
+ *  chunks with a `sendChunk` that records which indices are (re-)sent. */
+function makeResumeDeliverAnswer(ledger: BackstopDeliveryLedger, sentIdx: number[]) {
+  return async (a: CapturedResumeArgs): Promise<{ delivered: boolean; sentIds: number[] }> => {
+    a.resume.hydrate(ledger, a.turnId)
+    const res = await runBackstopDelivery(
+      ledger,
+      a.turnId,
+      a.resume.snapshot.chunks,
+      a.cardMessageId,
+      {
+        sendChunk: async (i: number) => {
+          sentIdx.push(i)
+          return [7000 + i]
+        },
+        readBack: async (): Promise<ReadBackResult> => 'exists',
+      },
+      3,
+    )
+    return { delivered: res.delivered, sentIds: res.sentIds }
+  }
+}
+
+async function flush(dispatcher: { inFlight: () => string[] }): Promise<void> {
+  for (let i = 0; i < 50 && dispatcher.inFlight().length > 0; i++) {
+    await new Promise((r) => setTimeout(r, 0))
+  }
+}
+
+describe('#3282 buildCapturedDeliverySnapshot — captures per-chunk landed state', () => {
+  it('captures landed chunks (ids + confirmed flag); an unsent chunk is absent', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const chunks = ['c0', 'c1', 'c2']
+    // chunk 0 confirmed, chunk 1 landed-unconfirmed, chunk 2 never sent.
+    await seedPartial(ledger, '#s', chunks, (i) => (i === 0 ? 'ok' : i === 1 ? 'unconfirmed' : 'throw'))
+    const snap = buildCapturedDeliverySnapshot(ledger, '#s', chunks)
+    expect(snap.chunks).toEqual(chunks)
+    const byIndex = Object.fromEntries(snap.chunkStates.map((s) => [s.index, s]))
+    expect(byIndex[0]).toMatchObject({ index: 0, confirmed: true })
+    expect(byIndex[0].messageIds.length).toBeGreaterThan(0)
+    expect(byIndex[1]).toMatchObject({ index: 1, confirmed: false })
+    expect(byIndex[2]).toBeUndefined() // never landed → not in the snapshot
+  })
+})
+
+describe('#3282 hydrateResumeLedger — rebuilds ledger + oracle reconcile', () => {
+  it('confirmed chunk ⇒ excluded from the resume send set; unsent chunk ⇒ included', () => {
+    const l = new BackstopDeliveryLedger()
+    const snap = {
+      chunks: ['c0', 'c1', 'c2'],
+      chunkStates: [{ index: 0, messageIds: [10], confirmed: true }],
+    }
+    hydrateResumeLedger(l, '#h', snap, () => false)
+    expect(l.hasConfirmedChunk('#h', 0)).toBe(true)
+    // chunk 0 confirmed → not resent; chunks 1,2 unsent → the resume tail.
+    expect(l.unsentIndices('#h', 3)).toEqual([1, 2])
+  })
+
+  it('landed-unconfirmed chunk ⇒ re-PROBED (landedUnconfirmed), not re-sent', () => {
+    const l = new BackstopDeliveryLedger()
+    const snap = {
+      chunks: ['c0', 'c1'],
+      chunkStates: [{ index: 0, messageIds: [10], confirmed: false }],
+    }
+    hydrateResumeLedger(l, '#h', snap, () => false)
+    expect(l.landedUnconfirmedIndices('#h', 2)).toEqual([0]) // will be re-probed
+    expect(l.unsentIndices('#h', 2)).toEqual([1]) // only chunk 1 is unsent
+  })
+
+  it('oracle proves a landed-unconfirmed chunk landed ⇒ CONFIRMED (crash-idempotency A5)', () => {
+    const l = new BackstopDeliveryLedger()
+    const snap = {
+      chunks: ['c0', 'c1'],
+      chunkStates: [{ index: 0, messageIds: [10], confirmed: false }],
+    }
+    // The durable outbound row for c0 exists → confirm without re-probe/re-send.
+    hydrateResumeLedger(l, '#h', snap, (txt) => txt === 'c0')
+    expect(l.hasConfirmedChunk('#h', 0)).toBe(true)
+    expect(l.landedUnconfirmedIndices('#h', 2)).toEqual([])
+    expect(l.unsentIndices('#h', 2)).toEqual([1])
+  })
+
+  it('a chunkState with no message ids is left unsent (never fabricates a landing)', () => {
+    const l = new BackstopDeliveryLedger()
+    const snap = { chunks: ['c0'], chunkStates: [{ index: 0, messageIds: [], confirmed: false }] }
+    hydrateResumeLedger(l, '#h', snap, () => false)
+    expect(l.unsentIndices('#h', 1)).toEqual([0])
+  })
+})
+
+describe('#3282 createCapturedResumeDispatcher — the represent RESUME outcome', () => {
+  it('(a) partial [0 confirmed, 1+2 unsent] ⇒ resume sends EXACTLY [1,2]; chunk 0 never re-sent; each chunk once', async () => {
+    const chunks = ['c0', 'c1', 'c2']
+    // Original delivery: chunk 0 lands+confirms, chunks 1,2 fail (unsent).
+    const orig = new BackstopDeliveryLedger()
+    await seedPartial(orig, '#t1', chunks, (i) => (i === 0 ? 'ok' : 'throw'))
+    const snapshot = buildCapturedDeliverySnapshot(orig, '#t1', chunks)
+    orig.clear('#t1') // the turn-flush GCs the in-memory ledger (state is durable)
+
+    // The represent runs on a FRESH ledger (as after a sweep / restart).
+    const resumeLedger = new BackstopDeliveryLedger()
+    const sentIdx: number[] = []
+    const oblLedger = new ObligationLedger(2)
+    const supersedes: Array<{ ids: number[] }> = []
+    const o = obligation({ capturedDelivery: snapshot })
+    oblLedger.openIfAbsent(o)
+    oblLedger.noteCapturedDelivery('#t1', snapshot)
+
+    const dispatcher = createCapturedResumeDispatcher({
+      deliverAnswer: makeResumeDeliverAnswer(resumeLedger, sentIdx),
+      obligationLedger: oblLedger,
+      backstopDeliveryLedger: resumeLedger,
+      flushedTurnSupersede: { record: (_c, _t, rec) => supersedes.push({ ids: rec.messageIds }) },
+      historyEnabled: false,
+    })
+    dispatcher.dispatch(oblLedger.list()[0])
+    await flush(dispatcher)
+
+    // The core anti-regression assertion: ONLY the unlanded tail is (re-)sent.
+    expect(sentIdx.sort()).toEqual([1, 2])
+    expect(sentIdx).not.toContain(0) // chunk 0 (already landed) NEVER re-posted
+    expect(oblLedger.isOpen('#t1')).toBe(false) // fully delivered ⇒ closed
+    // §4 — the supersede record covers the WHOLE delivered set (original landed
+    // chunk 0's id 5000 + the resumed tail's ids), keyed by turn so a late reply
+    // corrects the complete answer in place.
+    expect(supersedes.at(-1)?.ids).toEqual([5000, 7001, 7002])
+  })
+
+  it('(b) restart between landing and confirmation ⇒ oracle-confirmed chunk NOT re-sent', async () => {
+    const chunks = ['c0', 'c1']
+    // Snapshot has chunk 0 landed-unconfirmed (crashed before read-back), chunk 1 unsent.
+    const snapshot = {
+      chunks,
+      chunkStates: [{ index: 0, messageIds: [5000], confirmed: false }],
+    }
+    const resumeLedger = new BackstopDeliveryLedger()
+    const sentIdx: number[] = []
+    const oblLedger = new ObligationLedger(2)
+    oblLedger.openIfAbsent(obligation({ capturedDelivery: snapshot }))
+    oblLedger.noteCapturedDelivery('#t1', snapshot)
+
+    // The durable oracle proves chunk 0's text landed → confirm, don't re-send.
+    mockOracle = (_c, txt) => txt === 'c0'
+
+    const dispatcher = createCapturedResumeDispatcher({
+      deliverAnswer: makeResumeDeliverAnswer(resumeLedger, sentIdx),
+      obligationLedger: oblLedger,
+      backstopDeliveryLedger: resumeLedger,
+      flushedTurnSupersede: { record: () => {} },
+      historyEnabled: true,
+    })
+    dispatcher.dispatch(oblLedger.list()[0])
+    await flush(dispatcher)
+
+    expect(sentIdx).toEqual([1]) // chunk 0 reconciled-confirmed, only chunk 1 sent
+    expect(sentIdx).not.toContain(0)
+    expect(oblLedger.isOpen('#t1')).toBe(false)
+  })
+
+  it('(c) fully-landed answer ⇒ resume sends NOTHING and closes the obligation', async () => {
+    const chunks = ['c0', 'c1']
+    const snapshot = {
+      chunks,
+      chunkStates: [
+        { index: 0, messageIds: [5000], confirmed: true },
+        { index: 1, messageIds: [5001], confirmed: true },
+      ],
+    }
+    const resumeLedger = new BackstopDeliveryLedger()
+    const sentIdx: number[] = []
+    const oblLedger = new ObligationLedger(2)
+    oblLedger.openIfAbsent(obligation({ capturedDelivery: snapshot }))
+    oblLedger.noteCapturedDelivery('#t1', snapshot)
+
+    const dispatcher = createCapturedResumeDispatcher({
+      deliverAnswer: makeResumeDeliverAnswer(resumeLedger, sentIdx),
+      obligationLedger: oblLedger,
+      backstopDeliveryLedger: resumeLedger,
+      flushedTurnSupersede: { record: () => {} },
+      historyEnabled: false,
+    })
+    dispatcher.dispatch(oblLedger.list()[0])
+    await flush(dispatcher)
+
+    expect(sentIdx).toEqual([]) // nothing re-posted
+    expect(oblLedger.isOpen('#t1')).toBe(false)
+  })
+
+  it('a partial RESUME (tail still fails) leaves the obligation OPEN + consumes represent budget', async () => {
+    const chunks = ['c0', 'c1']
+    const snapshot = {
+      chunks,
+      chunkStates: [{ index: 0, messageIds: [5000], confirmed: true }],
+    }
+    const resumeLedger = new BackstopDeliveryLedger()
+    const oblLedger = new ObligationLedger(2)
+    oblLedger.openIfAbsent(obligation({ capturedDelivery: snapshot }))
+    oblLedger.noteCapturedDelivery('#t1', snapshot)
+
+    // A resume whose tail send keeps throwing ⇒ not delivered ⇒ obligation stays OPEN.
+    const dispatcher = createCapturedResumeDispatcher({
+      deliverAnswer: async (a) => {
+        a.resume.hydrate(resumeLedger, a.turnId)
+        const res = await runBackstopDelivery(
+          resumeLedger, a.turnId, a.resume.snapshot.chunks, a.cardMessageId,
+          { sendChunk: async () => { throw new Error('FLOOD_WAIT_ACTIVE') }, readBack: async () => 'exists' as ReadBackResult },
+          2,
+        )
+        return { delivered: res.delivered, sentIds: res.sentIds }
+      },
+      obligationLedger: oblLedger,
+      backstopDeliveryLedger: resumeLedger,
+      flushedTurnSupersede: { record: () => {} },
+      historyEnabled: false,
+    })
+    dispatcher.dispatch(oblLedger.list()[0])
+    await flush(dispatcher)
+
+    expect(oblLedger.isOpen('#t1')).toBe(true) // left OPEN for the next paced sweep
+    expect(oblLedger.list()[0].representCount).toBe(1) // budget consumed → bounded ladder
+  })
+
+  it('de-dupes concurrent dispatches for the same origin (only one resume runs)', async () => {
+    const chunks = ['c0', 'c1']
+    const orig = new BackstopDeliveryLedger()
+    await seedPartial(orig, '#t1', chunks, (i) => (i === 0 ? 'ok' : 'throw'))
+    const snapshot = buildCapturedDeliverySnapshot(orig, '#t1', chunks)
+    orig.clear('#t1')
+
+    const resumeLedger = new BackstopDeliveryLedger()
+    let deliverCalls = 0
+    const oblLedger = new ObligationLedger(2)
+    oblLedger.openIfAbsent(obligation({ capturedDelivery: snapshot }))
+    oblLedger.noteCapturedDelivery('#t1', snapshot)
+
+    const dispatcher = createCapturedResumeDispatcher({
+      deliverAnswer: async (a) => {
+        deliverCalls++
+        a.resume.hydrate(resumeLedger, a.turnId)
+        const res = await runBackstopDelivery(
+          resumeLedger, a.turnId, a.resume.snapshot.chunks, a.cardMessageId,
+          { sendChunk: async (i: number) => [7000 + i], readBack: async () => 'exists' as ReadBackResult },
+          3,
+        )
+        return { delivered: res.delivered, sentIds: res.sentIds }
+      },
+      obligationLedger: oblLedger,
+      backstopDeliveryLedger: resumeLedger,
+      flushedTurnSupersede: { record: () => {} },
+      historyEnabled: false,
+    })
+    const o = oblLedger.list()[0]
+    dispatcher.dispatch(o)
+    dispatcher.dispatch(o) // second, concurrent — must be a no-op
+    await flush(dispatcher)
+    expect(deliverCalls).toBe(1)
+  })
+
+  it('no captured snapshot ⇒ dispatch is a no-op (caller falls through to fresh generation)', async () => {
+    let delivered = false
+    const dispatcher = createCapturedResumeDispatcher({
+      deliverAnswer: async () => { delivered = true; return { delivered: true, sentIds: [] } },
+      obligationLedger: new ObligationLedger(2),
+      backstopDeliveryLedger: new BackstopDeliveryLedger(),
+      flushedTurnSupersede: { record: () => {} },
+      historyEnabled: false,
+    })
+    dispatcher.dispatch(obligation()) // no capturedDelivery
+    dispatcher.dispatch(obligation({ capturedDelivery: { chunks: [], chunkStates: [] } })) // empty
+    await flush(dispatcher)
+    expect(delivered).toBe(false)
+  })
+})