switchroom 0.17.10 → 0.18.3

package/telegram-plugin/tests/orphaned-reply-rearm.test.ts

@@ -1,21 +1,22 @@
 /**
- * Unit tests for the activity-feed-teardown fix (orphaned-reply backstop).
+ * Unit tests for the orphaned-reply backstop, repointed at the REAL
+ * LivenessTracker (the thinking-pause fix seam) — no replica decision helpers.
  *
  * Root cause: the orphaned-reply backstop fired a synthetic turn_end
- * (`durationMs: -1`) after 30 s of silence, even mid-tool-call. That nulled
+ * (`durationMs: -1`) after 30 s of silence, even mid-work. That nulled
  * `currentTurn` and dropped every subsequent `tool_label`, darkening the live
  * activity feed for the rest of the turn.
  *
- * Fix: three layers described in the PR.
- *   PRIMARY   — fuse fires mid-tool → re-arm instead (bounded by ORPHANED_REPLY_MAX_REARMS).
- *   SECONDARY — tool_label re-arms the fuse so active label streams keep it fresh.
- *   DEFENSIVE — turn_end entry rejects the synthetic event if tools are in flight.
- *
- * These tests cover the pure / unit-testable surfaces:
- *   - shouldArmOrphanedReplyTimeout (existing, now with midToolCall param)
- *   - ORPHANED_REPLY_MAX_REARMS constant math
- *   - The re-arm guard logic (pure decision extracted from the closure)
- *   - The defensive turn_end discriminator (durationMs === -1 + in-flight check)
+ * Fix layers (all now expressed through `LivenessTracker`):
+ *   PRIMARY   — the fuse fires mid-work → re-arm instead. `decideOnExpiry`
+ *               re-arms while working OR recently-streaming OR human-waiting,
+ *               bounded by ORPHANED_REPLY_MAX_REARMS for the working /
+ *               recently-streaming cases (human-wait is uncapped).
+ *   SECONDARY — a genuine stream event (`onStreamEvent`) re-stamps liveness and
+ *               zeroes the rearm counter, so an actively-progressing turn never
+ *               hits the cap.
+ *   DEFENSIVE — the gateway rejects a synthetic turn_end while the turn is
+ *               legitimately working OR recently streaming (`recentlyStreaming`).
  */
 
 import { describe, it, expect } from 'vitest'
@@ -23,37 +24,24 @@ import {
   shouldArmOrphanedReplyTimeout,
   ORPHANED_REPLY_TIMEOUT_MS,
   ORPHANED_REPLY_MAX_REARMS,
+  ORPHANED_REPLY_STREAM_WINDOW_MS,
+  LivenessTracker,
 } from '../context-exhaustion.js'
 import { ToolFlightTracker } from '../gateway/interrupt-defer.js'
 
-// ---------------------------------------------------------------------------
-// Helpers — pure decision functions mirroring the gateway closure logic.
-// These extract the discriminable parts of the fix so they are unit-testable
-// without instantiating the full gateway.
-// ---------------------------------------------------------------------------
-
-/**
- * Mirrors the PRIMARY fix decision inside the setTimeout callback:
- * should the backstop re-arm (true) or fire turn_end (false)?
- */
-function shouldRearmInsteadOfFire(opts: {
-  midToolCall: boolean
-  rearmCount: number
-  maxRearms: number
-}): boolean {
-  return opts.midToolCall && opts.rearmCount < opts.maxRearms
-}
+const W = ORPHANED_REPLY_STREAM_WINDOW_MS
+const MAX = ORPHANED_REPLY_MAX_REARMS
 
 /**
- * Mirrors the DEFENSIVE fix at turn_end entry:
- * should a synthetic turn_end (durationMs === -1) be suppressed?
+ * A tracker whose last stream event is far enough in the past that
+ * `recentlyStreaming` is false at `now`, so the ONLY thing keeping the turn
+ * alive in a `decideOnExpiry` call is the `working` / `humanWaiting` inputs.
+ * Lets us test the "no liveness except the tool" decisions in isolation.
  */
