switchroom 0.18.17 → 0.18.18

package/telegram-plugin/premium-recovery.ts

@@ -0,0 +1,101 @@
+/**
+ * premium-recovery.ts — "your premium model is servable again" ping (pure layer).
+ *
+ * Companion to tier-downgrade.ts. When a premium `/model` selection (e.g.
+ * `/model fable`) is walled fleet-wide, the tier-downgrade tier resumes the
+ * turn on the configured default and tells the user to re-issue `/model fable`
+ * once it frees up (there is NO automatic revert — the override is session-
+ * scoped and dies on the downgrade restart). This module closes that loop with
+ * a HEADS-UP: the moment the premium tier can be served again, ping the chat
+ * ONCE with a one-tap "switch back" button.
+ *
+ * DETERMINISTIC recovery signal (P0 deterministic-controls — never model-
+ * decided). The signal is the auth-broker's own per-account eligibility, read
+ * off `list-state` (the SAME state the gateway's `runQuotaWatch` tick already
+ * polls every 15 min — no new poller, no broker change):
+ *   - `account.exhausted`      — live-authoritative `isAccountExhausted` verdict
+ *     (5h/7d wall or an unexpired `exhausted_until` mark).
+ *   - `account.premium_walled` — live-authoritative `isAccountPremiumWalled`
+ *     verdict; `isModelTierWalled` is a pure timestamp compare
+ *     (`premium_walled_until > now`) unless a fresher canary read the flagship
+ *     tier `allowed`. (src/auth/broker/model-tier-quota.ts / account-eligibility.ts.)
+ * The tier-downgrade fires from the account-swap `all-blocked` verdict — i.e.
+ * EVERY account was exhausted or premium-walled. Recovery is the exact
+ * complement: at least ONE account is neither. No clock of our own, no model
+ * judgement — the broker already decided; we read its decision.
+ *
+ * AT-MOST-ONCE. The gateway holds a consume-once `.premium-recovery` marker
+ * (session-model-file.ts) recording the dropped premium token + the chats to
+ * notify. `decidePremiumRecovery` is a pure predicate; the gateway clears the
+ * marker BEFORE sending (never-storm) and additionally takes a fleet-wide
+ * `claim-notification` so a bounce or a second gateway tick can't double-fire.
+ * The marker is also cleared the instant the user manually re-issues
+ * `/model <premium>` (no stale ping).
+ *
+ * PURE — no I/O, no clock. The gateway does the list-state read, the marker
+ * FS, the claim, and the send off these verdicts.
+ */
+
+/** The minimal per-account eligibility view the recovery predicate needs —
+ *  both fields are the broker's live-authoritative verdicts from `list-state`. */
+export interface AccountRecoveryView {
+  /** `isAccountExhausted` — a 5h/7d wall or an unexpired `exhausted_until` mark. */
+  exhausted: boolean
+  /** `isAccountPremiumWalled` — the flagship (`7d_oi`) tier wall verdict. */
+  premiumWalled: boolean
+}
+
+export interface PremiumRecoveryDecision {
+  /** Fire exactly one ping now (a marker is pending AND the premium tier is
+   *  servable again). The gateway clears the marker + claims before sending. */
+  fire: boolean
+  /** Why not, for the log (never surfaced to the user). */
+  reason: 'no-marker' | 'still-walled' | 'recovered'
+}
+
+/**
+ * Decide whether the premium tier has recovered for a pending downgrade.
+ * PURE. Fires iff a marker is pending AND at least one account can serve the
+ * premium tier again (neither exhausted nor premium-walled) — the exact
+ * complement of the `all-blocked` condition that fired the downgrade.
+ */
+export function decidePremiumRecovery(opts: {
+  hasMarker: boolean
+  accounts: ReadonlyArray<AccountRecoveryView>
+}): PremiumRecoveryDecision {
+  if (!opts.hasMarker) return { fire: false, reason: 'no-marker' }
+  const servable = opts.accounts.some((a) => !a.exhausted && !a.premiumWalled)
+  return servable
+    ? { fire: true, reason: 'recovered' }
+    : { fire: false, reason: 'still-walled' }
+}
+
+export interface PremiumRecoveryPing {
+  /** Telegram-formatted (rich-markdown) body. */
+  text: string
+  /** Inline-keyboard button label. */
+  buttonText: string
+}
+
+/**
+ * The user-facing recovery ping. PURE + deterministic so the wording + button
+ * are pinned by a test. Honest: the switch it offers is SESSION-SCOPED (the
+ * same `/model` semantics as everywhere else — it reverts on the next restart),
+ * so it never promises a durable pin.
+ */
+export function renderPremiumRecoveryPing(premiumModel: string): PremiumRecoveryPing {
+  return {
+    text:
+      `✅ \`${premiumModel}\` is available again — tap to switch back to it for this session.`,
+    buttonText: `Switch to ${premiumModel}`,
+  }
+}
+
+/**
+ * The fleet-wide `claim-notification` key for a premium-recovery ping. Keyed on
+ * agent + the specific premium token so two different dropped models never
+ * dedup each other, and a bounce mid-window can't re-send the same one.
+ */
+export function premiumRecoveryClaimKey(agent: string, premiumModel: string): string {
+  return `premium-recovery:${agent}:${premiumModel}`
+}

package/telegram-plugin/raw-error-scrub.ts

