switchroom 0.19.26 → 0.19.27

package/telegram-plugin/tests/card-variants.ts

@@ -0,0 +1,366 @@
+/**
+ * The catalogue of EVERY status/progress card variant the gateway can paint,
+ * each rendered through the REAL renderer with realistic inputs.
+ *
+ * One catalogue, two consumers, so they can never disagree:
+ *   - `telegram-plugin/tests/card-golden.test.ts` — the golden suite. Every
+ *     variant's exact wire text is pinned in `card-variants.golden.txt`, so a
+ *     change to the shared card layout that alters ANY card fails loudly.
+ *   - `scripts/card-previews.ts` — the human-readable preview doc.
+ *
+ * Adding a card variant means adding it HERE (and regenerating the golden with
+ * `UPDATE_CARD_GOLDEN=1 npx vitest run telegram-plugin/tests/card-golden.test.ts`),
+ * which is what keeps the golden suite exhaustive rather than a sample.
+ *
+ * These are RENDERER-level fixtures. The lifecycle behaviour that decides WHICH
+ * variant gets painted (dispatch → running → 2 workers → spill → done → failed
+ * → superseded) is covered end-to-end from the feed manager in
+ * `card-lifecycle-render.test.ts`; the two suites are complementary, not
+ * duplicates.
+ */
+import {
+  renderActivityFeed,
+  renderActivityFeedWithNested,
+  renderCombinedWorkerFeed,
+  type CombinedWorkerRow,
+  type SessionActivityHeader,
+} from '../tool-activity-summary.js'
+import {
+  renderWorkerActivity,
+  WORKER_CARD_SUPERSEDED_BODY,
+  type WorkerActivityView,
+} from '../worker-activity-feed.js'
+
+/** Which renderer path a variant exercises, for the preview doc's inventory. */
+export interface CardVariant {
+  /** Stable identity — the golden file keys on this, so renaming rewrites it. */
+  name: string
+  /** The call path, for the preview doc. */
+  fn: string
+  /** When a user actually sees this card. */
+  when: string
+  /**
+   * How the variant reaches the wire:
+   *  - `shared`   — composed by the one card layout core (`card-layout.ts`).
+   *  - `constant` — a static notice with no live state to render (see the
+   *    superseded card); its title line still comes from the shared composer.
+   */
+  layout?: 'shared' | 'constant'
+  /** The real render. `null` means the renderer declined to emit anything. */
+  render: () => string | null
+}
+
+const agentHeader = (over: Partial<SessionActivityHeader> = {}): SessionActivityHeader => ({
+  label: 'Agent',
+  elapsedMs: 95_000,
+  toolCount: 12,
+  state: 'running',
+  model: 'claude-opus-4-8',
+  totalTokens: 41_200,
+  ...over,
+})
+
+const AGENT_STEPS = [
+  'Searching memory for card render paths',
+  'Reading telegram-plugin/tool-activity-summary.ts',
+  'Reading telegram-plugin/worker-activity-feed.ts',
+  'Grepping for renderStatusCard callers',
+  'Drafting the inventory table',
+]
+
+const workerView = (over: Partial<WorkerActivityView> = {}): WorkerActivityView => ({
+  description: 'Audit every card render path and de-indent the worker card',
+  state: 'running',
+  elapsedMs: 143_000,
+  toolCount: 31,
+  lastTool: null,
+  latestSummary: '',
+  narrativeLines: [
+    'Fetching origin and branching off main',
+    'Reading telegram-plugin/status-no-truncate.ts',
+    'Mapping renderStatusCard callers',
+    'Writing the preview harness',
+  ],
+  model: 'claude-opus-4-8',
+  totalTokens: 88_400,
+  ...over,
+})
+
+const row = (
+  n: number,
+  desc: string,
+  hist: string[],
+  over: Partial<CombinedWorkerRow> = {},
+): CombinedWorkerRow => ({
+  ordinal: n,
+  description: desc,
+  elapsedMs: 60_000 * n + 15_000,
+  toolCount: 7 * n,
+  totalTokens: 20_000 * n,
+  currentStep: hist[hist.length - 1] ?? 'starting…',
+  historyLines: hist,
+  model: 'claude-opus-4-8',
+  ...over,
+})
+
+const H = (k: number, tag: string): string[] =>
+  Array.from({ length: k }, (_, i) => `${tag} step ${i + 1}`)
+
+/** A 700-char step — long enough to blow the per-line clip and force the backstop. */
+const LONG = 'A'.repeat(700)
+
+export const CARD_VARIANTS: CardVariant[] = [
+  {
+    name: 'Agent card — running',
+    fn: 'renderActivityFeed → renderStatusCard',
+    when: 'Every turn that labels a tool. Pinned in the session chat, edited in place.',
+    render: () => renderActivityFeed(AGENT_STEPS, false, '', undefined, agentHeader()),
+  },
+  {
+    name: 'Agent card — final (turn complete)',
+    fn: 'renderActivityFeed → renderStatusCard',
+    when: 'The terminal edit when the turn ends: every step struck, `✓ N steps` footer.',
+    render: () =>
+      renderActivityFeed(AGENT_STEPS, true, '', 17, agentHeader({ state: 'done', elapsedMs: 214_000 })),
+  },
+  {
+    name: 'Agent card — steps only (no header)',
+    fn: 'renderActivityFeed → renderStatusCard (header omitted)',
+    when: 'Legacy/direct callers (`appendActivityLine`, `appendActivityLabel`) that pass no header.',
+    render: () => renderActivityFeed(AGENT_STEPS.slice(0, 3)),
+  },
+  {
+    name: 'Agent card — with nested foreground sub-agent',
+    fn: 'renderActivityFeedWithNested → renderStatusCard (childSteps)',
+    when: 'A foreground Task/Agent runs inside the turn: parent lines all struck, the live `→` sits in the `↳` child block.',
+    render: () =>
+      renderActivityFeedWithNested(
+        AGENT_STEPS.slice(0, 3),
+        ['Reading the repo conventions', 'Running the scoped test suite', 'Summarising findings'],
+        false,
+        ' · 24s',
+        undefined,
+        agentHeader(),
+      ),
+  },
+  {
+    name: 'Agent card — liveness early-open (no tools yet)',
+    fn: 'narrative-lane.ts → renderActivityFeedWithNested → renderStatusCard',
+    when: 'A silent turn passes the liveness threshold before any tool is labelled — the card opens on `Working…`.',
+    render: () =>
+      renderActivityFeedWithNested(['Working…'], [], false, ' · 32s', undefined, {
+        label: 'Agent',
+        elapsedMs: 32_000,
+        toolCount: 0,
+        state: 'running',
+        model: 'claude-opus-4-8',
+      }),
+  },
+  {
+    name: 'Agent card — liveness finalised',
+    fn: 'narrative-lane.ts → renderActivityFeedWithNested → renderStatusCard',
+    when: 'The liveness-only card at turn end: `→ Working…` becomes a done record instead of freezing live.',
+    render: () =>
+      renderActivityFeedWithNested(['Working…'], [], true, '', undefined, {
+        label: 'Agent',
+        elapsedMs: 88_000,
+        toolCount: 0,
+        state: 'done',
+        model: 'claude-opus-4-8',
+      }),
+  },
+  {
+    name: 'Agent card — post-answer background activity',
+    fn: 'narrative-lane.ts → renderActivityFeedWithNested → renderStatusCard',
+    when: 'The reply already went out and a background sub-agent is still running — the card surfaces below the reply.',
+    render: () =>
+      renderActivityFeedWithNested(['Working in background…'], [], false, ' · 1m10s', undefined, {
+        label: 'Agent',
+        elapsedMs: 130_000,
+        toolCount: 3,
+        state: 'running',
+        model: 'claude-opus-4-8',
+      }),
+  },
+  {
+    name: 'Agent card — over-long steps (per-line clip)',
+    fn: 'renderStatusCard → cleanStepLine (STATUS_LINE_MAX)',
+    when: 'A step line far exceeds STATUS_LINE_MAX: each is clipped to 200 chars + `…` before escaping. (This is also why the card-wide `fitCardToBudget` backstop is unreachable on the agent card — 5 clipped lines cannot approach 32768. The shrink levels are genuinely exercised by the WORKERS spill variant.)',
+    render: () =>
+      renderActivityFeed(
+        [LONG, LONG, LONG, 'Finally a short newest step'],
+        false,
+        '',
+        undefined,
+        agentHeader(),
+      ),
+  },
+  {
+    name: 'Worker card — just dispatched (no steps yet)',
+    fn: 'renderWorkerActivity → renderStatusCard (emptyPlaceholder)',
+    when: 'The first paint of a background worker, before it has produced a narrative line.',
+    render: () =>
+      renderWorkerActivity(
+        workerView({ narrativeLines: [], latestSummary: '', elapsedMs: 1_200, toolCount: 0 }),
+      ),
+  },
+  {
+    name: 'Worker card — single worker running',
+    fn: 'renderWorkerActivity → renderStatusCard',
+    when: 'Exactly one background worker live in the chat. Pinned; edited in place.',
+    render: () => renderWorkerActivity(workerView(), ' · 18s'),
+  },
+  {
+    name: 'Worker card — done (with result recap)',
+    fn: 'renderWorkerActivity → renderStatusCard (result block)',
+    when: 'The worker finished successfully: feed all-struck, rule, then the ✅ result paragraph.',
+    render: () =>
+      renderWorkerActivity(
+        workerView({
+          state: 'done',
+          elapsedMs: 902_000,
+          latestSummary:
+            'Inventoried 14 card variants, found renderCombinedWorkerFeed forks the header + budget logic, and de-indented the worker card. PR #0000.',
+        }),
+      ),
+  },
+  {
+    name: 'Worker card — failed',
+    fn: 'renderWorkerActivity → renderStatusCard (result block, ⚠️)',
+    when: 'The worker errored: header line 2 reads `failed`, result block carries the error recap.',
+    render: () =>
+      renderWorkerActivity(
+        workerView({
+          state: 'failed',
+          elapsedMs: 61_000,
+          latestSummary: 'Scoped test run failed: 3 assertions in card-type-distinguishability.test.ts.',
+        }),
+      ),
+  },
+  {
+    name: 'Worker card — incomplete (killed / timed out)',
+    fn: 'renderWorkerActivity → renderStatusCard (result suppressed by invariant)',
+    when: 'The worker was terminated before producing a result — the renderer refuses to fabricate a result block.',
+    render: () =>
+      renderWorkerActivity(
+        workerView({
+          state: 'incomplete',
+          elapsedMs: 1_805_000,
+          latestSummary: 'stray text that must not render',
+        }),
+      ),
+  },
+  {
+    name: 'WORKERS card — 2 workers',
+    fn: 'renderCombinedWorkerFeed → the shared card spec',
+    when: '2+ background workers live in the same chat/thread coalesce into ONE message. Depth = 5 each.',
+    render: () =>
+      renderCombinedWorkerFeed(
+        [
+          row(1, 'Audit every card render path', H(5, 'audit')),
+          row(2, 'Fix the hindsight recall floor', H(5, 'recall')),
+        ],
+        { maxRows: 6 },
+      ),
+  },
+  {
+    name: 'WORKERS card — 4 workers',
+    fn: 'renderCombinedWorkerFeed → the shared card spec',
+    when: "Depth degrades to the floor of Ken's 6/5/4/3 curve.",
+    render: () =>
+      renderCombinedWorkerFeed(
+        [
+          row(1, 'Audit every card render path', H(4, 'audit')),
+          row(2, 'Fix the hindsight recall floor', H(4, 'recall')),
+          row(3, 'Release v0.19.24', H(4, 'release')),
+          row(4, 'Investigate the flaky UAT scenario', H(4, 'uat')),
+        ],
+        { maxRows: 6 },
+      ),
+  },
+  {
+    name: 'WORKERS card — 8 workers (spill)',
+    fn: 'renderCombinedWorkerFeed → fitCardToBudget (row-count shrink levels)',
+    when: 'Beyond the design fan-out the NEWEST rows collapse into a single `+M more working…` line.',
+    render: () =>
+      renderCombinedWorkerFeed(
+        Array.from({ length: 8 }, (_, i) => row(i + 1, `Background task number ${i + 1}`, H(3, `t${i + 1}`))),
+        { maxRows: 6 },
+      ),
+  },
+  {
+    name: 'WORKERS card — survivors keep their ordinals',
+    fn: 'renderCombinedWorkerFeed → the shared card spec',
+    when: 'Worker 1 finished; 2 and 3 keep their numbers, so the card shows `2.`/`3.` with no `1.`',
+    render: () =>
+      renderCombinedWorkerFeed(
+        [
+          row(2, 'Fix the hindsight recall floor', H(4, 'recall')),
+          row(3, 'Release v0.19.24', H(4, 'release')),
+        ],
+        { maxRows: 6 },
+      ),
+  },
+  {
+    name: 'WORKERS card — a worker with no history yet',
+    fn: 'renderCombinedWorkerFeed → section placeholder',
+    when: 'A freshly dispatched worker joins a group that already has a live card.',
+    render: () =>
+      renderCombinedWorkerFeed(
+        [
+          row(1, 'Audit every card render path', H(5, 'audit')),
+          row(2, 'Freshly dispatched worker', [], { currentStep: '', historyLines: undefined }),
+        ],
+        { maxRows: 6 },
+      ),
+  },
+  {
+    name: 'Worker card — superseded (group message rotated)',
+    layout: 'constant',
+    fn: 'WORKER_CARD_SUPERSEDED_BODY (static notice; title line via renderCardTitleLine)',
+    when: 'The shared worker message hit its lifetime cap and a fresh card was opened; the retired message is finalised to this static note so it does not read as a stuck worker.',
+    render: () => WORKER_CARD_SUPERSEDED_BODY,
+  },
+  {
+    name: 'Agent card — rolling-window overflow',
+    fn: 'renderActivityFeed → renderStatusCard → emitSection',
+    when: 'More steps than the rolling window: the oldest collapse to a `✓ +N earlier…` header.',
+    render: () =>
+      renderActivityFeed(
+        Array.from({ length: 14 }, (_, i) => `Doing thing number ${i + 1}`),
+        false,
+        '',
+        undefined,
+        agentHeader(),
+      ),
+  },
+  {
+    name: 'Agent card — nested sub-agent with child overflow',
+    fn: 'renderActivityFeedWithNested → renderStatusCard',
+    when: 'The foreground sub-agent has produced more steps than the window: a `↳ +N earlier…` header appears in the child block.',
+    render: () =>
+      renderActivityFeedWithNested(
+        AGENT_STEPS.slice(0, 2),
+        Array.from({ length: 11 }, (_, i) => `Child step ${i + 1}`),
+        false,
+        '',
+        undefined,
+        agentHeader(),
+      ),
+  },
+]
+
+/** Section delimiter in the golden file. Chosen so no card body can contain it. */
+export const GOLDEN_DELIMITER = '\n===== CARD ====='
+
+/**
+ * The whole catalogue as ONE deterministic string — what the golden file holds.
+ * Every variant contributes its name and its exact rendered bytes.
+ */
+export function renderGoldenDocument(): string {
+  return (
+    CARD_VARIANTS.map(
+      (v) => `${GOLDEN_DELIMITER} ${v.name}\n${v.render() ?? '(null — renderer returned nothing)'}`,
+    ).join('\n') + '\n'
+  )
+}