-function shouldSuppressSyntheticTurnEnd(opts: {
-  durationMs: number
-  midToolCall: boolean
-}): boolean {
-  return opts.durationMs === -1 && opts.midToolCall
+function staleTracker(): LivenessTracker {
+  return new LivenessTracker(0)
 }
+const STALE_NOW = W + 10_000 // gap > window → recentlyStreaming false
 
 // ---------------------------------------------------------------------------
 // Tests: ORPHANED_REPLY_MAX_REARMS constant
@@ -66,7 +54,6 @@ describe('ORPHANED_REPLY_MAX_REARMS', () => {
 
   it('combined with ORPHANED_REPLY_TIMEOUT_MS covers at least 10 min of tool activity', () => {
     const coverageMs = ORPHANED_REPLY_MAX_REARMS * ORPHANED_REPLY_TIMEOUT_MS
-    // 20 × 30 000 ms = 600 000 ms = 10 min
     expect(coverageMs).toBeGreaterThanOrEqual(10 * 60 * 1000)
   })
 
@@ -76,165 +63,138 @@ describe('ORPHANED_REPLY_MAX_REARMS', () => {
 })
 
 // ---------------------------------------------------------------------------
-// Tests: PRIMARY fix — re-arm guard
+// Tests: PRIMARY fix — re-arm via decideOnExpiry (REAL tracker)
 // ---------------------------------------------------------------------------
 
-describe('PRIMARY fix: re-arm guard (shouldRearmInsteadOfFire)', () => {
-  it('re-arms when a tool is in flight and rearm count is under the cap', () => {
-    expect(shouldRearmInsteadOfFire({ midToolCall: true, rearmCount: 0, maxRearms: 20 })).toBe(true)
-    expect(shouldRearmInsteadOfFire({ midToolCall: true, rearmCount: 19, maxRearms: 20 })).toBe(true)
+describe('PRIMARY fix: re-arm guard (LivenessTracker.decideOnExpiry)', () => {
+  it('re-arms while working and under the cap (recentlyStreaming false)', () => {
+    const t = staleTracker()
+    const d = t.decideOnExpiry({ working: true, humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX })
+    expect(d).toEqual({ rearm: true, countsAgainstCap: true })
   })
 
-  it('fires once rearm count reaches the cap, even mid-tool-call', () => {
-    expect(shouldRearmInsteadOfFire({ midToolCall: true, rearmCount: 20, maxRearms: 20 })).toBe(false)
-    expect(shouldRearmInsteadOfFire({ midToolCall: true, rearmCount: 21, maxRearms: 20 })).toBe(false)
+  it('fires once the working rearm count reaches the cap (recentlyStreaming false)', () => {
+    const t = staleTracker()
+    let last: { rearm: boolean } | undefined
+    for (let k = 0; k <= MAX; k++) {
+      last = t.decideOnExpiry({ working: true, humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX })
+    }
+    // MAX re-arms proceeded (counter 1..MAX); the (MAX+1)th fires.
+    expect(last!.rearm).toBe(false)
+    expect(t.orphanedReplyRearmCount).toBe(MAX)
   })
 
-  it('fires immediately when no tool is in flight, regardless of rearm count', () => {
-    expect(shouldRearmInsteadOfFire({ midToolCall: false, rearmCount: 0, maxRearms: 20 })).toBe(false)
-    expect(shouldRearmInsteadOfFire({ midToolCall: false, rearmCount: 5, maxRearms: 20 })).toBe(false)
+  it('fires immediately when nothing keeps the turn alive (idle, not recently streaming)', () => {
+    const t = staleTracker()
+    const d = t.decideOnExpiry({ working: false, humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX })
+    expect(d).toEqual({ rearm: false, countsAgainstCap: false })
   })
 
-  it('rearm count transitions: 0 → cap-1 → cap fires', () => {
-    const max = ORPHANED_REPLY_MAX_REARMS
-    for (let i = 0; i < max; i++) {
-      expect(shouldRearmInsteadOfFire({ midToolCall: true, rearmCount: i, maxRearms: max })).toBe(true)
-    }
-    // At exactly the cap: fire
-    expect(shouldRearmInsteadOfFire({ midToolCall: true, rearmCount: max, maxRearms: max })).toBe(false)
+  it('re-arms while recently streaming even when NOT working (thinking-pause survival)', () => {
+    const t = new LivenessTracker(0)
+    t.onStreamEvent('text', undefined, 0)
+    const d = t.decideOnExpiry({ working: false, humanWaiting: false, now: 30_000, windowMs: W, maxRearms: MAX })
+    expect(d).toEqual({ rearm: true, countsAgainstCap: true })
   })
 })
 
 // ---------------------------------------------------------------------------
-// Tests: DEFENSIVE fix — synthetic turn_end suppressor
+// Tests: DEFENSIVE fix — recentlyStreaming keeps the synthetic turn_end at bay
 // ---------------------------------------------------------------------------
 
-describe('DEFENSIVE fix: synthetic turn_end suppressor', () => {
-  it('suppresses a synthetic turn_end (durationMs === -1) when tools are in flight', () => {
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: -1, midToolCall: true })).toBe(true)
-  })
-
-  it('does NOT suppress a synthetic turn_end when no tools are in flight', () => {
-    // No tools → the backstop should fire normally (turn is genuinely orphaned)
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: -1, midToolCall: false })).toBe(false)
+describe('DEFENSIVE fix: recentlyStreaming suppression window', () => {
+  it('is true within the window of the last genuine stream event', () => {
+    const t = new LivenessTracker(0)
+    t.onStreamEvent('tool_use', undefined, 5_000)
+    expect(t.recentlyStreaming(5_000, W)).toBe(true)
+    expect(t.recentlyStreaming(5_000 + W - 1, W)).toBe(true)
   })
 
-  it('does NOT suppress an authoritative turn_end (durationMs >= 0)', () => {
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: 0, midToolCall: true })).toBe(false)
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: 1, midToolCall: true })).toBe(false)
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: 12345, midToolCall: true })).toBe(false)
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: 0, midToolCall: false })).toBe(false)
+  it('is false once the window lapses (genuine hang, teardown proceeds)', () => {
+    const t = new LivenessTracker(0)
+    t.onStreamEvent('tool_use', undefined, 5_000)
+    expect(t.recentlyStreaming(5_000 + W, W)).toBe(false)
   })
 
-  it('only durationMs === -1 is the synthetic discriminator', () => {
-    // Values near -1 must not accidentally trigger suppression
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: -2, midToolCall: true })).toBe(false)
-    expect(shouldSuppressSyntheticTurnEnd({ durationMs: -0.5, midToolCall: true })).toBe(false)
+  it('a synthetic turn_end (-1) does not extend the window', () => {
+    const t = new LivenessTracker(0)
+    t.onStreamEvent('tool_use', undefined, 5_000)
+    t.onStreamEvent('turn_end', -1, 5_500) // ignored
+    expect(t.lastStreamEventAt).toBe(5_000)
+    expect(t.recentlyStreaming(5_000 + W, W)).toBe(false)
   })
 })
 
 // ---------------------------------------------------------------------------
