switchroom 0.20.6 → 0.20.8

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -9,6 +9,8 @@
 import { describe, it, expect } from 'vitest'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick, planBufferedRedelivery, DEFAULT_PENDING_INBOUND_CAP } from '../gateway/pending-inbound-buffer.js'
 import type { InboundMessage } from '../gateway/ipc-protocol.js'
+import { ObligationLedger } from '../gateway/obligation-ledger.js'
+import { makeRepresentRedeliveryGuard } from '../gateway/represent-delivery-guard.js'
 
 function inbound(source: string, ts = Date.now()): InboundMessage {
   return {
@@ -223,7 +225,7 @@ describe('redeliverBufferedInbound — wedge-clear self-heal (fleet-update incid
       seen.push(m.messageId as number)
       return true
     })
-    expect(r).toEqual({ drained: 2, redelivered: 2, rebuffered: 0 })
+    expect(r).toEqual({ drained: 2, redelivered: 2, rebuffered: 0, retracted: 0 })
     expect(seen).toEqual([1, 2]) // FIFO preserved
     expect(buf.depth('klanker')).toBe(0)
   })
@@ -233,7 +235,7 @@ describe('redeliverBufferedInbound — wedge-clear self-heal (fleet-update incid
     buf.push('klanker', inbound('user', 1))
     buf.push('klanker', inbound('cron', 2))
     const r = redeliverBufferedInbound(buf, 'klanker', () => false)
-    expect(r).toEqual({ drained: 2, redelivered: 0, rebuffered: 2 })
+    expect(r).toEqual({ drained: 2, redelivered: 0, rebuffered: 2, retracted: 0 })
     expect(buf.depth('klanker')).toBe(2) // still there, nothing lost
     expect(buf.drain('klanker').map((m) => m.meta?.source)).toEqual(['user', 'cron'])
   })
@@ -244,7 +246,7 @@ describe('redeliverBufferedInbound — wedge-clear self-heal (fleet-update incid
     const r = redeliverBufferedInbound(buf, 'klanker', () => {
       throw new Error('bridge write failed')
     })
-    expect(r).toEqual({ drained: 1, redelivered: 0, rebuffered: 1 })
+    expect(r).toEqual({ drained: 1, redelivered: 0, rebuffered: 1, retracted: 0 })
     expect(buf.depth('klanker')).toBe(1)
   })
 
@@ -258,7 +260,7 @@ describe('redeliverBufferedInbound — wedge-clear self-heal (fleet-update incid
       n++
       return n !== 2 // 2nd send fails
     })
-    expect(r).toEqual({ drained: 3, redelivered: 2, rebuffered: 1 })
+    expect(r).toEqual({ drained: 3, redelivered: 2, rebuffered: 1, retracted: 0 })
     expect(buf.drain('klanker').map((m) => m.meta?.source)).toEqual(['b'])
   })
 
@@ -269,7 +271,7 @@ describe('redeliverBufferedInbound — wedge-clear self-heal (fleet-update incid
       calls++
       return true
     })
-    expect(r).toEqual({ drained: 0, redelivered: 0, rebuffered: 0 })
+    expect(r).toEqual({ drained: 0, redelivered: 0, rebuffered: 0, retracted: 0 })
     expect(calls).toBe(0)
   })
 
@@ -334,7 +336,7 @@ describe('idleDrainTick — the 3rd drain trigger (finn orphan gap, 2026-05-19)'
     buf.push('finn', inbound('user', 2013)) // the orphaned "verify with mff-query.py" class
     const seen: number[] = []
     const r = idleDrainTick(buf, 'finn', () => true, (m) => { seen.push(m.messageId as number); return true })
-    expect(r).toEqual({ drained: 1, redelivered: 1, rebuffered: 0 })
+    expect(r).toEqual({ drained: 1, redelivered: 1, rebuffered: 0, retracted: 0 })
     expect(seen).toEqual([2013])
     expect(buf.depth('finn')).toBe(0)
   })
@@ -343,7 +345,7 @@ describe('idleDrainTick — the 3rd drain trigger (finn orphan gap, 2026-05-19)'
     const buf = createPendingInboundBuffer({ log: () => {} })
     buf.push('finn', inbound('user', 1))
     const r = idleDrainTick(buf, 'finn', () => true, () => false)
-    expect(r).toEqual({ drained: 1, redelivered: 0, rebuffered: 1 })
+    expect(r).toEqual({ drained: 1, redelivered: 0, rebuffered: 1, retracted: 0 })
     expect(buf.depth('finn')).toBe(1) // nothing lost
     expect(idleDrainTick(buf, '', () => true, () => true)).toBeNull() // empty agent guard
   })
