switchroom 0.18.15 → 0.18.18

package/telegram-plugin/send-gate-degraded.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { createSendGate, type Clock } from './send-gate.js'
+import { createSendGate, SEND_GATE_SHED, type Clock } from './send-gate.js'
 import { isFloodWaitActiveError } from './retry-api-call.js'
 
 /**
@@ -73,8 +73,10 @@ describe('send-gate PR2: cosmetic shedding', () => {
 
     const res = await gate.gate(fn('cosmetic'), { priorityClass: 'cosmetic' })
 
-    // Shed resolves undefined; fn never ran; the shed counter moved.
-    expect(res).toBeUndefined()
+    // Shed resolves the distinguishable sentinel (#3110 F1 — never a bare
+    // undefined, which is reserved for benign no-op drops); fn never ran;
+    // the shed counter moved.
+    expect(res).toBe(SEND_GATE_SHED)
     expect(calls).toHaveLength(0)
     expect(gate.stats().global.shed).toBe(1)
     expect(gate.stats().global.sent).toBe(0)
@@ -95,7 +97,7 @@ describe('send-gate PR2: cosmetic shedding', () => {
     const shed = await gate.gate(fn('b'), { chat_id: '5', priorityClass: 'cosmetic' })
 
     expect(calls.map((c) => c.label)).toEqual(['a'])
-    expect(shed).toBeUndefined()
+    expect(shed).toBe(SEND_GATE_SHED)
     expect(gate.stats().global.shed).toBe(1)
   })
 
@@ -128,7 +130,7 @@ describe('send-gate PR2: cosmetic shedding', () => {
       priorityClass: 'cosmetic',
     })
 
-    expect(res).toBeUndefined()
+    expect(res).toBe(SEND_GATE_SHED)
     expect(calls).toHaveLength(0)
     expect(gate.stats().global.shed).toBe(1)
   })
@@ -366,7 +368,7 @@ describe('send-gate PR2: H1 cross-chat message_id isolation', () => {
       priorityClass: 'cosmetic',
     })
 
-    expect(rA).toBeUndefined() // A shed
+    expect(rA).toBe(SEND_GATE_SHED) // A shed
     expect(rB).toBe('B-edit') // B sent
     expect(calls.map((c) => c.label)).toEqual(['B-edit'])
     expect(gate.stats().global.shed).toBe(1)
@@ -564,11 +566,162 @@ describe('send-gate PR2: opening a window from a 429, and persistence hook', ()
     ).rejects.toBe(floodErr)
 
     const scopes = opened.map((o) => o.scopeKey).sort()
+    // #3111: a chat-bound 429 opens ONLY the chat/group/msg-edit scopes — NOT a
+    // coincident `global` window (which would suppress unrelated chats).
     // H1: msg-edit scope carries the chat_id (msg-edit:7:3), not the bare id.
-    expect(scopes).toEqual(['chat:7', 'global', 'group:7', 'msg-edit:7:3'])
+    expect(scopes).toEqual(['chat:7', 'group:7', 'msg-edit:7:3'])
     // After the window opens, a later cosmetic on the same chat sheds.
     const shed = await gate.gate(async () => 'x', { chat_id: '7', priorityClass: 'cosmetic' })
-    expect(shed).toBeUndefined()
+    expect(shed).toBe(SEND_GATE_SHED)
     expect(gate.stats().global.shed).toBe(1)
   })
 })
+
+describe('send-gate #3111: scope-precise flood windows', () => {
+  // A structured FLOOD_WAIT_ACTIVE the wrapped `fn` throws to simulate a 429
+  // whose remaining window (`untilTs`) exceeds the fail-fast ceiling.
+  function floodErrUntil(untilTs: number) {
+    const sec = Math.ceil(untilTs / 1000)
+    return Object.assign(new Error('FLOOD_WAIT_ACTIVE'), {
+      retryAfterSec: sec,
+      untilTs,
+      error_code: 429 as const,
+      parameters: { retry_after: sec },
+      original: null,
+    })
+  }
+
+  it('a chat:A 429 suppresses only chat:A — an unrelated chat:B critical still sends', async () => {
+    const clock = new FakeClock()
+    const opened: string[] = []
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      criticalFailFastMs: 60_000,
+      onWindowOpen: (scopeKey) => opened.push(scopeKey),
+    })
+
+    // A LONG (10-min) 429 on chat:A opens the flood window via the gate's catch.
+    const floodErr = floodErrUntil(600_000)
+    await expect(
+      gate.gate(
+        async () => {
+          throw floodErr
+        },
+        { chat_id: 'A', priorityClass: 'critical' },
+      ),
+    ).rejects.toBe(floodErr)
+
+    // Only chat:A was suppressed — pre-#3111 this ALSO opened `global`.
+    expect(opened.sort()).toEqual(['chat:A'])
+    // The 429 came from `fn`, not a fail-fast admission.
+    expect(gate.stats().global.failedFast).toBe(0)
+
+    // An unrelated chat:B critical is NOT fail-fasted — it sends. Pre-#3111 the
+    // coincident global window would have fail-fasted this critical too.
+    const bResult = await gate.gate(async () => 'B-sent', {
+      chat_id: 'B',
+      priorityClass: 'critical',
+    })
+    expect(bResult).toBe('B-sent')
+    expect(gate.stats().global.failedFast).toBe(0)
+    expect(gate.stats().global.sent).toBe(1)
+
+    // A chat:A critical IS fail-fasted — its window exceeds the ceiling.
+    let caught: unknown
+    await gate
+      .gate(async () => 'A-sent', { chat_id: 'A', priorityClass: 'critical' })
+      .catch((e) => {
+        caught = e
+      })
+    expect(isFloodWaitActiveError(caught)).toBe(true)
+    expect(gate.stats().global.failedFast).toBe(1)
+    // chat:B's critical really was the only additional send.
+    expect(gate.stats().global.sent).toBe(1)
+  })
+
+  it('a global 429 (no chat scope) still opens the global window and suppresses everywhere', async () => {
+    const clock = new FakeClock()
+    const opened: string[] = []
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      onWindowOpen: (scopeKey) => opened.push(scopeKey),
+    })
+
+    // A 429 on a call with NO chat_id → the evidence IS global.
+    const floodErr = floodErrUntil(HOUR)
+    await expect(
+      gate.gate(
+        async () => {
+          throw floodErr
+        },
+        { priorityClass: 'critical' },
+      ),
+    ).rejects.toBe(floodErr)
+
+    expect(opened).toEqual(['global'])
+    // An unrelated chat's cosmetic sheds — global covers every scope.
+    const shed = await gate.gate(async () => 'x', { chat_id: 'Z', priorityClass: 'cosmetic' })
+    expect(shed).toBe(SEND_GATE_SHED)
+    expect(gate.stats().global.shed).toBe(1)
+  })
+
+  it('conservativeGlobalFloodScope restores the pre-#3111 always-open-global posture', async () => {
+    const clock = new FakeClock()
+    const opened: string[] = []
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      conservativeGlobalFloodScope: true,
+      onWindowOpen: (scopeKey) => opened.push(scopeKey),
+    })
+
+    const floodErr = floodErrUntil(HOUR)
+    await expect(
+      gate.gate(
+        async () => {
+          throw floodErr
+        },
+        { chat_id: 'A', priorityClass: 'critical' },
+      ),
+    ).rejects.toBe(floodErr)
+
+    // Conservative posture: a chat-bound 429 ALSO opens the global window.
+    expect(opened.sort()).toEqual(['chat:A', 'global'])
+  })
+
+  it('openScopedFloodWindows (the gateway onFloodWait seam) opens scope-precise windows', async () => {
+    const clock = new FakeClock()
+    const opened: string[] = []
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      onWindowOpen: (scopeKey) => opened.push(scopeKey),
+    })
+
+    // Simulates the gateway's onFloodWait hook for a SHORT slept-and-retried 429
+    // on a supergroup chat — the gate's own FLOOD_WAIT_ACTIVE catch never fires
+    // for those, so this seam must carry the scope precision.
+    gate.openScopedFloodWindows({ chat_id: '9', chatType: 'supergroup' }, HOUR)
+    expect(opened.sort()).toEqual(['chat:9', 'group:9'])
+
+    // A no-chat-scope 429 opens global.
+    opened.length = 0
+    gate.openScopedFloodWindows(undefined, HOUR)
+    expect(opened).toEqual(['global'])
+  })
+
+  it('openScopedFloodWindows is a pure no-op when the gate is disabled', async () => {
+    const clock = new FakeClock()
+    const opened: string[] = []
+    const gate = createSendGate({
+      enabled: false,
+      clock,
+      onWindowOpen: (scopeKey) => opened.push(scopeKey),
+    })
+    gate.openScopedFloodWindows({ chat_id: 'A' }, HOUR)
+    gate.openScopedFloodWindows(undefined, HOUR)
+    expect(opened).toEqual([])
+  })
+})

package/telegram-plugin/send-gate-observability.test.ts

@@ -352,6 +352,146 @@ describe('createFloodWindowObserver — alerting', () => {
     expect(alerts).toHaveLength(1)
   })
 
+  // The operator-facing alert timestamps must render in the CONFIGURED local
+  // timezone, not UTC. The live incident that prompted this: a "flood ban
+  // cleared" card printed `2026-07-12T23:39:24Z to 2026-07-12T23:46:40Z UTC`,
+  // which is 9:39am–9:46am AEST in the fleet's configured zone. These assert
+  // the local rendering and would FAIL on the old `.toISOString()` output.
+  const OBSERVED = Date.parse('2026-07-12T23:39:24Z') // 2026-07-13 09:39 AEST
+  const UNTIL = Date.parse('2026-07-12T23:46:40Z') // 2026-07-13 09:46 AEST
+
+  it('renders the CLEARED card timestamps in the configured local tz (AEST), not UTC', async () => {
+    const clock = new TestClock()
+    const alerts: string[] = []
+    let windows: FloodWindowRecord[] = [
+      { scopeKey: 'global', untilTs: UNTIL, retryAfterSrc: '429', observedAt: OBSERVED },
+    ]
+    const obs = createFloodWindowObserver({
+      clock,
+      log: () => {},
+      stats: () => makeStats(),
+      readWindows: () => windows,
+      markAlerted: () => {},
+      sendAlert: async (t) => {
+        alerts.push(t)
+      },
+      operatorChatId: () => 'op',
+      alertThresholdMs: 60_000,
+      tz: 'Australia/Melbourne',
+    })
+
+    // Past threshold but global → operator unreachable → defer to close.
+    clock.cur = OBSERVED + 61_000
+    await obs.tick()
+    expect(alerts).toHaveLength(0)
+
+    // Window closes → deferred cleared card fires, in LOCAL time.
+    clock.cur = UNTIL + 1_000
+    windows = []
+    await obs.tick()
+    expect(alerts).toHaveLength(1)
+    expect(alerts[0]).toContain('flood ban cleared')
+    // Local-tz rendering: 9:39am to 9:46am AEST.
+    expect(alerts[0]).toContain('was banned from 9:39am to 9:46am AEST')
+    // And explicitly NOT the old UTC ISO output.
+    expect(alerts[0]).not.toContain('2026-07-12T23:39:24Z')
+    expect(alerts[0]).not.toContain('UTC')
+  })
+
+  it('renders the ACTIVE card clear-time in the configured local tz (AEST), not UTC', async () => {
+    const clock = new TestClock()
+    const alerts: string[] = []
+    let windows: FloodWindowRecord[] = [
+      // A far-future untilTs so the window stays open; a non-operator chat so
+      // the immediate-delivery branch fires (openAlertText).
+      { scopeKey: 'chat:other', untilTs: UNTIL, retryAfterSrc: '429', observedAt: OBSERVED },
+    ]
+    const obs = createFloodWindowObserver({
+      clock,
+      log: () => {},
+      stats: () => makeStats(),
+      readWindows: () => windows,
+      markAlerted: (scope, at) => {
+        windows = windows.map((w) => (w.scopeKey === scope ? { ...w, alertedAt: at } : w))
+      },
+      sendAlert: async (t) => {
+        alerts.push(t)
+      },
+      operatorChatId: () => 'op',
+      alertThresholdMs: 60_000,
+      tz: 'Australia/Melbourne',
+    })
+
+    clock.cur = OBSERVED + 61_000
+    await obs.tick()
+    expect(alerts).toHaveLength(1)
+    expect(alerts[0]).toContain('flood ban active')
+    // "expected to clear at 9:46am AEST" — local wall-clock, not UTC ISO.
+    expect(alerts[0]).toContain('expected to clear at 9:46am AEST')
+    expect(alerts[0]).not.toContain('2026-07-12T23:46:40Z')
+    expect(alerts[0]).not.toContain('UTC')
+  })
+
+  it('defaults to UTC wording when no tz is configured (backward compat)', async () => {
+    const clock = new TestClock()
+    const alerts: string[] = []
+    let windows: FloodWindowRecord[] = [
+      { scopeKey: 'global', untilTs: UNTIL, retryAfterSrc: '429', observedAt: OBSERVED },
+    ]
+    const obs = createFloodWindowObserver({
+      clock,
+      log: () => {},
+      stats: () => makeStats(),
+      readWindows: () => windows,
+      markAlerted: () => {},
+      sendAlert: async (t) => {
+        alerts.push(t)
+      },
+      operatorChatId: () => 'op',
+      alertThresholdMs: 60_000,
+      // no tz → UTC
+    })
+    clock.cur = OBSERVED + 61_000
+    await obs.tick()
+    clock.cur = UNTIL + 1_000
+    windows = []
+    await obs.tick()
+    expect(alerts).toHaveLength(1)
+    // UTC fallback: 11:39pm to 11:46pm UTC on 2026-07-12.
+    expect(alerts[0]).toContain('11:39pm to 11:46pm UTC')
+  })
+
+  it('spans the local date when a window crosses local midnight', async () => {
+    const clock = new TestClock()
+    const alerts: string[] = []
+    // 2026-07-13T13:55:00Z .. 2026-07-13T14:05:00Z = 11:55pm 13 Jul .. 12:05am 14 Jul AEST.
+    const obsStart = Date.parse('2026-07-13T13:55:00Z')
+    const obsEnd = Date.parse('2026-07-13T14:05:00Z')
+    let windows: FloodWindowRecord[] = [
+      { scopeKey: 'global', untilTs: obsEnd, retryAfterSrc: '429', observedAt: obsStart },
+    ]
+    const obs = createFloodWindowObserver({
+      clock,
+      log: () => {},
+      stats: () => makeStats(),
+      readWindows: () => windows,
+      markAlerted: () => {},
+      sendAlert: async (t) => {
+        alerts.push(t)
+      },
+      operatorChatId: () => 'op',
+      alertThresholdMs: 60_000,
+      tz: 'Australia/Melbourne',
+    })
+    clock.cur = obsStart + 61_000
+    await obs.tick()
+    clock.cur = obsEnd + 1_000
+    windows = []
+    await obs.tick()
+    expect(alerts).toHaveLength(1)
+    expect(alerts[0]).toContain('13 Jul 11:55pm to 14 Jul 12:05am AEST')
+  })
+
   it('does not alert for msg-edit (cosmetic) scopes', async () => {
     const clock = new TestClock()
     const alerts: string[] = []

package/telegram-plugin/send-gate-observability.ts

@@ -29,14 +29,15 @@
  *     "was banned from X to Y" alert when the window CLOSES (or as soon as the
  *     operator chat becomes reachable again).
  *
- * STATUS OF THE IMMEDIATE PATH (today vs. after #3111)
- * ----------------------------------------------------
- * The immediate-delivery branch is present and unit-tested, but it does NOT
- * fire in production yet: `openScopedWindowsForOpts` opens a coincident `global`
- * window on every 429, so the operator chat is always "covered" while any ban is
- * active and every alert defers to close. It becomes live once #3111 makes
- * `onFloodWait` scope-precise. Until then the operator is alerted at window
- * CLOSE — once per incident, all scopes coalesced into one card (M1, #3112).
+ * STATUS OF THE IMMEDIATE PATH (live since #3111)
+ * -----------------------------------------------
+ * The immediate-delivery branch is present, unit-tested, AND now fires in
+ * production: as of #3111 a chat-scoped 429 opens ONLY that chat's window (no
+ * coincident `global`), so when a ban covers `chat:<other>` while the operator's
+ * own chat is clear, the alert is delivered IMMEDIATELY rather than deferred to
+ * close. A genuinely global 429 still opens `global`, so the operator chat is
+ * "covered" and the alert defers to close — once per incident, all scopes
+ * coalesced into one card (M1, #3112).
  *
  * At-most-once is anchored by the persisted `alertedAt` (survives restart). The
  * deferred close-alert is best-effort at-least-once: if the gateway is down for
@@ -53,6 +54,7 @@
 
 import type { Clock, SendGateStats } from './send-gate.js'
 import type { FloodWindowRecord } from './flood-circuit-breaker.js'
+import { fmtLocalClock, fmtLocalDate, localDay, tzAbbrev } from './shared/local-time.js'
 
 /** One-line, human-scannable summary of the gate counters + global fill. */
 export function formatStatsLine(stats: SendGateStats): string {
@@ -153,6 +155,14 @@ export interface FloodWindowObserverConfig {
   operatorChatId?: () => string | undefined
   /** Ms a window must be open before it earns an alert. Default 60_000. */
   alertThresholdMs?: number
+  /**
+   * IANA timezone (e.g. `Australia/Melbourne`) for rendering the operator-facing
+   * alert timestamps in local wall-clock time instead of UTC. The gateway sources
+   * this from `SWITCHROOM_TIMEZONE ?? TZ` (the same env the config cascade bakes
+   * into every agent service — see `src/config/timezone.ts`). Defaults to `'UTC'`
+   * so a missing tz degrades to the previous behaviour rather than throwing.
+   */
+  tz?: string
 }
 
 export interface FloodWindowObserver {
@@ -160,11 +170,44 @@ export interface FloodWindowObserver {
   tick(): Promise<void>
 }
 
-/** Human-readable ISO-ish timestamp (UTC, second precision) for alert wording. */
-function fmtTs(ms: number): string {
-  // Strip the milliseconds (`.\d{3}`) for second precision — this also covers
-  // the `.000` case, so no separate replace is needed.
-  return new Date(ms).toISOString().replace(/\.\d{3}/, '')
+// ─── Operator-facing local-time formatting ──────────────────────────────────
+// Operator alerts (openAlertText / closeAlertText) render timestamps in the
+// operator's CONFIGURED timezone, not UTC — a "was banned from 9:39am to 9:46am
+// AEST" reads at a glance where a raw `2026-07-12T23:39:24Z UTC` does not. The
+// machine-facing snapshot LOG lines (config.log → gateway-supervisor.log) keep
+// their epoch/ISO wording; only the chat/card text is localized.
+//
+// The four wall-clock primitives (fmtLocalClock / fmtLocalDate / localDay /
+// tzAbbrev) now live in shared/local-time.ts so the humanized LLM-error card
+// renders timestamps through the SAME source of truth. The two composers below
+// (fmtLocalStamp / fmtLocalRange) stay here — they are this module's own wording.
+
+/**
+ * A single operator-facing local timestamp with tz suffix, e.g. `9:46am AEST`.
+ * When `refMs` is on a different local calendar day (or omitted), the date is
+ * prepended (`12 Jul 11:52pm AEST`) so a day-spanning window is unambiguous.
+ */
+function fmtLocalStamp(ms: number, tz: string, refMs?: number): string {
+  const clock = fmtLocalClock(ms, tz)
+  const sameDay = refMs != null && localDay(ms, tz) === localDay(refMs, tz)
+  const body = sameDay ? clock : `${fmtLocalDate(ms, tz)} ${clock}`
+  return `${body} ${tzAbbrev(ms, tz)}`
+}
+
+/**
+ * A local time RANGE with a single tz suffix, e.g. `9:39am to 9:46am AEST`.
+ * Same-local-day windows drop the redundant start date; day-spanning windows
+ * carry the date on each end (`12 Jul 11:59pm to 13 Jul 12:04am AEST`).
+ */
+function fmtLocalRange(startMs: number, endMs: number, tz: string): string {
+  const sameDay = localDay(startMs, tz) === localDay(endMs, tz)
+  if (sameDay) {
+    return `${fmtLocalClock(startMs, tz)} to ${fmtLocalClock(endMs, tz)} ${tzAbbrev(endMs, tz)}`
+  }
+  return (
+    `${fmtLocalDate(startMs, tz)} ${fmtLocalClock(startMs, tz)} to ` +
+    `${fmtLocalDate(endMs, tz)} ${fmtLocalClock(endMs, tz)} ${tzAbbrev(endMs, tz)}`
+  )
 }
 
 function fmtDur(ms: number): string {
@@ -186,6 +229,7 @@ export function createFloodWindowObserver(
   config: FloodWindowObserverConfig,
 ): FloodWindowObserver {
   const alertThresholdMs = config.alertThresholdMs ?? 60_000
+  const tz = config.tz ?? 'UTC'
   // Full records seen on the previous tick, keyed by scope (close detection).
   let lastSeen = new Map<string, FloodWindowRecord>()
   // First tick after boot: any window already present was loaded from disk
@@ -232,7 +276,7 @@ export function createFloodWindowObserver(
     const openFor = fmtDur(now - w.observedAt)
     return (
       `⚠️ Telegram flood ban active (scope \`${w.scopeKey}\`). ` +
-      `Open for ${openFor}, expected to clear at ${fmtTs(w.untilTs)} UTC. ` +
+      `Open for ${openFor}, expected to clear at ${fmtLocalStamp(w.untilTs, tz, now)}. ` +
       `Outbound to that scope is being suppressed.`
     )
   }
@@ -250,7 +294,7 @@ export function createFloodWindowObserver(
     const plural = recs.length > 1 ? 's' : ''
     return (
       `⚠️ Telegram flood ban cleared (scope${plural} ${scopes}). ` +
-      `The bot was banned from ${fmtTs(observedAt)} to ${fmtTs(untilTs)} UTC ` +
+      `The bot was banned from ${fmtLocalRange(observedAt, untilTs, tz)} ` +
       `(~${fmtDur(untilTs - observedAt)}). Some outbound messages during that ` +
       `window were suppressed.`
     )
@@ -312,11 +356,12 @@ export function createFloodWindowObserver(
       if (w.alertedAt != null) continue
       if (now - w.observedAt < alertThresholdMs) continue
       if (operatorReachable && !coversOperator(w, operatorChatId)) {
-        // NOTE (M1, #3112): this immediate-delivery branch is currently
-        // UNREACHABLE for recorder-produced state — `openScopedWindowsForOpts`
-        // opens a coincident `global` window on every 429, so `operatorReachable`
-        // is always false while any ban is active. It goes live once #3111 makes
-        // `onFloodWait` scope-precise. Kept + unit-tested as forward-looking.
+        // NOTE (M1, #3112 / #3111): this immediate-delivery branch is now LIVE
+        // for recorder-produced state. Since #3111 a chat-scoped 429 opens only
+        // that chat's window (no coincident `global`), so when a ban covers a
+        // chat OTHER than the operator's, `operatorReachable` is true and the
+        // alert is delivered here rather than deferred to close. A genuinely
+        // global 429 still opens `global`, keeping the operator "covered".
         // NOTE (L1, #3112): send-first, then persist `alertedAt`. A crash between
         // the delivered card and the disk write re-alerts on restart — a benign
         // duplicate. Deliberate: send-first guarantees an alert is never LOST,

package/telegram-plugin/send-gate.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest'
-import { createSendGate, sendGateEnabledFromEnv, type Clock } from './send-gate.js'
+import {
+  createSendGate,
+  sendGateEnabledFromEnv,
+  sendGateConfigFromEnv,
+  SEND_GATE_DEFAULTS,
+  type Clock,
+} from './send-gate.js'
 
 /**
  * Deterministic fake clock. `sleep()` registers a wake at `now + ms`;
@@ -117,6 +123,142 @@ describe('send-gate: feature flag', () => {
   })
 })
 
+describe('send-gate: SEND_GATE_DEFAULTS (compile-time default PIN)', () => {
+  it('pins the exact default rate limits — a drive-by change fails here', () => {
+    // Load-bearing PIN: these are the values createSendGate falls back to when a
+    // knob is unset, i.e. today's shipped behaviour. If any of these numbers
+    // changes, that is a real behaviour change and must be a deliberate,
+    // reviewed edit — not a silent drift. (#3084 send-gate config PR.)
+    expect(SEND_GATE_DEFAULTS).toEqual({
+      globalPerSec: 25,
+      globalBurst: 4,
+      perChatPerSec: 1,
+      perChatBurst: 3,
+      perGroupPerMin: 18,
+      perGroupBurst: 2,
+      editFloorMs: 1500,
+    })
+  })
+})
+
+describe('send-gate: sendGateConfigFromEnv (yaml → env → createSendGate)', () => {
+  const E = (o: Record<string, string | undefined>) => o as unknown as NodeJS.ProcessEnv
+
+  it('maps every SWITCHROOM_TG_SEND_GATE_* env to the exact createSendGate field', () => {
+    // The gateway spreads this object straight into createSendGate({...}), so
+    // asserting the returned slice IS asserting what createSendGate receives.
+    const cfg = sendGateConfigFromEnv(
+      E({
+        SWITCHROOM_TG_SEND_GATE_ENABLED: '1',
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_PER_SEC: '40',
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_BURST: '6',
+        SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC: '2',
+        SWITCHROOM_TG_SEND_GATE_PER_CHAT_BURST: '5',
+        SWITCHROOM_TG_SEND_GATE_PER_GROUP_PER_MIN: '30',
+        SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST: '4',
+        SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '2000',
+      }),
+    )
+    expect(cfg).toEqual({
+      enabled: true,
+      globalPerSec: 40,
+      globalBurst: 6,
+      perChatPerSec: 2,
+      perChatBurst: 5,
+      perGroupPerMin: 30,
+      perGroupBurst: 4,
+      editFloorMs: 2000,
+    })
+  })
+
+  it('accepts a fractional per-sec rate (rates are not integers)', () => {
+    const cfg = sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC: '0.5' }))
+    expect(cfg.perChatPerSec).toBe(0.5)
+  })
+
+  it('unset knobs are ABSENT so createSendGate applies SEND_GATE_DEFAULTS (no behaviour change)', () => {
+    const cfg = sendGateConfigFromEnv(E({}))
+    // Only enabled is present; every rate field is omitted → default fallback.
+    expect(cfg).toEqual({ enabled: true })
+    // And the gate built from it actually pours in the pinned defaults.
+    const gate = createSendGate({ ...cfg, clock: new FakeClock() })
+    // enabled default is ON (escape hatch, not opt-in).
+    expect(gate.stats().enabled).toBe(true)
+  })
+
+  it('drops malformed / wedge-inducing env values back to the default (defensive net)', () => {
+    // The LOUD rejection lives in the Zod config schema; a hand-set bad env must
+    // never wedge sends, so it falls back to undefined → compile-time default.
+    const cfg = sendGateConfigFromEnv(
+      E({
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_PER_SEC: '0', // ≤0 → dropped
+        SWITCHROOM_TG_SEND_GATE_PER_CHAT_BURST: '-3', // negative → dropped
+        SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST: '2.5', // non-int → dropped
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_BURST: 'nonsense', // NaN → dropped
+      }),
+    )
+    expect(cfg).toEqual({ enabled: true })
+  })
+
+  it('edit_floor_ms accepts 0 (disables the floor) but not negatives', () => {
+    expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '0' })).editFloorMs).toBe(0)
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '-1' })).editFloorMs,
+    ).toBeUndefined()
+  })
+
+  it('maps the #3111 conservative-global flood-scope break-glass flag', () => {
+    // Unset ⇒ absent (scope-precise default; createSendGate falls back to false).
+    expect(
+      sendGateConfigFromEnv(E({})).conservativeGlobalFloodScope,
+    ).toBeUndefined()
+    // On-values ⇒ true (restore pre-#3111 always-open-global posture).
+    for (const on of ['1', 'true', 'on', 'yes']) {
+      expect(
+        sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL: on }))
+          .conservativeGlobalFloodScope,
+      ).toBe(true)
+    }
+    // Off-values ⇒ explicit false.
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL: '0' }))
+        .conservativeGlobalFloodScope,
+    ).toBe(false)
+    // Unrecognised ⇒ absent (defensive net).
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL: 'nonsense' }))
+        .conservativeGlobalFloodScope,
+    ).toBeUndefined()
+  })
+
+  describe('enabled precedence: break-glass valve > config > default-on', () => {
+    it('config send_gate.enabled decides when the env valve is unset', () => {
+      expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_ENABLED: '0' })).enabled).toBe(false)
+      expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_ENABLED: '1' })).enabled).toBe(true)
+      expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_ENABLED: 'off' })).enabled).toBe(false)
+    })
+
+    it('the SWITCHROOM_TELEGRAM_SEND_GATE valve ALWAYS wins when explicitly set', () => {
+      // valve off beats config on
+      expect(
+        sendGateConfigFromEnv(
+          E({ SWITCHROOM_TELEGRAM_SEND_GATE: '0', SWITCHROOM_TG_SEND_GATE_ENABLED: '1' }),
+        ).enabled,
+      ).toBe(false)
+      // valve on beats config off
+      expect(
+        sendGateConfigFromEnv(
+          E({ SWITCHROOM_TELEGRAM_SEND_GATE: '1', SWITCHROOM_TG_SEND_GATE_ENABLED: '0' }),
+        ).enabled,
+      ).toBe(true)
+    })
+
+    it('both unset ⇒ enabled (ON by default, unchanged)', () => {
+      expect(sendGateConfigFromEnv(E({})).enabled).toBe(true)
+    })
+  })
+})
+
 describe('send-gate: global bucket', () => {
   it('admits up to capacity immediately, then paces the rest by refill', async () => {
     const clock = new FakeClock()