-// Tests: ToolFlightTracker integration with the guard logic
+// Tests: ToolFlightTracker → working input → decideOnExpiry
 // ---------------------------------------------------------------------------
 
-describe('ToolFlightTracker + guard integration', () => {
-  it('re-arm fires when a Bash tool is in flight', () => {
-    const tracker = new ToolFlightTracker()
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'bash_1' })
-
-    expect(shouldRearmInsteadOfFire({
-      midToolCall: tracker.isMidToolCall(),
-      rearmCount: 0,
-      maxRearms: ORPHANED_REPLY_MAX_REARMS,
-    })).toBe(true)
-  })
-
-  it('fires normally after tool_result completes the tool', () => {
-    const tracker = new ToolFlightTracker()
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'bash_1' })
-    tracker.onEvent({ kind: 'tool_result', toolUseId: 'bash_1' })
-
-    expect(shouldRearmInsteadOfFire({
-      midToolCall: tracker.isMidToolCall(),
-      rearmCount: 0,
-      maxRearms: ORPHANED_REPLY_MAX_REARMS,
-    })).toBe(false)
-  })
-
-  it('defensive guard suppresses synthetic turn_end mid-Bash', () => {
-    const tracker = new ToolFlightTracker()
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'bash_2' })
-
-    expect(shouldSuppressSyntheticTurnEnd({
-      durationMs: -1,
-      midToolCall: tracker.isMidToolCall(),
-    })).toBe(true)
-  })
-
-  it('defensive guard allows synthetic turn_end after all tools complete', () => {
-    const tracker = new ToolFlightTracker()
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'bash_2' })
-    tracker.onEvent({ kind: 'tool_result', toolUseId: 'bash_2' })
-
-    expect(shouldSuppressSyntheticTurnEnd({
-      durationMs: -1,
-      midToolCall: tracker.isMidToolCall(),
-    })).toBe(false)
+describe('ToolFlightTracker drives the `working` input', () => {
+  it('re-arm fires when a Bash tool is in flight (working=true)', () => {
+    const flight = new ToolFlightTracker()
+    flight.onEvent({ kind: 'tool_use', toolUseId: 'bash_1' })
+    const t = staleTracker()
+    const d = t.decideOnExpiry({
+      working: flight.isMidToolCall(),
+      humanWaiting: false,
+      now: STALE_NOW,
+      windowMs: W,
+      maxRearms: MAX,
+    })
+    expect(d.rearm).toBe(true)
+  })
+
+  it('fires normally after tool_result completes the tool (working=false, not recently streaming)', () => {
+    const flight = new ToolFlightTracker()
+    flight.onEvent({ kind: 'tool_use', toolUseId: 'bash_1' })
+    flight.onEvent({ kind: 'tool_result', toolUseId: 'bash_1' })
+    const t = staleTracker()
+    const d = t.decideOnExpiry({
+      working: flight.isMidToolCall(),
+      humanWaiting: false,
+      now: STALE_NOW,
+      windowMs: W,
+      maxRearms: MAX,
+    })
+    expect(d.rearm).toBe(false)
   })
 
   it('parallel tools: re-arm persists while ANY tool is in flight', () => {
-    const tracker = new ToolFlightTracker()
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'read_1' })
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'read_2' })
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'edit_1' })
-
-    // Still re-arming: 3 tools open
-    expect(shouldRearmInsteadOfFire({
-      midToolCall: tracker.isMidToolCall(),
-      rearmCount: 0,
-      maxRearms: ORPHANED_REPLY_MAX_REARMS,
-    })).toBe(true)
-
-    // Two complete
-    tracker.onEvent({ kind: 'tool_result', toolUseId: 'read_1' })
-    tracker.onEvent({ kind: 'tool_result', toolUseId: 'read_2' })
-
-    // Still re-arming: edit_1 open
-    expect(shouldRearmInsteadOfFire({
-      midToolCall: tracker.isMidToolCall(),
-      rearmCount: 1,
-      maxRearms: ORPHANED_REPLY_MAX_REARMS,
-    })).toBe(true)
+    const flight = new ToolFlightTracker()
+    flight.onEvent({ kind: 'tool_use', toolUseId: 'read_1' })
+    flight.onEvent({ kind: 'tool_use', toolUseId: 'read_2' })
+    flight.onEvent({ kind: 'tool_use', toolUseId: 'edit_1' })
+    const t = staleTracker()
+    expect(
+      t.decideOnExpiry({ working: flight.isMidToolCall(), humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX }).rearm,
+    ).toBe(true)
 