@@ -419,6 +421,7 @@ describe('durable-spool integration (finn/carrie lost-on-restart fix)', () => {
       drained: 1,
       redelivered: 1,
       rebuffered: 0,
+      retracted: 0,
     })
   })
 })
@@ -589,7 +592,7 @@ describe('planBufferedRedelivery — merge-on-drain (forwarded-burst across a tu
       return true
     })
     expect(sent).toEqual(['part 1\npart 2\npart 3']) // ONE turn, not three
-    expect(r).toEqual({ drained: 3, redelivered: 3, rebuffered: 0 })
+    expect(r).toEqual({ drained: 3, redelivered: 3, rebuffered: 0, retracted: 0 })
     expect(buf.depth('ziggy')).toBe(0)
   })
 
@@ -598,7 +601,7 @@ describe('planBufferedRedelivery — merge-on-drain (forwarded-burst across a tu
     buf.push('ziggy', userMsg({ text: 'part 1', ts: 1 }))
     buf.push('ziggy', userMsg({ text: 'part 2', ts: 2 }))
     const r = redeliverBufferedInbound(buf, 'ziggy', () => false)
-    expect(r).toEqual({ drained: 2, redelivered: 0, rebuffered: 2 })
+    expect(r).toEqual({ drained: 2, redelivered: 0, rebuffered: 2, retracted: 0 })
     expect(buf.depth('ziggy')).toBe(2) // both originals back, nothing lost
     expect(buf.drain('ziggy').map((m) => m.text)).toEqual(['part 1', 'part 2'])
   })
@@ -713,3 +716,136 @@ describe('planBufferedRedelivery — seeded fuzz over random burst schedules', (
     }
   })
 })
