@link-assistant/hive-mind 2.7.0 → 2.7.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 2.7.2
+
+### Patch Changes
+
+- c6add61: Add experimental `--auto-resume-on-uncommitted-changes` flag (#1056) that complements the existing `--auto-restart-on-uncommitted-changes` by reusing the previous Claude Code session via `--resume <sessionId>` when uncommitted changes are detected, preserving the agent's accumulated context instead of starting a fresh session. The flag is disabled by default. A companion knob, `--auto-resume-on-uncommitted-changes-maximum-context-window-usage` (default 50%), bounds the worst-case peak usage of the usable pre-compaction context (respecting `--sub-session-size`); sessions at or above the threshold, or sessions whose usage cannot be verified, fall back to a fresh run.
+
+## 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.2",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/auto-resume-uncommitted.lib.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-resume on uncommitted changes — decision helpers.
+ *
+ * Issue #1056: when uncommitted changes are detected and the user has
+ * enabled `--auto-resume-on-uncommitted-changes`, we want to call the
+ * agent again with `--resume <sessionId>` (preserving context) instead
+ * of starting a fresh session — but only when the previous session has
+ * not already filled most of its usable pre-compaction context. The threshold
+ * defaults to 50% of that usable limit and is configurable via
+ * `--auto-resume-on-uncommitted-changes-maximum-context-window-usage`.
+ *
+ * This module is intentionally tool-agnostic. It does not perform the
+ * resume itself — it just decides whether resuming is viable and
+ * computes the percentage that the caller can log.
+ */
+
+import { parseSubSessionSize } from './sub-session-size.lib.mjs';
+
+export const DEFAULT_MAX_CONTEXT_USAGE_PERCENT = 50;
+
+/**
+ * Read the configured max-context-usage threshold (in percent) from argv.
+ *
+ * Accepts both the camelCase form populated by yargs
+ * (`autoResumeOnUncommittedChangesMaximumContextWindowUsage`) and the
+ * dash-cased flag itself, so that programmatic callers and CLI users
+ * see the same default.
+ *
+ * @param {Object} argv - parsed CLI arguments
+ * @returns {number} threshold in [0, 100]
+ */
+export const getAutoResumeMaxContextUsage = (argv = {}) => {
+  const candidates = [argv.autoResumeOnUncommittedChangesMaximumContextWindowUsage, argv['auto-resume-on-uncommitted-changes-maximum-context-window-usage']];
+  for (const value of candidates) {
+    if (value === undefined || value === null || value === '') continue;
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (Number.isFinite(parsed)) return Math.max(0, Math.min(100, parsed));
+  }
+  return DEFAULT_MAX_CONTEXT_USAGE_PERCENT;
+};
+
+/**
+ * Whether `--auto-resume-on-uncommitted-changes` is enabled.
+ * @param {Object} argv
+ * @returns {boolean}
+ */
+export const isAutoResumeOnUncommittedChangesEnabled = (argv = {}) => {
+  return argv.autoResumeOnUncommittedChanges === true || argv['auto-resume-on-uncommitted-changes'] === true;
+};
+
+/**
+ * Pick the largest peak-context-input across all models in a token-usage map
+ * that has a known model context limit, and return both the peak and the
+ * matching limit. We use the worst (highest-utilisation) model so that
+ * resuming with multi-model sessions does not silently exceed the threshold
+ * for the model that has the smallest remaining headroom.
+ *
+ * @param {Object|null} tokenUsage - shape returned by calculateSessionTokens
+ * @returns {{peak: number, limit: number, contextLimit: number, ratio: number}|null} null when no model with verified usage and a known limit was found
+ */
+export const pickWorstContextUtilisation = (tokenUsage, argv = {}) => {
+  if (!tokenUsage || !tokenUsage.modelUsage) return null;
+  let worst = null;
+  for (const usage of Object.values(tokenUsage.modelUsage)) {
+    const contextLimit = usage?.modelInfo?.limit?.context;
+    if (!contextLimit || contextLimit <= 0) continue;
+    let limit = contextLimit;
+    try {
+      const configured = argv.subSessionSize ?? argv['sub-session-size'];
+      const subSession = parseSubSessionSize(configured, { contextWindow: contextLimit });
+      if (subSession.kind === 'tokens' && subSession.tokens > 0) {
+        limit = Math.min(contextLimit, subSession.tokens);
+      } else if (subSession.kind === 'percent' && subSession.tokens > 0) {
+        limit = Math.min(contextLimit, subSession.tokens);
+      }
+    } catch {
+      // Invalid values are reported by normal CLI validation. Programmatic
+      // callers still get a conservative decision against the model limit.
+    }
+    const peak = usage.peakContextUsage;
+    if (!Number.isFinite(peak) || peak <= 0) continue;
+    const ratio = peak / limit;
+    if (!worst || ratio > worst.ratio) worst = { peak, limit, contextLimit, ratio };
+  }
+  return worst;
+};
+
+/**
+ * Decide whether resuming is viable given a session ID and the previous
+ * session's token-usage data. Returns a structured result that the caller
+ * can log and act on.
+ *
+ * The decision tree is:
+ *   - no auto-resume flag → 'disabled'
+ *   - flag set, no session ID known → 'no_session_id'
+ *   - flag set, session id known, no usable context-stat data → 'no_context_data'
+ *     (fall back to a fresh run because available headroom cannot be verified)
+ *   - flag set, peak >= threshold → 'context_too_full'
+ *   - flag set, peak <  threshold → 'ok'
+ *
+ * @param {Object} params
+ * @param {Object} params.argv - parsed CLI arguments
+ * @param {string|null} params.sessionId - the session ID to resume, if any
+ * @param {Object|null} params.tokenUsage - result of calculateSessionTokens (may be null)
+ * @returns {{resume: boolean, reason: string, threshold: number, usedPercent: number|null, peak: number|null, limit: number|null}}
+ */
+export const decideAutoResumeOnUncommittedChanges = ({ argv = {}, sessionId = null, tokenUsage = null } = {}) => {
+  const threshold = getAutoResumeMaxContextUsage(argv);
+  if (!isAutoResumeOnUncommittedChangesEnabled(argv)) {
+    return { resume: false, reason: 'disabled', threshold, usedPercent: null, peak: null, limit: null };
+  }
+  if (!sessionId) {
+    return { resume: false, reason: 'no_session_id', threshold, usedPercent: null, peak: null, limit: null };
+  }
+  const worst = pickWorstContextUtilisation(tokenUsage, argv);
+  if (!worst) {
+    return { resume: false, reason: 'no_context_data', threshold, usedPercent: null, peak: null, limit: null };
+  }
+  const usedPercent = (worst.peak / worst.limit) * 100;
+  if (usedPercent >= threshold) {
+    return {
+      resume: false,
+      reason: 'context_too_full',
+      threshold,
+      usedPercent,
+      peak: worst.peak,
+      limit: worst.limit,
+    };
+  }
+  return {
+    resume: true,
+    reason: 'ok',
+    threshold,
+    usedPercent,
+    peak: worst.peak,
+    limit: worst.limit,
+  };
+};
+
+export default {
+  DEFAULT_MAX_CONTEXT_USAGE_PERCENT,
+  getAutoResumeMaxContextUsage,
+  isAutoResumeOnUncommittedChangesEnabled,
+  pickWorstContextUtilisation,
+  decideAutoResumeOnUncommittedChanges,
+};

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/option-suggestions.lib.mjs

@@ -197,6 +197,8 @@ const KNOWN_OPTION_NAMES = [
   'auto-pull-request-creation',
   'auto-commit-uncommitted-changes',
   'auto-restart-on-uncommitted-changes',
+  'auto-resume-on-uncommitted-changes',
+  'auto-resume-on-uncommitted-changes-maximum-context-window-usage',
   'continue-only-on-feedback',
   'claude-file',
   'gitkeep-file',

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/solve.config.lib.mjs

@@ -201,6 +201,16 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Automatically restart when uncommitted changes are detected to allow the tool to handle them (default: true, use --no-auto-restart-on-uncommitted-changes to disable)',
     default: true,
   },
+  'auto-resume-on-uncommitted-changes': {
+    type: 'boolean',
+    description: 'EXPERIMENTAL: Automatically resume the previous Claude session when uncommitted changes are detected. Falls back to a fresh session when usable context headroom cannot be verified or is too low. Disabled by default; use --no-auto-resume-on-uncommitted-changes to switch it off explicitly.',
+    default: false,
+  },
+  'auto-resume-on-uncommitted-changes-maximum-context-window-usage': {
+    type: 'number',
+    description: 'Maximum usable pre-compaction context usage (percent) that still allows --auto-resume-on-uncommitted-changes to resume. The usable limit respects --sub-session-size. At or above this threshold the tool starts a fresh session (default: 50).',
+    default: 50,
+  },
   'auto-restart-max-iterations': {
     type: 'number',
     description: 'Maximum number of auto-restart iterations before stopping (default: 5, 0 = unlimited)',

package/src/solve.mjs

@@ -12,7 +12,6 @@ const { configureGitHubRateLimitLogging, wrapDollarWithGhRetry } = await import(
 const $ = wrapDollarWithGhRetry(__rawDollar$);
 const config = await import('./solve.config.lib.mjs');
 const { initializeConfig, parseArguments } = config;
-// Import Sentry integration
 const sentryLib = await import('./sentry.lib.mjs');
 const { initializeSentry, addBreadcrumb, reportError, closeSentry } = sentryLib;
 const { yargs, hideBin } = await initializeConfig(use);
@@ -1334,6 +1333,8 @@ try {
     prBranch,
     branchName,
     tempDir,
+    initialSessionId: sessionId,
+    initialResultModelUsage: resultModelUsage,
     argv: {
       ...argv,
       watch: argv.watch || shouldRestart, // Enable watch if uncommitted changes
@@ -1341,7 +1342,6 @@ try {
     },
   });
 
-  // Update session data with latest from watch mode for accurate pricing
   if (watchResult && watchResult.latestSessionId) {
     sessionId = watchResult.latestSessionId;
     anthropicTotalCostUSD = watchResult.latestAnthropicCost;

package/src/solve.watch.lib.mjs

@@ -65,6 +65,11 @@ const { trackAuthenticatedUserCommentsSince } = autoMergeHelpers;
 const resultsLib = await import('./solve.results.lib.mjs');
 const { maybeAttachWorkingSessionSummary, ensurePullRequestIssueLink } = resultsLib;
 
+// Issue #1056: Auto-resume on uncommitted changes — decide whether to call the
+// agent again with --resume <sessionId> instead of restarting from scratch.
+const autoResumeLib = await import('./auto-resume-uncommitted.lib.mjs');
+const { decideAutoResumeOnUncommittedChanges, isAutoResumeOnUncommittedChangesEnabled } = autoResumeLib;
+
 /**
  * Monitor for feedback in a loop and trigger restart when detected
  */
@@ -76,8 +81,12 @@ export const watchForFeedback = async params => {
   const maxAutoRestartIterations = normalizeAutoIterationLimit(argv.autoRestartMaxIterations);
 
   // Track latest session data across all iterations for accurate pricing
-  let latestSessionId = null;
+  // Issue #1056: Seed from the *initial* tool execution so the first auto-restart
+  // iteration can attempt --resume on the original session if the user opted in
+  // via --auto-resume-on-uncommitted-changes.
+  let latestSessionId = params.initialSessionId || null;
   let latestAnthropicCost = null;
+  let latestResultModelUsage = params.initialResultModelUsage || null;
 
   // Issue #1290: Track whether auto-restart iterations actually ran and whether logs were uploaded
   // This helps solve.mjs decide whether to upload final logs
@@ -323,16 +332,43 @@ export const watchForFeedback = async params => {
 
         let restartFeedbackLines = feedbackLines;
         let restartArgv = argv;
-        const shouldUseSessionResume = Boolean(isTemporaryWatch && (firstIterationInTemporaryMode || hasUncommittedInTempMode) && (argv.resumeOnAutoRestart || argv['resume-on-auto-restart']) && (argv.tool === 'claude' || !argv.tool) && global.previousSessionId);
+        const isUncommittedChangesRestart = isTemporaryWatch && (firstIterationInTemporaryMode || hasUncommittedInTempMode);
+        const isClaudeTool = argv.tool === 'claude' || !argv.tool;
+        const autoResumeOnUncommittedChanges = isUncommittedChangesRestart && isClaudeTool && isAutoResumeOnUncommittedChangesEnabled(argv);
+        let autoResumeDecision = null;
+
+        if (autoResumeOnUncommittedChanges) {
+          let tokenUsage = null;
+          if (latestSessionId && tempDir) {
+            try {
+              const { calculateSessionTokens } = await import('./claude.lib.mjs');
+              tokenUsage = await calculateSessionTokens(latestSessionId, tempDir, latestResultModelUsage);
+            } catch (tokenError) {
+              await log(`   ⚠️  Could not calculate token usage for auto-resume decision: ${tokenError.message}`, { verbose: true });
+            }
+          }
+          autoResumeDecision = decideAutoResumeOnUncommittedChanges({ argv, sessionId: latestSessionId, tokenUsage });
+        }
+
+        // Keep the older issue #661 experiment working independently. The issue
+        // #1056 option takes precedence when enabled because it adds the required
+        // context-headroom safety check.
+        const legacyResumeRequested = isUncommittedChangesRestart && isClaudeTool && (argv.resumeOnAutoRestart || argv['resume-on-auto-restart']);
+        const shouldUseSessionResume = autoResumeOnUncommittedChanges ? autoResumeDecision?.resume === true : Boolean(legacyResumeRequested && global.previousSessionId);
+        const resumeSessionId = autoResumeOnUncommittedChanges ? latestSessionId : global.previousSessionId;
 
         if (shouldUseSessionResume) {
           await log(formatAligned('', 'Experimental session resume: using minimal auto-restart prompt', '', 2));
-          await log(formatAligned('', `Resuming session: ${global.previousSessionId}`, '', 2));
+          await log(formatAligned('', `Resuming session: ${resumeSessionId}`, '', 2));
+
+          if (autoResumeDecision?.reason === 'ok') {
+            await log(formatAligned('', `Peak context usage: ${autoResumeDecision.peak.toLocaleString()} / ${autoResumeDecision.limit.toLocaleString()} usable tokens (${autoResumeDecision.usedPercent.toFixed(1)}%, threshold ${autoResumeDecision.threshold}%)`, '', 2));
+          }
 
-          if (argv.verbose) {
+          if (!autoResumeOnUncommittedChanges && argv.verbose) {
             try {
               const { calculateSessionTokens } = await import('./claude.lib.mjs');
-              const tokenUsage = await calculateSessionTokens(global.previousSessionId, tempDir);
+              const tokenUsage = await calculateSessionTokens(resumeSessionId, tempDir);
               if (tokenUsage?.totalTokens) {
                 await log(formatAligned('', `Previous session tokens: ${tokenUsage.totalTokens.toLocaleString()}`, '', 2));
               }
@@ -346,11 +382,14 @@ export const watchForFeedback = async params => {
           restartFeedbackLines = [minimalPrompt];
           restartArgv = {
             ...argv,
-            resume: global.previousSessionId,
+            resume: resumeSessionId,
             minimalRestartContext: true,
           };
 
           await log(formatAligned('', `Minimal restart prompt size: ${minimalPrompt.length} characters`, '', 2));
+        } else if (autoResumeOnUncommittedChanges) {
+          const skipReason = autoResumeDecision?.reason === 'context_too_full' ? `peak context usage ${autoResumeDecision.usedPercent.toFixed(1)}% reached the ${autoResumeDecision.threshold}% threshold` : autoResumeDecision?.reason === 'no_session_id' ? 'no previous session ID is available' : 'context usage could not be verified';
+          await log(formatAligned('', 'Auto-resume skipped:', `${skipReason}; starting a fresh session`, 2));
         }
 
         // Execute tool using shared utility
@@ -498,6 +537,12 @@ export const watchForFeedback = async params => {
             }
           }
 
+          // Issue #1056: Track latest model usage so the next auto-resume decision
+          // can re-evaluate context-window usage against the most recent peak.
+          if (toolResult.resultModelUsage) {
+            latestResultModelUsage = toolResult.resultModelUsage;
+          }
+
           // Issue #1508: Compute budget stats for auto-restart log comment
           let autoRestartBudgetStatsData = null;
           if (argv.tokensBudgetStats && latestSessionId && tempDir) {

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;