@link-assistant/hive-mind 2.5.6 → 2.6.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 2.6.1
+
+### Patch Changes
+
+- 9ab8794: Make `HIVE_MIND_MIN_START_INTERVAL_MS` authoritative, warn when it is below the recommended 10-minute interval, and deprecate the redundant floor variable.
+
+## 2.6.0
+
+### Minor Changes
+
+- c031b7b: Handle weekly-only Codex usage windows and add Telegram Bot API rolling rate-limit telemetry to `/limits`.
+
 ## 2.5.6
 
 ### Patch Changes

package/package.json

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

package/src/codex-rate-limit-windows.lib.mjs

@@ -0,0 +1,27 @@
+/**
+ * Classify raw Codex windows by duration instead of response position.
+ *
+ * Historically the primary window was five hours and the secondary window was
+ * weekly. Weekly-only accounts can put the weekly value in the primary slot.
+ */
+export function classifyCodexRateLimitWindows(rateLimit) {
+  const primary = rateLimit?.primary_window;
+  const secondary = rateLimit?.secondary_window;
+  const windows = [primary, secondary].filter(Boolean);
+  const hasDurationMetadata = windows.some(window => Number.isFinite(Number(window?.limit_window_seconds)));
+
+  if (!hasDurationMetadata) {
+    return { sessionWindow: primary, weeklyWindow: secondary };
+  }
+
+  const sessionWindow = windows.find(window => {
+    const seconds = Number(window?.limit_window_seconds);
+    return Number.isFinite(seconds) && seconds > 0 && seconds < 24 * 60 * 60;
+  });
+  const weeklyWindow = windows.find(window => {
+    const seconds = Number(window?.limit_window_seconds);
+    return Number.isFinite(seconds) && seconds >= 24 * 60 * 60;
+  });
+
+  return { sessionWindow, weeklyWindow };
+}

package/src/env-config.lib.mjs

@@ -16,6 +16,19 @@ function readExplicitEnv(envVar) {
   return rawValue === undefined ? null : rawValue;
 }
 
+/**
+ * Emit a warning once when an environment variable was explicitly configured.
+ *
+ * @param {string} envVar
+ * @param {string} warningKey
+ * @param {string} message
+ */
+export function warnExplicitEnv(envVar, warningKey, message) {
+  if (readExplicitEnv(envVar) !== null) {
+    warnOnce(`${warningKey}:${envVar}`, message);
+  }
+}
+
 function warnInvalid(envVar, rawValue, type, defaultValue, scope) {
   warnOnce(`invalid:${envVar}`, `[${scope}] ${envVar}=${JSON.stringify(rawValue)} is not a valid ${type}; using default ${defaultValue}.`);
 }

package/src/limits-i18n.lib.mjs

@@ -85,6 +85,12 @@ 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_last_rate_limit: 'Last 429: {{method}}',
+  telegram_rate_limit_responses: '429 responses since startup: {{count}}',
+  telegram_retry_in: 'retry in {{seconds}}s',
   trial_ends: 'Trial ends {{time}}',
   trial_ends_in: 'Trial ends in {{duration}} ({{time}})',
   unavailable: 'unavailable',

package/src/limits.lib.mjs

@@ -12,9 +12,11 @@ import { promisify } from 'node:util';
 import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc.js';
 
+import { classifyCodexRateLimitWindows } from './codex-rate-limit-windows.lib.mjs';
 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';
+import { getTelegramRateLimits } from './telegram-rate-limit.lib.mjs';
 export { getCachedClaudeSubscription, getCachedCodexSubscription, getClaudeSubscriptionInfo, getCodexSubscriptionInfo };
 // Initialize dayjs plugins
 dayjs.extend(utc);
@@ -75,6 +77,15 @@ function mapCodexWindow(window) {
   };
 }
 
