switchroom 0.17.10 → 0.18.6

package/telegram-plugin/tests/quota-bar-format.test.ts

@@ -0,0 +1,444 @@
+/**
+ * Tests for quota-bar-format.ts — bar-building, time-left formatting, and
+ * the full block assembly. Pure functions, frozen-clock fixtures.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  pickDot,
+  formatTimeLeft,
+  elapsedFraction,
+  buildBar,
+  accountStatus,
+  formatWindowRow,
+  renderQuotaBarAccount,
+  renderQuotaBarBlockFromListState,
+  renderUsageCard,
+} from '../quota-bar-format.js';
+import type { AccountSnapshot } from '../auth-snapshot-format.js';
+import type { QuotaUtilization } from '../quota-check.js';
+import type { ListStateData } from '../../src/auth/broker/client.js';
+
+const NOW = new Date('2026-07-10T00:00:00.000Z');
+
+function quota(part: Partial<QuotaUtilization>): QuotaUtilization {
+  return {
+    fiveHourUtilizationPct: 0,
+    sevenDayUtilizationPct: 0,
+    fiveHourResetAt: null,
+    sevenDayResetAt: null,
+    representativeClaim: null,
+    overageStatus: null,
+    overageDisabledReason: null,
+    ...part,
+  };
+}
+
+// ── pickDot ──────────────────────────────────────────────────────────
+
+describe('pickDot', () => {
+  it('green under 50%', () => {
+    expect(pickDot(0)).toBe('🟢');
+    expect(pickDot(49)).toBe('🟢');
+  });
+  it('yellow 50-89%', () => {
+    expect(pickDot(50)).toBe('🟡');
+    expect(pickDot(89)).toBe('🟡');
+  });
+  it('red 90%+', () => {
+    expect(pickDot(90)).toBe('🔴');
+    expect(pickDot(100)).toBe('🔴');
+  });
+});
+
+// ── formatTimeLeft ───────────────────────────────────────────────────
+
+describe('formatTimeLeft', () => {
+  it('returns "resets now" when the target is null', () => {
+    expect(formatTimeLeft(null, NOW)).toBe('resets now');
+  });
+  it('returns "resets now" when the target has already passed', () => {
+    expect(formatTimeLeft(new Date(NOW.getTime() - 1000), NOW)).toBe('resets now');
+  });
+  it('returns "resets now" when the target is exactly now', () => {
+    expect(formatTimeLeft(new Date(NOW.getTime()), NOW)).toBe('resets now');
+  });
+  it('formats sub-hour deltas as minutes', () => {
+    expect(formatTimeLeft(new Date(NOW.getTime() + 45 * 60_000), NOW)).toBe('45m left');
+  });
+  it('formats sub-day deltas as compact hours+minutes', () => {
+    expect(formatTimeLeft(new Date(NOW.getTime() + (4 * 60 + 20) * 60_000), NOW)).toBe('4h20m left');
+  });
+  it('formats multi-day deltas as compact days+hours', () => {
+    expect(formatTimeLeft(new Date(NOW.getTime() + (3 * 24 + 1) * 60 * 60_000), NOW)).toBe('3d1h left');
+  });
+  it('drops the hours segment when exactly on a day boundary', () => {
+    expect(formatTimeLeft(new Date(NOW.getTime() + 2 * 24 * 60 * 60_000), NOW)).toBe('2d left');
+  });
+  it('returns "resets now" (never "NaNm left") for an invalid reset date', () => {
+    expect(formatTimeLeft(new Date('not-a-date'), NOW)).toBe('resets now');
+    expect(formatTimeLeft(new Date(NaN), NOW)).toBe('resets now');
+  });
+});
+
+// ── elapsedFraction ──────────────────────────────────────────────────
+
+describe('elapsedFraction', () => {
+  const fiveHourMs = 5 * 60 * 60 * 1000;
+  it('is 0 when there is no reset timestamp', () => {
+    expect(elapsedFraction(null, fiveHourMs, NOW)).toBe(0);
+  });
+  it('is 0 when the reset has already passed', () => {
+    expect(elapsedFraction(new Date(NOW.getTime() - 1000), fiveHourMs, NOW)).toBe(0);
+  });
+  it('is close to 1 just before reset', () => {
+    const frac = elapsedFraction(new Date(NOW.getTime() + 60_000), fiveHourMs, NOW);
+    expect(frac).toBeGreaterThan(0.99);
+    expect(frac).toBeLessThanOrEqual(1);
+  });
+  it('is ~0.5 halfway through the window', () => {
+    const frac = elapsedFraction(new Date(NOW.getTime() + fiveHourMs / 2), fiveHourMs, NOW);
+    expect(frac).toBeCloseTo(0.5, 5);
+  });
+  it('is 0 (never NaN) for an invalid reset date', () => {
+    expect(elapsedFraction(new Date('not-a-date'), fiveHourMs, NOW)).toBe(0);
+    expect(elapsedFraction(new Date(NaN), fiveHourMs, NOW)).toBe(0);
+  });
+});
+
+// ── buildBar ─────────────────────────────────────────────────────────
+
+describe('buildBar', () => {
+  it('is all empty cells with a tick at 0% pct and 0 elapsed fraction', () => {
+    expect(buildBar(0, 0)).toBe('┃░░░░░░░░░');
+  });
+  it('the tick always overrides the fill, even at 100% pct', () => {
+    expect(buildBar(100, 0.5)).toBe('█████┃████');
+  });
+  it('the tick overrides fill at the very last cell (100% pct, 100% elapsed)', () => {
+    expect(buildBar(100, 1)).toBe('█████████┃');
+  });
+  it('is exactly 10 characters for any pct/fraction combination', () => {
+    for (const pct of [0, 1, 33, 47, 89, 99, 100]) {
+      for (const frac of [0, 0.25, 0.5, 0.75, 1]) {
+        expect(buildBar(pct, frac).length).toBe(10);
+      }
+    }
+  });
+  it('places the tick outside the filled region when there is room', () => {
+    // 20% filled (2 cells) + tick at fraction 0.8 → tick lands past the fill.
+    const bar = buildBar(20, 0.8);
+    expect(bar[0]).toBe('█');
+    expect(bar[1]).toBe('█');
+    expect(bar).toContain('┃');
+  });
+  it('over-pace: quota fill visibly punches through past the time-elapsed tick', () => {
+    // 80% quota used, only 30% of the way through the window — burning
+    // faster than the clock. Fill (8 cells) extends past the tick
+    // (index round(0.3*9)=3), so filled cells appear on BOTH sides of the
+    // tick — that's the "punch through" signal the operator asked for.
+    const bar = buildBar(80, 0.3);
+    expect(bar).toBe('███┃████░░');
+    const tickIndex = bar.indexOf('┃');
+    const filledAfterTick = bar.slice(tickIndex + 1).includes('█');
+    expect(filledAfterTick).toBe(true); // fill visibly overtakes the pace marker
+  });
+});
+
+// ── accountStatus ────────────────────────────────────────────────────
+
+describe('accountStatus', () => {
+  it('active wins even if the broker also flags the account exhausted', () => {
+    expect(accountStatus(true, true)).toBe('active');
+  });
+  it('reports exhausted for a non-active exhausted account', () => {
+    expect(accountStatus(false, true)).toBe('exhausted');
+  });
+  it('reports idle for a non-active, non-exhausted account', () => {
+    expect(accountStatus(false, false)).toBe('idle');
+  });
+});
+
+// ── formatWindowRow / renderQuotaBarAccount ─────────────────────────
+
+describe('formatWindowRow', () => {
+  it('renders the locked row shape', () => {
+    const row = formatWindowRow('5h', 0, null, NOW);
+    expect(row).toBe('- 🟢 5h `[┃░░░░░░░░░] 0% / resets now`');
+  });
+  it('clamps a >100% probe value for display', () => {
+    const row = formatWindowRow('7d', 101, null, NOW);
+    expect(row).toContain('100%');
+  });
+});
+
+describe('renderQuotaBarAccount', () => {
+  it('renders a title line + two window rows', () => {
+    const q = quota({
+      fiveHourUtilizationPct: 0,
+      sevenDayUtilizationPct: 47,
+      sevenDayResetAt: new Date(NOW.getTime() + (3 * 24 + 1) * 60 * 60_000),
+    });
+    const lines = renderQuotaBarAccount('ken@example.com', true, false, q, NOW);
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toBe('- **ken@example.com** (active)');
+    expect(lines[1]).toBe('- 🟢 5h `[┃░░░░░░░░░] 0% / resets now`');
+    expect(lines[2]).toContain('🟢 7d');
+    expect(lines[2]).toContain('47% / 3d1h left');
+  });
+  it('escapes markdown-significant characters in the label (bold run, not a code span)', () => {
+    // Regression: the title line wraps label in **bold**, so a label
+    // containing `**` or `[...]` must be backslash-escaped (escapeMarkdown),
+    // not defused with codeSpanSafe (which only strips backticks and would
+    // leave `*`/`[`/`]` live, breaking the bold run or injecting a link).
+    const lines = renderQuotaBarAccount('a**b[x](evil)_c', false, false, null, NOW);
+    expect(lines[0]).toBe('- **a\\*\\*b\\[x\\](evil)\\_c** (idle)');
+  });
+  it('exhausted account at 0% utilization on both windows still shows exhausted status with healthy dots', () => {
+    const q = quota({ fiveHourUtilizationPct: 0, sevenDayUtilizationPct: 0 });
+    const lines = renderQuotaBarAccount('done@example.com', false, true, q, NOW);
+    expect(lines[0]).toBe('- **done@example.com** (exhausted)');
+    expect(lines[1]).toContain('🟢 5h');
+    expect(lines[2]).toContain('🟢 7d');
+  });
+  it('renders a distinct probe-failed warning (never a healthy green 0% bar) when quota is null', () => {
+    // #2959 blocking bug: a failed probe must NOT be indistinguishable from a
+    // fresh account with full headroom (🟢 0%). It must carry a ⚠️ glyph and a
+    // "no data" label, with no green dot and no fake 0% bar.
+    const lines = renderQuotaBarAccount('nobody@example.com', false, false, null, NOW);
+    expect(lines).toEqual([
+      '- **nobody@example.com** (idle)',
+      '- ⚠️ 5h `no data — probe failed`',
+      '- ⚠️ 7d `no data — probe failed`',
+    ]);
+    const body = lines.join('\n');
+    expect(body).not.toContain('🟢');
+    expect(body).not.toContain('0%');
+  });
+
+  it('renders a distinct thin-probe warning (never a healthy green 0% bar) when the probe is thin', () => {
+    // A thin/headerless probe carries no real utilization — must degrade to the
+    // same ⚠️ data-quality gap, not a confident 🟢 0%.
+    const thin = quota({ fiveHourUtilPresent: false, sevenDayUtilPresent: false });
+    const lines = renderQuotaBarAccount('thin@example.com', false, false, thin, NOW);
+    expect(lines).toEqual([
+      '- **thin@example.com** (idle)',
+      '- ⚠️ 5h `no data — thin probe`',
+      '- ⚠️ 7d `no data — thin probe`',
+    ]);
+    expect(lines.join('\n')).not.toContain('🟢');
+  });
+});
+
+// ── renderQuotaBarBlockFromListState ────────────────────────────────
+
+describe('renderQuotaBarBlockFromListState', () => {
+  it('renders the locked multi-account block shape', () => {
+    const state: ListStateData = {
+      active: 'ken@example.com',
+      fallback_order: ['ken@example.com', 'alt@example.com'],
+      accounts: [
+        {
+          label: 'ken@example.com',
+          exhausted: false,
+          last_quota: {
+            fiveHourUtilizationPct: 0,
+            sevenDayUtilizationPct: 47,
+            fiveHourResetAt: new Date(NOW.getTime() + 60_000).toISOString(),
+            sevenDayResetAt: new Date(NOW.getTime() + (3 * 24 + 1) * 60 * 60_000).toISOString(),
+            representativeClaim: null,
+            overageStatus: null,
+            overageDisabledReason: null,
+            capturedAt: NOW.getTime(),
+          },
+        },
+        {
+          label: 'alt@example.com',
+          exhausted: true,
+          last_quota: {
+            fiveHourUtilizationPct: 0,
+            sevenDayUtilizationPct: 100,
+            fiveHourResetAt: new Date(NOW.getTime() - 60_000).toISOString(),
+            sevenDayResetAt: new Date(NOW.getTime() + 2 * 24 * 60 * 60_000 + 16 * 60 * 60_000).toISOString(),
+            representativeClaim: null,
+            overageStatus: null,
+            overageDisabledReason: null,
+            capturedAt: NOW.getTime(),
+          },
+        },
+      ],
+      agents: [],
+      consumers: [],
+    };
+    const block = renderQuotaBarBlockFromListState(state, { now: NOW });
+    const lines = block.split('\n');
+    expect(lines).toEqual([
+      '- **ken@example.com** (active)',
+      '- 🟢 5h `[░░░░░░░░░┃] 0% / 1m left`',
+      '- 🟢 7d `[█████┃░░░░] 47% / 3d1h left`',
+      '- **alt@example.com** (exhausted)',
+      '- 🟢 5h `[┃░░░░░░░░░] 0% / resets now`',
+      '- 🔴 7d `[██████┃███] 100% / 2d16h left`',
+    ]);
+  });
+});
+
+// ── renderUsageCard (bar block only — /usage no longer appends the ─────
+// Format 2 table underneath; see gateway.ts's `bot.command('usage', ...)`)
+
+describe('renderUsageCard', () => {
+  function snap(part: Partial<AccountSnapshot> & { label: string }): AccountSnapshot {
+    return {
+      isActive: false,
+      quota: null,
+      ...part,
+    };
+  }
+
+  const snapshots: AccountSnapshot[] = [
+    snap({
+      label: 'ken@example.com',
+      isActive: true,
+      quota: quota({
+        fiveHourUtilizationPct: 0,
+        sevenDayUtilizationPct: 47,
+        fiveHourResetAt: new Date(NOW.getTime() + 60 * 60_000),
+        sevenDayResetAt: new Date(NOW.getTime() + (3 * 24 + 1) * 60 * 60_000),
+      }),
+    }),
+  ];
+  const exhausted = new Map<string, boolean>([['ken@example.com', false]]);
+
+  it('renders the quota-bar block plus a recommendation + freshness footer — no Format 2 table', () => {
+    const out = renderUsageCard(snapshots, exhausted, { now: NOW });
+    const lines = out.split('\n');
+    // Bar block — account title + two window rows with the ASCII bar.
+    expect(lines[0]).toBe('- **ken@example.com** (active)');
+    expect(out).toContain('- 🟢 5h `[');
+    expect(out).toContain('- 🟢 7d `[');
+    // Reset info is carried by the bar rows themselves (relative
+    // time-left), not a separate table.
+    expect(out).toContain('1h0m left');
+    expect(out).toContain('left');
+    // The old Format 2 TABLE must be fully gone from this card.
+    expect(out).not.toContain('🔋 **Auth — fleet status**');
+    expect(out).not.toContain('| State | Account | 5h | 5h resets | 7d | 7d resets |');
+    // ...but the actionable recommendation footer is RESTORED (#2959 review).
+    expect(out).toContain('Recommendation: stay on ken@example.com.');
+    // Freshness marker present (no stamp supplied → bare "Live").
+    expect(lines[lines.length - 1]).toBe('_Live_');
+    // 3 bar lines + recommendation + freshness = 5.
+    expect(lines).toHaveLength(5);
+  });
+
+  it('restores the "switch now" recommendation footer for a BLOCKED active account', () => {
+    // Matches the old renderAuthSnapshotFormat2 / recommendation() logic: an
+    // active account maxed on a window, with a healthy alternative, yields the
+    // most actionable line — "switch to Y now".
+    const blocked: AccountSnapshot[] = [
+      snap({
+        label: 'active@example.com',
+        isActive: true,
+        quota: quota({ fiveHourUtilizationPct: 100, sevenDayUtilizationPct: 100 }),
+      }),
+      snap({
+        label: 'healthy@example.com',
+        isActive: false,
+        quota: quota({ fiveHourUtilizationPct: 5, sevenDayUtilizationPct: 10 }),
+      }),
+    ];
+    const ex = new Map<string, boolean>([
+      ['active@example.com', true],
+      ['healthy@example.com', false],
+    ]);
+    const out = renderUsageCard(blocked, ex, { now: NOW });
+    expect(out).toContain(
+      '_Recommendation: active active@example.com is BLOCKED — switch to healthy@example.com now._',
+    );
+  });
+
+  it('shows a "⚠ cached Nm ago" marker for stale-cache-served data instead of a live stamp', () => {
+    const out = renderUsageCard(snapshots, exhausted, {
+      now: NOW,
+      staleCachedAtMs: NOW.getTime() - 3 * 60_000,
+    });
+    const lines = out.split('\n');
+    expect(lines[lines.length - 1]).toBe('_⚠ cached 3m ago_');
+    expect(out).not.toContain('_Live');
+  });
+
+  it('shows a "Live · refreshed" stamp when the probe was live', () => {
+    const out = renderUsageCard(snapshots, exhausted, {
+      now: NOW,
+      liveProbedAtMs: NOW.getTime() - 5_000,
+    });
+    const lines = out.split('\n');
+    expect(lines[lines.length - 1]).toBe('_Live · refreshed 5s ago_');
+    expect(out).not.toContain('cached');
+  });
+
+  it('stale-cache marker takes precedence over a live stamp when both are supplied', () => {
+    const out = renderUsageCard(snapshots, exhausted, {
+      now: NOW,
+      staleCachedAtMs: NOW.getTime() - 60_000,
+      liveProbedAtMs: NOW.getTime(),
+    });
+    expect(out.split('\n').pop()).toBe('_⚠ cached 1m ago_');
+  });
+
+  it('probeFailed renders an explicit "probe failed" marker instead of a false "Live" footer (#2959 honesty fix)', () => {
+    // A total probe failure: zero result rows, nothing served from cache.
+    // Every account row renders "⚠️ no data — probe failed"; the footer
+    // must NOT claim "Live". Pre-fix this rendered a bare `_Live_`.
+    const out = renderUsageCard(snapshots, exhausted, { now: NOW, probeFailed: true });
+    expect(out.split('\n').pop()).toBe('_⚠ probe failed — no live data_');
+    expect(out).not.toContain('_Live');
+    expect(out).not.toContain('cached');
+  });
+
+  it('probeFailed does not override real cached data (cache takes precedence)', () => {
+    // If some rows WERE served from cache, there IS real (stale) data —
+    // the cache marker must win over the probe-failed marker.
+    const out = renderUsageCard(snapshots, exhausted, {
+      now: NOW,
+      staleCachedAtMs: NOW.getTime() - 2 * 60_000,
+      probeFailed: true,
+    });
+    expect(out.split('\n').pop()).toBe('_⚠ cached 2m ago_');
+    expect(out).not.toContain('probe failed');
+  });
+
+  it('handles an invalid/NaN reset date without emitting "NaN" or corrupting the bar', () => {
+    const bad: AccountSnapshot[] = [
+      snap({
+        label: 'ken@example.com',
+        isActive: true,
+        quota: quota({
+          fiveHourUtilizationPct: 10,
+          sevenDayUtilizationPct: 20,
+          fiveHourResetAt: new Date('not-a-date'),
+          sevenDayResetAt: new Date(NaN),
+        }),
+      }),
+    ];
+    const out = renderUsageCard(bad, exhausted, { now: NOW });
+    expect(out).not.toContain('NaN');
+    // Malformed reset → treated as "resets now", tick at index 0.
+    expect(out).toContain('/ resets now`');
+    for (const line of out.split('\n')) {
+      const m = line.match(/\[(.+?)\]/);
+      if (m) expect(m[1].length).toBe(10); // bar stays exactly 10 cells
+    }
+  });
+
+  it('masks the account-email label in demo mode', () => {
+    const out = renderUsageCard(snapshots, exhausted, { now: NOW, demo: true });
+    expect(out).not.toContain('ken@example.com');
+    // Bar rows are unaffected; only the title-line label is masked.
+    expect(out).toContain('5h `[');
+  });
+
+  it('does not mask the label when demo is omitted', () => {
+    const out = renderUsageCard(snapshots, exhausted, { now: NOW });
+    expect(out).toContain('- **ken@example.com** (active)');
+  });
+});

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.
+  })
+})