switchroom 0.20.3 → 0.20.5

package/telegram-plugin/tests/edit-flood-fuse-cosmetic-fairness.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Per-`message_id` cosmetic fair-share (#4300).
+ *
+ * The bug: `cosmeticPerChatMaxPerWindow` (6/60s) is ONE bucket shared across
+ * every cosmetic surface in a chat — the primary activity card, a worker /
+ * sub-agent card, and answer-stream draft edits. Under intra-cosmetic
+ * contention (two live cards) — and especially once a 429 tightens that bucket
+ * — the surface the user is actually watching (the primary activity card) could
+ * be starved well past 60s between frames while the OTHER surface kept
+ * repainting. The fix carves a small AIMD-immune per-message floor OUT OF the
+ * same pool (no new wire rate, so 429 risk is unchanged) so no cosmetic surface
+ * can starve another, and a watched card keeps a minimum cadence under flood.
+ *
+ * These tests assert OUTCOMES (frames that actually reached the API within a
+ * window), not code paths, and pin the behaviour against the kill-switch so a
+ * revert of the core change fails at least one of them.
+ */
+import { describe, it, expect } from 'vitest'
+import { createEditFloodFuse, EDIT_FLOOD_FUSE_DEFAULTS } from '../edit-flood-fuse.js'
+import type { Clock } from '../send-gate.js'
+
+const CHAT = '5005'
+const PRIMARY = 1 // the activity card the user watches
+const WORKER = 2 // a second live cosmetic surface (sub-agent card / draft)
+
+const D = EDIT_FLOOD_FUSE_DEFAULTS
+
+class FakeClock implements Clock {
+  private cur = 0
+  private seq = 0
+  private timers: { at: number; id: number; resolve: () => void }[] = []
+
+  now(): number { return this.cur }
+
+  sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.timers.push({ at: this.cur + ms, id: this.seq++, resolve })
+    })
+  }
+
+  async advance(ms: number): Promise<void> {
+    const target = this.cur + ms
+    for (;;) {
+      await flush()
+      const due = this.timers.filter((t) => t.at <= target).sort((a, b) => a.at - b.at || a.id - b.id)
+      if (due.length === 0) break
+      const t = due[0]!
+      this.timers = this.timers.filter((x) => x !== t)
+      this.cur = t.at
+      t.resolve()
+      await flush()
+    }
+    this.cur = target
+    await flush()
+  }
+}
+
+function flush(): Promise<void> {
+  return new Promise((r) => setImmediate(r))
+}
+
+const flood = () => Object.assign(
+  new Error('Too Many Requests: retry after 3'),
+  { error_code: 429, parameters: { retry_after: 3 } },
+)
+
+/**
+ * Drive `n` observed 429s so the ceilings tighten by `n` AIMD levels. The
+ * probes go to a SEPARATE chat: tightening is global, but a probe still charges
+ * the target chat's shared total window, and we don't want those synthetic
+ * sends to eat into CHAT's tightened cosmetic-total budget under test.
+ */
+async function tighten(fuse: ReturnType<typeof createEditFloodFuse>, n: number): Promise<void> {
+  for (let i = 0; i < n; i++) {
+    await fuse.apply('sendMessage', { chat_id: '9009', text: 'probe' }, async () => { throw flood() })
+      .then(() => { /* unreachable */ }, () => { /* the 429 is re-thrown; swallow */ })
+  }
+}
+
+/**
+ * Run a contention scenario: WORKER repaints densely (every `workerEveryMs`)
+ * and PRIMARY repaints at a heartbeat cadence (every `primaryEveryMs`), both
+ * for `spanMs`. Returns how many frames of each landed strictly inside the
+ * first `perChatWindowMs` window.
+ */
+async function contend(
+  fuse: ReturnType<typeof createEditFloodFuse>, clock: FakeClock,
+  opts: { spanMs: number; workerEveryMs: number; primaryEveryMs: number },
+): Promise<{ primary: number; worker: number }> {
+  const landed: { primary: number; worker: number } = { primary: 0, worker: 0 }
+  const inflight: Promise<unknown>[] = []
+  let nextWorker = 0
+  let nextPrimary = 3_000 // let the worker grab the pool first, as in the real stall
+  const step = 500
+  for (let t = 0; t <= opts.spanMs; t += step) {
+    if (t >= nextWorker) {
+      inflight.push(fuse.apply(
+        'editMessageText', { chat_id: CHAT, message_id: WORKER, text: `w${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) landed.worker++; return true },
+      ))
+      nextWorker += opts.workerEveryMs
+    }
+    if (t >= nextPrimary) {
+      inflight.push(fuse.apply(
+        'editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: `p${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) landed.primary++; return true },
+      ))
+      nextPrimary += opts.primaryEveryMs
+    }
+    await clock.advance(step)
+  }
+  // Drain every still-deferred frame so no promise is left dangling.
+  await clock.advance(D.maxDeferMs + 1_000)
+  await Promise.all(inflight)
+  return landed
+}
+
+describe('#4300 cosmetic fair-share — a watched card is not starved by a second surface', () => {
+  it('(a) under flood tightening the primary card keeps its per-message floor while a worker card repaints', async () => {
+    // One 429 → AIMD level 1: the shared cosmetic pool ceiling(6) shrinks to 3,
+    // which two live cosmetic surfaces would otherwise fight over.
+    const clockOn = new FakeClock()
+    const fuseOn = createEditFloodFuse({ clock: clockOn })
+    await tighten(fuseOn, 1)
+    expect(fuseOn.stats().tightenLevel).toBeGreaterThanOrEqual(1)
+    const on = await contend(fuseOn, clockOn, { spanMs: 58_000, workerEveryMs: 1_000, primaryEveryMs: 6_000 })
+
+    // The invariant: the watched card still repaints at least its guaranteed
+    // floor (cosmeticFloorPerWindow = 2/60s = 1 edit/30s), AIMD-immune, even
+    // though the worker is hammering the same pool.
+    expect(on.primary).toBeGreaterThanOrEqual(D.cosmeticFloorPerWindow)
+  })
+
+  it('(d) mutation guard — with fair-share OFF the SAME scenario starves the primary below the floor', async () => {
+    // Kill-switch OFF is the pre-fix single shared bucket. Reverting the core
+    // change is behaviourally identical to this, so if the fix did nothing the
+    // (a) assertion above would already hold here — it must NOT.
+    const clockOff = new FakeClock()
+    const fuseOff = createEditFloodFuse({ clock: clockOff, cosmeticFairShareEnabled: false })
+    await tighten(fuseOff, 1)
+    const off = await contend(fuseOff, clockOff, { spanMs: 58_000, workerEveryMs: 1_000, primaryEveryMs: 6_000 })
+
+    // No per-message floor: the dense worker wins the shared pool and the
+    // watched card is starved below the floor the fix guarantees.
+    expect(off.primary).toBeLessThan(D.cosmeticFloorPerWindow)
+    expect(fuseOff.stats().cosmeticFairShareEnabled).toBe(false)
+  })
+
+  it('(b) a heavily-tightened pool still lets a lone watched card repaint ≥ 1 edit / 30s (AIMD floor)', async () => {
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({ clock })
+    // Two 429s → level 2: ceiling(6) → 1, so WITHOUT the floor the whole chat's
+    // cosmetic budget would be a single frame per 60s.
+    await tighten(fuse, 2)
+    expect(fuse.stats().tightenLevel).toBeGreaterThanOrEqual(2)
+
+    const landed: number[] = []
+    const inflight: Promise<unknown>[] = []
+    // A watched card's heartbeat: an edit every 5s across a 60s window.
+    for (let i = 0; i < 12; i++) {
+      inflight.push(fuse.apply(
+        'editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: `hb${i}` },
+        async () => { if (clock.now() < D.perChatWindowMs) landed.push(i); return true },
+      ))
+      await clock.advance(5_000)
+    }
+    await clock.advance(1_000)
+    const inWindow = landed.length
+    await clock.advance(D.maxDeferMs + 1_000)
+    await Promise.all(inflight)
+
+    // ≥ 1 edit / 30s = ≥ cosmeticFloorPerWindow (2) per 60s window, guaranteed
+    // no matter how many 429s tighten the pool.
+    expect(inWindow).toBeGreaterThanOrEqual(D.cosmeticFloorPerWindow)
+  })
+
+  it('(c) fair-share OFF is the old single shared bucket — two surfaces share exactly cosmeticPerChatMax, byte-for-byte', async () => {
+    // No tightening: the pre-fix behaviour is that ALL cosmetic surfaces in a
+    // chat draw from one `cosmeticPerChatMaxPerWindow` bucket with no
+    // per-message reservation. Two saturating surfaces therefore land, in
+    // aggregate, exactly the pool — never more (the fix does not raise the wire
+    // rate) and, with the flag off, with no floor keeping either one alive.
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({ clock, cosmeticFairShareEnabled: false })
+    let a = 0
+    let b = 0
+    const inflight: Promise<unknown>[] = []
+    for (let t = 0; t < 58_000; t += 500) {
+      inflight.push(fuse.apply('editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: `a${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) a++; return true }))
+      inflight.push(fuse.apply('editMessageText', { chat_id: CHAT, message_id: WORKER, text: `b${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) b++; return true }))
+      await clock.advance(500)
+    }
+    await clock.advance(D.maxDeferMs + 1_000)
+    await Promise.all(inflight)
+
+    // The single shared bucket: aggregate cosmetic frames == the pool, and the
+    // fair-share machinery is provably not in play.
+    expect(a + b).toBeLessThanOrEqual(D.cosmeticPerChatMaxPerWindow)
+    expect(a + b).toBeGreaterThan(0)
+    expect(fuse.stats().cosmeticFairShareEnabled).toBe(false)
+  })
+
+  it('raises a visible `throttled` signal when a cosmetic edit is deferred past throttleNoticeMs', async () => {
+    const clock = new FakeClock()
+    const actions: string[] = []
+    // Saturate the per-chat cosmetic pool with a DIFFERENT card so the target
+    // edit has to wait; a long defer window lets it cross the notice threshold.
+    const fuse = createEditFloodFuse({
+      clock,
+      cosmeticPerChatMaxPerWindow: 1, cosmeticFloorPerWindow: 0,
+      perChatWindowMs: 600_000, maxDeferMs: 120_000, throttleNoticeMs: 45_000,
+      onTrip: (i) => { actions.push(i.action) },
+    })
+    // Burn the pool.
+    await fuse.apply('editMessageText', { chat_id: CHAT, message_id: WORKER, text: 'hog' },
+      async () => true)
+    // The watched card's frame cannot get in; it sits deferred.
+    const stuck = fuse.apply('editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: 'watched' },
+      async () => true)
+    await clock.advance(46_000)
+    expect(fuse.stats().throttled).toBeGreaterThan(0)
+    expect(actions).toContain('throttled')
+    // Drain.
+    await clock.advance(120_000)
+    await stuck
+  })
+})

package/telegram-plugin/tests/feed-open-gate.test.ts

@@ -179,6 +179,48 @@ describe('mayOpenActivityCard — lever 1 exception: post-answer sub-agent liven
   })
 })
 
+describe('mayOpenActivityCard — lever 1 exception: post-substantive MAIN-agent reopen', () => {
+  // The foreground sibling of the sub-agent exemption above: a turn that
+  // delivered a substantive answer early and kept doing tool work sets
+  // `postAnswerMainActivity=true` (via decideFeedReopen().liftLeverOne) so a
+  // fresh activity card can open below the reply. Same 'tool'-only scoping.
+
+  it('post-answer MAIN-agent tool activity DOES open a card (tool + postAnswerMainActivity)', () => {
+    expect(
+      mayOpenActivityCard({
+        producer: 'tool',
+        finalAnswerEverDelivered: true,
+        labeledToolCount: 4,
+        postAnswerMainActivity: true,
+      }),
+    ).toBe(true)
+  })
+
+  it('without the signal Lever 1 stays active (no postAnswerMainActivity → blocked)', () => {
+    expect(
+      mayOpenActivityCard({
+        producer: 'tool',
+        finalAnswerEverDelivered: true,
+        labeledToolCount: 4,
+        postAnswerMainActivity: false,
+      }),
+    ).toBe(false)
+  })
+
+  it('only the tool producer is exempted (liveness/narrative stay blocked with the signal)', () => {
+    for (const producer of ['liveness', 'narrative'] as const) {
+      expect(
+        mayOpenActivityCard({
+          producer,
+          finalAnswerEverDelivered: true,
+          labeledToolCount: 4,
+          postAnswerMainActivity: true,
+        }),
+      ).toBe(false)
+    }
+  })
+})
+
 describe('shouldEarlyOpenLiveness — the early-open WHEN gate (enqueue + heartbeat)', () => {
   // The minimal "Working…" placeholder is due to open for a 0-label turn once it
   // has been alive past the threshold and NO card is open yet. Both the

package/telegram-plugin/tests/feed-reopen-gate.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
 import {
+  SUBSTANTIVE_REOPEN_MIN_LABELS,
   decideFeedReopen,
   shouldReopenFeedAfterAck,
 } from '../gateway/feed-reopen-gate.js'
@@ -131,3 +132,116 @@ describe('decideFeedReopen — tool_label branch outcome for a delivered turn',
     expect(outcome.reset).toBeUndefined()
   })
 })
+
+/**
+ * Post-SUBSTANTIVE feed reopen — a turn that delivered a real answer EARLY and
+ * then kept doing tool work for minutes had its live feed go dark for the rest
+ * of the turn. It reopens once >= SUBSTANTIVE_REOPEN_MIN_LABELS post-answer
+ * labels arrive, WITHOUT clearing finalAnswerDelivered (which would trip the
+ * turn-end re-prompt → duplicate answer). Gated by
+ * `reopenAfterSubstantiveEnabled` (SWITCHROOM_FEED_REOPEN_AFTER_SUBSTANTIVE).
+ */
+describe('post-substantive feed reopen', () => {
+  const substantiveBase = {
+    finalAnswerDelivered: true,
+    finalAnswerSubstantive: true,
+    enabled: true,
+    reopenAfterSubstantiveEnabled: true,
+  }
+
+  it('reopens once >= SUBSTANTIVE_REOPEN_MIN_LABELS post-answer labels have arrived', () => {
+    // The bug: with the flag ON but the counter at threshold, the old gate
+    // hard-returned false. Now it reopens.
+    expect(
+      shouldReopenFeedAfterAck({
+        ...substantiveBase,
+        postSubstantiveToolLabelCount: SUBSTANTIVE_REOPEN_MIN_LABELS,
+      }),
+    ).toBe(true)
+    // And it keeps returning true for further labels (a long multi-phase turn).
+    expect(
+      shouldReopenFeedAfterAck({
+        ...substantiveBase,
+        postSubstantiveToolLabelCount: SUBSTANTIVE_REOPEN_MIN_LABELS + 5,
+      }),
+    ).toBe(true)
+  })
+
+  it('does NOT reopen before the threshold (0 or 1 post-answer labels → no flap)', () => {
+    // A genuinely-final single-reply turn with a stray housekeeping tool must
+    // not flap the card.
+    for (const n of [0, 1]) {
+      expect(
+        shouldReopenFeedAfterAck({
+          ...substantiveBase,
+          postSubstantiveToolLabelCount: n,
+        }),
+      ).toBe(false)
+    }
+    // The threshold is exactly 2 (not 1) by design.
+    expect(SUBSTANTIVE_REOPEN_MIN_LABELS).toBe(2)
+  })
+
+  it('flag OFF → never reopens after a substantive final, even past the threshold (legacy)', () => {
+    expect(
+      shouldReopenFeedAfterAck({
+        finalAnswerDelivered: true,
+        finalAnswerSubstantive: true,
+        enabled: true,
+        reopenAfterSubstantiveEnabled: false,
+        postSubstantiveToolLabelCount: SUBSTANTIVE_REOPEN_MIN_LABELS + 10,
+      }),
+    ).toBe(false)
+    // Omitting the flag entirely is also legacy (default-off at the pure gate).
+    expect(
+      shouldReopenFeedAfterAck({
+        finalAnswerDelivered: true,
+        finalAnswerSubstantive: true,
+        enabled: true,
+        postSubstantiveToolLabelCount: SUBSTANTIVE_REOPEN_MIN_LABELS + 10,
+      }),
+    ).toBe(false)
+  })
+
+  it('decideFeedReopen: at threshold → reopen with liftLeverOne and NO reset (finalAnswerDelivered stays true)', () => {
+    const outcome = decideFeedReopen({
+      ...substantiveBase,
+      postSubstantiveToolLabelCount: SUBSTANTIVE_REOPEN_MIN_LABELS,
+    })
+    expect(outcome.dropLabel).toBe(false)
+    // Crucially NO reset: finalAnswerDelivered must stay true so the turn-end
+    // silent-end re-prompt does not fire → no duplicate answer.
+    expect(outcome.reset).toBeUndefined()
+    // Lever 1 must be lifted so the fresh card opens below the delivered reply.
+    expect(outcome.liftLeverOne).toBe(true)
+  })
+
+  it('decideFeedReopen: below threshold → drops the label (feed stays gated, no flap)', () => {
+    const outcome = decideFeedReopen({
+      ...substantiveBase,
+      postSubstantiveToolLabelCount: 1,
+    })
+    expect(outcome.dropLabel).toBe(true)
+    expect(outcome.reset).toBeUndefined()
+    expect(outcome.liftLeverOne).toBeUndefined()
+  })
+
+  it('ack reopen is unchanged: reset clears finalAnswerDelivered and does NOT lift lever 1', () => {
+    // The ack path (non-substantive) is orthogonal — the new flag/counter must
+    // not perturb it.
+    const outcome = decideFeedReopen({
+      finalAnswerDelivered: true,
+      finalAnswerSubstantive: false,
+      enabled: true,
+      reopenAfterSubstantiveEnabled: true,
+      postSubstantiveToolLabelCount: 99,
+    })
+    expect(outcome.dropLabel).toBe(false)
+    expect(outcome.reset).toEqual({
+      finalAnswerDelivered: false,
+      activityMessageId: null,
+      activityLastSentRender: null,
+    })
+    expect(outcome.liftLeverOne).toBeUndefined()
+  })
+})

package/telegram-plugin/tests/progress-cap.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Integration test for the `progress_update` attention-cap RESERVATION path
+ * (`gateway/progress-fallback-cap.ts` `reserveProgressSlot` /
+ * `sendWithProgressCap`).
+ *
+ * These are the REAL functions the gateway's `executeProgressUpdate` calls —
+ * not a mirror re-implementation. `executeProgressUpdate` wires
+ * `sendWithProgressCap({ key, now, turnStart, turnCount }, () => robustApiCall(...))`
+ * and returns `turn_limit` on `{ capped: true }`, so an ordering regression
+ * INSIDE the reserve/release/cap logic is caught here. (The surrounding
+ * executeProgressUpdate — truncation, the 20s floor, secret scrub — is covered
+ * by `progress-update.test.ts`; isolating the whole async function would drag in
+ * the entire gateway module, so the counter-ordering + cap logic is the seam
+ * bound directly.)
+ *
+ * What it proves:
+ *   (a) the turn-less fallback path caps at 5 and refuses the 6th;
+ *   (b) a thrown send consumes NO slot on either path (release-on-throw);
+ *   (c) N truly-concurrent same-key sends never exceed the cap (Low 1 — the
+ *       reservation happens BEFORE the await, so a concurrent caller sees it).
+ */
+import { describe, it, expect, beforeEach } from 'bun:test'
+import {
+  reserveProgressSlot,
+  sendWithProgressCap,
+  _resetProgressFallbackCap,
+  PROGRESS_TURN_MAX,
+} from '../gateway/progress-fallback-cap.js'
+
+const KEY = 'chat123:_'
+
+/** A send that resolves on the next microtask (models the real async send). */
+function asyncSend<T>(value: T, counter?: { n: number }): () => Promise<T> {
+  return async () => {
+    await Promise.resolve()
+    if (counter) counter.n += 1
+    return value
+  }
+}
+
+describe('progress cap reservation (real gateway path)', () => {
+  beforeEach(() => {
+    _resetProgressFallbackCap()
+  })
+
+  // (a) turn-less path caps at PROGRESS_TURN_MAX, refuses the next.
+  it('turn-less path allows exactly PROGRESS_TURN_MAX then caps (a)', async () => {
+    const turnCount = new Map<string, number>()
+    const now = 1_000
+    for (let i = 0; i < PROGRESS_TURN_MAX; i++) {
+      const r = await sendWithProgressCap(
+        { key: KEY, now, turnStart: undefined, turnCount },
+        asyncSend({ message_id: i }),
+      )
+      expect(r.capped).toBe(false)
+    }
+    const over = await sendWithProgressCap(
+      { key: KEY, now, turnStart: undefined, turnCount },
+      asyncSend({ message_id: 99 }),
+    )
+    expect(over.capped).toBe(true)
+  })
+
+  // (a') turn-scoped path caps too, and does not touch the fallback window.
+  it('turn-scoped path caps at PROGRESS_TURN_MAX (a)', async () => {
+    const turnCount = new Map<string, number>()
+    const deps = { key: KEY, now: 1_000, turnStart: 1_000, turnCount }
+    for (let i = 0; i < PROGRESS_TURN_MAX; i++) {
+      const r = await sendWithProgressCap(deps, asyncSend({ message_id: i }))
+      expect(r.capped).toBe(false)
+    }
+    expect(turnCount.get(KEY)).toBe(PROGRESS_TURN_MAX)
+    const over = await sendWithProgressCap(deps, asyncSend({ message_id: 99 }))
+    expect(over.capped).toBe(true)
+    // Still exactly at the cap — the refused call did not increment.
+    expect(turnCount.get(KEY)).toBe(PROGRESS_TURN_MAX)
+  })
+
+  // (b) a thrown send releases the turn-counter slot.
+  it('a thrown send consumes no turn-counter slot (b)', async () => {
+    const turnCount = new Map<string, number>([[KEY, 0]])
+    const deps = { key: KEY, now: 1_000, turnStart: 1_000, turnCount }
+    await expect(
+      sendWithProgressCap(deps, async () => {
+        throw new Error('telegram 500')
+      }),
+    ).rejects.toThrow('telegram 500')
+    // Slot released → counter back to 0.
+    expect(turnCount.get(KEY)).toBe(0)
+    // Full budget still available afterwards.
+    for (let i = 0; i < PROGRESS_TURN_MAX; i++) {
+      const r = await sendWithProgressCap(deps, asyncSend({ message_id: i }))
+      expect(r.capped).toBe(false)
+    }
+    expect(turnCount.get(KEY)).toBe(PROGRESS_TURN_MAX)
+  })
+
+  // (b) a thrown send releases the fallback-window slot.
+  it('a thrown send consumes no fallback-window slot (b)', async () => {
+    const turnCount = new Map<string, number>()
+    const now = 1_000
+    // PROGRESS_TURN_MAX throwing sends on the turn-less path.
+    for (let i = 0; i < PROGRESS_TURN_MAX; i++) {
+      await expect(
+        sendWithProgressCap(
+          { key: KEY, now, turnStart: undefined, turnCount },
+          async () => {
+            throw new Error('telegram 500')
+          },
+        ),
+      ).rejects.toThrow('telegram 500')
+    }
+    // Window is still empty — every throw released its slot, so a full budget
+    // of real deliveries is allowed, and only the (MAX+1)th is capped.
+    for (let i = 0; i < PROGRESS_TURN_MAX; i++) {
+      const r = await sendWithProgressCap(
+        { key: KEY, now, turnStart: undefined, turnCount },
+        asyncSend({ message_id: i }),
+      )
+      expect(r.capped).toBe(false)
+    }
+    const over = await sendWithProgressCap(
+      { key: KEY, now, turnStart: undefined, turnCount },
+      asyncSend({ message_id: 99 }),
+    )
+    expect(over.capped).toBe(true)
+  })
+
+  // (c) N concurrent same-key sends never exceed the cap — fallback path.
+  // Pre-Low-1 (check atCap → await → record) this delivered all N, because the
+  // record only ran after the await, so every concurrent caller read count 0.
+  it('concurrent same-key sends never exceed the cap — fallback path (c)', async () => {
+    const turnCount = new Map<string, number>()
+    const now = 1_000
+    const delivered = { n: 0 }
+    const N = 25
+    const results = await Promise.all(
+      Array.from({ length: N }, () =>
+        sendWithProgressCap(
+          { key: KEY, now, turnStart: undefined, turnCount },
+          asyncSend({ message_id: 1 }, delivered),
+        ),
+      ),
+    )
+    const proceeded = results.filter((r) => !r.capped).length
+    expect(proceeded).toBe(PROGRESS_TURN_MAX)
+    expect(delivered.n).toBe(PROGRESS_TURN_MAX)
+  })
+
+  // (c) N concurrent same-key sends never exceed the cap — turn-counter path.
+  it('concurrent same-key sends never exceed the cap — turn path (c)', async () => {
+    const turnCount = new Map<string, number>([[KEY, 0]])
+    const delivered = { n: 0 }
+    const N = 25
+    const deps = { key: KEY, now: 1_000, turnStart: 1_000, turnCount }
+    const results = await Promise.all(
+      Array.from({ length: N }, () =>
+        sendWithProgressCap(deps, asyncSend({ message_id: 1 }, delivered)),
+      ),
+    )
+    const proceeded = results.filter((r) => !r.capped).length
+    expect(proceeded).toBe(PROGRESS_TURN_MAX)
+    expect(delivered.n).toBe(PROGRESS_TURN_MAX)
+    // The counter settled exactly at the cap — no overshoot, no leaked slot.
+    expect(turnCount.get(KEY)).toBe(PROGRESS_TURN_MAX)
+  })
+
+  // Non-concurrent behaviour is identical to before: a successful reserve keeps
+  // the slot, so reserveProgressSlot alone (no send) accounts the delivery.
+  it('reserveProgressSlot keeps the slot on success, releases on demand', () => {
+    const turnCount = new Map<string, number>([[KEY, 0]])
+    const deps = { key: KEY, now: 1_000, turnStart: 1_000, turnCount }
+    const first = reserveProgressSlot(deps)
+    expect(first).not.toBeNull()
+    expect(turnCount.get(KEY)).toBe(1)
+    // Releasing hands the slot back; a second release is a no-op.
+    first!.release()
+    expect(turnCount.get(KEY)).toBe(0)
+    first!.release()
+    expect(turnCount.get(KEY)).toBe(0)
+  })
+})

package/telegram-plugin/tests/progress-fallback-cap.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Unit tests for the `progress_update` turn-less fallback attention cap
+ * (`gateway/progress-fallback-cap.ts`).
+ *
+ * The bug this guards: when an inbound mints no turn atom (handback / progress
+ * inbound turns), the per-turn 5-call cap never applied, so a worker could
+ * `progress_update` at the 20s floor indefinitely. This is the real module the
+ * gateway calls — it exercises the rolling-window cap, the delivery-only
+ * counting, and the prune-to-empty memory behaviour directly.
+ */
+import { describe, it, expect, beforeEach } from 'bun:test'
+import {
+  progressFallbackAtCap,
+  recordProgressFallbackSend,
+  _resetProgressFallbackCap,
+  PROGRESS_FALLBACK_MAX,
+  PROGRESS_FALLBACK_WINDOW_MS,
+} from '../gateway/progress-fallback-cap.js'
+
+const KEY = 'chat123:_'
+
+describe('progress fallback cap', () => {
+  beforeEach(() => {
+    _resetProgressFallbackCap()
+  })
+
+  it('allows exactly PROGRESS_FALLBACK_MAX deliveries then caps', () => {
+    let now = 1_000
+    for (let i = 0; i < PROGRESS_FALLBACK_MAX; i++) {
+      expect(progressFallbackAtCap(KEY, now)).toBe(false)
+      recordProgressFallbackSend(KEY, now)
+      now += 25_000 // past the 20s floor, still well inside the window
+    }
+    // The (MAX+1)th within the window is refused.
+    expect(progressFallbackAtCap(KEY, now)).toBe(true)
+  })
+
+  it('rolls: a delivery ages out after the window and frees a slot', () => {
+    const start = 1_000
+    let now = start
+    for (let i = 0; i < PROGRESS_FALLBACK_MAX; i++) {
+      recordProgressFallbackSend(KEY, now)
+      now += 25_000
+    }
+    expect(progressFallbackAtCap(KEY, now)).toBe(true)
+
+    // Jump past the window relative to the FIRST send: the oldest entries age
+    // out, so we are under cap again.
+    now = start + PROGRESS_FALLBACK_WINDOW_MS + 1
+    expect(progressFallbackAtCap(KEY, now)).toBe(false)
+  })
+
+  it('a slot is consumed only by recordProgressFallbackSend, not by the check', () => {
+    const now = 1_000
+    // Checking the cap repeatedly must not itself consume slots (models a
+    // thrown send: cap checked, send throws, nothing recorded).
+    for (let i = 0; i < 100; i++) {
+      expect(progressFallbackAtCap(KEY, now)).toBe(false)
+    }
+    // Full budget still available.
+    for (let i = 0; i < PROGRESS_FALLBACK_MAX; i++) {
+      expect(progressFallbackAtCap(KEY, now)).toBe(false)
+      recordProgressFallbackSend(KEY, now + i)
+    }
+    expect(progressFallbackAtCap(KEY, now + PROGRESS_FALLBACK_MAX)).toBe(true)
+  })
+
+  it('keys are independent', () => {
+    const now = 1_000
+    for (let i = 0; i < PROGRESS_FALLBACK_MAX; i++) {
+      recordProgressFallbackSend('a:_', now + i)
+    }
+    expect(progressFallbackAtCap('a:_', now + PROGRESS_FALLBACK_MAX)).toBe(true)
+    expect(progressFallbackAtCap('b:_', now + PROGRESS_FALLBACK_MAX)).toBe(false)
+  })
+
+  it('prunes an emptied key so the map does not grow unbounded', () => {
+    // A single delivery, then a check well past the window: the key should be
+    // dropped, restoring the full budget (proves the array was pruned, not
+    // just skipped over).
+    recordProgressFallbackSend(KEY, 1_000)
+    const later = 1_000 + PROGRESS_FALLBACK_WINDOW_MS + 1
+    expect(progressFallbackAtCap(KEY, later)).toBe(false)
+    // And a fresh full budget is available from `later`.
+    for (let i = 0; i < PROGRESS_FALLBACK_MAX; i++) {
+      expect(progressFallbackAtCap(KEY, later + i)).toBe(false)
+      recordProgressFallbackSend(KEY, later + i)
+    }
+    expect(progressFallbackAtCap(KEY, later + PROGRESS_FALLBACK_MAX)).toBe(true)
+  })
+})