switchroom 0.18.11 → 0.18.13

package/telegram-plugin/session-tail.ts

@@ -41,7 +41,8 @@ function isMultiAgentEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   return env.PROGRESS_CARD_MULTI_AGENT !== '0'
 }
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
-import { createToolLabelSidecar, type ToolLabelSidecar } from './tool-label-sidecar.js'
+import { isTransientUpstreamSignal } from './model-unavailable.js'
+import { createToolLabelSidecar, type ToolLabelSidecar, type SidecarOptions } from './tool-label-sidecar.js'
 import { isModelSentinel } from './model-label.js'
 
 /** Match Claude Code's cli.js VX() function. */
@@ -668,13 +669,26 @@ export function detectErrorInTranscriptLine(
       typeof obj.apiErrorStatus === 'number' ? obj.apiErrorStatus : null
     const errStr = typeof obj.error === 'string' ? obj.error : ''
     const text = extractAssistantText(obj)
-    // A 429 in this shape is a subscription usage-limit hit (it carries
-    // a reset time) — classify it quota-exhausted so the operator event
-    // resolves to an auto-fallback-eligible kind. Other statuses fall
+    // A 429 in this shape is USUALLY a subscription usage-limit wall (it
+    // carries a reset time) — classify it quota-exhausted so the operator
+    // event resolves to an auto-fallback-eligible kind that always shows the
+    // "model unavailable" card. BUT Anthropic also emits a 429 for a TRANSIENT
+    // per-account burst / RPM throttle whose wording explicitly negates the
+    // account-quota reading ("This request would exceed your account's rate
+    // limit … not your usage limit"). That is a self-healing few-second throttle
+    // Claude Code retries internally — blanket-labeling it quota-exhausted fired
+    // a false scary card on the fleet (carrie incident, 2026-07-12). So a 429 is
+    // only quota-exhausted when it LACKS an explicit transient-burst marker;
+    // with one, classify it rate-limited so it takes the calm path (no card, no
+    // failover). Keyed on the explicit transient NEGATION (canonical list in
+    // model-unavailable.ts) — an ambiguous 429 that merely says "limit" stays
+    // quota-exhausted, biasing toward surfacing a real wall. Other statuses fall
     // through to the shared classifier.
     const kind: OperatorEventKind =
       status === 429
-        ? 'quota-exhausted'
+        ? isTransientUpstreamSignal(`${text}\n${errStr}`)
+          ? 'rate-limited'
+          : 'quota-exhausted'
         : classifyClaudeError({ type: errStr, status, message: text })
     // An `isApiErrorMessage` line is Claude surfacing the failure to the
     // user — terminal by construction (Claude writes this shape only
@@ -781,6 +795,13 @@ export interface SessionTailConfig {
   claudeHome?: string
   /** How often to re-scan for a new active session file (ms). Default 500. */
   rescanIntervalMs?: number
+  /**
+   * Idle window before an inactive sub-agent FSWatcher (and its PreToolUse
+   * sidecar) is reaped, in ms. Defaults to 5 minutes — well past the 99th-
+   * percentile sub-agent completion time. Exposed only so tests can drive the
+   * reap deterministically without a 5-minute wall-clock wait.
+   */
+  subTailIdleReapMs?: number
   /** Optional logger. */
   log?: (msg: string) => void
   /** Called for each parsed event. */
@@ -791,6 +812,18 @@ export interface SessionTailConfig {
    * TODO(Phase 4b): wire this to the gateway's emitOperatorEvent pipeline.
    */
   onOperatorEvent?: (event: TailOperatorEvent) => void
+  /**
+   * PreToolUse sidecar factory. Defaults to the real `createToolLabelSidecar`;
+   * production never sets this. It exists as a dependency-injection seam so the
+   * M1 FD-leak reap test can drive a fake sidecar per session WITHOUT
+   * `vi.mock`-ing the shared `tool-label-sidecar` module: bun's `vi.mock` is
+   * process-global (not file-scoped like vitest), and the CI bun-test shard
+   * runs the whole `tests/` dir in ONE process, so a module-mock here would
+   * leak into the real `tool-label-sidecar.test.ts` suite and break it. This
+   * mirrors the repo's bun-safe injection precedent (`vault-write-posture`'s
+   * optional `deps` param).
+   */
+  createSidecar?: (opts: SidecarOptions) => ToolLabelSidecar
 }
 
 export interface SessionTailHandle {
@@ -887,6 +920,7 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
   // $TELEGRAM_STATE_DIR/tool-labels-<session_id>.jsonl. Each sub-agent
   // has its OWN sessionId (its jsonl filename stem), so we key by that.
   const sidecars = new Map<string, ToolLabelSidecar>()
+  const createSidecar = config.createSidecar ?? createToolLabelSidecar
   const stateDirForSidecar = process.env.TELEGRAM_STATE_DIR ?? null
   function sessionIdForFile(file: string | null): string | null {
     if (!file) return null
@@ -898,7 +932,7 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
     const existing = sidecars.get(sessionId)
     if (existing) return existing
     try {
-      const s = createToolLabelSidecar({ stateDir: stateDirForSidecar, sessionId })
+      const s = createSidecar({ stateDir: stateDirForSidecar, sessionId })
       sidecars.set(sessionId, s)
       // Real-time draft-mirror source: emit a `tool_label` event the moment
       // the hook writes a label (flush-independent), so the gateway can
@@ -913,6 +947,22 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
       return null
     }
   }
+  /**
+   * M1 FD-leak fix: stop and forget the PreToolUse sidecar for a session that
+   * has ended (a rotated-away parent session, or a reaped sub-agent). Each
+   * sidecar holds its own stat-poll timer (and, on real fs, a file handle);
+   * pre-fix they were only reaped in `stop()`, so every session rotation
+   * (`/clear`, compaction → new sessionId) and every finished sub-agent leaked
+   * one for the gateway's life. Idempotent — a no-op when the key is absent.
+   */
+  function stopSidecar(sessionId: string | null): void {
+    if (!sessionId) return
+    const s = sidecars.get(sessionId)
+    if (!s) return
+    try { s.stop() } catch { /* ignore */ }
+    sidecars.delete(sessionId)
+  }
+
   function decorate(ev: SessionEvent, sessionId: string | null): SessionEvent {
     if (!sessionId) return ev
     if (ev.kind !== 'tool_use' && ev.kind !== 'sub_agent_tool_use') return ev
@@ -1024,6 +1074,19 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
       try { watcher.close() } catch { /* ignore */ }
       watcher = null
     }
+    // M1 FD-leak fix: we are rotating the PARENT tail off `currentFile`; its
+    // PreToolUse sidecar is no longer needed (its watcher just closed). Reap it
+    // so `/clear`- and compaction-driven session rotations don't accumulate one
+    // idle sidecar poll-timer per rotation. Parent session ids are the JSONL
+    // stem (`<uuid>`); sub-agent sidecars are keyed by `agent-<id>` stems and
+    // owned by their sub-tail (reaped in `reapIdleSubTails`), so this never
+    // stops a sidecar a live sub-tail still depends on. A later re-attach to
+    // this same file transparently recreates the sidecar via `ensureSidecar`.
+    const rotatedAwaySid = sessionIdForFile(currentFile)
+    const nextSid = sessionIdForFile(file)
+    if (rotatedAwaySid != null && rotatedAwaySid !== nextSid) {
+      stopSidecar(rotatedAwaySid)
+    }
     currentFile = file
     const prior = fileCursors.get(file)
     if (prior != null) {
@@ -1113,7 +1176,12 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
    * very-long task (rescanSubagents picks the file back up on the
    * next tick if it grows).
    */
-  const IDLE_FSWATCH_TTL_MS = 5 * 60 * 1000
+  // Floor-clamp the reap window: a 0 / negative override would make
+  // `reapIdleSubTails` treat every live sub-tail as instantly idle
+  // (cutoff = Date.now() - 0 ≥ lastActivityAt), reaping every live
+  // sidecar on the first tick. Only tests set this today, but the clamp
+  // makes the footgun unreachable — the smallest sane window is 1s.
+  const IDLE_FSWATCH_TTL_MS = Math.max(1000, config.subTailIdleReapMs ?? 5 * 60 * 1000)
 
   function readSub(t: SubTail): void {
     if (stopped) return
@@ -1254,6 +1322,13 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
           try { t.watcher.close() } catch { /* ignore */ }
           t.watcher = null
         }
+        // M1 FD-leak fix: reap the sub-agent's PreToolUse sidecar alongside its
+        // file watcher. Sub-agent sidecars are keyed by the sub file's stem
+        // (`agent-<id>`), created lazily by `decorate` while reading the sub
+        // JSONL. Pre-fix `reapIdleSubTails` closed the sub-tail watcher but left
+        // the sidecar (and its poll timer) alive until `stop()`, so a long-lived
+        // agent leaked one sidecar per finished sub-agent.
+        stopSidecar(sessionIdForFile(t.file))
         subTails.delete(file)
         log?.(`session-tail: reaped idle sub ${t.agentId} (${file})`)
       }

package/telegram-plugin/shared/bot-runtime.ts

@@ -29,8 +29,9 @@ import { createHash } from 'crypto'
 import { AsyncLocalStorage } from 'async_hooks'
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
 import { createRetryApiCall } from '../retry-api-call.js'
-import { makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
+import { makeFloodWaitRecorder, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { shouldEmitTgPost } from './gw-trace-gate.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
 
@@ -115,9 +116,14 @@ export function installTgPostLogger(bot: Bot): void {
     const tagSuffix = formatTgPostTags(_getTgPostTags())
     try {
       const res = await prev(method, payload, signal)
-      process.stderr.write(
-        `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=ok err=- code=- desc=-${tagSuffix}\n`,
-      )
+      // #3025: suppress zero-signal per-poll heartbeats (getUpdates/getMe
+      // status=ok, one line per ~30s long-poll tick) unless the operator
+      // set SWITCHROOM_GW_TRACE. Errors and all other methods still log.
+      if (shouldEmitTgPost(method, 'ok')) {
+        process.stderr.write(
+          `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=ok err=- code=- desc=-${tagSuffix}\n`,
+        )
+      }
       return res
     } catch (err) {
       const errClass = err instanceof GrammyError
@@ -156,8 +162,14 @@ export function createRobustApiCall(opts: { floodStatePath?: string } = {}) {
     // #2923: persist every observed 429 flood-wait window so a restart during
     // the ban can suppress non-essential sends (boot cards) instead of feeding
     // the per-bot flood counter and prolonging the ban.
+    // #3084: and refuse to issue a call while that window is still open —
+    // otherwise the card heartbeats re-drive a request into the ban every
+    // few seconds once the policy stops sleeping long waits.
     ...(opts.floodStatePath
-      ? { onFloodWait: makeFloodWaitRecorder(opts.floodStatePath) }
+      ? {
+          onFloodWait: makeFloodWaitRecorder(opts.floodStatePath),
+          floodWaitRemainingMs: makeFloodWaitProbe(opts.floodStatePath),
+        }
       : {}),
   })
 }

package/telegram-plugin/shared/gw-trace-gate.ts

@@ -0,0 +1,105 @@
+/**
+ * Gateway trace verbosity gate (#3025).
+ *
+ * The gateway emits two families of high-frequency stderr trace lines that
+ * are pure per-poll noise on a healthy, idle agent:
+ *
+ *   - `tg-post method=getUpdates ... status=ok` / `method=getMe ... status=ok`
+ *     — one line per long-poll tick (~every 30s) from the tg-post
+ *     observability transformer in `bot-runtime.ts`.
+ *   - `gw-trace shadow event=tick effects=[] global=bridge_alive_idle ...`
+ *     — one line per delivery-machine TTL tick (~every 30s) from
+ *     `inbound-delivery-machine-shadow.ts`.
+ *
+ * With no log rotation these ungated lines grew gateway-supervisor.log to
+ * 555MB on clerk / 162MB on klanker and filled the host disk. They carry
+ * zero signal when nothing happened: a successful empty long-poll and an
+ * idle no-op tick.
+ *
+ * This module centralises the "should I emit a zero-signal trace line?"
+ * decision behind a single debug env flag so operators can turn the full
+ * firehose back on when actually debugging the delivery/poll path.
+ *
+ * Flag: set `SWITCHROOM_GW_TRACE=1` (or `true`/`yes`/`on`, any case) to
+ * restore every trace line unconditionally. Unset / any other value → zero-signal polling
+ * success + idle-tick lines are suppressed, while ALL error lines, all
+ * non-poll methods (sendMessage, editMessageText, ...), and every tick or
+ * event that produced a real effect or state change are still emitted.
+ *
+ * Read once at module init — the flag is a boot-time debug switch, not a
+ * hot-reloadable knob, so a cached read keeps the per-line cost at a
+ * single boolean check.
+ */
+
+/**
+ * Pure env-flag parse — exported so tests can exercise the parsing
+ * directly. Kept separate from the module-init read because the dual
+ * vitest/bun runner boundary means module-cache tricks
+ * (`vi.resetModules()` + re-import) don't work under bun's vitest shim;
+ * flag variants must be testable via explicit arguments.
+ */
+export function computeGwTraceVerbose(flag: string | undefined): boolean {
+  const v = (flag ?? '').trim().toLowerCase()
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on'
+}
+
+/** True when the operator opted into the full gateway trace firehose. */
+export const gwTraceVerbose: boolean = computeGwTraceVerbose(
+  process.env.SWITCHROOM_GW_TRACE,
+)
+
+/**
+ * Bot API methods whose successful long-poll ticks are zero-signal:
+ * `getUpdates` is the long-poll itself and `getMe` is the periodic
+ * identity refresh. A `status=ok` on either says only "polling is alive",
+ * which the gateway already reports once at startup. Errors on these
+ * methods are NOT suppressed (see `shouldEmitTgPost`).
+ */
+const ZERO_SIGNAL_POLL_METHODS = new Set(['getUpdates', 'getMe'])
+
+/**
+ * Decide whether a `tg-post` line should be written.
+ *
+ * Suppressed (unless `SWITCHROOM_GW_TRACE` is set):
+ *   - `status=ok` for `getUpdates` / `getMe` — the per-poll heartbeat.
+ *
+ * Always emitted:
+ *   - any `status=err` (real failures — the whole point of the log),
+ *   - every other method's `ok` line (sendMessage/editMessageText/... are
+ *     genuine outbound observability, #656/#657).
+ */
+export function shouldEmitTgPost(
+  method: string,
+  status: 'ok' | 'err',
+  verbose: boolean = gwTraceVerbose,
+): boolean {
+  if (verbose) return true
+  if (status === 'err') return true
+  return !ZERO_SIGNAL_POLL_METHODS.has(method)
+}
+
+/**
+ * Decide whether a `gw-trace shadow` line should be written.
+ *
+ * Suppressed (unless `SWITCHROOM_GW_TRACE` is set):
+ *   - `event=tick` that produced NO effects AND left the machine in an
+ *     idle global state (`bridge_alive_idle` / `bridge_dead`) — the
+ *     no-op TTL heartbeat.
+ *
+ * Always emitted:
+ *   - any non-tick event (real inbound/turn/bridge activity),
+ *   - any tick that produced effects (e.g. a TTL turn expiry) or that
+ *     landed the machine in `bridge_alive_in_turn`.
+ */
+export function shouldEmitShadowTrace(
+  eventKind: string,
+  effectCount: number,
+  globalKind: string,
+  verbose: boolean = gwTraceVerbose,
+): boolean {
+  if (verbose) return true
+  if (eventKind !== 'tick') return true
+  if (effectCount > 0) return true
+  const idle = globalKind === 'bridge_alive_idle' || globalKind === 'bridge_dead'
+  return !idle
+}

package/telegram-plugin/status-pin-driver.ts

@@ -29,8 +29,8 @@
  * job spec.
  */
 
-import type { PinState, DesiredPin } from './status-pin.js'
-import { decidePinAction } from './status-pin.js'
+import type { PinState, DesiredPin, PinRightsCache } from './status-pin.js'
+import { decidePinAction, isPinRightsError } from './status-pin.js'
 
 /** Minimal subset of grammy's `bot.api` the pin driver depends on.
  *  Lets tests swap in a fake without dragging in the full Bot type. */
@@ -55,6 +55,16 @@ export interface ReconcilePinArgs {
   desired: DesiredPin
   /** Optional API-failure observer. Default: silent. */
   onError?: (phase: 'pin' | 'unpin', err: unknown) => void
+  /** Optional per-process rights-aware negative cache (issue #3024). When a
+   *  pin attempt fails with the permanent "not enough rights" 400, the chat is
+   *  recorded and all subsequent pin attempts in it are skipped (no API call,
+   *  no log). Omit to disable the cache entirely (the pre-#3024 behaviour). */
+  rightsCache?: PinRightsCache
+  /** Called EXACTLY ONCE per chat, the first time that chat is recorded as
+   *  pin-incapable. Lets the caller emit a single warn line instead of the
+   *  per-attempt `status-pin pin failed` spam. Only fires when `rightsCache`
+   *  is supplied. */
+  onPinRightsDisabled?: (chatId: string) => void
 }
 
 /**
@@ -77,10 +87,26 @@ export async function reconcilePin(
   if (action.kind === 'noop') return args.prevState
 
   if (action.kind === 'unpin') {
-    try {
-      await args.api.unpinChatMessage(args.chatId, action.messageId)
-    } catch (err) {
-      args.onError?.('unpin', err)
+    // Skip the unpin API call in a chat the bot can't manage pins in — the
+    // call would fail with the same rights 400 and spam the log. The claim is
+    // dropped either way (below), so skipping is safe.
+    if (!args.rightsCache?.isBlocked(args.chatId)) {
+      try {
+        await args.api.unpinChatMessage(args.chatId, action.messageId)
+      } catch (err) {
+        // Symmetric with the pin path below: a permanent rights 400 on UNPIN
+        // (rights revoked mid-session after we pinned) also enters the
+        // negative cache and logs once via onPinRightsDisabled — otherwise
+        // every later unpin attempt would burn an API call and spam
+        // `status-pin unpin failed` per attempt, the exact class this cache
+        // exists to kill (#3073 review finding). Claim is dropped regardless.
+        if (args.rightsCache && isPinRightsError(err)) {
+          const firstTime = args.rightsCache.block(args.chatId)
+          if (firstTime) args.onPinRightsDisabled?.(args.chatId)
+        } else {
+          args.onError?.('unpin', err)
+        }
+      }
     }
     // Drop the claim regardless of the unpin outcome. A stuck claim would
     // leave a permanent pin on a crash / out-of-band unpin — the exact
@@ -89,14 +115,33 @@ export async function reconcilePin(
   }
 
   // action.kind === 'pin' — pin an EXISTING message, silently.
+  // Rights-aware negative cache (issue #3024): if a prior attempt in this chat
+  // already failed with the permanent "not enough rights" 400, skip silently —
+  // no API call, no log. Don't claim the message (the pin never happened), so a
+  // later reconcile after a restart (cache cleared) can retry.
+  if (args.rightsCache?.isBlocked(args.chatId)) {
+    return args.prevState
+  }
   try {
     await args.api.pinChatMessage(args.chatId, action.messageId, {
       disable_notification: true,
     })
   } catch (err) {
-    args.onError?.('pin', err)
+    // A permanent pin-rights failure enters the negative cache and logs ONCE
+    // (via onPinRightsDisabled) — every subsequent attempt in this chat is then
+    // skipped above. Transient failures (429 / 5xx / network) are NOT cached
+    // and route through onError as before, preserving retry behaviour.
+    if (args.rightsCache && isPinRightsError(err)) {
+      const firstTime = args.rightsCache.block(args.chatId)
+      if (firstTime) args.onPinRightsDisabled?.(args.chatId)
+    } else {
+      args.onError?.('pin', err)
+    }
     // Don't claim a message we failed to pin — the next reconcile retries.
     return args.prevState
   }
+  // Pin succeeded — if this chat was previously cached as pin-incapable, rights
+  // were granted since; forget it so we resume normal behaviour immediately.
+  args.rightsCache?.clear(args.chatId)
   return { messageId: action.messageId }
 }

package/telegram-plugin/status-pin.ts

@@ -74,3 +74,84 @@ export function decidePinAction(
   // re-pins the new one on the next reconcile.
   return { kind: 'unpin', messageId: prev.messageId }
 }
+
+/** Extract a lowercased human description from any thrown value, preferring
+ *  grammy's structured `.description` (the wire text Telegram returned) and
+ *  falling back to `.message` / String(). Kept dependency-free — matches on
+ *  the wire text, never on a grammy class import. */
+function errorDescription(err: unknown): string {
+  if (err != null && typeof err === 'object') {
+    const o = err as { description?: unknown; message?: unknown }
+    if (typeof o.description === 'string' && o.description.length > 0) {
+      return o.description.toLowerCase()
+    }
+    if (typeof o.message === 'string' && o.message.length > 0) {
+      return o.message.toLowerCase()
+    }
+  }
+  return String(err).toLowerCase()
+}
+
+/**
+ * True when a pin/unpin failure is the PERMANENT "the bot lacks pin rights in
+ * this chat" class — Telegram returns this as a 400 (not a 403):
+ * "not enough rights to manage pinned messages in the chat". This is the one
+ * error class that will NOT self-heal on retry: the bot is simply not an admin
+ * (or lacks the "Pin messages" right) in that supergroup, and every subsequent
+ * pin attempt in the same chat fails identically until an admin grants the
+ * right (which only takes effect after a gateway restart re-reads chat perms).
+ *
+ * Transient classes (429 flood-wait, 5xx, network HttpError) are deliberately
+ * EXCLUDED — they must keep the existing retry behaviour, never enter the
+ * negative cache. Only this permanent-rights class is cacheable.
+ *
+ * The single source of truth for the pin-rights concept: the gateway's
+ * `unhandled-rejection-policy.ts` and the various edit-error classifiers each
+ * fold `not enough rights` into a broader boolean for their own purpose; this
+ * is the one helper dedicated to the pin negative-cache decision.
+ */
+export function isPinRightsError(err: unknown): boolean {
+  return errorDescription(err).includes('not enough rights')
+}
+
+/**
+ * Per-process, per-chat negative cache for chats the bot cannot pin in.
+ *
+ * When an auto status-pin attempt fails with the permanent pin-rights 400
+ * (`isPinRightsError`), the chat is recorded here as pin-incapable so the
+ * driver skips every subsequent auto-pin attempt in that chat — no wasted API
+ * call, no repeated `status-pin pin failed` log line (issue #3024: marko logged
+ * 41 identical pin-rights rejections in 48h, one per attempt).
+ *
+ * Deliberately IN-MEMORY / per-boot only: pin rights may be granted later, and
+ * Telegram surfaces the new permission to the bot only on a fresh chat-member
+ * fetch — a gateway restart. Clearing the cache on restart is therefore the
+ * correct re-enable trigger. An explicit `pin_message` tool success in a chat
+ * also clears its entry (rights were granted mid-session).
+ *
+ * Scope: the AUTO status-pin path only. The explicit `pin_message` MCP tool
+ * never consults this cache — it always attempts and surfaces the error to the
+ * agent as a normal tool error.
+ */
+export class PinRightsCache {
+  private readonly blocked = new Set<string>()
+
+  /** True when auto-pin should be skipped for this chat (already known bad). */
+  isBlocked(chatId: string): boolean {
+    return this.blocked.has(chatId)
+  }
+
+  /** Record a chat as pin-incapable. Returns `true` only the FIRST time a chat
+   *  is added, so the caller can log the warn line exactly once per chat. */
+  block(chatId: string): boolean {
+    if (this.blocked.has(chatId)) return false
+    this.blocked.add(chatId)
+    return true
+  }
+
+  /** Forget a chat (rights re-granted, e.g. an explicit pin later succeeded).
+   *  Returns `true` if an entry was actually removed. */
+  clear(chatId: string): boolean {
+    return this.blocked.delete(chatId)
+  }
+}