-    // All complete
-    tracker.onEvent({ kind: 'tool_result', toolUseId: 'edit_1' })
+    flight.onEvent({ kind: 'tool_result', toolUseId: 'read_1' })
+    flight.onEvent({ kind: 'tool_result', toolUseId: 'read_2' })
+    expect(
+      t.decideOnExpiry({ working: flight.isMidToolCall(), humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX }).rearm,
+    ).toBe(true) // edit_1 still open
 
-    expect(shouldRearmInsteadOfFire({
-      midToolCall: tracker.isMidToolCall(),
-      rearmCount: 2,
-      maxRearms: ORPHANED_REPLY_MAX_REARMS,
-    })).toBe(false)
+    flight.onEvent({ kind: 'tool_result', toolUseId: 'edit_1' })
+    const t2 = staleTracker() // fresh so the earlier rearms don't confound the cap
+    expect(
+      t2.decideOnExpiry({ working: flight.isMidToolCall(), humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX }).rearm,
+    ).toBe(false) // all complete, not recently streaming → fire
   })
 
   it('cap fires even mid-tool after 20 re-arms (wedged tool surfaces)', () => {
-    const tracker = new ToolFlightTracker()
-    tracker.onEvent({ kind: 'tool_use', toolUseId: 'hung_bash' })
-
-    // First 20 re-arms proceed
-    for (let i = 0; i < ORPHANED_REPLY_MAX_REARMS; i++) {
-      expect(shouldRearmInsteadOfFire({
-        midToolCall: tracker.isMidToolCall(),
-        rearmCount: i,
-        maxRearms: ORPHANED_REPLY_MAX_REARMS,
-      })).toBe(true)
+    const flight = new ToolFlightTracker()
+    flight.onEvent({ kind: 'tool_use', toolUseId: 'hung_bash' })
+    const t = staleTracker()
+    for (let i = 0; i < MAX; i++) {
+      expect(
+        t.decideOnExpiry({ working: flight.isMidToolCall(), humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX }).rearm,
+      ).toBe(true)
     }
-
-    // 21st: cap exceeded — fire despite in-flight
-    expect(shouldRearmInsteadOfFire({
-      midToolCall: tracker.isMidToolCall(),
-      rearmCount: ORPHANED_REPLY_MAX_REARMS,
-      maxRearms: ORPHANED_REPLY_MAX_REARMS,
-    })).toBe(false)
+    // Cap exceeded — fire despite in-flight.
+    expect(
+      t.decideOnExpiry({ working: flight.isMidToolCall(), humanWaiting: false, now: STALE_NOW, windowMs: W, maxRearms: MAX }).rearm,
+    ).toBe(false)
   })
 })
 