+
+/**
+ * F1 end-to-end: the delivery-time represent re-check wired into
+ * redeliverBufferedInbound via `beforeRedeliver`. These exercise the WHOLE
+ * drain path (buffer → plan → guard → send) against a real ObligationLedger,
+ * asserting OUTCOMES: a stale represent is dropped and the ledger closed; a
+ * truly-unanswered obligation fires exactly one represent.
+ */
+describe('redeliverBufferedInbound + F1 delivery-time represent re-check', () => {
+  const CHAT = 'c1'
+  const ORIGIN = 'turn-abc'
+  const OPENED_AT = 1_000
+
+  function representInbound(): InboundMessage {
+    return {
+      type: 'inbound',
+      chatId: CHAT,
+      messageId: 5_000,
+      user: 'obligation-ledger',
+      userId: 0,
+      ts: 5_000,
+      text: 'You asked earlier and I want to make sure I did not miss it…',
+      meta: { source: 'obligation_represent', origin_turn_id: ORIGIN },
+    }
+  }
+
+  function openLedger(): ObligationLedger {
+    const l = new ObligationLedger()
+    l.openIfAbsent({
+      originTurnId: ORIGIN,
+      chatId: CHAT,
+      messageId: 42,
+      text: 'original question',
+      openedAt: OPENED_AT,
+    })
+    return l
+  }
+
+  function guardFor(
+    ledger: ObligationLedger,
+    hasOutboundDeliveredSince: (chatId: string, sinceMs: number) => boolean,
+  ) {
+    return makeRepresentRedeliveryGuard({
+      enabled: true,
+      historyEnabled: true,
+      ledger,
+      hasOutboundDeliveredSince: (chatId, sinceMs) => hasOutboundDeliveredSince(chatId, sinceMs),
+      minReplyChars: 1,
+      log: () => {},
+    })
+  }
+
+  it('drops a buffered represent whose reply landed since decision, and closes the ledger', () => {
+    const ledger = openLedger()
+    // A real answer was delivered AT/AFTER the obligation's cutoff (openedAt).
+    const buf = createPendingInboundBuffer({
+      log: () => {},
+      beforeRedeliver: guardFor(ledger, (_chat, sinceMs) => sinceMs <= 2_000),
+    })
+    buf.push('a', representInbound())
+
+    let sends = 0
+    const r = redeliverBufferedInbound(buf, 'a', () => {
+      sends++
+      return true
+    })
+
+    expect(sends).toBe(0) // never handed to the CLI bridge
+    expect(r.drained).toBe(1)
+    expect(r.retracted).toBe(1)
+    expect(r.redelivered).toBe(0)
+    expect(r.rebuffered).toBe(0)
+    expect(ledger.isOpen(ORIGIN)).toBe(false) // F1 closed the stale obligation
+    expect(buf.depth('a')).toBe(0) // dropped, not re-buffered
+  })
+
+  it('delivers exactly one represent for a truly-unanswered obligation (no outbound row)', () => {
+    const ledger = openLedger()
+    // Plain-text-no-reply / genuinely unanswered: no outbound recorded since cutoff.
+    const buf = createPendingInboundBuffer({
+      log: () => {},
+      beforeRedeliver: guardFor(ledger, () => false),
+    })
+    buf.push('a', representInbound())
+
+    let sends = 0
+    const r = redeliverBufferedInbound(buf, 'a', () => {
+      sends++
+      return true
+    })
+
+    expect(sends).toBe(1)
+    expect(r.drained).toBe(1)
+    expect(r.redelivered).toBe(1)
+    expect(r.retracted).toBe(0)
+    expect(r.rebuffered).toBe(0)
+    expect(ledger.isOpen(ORIGIN)).toBe(true) // still open — the represent will be answered
+  })
+})
+
+/**
+ * FAIL-OPEN safety: a `beforeRedeliver` predicate that THROWS must never silence
+ * or lose a real message, nor abort the drain loop. The throw is swallowed, the
+ * message is treated as "deliver", and every following buffered message in the
+ * same drain is still delivered. This test fails if the try/catch around the
+ * predicate is removed (the throw would propagate out of redeliverBufferedInbound).
+ */
+describe('redeliverBufferedInbound — beforeRedeliver fail-open on throw', () => {
+  it('delivers the message and the rest of the drain when the predicate throws', () => {
+    const buf = createPendingInboundBuffer({
+      log: () => {},
+      beforeRedeliver: () => {
+        throw new Error('guard boom')
+      },
+    })
+    buf.push('a', inbound('cron', 1))
+    buf.push('a', inbound('vault_grant_approved', 2))
+
+    const seen: number[] = []
+    // Must not throw — the loop completes past a throwing predicate.
+    const r = redeliverBufferedInbound(buf, 'a', (m) => {
+      seen.push(m.messageId as number)
+      return true
+    })
+
+    expect(seen).toEqual([1, 2]) // both delivered, loop not aborted
+    expect(r.drained).toBe(2)
+    expect(r.redelivered).toBe(2) // failed open → delivered, not dropped
+    expect(r.retracted).toBe(0) // a throw is NOT a retract
+    expect(r.rebuffered).toBe(0)
+    expect(buf.depth('a')).toBe(0) // nothing stranded
+  })
+})

package/telegram-plugin/tests/queued-card-surface.test.ts

@@ -260,3 +260,69 @@ describe('Part B — handback-while-busy: exactly one card, never a frozen "Queu
     expect(rec.edits).toHaveLength(0)
   })
 })