@@ -0,0 +1,73 @@
+/**
+ * raw-error-scrub.ts — the ONE scrubber that removes raw-API-error bytes from a
+ * string before it reaches a user, shared by every surface that might print an
+ * error `detail`.
+ *
+ * Zero dependencies (a leaf module) so both the pure `operator-events.ts`
+ * renderer AND `llm-error-present.ts` can import it without a cycle. Anchored on
+ * the same markers as `looksLikeRawApiError` (pty-partial-handler.ts): the CLI's
+ * Python `· b'{…}'` byte-blob, a trailing `{"type":"error"…}` JSON object, and an
+ * `API Error:` prefix.
+ */
+
+/**
+ * Strip the raw-API-error bytes a source can smuggle into an otherwise-human
+ * string. Total — never throws; a clean human string passes through unchanged
+ * (modulo whitespace tidy-up).
+ */
+export function stripRawErrorBytes(raw: string): string {
+  if (typeof raw !== 'string' || raw.length === 0) return ''
+  let s = raw
+  // 1. `API Error:` / `API Error 429:` prefix anywhere.
+  s = s.replace(/API Error:?\s*\d*\s*/gi, ' ')
+  // 2. Python byte-blob render: ` b'{…}'` or ` b"{…}"` (the CLI's raw-body echo).
+  s = s.replace(/\bb'[^']*'/g, ' ')
+  s = s.replace(/\bb"[^"]*"/g, ' ')
+  // 3. A JSON error object `{"type":"error"…}` (or `'type': 'error'`) and
+  //    everything after it — these blobs are always trailing on the real lines,
+  //    and brace-balanced stripping is not worth the fragility.
+  s = s.replace(/[·\-\s]*\{[\s\S]*?["']type["']\s*:\s*["']error["'][\s\S]*$/i, ' ')
+  // 4. A bare leading/trailing JSON object with no human text around it.
+  s = s.replace(/^\s*\{[\s\S]*\}\s*$/g, ' ')
+  // 5. Tidy: collapse whitespace, drop dangling separators.
+  s = s.replace(/\s+/g, ' ').replace(/[·:\-\s]+$/g, '').replace(/^[·:\-\s]+/g, '').trim()
+  return s
+}
+
+/**
+ * Pull an Anthropic `request_id` out of a raw error string, or undefined. The
+ * id lives in the trailing byte-blob (`…,"request_id":"req_abc"}'`) and can sit
+ * far into a long body — see `truncateDetailPreservingRequestId`. Total.
+ */
+export function extractRequestId(raw: string): string | undefined {
+  if (typeof raw !== 'string' || raw.length === 0) return undefined
+  const m =
+    raw.match(/["']request[_-]?id["']\s*:\s*["']([A-Za-z0-9._-]+)["']/i) ??
+    raw.match(/\brequest[_-]?id[=:]\s*([A-Za-z0-9._-]+)/i)
+  return m ? m[1] : undefined
+}
+
+/**
+ * Truncate an error `detail` to `max` chars WITHOUT losing the `request_id`.
+ *
+ * Why this exists: the bridge forwards operator-event detail truncated to 1000
+ * chars (OPERATOR_EVENT_DETAIL_MAX), but the Anthropic `request_id` lives in the
+ * trailing byte-blob, which can sit PAST char 1000. A naive `slice(0, 1000)`
+ * drops it, so the cross-surface dedup gate silently degrades from the reliable
+ * `rid:` EXACT key to the coarse `${kind}:${agent}:${bucket}` key — collapsing
+ * two genuinely-distinct same-kind errors within 60s into one card.
+ *
+ * Fix: extract the id from the FULL body first; if the plain head would drop it,
+ * append `request_id=<id>` in the freed tail budget (`extractRequestId` matches
+ * that form), keeping the result ≤ `max`. Total — never throws.
+ */
+export function truncateDetailPreservingRequestId(detail: string, max: number): string {
+  if (typeof detail !== 'string') return ''
+  if (detail.length <= max) return detail
+  const rid = extractRequestId(detail)
+  const head = detail.slice(0, max)
+  if (rid == null || head.includes(rid)) return head
+  const suffix = ` request_id=${rid}`
+  const headBudget = Math.max(0, max - suffix.length)
+  return `${detail.slice(0, headBudget)}${suffix}`
+}

package/telegram-plugin/retry-api-call.ts

@@ -121,8 +121,14 @@ export interface RetryApiCallConfig {
    * a container restart during an active ban can suppress non-essential
    * sends (boot cards) instead of feeding the same per-bot-token flood
    * counter and prolonging the ban. Best-effort; a throw here is swallowed.
+   *
+   * The call's `opts` are passed through (#3111) so the hook can open a
+   * SCOPE-PRECISE send-gate window: this fires even for a SHORT slept-and-retried
+   * 429 that never throws `FLOOD_WAIT_ACTIVE`, so without the opts the gateway
+   * could only open a blanket `global` window for those. Existing callers that
+   * ignore the second argument are unaffected.
    */
-  onFloodWait?: (retryAfterSec: number) => void
+  onFloodWait?: (retryAfterSec: number, opts?: RetryCallOpts) => void
 }
 
 /**
@@ -353,7 +359,7 @@ export function createRetryApiCall(
           // Persist the flood window so a restart during the ban can suppress
           // non-essential sends instead of extending it (#2923 circuit breaker).
           try {
-            onFloodWait?.(retryAfter)
+            onFloodWait?.(retryAfter, opts)
           } catch {
             /* best-effort — never let the breaker hook break the retry path */
           }

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

@@ -566,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).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,