package/telegram-plugin/tests/edit-flood-fuse-ban-awareness.test.ts

@@ -0,0 +1,316 @@
+/**
+ * The fuse must survive a restart and must react in PROPORTION to the ban
+ * (#3856).
+ *
+ * ── The two bugs these tests guard ───────────────────────────────────────
+ *
+ * 1. **All state was in process memory.** `tightenLevel` / `tightenedUntil`
+ *    were module-local variables. The gateway restarting during a flood ban —
+ *    the single most likely thing to happen during a multi-hour outage —
+ *    brought the fuse back FULLY UNTIGHTENED, at exactly the rate that earned
+ *    the ban, while the window was still open. Every other outbound path in
+ *    the tree already consults `flood-wait.json`; the fuse did not.
+ *
+ * 2. **`noteFlood()` ignored the magnitude.** Every 429 was worth exactly one
+ *    level of multiplicative decrease, so a 3-second burst nudge and the
+ *    15908-second (4.4h) ban of 2026-07-27 produced an identical response.
+ *    The tightening also expired after a flat 10 minutes — ~25× shorter than
+ *    that ban, so the fuse would have been back at full rate for hours while
+ *    still banned.
+ *
+ * Every test asserts an OUTCOME (the live ceiling, or how many calls reached
+ * the wire), never that a branch ran.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  createEditFloodFuse,
+  editFloodFuseConfigFromEnv,
+  EDIT_FLOOD_FUSE_DEFAULTS,
+} from '../edit-flood-fuse.js'
+import { floodStatePath, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
+import type { Clock } from '../send-gate.js'
+
+const CHAT = '1001'
+
+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()
+  }
+}
+const flush = (): Promise<void> => new Promise((r) => setImmediate(r))
+
+/** A 429 in the shape grammY throws it. */
+function flood(retryAfterSec: number): Error & Record<string, unknown> {
+  const e = new Error('Too Many Requests: retry after ' + retryAfterSec) as Error &
+    Record<string, unknown>
+  e.error_code = 429
+  e.parameters = { retry_after: retryAfterSec }
+  return e
+}
+
+describe('restart durability — the persisted window outranks process memory', () => {
+  it('a FRESH fuse is already at its tightest when a ban is open on disk', async () => {
+    const clock = new FakeClock()
+    // Simulate the restart: brand-new fuse, zero in-memory history, but the
+    // marker on disk still says 12247s of ban to go.
+    const fuse = createEditFloodFuse({
+      clock, floodWaitRemainingMs: () => 12_247_000,
+      perMessageMaxPerWindow: 20, cosmeticPerMessageMaxPerWindow: 16,
+      maxTightenLevel: 4, tightenFactor: 0.5,
+    })
+
+    const s = fuse.stats()
+    expect(s.persistedFloodOpen).toBe(true)
+    expect(s.tightenLevel).toBe(4)
+    // 0.5^4 = 1/16 of the base ceiling — the fuse did NOT come back at full rate.
+    expect(s.cosmeticPerMessageCeiling).toBe(1)
+    expect(s.perMessageCeiling).toBe(1)
+    // And it BINDS: 30 cosmetic edits offered, at most the tightened ceiling
+    // reaches the wire. Without the persisted read this is 16.
+    let landed = 0
+    const calls = Array.from({ length: 30 }, () =>
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 7 }, async () => {
+        landed++
+        return true
+      }))
+    await clock.advance(31_000)
+    await Promise.all(calls)
+    expect(landed).toBeLessThanOrEqual(2)
+  })
+
+  it('untightens once the window on disk closes — it is a floor, not a latch', async () => {
+    const clock = new FakeClock()
+    let remaining = 60_000
+    const fuse = createEditFloodFuse({
+      clock, floodWaitRemainingMs: () => remaining,
+      floodProbeIntervalMs: 0, // re-read every call, for determinism here
+      perMessageMaxPerWindow: 20, maxTightenLevel: 4, tightenFactor: 0.5,
+    })
+    expect(fuse.stats().tightenLevel).toBe(4)
+    remaining = 0
+    // The fuse earned nothing itself, so it returns all the way to base — the
+    // persisted window pins the level while open and never mutates it.
+    expect(fuse.stats().tightenLevel).toBe(0)
+    expect(fuse.stats().perMessageCeiling).toBe(20)
+  })
+
+  it('FAILS OPEN: an unreadable marker must never gag the bot', async () => {
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({
+      clock,
+      floodWaitRemainingMs: () => {
+        throw new Error('EACCES: flood-wait.json owned by another uid')
+      },
+      perChatSendMaxPerWindow: 25,
+    })
+    expect(fuse.stats().persistedFloodOpen).toBe(false)
+    expect(fuse.stats().tightenLevel).toBe(0)
+    let landed = 0
+    await fuse.apply('sendMessage', { chat_id: CHAT, text: 'the answer' }, async () => {
+      landed++
+      return true
+    })
+    expect(landed).toBe(1)
+  })
+
+  it('re-reads the marker at most once per floodProbeIntervalMs', async () => {
+    const clock = new FakeClock()
+    let reads = 0
+    const fuse = createEditFloodFuse({
+      clock, floodProbeIntervalMs: 1_000,
+      floodWaitRemainingMs: () => { reads++; return 0 },
+      perChatTotalMaxPerWindow: 1_000, perChatSendMaxPerWindow: 1_000,
+      perTokenMaxPerWindow: 1_000,
+    })
+    for (let i = 0; i < 50; i++) {
+      await fuse.apply('sendMessage', { chat_id: CHAT, text: 'x' }, async () => true)
+    }
+    // A file read on every admission would make the fuse the latency problem
+    // it exists to prevent.
+    expect(reads).toBeLessThanOrEqual(2)
+  })
+
+  it('reads the REAL breaker file that robustApiCall and the sweep use', async () => {
+    // Not a mock: write the actual on-disk marker and let the production probe
+    // read it, so the two halves cannot drift apart.
+    const dir = mkdtempSync(join(tmpdir(), 'fuse-flood-'))
+    try {
+      writeFileSync(
+        floodStatePath(dir),
+        JSON.stringify({ untilTs: Date.now() + 12_247_000, retryAfterSec: 12247, recordedTs: Date.now() }),
+        'utf-8',
+      )
+      const fuse = createEditFloodFuse({
+        floodWaitRemainingMs: makeFloodWaitProbe(floodStatePath(dir)),
+        maxTightenLevel: 4, tightenFactor: 0.5, perMessageMaxPerWindow: 20,
+      })
+      expect(fuse.stats().persistedFloodOpen).toBe(true)
+      expect(fuse.stats().perMessageCeiling).toBe(1)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('editFloodFuseConfigFromEnv wires the probe from TELEGRAM_STATE_DIR', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'fuse-env-'))
+    try {
+      writeFileSync(
+        floodStatePath(dir),
+        JSON.stringify({ untilTs: Date.now() + 600_000, retryAfterSec: 600, recordedTs: Date.now() }),
+        'utf-8',
+      )
+      const cfg = editFloodFuseConfigFromEnv({ TELEGRAM_STATE_DIR: dir })
+      expect(cfg.floodWaitRemainingMs).toBeTypeOf('function')
+      expect(cfg.floodWaitRemainingMs!()).toBeGreaterThan(0)
+      // The wiring is what makes it durable in production — a fuse built from
+      // this config is tightened without anyone remembering to pass a probe.
+      expect(createEditFloodFuse(cfg).stats().persistedFloodOpen).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('is a no-op when TELEGRAM_STATE_DIR is unset (dev / one-shot contexts)', () => {
+    const cfg = editFloodFuseConfigFromEnv({})
+    expect(cfg.floodWaitRemainingMs).toBeUndefined()
+    expect(createEditFloodFuse(cfg).stats().persistedFloodOpen).toBe(false)
+  })
+})
+
+describe('severity scaling — a 4.4h ban is not one nudge\'s worth of signal', () => {
+  const mk = (clock: FakeClock) =>
+    createEditFloodFuse({
+      clock, maxTightenLevel: 4, tightenFactor: 0.5, tightenMs: 600_000,
+      perMessageMaxPerWindow: 32,
+    })
+
+  async function observe(fuse: ReturnType<typeof mk>, retryAfterSec: number): Promise<void> {
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw flood(retryAfterSec)
+      }),
+    ).rejects.toThrow()
+  }
+
+  it.each([
+    [3, 1],      // routine burst nudge
+    [30, 2],     // sustained overrate
+    [120, 3],    // a real ban
+    [3713, 4],   // the 2026-07-25 incident — straight to maximum
+    [15908, 4],  // the 2026-07-27 incident
+  ])('retry_after=%is tightens by %i level(s)', async (retryAfterSec, expected) => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await observe(fuse, retryAfterSec)
+    expect(fuse.stats().tightenLevel).toBe(expected)
+  })
+
+  it('the ban-magnitude case reaches the floor in ONE 429, not four', async () => {
+    // This is the assertion that fails on the pre-fix code: there, a single
+    // 15908s ban moved the ceiling from 32 to 16 and the stream carried on at
+    // half rate into a four-hour outage.
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    expect(fuse.stats().perMessageCeiling).toBe(32)
+    await observe(fuse, 15_908)
+    expect(fuse.stats().perMessageCeiling).toBe(2) // 32 * 0.5^4
+  })
+
+  it('holds the tightening for AT LEAST the ban\'s own duration', async () => {
+    // A flat 10-minute tightenMs expired ~25× over during the 4.4h ban.
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await observe(fuse, 15_908)
+    await clock.advance(15_907_000) // one second before the ban lifts
+    expect(fuse.stats().tightenLevel).toBeGreaterThan(0)
+    expect(fuse.stats().perMessageCeiling).toBeLessThan(32)
+  })
+
+  it('a 3s nudge still decays on the normal 10-minute schedule', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await observe(fuse, 3)
+    expect(fuse.stats().tightenLevel).toBe(1)
+    // Held for tightenMs PLUS the stated penalty (3s) — still ~10 minutes.
+    await clock.advance(600_001)
+    expect(fuse.stats().tightenLevel).toBe(1)
+    await clock.advance(3_001)
+    expect(fuse.stats().tightenLevel).toBe(0)
+    expect(fuse.stats().perMessageCeiling).toBe(32)
+  })
+
+  it('recovers the magnitude from a 429 that arrives as a raw ApiResponse', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () =>
+      ({ ok: false, error_code: 429, parameters: { retry_after: 15_908 } }))
+    expect(fuse.stats().tightenLevel).toBe(4)
+  })
+
+  it('recovers the magnitude from the message text when there is no parameters block', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw new Error('Too Many Requests: retry after 15908')
+      }),
+    ).rejects.toThrow()
+    expect(fuse.stats().tightenLevel).toBe(4)
+  })
+
+  it('an UNQUANTIFIED flood is treated as the mildest case, not the worst', async () => {
+    // Inflating an unmeasured signal into a maximal response would let one
+    // ambiguous error message throttle the bot to 1/window.
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw new Error('Too Many Requests')
+      }),
+    ).rejects.toThrow()
+    expect(fuse.stats().tightenLevel).toBe(1)
+  })
+
+  it('still does NOT tighten on an ordinary error that merely contains "429"', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw new Error('Bad Request: message 429 not found')
+      }),
+    ).rejects.toThrow()
+    expect(fuse.stats().tightenLevel).toBe(0)
+    expect(fuse.stats().floodObserved).toBe(0)
+  })
+
+  it('the default probe interval is bounded', () => {
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.floodProbeIntervalMs).toBeGreaterThan(0)
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.floodProbeIntervalMs).toBeLessThanOrEqual(5_000)
+  })
+})