+
+describe('Part B — synthetic (fabricated) message ids never 400 the queued card', () => {
+  /** Recording bot that enforces the REAL Telegram Bot API contract on
+   *  `reply_parameters.message_id`: anything non-integer or beyond signed int32
+   *  is hard-rejected with the exact 400 the live gateway hit
+   *  (gateway-supervisor.log 2026-08-04, msg=1785846295635) — BEFORE recording,
+   *  exactly like the wire call. `allow_sending_without_reply` does not bypass
+   *  the range check, only the message-not-found case. */
+  function withTelegramStrictBot(h: Harness) {
+    const sends: SendRec[] = []
+    let nextId = 9001
+    ;(h.deps as unknown as { bot: unknown }).bot = {
+      api: {
+        sendRichMessage: async (chatId: string, msg: { markdown: string }, opts: Record<string, unknown>) => {
+          const rp = opts.reply_parameters as { message_id?: unknown } | undefined
+          if (rp != null) {
+            const mid = rp.message_id
+            if (typeof mid !== 'number' || !Number.isInteger(mid) || mid <= 0 || mid >= 2 ** 31) {
+              throw new Error(
+                `Call to 'sendRichMessage' failed! (400: Bad Request: field "message_id" must be a valid Number)`,
+              )
+            }
+          }
+          const id = nextId++
+          sends.push({ chatId, markdown: msg.markdown, opts, id })
+          return { message_id: id }
+        },
+        editMessageText: async () => true,
+        deleteMessage: async () => true,
+      },
+    }
+    return { sends }
+  }
+
+  it('sends the queued card UNANCHORED (no 400) when the parked message id is a fabricated Date.now() timestamp', async () => {
+    const h = makeHarness()
+    const rec = withTelegramStrictBot(h)
+
+    // Turn A mints on an idle session.
+    handleSessionEvent(h.deps, enqueue('501'))
+    expect(rec.sends).toHaveLength(0)
+
+    // A synthetic enqueue (subagent handback / boot resume) parks mid-turn with
+    // a fabricated ms-timestamp message id — finite, but NOT a Telegram id.
+    handleSessionEvent(h.deps, enqueue('1785846295635', 'handback: worker done'))
+    await settle()
+    expect(__parkedTurnStartCountForTest()).toBe(1)
+
+    // The card SENT (no 400 — RED on the pre-fix guard, which forwarded the
+    // 13-digit id into reply_parameters and lost the whole card)…
+    expect(rec.sends).toHaveLength(1)
+    // …and it sent WITHOUT reply-linkage: no reply_parameters at all.
+    expect(rec.sends[0]!.opts.reply_parameters).toBeUndefined()
+  })
+
+  it('still reply-anchors when the parked message id is a real Telegram id', async () => {
+    const h = makeHarness()
+    const rec = withTelegramStrictBot(h)
+
+    handleSessionEvent(h.deps, enqueue('501'))
+    handleSessionEvent(h.deps, enqueue('502', 'real mid-turn message'))
+    await settle()
+    expect(rec.sends).toHaveLength(1)
+    expect((rec.sends[0]!.opts.reply_parameters as { message_id: number }).message_id).toBe(502)
+  })
+})

package/telegram-plugin/tests/represent-guard.test.ts

@@ -4,6 +4,12 @@ import {
   type RepresentGuardObligation,
 } from "../gateway/represent-guard.js";
 import { ObligationLedger } from "../gateway/obligation-ledger.js";
+import {
+  makeRepresentRedeliveryGuard,
+  makeSessionBusyDrainDeferral,
+} from "../gateway/represent-delivery-guard.js";
+import { createObligationWiring } from "../gateway/obligation-wiring.js";
+import type { InboundMessage } from "../gateway/ipc-protocol.js";
 
 // Executable verification of the #2472 fix: obligation_represent must NOT re-fire
 // for an origin_turn_id that has already been answered by a reply since the last
@@ -171,6 +177,295 @@ describe("represent guard — terse genuine reply suppresses the duplicate (#247
   });
 });
 