package/telegram-plugin/tests/quota-watch.test.ts

@@ -696,12 +696,11 @@ import {
 } from "../quota-watch.js";
 
 describe("resolveQuotaWatchTuning", () => {
-  it("defaults: stale gate 60min, late-recovery 6h, dedup on, probe-fail send off", () => {
+  it("defaults: stale gate 60min, late-recovery 6h, dedup on", () => {
     const t = resolveQuotaWatchTuning({});
     expect(t.maxStaleMs).toBe(DEFAULT_QUOTA_WATCH_MAX_STALE_MS);
     expect(t.lateRecoveryMs).toBe(DEFAULT_QUOTA_WATCH_LATE_RECOVERY_MS);
     expect(t.fleetDedup).toBe(true);
-    expect(t.sendOnProbeFail).toBe(false);
   });
 
   it("each knob is individually kill-switchable", () => {
@@ -709,12 +708,10 @@ describe("resolveQuotaWatchTuning", () => {
       SWITCHROOM_QUOTA_WATCH_MAX_STALE_MS: "0",
       SWITCHROOM_QUOTA_WATCH_LATE_RECOVERY_MS: "0",
       SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP: "0",
-      SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL: "1",
     });
     expect(t.maxStaleMs).toBe(0);
     expect(t.lateRecoveryMs).toBe(0);
     expect(t.fleetDedup).toBe(false);
-    expect(t.sendOnProbeFail).toBe(true);
   });
 
   it("garbage numeric values fall back to defaults", () => {

package/telegram-plugin/tests/rapid-fire-delivery-ordering.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  decideInboundDelivery,
+  reserveInboundDelivery,
+} from '../gateway/inbound-delivery-gate.js'
+
+/**
+ * #2917 — rapid-fire DM: replies emitted late & out of order.
+ *
+ * Root cause: the #1556 delivery gate is documented as a LIVE read
+ * ("evaluated at delivery time — not a receipt-time snapshot"), but on the
+ * concurrent `handleInbound` path the gate decision and the busy-mark that
+ * records "a turn is in flight for this chat" were separated by an `await`
+ * (attachment download, composer-clear). Two same-chat inbounds each read
+ * "idle" during the other's async lead-in, both passed the gate, and both
+ * were delivered to the bridge — so the replies came back reordered.
+ *
+ * The fix couples the deliver decision with a synchronous RESERVE
+ * (`reserveInboundDelivery`): a fresh-turn deliver reserves the chat's busy
+ * key BEFORE any await, so a concurrent same-chat inbound observes the
+ * reservation on the live gate and buffers behind it — restoring per-chat
+ * FIFO without dropping anything (a buffered inbound drains on turn-complete
+ * / idle exactly as before).
+ */
+describe('reserveInboundDelivery — fresh-turn reservation flag', () => {
+  it('reserves a fresh-turn deliver (idle, non-steering, non-interrupt)', () => {
+    const r = reserveInboundDelivery({ turnInFlight: false, isSteering: false, isInterrupt: false })
+    expect(r.decision).toBe('deliver')
+    expect(r.reserve).toBe(true)
+  })
+
+  it('does NOT reserve a buffered (mid-turn) inbound', () => {
+    const r = reserveInboundDelivery({ turnInFlight: true, isSteering: false, isInterrupt: false })
+    expect(r.decision).toBe('buffer-until-idle')
+    expect(r.reserve).toBe(false)
+  })
+
+  it('does NOT reserve a steering deliver (amends the running turn)', () => {
+    const r = reserveInboundDelivery({ turnInFlight: true, isSteering: true, isInterrupt: false })
+    expect(r.decision).toBe('deliver')
+    expect(r.reserve).toBe(false)
+  })
+
+  it('does NOT reserve an interrupt deliver (amends the running turn)', () => {
+    const r = reserveInboundDelivery({ turnInFlight: true, isSteering: false, isInterrupt: true })
+    expect(r.decision).toBe('deliver')
+    expect(r.reserve).toBe(false)
+  })
+
+  it('decision stays byte-identical to decideInboundDelivery across the matrix', () => {
+    for (const turnInFlight of [false, true]) {
+      for (const isSteering of [false, true]) {
+        for (const isInterrupt of [false, true]) {
+          const input = { turnInFlight, isSteering, isInterrupt }
+          expect(reserveInboundDelivery(input).decision).toBe(decideInboundDelivery(input))
+        }
+      }
+    }
+  })
+})
+
+/**
+ * A minimal model of the gateway's concurrent same-chat delivery path. Each
+ * inbound handler:
+ *   1. reads the LIVE gate off the shared busy set,
+ *   2. yields at an `await` (the composer-clear / attachment lead-in),
+ *   3. on a reserving deliver, marks the chat busy and appends to the wire.
+ *
+ * This reproduces the ordering race deterministically: two same-chat handlers
+ * whose async lead-ins overlap. The `syncReserve` flag toggles the fix — when
+ * off (legacy: mark busy only AFTER the await), both handlers deliver and the
+ * wire order is decided by the await race; when on (#2917: reserve BEFORE the
+ * await), the second handler sees the reservation and buffers, preserving FIFO.
+ */
+interface WireResult {
+  delivered: string[]
+  buffered: string[]
+}
+
+async function runTwoConcurrentInbounds(opts: {
+  syncReserve: boolean
+  /** ms the first handler's lead-in await takes vs the second's. First is
+   *  SLOWER so, without the fix, the second overtakes it on the wire. */
+  firstLeadInMs: number
+  secondLeadInMs: number
+}): Promise<WireResult> {
+  const busy = new Set<string>()
+  const key = 'chatDM:_'
+  const delivered: string[] = []
+  const buffered: string[] = []
+
+  const handle = async (id: string, leadInMs: number): Promise<void> => {
+    // Step 1 — live gate read.
+    const gate = reserveInboundDelivery({
+      turnInFlight: busy.size > 0,
+      isSteering: false,
+      isInterrupt: false,
+    })
+    if (gate.decision === 'buffer-until-idle') {
+      buffered.push(id)
+      return
+    }
+    // Step 2 — the fix reserves synchronously BEFORE the await.
+    let reserved = false
+    if (opts.syncReserve && gate.reserve) {
+      busy.add(key)
+      reserved = true
+    }
+    // Step 3 — the async lead-in (composer-clear / attachment download).
+    await new Promise((r) => setTimeout(r, leadInMs))
+    // Step 4 — legacy marks busy only now, after the await.
+    if (!reserved) busy.add(key)
+    delivered.push(id)
+  }
+
+  await Promise.all([
+    handle('msg1', opts.firstLeadInMs),
+    handle('msg2', opts.secondLeadInMs),
+  ])
+  return { delivered, buffered }
+}
+
+describe('rapid-fire same-chat delivery ordering (#2917)', () => {
+  it('LEGACY (mark-after-await): the faster second inbound overtakes the first — reorder', async () => {
+    // msg1's lead-in is slower, so with the busy-mark deferred until after the
+    // await BOTH pass the idle gate and BOTH deliver, with msg2 landing first.
+    const { delivered, buffered } = await runTwoConcurrentInbounds({
+      syncReserve: false,
+      firstLeadInMs: 20,
+      secondLeadInMs: 1,
+    })
+    expect(buffered).toEqual([]) // nothing buffered — the bug
+    expect(delivered).toEqual(['msg2', 'msg1']) // out of order
+  })
+
+  it('FIX (sync reserve): the second inbound sees the reservation and buffers — FIFO preserved', async () => {
+    const { delivered, buffered } = await runTwoConcurrentInbounds({
+      syncReserve: true,
+      firstLeadInMs: 20,
+      secondLeadInMs: 1,
+    })
+    // msg1 reserved synchronously; msg2's live gate sees busy → buffers.
+    expect(delivered).toEqual(['msg1'])
+    expect(buffered).toEqual(['msg2'])
+    // msg2 is not lost — it is held for the turn-complete / idle drain, which
+    // re-delivers it in order after msg1's turn ends.
+  })
+})