+export function mapCodexRateLimitWindows(rateLimit) {
+  const { sessionWindow, weeklyWindow } = classifyCodexRateLimitWindows(rateLimit);
+
+  return {
+    currentSession: mapCodexWindow(sessionWindow),
+    allModels: mapCodexWindow(weeklyWindow),
+  };
+}
+
 export async function readCodexAuth(authPath = DEFAULT_CODEX_AUTH_PATH, verbose = false) {
   try {
     const content = await readFile(authPath, 'utf-8');
@@ -936,8 +947,7 @@ export async function getCodexUsageLimits(verbose = false, authPath = DEFAULT_CO
     }
 
     const usage = {
-      currentSession: mapCodexWindow(data?.rate_limit?.primary_window),
-      allModels: mapCodexWindow(data?.rate_limit?.secondary_window),
+      ...mapCodexRateLimitWindows(data?.rate_limit),
       sonnetOnly: {
         percentage: null,
         resetTime: null,
@@ -949,8 +959,7 @@ export async function getCodexUsageLimits(verbose = false, authPath = DEFAULT_CO
       ? data.additional_rate_limits.map(limit => ({
           limitId: limit?.metered_feature || null,
           limitName: limit?.limit_name || limit?.metered_feature || 'additional',
-          currentSession: mapCodexWindow(limit?.rate_limit?.primary_window),
-          allModels: mapCodexWindow(limit?.rate_limit?.secondary_window),
+          ...mapCodexRateLimitWindows(limit?.rate_limit),
           allowed: limit?.rate_limit?.allowed ?? null,
           limitReached: limit?.rate_limit?.limit_reached ?? null,
         }))
@@ -1116,6 +1125,24 @@ 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 claudeHeading = formatSubscriptionHeading('claude', subscription, { locale });
   const useShortClaudeLabels = Boolean(claudeHeading);
   const claudeSections = [];
@@ -1194,7 +1221,7 @@ export function formatCodexLimitsSection(codexLimits, codexError = null, options
   const sessionSection = formatLimitWindowSection(useTitledLayout ? lt('five_hour_limit_session', {}, { locale }) : lt('codex_5_hour_session', {}, { locale }), usage?.currentSession, 5, DISPLAY_THRESHOLDS.CODEX_5_HOUR_SESSION, { locale });
   const weeklySection = formatLimitWindowSection(useTitledLayout ? lt('current_week', {}, { locale }) : lt('current_week_all_models', {}, { locale }), usage?.allModels, 168, DISPLAY_THRESHOLDS.CODEX_WEEKLY, { locale });
 
-  section += `${sessionSection}\n${weeklySection}`;
+  section += [sessionSection, weeklySection].filter((_, index) => (index === 0 ? hasLimitPercentage(usage?.currentSession) : hasLimitPercentage(usage?.allModels))).join('\n');
 
   const visibleAdditionalRateLimits = additionalRateLimits.filter(limit => hasPositivePercentage(limit.allModels?.percentage));
   if (visibleAdditionalRateLimits.length > 0) {
@@ -1202,9 +1229,10 @@ export function formatCodexLimitsSection(codexLimits, codexError = null, options
     for (const limit of visibleAdditionalRateLimits) {
       const sessionPct = limit.currentSession?.percentage;
       const weeklyPct = limit.allModels?.percentage;
-      const sessionText = sessionPct === null || sessionPct === undefined ? `${lt('session', {}, { locale })} ${lt('na', {}, { locale })}` : `${lt('session', {}, { locale })} ${Math.floor(sessionPct)}%`;
-      const weeklyText = weeklyPct === null || weeklyPct === undefined ? `${lt('week', {}, { locale })} ${lt('na', {}, { locale })}` : `${lt('week', {}, { locale })} ${Math.floor(weeklyPct)}%`;
-      section += `${limit.limitName}: ${sessionText}, ${weeklyText}\n`;
+      const windowTexts = [];
+      if (sessionPct !== null && sessionPct !== undefined) windowTexts.push(`${lt('session', {}, { locale })} ${Math.floor(sessionPct)}%`);
+      if (weeklyPct !== null && weeklyPct !== undefined) windowTexts.push(`${lt('week', {}, { locale })} ${Math.floor(weeklyPct)}%`);
+      section += `${limit.limitName}: ${windowTexts.join(', ')}\n`;
     }
   }
 
@@ -1409,8 +1437,8 @@ export async function getCachedDiskInfo(verbose = false) {
 }
 
 export async function getAllCachedLimits(verbose = false) {
-  const [claude, codex, github, memory, cpu, disk, claudeSubscription, codexSubscription] = await Promise.all([getCachedClaudeLimits(verbose), getCachedCodexLimits(verbose), getCachedGitHubLimits(verbose), getCachedMemoryInfo(verbose), getCachedCpuInfo(verbose), getCachedDiskInfo(verbose), getCachedClaudeSubscription(verbose), getCachedCodexSubscription(verbose)]);
-  return { claude, codex, github, memory, cpu, disk, claudeSubscription, codexSubscription };
+  const [claude, codex, github, memory, cpu, disk, claudeSubscription, codexSubscription, telegram] = await Promise.all([getCachedClaudeLimits(verbose), getCachedCodexLimits(verbose), getCachedGitHubLimits(verbose), getCachedMemoryInfo(verbose), getCachedCpuInfo(verbose), getCachedDiskInfo(verbose), getCachedClaudeSubscription(verbose), getCachedCodexSubscription(verbose), getTelegramRateLimits(verbose)]);
+  return { claude, codex, github, memory, cpu, disk, claudeSubscription, codexSubscription, telegram };
 }
 
 export default {

package/src/locales/en.lino

@@ -334,6 +334,20 @@ en
         label "Subscription ends {{time}}"
         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"
+      last
+        rate
+          limit "Last 429: {{method}}"
+      rate
+        limit
+          responses "429 responses since startup: {{count}}"
+      retry
+        in "retry in {{seconds}}s"
     trial
       ends
         label "Trial ends {{time}}"

package/src/locales/hi.lino

@@ -334,6 +334,20 @@ hi
         label "सदस्यता समाप्त होगी {{time}}"
         in "सदस्यता {{duration}} में समाप्त होगी ({{time}})"
       status "सदस्यता: {{status}}"
+    telegram
+      api "Telegram Bot API (स्थानीय रोलिंग टेलीमेट्री)"
+      global
+        window "1 सेकंड में {{used}}/{{limit}} संदेश"
+      group
+        window "सबसे व्यस्त समूह में 1 मिनट में {{used}}/{{limit}} संदेश"
+      last
+        rate
+          limit "अंतिम 429: {{method}}"
+      rate
+        limit
+          responses "स्टार्टअप के बाद 429 प्रतिक्रियाएँ: {{count}}"
+      retry
+        in "{{seconds}} सेकंड में पुनः प्रयास"
     trial
       ends
         label "ट्रायल समाप्त होगा {{time}}"

package/src/locales/ru.lino

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

package/src/locales/zh.lino

@@ -334,6 +334,20 @@ zh
         label "订阅结束于 {{time}}"
         in "订阅将在 {{duration}} 后结束 ({{time}})"
       status "订阅: {{status}}"
+    telegram
+      api "Telegram Bot API（本地滚动遥测）"
+      global
+        window "1 秒内 {{used}}/{{limit}} 条消息"
+      group
+        window "最繁忙群组 1 分钟内 {{used}}/{{limit}} 条消息"
+      last
+        rate
+          limit "最近一次 429：{{method}}"
+      rate
+        limit
+          responses "启动后的 429 响应：{{count}}"
+      retry
+        in "{{seconds}} 秒后重试"
     trial
       ends
         label "试用结束于 {{time}}"

package/src/queue-config.lib.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { ensureUseM } from './use-m-bootstrap.lib.mjs';
-import { clampEnvValue, parseIntegerEnv, parseNumberEnv } from './env-config.lib.mjs';
+import { parseIntegerEnv, parseNumberEnv, warnExplicitEnv } from './env-config.lib.mjs';
 
 /**
  * Queue Configuration Module
@@ -183,7 +183,32 @@ const parseFloatWithDefault = (envVar, defaultValue) => parseNumberEnv(envVar, d
 const parseIntWithDefault = (envVar, defaultValue) => parseIntegerEnv(envVar, defaultValue, { scope: 'queue-config' });
 
 const DEFAULT_MINIMUM_START_INTERVAL_MS = 10 * 60 * 1000;
-const minimumStartIntervalMs = parseIntWithDefault('HIVE_MIND_MIN_START_INTERVAL_FLOOR_MS', DEFAULT_MINIMUM_START_INTERVAL_MS);
+const START_INTERVAL_ENV = 'HIVE_MIND_MIN_START_INTERVAL_MS';
+const LEGACY_START_INTERVAL_FLOOR_ENV = 'HIVE_MIND_MIN_START_INTERVAL_FLOOR_MS';
+
+function resolveMinimumStartIntervalMs() {
+  const hasExplicitInterval = process.env[START_INTERVAL_ENV] !== undefined;
+  const hasLegacyFloor = process.env[LEGACY_START_INTERVAL_FLOOR_ENV] !== undefined;
+
+  if (hasLegacyFloor) {
+    warnExplicitEnv(LEGACY_START_INTERVAL_FLOOR_ENV, 'deprecated', `[queue-config] ${LEGACY_START_INTERVAL_FLOOR_ENV} is deprecated; use ${START_INTERVAL_ENV} instead.`);
+  }
+
+  let interval = DEFAULT_MINIMUM_START_INTERVAL_MS;
+  if (hasExplicitInterval) {
+    interval = parseIntWithDefault(START_INTERVAL_ENV, DEFAULT_MINIMUM_START_INTERVAL_MS);
+  } else if (hasLegacyFloor) {
+    interval = parseIntWithDefault(LEGACY_START_INTERVAL_FLOOR_ENV, DEFAULT_MINIMUM_START_INTERVAL_MS);
+  }
+
+  if (hasExplicitInterval && interval < DEFAULT_MINIMUM_START_INTERVAL_MS) {
+    warnExplicitEnv(START_INTERVAL_ENV, 'recommendation', `[queue-config] ${START_INTERVAL_ENV}=${interval} is below the recommended ${DEFAULT_MINIMUM_START_INTERVAL_MS} ms; short intervals can start a backlog before host metrics settle (#2015).`);
+  }
+
+  return interval;
+}
+
+const minimumStartIntervalMs = resolveMinimumStartIntervalMs();
 
 // Parse links notation config from environment variable (if provided)
 const linoConfig = parseQueueConfig(getenv('HIVE_MIND_QUEUE_CONFIG', ''));
@@ -267,13 +292,10 @@ export const QUEUE_CONFIG = {
   // MIN_START_INTERVAL_MS: Minimum global spacing between task startups.
   // Issue #2015: after resource thresholds clear, starting a backlog in a burst
   // can kill the next batch before host metrics have time to settle.
-  // Issue #2053: operators can explicitly lower the safety floor on hosts where
-  // resource metrics settle sooner. The default remains 10 minutes.
-  MIN_START_INTERVAL_MS: clampEnvValue('HIVE_MIND_MIN_START_INTERVAL_MS', parseIntWithDefault('HIVE_MIND_MIN_START_INTERVAL_MS', DEFAULT_MINIMUM_START_INTERVAL_MS), {
-    minimum: minimumStartIntervalMs,
-    scope: 'queue-config',
-    hint: 'Set HIVE_MIND_MIN_START_INTERVAL_FLOOR_MS to lower the minimum.',
-  }),
+  // Issue #2065: an explicit interval is authoritative. The deprecated floor
+  // remains a fallback for existing deployments, while the default remains the
+  // safe 10-minute interval introduced for issue #2015.
+  MIN_START_INTERVAL_MS: minimumStartIntervalMs,
   CONSUMER_POLL_INTERVAL_MS: parseIntWithDefault('HIVE_MIND_CONSUMER_POLL_INTERVAL_MS', 60000), // 1 minute between queue checks
   MESSAGE_UPDATE_INTERVAL_MS: parseIntWithDefault('HIVE_MIND_MESSAGE_UPDATE_INTERVAL_MS', 60000), // 1 minute between status message updates
 

package/src/telegram-bot.mjs

@@ -329,6 +329,7 @@ const { executeStartScreen: executeStartScreenCommand, buildExecuteAndUpdateMess
 const { isChatStopped, getChatStopInfo, getStoppedChatRejectMessage, DEFAULT_STOP_REASON } = await import('./telegram-start-stop-command.lib.mjs');
 const { isOldMessage: _isOldMessage, isGroupChat: _isGroupChat, isChatAuthorized: _isChatAuthorized, isForwarded: _isForwarded, isForwardedOrReply: _isForwardedOrReply, extractCommandFromText, extractGitHubUrl: _extractGitHubUrl } = await import('./telegram-message-filters.lib.mjs');
 const { installTelegramFormattingFallback, isTelegramFormattingError, isTelegramMessageTooLongError, safeEditMessageText, safeReply, TELEGRAM_TEXT_LIMIT } = await import('./telegram-safe-reply.lib.mjs');
+const { installTelegramRateLimitTracker } = await import('./telegram-rate-limit.lib.mjs');
 const { registerTerminalWatchCommand, startAutoTerminalWatchForSession } = await import('./telegram-terminal-watch-command.lib.mjs');
 const { launchBotWithRetry } = await import('./telegram-bot-launcher.lib.mjs');
 const { trackSession, untrackSession, startSessionMonitoring, hasActiveSessionForUrlAsync, findStoppableSessionByUrl, setSessionStore, setSessionLogger, resumeTrackedSessions, getActiveSessionCount } = await import('./session-monitor.lib.mjs');
@@ -352,12 +353,11 @@ await preloadAllLocales();
 
 const telegrafModule = await use('telegraf');
 const { Telegraf } = telegrafModule;
-
 const bot = new Telegraf(BOT_TOKEN, {
   handlerTimeout: Infinity, // Remove default 90s timeout; command handlers like /solve spawn long-running processes
 });
 installTelegramFormattingFallback(bot.telegram, { verbose: VERBOSE });
-
+installTelegramRateLimitTracker(bot.telegram, { verbose: VERBOSE });
 // Track bot startup time (Unix seconds to match Telegram's message.date format)
 const BOT_START_TIME = Math.floor(Date.now() / 1000);
 
@@ -635,7 +635,7 @@ bot.command('limits', async ctx => {
   const claudeSubscription = limits.claudeSubscription?.success ? limits.claudeSubscription.subscription : null;
   const codexSubscription = limits.codexSubscription?.success ? limits.codexSubscription.subscription : null;
   const codexSection = formatCodexLimitsSection(limits.codex.success ? limits.codex : null, codexError, { locale: userLocale, subscription: codexSubscription });
-  const message = t('telegram.usage_limits_title', {}, { locale: userLocale }) + '\n\n' + formatUsageMessage(limits.claude.success ? limits.claude.usage : null, limits.disk.success ? limits.disk.diskSpace : null, limits.github.success ? limits.github.githubRateLimit : null, limits.cpu.success ? limits.cpu.cpuLoad : null, limits.memory.success ? limits.memory.memory : null, claudeError, [codexSection, queueStatus], { locale: userLocale, subscription: claudeSubscription });
+  const message = t('telegram.usage_limits_title', {}, { locale: userLocale }) + '\n\n' + formatUsageMessage(limits.claude.success ? limits.claude.usage : null, limits.disk.success ? limits.disk.diskSpace : null, limits.github.success ? limits.github.githubRateLimit : null, limits.cpu.success ? limits.cpu.cpuLoad : null, limits.memory.success ? limits.memory.memory : null, claudeError, [codexSection, queueStatus], { locale: userLocale, subscription: claudeSubscription, telegramRateLimit: limits.telegram.telegramRateLimit });
   await safeEditMessageText(ctx.telegram, fetchingMessage.chat.id, fetchingMessage.message_id, undefined, message, { parse_mode: 'Markdown', fallbackLocale: userLocale, verbose: VERBOSE });
 });
 bot.command('version', async ctx => {

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

@@ -0,0 +1,167 @@
+/**
+ * In-process Telegram Bot API rate-limit telemetry.
+ *
+ * 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.
+ */
+
+export const TELEGRAM_RATE_LIMITS = Object.freeze({
+  GLOBAL_MESSAGES_PER_SECOND: 30,
+  GROUP_MESSAGES_PER_MINUTE: 20,
+});
+
+const TRACKER_INSTALLED = Symbol.for('hiveMind.telegramRateLimitTrackerInstalled');
+
+function isMessageMethod(method) {
+  const name = String(method || '');
+  if (/^sendChatAction$/i.test(name)) return false;
+  return /^(send|copyMessage$|forwardMessage$|editMessage)/i.test(name);
+}
+
+function toChatId(payload) {
+  const value = payload?.chat_id;
+  return value === null || value === undefined ? null : String(value);
+}
+
+function isGroupChatId(chatId) {
+  return typeof chatId === 'string' && chatId.startsWith('-');
+}
+
+function percentage(used, limit) {
+  return limit > 0 ? Math.min(100, Math.round((used / limit) * 100)) : 0;
+}
+
+function extractRateLimitError(error) {
+  const response = error?.response || error;
+  const code = response?.error_code ?? response?.status ?? error?.code;
+  const description = response?.description || error?.description || error?.message || '';
+  if (Number(code) !== 429 && !/\b429\b|too many requests/i.test(String(description))) return null;
+
+  const rawRetryAfter = response?.parameters?.retry_after ?? error?.parameters?.retry_after;
+  const retryAfterSeconds = Number(rawRetryAfter);
+  return {
+    retryAfterSeconds: Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0 ? retryAfterSeconds : null,
+    description: String(description),
+  };
+}
+
+export class TelegramRateLimitTracker {
+  constructor({ now = Date.now } = {}) {
+    this.now = now;
+    this.messageEvents = [];
+    this.totalApiRequests = 0;
+    this.rateLimitResponses = 0;
+    this.lastRateLimit = null;
+  }
+
+  prune(now = this.now()) {
+    const oldestRelevant = now - 60_000;
+    this.messageEvents = this.messageEvents.filter(event => event.at > oldestRelevant);
+  }
+
+  recordRequest(method, payload = {}) {
+    this.totalApiRequests++;
+    if (!isMessageMethod(method)) return;
+
+    const now = this.now();
+    const chatId = toChatId(payload);
+    this.messageEvents.push({ at: now, method: String(method), chatId, isGroup: isGroupChatId(chatId) });
+    this.prune(now);
+  }
+
+  recordError(error, method, payload = {}) {
+    const rateLimit = extractRateLimitError(error);
+    if (!rateLimit) return false;
+
+    const observedAt = this.now();
+    this.rateLimitResponses++;
+    this.lastRateLimit = {
+      ...rateLimit,
+      method: String(method || 'unknown'),
+      chatId: toChatId(payload),
+      observedAt,
+      retryUntil: rateLimit.retryAfterSeconds === null ? null : observedAt + rateLimit.retryAfterSeconds * 1_000,
+    };
+    return true;
+  }
+
+  getSnapshot() {
+    const now = this.now();
+    this.prune(now);
+
+    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 busiestGroupChatId = null;
+    let busiestGroupUsed = 0;
+    for (const [chatId, count] of groupCounts) {
+      if (count > busiestGroupUsed) {
+        busiestGroupChatId = chatId;
+        busiestGroupUsed = count;
+      }
+    }
+
+    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 {
+      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,
+      },
+      totalApiRequests: this.totalApiRequests,
+      rateLimitResponses: this.rateLimitResponses,
+      lastRateLimit,
+    };
+  }
+}
+
+const defaultTracker = new TelegramRateLimitTracker();
+
+export function getTelegramRateLimits(verbose = false) {
+  const telegramRateLimit = defaultTracker.getSnapshot();
+  if (verbose) console.log('[VERBOSE] /limits Telegram Bot API telemetry:', JSON.stringify(telegramRateLimit, null, 2));
+  return { success: true, telegramRateLimit };
+}
+
+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`);
+    }
+    try {
+      return await originalCallApi.call(this, method, payload, ...rest);
+    } 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`);
+        if (verbose) console.error('[VERBOSE] Telegram Bot API 429 response:', JSON.stringify(error?.response || { message: error?.message }, null, 2));
+      }
+      throw error;
+    }
+  };
+
+  telegram[TRACKER_INSTALLED] = true;
+  return telegram;
+}