switchroom 0.18.17 → 0.18.19

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()