+// F1 (fix/represent-double-send-delivery-recheck) — the DELIVERY-time re-check.
+// The decision-time guard (shouldSuppressRepresent) is consulted when the sweep
+// buffers a represent, which can be BEFORE the reply exists. This layer re-runs it
+// at the moment the buffered represent is handed to the CLI bridge, catching the
+// reply that landed in between (the double-send race).
+describe("makeRepresentRedeliveryGuard — F1 delivery-time represent re-check", () => {
+  const MSG_ID = 42;
+
+  function representInbound(originTurnId: string, chatId: string): InboundMessage {
+    return {
+      type: "inbound",
+      chatId,
+      messageId: MSG_ID,
+      user: "switchroom",
+      userId: 0,
+      ts: 1,
+      text: "you have an earlier message…",
+      meta: { source: "obligation_represent", origin_turn_id: originTurnId, chat_id: chatId },
+    };
+  }
+
+  function openRepresented(ledger: ObligationLedger, representedAt: number, openedAt = 1000): void {
+    ledger.openIfAbsent({ originTurnId: ORIGIN, chatId: CHAT, messageId: MSG_ID, text: "q", openedAt });
+    ledger.markRepresented(ORIGIN, representedAt); // mirror the sweep stamping lastRepresentedAt
+  }
+
+  it("RETRACTS (drops + closes) a represent whose reply landed since the decision", () => {
+    const ledger = new ObligationLedger();
+    openRepresented(ledger, 2000); // sweep decided this represent at t=2000
+    // The real reply was recorded at t=3000 (AFTER the decision) but its routing
+    // missed the normal close path — the exact double-send race.
+    const guard = makeRepresentRedeliveryGuard({
+      enabled: true,
+      historyEnabled: true,
+      ledger,
+      // Chat-scoped: only the obligation's OWN (resolved) chat id has the row —
+      // outbound was recorded under the fallback-resolved id, which is o.chatId.
+      hasOutboundDeliveredSince: (chat, sinceMs) => chat === CHAT && 3000 >= sinceMs,
+      minReplyChars: 1,
+      log: () => {},
+    });
+    expect(guard(representInbound(ORIGIN, CHAT))).toBe(false); // do NOT deliver
+    expect(ledger.isOpen(ORIGIN)).toBe(false); // ledger closed by the retract
+  });
+
+  it("RETRACTS a represent whose obligation was already closed since it was buffered", () => {
+    const ledger = new ObligationLedger();
+    openRepresented(ledger, 2000);
+    ledger.close(ORIGIN); // the normal close path DID fire after buffering
+    const guard = makeRepresentRedeliveryGuard({
+      enabled: true,
+      historyEnabled: true,
+      ledger,
+      hasOutboundDeliveredSince: () => false, // irrelevant — obligation is gone
+      minReplyChars: 1,
+      log: () => {},
+    });
+    expect(guard(representInbound(ORIGIN, CHAT))).toBe(false); // stale → drop
+  });
+
+  it("PROCEEDS (delivers once) when NO outbound row exists — plain-text-no-reply (#2788)", () => {
+    const ledger = new ObligationLedger();
+    openRepresented(ledger, 2000);
+    const guard = makeRepresentRedeliveryGuard({
+      enabled: true,
+      historyEnabled: true,
+      ledger,
+      hasOutboundDeliveredSince: () => false, // the agent never called the reply tool
+      minReplyChars: 1,
+      log: () => {},
+    });
+    expect(guard(representInbound(ORIGIN, CHAT))).toBe(true); // still fires exactly once
+    expect(ledger.isOpen(ORIGIN)).toBe(true); // guard did NOT close it
+  });
+
+  it("PROCEEDS when the only reply PREDATES lastRepresentedAt (#2472 second-represent cutoff)", () => {
+    const ledger = new ObligationLedger();
+    openRepresented(ledger, 5000); // second represent decided at t=5000
+    // A reply exists but only at t=3000 — it answered an EARLIER question, not
+    // this represent. The delivery re-check must use the obligation's own cutoff
+    // (lastRepresentedAt=5000), so this old reply does NOT suppress.
+    const guard = makeRepresentRedeliveryGuard({
+      enabled: true,
+      historyEnabled: true,
+      ledger,
+      hasOutboundDeliveredSince: (_chat, sinceMs) => 3000 >= sinceMs,
+      minReplyChars: 1,
+      log: () => {},
+    });
+    expect(guard(representInbound(ORIGIN, CHAT))).toBe(true); // legitimate new represent fires
+    expect(ledger.isOpen(ORIGIN)).toBe(true);
+  });
+
+  it("passes NON-represent inbounds through untouched", () => {
+    const ledger = new ObligationLedger();
+    openRepresented(ledger, 2000);
+    const guard = makeRepresentRedeliveryGuard({
+      enabled: true,
+      historyEnabled: true,
+      ledger,
+      hasOutboundDeliveredSince: () => true, // would suppress a represent — but this isn't one
+      minReplyChars: 1,
+      log: () => {},
+    });
+    const userMsg: InboundMessage = {
+      type: "inbound",
+      chatId: CHAT,
+      messageId: 7,
+      user: "ken",
+      userId: 1,
+      ts: 1,
+      text: "hello",
+    };
+    expect(guard(userMsg)).toBe(true);
+    expect(ledger.isOpen(ORIGIN)).toBe(true);
+  });
+
+  it("is inert when the obligation ledger is disabled", () => {
+    const ledger = new ObligationLedger();
+    openRepresented(ledger, 2000);
+    const guard = makeRepresentRedeliveryGuard({
+      enabled: false,
+      historyEnabled: true,
+      ledger,
+      hasOutboundDeliveredSince: () => true,
+      minReplyChars: 1,
+      log: () => {},
+    });
+    expect(guard(representInbound(ORIGIN, CHAT))).toBe(true); // never retracts when off
+  });
+});
+
+// F2 (fix/represent-double-send-delivery-recheck) — a poke-cleared session that is
+// STILL busy must not be treated as idle. Two halves: the bounded drain-defer
+// (drain half) and the sweep decision folding session-busy into the bounded
+// background-work grace (decision half).
+describe("makeSessionBusyDrainDeferral — F2 bounded busy-defer for the idle drain", () => {
+  it("defers while busy, then STOPS deferring once the bound elapses (red-team #2: no forever-silence)", () => {
+    const defer = makeSessionBusyDrainDeferral(1000);
+    expect(defer(true, 0)).toBe(true); // busy → defer the drain
+    expect(defer(true, 500)).toBe(true); // still within the bound
+    expect(defer(true, 999)).toBe(true);
+    expect(defer(true, 1000)).toBe(false); // bound reached → drain anyway (bounded)
+  });
+
+  it("resets the deferral clock whenever the session reads idle", () => {
+    const defer = makeSessionBusyDrainDeferral(1000);
+    expect(defer(true, 0)).toBe(true);
+    expect(defer(false, 400)).toBe(false); // idle → reset
+    expect(defer(true, 500)).toBe(true); // fresh window opens at 500
+    expect(defer(true, 1499)).toBe(true); // 999ms into the new window
+    expect(defer(true, 1500)).toBe(false); // new bound elapsed
+  });
+
+  it("is disabled when the bound is <= 0 (kill switch)", () => {
+    const off = makeSessionBusyDrainDeferral(0);
+    expect(off(true, 0)).toBe(false);
+    expect(off(true, 10_000)).toBe(false);
+  });
+
+  it("starts a FRESH bound for a new deferral episode after a call gap — a buffer emptied by bridge re-register (no busy=false call) must not pin a stale t0 (#4341 follow-up)", () => {
+    const BOUND = 20_000; // small bound so a realistic 5s poll cadence spans it
+    const defer = makeSessionBusyDrainDeferral(BOUND); // default staleGap = 15s
+
+    // Episode A: a represent is buffered while the session is busy. The idle
+    // drain gate polls it every ~5s (< staleGap) and defers each time.
+    expect(defer(true, 0)).toBe(true); // t0 = 0
+    expect(defer(true, 5_000)).toBe(true);
+    expect(defer(true, 10_000)).toBe(true);
+
+    // The buffer is now emptied by a bridge re-register (onClientRegistered)
+    // while the session is STILL busy. That drain path does NOT consult this
+    // predicate, so there is no busy=false call — deferringSince stays at 0 on
+    // the buggy code. Time then advances well past the bound with the buffer
+    // empty (predicate not called).
+
+    // Episode B: a brand-new represent is buffered while the session is busy,
+    // long after t0. This is a NEW mid-answer session — the represent MUST stay
+    // deferred (its own bound has not elapsed), NOT be drained immediately.
+    // Buggy code: now - stalePinnedT0 (2_000_000 - 0) >= BOUND → false → the
+    // represent is drained into the mid-answer session, reopening the duplicate
+    // window. Fixed code: the >15s call gap starts a fresh episode clock at
+    // t=2_000_000, so it defers.
+    const B0 = 2_000_000;
+    expect(defer(true, B0)).toBe(true);
+    // ...and the fresh episode is still bounded from ITS OWN start, polled at the
+    // real ~5s cadence (each gap < staleGap, so no further reset).
+    expect(defer(true, B0 + 5_000)).toBe(true);
+    expect(defer(true, B0 + 10_000)).toBe(true);
+    expect(defer(true, B0 + 15_000)).toBe(true);
+    expect(defer(true, B0 + BOUND)).toBe(false); // fresh bound elapsed → drains
+  });
+
+  it("does NOT reset the clock on the normal poll cadence — a genuinely wedged busy session still drains at the bound (wedge budget preserved)", () => {
+    const BOUND = 20_000;
+    const defer = makeSessionBusyDrainDeferral(BOUND); // default staleGap = 15s
+    // Polls arrive every 5s (< staleGap) throughout one continuous episode, so
+    // the clock is never reset and the bound elapses on schedule.
+    expect(defer(true, 0)).toBe(true);
+    expect(defer(true, 5_000)).toBe(true);
+    expect(defer(true, 10_000)).toBe(true);
+    expect(defer(true, 15_000)).toBe(true);
+    expect(defer(true, 20_000)).toBe(false); // bound reached — drains, not silenced forever
+  });
+});
+
+describe("obligationSweep — F2 decision half: a poke-cleared-but-busy session defers, then re-asks (bounded)", () => {
+  const GRACE = 20 * 60_000;
+  const SWEEP_ORIGIN = "12345:_#77001";
+
+  function makeWiring(opts: { ledger: ObligationLedger; pushed: InboundMessage[]; sessionBusy: boolean }) {
+    const liveTurn = opts.sessionBusy ? ({ turnId: "live", endedAt: null } as any) : null;
+    const deps = {
+      OBLIGATION_LEDGER_ENABLED: true,
+      HISTORY_ENABLED: true,
+      OBLIGATION_BACKGROUND_WORK_GRACE_MS: GRACE,
+      OBLIGATION_ESCALATE_GRACE_MS: 0,
+      OBLIGATION_REPRESENT_GRACE_MS: 0,
+      OBLIGATION_REPRESENT_MAX: 2,
+      OBLIGATION_REPRESENT_GUARD_MIN_REPLY_CHARS: 1,
+      OBLIGATION_ESCALATE_MAX: 3,
+      OBLIGATION_ESCALATE_SEND_DEADLINE_MS: 10_000,
+      obligationLedger: opts.ledger,
+      obligationEscalateInFlight: new Set<string>(),
+      pendingCrossTurnGate: { set: () => {} },
+      pendingInboundBuffer: {
+        depth: () => 0,
+        push: (_agent: string, m: InboundMessage) => {
+          opts.pushed.push(m);
+          return true;
+        },
+      },
+      capturedResume: { dispatch: () => {} },
+      getCurrentTurn: () => liveTurn,
+      // The ~5-min silence poke has ALREADY cleared the machine turn.
+      turnInFlightForGate: () => false,
+      agentHasInFlightBackgroundWork: () => false,
+      // No reply has been delivered — a genuinely unanswered turn.
+      hasOutboundDeliveredSince: () => false,
+      findTurnByOriginId: () => undefined,
+      bridgeAlive: () => true,
+      sendEscalationNudge: () => {},
+    };
+    // The wiring's dep type is derived from the gateway; the shape above matches
+    // the fields the sweep reads.
+    return createObligationWiring(deps as unknown as Parameters<typeof createObligationWiring>[0]);
+  }
+
+  function open(ledger: ObligationLedger, openedAt: number): void {
+    ledger.openIfAbsent({
+      originTurnId: SWEEP_ORIGIN,
+      chatId: CHAT,
+      messageId: 77001,
+      text: "an unanswered question",
+      openedAt,
+    });
+  }
+
+  it("DEFERS the represent while the session is busy and the obligation is younger than the grace", () => {
+    const ledger = new ObligationLedger(2);
+    const pushed: InboundMessage[] = [];
+    const wiring = makeWiring({ ledger, pushed, sessionBusy: true });
+    open(ledger, Date.now()); // age ~0 < GRACE
+    wiring.obligationSweep();
+    expect(pushed).toHaveLength(0); // deferred — no represent buffered
+    expect(ledger.isOpen(SWEEP_ORIGIN)).toBe(true);
+  });
+
+  it("RE-ASKS once the bound expires even though the session is still busy (bounded, not silent)", () => {
+    const ledger = new ObligationLedger(2);
+    const pushed: InboundMessage[] = [];
+    const wiring = makeWiring({ ledger, pushed, sessionBusy: true });
+    open(ledger, Date.now() - (GRACE + 60_000)); // age > GRACE → bound expired
+    wiring.obligationSweep();
+    expect(pushed).toHaveLength(1); // represent fires despite the still-busy session
+    expect(pushed[0]?.meta?.source).toBe("obligation_represent");
+  });
+
+  it("does NOT defer when the session is idle (represent fires immediately)", () => {
+    const ledger = new ObligationLedger(2);
+    const pushed: InboundMessage[] = [];
+    const wiring = makeWiring({ ledger, pushed, sessionBusy: false });
+    open(ledger, Date.now()); // young, but session is genuinely idle
+    wiring.obligationSweep();
+    expect(pushed).toHaveLength(1);
+    expect(pushed[0]?.meta?.source).toBe("obligation_represent");
+  });
+});
+
 describe("represent_count cap is honored by the ledger — a misdetected obligation cannot loop", () => {
   it("escalates (stops re-presenting) once representCount reaches maxRepresents", () => {
     const L = new ObligationLedger(2); // maxRepresents = 2