switchroom 0.18.17 → 0.18.19

package/telegram-plugin/permission-title.ts

@@ -20,7 +20,7 @@
 import { basename } from "node:path";
 import { escapeMarkdown } from "./card-format.js";
 import { prettyMcpServer, type ScopeOption } from "./permission-rule.js";
-import { redact } from "./secret-detect/redact.js";
+import { redact, REDACTED_MARKER } from "./secret-detect/redact.js";
 
 const COMMAND_TITLE_MAX = 48;
 const DESCRIPTION_LINE_MAX = 240;
@@ -35,6 +35,55 @@ const ARG_SUMMARY_MAX_KEYS = 4; // how many payload keys to surface on the card
 const ARG_VALUE_MAX = 40; // per-value truncation in the arg-summary line
 const ARG_SUMMARY_LINE_MAX = 180; // total cap for the arg-summary line
 
+/**
+ * Input keys that are routing / formatting / id noise, never operator-
+ * meaningful context. Stripped when synthesizing the fallback `context:`
+ * line (#3167) so it surfaces the substance (the reply text, the command,
+ * the query) and not `chat_id` / `format` / `disable_notification` chrome.
+ * `reason`/`why` are here too because their presence takes the `why:` path —
+ * they never reach the synthesizer.
+ */
+const CONTEXT_NOISE_KEYS = new Set([
+  "reason",
+  "why",
+  "chat_id",
+  "message_id",
+  "message_thread_id",
+  "thread_id",
+  "origin_turn_id",
+  "reply_to",
+  "quote",
+  "quote_text",
+  "format",
+  "parse_mode",
+  "disable_web_page_preview",
+  "disable_notification",
+  "protect_content",
+  "single_use",
+  "ack_text",
+  "inline_keyboard",
+  "file_id",
+]);
+
+/**
+ * Input keys whose VALUE is credential-shaped by name — hard-masked whole,
+ * never partially revealed (#3167 review). The token-shape detectors in
+ * `redact()` need a random-looking value to fire, so a low-entropy password
+ * or a short secret under one of these keys would otherwise slip through the
+ * synthesized `context:` line. Matching the key is the reliable signal.
+ */
+const SENSITIVE_VALUE_KEY_RE =
+  /token|secret|password|passwd|key|auth|dsn|conn|url|credential|cookie|session/i;
+
+/**
+ * Credential-bearing DSN schemes that `redactUrls()` (inside `redact()`) does
+ * NOT cover — it only handles http(s)/ws(s)/ftp. A `postgres://user:pass@host`
+ * DATABASE_URL is a real vault-key shape here, so mask the whole DSN when its
+ * authority carries a `user:pass@` credential (#3167 review).
+ */
+const NON_HTTP_DSN_RE =
+  /\b(?:postgres(?:ql)?|mysql|mariadb|redis|rediss|mongodb(?:\+srv)?|amqp|amqps):\/\/\S*@\S+/gi;
+
 /**
  * Human verb-phrases for switchroom-managed MCP tools. The raw
  * `mcp__<server>__<tool>` name is operator-hostile. Phrases are written
@@ -141,15 +190,23 @@ export function formatPermissionCardBody(opts: {
   // static schema description (#2469).
   const callerReason = callerSuppliedReason(opts.inputPreview);
   const rawWhy = (callerReason ?? "").replace(/\s+/g, " ").trim();
-  const truncatedWhy =
-    rawWhy.length > DESCRIPTION_LINE_MAX
-      ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
-      : rawWhy;
-  lines.push(
-    truncatedWhy.length > 0
-      ? `why: _${escapeTgHtml(truncatedWhy)}_`
-      : `why: _not provided_`,
-  );
+  if (rawWhy.length > 0) {
+    const truncatedWhy =
+      rawWhy.length > DESCRIPTION_LINE_MAX
+        ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
+        : rawWhy;
+    lines.push(`why: _${escapeTgHtml(truncatedWhy)}_`);
+  } else {
+    // No caller reason. Many tools (reply, react, edit_message, …) carry no
+    // `reason`/`why` argument at all, so a bare "why: not provided" gives the
+    // operator nothing to decide on — the post-rollout permission storm filled
+    // the chat with contentless cards (#3167). Fall back to an honest,
+    // redaction-safe `context:` line synthesized from the tool + its salient
+    // input, so the card always carries something meaningful. The distinct
+    // label keeps the agent's omission of a rationale visible (it is NOT a
+    // fabricated "why"), while still surfacing what the tool is about to do.
+    lines.push(`context: _${escapeTgHtml(synthesizeContext(opts.toolName, opts.inputPreview))}_`);
+  }
 
   // Third line (REST-wrapper MCP writes only): a redaction-safe summary of
   // the payload so the operator can see WHAT is being sent, not just the
@@ -597,6 +654,111 @@ function callerSuppliedReason(inputPreview: string | undefined): string | null {
   return null;
 }
 
+/**
+ * Honest, redaction-safe fallback for the card's rationale line when the
+ * caller supplied no `reason`/`why` (#3167). Synthesizes context from a
+ * summary of the tool's salient input fields — the reply text, the command,
+ * the search query — so the operator always has something to decide on
+ * instead of a contentless "not provided". Every value passes through
+ * `redact()`; ids / routing / formatting keys are stripped. Falls back to
+ * the natural action phrase when the input exposes nothing salient.
+ * Deterministic (no model in the loop): same input → same line. Exported
+ * for unit testing.
+ */
+export function synthesizeContext(
+  toolName: string,
+  inputPreview: string | undefined,
+): string {
+  const input = parseInput(inputPreview);
+  const summary = input ? salientInputSummary(input) : null;
+  // Prefer the salient input summary (the reply text, the query, the diff
+  // target) — the substance the title's verb-phrase does NOT already carry.
+  // When the input exposes nothing meaningful, fall back to the natural
+  // action so the line still names the tool rather than reading empty.
+  const base = summary ?? naturalAction(toolName, inputPreview);
+  // Acceptance criteria (#3167) call for "tool + summarized input +
+  // originating turn". When the call carries a forum-topic origin turn,
+  // append a compact reference so the operator can tie the card to the turn
+  // that spawned it. Kept short — it's a routing id, not prose.
+  const turnRef = input ? readString(input, "origin_turn_id") : null;
+  return turnRef ? `${base} · turn ${shortTurnRef(turnRef)}` : base;
+}
+
+/** Compact display form of an origin-turn id — the tail is the distinguishing
+ *  part; a full opaque id would swamp the line. */
+function shortTurnRef(turnId: string): string {
+  const t = turnId.trim();
+  return t.length <= 10 ? t : `…${t.slice(-8)}`;
+}
+
+/**
+ * A compact, redaction-safe summary of the operator-meaningful scalar fields
+ * of a tool input — used to build the synthesized `context:` line (#3167).
+ * Skips {@link CONTEXT_NOISE_KEYS} (ids/routing/formatting), surfaces up to
+ * {@link ARG_SUMMARY_MAX_KEYS} scalar `key: value` pairs (each redacted +
+ * truncated), and renders nested objects/arrays as the bare key name (no
+ * value dump — avoids leaking PII/secrets and oversized blobs). Returns null
+ * when nothing meaningful remains, so the caller falls back to the bare
+ * action phrase.
+ *
+ * Free-text fields (e.g. a reply `text`) surface as content — a conscious
+ * choice (#3167 review, LOW-1): the operator NEEDS to see *what* is being
+ * sent to judge the card. Exposure is bounded to {@link ARG_VALUE_MAX} chars
+ * and every value is redaction-passed via {@link redactSalientValue}, so a
+ * card can never leak more than the outbound reply already does in history
+ * (both use the same `redact()` chokepoint). We do not mask free text to a
+ * placeholder, which would gut the card's usefulness.
+ */
+function salientInputSummary(input: Record<string, unknown>): string | null {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (CONTEXT_NOISE_KEYS.has(key)) continue;
+    if (value == null) continue;
+    if (parts.length >= ARG_SUMMARY_MAX_KEYS) {
+      parts.push("…");
+      break;
+    }
+    if (typeof value === "object") {
+      parts.push(key); // nested object/array → key name only, never dumped
+      continue;
+    }
+    const shown = truncate(redactSalientValue(key, String(value)), ARG_VALUE_MAX);
+    if (shown.length === 0) continue;
+    parts.push(`${key}: ${shown}`);
+  }
+  if (parts.length === 0) return null;
+  const joined = parts.join(", ");
+  return joined.length > ARG_SUMMARY_LINE_MAX
+    ? joined.slice(0, ARG_SUMMARY_LINE_MAX - 1) + "…"
+    : joined;
+}
+
+/**
+ * Redact a single salient value for display on the synthesized `context:`
+ * line, given its input KEY (#3167 review). Three layers, defense-in-depth:
+ *
+ *   1. Hard-mask whole when the key is credential-shaped
+ *      ({@link SENSITIVE_VALUE_KEY_RE}) — the token-shape detectors need a
+ *      random-looking value, so a low-entropy password / short secret under a
+ *      `token`/`password`/`api_key` key would otherwise leak. The key name is
+ *      the reliable signal.
+ *   2. Mask non-http DSN credentials ({@link NON_HTTP_DSN_RE}) that
+ *      `redactUrls()` misses (postgres://user:pass@host, mysql://, redis://…).
+ *   3. Run `redact()` WITH the key restored as `key=value` context, so the
+ *      contextual detectors (`kv_entropy` / `env_key_value`) that require the
+ *      `key[:=]value` shape in one string can fire — then strip the synthetic
+ *      `key=` prefix. Redacting the BARE value (the pre-review bug) blinded
+ *      those detectors, since `redact()` deliberately excludes the
+ *      low-precision `generic_high_entropy` fallback.
+ */
+function redactSalientValue(key: string, value: string): string {
+  if (SENSITIVE_VALUE_KEY_RE.test(key)) return REDACTED_MARKER;
+  const dsnScrubbed = value.replace(NON_HTTP_DSN_RE, REDACTED_MARKER);
+  const scrubbed = redact(`${key}=${dsnScrubbed}`);
+  const prefix = `${key}=`;
+  return scrubbed.startsWith(prefix) ? scrubbed.slice(prefix.length) : scrubbed;
+}
+
 /**
  * Regex-based fallback to extract a `reason` or `why` value from a raw
  * (possibly truncated / invalid-JSON) inputPreview string. Mirrors

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([])
+  })
+})