@link-assistant/hive-mind 2.7.0 → 2.7.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.7.1
+
+### Patch Changes
+
+- 0f57fe3: Make the Telegram Bot API section of `/limits` report real usage instead of near-permanent zeroes. Every Bot API call is now counted (not just sends), each documented flood-control window is tracked separately, and the section shows a single bar for the window closest to refusing the next request. Limits are learned from Telegram's own answers: a success proves capacity, a 429 proves a ceiling, and an active `retry_after` shows a full bar with the countdown.
+
 ## 2.7.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/limits-i18n.lib.mjs

@@ -85,12 +85,18 @@ const ENGLISH_LIMITS = {
   subscription_detail_trial_ends: 'trial ends {{time}}',
   subscription_detail_trial_ends_in: 'trial ends in {{duration}}; {{time}}',
   subscription_status: 'Subscription: {{status}}',
-  telegram_api: 'Telegram Bot API (local rolling telemetry)',
-  telegram_global_window: '{{used}}/{{limit}} messages in 1s',
-  telegram_group_window: '{{used}}/{{limit}} messages in busiest group over 1m',
+  telegram_api: 'Telegram Bot API',
+  telegram_flood_control: 'flood control',
   telegram_last_rate_limit: 'Last 429: {{method}}',
+  telegram_observed_limit: 'observed limit',
+  telegram_peak: 'peak {{peak}}',
   telegram_rate_limit_responses: '429 responses since startup: {{count}}',
-  telegram_retry_in: 'retry in {{seconds}}s',
+  telegram_requests: '{{used}}/{{limit}} requests',
+  telegram_retry_in: 'retry in {{duration}}',
+  telegram_scope_broadcast: 'messages to all chats, 1s',
+  telegram_scope_chat: 'messages per chat, 1m',
+  telegram_scope_group: 'messages per group, 1m',
+  telegram_scope_other: 'other API requests, 1s',
   trial_ends: 'Trial ends {{time}}',
   trial_ends_in: 'Trial ends in {{duration}} ({{time}})',
   unavailable: 'unavailable',

package/src/limits.lib.mjs

@@ -16,6 +16,9 @@ import { classifyCodexRateLimitWindows } from './codex-rate-limit-windows.lib.mj
 import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry, execGhWithRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller. execGhWithRetry adds transient-network retry (#1756).
 import { formatLimitResetsAt, formatLimitResetsIn, formatLocalizedCurrentTime, formatLocalizedRelativeTime, formatLocalizedResetTime, localizeCompactDuration, lt, resolveLimitLocale } from './limits-i18n.lib.mjs';
 import { formatSubscriptionHeading, formatSubscriptionLines, getCachedClaudeSubscription, getCachedCodexSubscription, getClaudeSubscriptionInfo, getCodexSubscriptionInfo } from './limits-subscription.lib.mjs';
+export { getProgressBar } from './progress-bar.lib.mjs';
+import { getProgressBar } from './progress-bar.lib.mjs';
+import { formatTelegramLimitsSection } from './telegram-limits-section.lib.mjs';
 import { getTelegramRateLimits } from './telegram-rate-limit.lib.mjs';
 export { getCachedClaudeSubscription, getCachedCodexSubscription, getClaudeSubscriptionInfo, getCodexSubscriptionInfo };
 // Initialize dayjs plugins
@@ -984,40 +987,6 @@ export async function getCodexUsageLimits(verbose = false, authPath = DEFAULT_CO
   }
 }
 
-/**
- * Generate a text-based progress bar for usage percentage
- * @param {number} percentage - Usage percentage (0-100)
- * @param {number|null} thresholdPercentage - Optional threshold position to show in the bar (0-100)
- * @returns {string} Text-based progress bar
- * @see https://github.com/link-assistant/hive-mind/issues/1242
- */
-export function getProgressBar(percentage, thresholdPercentage = null) {
-  const totalBlocks = 30;
-  const filledBlocks = Math.round((percentage / 100) * totalBlocks);
-
-  if (thresholdPercentage === null) {
-    // No threshold - original behavior
-    const emptyBlocks = totalBlocks - filledBlocks;
-    return '\u2593'.repeat(filledBlocks) + '\u2591'.repeat(emptyBlocks);
-  }
-
-  // With threshold marker
-  const thresholdPos = Math.round((thresholdPercentage / 100) * totalBlocks);
-  let bar = '';
-
-  for (let i = 0; i < totalBlocks; i++) {
-    if (i === thresholdPos) {
-      bar += '│'; // Threshold marker (U+2502 Box Drawings Light Vertical)
-    } else if (i < filledBlocks) {
-      bar += '▓'; // Filled (U+2593)
-    } else {
-      bar += '░'; // Empty (U+2591)
-    }
-  }
-
-  return bar;
-}
-
 /**
  * Calculate the percentage of time that has passed in a period
  * @param {string} resetsAt - ISO date string when the period resets
@@ -1125,23 +1094,8 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     sections.push(section);
   }
 
-  const telegramRateLimit = options?.telegramRateLimit || null;
-  if (telegramRateLimit) {
-    let section = `${lt('telegram_api', {}, { locale })}\n`;
-    const global = telegramRateLimit.global;
-    section += `${getProgressBar(global.usedPercentage)} ${global.usedPercentage}% ${lt('used', {}, { locale })}\n`;
-    section += `${lt('telegram_global_window', { used: global.used, limit: global.limit }, { locale })}\n`;
-    const group = telegramRateLimit.busiestGroup;
-    section += `${getProgressBar(group.usedPercentage)} ${group.usedPercentage}% ${lt('used', {}, { locale })}\n`;
-    section += `${lt('telegram_group_window', { used: group.used, limit: group.limit }, { locale })}\n`;
-    section += `${lt('telegram_rate_limit_responses', { count: telegramRateLimit.rateLimitResponses }, { locale })}\n`;
-    if (telegramRateLimit.lastRateLimit) {
-      const retry = telegramRateLimit.lastRateLimit.retryRemainingSeconds;
-      const retryText = retry === null ? '' : `, ${lt('telegram_retry_in', { seconds: retry }, { locale })}`;
-      section += `${lt('telegram_last_rate_limit', { method: telegramRateLimit.lastRateLimit.method }, { locale })}${retryText}\n`;
-    }
-    sections.push(section);
-  }
+  const telegramSection = formatTelegramLimitsSection(options?.telegramRateLimit, { locale });
+  if (telegramSection) sections.push(telegramSection);
 
   const claudeHeading = formatSubscriptionHeading('claude', subscription, { locale });
   const useShortClaudeLabels = Boolean(claudeHeading);

package/src/locales/en.lino

@@ -335,19 +335,26 @@ en
         in "Subscription ends in {{duration}} ({{time}})"
       status "Subscription: {{status}}"
     telegram
-      api "Telegram Bot API (local rolling telemetry)"
-      global
-        window "{{used}}/{{limit}} messages in 1s"
-      group
-        window "{{used}}/{{limit}} messages in busiest group over 1m"
+      api "Telegram Bot API"
+      flood
+        control "flood control"
       last
         rate
           limit "Last 429: {{method}}"
+      observed
+        limit "observed limit"
+      peak "peak {{peak}}"
       rate
         limit
           responses "429 responses since startup: {{count}}"
+      requests "{{used}}/{{limit}} requests"
       retry
-        in "retry in {{seconds}}s"
+        in "retry in {{duration}}"
+      scope
+        broadcast "messages to all chats, 1s"
+        chat "messages per chat, 1m"
+        group "messages per group, 1m"
+        other "other API requests, 1s"
     trial
       ends
         label "Trial ends {{time}}"

package/src/locales/hi.lino

@@ -335,19 +335,26 @@ hi
         in "सदस्यता {{duration}} में समाप्त होगी ({{time}})"
       status "सदस्यता: {{status}}"
     telegram
-      api "Telegram Bot API (स्थानीय रोलिंग टेलीमेट्री)"
-      global
-        window "1 सेकंड में {{used}}/{{limit}} संदेश"
-      group
-        window "सबसे व्यस्त समूह में 1 मिनट में {{used}}/{{limit}} संदेश"
+      api "Telegram Bot API"
+      flood
+        control "फ्लड नियंत्रण"
       last
         rate
           limit "अंतिम 429: {{method}}"
+      observed
+        limit "मापी गई सीमा"
+      peak "शिखर {{peak}}"
       rate
         limit
           responses "स्टार्टअप के बाद 429 प्रतिक्रियाएँ: {{count}}"
+      requests "{{used}}/{{limit}} अनुरोध"
       retry
-        in "{{seconds}} सेकंड में पुनः प्रयास"
+        in "{{duration}} में पुनः प्रयास"
+      scope
+        broadcast "सभी चैट में संदेश, 1 सेकंड"
+        chat "प्रति चैट संदेश, 1 मिनट"
+        group "प्रति समूह संदेश, 1 मिनट"
+        other "अन्य API अनुरोध, 1 सेकंड"
     trial
       ends
         label "ट्रायल समाप्त होगा {{time}}"

package/src/locales/ru.lino

@@ -335,19 +335,26 @@ ru
         in "Подписка заканчивается через {{duration}} ({{time}})"
       status "Подписка: {{status}}"
     telegram
-      api "Telegram Bot API (локальная скользящая статистика)"
-      global
-        window "{{used}}/{{limit}} сообщений за 1 с"
-      group
-        window "{{used}}/{{limit}} сообщений в самой активной группе за 1 мин"
+      api "Telegram Bot API"
+      flood
+        control "контроль флуда"
       last
         rate
           limit "Последний ответ 429: {{method}}"
+      observed
+        limit "измеренный лимит"
+      peak "пик {{peak}}"
       rate
         limit
           responses "Ответов 429 с момента запуска: {{count}}"
+      requests "{{used}}/{{limit}} запросов"
       retry
-        in "повтор через {{seconds}} с"
+        in "повтор через {{duration}}"
+      scope
+        broadcast "сообщения во все чаты, 1 с"
+        chat "сообщения в чат, 1 мин"
+        group "сообщения в группу, 1 мин"
+        other "другие запросы API, 1 с"
     trial
       ends
         label "Пробный период заканчивается {{time}}"

package/src/locales/zh.lino

@@ -335,19 +335,26 @@ zh
         in "订阅将在 {{duration}} 后结束 ({{time}})"
       status "订阅: {{status}}"
     telegram
-      api "Telegram Bot API（本地滚动遥测）"
-      global
-        window "1 秒内 {{used}}/{{limit}} 条消息"
-      group
-        window "最繁忙群组 1 分钟内 {{used}}/{{limit}} 条消息"
+      api "Telegram Bot API"
+      flood
+        control "限流"
       last
         rate
           limit "最近一次 429：{{method}}"
+      observed
+        limit "实测上限"
+      peak "峰值 {{peak}}"
       rate
         limit
           responses "启动后的 429 响应：{{count}}"
+      requests "{{used}}/{{limit}} 个请求"
       retry
-        in "{{seconds}} 秒后重试"
+        in "{{duration}} 后重试"
+      scope
+        broadcast "发送到所有聊天，1 秒"
+        chat "每个聊天的消息，1 分钟"
+        group "每个群组的消息，1 分钟"
+        other "其他 API 请求，1 秒"
     trial
       ends
         label "试用结束于 {{time}}"

package/src/progress-bar.lib.mjs

@@ -0,0 +1,45 @@
+/**
+ * Text progress bar rendering shared by the /limits sections.
+ *
+ * Extracted from limits.lib.mjs so that section formatters can render bars
+ * without importing limits.lib.mjs itself (which would be a cycle, since
+ * limits.lib.mjs imports those formatters).
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1242
+ */
+
+/**
+ * Generate a text-based progress bar for usage percentage
+ * @param {number} percentage - Usage percentage (0-100)
+ * @param {number|null} thresholdPercentage - Optional threshold position to show in the bar (0-100)
+ * @returns {string} Text-based progress bar
+ * @see https://github.com/link-assistant/hive-mind/issues/1242
+ */
+export function getProgressBar(percentage, thresholdPercentage = null) {
+  const totalBlocks = 30;
+  const filledBlocks = Math.round((percentage / 100) * totalBlocks);
+
+  if (thresholdPercentage === null) {
+    // No threshold - original behavior
+    const emptyBlocks = totalBlocks - filledBlocks;
+    return '▓'.repeat(filledBlocks) + '░'.repeat(emptyBlocks);
+  }
+
+  // With threshold marker
+  const thresholdPos = Math.round((thresholdPercentage / 100) * totalBlocks);
+  let bar = '';
+
+  for (let i = 0; i < totalBlocks; i++) {
+    if (i === thresholdPos) {
+      bar += '│'; // Threshold marker (U+2502 Box Drawings Light Vertical)
+    } else if (i < filledBlocks) {
+      bar += '▓'; // Filled (U+2593)
+    } else {
+      bar += '░'; // Empty (U+2591)
+    }
+  }
+
+  return bar;
+}
+
+export default { getProgressBar };

package/src/telegram-limits-section.lib.mjs

@@ -0,0 +1,76 @@
+/**
+ * Renders the Telegram Bot API section of `/limits` (issue #2070).
+ *
+ * The section shows exactly one bar, for the window closest to refusing the next
+ * request, because Telegram enforces several limits at once and only the tightest
+ * one can stop the bot. See telegram-rate-limit.lib.mjs for how the windows are
+ * measured and corrected.
+ */
+
+import { localizeCompactDuration, lt } from './limits-i18n.lib.mjs';
+import { getProgressBar } from './progress-bar.lib.mjs';
+
+const FULL_PERCENTAGE = 100;
+
+/**
+ * Format a `retry_after` countdown.
+ * Telegram's values span three orders of magnitude — routine flood control returns
+ * ~10s, while repeat offences have been observed returning 2282s and above — so
+ * the countdown has to carry hours, not just seconds.
+ * @see https://github.com/tdlib/telegram-bot-api/issues/184
+ */
+export function formatRetryDuration(seconds, options = {}) {
+  const total = Math.max(0, Math.round(Number(seconds) || 0));
+  const parts = [];
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const remainingSeconds = total % 60;
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (remainingSeconds > 0 || parts.length === 0) parts.push(`${remainingSeconds}s`);
+  return localizeCompactDuration(parts.join(' '), options);
+}
+
+function formatThrottledLabel(lastRateLimit, options) {
+  const label = lt('telegram_flood_control', {}, options);
+  const seconds = lastRateLimit?.retryRemainingSeconds;
+  if (!seconds) return label;
+  return `${label}, ${lt('telegram_retry_in', { duration: formatRetryDuration(seconds, options) }, options)}`;
+}
+
+function formatUsageLine(display, options) {
+  const requests = lt('telegram_requests', { used: display.used, limit: display.limit }, options);
+  // Say so when the number came from Telegram refusing or accepting a call,
+  // rather than from the documentation, since the two disagree in practice.
+  const source = display.limitSource === 'observed' ? ` (${lt('telegram_observed_limit', {}, options)})` : '';
+  return `${requests}${source}, ${lt('telegram_peak', { peak: display.peak }, options)}`;
+}
+
+/**
+ * @param {object|null} telegramRateLimit - Snapshot from TelegramRateLimitTracker
+ * @param {object} options - { locale }
+ * @returns {string|null} Section text, or null when there is nothing measured yet
+ */
+export function formatTelegramLimitsSection(telegramRateLimit, options = {}) {
+  const display = telegramRateLimit?.display;
+  if (!display) return null;
+
+  const locale = options?.locale || null;
+  const lastRateLimit = telegramRateLimit.lastRateLimit || null;
+  // While retry_after is still counting down, the rolling windows are the wrong
+  // thing to report: Telegram has already said no, whatever they estimate. Show
+  // the refusal, and let the bar fall back to measured usage once it expires.
+  const throttled = Boolean(telegramRateLimit.throttled);
+  const usedPercentage = throttled ? FULL_PERCENTAGE : display.usedPercentage;
+  const label = throttled ? formatThrottledLabel(lastRateLimit, { locale }) : lt(`telegram_scope_${display.id}`, {}, { locale });
+  const suffix = usedPercentage >= FULL_PERCENTAGE ? ' ⚠️' : ` ${lt('used', {}, { locale })}`;
+
+  let section = `${lt('telegram_api', {}, { locale })}\n`;
+  section += `${getProgressBar(usedPercentage)} ${usedPercentage}%${suffix} (${label})\n`;
+  section += `${formatUsageLine(display, { locale })}\n`;
+  section += `${lt('telegram_rate_limit_responses', { count: telegramRateLimit.rateLimitResponses }, { locale })}\n`;
+  if (lastRateLimit) section += `${lt('telegram_last_rate_limit', { method: lastRateLimit.method }, { locale })}\n`;
+  return section;
+}
+
+export default { formatRetryDuration, formatTelegramLimitsSection };

package/src/telegram-rate-limit.lib.mjs

@@ -1,24 +1,59 @@
 /**
- * In-process Telegram Bot API rate-limit telemetry.
+ * Telegram Bot API rate-limit telemetry for `/limits` (issues #2060 and #2070).
  *
- * Telegram does not expose a quota endpoint. The Bot API documents approximate
- * outbound-message limits and reports actual flood control as error 429 with a
- * ResponseParameters.retry_after value. This tracker therefore combines local
- * rolling counters with the last observed server-side throttle.
+ * Telegram exposes no quota endpoint, and the official open-source Bot API
+ * server does not even implement the sending limits: `Client::get_retry_after_time`
+ * only parses `"Too Many Requests: retry after "` out of errors relayed from
+ * Telegram's closed backend. The published numbers are hedged ("about 30",
+ * "~30 users per second", "we may allow short bursts that go over this limit"),
+ * and Telegram tells bot authors to write clients that do not "depend on
+ * hardcoded limit values".
+ *
+ * This module therefore does not pretend to mirror a server counter. It keeps
+ * rolling windows modelled on the documented limits and then corrects each
+ * window's limit from what Telegram actually does: a successful call proves the
+ * window it landed in is allowed, and a 429 proves the window it landed in is
+ * not. The documented values are only a starting point.
+ *
+ * References:
+ * - https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this
+ * - https://core.telegram.org/bots/api#responseparameters
+ * - https://core.telegram.org/bots/features#dedicated-test-environment
+ * - https://github.com/tdlib/telegram-bot-api/blob/master/telegram-bot-api/Client.cpp
+ * - https://github.com/tdlib/td/issues/3034 (message edits share the sending limits)
+ * - https://grammy.dev/advanced/flood
+ */
+
+const SECOND_MS = 1_000;
+const MINUTE_MS = 60_000;
+
+/**
+ * The windows Telegram is believed to enforce, with the evidence for each size.
+ *
+ * `chat` restates the documented "avoid sending more than one message per
+ * second" advisory as a sustained rate over a minute, because the same FAQ
+ * allows short bursts above it. grammY models that advisory the same way, as a
+ * sustained rate rather than a hard per-second cap.
+ *
+ * `other` has no documented size: Telegram states no limit for `getUpdates`,
+ * `getMe` or `answerCallbackQuery`, yet grammY lists "getUpdates cannot receive
+ * flood wait errors" among the false assumptions. It stays unknown, and hidden,
+ * until a 429 measures it.
  */
+export const TELEGRAM_LIMIT_RULES = Object.freeze([Object.freeze({ id: 'chat', kind: 'message', scope: 'chat', windowMs: MINUTE_MS, documentedLimit: 60 }), Object.freeze({ id: 'group', kind: 'message', scope: 'group', windowMs: MINUTE_MS, documentedLimit: 20 }), Object.freeze({ id: 'broadcast', kind: 'message', scope: 'global', windowMs: SECOND_MS, documentedLimit: 30 }), Object.freeze({ id: 'other', kind: 'other', scope: 'global', windowMs: SECOND_MS, documentedLimit: null })]);
 
-export const TELEGRAM_RATE_LIMITS = Object.freeze({
-  GLOBAL_MESSAGES_PER_SECOND: 30,
-  GROUP_MESSAGES_PER_MINUTE: 20,
-});
+/** A window must be at least this full before a 429 can be blamed on it. */
+const BLAME_UTILIZATION = 0.5;
 
 const TRACKER_INSTALLED = Symbol.for('hiveMind.telegramRateLimitTrackerInstalled');
+const MAX_WINDOW_MS = Math.max(...TELEGRAM_LIMIT_RULES.map(rule => rule.windowMs));
 
-function isMessageMethod(method) {
-  const name = String(method || '');
-  if (/^sendChatAction$/i.test(name)) return false;
-  return /^(send|copyMessage$|forwardMessage$|editMessage)/i.test(name);
-}
+/**
+ * Chat-scoped methods that read or signal instead of producing a message.
+ * telegraf-throttler excludes exactly these from the per-group sending limit.
+ * https://github.com/KnightNiwrem/telegraf-throttler
+ */
+const NON_MESSAGE_CHAT_METHODS = new Set(['sendchataction', 'getchat', 'getchatadministrators', 'getchatmember', 'getchatmembercount', 'getchatmemberscount']);
 
 function toChatId(payload) {
   const value = payload?.chat_id;
@@ -33,6 +68,32 @@ function percentage(used, limit) {
   return limit > 0 ? Math.min(100, Math.round((used / limit) * 100)) : 0;
 }
 
+/**
+ * Decide which limits a request is subject to.
+ *
+ * grammY, python-telegram-bot and telegraf-throttler all key on the presence of
+ * `chat_id` rather than on a method allow-list, because that parameter is what
+ * scopes a call to a conversation. Doing the same keeps message edits inside the
+ * sending limits, which TDLib's maintainer confirms they share.
+ */
+export function classifyTelegramRequest(method, payload = {}) {
+  const name = String(method || '');
+  const chatId = toChatId(payload);
+  const kind = chatId !== null && !NON_MESSAGE_CHAT_METHODS.has(name.toLowerCase()) ? 'message' : 'other';
+  return { method: name, chatId, kind, isGroup: isGroupChatId(chatId) };
+}
+
+function ruleMatches(rule, event) {
+  if (rule.kind !== event.kind) return false;
+  if (rule.scope === 'group') return event.isGroup;
+  if (rule.scope === 'chat') return event.chatId !== null;
+  return true;
+}
+
+function ruleKey(rule, event) {
+  return rule.scope === 'global' ? '' : event.chatId;
+}
+
 function extractRateLimitError(error) {
   const response = error?.response || error;
   const code = response?.error_code ?? response?.status ?? error?.code;
@@ -47,84 +108,202 @@ function extractRateLimitError(error) {
   };
 }
 
+/** Order candidates so the window closest to refusing the next request wins. */
+function isMoreConstrained(candidate, best) {
+  if (candidate.throttled !== best.throttled) return candidate.throttled;
+  if (candidate.remaining !== best.remaining) return candidate.remaining < best.remaining;
+  if (candidate.used !== best.used) return candidate.used > best.used;
+  return candidate.usedPercentage > best.usedPercentage;
+}
+
+function mostUtilized(candidates) {
+  return candidates.reduce((best, candidate) => (candidate.utilization > best.utilization ? candidate : best));
+}
+
 export class TelegramRateLimitTracker {
   constructor({ now = Date.now } = {}) {
     this.now = now;
-    this.messageEvents = [];
+    this.events = [];
     this.totalApiRequests = 0;
+    this.messageRequests = 0;
     this.rateLimitResponses = 0;
     this.lastRateLimit = null;
+    this.rules = new Map(
+      TELEGRAM_LIMIT_RULES.map(rule => [
+        rule.id,
+        {
+          rule,
+          limit: rule.documentedLimit,
+          limitSource: rule.documentedLimit === null ? 'unknown' : 'documented',
+          peak: 0,
+          throttledUntil: null,
+        },
+      ])
+    );
   }
 
   prune(now = this.now()) {
-    const oldestRelevant = now - 60_000;
-    this.messageEvents = this.messageEvents.filter(event => event.at > oldestRelevant);
+    const oldestRelevant = now - MAX_WINDOW_MS;
+    this.events = this.events.filter(event => event.at > oldestRelevant);
   }
 
+  /** Count matching requests inside one rule's window, split by chat when scoped. */
+  windowCounts(rule, now) {
+    const oldestRelevant = now - rule.windowMs;
+    const counts = new Map();
+    for (const event of this.events) {
+      if (event.at <= oldestRelevant || !ruleMatches(rule, event)) continue;
+      const key = ruleKey(rule, event);
+      counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    return counts;
+  }
+
+  /**
+   * Record an outbound request and return the window counts it lands in, so the
+   * eventual response can be attributed to those exact windows.
+   */
   recordRequest(method, payload = {}) {
+    const at = this.now();
+    const event = { at, ...classifyTelegramRequest(method, payload) };
     this.totalApiRequests++;
-    if (!isMessageMethod(method)) return;
+    if (event.kind === 'message') this.messageRequests++;
+    this.events.push(event);
+    this.prune(at);
 
-    const now = this.now();
-    const chatId = toChatId(payload);
-    this.messageEvents.push({ at: now, method: String(method), chatId, isGroup: isGroupChatId(chatId) });
-    this.prune(now);
+    const counts = new Map();
+    for (const rule of TELEGRAM_LIMIT_RULES) {
+      if (!ruleMatches(rule, event)) continue;
+      counts.set(rule.id, this.windowCounts(rule, at).get(ruleKey(rule, event)) || 0);
+    }
+    return { event, counts };
+  }
+
+  /** Telegram accepted the request, so every window it landed in tolerates its count. */
+  recordSuccess(pending) {
+    if (!pending?.counts) return;
+    for (const [id, count] of pending.counts) {
+      const state = this.rules.get(id);
+      if (count > state.peak) state.peak = count;
+      // An unknown limit stays unknown: a success proves capacity, never a ceiling.
+      if (state.limit !== null && count > state.limit) {
+        state.limit = count;
+        state.limitSource = 'observed';
+      }
+    }
   }
 
-  recordError(error, method, payload = {}) {
-    const rateLimit = extractRateLimitError(error);
-    if (!rateLimit) return false;
+  /**
+   * Pick the window that best explains a 429, or none when no modelled window
+   * was full enough to be a plausible cause.
+   */
+  blameRule(pending) {
+    if (!pending?.counts?.size) return null;
+    const candidates = [];
+    for (const [id, count] of pending.counts) {
+      const state = this.rules.get(id);
+      const utilization = state.limit === null ? Infinity : count / state.limit;
+      candidates.push({ state, count, utilization, explained: state.limit !== null && count >= state.limit });
+    }
 
-    const observedAt = this.now();
+    const explained = candidates.filter(candidate => candidate.explained);
+    if (explained.length) return mostUtilized(explained);
+    // A 429 that arrives while every window is nearly empty was caused by state
+    // we cannot observe: flood control carries a penalty across windows and
+    // escalates on repeat offences. Blaming a window would collapse its limit
+    // for no reason, so learn nothing and only report the throttle.
+    const plausible = candidates.filter(candidate => candidate.count >= 2 && candidate.utilization >= BLAME_UTILIZATION);
+    return plausible.length ? mostUtilized(plausible) : null;
+  }
+
+  recordError(error, pending = null) {
+    const details = extractRateLimitError(error);
+    if (!details) return null;
+
+    const at = this.now();
     this.rateLimitResponses++;
+    const retryUntil = details.retryAfterSeconds === null ? null : at + details.retryAfterSeconds * SECOND_MS;
+    const blamed = this.blameRule(pending);
+    // Blame is decided from the count including this request, but the request
+    // itself was refused: it never landed in any window. Dropping it keeps the
+    // windows a record of what Telegram accepted, so `used` cannot exceed the
+    // ceiling the refusal just proved.
+    const landed = this.events.indexOf(pending?.event);
+    if (landed !== -1) this.events.splice(landed, 1);
+    if (blamed && !blamed.explained) {
+      // Telegram refused a window our estimate still considered allowed, so the
+      // estimate is too high: the real limit is below the refused count.
+      blamed.state.limit = Math.max(1, blamed.count - 1);
+      blamed.state.limitSource = 'observed';
+    }
+    if (blamed) blamed.state.throttledUntil = retryUntil;
+
     this.lastRateLimit = {
-      ...rateLimit,
-      method: String(method || 'unknown'),
-      chatId: toChatId(payload),
-      observedAt,
-      retryUntil: rateLimit.retryAfterSeconds === null ? null : observedAt + rateLimit.retryAfterSeconds * 1_000,
+      method: pending?.event?.method || 'unknown',
+      chatId: pending?.event?.chatId ?? null,
+      retryAfterSeconds: details.retryAfterSeconds,
+      description: details.description,
+      observedAt: at,
+      retryUntil,
+      ruleId: blamed?.state.rule.id ?? null,
     };
-    return true;
+    return this.lastRateLimit;
   }
 
-  getSnapshot() {
-    const now = this.now();
-    this.prune(now);
+  describeRule(rule, now) {
+    const state = this.rules.get(rule.id);
+    if (state.limit === null) return null;
 
-    const globalUsed = this.messageEvents.filter(event => event.at > now - 1_000).length;
-    const groupCounts = new Map();
-    for (const event of this.messageEvents) {
-      if (!event.isGroup || event.chatId === null) continue;
-      groupCounts.set(event.chatId, (groupCounts.get(event.chatId) || 0) + 1);
+    let busiest = null;
+    for (const [key, count] of this.windowCounts(rule, now)) {
+      if (!busiest || count > busiest.count) busiest = { key, count };
     }
-    let busiestGroupChatId = null;
-    let busiestGroupUsed = 0;
-    for (const [chatId, count] of groupCounts) {
-      if (count > busiestGroupUsed) {
-        busiestGroupChatId = chatId;
-        busiestGroupUsed = count;
-      }
+    // A per-chat window with no traffic has no subject, so showing it would add
+    // a phantom bar for a conversation the bot is not talking to.
+    if (!busiest) {
+      if (rule.scope !== 'global') return null;
+      busiest = { key: '', count: 0 };
     }
 
-    let lastRateLimit = null;
-    if (this.lastRateLimit) {
-      const retryRemainingSeconds = this.lastRateLimit.retryUntil === null ? null : Math.max(0, Math.ceil((this.lastRateLimit.retryUntil - now) / 1_000));
-      lastRateLimit = { ...this.lastRateLimit, retryRemainingSeconds };
+    return {
+      id: rule.id,
+      scope: rule.scope,
+      windowMs: rule.windowMs,
+      chatId: rule.scope === 'global' ? null : busiest.key,
+      used: busiest.count,
+      limit: state.limit,
+      limitSource: state.limitSource,
+      peak: state.peak,
+      remaining: Math.max(0, state.limit - busiest.count),
+      usedPercentage: percentage(busiest.count, state.limit),
+      throttled: state.throttledUntil !== null && state.throttledUntil > now,
+    };
+  }
+
+  describeLastRateLimit(now) {
+    if (!this.lastRateLimit) return null;
+    const { retryUntil } = this.lastRateLimit;
+    const retryRemainingSeconds = retryUntil === null ? null : Math.max(0, Math.ceil((retryUntil - now) / SECOND_MS));
+    return { ...this.lastRateLimit, retryRemainingSeconds };
+  }
+
+  getSnapshot() {
+    const now = this.now();
+    this.prune(now);
+
+    const rules = TELEGRAM_LIMIT_RULES.map(rule => this.describeRule(rule, now)).filter(Boolean);
+    let display = null;
+    for (const candidate of rules) {
+      if (!display || isMoreConstrained(candidate, display)) display = candidate;
     }
 
+    const lastRateLimit = this.describeLastRateLimit(now);
     return {
-      global: {
-        used: globalUsed,
-        limit: TELEGRAM_RATE_LIMITS.GLOBAL_MESSAGES_PER_SECOND,
-        usedPercentage: percentage(globalUsed, TELEGRAM_RATE_LIMITS.GLOBAL_MESSAGES_PER_SECOND),
-      },
-      busiestGroup: {
-        used: busiestGroupUsed,
-        limit: TELEGRAM_RATE_LIMITS.GROUP_MESSAGES_PER_MINUTE,
-        usedPercentage: percentage(busiestGroupUsed, TELEGRAM_RATE_LIMITS.GROUP_MESSAGES_PER_MINUTE),
-        chatId: busiestGroupChatId,
-      },
+      display,
+      rules,
+      throttled: Boolean(lastRateLimit?.retryRemainingSeconds),
       totalApiRequests: this.totalApiRequests,
+      messageRequests: this.messageRequests,
       rateLimitResponses: this.rateLimitResponses,
       lastRateLimit,
     };
@@ -139,23 +318,27 @@ export function getTelegramRateLimits(verbose = false) {
   return { success: true, telegramRateLimit };
 }
 
+/**
+ * Observe every Bot API call from Telegraf's single `callApi` choke point, which
+ * also carries `getUpdates` long polling, without delaying, retrying, reordering
+ * or swallowing anything.
+ */
 export function installTelegramRateLimitTracker(telegram, { tracker = defaultTracker, verbose = false } = {}) {
   if (!telegram || telegram[TRACKER_INSTALLED]) return telegram;
   const originalCallApi = telegram.callApi;
   if (typeof originalCallApi !== 'function') return telegram;
 
   telegram.callApi = async function trackedCallApi(method, payload = {}, ...rest) {
-    tracker.recordRequest(method, payload);
-    if (verbose && isMessageMethod(method)) {
-      const snapshot = tracker.getSnapshot();
-      console.log(`[VERBOSE] Telegram Bot API ${method}: global ${snapshot.global.used}/${snapshot.global.limit} messages/1s; busiest group ${snapshot.busiestGroup.used}/${snapshot.busiestGroup.limit} messages/1m`);
-    }
+    const pending = tracker.recordRequest(method, payload);
     try {
-      return await originalCallApi.call(this, method, payload, ...rest);
+      const result = await originalCallApi.call(this, method, payload, ...rest);
+      tracker.recordSuccess(pending);
+      if (verbose) console.log(`[VERBOSE] Telegram Bot API ${method} accepted; windows: ${JSON.stringify(Object.fromEntries(pending.counts))}`);
+      return result;
     } catch (error) {
-      if (tracker.recordError(error, method, payload)) {
-        const observed = tracker.getSnapshot().lastRateLimit;
-        console.warn(`[telegram-bot] Telegram Bot API rate limit: method=${observed.method} chat=${observed.chatId ?? 'unknown'} retry_after=${observed.retryAfterSeconds ?? 'unknown'}s`);
+      const observed = tracker.recordError(error, pending);
+      if (observed) {
+        console.warn(`[telegram-bot] Telegram Bot API rate limit: method=${observed.method} chat=${observed.chatId ?? 'unknown'} retry_after=${observed.retryAfterSeconds ?? 'unknown'}s window=${observed.ruleId ?? 'unattributed'}`);
         if (verbose) console.error('[VERBOSE] Telegram Bot API 429 response:', JSON.stringify(error?.response || { message: error?.message }, null, 2));
       }
       throw error;