switchroom 0.18.17 → 0.18.19

package/telegram-plugin/gateway/gateway.ts

@@ -184,6 +184,7 @@ import {
   selectHeldForRedelivery,
   holdReasonFor,
   heldRetryBackoffMs,
+  applyDeliveredHoldReset,
   type UndeliverableMark,
 } from './approval-hold.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
@@ -207,7 +208,7 @@ import {
   isPhotoDimensionRejectError,
   isFloodWaitActiveError,
 } from '../retry-api-call.js'
-import { createSendGate, sendGateEnabledFromEnv } from '../send-gate.js'
+import { createSendGate, sendGateConfigFromEnv } from '../send-gate.js'
 import { createStatsLogger, createFloodWindowObserver } from '../send-gate-observability.js'
 import { classifyPhotoFile, rerouteResultSuffix } from '../photo-precheck.js'
 import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
@@ -314,6 +315,11 @@ import {
   type OperatorEventKind,
 } from '../operator-events.js'
 import { recordOperatorEvent } from '../operator-events-history.js'
+import {
+  parseLlmError,
+  renderLlmErrorSafe,
+  decideErrorSurface,
+} from '../llm-error-present.js'
 import {
   formatModelUnavailableCard,
   resolveModelUnavailableFromOperatorEvent,
@@ -342,7 +348,7 @@ const REPLY_TO_TEXT_MAX = 200
 // #1161 silent-end fallback text now lives in ../silent-end.ts
 // (`silentEndFallbackText`, imported above) so the transport-boundary
 // tests exercise the real string — see PR #2892.
-import { splitMarkdownChunks, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { splitMarkdownChunks, repairEscapedWhitespace, normalizeParagraphBreaks, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { scrubVoice } from '../text-voice-scrub.js'
 import {
@@ -468,7 +474,13 @@ import {
   readConfiguredDefaultModel,
   writeSessionEffortFile,
   clearSessionEffortFile,
+  writePremiumRecoveryFile,
+  readPremiumRecoveryFile,
+  clearPremiumRecoveryFile,
 } from './session-model-file.js'
+import { runTierDowngrade } from './tier-downgrade-wiring.js'
+import { runPremiumRecoveryPing } from './premium-recovery-wiring.js'
+import { decidePremiumRecovery } from '../premium-recovery.js'
 import { discoverModels, selectModel } from '../../src/agents/model-picker.js'
 import { resolveMainModel, SWITCHROOM_DEFAULT_THINKING_EFFORT } from '../../src/agents/scaffold.js'
 import {
@@ -5468,8 +5480,14 @@ const recordFloodWindow = makeFloodWindowRecorder(FLOOD_WINDOWS_PATH)
 // ban never resends into an open window. onWindowOpen write-throughs every
 // runtime-opened window to FLOOD_WINDOWS_PATH; bootRamp starts the global
 // bucket at half capacity for 10s to absorb the boot-card burst.
+// Resolve enabled + the tunable rate limits (channels.telegram.send_gate.* →
+// SWITCHROOM_TG_SEND_GATE_* env) ONCE at boot. Unset knobs are absent, so
+// createSendGate applies SEND_GATE_DEFAULTS — omitting config = today's exact
+// behaviour. The SWITCHROOM_TELEGRAM_SEND_GATE break-glass valve still wins on
+// `enabled` when explicitly set (see sendGateConfigFromEnv precedence).
+const sendGateConfig = sendGateConfigFromEnv()
 const sendGate = createSendGate({
-  enabled: sendGateEnabledFromEnv(),
+  ...sendGateConfig,
   initialWindows: loadInitialFloodWindows(FLOOD_STATE_PATH, FLOOD_WINDOWS_PATH, Date.now()),
   bootRamp: {},
   onWindowOpen: (scopeKey, untilTs) => recordFloodWindow(scopeKey, untilTs),
@@ -5482,15 +5500,20 @@ const sendGate = createSendGate({
 const probeFloodWaitRemainingMs = makeFloodWaitProbe(FLOOD_STATE_PATH)
 const rawRobustApiCall = createRetryApiCall({
   log: (line) => process.stderr.write(line),
-  onFloodWait: (retryAfterSec) => {
+  onFloodWait: (retryAfterSec, opts) => {
     // #2923/#3094 — persist the single-object global window (probe reads this).
     makeFloodWaitRecorder(FLOOD_STATE_PATH)(retryAfterSec)
-    // #3084 PR 2 — also open a GLOBAL send-gate window so cosmetic traffic sheds
-    // for the ban's duration even on a SHORT (slept-and-retried) 429 that never
-    // throws FLOOD_WAIT_ACTIVE. Scope-precise windows are opened by the gate's
-    // own FLOOD_WAIT_ACTIVE catch (which has the call's opts).
+    // #3084 PR 2 / #3111 — also open SCOPE-PRECISE send-gate window(s) so cosmetic
+    // traffic sheds for the ban's duration even on a SHORT (slept-and-retried)
+    // 429 that never throws FLOOD_WAIT_ACTIVE. The retry policy now passes the
+    // call's `opts` (#3111) so this opens the FINEST scope the 429 implies —
+    // `chat:`/`group:`/`msg-edit:` for a chat-bound call, `global` only when the
+    // call carries no chat scope (genuinely global) — instead of a blanket
+    // `global` window that would suppress unrelated chats. This mirrors the
+    // gate's own FLOOD_WAIT_ACTIVE catch, which uses the same scope-precise
+    // opener for LONG bans.
     try {
-      sendGate.openFloodWindow('global', Date.now() + Math.max(0, retryAfterSec) * 1000)
+      sendGate.openScopedFloodWindows(opts, Date.now() + Math.max(0, retryAfterSec) * 1000)
     } catch {
       /* best-effort — never let the window hook break the retry path */
     }
@@ -5634,6 +5657,9 @@ const sendGateStatsLogger = createStatsLogger({
 const floodWindowObserver = createFloodWindowObserver({
   clock: { now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)) },
   log: (line) => process.stderr.write(line),
+  // Render the operator-facing flood alerts in the configured local timezone
+  // (same env the config cascade bakes into every agent — see timezone.ts).
+  tz: process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC',
   stats: () => sendGate.stats(),
   readWindows: (now) => readFloodWindows(FLOOD_WINDOWS_PATH, now),
   markAlerted: (scopeKey, alertedAt) =>
@@ -5654,7 +5680,7 @@ const floodWindowObserver = createFloodWindowObserver({
     )
   },
 })
-if (sendGateEnabledFromEnv()) {
+if (sendGateConfig.enabled) {
   const observeTimer = setInterval(() => {
     try {
       sendGateStatsLogger.tick()
@@ -6726,10 +6752,19 @@ function isAutoFallbackCooldownActive(_agentName: string, now: number): boolean
 
 async function editCardExpired(chatId: string, messageId: number | undefined, body: string): Promise<void> {
   if (messageId == null) return
-  await lockedBot.api
-    // allow-raw-bot-api: message-id-targeted edit (no thread to lose); best-effort card-expiry strip from the reaper (no grammy ctx). Dropping reply_markup strips the stale keyboard atomically with the text edit.
-    .editMessageText(chatId, messageId, richMessage(body), { reply_markup: { inline_keyboard: [] } })
-    .catch(() => {})
+  // #3084 bypass audit: this best-effort card-expiry strip (reaper + lazy
+  // sweeps, no grammy ctx) previously fired a RAW `lockedBot.api.editMessageText`
+  // OUTSIDE the send gate — a residual flood vector (a 429 here never reached
+  // `onFloodWait`, so the breaker stayed blind). Routed through `robustApiCall`
+  // (chat-lock → send-gate → retry/breaker) as a `cosmetic` edit carrying
+  // messageId+editPayload so it paces/sheds under pressure and its 429 records
+  // the flood window. Dropping reply_markup strips the stale keyboard atomically
+  // with the text edit; message-id-targeted so no thread to lose.
+  const text = richMessage(body)
+  await robustApiCall(
+    () => lockedBot.api.editMessageText(chatId, messageId, text, { reply_markup: { inline_keyboard: [] } }),
+    { chat_id: chatId, verb: 'card-expired.strip', priorityClass: 'cosmetic', messageId, editPayload: body },
+  ).catch(() => {})
 }
 
 function recordMissedApproval(opts: {
@@ -7073,20 +7108,13 @@ function postPermissionCard(
         const landedThreadId = sent.message_thread_id ?? undefined
         live.cards.push({ chatId, messageId: sent.message_id, threadId: landedThreadId })
         // The card LANDED — the operator can see and tap it, so the block is over.
-        // Drop the hold mark and reconcile the off-Telegram surface. (PR 3 also
-        // resets `startedAt` here: the TTL measures how long the operator had to
-        // answer, and until this moment they had nothing to answer.)
-        if (live.undeliverable != null) {
-          live.undeliverable = null
-          live.redeliveryFailures = 0
-          // RESET THE TTL CLOCK. Load-bearing, not cosmetic. `startedAt` is when
-          // the agent asked; the TTL measures how long the operator had to
-          // answer. Until this instant they had NOTHING to answer — the card did
-          // not exist in any chat. Without the reset, a card held through a 4.6h
-          // ban lands already-expired against a 60-min TTL and the very next
-          // reaper tick auto-denies it: we would have MOVED the silent denial,
-          // not removed it.
-          live.startedAt = Date.now()
+        // Drop the hold mark, reset the TTL clock, and reconcile the off-Telegram
+        // surface — as ONE shared decision (`applyDeliveredHoldReset`, #3128) that
+        // the outcome test's harness ALSO drives, so deleting the `startedAt` reset
+        // turns the behavioural `(d2)` test red instead of only a fragile grep.
+        // PR 3: the reset is load-bearing — the TTL measures how long the operator
+        // had to answer, and until this moment they had nothing to answer.
+        if (applyDeliveredHoldReset(live, Date.now())) {
           reconcileBlockedApprovals()
           process.stderr.write(
             `telegram gateway: permission-card RE-DELIVERED request=${requestId} ` +
@@ -7662,6 +7690,21 @@ const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
 function emitGatewayOperatorEvent(event: OperatorEvent): void {
   const { agent, kind } = event
 
+  // #llm-error-surfacing FIX 2 (secret leak): the operator-event cards are sent
+  // via a raw bot.api.sendRichMessage that BYPASSES the normal outbound redact
+  // chokepoint (normalizeOutboundBody → redact, outbound-send-path.ts). The only
+  // scrub the renderers apply is stripRawErrorBytes — a JSON-SHAPE scrub, NOT a
+  // secret scrubber — so a bearer token / `sk-…` key / url-embedded credential
+  // smuggled in an error `detail` would reach the operator card verbatim on the
+  // credentials-expired / credit-exhausted / unknown-4xx paths. Redact the detail
+  // ONCE here, up front, through the SAME redact() the reply path uses — and
+  // crucially BEFORE renderOperatorEvent runs escapeMarkdown on it (redacting the
+  // already-escaped text would let url-query-param secrets slip past url-redact,
+  // exactly the order the outbound pipeline documents: redact before markdown).
+  // Doing it at the top also scrubs the recorded operator-event history and the
+  // 429 metrics — defense in depth, no secret survives in ANY downstream sink.
+  event = { ...event, detail: redactOutboundText(event.detail, 'operator_event') }
+
   // ── 429 throttle tier (operator spec: "retry in place under 5 min, else
   // mark + failover, honest reset messaging") ────────────────────────────
   // A terminal TRANSIENT ACCOUNT-scoped 429 — kind `rate-limited` carrying
@@ -7910,6 +7953,35 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
       // the old account fails — honest reset messaging on the enriched card.
       void fireFleetAutoFallback(agent, untilMs, modelUnavailable.resetAt)
     }
+  } else if (kind === 'rate-limited' || kind === 'unknown-5xx') {
+    // #llm-error-surfacing — surface #2 (the "🚦 Rate limited" operator card).
+    // The transient rate-limit / overload family used to render the raw
+    // synthetic-error `detail` (bytes and all) via renderOperatorEvent. Route
+    // it through the humanized card instead: JSON-stripped coreText + reset in
+    // LOCAL time. The ErrorPresenceGate is the cross-surface dedup authority —
+    // the reply/done-card surfaces are already suppressed at the transcript
+    // source (session-tail), so the operator card is the sole renderer and
+    // wins the claim; a redundant burst within the collapse window is
+    // suppressed here in addition to the existing 5-min per-kind cooldown.
+    const parsed = parseLlmError(event.detail)
+    const now = Date.now()
+    if (decideErrorSurface(parsed, agent, { claim: true, now }) === 'suppress') {
+      process.stderr.write(
+        `telegram gateway: operator-event collapsed (error-presence-gate) agent=${agent} kind=${kind}\n`,
+      )
+      return
+    }
+    const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
+    // #llm-error-surfacing FIX 3 (crash guard): renderLlmErrorSafe wraps the
+    // tz-formatting render — an invalid IANA `SWITCHROOM_TIMEZONE`/`TZ` throws a
+    // RangeError out of Intl.DateTimeFormat (local-time.ts's "never throws" claim
+    // does NOT hold for construction-time zone validation). Pre-fix this branch
+    // had no guard, so a bad tz crashed the whole operator-event turn; now it
+    // degrades to a minimal tz-free line. There are no action buttons on this
+    // card (FIX 1) — the humanized text carries any recommendation inline.
+    const r = renderLlmErrorSafe(parsed, agent, tz, new Date(now))
+    renderedText = r.text
+    renderedKeyboard = undefined
   } else {
     try {
       const r = renderOperatorEvent(event)
@@ -8578,6 +8650,17 @@ async function runMidSessionCardReaper(): Promise<void> {
       const reaps = decideWorkerPinReaps({
         pins: candidates,
         statusOf: (agentId) => {
+          // #3207: coalesced feed pins are GROUP-level (`wk:group:<feedKey>`),
+          // so `workerAgentIdOfPinKey` yields `group:<feedKey>`, not a real
+          // jsonl agent id. Vouch for these off the live feed instead of the
+          // registry: a group the feed still tracks is 'running' (exempt from
+          // the TTL); a lingering group pin the feed no longer knows about is a
+          // missed unpin → 'terminal' (reap now). The feed's own group-empty
+          // unpin is the primary path; this is the missed-unpin backstop.
+          if (agentId.startsWith('group:')) {
+            const feedKey = agentId.slice('group:'.length)
+            return workerActivityFeed?.hasRunningInFeed(feedKey) ? 'running' : 'terminal'
+          }
           if (turnsDb == null) return 'unknown'
           try {
             const row = getSubagentByJsonlId(turnsDb, agentId)
@@ -8736,34 +8819,14 @@ async function reconcileStatusPinInner(
   }
 }
 
-/**
- * Background-worker desired-pin, driven off the live `🛠 Worker` message.
- * Reads the worker feed's current message_id (the EXISTING message — we pin
- * what the feed already rendered, never a new send) and reconciles a silent
- * pin while it's running / an unpin on completion. No-op until the feed has
- * actually painted a message for this worker (trivial sub-second workers stay
- * silent and are never pinned). Keyed `wk:<agentId>`.
- */
-function reconcileWorkerPin(
-  agentId: string,
-  chatId: string | null,
-  running: boolean,
-): void {
-  if (!PIN_STATUS_WHILE_WORKING) return
-  const key = `wk:${agentId}`
-  if (!running) {
-    // Unpin: recover the chat we pinned in (caller may not have it at
-    // completion). No-op when nothing was pinned for this worker.
-    const unpinChat = chatId ?? statusPinChatIds.get(key)
-    if (unpinChat == null) return
-    void reconcileStatusPin(key, unpinChat, { pinned: false })
-    return
-  }
-  if (chatId == null) return
-  const messageId = workerActivityFeed?.messageIdOf(agentId) ?? null
-  if (messageId == null) return // no message painted yet — nothing to pin
-  void reconcileStatusPin(key, chatId, { pinned: true, messageId })
-}
+// #3207: the per-worker `reconcileWorkerPin(agentId, …)` (keyed `wk:<agentId>`)
+// was removed. Now that background workers COALESCE into one shared message per
+// chat/thread, the pin is driven at the GROUP level by the feed itself
+// (`reconcilePin` → `wk:group:<feedKey>`, wired at createWorkerActivityFeed):
+// it pins when the group's first worker paints and unpins only when the group
+// empties. A per-worker unpin used to physically unpin a message a sibling
+// still needed, after which the survivor's re-pin NO-OP'd (its claim still
+// named that id) — leaving live work unpinned (review blocker).
 
 /** Unpin every owned status pin — used by the pre-restart sweep so a
  *  crash / interrupt never leaves a permanent pin behind. Best-effort;
@@ -10347,6 +10410,13 @@ const bridgeDeadWatchdog = createBridgeDeadWatchdog({
   // consecutive-escalation count. At the cap, arm() stands down loudly
   // instead of restart-looping a deterministically-failing bridge.
   priorStreak: bridgeDeadPriorStreak,
+  // #3086 — only THIS gateway's own primary bridge (registering under
+  // $SWITCHROOM_AGENT_NAME) drives the watchdog. A secondary/relay client
+  // (e.g. `overlord-relay`) registering a different name into this socket
+  // is named + non-cron but must NOT mark the (still-alive) primary bridge
+  // dead when it disconnects. Empty string ⟹ fall back to the pre-#3086
+  // "any named non-cron client" test inside the watchdog.
+  selfAgentName: process.env.SWITCHROOM_AGENT_NAME ?? '',
 })
 if (BRIDGE_DEAD_ESCALATION_ENABLED) {
   bridgeDeadWatchdog.arm()
@@ -10386,10 +10456,11 @@ const ipcServer: IpcServer = createIpcServer({
       : []
     // #3038 — a REAL (named, non-cron) bridge registered: stand the
     // bridge-dead watchdog down. Anonymous clients (recall.py, mcp
-    // handshakes) and cron-session bridges must NOT satisfy it — the
-    // watchdog gates on the identity INTERNALLY (isRealBridgeIdentity), so
-    // this call is safe wherever it sits relative to the cron early-return
-    // above (#3038 review finding 5).
+    // handshakes), cron-session bridges, and secondary/relay clients
+    // registering a name other than this gateway's own agent (#3086) must
+    // NOT satisfy it — the watchdog gates on the identity INTERNALLY
+    // (isRealBridgeIdentity vs selfAgentName), so this call is safe wherever
+    // it sits relative to the cron early-return above (#3038 review finding 5).
     bridgeDeadWatchdog.noteBridgeRegistered(client.agentName)
     client.send({ type: 'status', status: 'agent_connected' })
 
@@ -10583,8 +10654,10 @@ const ipcServer: IpcServer = createIpcServer({
       // #3038 — the real bridge went away mid-life. Re-arm the grace
       // window: a normal claude restart re-registers within seconds and
       // stands it down; a bridge that died for good escalates once (the
-      // once-per-boot fuse inside the watchdog caps it). Cron/anonymous
-      // identities are ignored inside the watchdog itself (finding 5).
+      // once-per-boot fuse inside the watchdog caps it). Cron/anonymous and
+      // secondary/relay identities (a name other than this gateway's own
+      // agent, #3086) are ignored inside the watchdog itself (finding 5) —
+      // so a transient relay disconnect never bounces a healthy container.
       if (BRIDGE_DEAD_ESCALATION_ENABLED) bridgeDeadWatchdog.noteBridgeDisconnected(client.agentName)
     }
 
@@ -14948,9 +15021,11 @@ async function executeEditMessage(args: Record<string, unknown>): Promise<unknow
   // secret into a live bubble or the history row. Mask before scrub/send.
   editRawText = redactOutboundText(editRawText, 'edit_message')
   // Fleet-wide consistent formatting (same order as the reply path: redact
-  // first so secrets are matched literally, then normalize, then spacers on
-  // the rich path only).
-  if (!editLiteralText) editRawText = addParagraphSpacers(stripExcessBold(normalizePunctuation(editRawText)))
+  // first so secrets are matched literally, then normalize). No paragraph
+  // spacer pass — the NBSP spacer was removed in the #2669 follow-up because it
+  // double-gapped every paragraph; the rich renderer already shows `\n\n` as
+  // one blank line.
+  if (!editLiteralText) editRawText = stripExcessBold(normalizePunctuation(editRawText))
   // Voice scrub (#1683): same em-dash scrub as the reply path. Edits
   // are how silent-anchor and progress-update mutate already-sent
   // bubbles, so without this an edit can re-introduce dashes the
@@ -17386,9 +17461,9 @@ function handleSessionEvent(ev: SessionEvent): void {
         // breaks into GFM hard breaks so the Bot API 10.1 rich path doesn't
         // collapse them (lists/tables/code left untouched). Runs BEFORE the
         // redact/scrub below, exactly as reply orders it (repair → normalize →
-        // redact → scrub), so masking sees the repaired text. The matching
-        // addParagraphSpacers pass runs on the send side just before
-        // splitMarkdownChunks (see below).
+        // redact → scrub), so masking sees the repaired text. Paragraph gaps
+        // are the plain `\n\n` normalizeParagraphBreaks guarantees — no spacer
+        // pass runs on the send side any more (removed in the #2669 follow-up).
         capturedText = normalizeParagraphBreaks(repairEscapedWhitespace(capturedText))
         // Component 3 — origin-thread backstop. `chatId`/`threadId` are
         // captured from the turn atom (turn.sessionChatId/sessionThreadId)
@@ -17532,13 +17607,12 @@ function handleSessionEvent(ev: SessionEvent): void {
             link_preview_options: { is_disabled: true },
           }
           const limit = RICH_MESSAGE_MAX_CHARS
-          // #2798 / #2692 — inject visible blank-line spacers into prose `\n\n`
-          // gaps before splitting, exactly as executeReply does. The rich GFM
-          // renderer collapses a bare `\n\n` gap TIGHT, so without this the
-          // paragraph boundaries from the '\n\n' block join (turn-flush-safety
-          // .ts) would still render jammed together. Mirrors reply's
-          // `addParagraphSpacers(text)` on the non-literal path.
-          const renderedText = addParagraphSpacers(capturedText)
+          // The `\n\n` block joins from turn-flush-safety.ts render as normal
+          // single blank lines under the Bot API 10.1 rich GFM path, so no
+          // spacer pass runs before splitting (the NBSP spacer was removed in
+          // the #2669 follow-up — it double-gapped every paragraph). Mirrors
+          // executeReply, which now also sends the normalized text as-is.
+          const renderedText = capturedText
           const htmlChunks = splitMarkdownChunks(renderedText, limit)
           const sentIds: number[] = []
           try {
@@ -21939,6 +22013,10 @@ function recordTypedModelSwitch(
   }
   if (!reply.selectedModel) return ''
   sessionModelSource.setOverride(reply.selectedModel)
+  // A manual /model apply to the dropped premium clears any pending recovery
+  // marker so the "available again" ping can't still fire after the user has
+  // already switched back themselves.
+  clearPremiumRecoveryOnManualSwitch(reply.selectedModel)
   return ''
 }
 
@@ -21967,6 +22045,11 @@ function recordModelMenuSideEffects(
   // (recommended)" selection clears any leftover carrier.
   if (outcome.selectedModel) {
     sessionModelSource.setOverride(outcome.selectedModel)
+    // Clear a pending premium-recovery marker when the tap re-selects the
+    // dropped premium (menu OR the recovery ping's own switch-back button):
+    // no stale "available again" ping once we're back on it. Idempotent — the
+    // ping-send path already consumed the marker, so this is a no-op there.
+    clearPremiumRecoveryOnManualSwitch(outcome.selectedModel)
   }
   if (outcome.clearedDefault) {
     const smDir = resolveAgentDirFromEnv()
@@ -23546,6 +23629,173 @@ function broadcastFleetFallbackFailure(triggerAgent: string, reason: string): vo
   }
 }
 
+/**
+ * Broadcast a status notice to every authorized chat (system notice posture:
+ * silenced ping, wrapped send). Shared by the tier-downgrade notices below.
+ */
+function broadcastTierNotice(markdown: string): void {
+  const access = loadAccess()
+  if (access.allowFrom.length === 0) return
+  for (const chat_id of access.allowFrom) {
+    void swallowingApiCall(
+      // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy)
+      () => bot.api.sendRichMessage(chat_id, richMessage(markdown), { disable_notification: true }),
+      { chat_id: String(chat_id), verb: 'tier-downgrade:notify' },
+    )
+  }
+}
+
+/**
+ * MODEL-TIER downgrade failover (second recovery tier). Consulted ONLY from the
+ * `all-blocked` branch of doFireFleetAutoFallback — i.e. AFTER account-swap has
+ * been tried and found no account still serving the walled premium model
+ * (precedence A: account-swap first). When a PREMIUM /model override is active
+ * (distinct from the configured default), downgrade to the configured default
+ * and resume the dead turn via a self-restart, rather than let the turn stall.
+ *
+ *   - NO automatic return to the premium model. The /model override is
+ *     session-scoped and in-memory only (recordTypedModelSwitch writes no
+ *     carrier), so it dies on the downgrade SIGTERM. The consume-once
+ *     `.session-model` carrier written here targets the CONFIGURED DEFAULT:
+ *     start.sh applies+deletes it on the resume boot, and every later restart
+ *     also boots the default. The premium tier is never restored on its own —
+ *     the user must re-issue `/model <premium>`, which the notice says plainly.
+ *   - Effort is NATIVE: no `.session-effort` carrier is written, so the restart
+ *     sheds any live /effort override and the downgraded default boots at the
+ *     configured `thinking_effort` (the fleet `low` pin, #1978).
+ *   - Loop-bounded by the NATURAL on-default guard: after the downgrade boot the
+ *     session runs the configured default (override gone), so a re-entry returns
+ *     `skip` ('on-default') and never re-downgrades — even if the default is
+ *     itself walled (then the normal all-blocked card fires, no loop). Pacing
+ *     reuses the fleetFallbackResumeGate single-flight + 3h staleness.
+ *
+ * Returns:
+ *   'downgraded'      — carrier written, latch armed, restart fired; caller must
+ *                       NOT also emit the all-blocked give-up card (we are
+ *                       recovering, not giving up).
+ *   'restart-pending' — a resume restart was ALREADY armed in this process (a
+ *                       concurrent turn's downgrade or account-swap); that
+ *                       restart replays the interrupted turn, so caller must NOT
+ *                       emit a give-up card (avoids the contradictory "could not
+ *                       be recovered" race).
+ *   'skip'            — not applicable (on the configured default, unresolved
+ *                       default, or the turn is too stale to resume); caller
+ *                       falls through to the all-blocked card.
+ */
+function maybeTierDowngrade(triggerAgent: string): 'downgraded' | 'restart-pending' | 'skip' {
+  // Thin adapter: the order-sensitive glue lives in runTierDowngrade
+  // (tier-downgrade-wiring.ts) behind injected deps so it is unit-testable
+  // without importing the gateway. This wires the real seams.
+  return runTierDowngrade(triggerAgent, {
+    getAgentDir: () => resolveAgentDirFromEnv() ?? null,
+    getConfiguredDefault: () => {
+      const dir = resolveAgentDirFromEnv()
+      if (!dir) return null
+      return resolveMainModel(readConfiguredDefaultModel(dir) ?? undefined)
+    },
+    getSessionOverride: () => sessionModelSource.getOverride(),
+    resolve: (t) => resolveMainModel(t),
+    // PEEK the resume gate WITHOUT arming (single-flight within this process +
+    // 3h staleness), the same gate the account-swap resume path uses.
+    peekResumeGate: () => fleetFallbackResumeGate.peek(newestActiveTurnStartedAtMs()),
+    writeCarrier: (dir, toModel, cfg) => writeSessionModelFile(dir, toModel, cfg),
+    armResumeGate: () => fleetFallbackResumeGate.arm(),
+    // Records the DROPPED premium token + the notice's allowFrom chats; start.sh
+    // never consumes `.premium-recovery`, so it survives the self-restart.
+    writeRecoveryMarker: (dir, premiumModel) => {
+      const chats = loadAccess().allowFrom.map((c) => String(c))
+      if (chats.length > 0) writePremiumRecoveryFile(dir, premiumModel, chats)
+    },
+    broadcastNotice: (md) => broadcastTierNotice(md),
+    selfRestart: (agent) => triggerSelfRestart(agent, 'tier-downgrade-resume'),
+    selfAgent: (t) => process.env.SWITCHROOM_AGENT_NAME ?? t,
+    log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
+  })
+}
+
+/**
+ * "Premium model recovered" ping (tier-downgrade companion). Consulted from the
+ * gateway's existing `runQuotaWatch` tick (every 15 min, on the cheap
+ * `list-state` IPC read it already does — NO new poller, NO broker change).
+ * When a `.premium-recovery` marker is pending (a downgrade dropped a premium
+ * `/model` selection fleet-wide) AND the broker's live-authoritative per-account
+ * eligibility shows the premium tier servable again — at least one account
+ * neither `exhausted` nor `premium_walled` — fire EXACTLY ONE ping to the
+ * recorded chats with a one-tap "switch back" button, then consume the marker.
+ *
+ * DETERMINISTIC: `exhausted` / `premium_walled` are the broker's own verdicts
+ * (`isAccountExhausted` / `isAccountPremiumWalled` → `isModelTierWalled`, a pure
+ * timestamp compare). No model judgement, no clock of our own.
+ *
+ * AT-MOST-ONCE: a fleet-wide `claim-notification` gates against a bounce or a
+ * concurrent tick, and the marker is cleared BEFORE the send (never-storm). The
+ * button routes through the SAME session-scoped `/model` apply path as the
+ * model menu (`mdl:alias:<premium>` → handleModelMenuCallback +
+ * recordModelMenuSideEffects) — it does not bypass it.
+ */
+async function maybePremiumRecoveryPing(
+  brokerClient: NonNullable<Awaited<ReturnType<typeof getAuthBrokerClient>>>,
+  accounts: ReadonlyArray<{ exhausted: boolean; premium_walled?: boolean }>,
+): Promise<void> {
+  // Thin adapter: the order-sensitive never-storm glue lives in
+  // runPremiumRecoveryPing (premium-recovery-wiring.ts) behind injected deps so
+  // it is unit-testable without importing the gateway. This wires the real seams
+  // (marker FS, fleet claim, send) — behaviour is preserved exactly.
+  return runPremiumRecoveryPing({
+    getAgentDir: () => resolveAgentDirFromEnv() ?? null,
+    readMarker: (dir) => readPremiumRecoveryFile(dir),
+    clearMarker: (dir) => clearPremiumRecoveryFile(dir),
+    getAgent: () => getMyAgentName(),
+    // The pure recovery predicate, bound to THIS tick's live per-account
+    // eligibility (the broker's own verdicts; `premium_walled` may be absent).
+    decide: () =>
+      decidePremiumRecovery({
+        hasMarker: true,
+        accounts: accounts.map((a) => ({
+          exhausted: a.exhausted,
+          premiumWalled: a.premium_walled === true,
+        })),
+      }).fire,
+    // Fail-open (claimQuotaNotification returns true on any broker error) — a
+    // convenience ping degrades to at-least-once, never lost.
+    claimNotification: (key) => claimQuotaNotification(brokerClient, key),
+    fallbackChats: () => loadAccess().allowFrom.map((c) => String(c)),
+    sendToChat: (chat_id, ping, keyboard) => {
+      void swallowingApiCall(
+        // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy)
+        () =>
+          bot.api.sendRichMessage(chat_id, richMessage(ping.text), {
+            disable_notification: true,
+            reply_markup: keyboard,
+          }),
+        { chat_id: String(chat_id), verb: 'premium-recovery:notify' },
+      )
+    },
+    log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
+  })
+}
+
+/**
+ * Clear a pending premium-recovery marker when the user MANUALLY re-selects the
+ * dropped premium model before the recovery ping fires — no stale "available
+ * again" ping after they've already switched back. Called from every `/model`
+ * apply chokepoint (typed + menu/callback). Matches on the canonicalized token
+ * so an alias vs resolved-id spelling of the same model still clears it.
+ */
+function clearPremiumRecoveryOnManualSwitch(appliedToken: string | null | undefined): void {
+  if (appliedToken == null || appliedToken.length === 0) return
+  const agentDir = resolveAgentDirFromEnv()
+  if (!agentDir) return
+  const marker = readPremiumRecoveryFile(agentDir)
+  if (marker == null) return
+  if (resolveMainModel(appliedToken) === resolveMainModel(marker.premiumModel)) {
+    clearPremiumRecoveryFile(agentDir)
+    process.stderr.write(
+      `telegram gateway: [premium-recovery] marker cleared — user manually re-issued /model ${marker.premiumModel}\n`,
+    )
+  }
+}
+
 /** Returns true iff the dispatcher actually performed a swap (and the
  *  user-visible announcement was broadcast). False on no-op /
  *  error / idempotent-skip — caller uses this to decide whether to
@@ -23628,6 +23878,21 @@ async function doFireFleetAutoFallback(
     if (outcome.kind === 'switched') {
       fallbackAllBlockedNoticeState = { lastSentAtMs: 0 }
     } else if (outcome.kind === 'all-blocked') {
+      // ── Second recovery tier: MODEL-TIER downgrade (precedence A) ──────────
+      // Account-swap just came back all-blocked (no account still serves the
+      // walled model). Before giving up, if a PREMIUM /model override is active,
+      // downgrade to the configured default and resume the dead turn rather than
+      // stall. Only reachable here — a `switched` outcome never enters this
+      // branch, so a model throttled on one account is always recovered by
+      // account-swap first, never by a downgrade. Loop-bounded by the natural
+      // on-default guard; effort revert is native (see maybeTierDowngrade).
+      const tier = maybeTierDowngrade(triggerAgent)
+      if (tier === 'downgraded' || tier === 'restart-pending') {
+        // Either this turn armed a downgrade restart, or a concurrent turn
+        // already armed a resume restart. Do NOT emit the all-blocked give-up
+        // card — a restart is coming that replays the interrupted turn.
+        return false
+      }
       const verdict = evaluateAllBlockedNotice(fallbackAllBlockedNoticeState, Date.now())
       if (!verdict.send) {
         process.stderr.write(
@@ -23860,6 +24125,16 @@ async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
     return // No accounts — nothing to watch.
   }
 
+  // Premium-model recovery ping (tier-downgrade companion). Reuses THIS tick's
+  // list-state read (no extra IPC): if a downgrade left a `.premium-recovery`
+  // marker and the broker now shows the premium tier servable again, ping once
+  // with a one-tap switch-back button. At-most-once + fleet-claim-deduped.
+  await maybePremiumRecoveryPing(brokerClient, listStateData.accounts).catch((err) => {
+    process.stderr.write(
+      `telegram gateway: [premium-recovery] ping check failed (non-fatal): ${(err as Error)?.message ?? err}\n`,
+    )
+  })
+
   // Build AccountSnapshot[] from cached broker state only — no live probe.
   // Accounts with null last_quota produce quota=null snapshots; classifyHealth
   // returns 'unknown'; evaluateQuotaWatchAccount skips — no false alarms.
@@ -29100,6 +29375,12 @@ void (async () => {
             // supersedes the coarse 5-min bucket relay below to avoid
             // double-surfacing the same progress beat.
             const workerFeedEnabled = isWorkerActivityFeedEnabled(process.env.SWITCHROOM_WORKER_ACTIVITY_FEED)
+            // Combined-feed row cap (channels.telegram.worker_feed.max_rows).
+            // Unset / non-positive → the feed's built-in default (8).
+            const workerFeedMaxRows = (() => {
+              const raw = Number(process.env.SWITCHROOM_TG_WORKER_FEED_MAX_ROWS)
+              return Number.isInteger(raw) && raw > 0 ? raw : undefined
+            })()
             // Model A — foreground sub-agent nesting in the parent's live
             // activity draft. ON by default; this edits the SAME activity-
             // summary message the tool_label feed already owns (not the
@@ -29157,6 +29438,32 @@ void (async () => {
               // every ~6s for the whole ban (the worker-feed shed-contract bug:
               // 565 `sent.message_id` crashes in one 6h ban).
               floodWaitRemainingMs: probeFloodWaitRemainingMs,
+              // #3084 follow-up: 2+ background workers in one chat/thread coalesce
+              // into ONE combined feed message. `maxRows` caps the visible rows
+              // (compact `+M more working…` spill) so the body stays under the
+              // rich-message wire ceiling (STATUS_CARD_CHAR_BUDGET). Sourced from
+              // channels.telegram.worker_feed.max_rows via the config cascade
+              // (scaffold emits SWITCHROOM_TG_WORKER_FEED_MAX_ROWS); unset → 8.
+              maxRows: workerFeedMaxRows,
+              // #3207 review: GROUP-level status pin. Workers now coalesce into
+              // ONE shared message, so the pin must follow the GROUP lifecycle,
+              // not a single worker's — otherwise a sibling's finish unpins a
+              // message the survivors still need and the survivor's re-pin NOOPs
+              // (its claim still names that id), leaving live work unpinned. The
+              // feed drives this: pin `wk:group:<feedKey>` when the group first
+              // paints, unpin only when the group empties (messageId === null).
+              reconcilePin: ({ feedKey, chatId, messageId }) => {
+                if (!PIN_STATUS_WHILE_WORKING) return
+                const key = `wk:group:${feedKey}`
+                if (messageId != null) {
+                  void reconcileStatusPin(key, chatId, { pinned: true, messageId })
+                } else {
+                  const unpinChat = chatId || statusPinChatIds.get(key)
+                  if (unpinChat != null && unpinChat.length > 0) {
+                    void reconcileStatusPin(key, unpinChat, { pinned: false })
+                  }
+                }
+              },
               log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
             })
             subagentWatcher = startSubagentWatcher({
@@ -29273,9 +29580,9 @@ void (async () => {
               // anything. The actual repaint + re-pin happen DOWNSTREAM on the
               // next replayed `running` cue: the watcher's re-registration
               // replays `onProgress`, which calls `workerActivityFeed.update()`
-              // (now un-gated) to first-paint a FRESH `🛠 Worker` message, and
-              // its `.then(reconcileWorkerPin(agentId, wkChat, true))` pins that
-              // new message via the `wk:<agentId>` status-pin. Clearing the gate
+              // (now un-gated) to first-paint a FRESH message, and the feed's
+              // own `reconcilePin` (#3207) re-pins that message at the GROUP
+              // level (`wk:group:<feedKey>`). Clearing the gate
               // here FIRST is the ordering requirement — without it those first
               // replayed ticks would be swallowed by the finalized gate and no
               // new card would ever paint. Net effect restores the operator
@@ -29381,7 +29688,7 @@ void (async () => {
                       // card keeps the model tag even with no live entry.
                       model: dispatch.feedModel ?? undefined,
                     })
-                    reconcileWorkerPin(agentId, null, false)
+                    // #3207: group-level pin dropped by the feed on group-empty.
                   }
                   return
                 }
@@ -29459,8 +29766,9 @@ void (async () => {
                       state: outcome === 'failed' ? 'failed' : 'done',
                       model: dispatch.feedModel ?? undefined,
                     })
-                    // Status-pin: worker done — drop its pin.
-                    reconcileWorkerPin(agentId, null, false)
+                    // #3207: the group-level pin is dropped by the feed itself
+                    // when this group's LAST worker finishes (reconcilePin →
+                    // `wk:group:<feedKey>`); no per-worker unpin here.
                   }
                   return
                 }
@@ -29479,8 +29787,8 @@ void (async () => {
                     state: outcome === 'failed' ? 'failed' : 'done',
                     model: dispatch.feedModel ?? undefined,
                   })
-                  // Status-pin: worker done — drop its pin.
-                  reconcileWorkerPin(agentId, null, false)
+                  // #3207: the group-level pin is dropped by the feed itself
+                  // when this group's LAST worker finishes; no per-worker unpin.
                 }
 
                 const handbackOrigin = resolveSubagentOriginChat(agentId)
@@ -29647,7 +29955,10 @@ void (async () => {
                         model: feedModel,
                       },
                       wk.threadId,
-                    )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
+                    )
+                  // #3207: the feed pins the group's shared message itself when
+                  // it first paints (reconcilePin → `wk:group:<feedKey>`); no
+                  // per-worker pin chained here.
                     return
                   }
                   if (surface !== 'nest') return // 'skip' — orphan-status off
@@ -29789,7 +30100,10 @@ void (async () => {
                       model: feedModel,
                     },
                     wk.threadId,
-                  )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
+                  )
+                  // #3207: the feed pins the group's shared message itself when
+                  // it first paints (reconcilePin → `wk:group:<feedKey>`); no
+                  // per-worker pin chained here.
                   return
                 }