switchroom 0.18.14 → 0.18.15

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.18.14",
+  "version": "0.18.15",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/bridge/bridge.js

@@ -23061,6 +23061,26 @@ function isTransientUpstreamSignal(text) {
   const lower = sample.toLowerCase();
   return transientUpstreamSignals.some((s) => lower.includes(s));
 }
+var litellmProxyLocal429Signals = [
+  "deployment over user-defined ratelimit",
+  "model rate limit exceeded. tpm limit",
+  "model rate limit exceeded. rpm limit",
+  "deployment over defined rpm limit",
+  "no deployments available for selected model",
+  "litellm rate limit handler",
+  "crossed tpm / rpm",
+  "max parallel request limit reached"
+];
+var litellmV3LimiterSignalPair = ["rate limit exceeded for ", "limit type:"];
+function isLitellmProxyLocal429(text) {
+  if (typeof text !== "string" || text.length === 0)
+    return false;
+  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
+  const lower = sample.toLowerCase();
+  if (litellmProxyLocal429Signals.some((s) => lower.includes(s)))
+    return true;
+  return litellmV3LimiterSignalPair.every((s) => lower.includes(s));
+}
 
 // tool-label-sidecar.ts
 import { existsSync as existsSync2, readFileSync, statSync as statSync2 } from "node:fs";
@@ -23481,6 +23501,7 @@ function detectErrorInTranscriptLine(line) {
     const errStr = typeof obj.error === "string" ? obj.error : "";
     const text = extractAssistantText(obj);
     const kind2 = status === 429 ? isTransientUpstreamSignal(`${text}
+${errStr}`) || isLitellmProxyLocal429(`${text}
 ${errStr}`) ? "rate-limited" : "quota-exhausted" : classifyClaudeError({ type: errStr, status, message: text });
     return {
       kind: kind2,

package/telegram-plugin/dist/gateway/gateway.js

@@ -64640,6 +64640,26 @@ var transientUpstreamSignals = [
   "would exceed your account\u2019s rate limit",
   "would exceed your account's rate limit"
 ];
+var litellmProxyLocal429Signals = [
+  "deployment over user-defined ratelimit",
+  "model rate limit exceeded. tpm limit",
+  "model rate limit exceeded. rpm limit",
+  "deployment over defined rpm limit",
+  "no deployments available for selected model",
+  "litellm rate limit handler",
+  "crossed tpm / rpm",
+  "max parallel request limit reached"
+];
+var litellmV3LimiterSignalPair = ["rate limit exceeded for ", "limit type:"];
+function isLitellmProxyLocal429(text4) {
+  if (typeof text4 !== "string" || text4.length === 0)
+    return false;
+  const sample = text4.length > 16384 ? text4.slice(0, 16384) : text4;
+  const lower = sample.toLowerCase();
+  if (litellmProxyLocal429Signals.some((s) => lower.includes(s)))
+    return true;
+  return litellmV3LimiterSignalPair.every((s) => lower.includes(s));
+}
 function detectModelUnavailable(stderr) {
   if (typeof stderr !== "string" || stderr.length === 0)
     return null;
@@ -64649,6 +64669,10 @@ function detectModelUnavailable(stderr) {
     const resetAt = parseResetTime(sample);
     return resetAt !== undefined ? { kind: "overload", resetAt, raw: stderr } : { kind: "overload", raw: stderr };
   }
+  if (isLitellmProxyLocal429(sample)) {
+    const resetAt = parseResetTime(sample);
+    return resetAt !== undefined ? { kind: "overload", resetAt, raw: stderr } : { kind: "overload", raw: stderr };
+  }
   const quotaSignals = [
     "out of extra usage",
     "extra usage",
@@ -64898,6 +64922,76 @@ function isTransientUpstreamSignal(text4) {
   const lower = sample.toLowerCase();
   return transientUpstreamSignals2.some((s) => lower.includes(s));
 }
+var litellmProxyLocal429Signals2 = [
+  "deployment over user-defined ratelimit",
+  "model rate limit exceeded. tpm limit",
+  "model rate limit exceeded. rpm limit",
+  "deployment over defined rpm limit",
+  "no deployments available for selected model",
+  "litellm rate limit handler",
+  "crossed tpm / rpm",
+  "max parallel request limit reached"
+];
+var litellmV3LimiterSignalPair2 = ["rate limit exceeded for ", "limit type:"];
+function isLitellmProxyLocal4292(text4) {
+  if (typeof text4 !== "string" || text4.length === 0)
+    return false;
+  const sample = text4.length > 16384 ? text4.slice(0, 16384) : text4;
+  const lower = sample.toLowerCase();
+  if (litellmProxyLocal429Signals2.some((s) => lower.includes(s)))
+    return true;
+  return litellmV3LimiterSignalPair2.every((s) => lower.includes(s));
+}
+function parseLitellmLimitDetail(text4, parseTimeNow = new Date) {
+  const empty2 = { limitType: null, limit: null, currentUsage: null, resetAtMs: null };
+  if (typeof text4 !== "string" || text4.length === 0)
+    return empty2;
+  const sample = text4.length > 16384 ? text4.slice(0, 16384) : text4;
+  const lower = sample.toLowerCase();
+  let limitType = null;
+  let limit = null;
+  const eqLimit = lower.match(/\b([tr]pm)[ _]limit[=:]\s*(\d+)/);
+  if (eqLimit) {
+    limitType = eqLimit[1];
+    limit = Number(eqLimit[2]);
+  }
+  if (limitType == null) {
+    const v3Type = lower.match(/limit type:\s*(tokens|requests|max_parallel_requests)/);
+    if (v3Type)
+      limitType = v3Type[1];
+  }
+  if (limit == null) {
+    const v3Limit = lower.match(/current limit:\s*(\d+)/);
+    if (v3Limit)
+      limit = Number(v3Limit[1]);
+  }
+  let currentUsage = null;
+  const usage = lower.match(/current usage=(\d+)/);
+  if (usage)
+    currentUsage = Number(usage[1]);
+  let resetAtMs = null;
+  const resetsAt = sample.match(/limit resets at:\s*(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) UTC/i);
+  if (resetsAt) {
+    const d = new Date(`${resetsAt[1]}T${resetsAt[2]}Z`);
+    if (!Number.isNaN(d.getTime()))
+      resetAtMs = d.getTime();
+  }
+  if (resetAtMs == null) {
+    const tryAgain = lower.match(/try again in\s+(\d+(?:\.\d+)?)\s*seconds/);
+    if (tryAgain) {
+      const secs = Number(tryAgain[1]);
+      if (Number.isFinite(secs) && secs > 0 && secs < 7 * 24 * 3600) {
+        resetAtMs = parseTimeNow.getTime() + Math.round(secs * 1000);
+      }
+    }
+  }
+  return {
+    limitType,
+    limit: limit != null && Number.isFinite(limit) ? limit : null,
+    currentUsage: currentUsage != null && Number.isFinite(currentUsage) ? currentUsage : null,
+    resetAtMs
+  };
+}
 function parseResetTime2(text4, parseTimeNow = new Date) {
   const lower = text4.toLowerCase();
   const retryAfter = lower.match(/retry[\s-]*after[:\s]+(\d+)\s*(seconds?|s\b|minutes?|m\b|hours?|h\b)?/);
@@ -65034,6 +65128,30 @@ function isAccountScopedThrottle(text4) {
   const lower = sample.toLowerCase();
   return accountScopedThrottleSignals.some((s) => lower.includes(s));
 }
+function classify429Detail(text4) {
+  if (isAccountScopedThrottle(text4))
+    return "account-scoped";
+  if (isLitellmProxyLocal4292(text4))
+    return "litellm-local";
+  return "generic-transient";
+}
+function build429ClassifiedMetric(opts) {
+  const detail = typeof opts.detail === "string" ? opts.detail : "";
+  const litellm = parseLitellmLimitDetail(detail, new Date(opts.now));
+  const anthropicResetMs = parseResetTime2(detail, new Date(opts.now))?.getTime() ?? null;
+  const resetAtMs = anthropicResetMs ?? litellm.resetAtMs;
+  return {
+    kind: "rate_limit_429_classified",
+    agent: opts.agent,
+    classification: opts.classification,
+    action: opts.action,
+    reset_at_ms: resetAtMs,
+    reset_in_ms: resetAtMs != null ? Math.max(0, resetAtMs - opts.now) : null,
+    limit_type: litellm.limitType,
+    limit: litellm.limit,
+    current_usage: litellm.currentUsage
+  };
+}
 var THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT = 5 * 60000;
 var THROTTLE_DEFAULT_WAIT_MS = 60000;
 function throttleRetryInPlaceMaxMs(env = process.env) {
@@ -69426,6 +69544,11 @@ function extractConfirmation(pane) {
 // ../src/agents/scaffold.ts
 import { join as join32, resolve as resolve6 } from "node:path";
 init_atomic();
+
+// ../src/agents/agent-uid.ts
+init_peercred();
+
+// ../src/agents/scaffold.ts
 init_schema();
 
 // ../src/config/users.ts
@@ -77097,6 +77220,7 @@ function detectErrorInTranscriptLine(line) {
     const errStr = typeof obj.error === "string" ? obj.error : "";
     const text4 = extractAssistantText(obj);
     const kind2 = status === 429 ? isTransientUpstreamSignal(`${text4}
+${errStr}`) || isLitellmProxyLocal4292(`${text4}
 ${errStr}`) ? "rate-limited" : "quota-exhausted" : classifyClaudeError({ type: errStr, status, message: text4 });
     return {
       kind: kind2,
@@ -80957,10 +81081,10 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.18.14";
-var COMMIT_SHA = "b0db04aa";
-var COMMIT_DATE = "2026-07-12T12:40:07+10:00";
-var LATEST_PR = 3165;
+var VERSION = "0.18.15";
+var COMMIT_SHA = "2fa611a1";
+var COMMIT_DATE = "2026-07-12T04:44:56Z";
+var LATEST_PR = 3171;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -85647,12 +85771,33 @@ function emitGatewayOperatorEvent(event) {
   const { agent, kind } = event;
   let throttleEscalation = null;
   let escalationFired = false;
-  if (kind === "rate-limited" && isAccountScopedThrottle(event.detail)) {
+  const rateLimit429Classification = kind === "rate-limited" ? classify429Detail(event.detail) : null;
+  if (rateLimit429Classification != null && rateLimit429Classification !== "account-scoped") {
+    emitRuntimeMetric(build429ClassifiedMetric({
+      agent,
+      detail: event.detail,
+      classification: rateLimit429Classification,
+      action: "calm",
+      now: Date.now()
+    }));
+    if (rateLimit429Classification === "litellm-local") {
+      process.stderr.write(`telegram gateway: 429 classified litellm-proxy-local agent=${agent} \u2014 ` + `calm path, no account attribution, no failover
+`);
+    }
+  }
+  if (rateLimit429Classification === "account-scoped") {
     const throttleDecision = decideThrottleTier({
       detail: event.detail,
       now: Date.now(),
       thresholdMs: throttleRetryInPlaceMaxMs()
     });
+    emitRuntimeMetric(build429ClassifiedMetric({
+      agent,
+      detail: event.detail,
+      classification: "account-scoped",
+      action: throttleDecision.action === "failover" ? "failover" : "throttle",
+      now: Date.now()
+    }));
     if (throttleDecision.action === "throttle") {
       process.stderr.write(`telegram gateway: throttle-tier staying-put agent=${agent} until=${new Date(throttleDecision.throttledUntilMs).toISOString()} parsedReset=${throttleDecision.resetParsed}
 `);

package/telegram-plugin/dist/server.js

@@ -17088,7 +17088,16 @@ function isTransientUpstreamSignal(text) {
   const lower = sample.toLowerCase();
   return transientUpstreamSignals.some((s) => lower.includes(s));
 }
-var transientUpstreamSignals;
+function isLitellmProxyLocal429(text) {
+  if (typeof text !== "string" || text.length === 0)
+    return false;
+  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
+  const lower = sample.toLowerCase();
+  if (litellmProxyLocal429Signals.some((s) => lower.includes(s)))
+    return true;
+  return litellmV3LimiterSignalPair.every((s) => lower.includes(s));
+}
+var transientUpstreamSignals, litellmProxyLocal429Signals, litellmV3LimiterSignalPair;
 var init_model_unavailable = __esm(() => {
   init_quota_check();
   init_card_format();
@@ -17102,6 +17111,17 @@ var init_model_unavailable = __esm(() => {
     "would exceed your account\u2019s rate limit",
     "would exceed your account's rate limit"
   ];
+  litellmProxyLocal429Signals = [
+    "deployment over user-defined ratelimit",
+    "model rate limit exceeded. tpm limit",
+    "model rate limit exceeded. rpm limit",
+    "deployment over defined rpm limit",
+    "no deployments available for selected model",
+    "litellm rate limit handler",
+    "crossed tpm / rpm",
+    "max parallel request limit reached"
+  ];
+  litellmV3LimiterSignalPair = ["rate limit exceeded for ", "limit type:"];
 });
 
 // tool-label-sidecar.ts
@@ -17534,6 +17554,7 @@ function detectErrorInTranscriptLine(line) {
     const errStr = typeof obj.error === "string" ? obj.error : "";
     const text = extractAssistantText(obj);
     const kind2 = status === 429 ? isTransientUpstreamSignal(`${text}
+${errStr}`) || isLitellmProxyLocal429(`${text}
 ${errStr}`) ? "rate-limited" : "quota-exhausted" : classifyClaudeError({ type: errStr, status, message: text });
     return {
       kind: kind2,

package/telegram-plugin/gateway/gateway.ts

@@ -320,8 +320,9 @@ import {
   type ModelUnavailableDetection,
 } from '../model-unavailable.js'
 import {
+  build429ClassifiedMetric,
+  classify429Detail,
   decideThrottleTier,
-  isAccountScopedThrottle,
   throttleRetryInPlaceMaxMs,
 } from '../throttle-tier.js'
 import { createThrottleTierRunner } from './throttle-tier-wiring.js'
@@ -7700,14 +7701,59 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   // through to the existing calm rate-limited card unchanged — an
   // account-scoped throttle would be the wrong action for a server-wide
   // condition.
+  //
+  // Classification is three-way (classify429Detail, throttle-tier.ts):
+  // only `account-scoped` may enter the throttle tier. `litellm-local` —
+  // the LiteLLM proxy's OWN tpm/rpm/router limiter tripping before the
+  // request reached Anthropic — takes the calm path with NO broker mark and
+  // NO failover: the condition is proxy-local and says nothing about the
+  // account. Every rate-limited event ALSO emits one
+  // `rate_limit_429_classified` runtime metric (PostHog + JSONL), fired
+  // here — before the cooldown gate — so operators can correlate
+  // account-scoped 429s with fleet TPM even when the card is suppressed.
   let throttleEscalation: ModelUnavailableDetection | null = null
   let escalationFired = false
-  if (kind === 'rate-limited' && isAccountScopedThrottle(event.detail)) {
+  const rateLimit429Classification =
+    kind === 'rate-limited' ? classify429Detail(event.detail) : null
+  if (rateLimit429Classification != null && rateLimit429Classification !== 'account-scoped') {
+    // litellm-local / generic-transient: the existing calm rate-limited
+    // path (fall through to renderOperatorEvent below). NO broker
+    // mark-throttled, NO throttle-tier runner, NO failover — for a
+    // proxy-local cap trip those would bench an account that was never
+    // touched.
+    emitRuntimeMetric(
+      build429ClassifiedMetric({
+        agent,
+        detail: event.detail,
+        classification: rateLimit429Classification,
+        action: 'calm',
+        now: Date.now(),
+      }),
+    )
+    if (rateLimit429Classification === 'litellm-local') {
+      process.stderr.write(
+        `telegram gateway: 429 classified litellm-proxy-local agent=${agent} — ` +
+          `calm path, no account attribution, no failover\n`,
+      )
+    }
+  }
+  if (rateLimit429Classification === 'account-scoped') {
     const throttleDecision = decideThrottleTier({
       detail: event.detail,
       now: Date.now(),
       thresholdMs: throttleRetryInPlaceMaxMs(),
     })
+    emitRuntimeMetric(
+      build429ClassifiedMetric({
+        agent,
+        detail: event.detail,
+        classification: 'account-scoped',
+        // decideThrottleTier can't return 'none' for account-scoped wording;
+        // map the two live actions onto the metric's vocabulary.
+        action: throttleDecision.action === 'failover' ? 'failover' : 'throttle',
+        now: Date.now(),
+      }),
+    )
     if (throttleDecision.action === 'throttle') {
       // Reset is near (≤ threshold) or unparseable (60s default): DO NOT
       // fail over. Record throttled_until broker-side, post ONE lightweight

package/telegram-plugin/model-unavailable.ts

@@ -92,6 +92,203 @@ export function isTransientUpstreamSignal(text: string): boolean {
   return transientUpstreamSignals.some(s => lower.includes(s))
 }
 
+// ─── LiteLLM-proxy-LOCAL 429 signals (canonical, single source of truth) ─────
+
+/**
+ * Explicit markers of a 429 generated by the LiteLLM proxy's OWN rate
+ * limiters — a router `tpm_limit`/`rpm_limit` deployment cap, a virtual-key /
+ * team / user cap, or an all-deployments-cooling-down router state. The
+ * request never reached Anthropic, so the condition is PROXY-LOCAL: it says
+ * nothing about the Anthropic account's quota and must never mark the account
+ * throttled/exhausted or trigger fleet failover.
+ *
+ * Each wording key is grounded in LiteLLM's source (verified against
+ * BerriAI/litellm `main`, 2026-07), matching how
+ * `accountScopedThrottleSignals` (throttle-tier.ts) documents its keys:
+ *
+ *  - "deployment over user-defined ratelimit" —
+ *    `RouterErrors.user_defined_ratelimit_error` (litellm/types/router.py),
+ *    the body prefix of every deployment tpm/rpm cap 429 raised by
+ *    litellm/router_utils/pre_call_checks/model_rate_limit_check.py:
+ *    "Deployment over user-defined ratelimit. tpm limit={n}. current
+ *    usage={n}. id={id}, model_group={g}".
+ *  - "model rate limit exceeded. tpm/rpm limit" — the `message` field of the
+ *    same enforcement RateLimitError: "Model rate limit exceeded. TPM
+ *    limit={n}, current usage={n}" (model_rate_limit_check.py).
+ *  - "deployment over defined rpm limit" — the usage-based-routing-v2
+ *    strategy wording "Deployment over defined rpm limit={n}. current
+ *    usage={n}" (litellm/router_strategy/lowest_tpm_rpm_v2.py). There is NO
+ *    tpm sibling in any known release — v2 TPM exhaustion surfaces as the
+ *    `no_deployments_available` wording below (the deployment is filtered
+ *    from the candidate set rather than erroring in the increment path).
+ *  - "no deployments available for selected model" —
+ *    `RouterErrors.no_deployments_available`, the RouterRateLimitError
+ *    message when every deployment for the model group is cooling down:
+ *    "No deployments available for selected model, Try again in {n}
+ *    seconds…" (litellm/types/router.py).
+ *  - "litellm rate limit handler" — the v1 parallel-request limiter's
+ *    ProxyRateLimitError detail prefix: "LiteLLM Rate Limit Handler for
+ *    rate limit type = {t}. Crossed TPM / RPM / Max Parallel Request
+ *    Limit. current rpm: {n}, rpm limit: {n}…"
+ *    (litellm/proxy/hooks/parallel_request_limiter.py).
+ *  - "crossed tpm / rpm" — `CommonProxyErrors
+ *    .max_parallel_request_limit_reached.value` = "Crossed TPM / RPM / Max
+ *    Parallel Request Limit" (litellm/proxy/_types.py), interpolated into
+ *    BOTH v1 detail shapes, so it also covers the zero-limit branch's
+ *    "Max parallel request limit reached {additional_details}" message.
+ *  - "max parallel request limit reached" — the standalone prefix
+ *    `raise_rate_limit_error` builds when a key's limit is set to 0
+ *    (parallel_request_limiter.py `error_message`).
+ *
+ * The proxy-side per-key/team/user limiter (parallel_request_limiter_v3.py
+ * `_handle_rate_limit_error`) is matched by CO-OCCURRENCE instead of a
+ * per-descriptor entry — see `isLitellmProxyLocal429`. Its detail shape:
+ * "Rate limit exceeded for {descriptor}: {value}. Limit type: {t}. Current
+ * limit: {n}, Remaining: {n}. Limit resets at: {ts}". Descriptor keys in
+ * source are numerous and growing (api_key / user / team / team_member /
+ * organization / end_user / agent / agent_session / model_per_key /
+ * model_per_team / model_per_organization / model_per_project / tag_per_key
+ * / mcp_per_key / mcp_per_team as of 2026-07), so enumerating them is a
+ * treadmill: the pair "rate limit exceeded for " + "limit type:" appears in
+ * every v3 body and in no Anthropic error. This is the shape a `tpm_limit`
+ * on the per-agent virtual keys (src/litellm/provision.ts) trips.
+ *
+ * Deliberately EXCLUDED: the bare exception-mapping prefix
+ * "litellm.RateLimitError:". LiteLLM wraps FORWARDED upstream 429s with the
+ * same prefix on the pass-through, so its presence is NOT evidence the limit
+ * was proxy-local — a genuine Anthropic account throttle traversing the
+ * proxy must keep its account-scoped classification (see
+ * `classify429Detail` in throttle-tier.ts for the tie-break).
+ */
+export const litellmProxyLocal429Signals = [
+  'deployment over user-defined ratelimit',
+  'model rate limit exceeded. tpm limit',
+  'model rate limit exceeded. rpm limit',
+  'deployment over defined rpm limit',
+  'no deployments available for selected model',
+  'litellm rate limit handler',
+  'crossed tpm / rpm',
+  'max parallel request limit reached',
+]
+
+/**
+ * The v3 proxy-limiter co-occurrence pair (see the provenance comment on
+ * `litellmProxyLocal429Signals`): both substrings appear in every
+ * parallel_request_limiter_v3 429 body regardless of descriptor key, and
+ * never in an Anthropic error. Exported so tests can pin the rule.
+ */
+export const litellmV3LimiterSignalPair = ['rate limit exceeded for ', 'limit type:'] as const
+
+/**
+ * True when `text` carries an EXPLICIT LiteLLM-proxy-local rate-limit marker:
+ * one of `litellmProxyLocal429Signals`, OR the v3 limiter co-occurrence pair
+ * (`litellmV3LimiterSignalPair` — descriptor-agnostic, so new v3 descriptor
+ * keys are covered without a list update). Never throws on weird input. Pure
+ * wording detection only — precedence against account-scoped wording is
+ * owned by `classify429Detail` (throttle-tier.ts).
+ */
+export function isLitellmProxyLocal429(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+  if (litellmProxyLocal429Signals.some(s => lower.includes(s))) return true
+  return litellmV3LimiterSignalPair.every(s => lower.includes(s))
+}
+
+/**
+ * Best-effort extraction of the limit detail LiteLLM embeds in its
+ * proxy-local 429 bodies, for instrumentation (the `rate_limit_429_classified`
+ * runtime metric). All fields null when nothing parseable is found — never
+ * throws. Shapes covered (same provenance as `litellmProxyLocal429Signals`):
+ *
+ *   - "tpm limit=8000. current usage=8241"    (model_rate_limit_check body)
+ *   - "TPM limit=8000, current usage=8241"    (model_rate_limit_check message)
+ *   - "Deployment over defined rpm limit=60. current usage=61"  (v2 strategy)
+ *   - "Limit type: tokens. Current limit: 8000 … Limit resets at:
+ *      2026-07-12 08:05:00 UTC"               (parallel_request_limiter_v3)
+ *   - "Try again in 27.5 seconds"             (RouterRateLimitError cooldown)
+ *
+ * CAVEAT — the v3 "Limit resets at" timestamp is NOT reliably UTC despite
+ * the literal: litellm formats it with a naive `datetime.fromtimestamp(...)
+ * .strftime("%Y-%m-%d %H:%M:%S UTC")` (parallel_request_limiter_v3.py
+ * `_handle_rate_limit_error`), i.e. proxy-LOCAL wall-clock time with a
+ * hard-coded "UTC" suffix. We parse it as UTC (nothing better is possible
+ * from the body alone), so `resetAtMs` — and the metric fields derived from
+ * it — can be skewed by the proxy host's UTC offset when the proxy doesn't
+ * run on UTC. Treat v3-derived resets as approximate; don't chase phantom
+ * clock drift from these metrics. The rate-limit windows are ≤1 minute
+ * anyway, so the absolute timestamp is informational.
+ */
+export function parseLitellmLimitDetail(
+  text: string,
+  parseTimeNow: Date = new Date(),
+): {
+  limitType: string | null
+  limit: number | null
+  currentUsage: number | null
+  resetAtMs: number | null
+} {
+  const empty = { limitType: null, limit: null, currentUsage: null, resetAtMs: null }
+  if (typeof text !== 'string' || text.length === 0) return empty
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+
+  // "tpm limit=8000" / "rpm limit=60" (body), "TPM limit=8000" (message),
+  // and the v1 limiter's colon form "rpm limit: 60".
+  let limitType: string | null = null
+  let limit: number | null = null
+  const eqLimit = lower.match(/\b([tr]pm)[ _]limit[=:]\s*(\d+)/)
+  if (eqLimit) {
+    limitType = eqLimit[1]
+    limit = Number(eqLimit[2])
+  }
+  // v3 limiter: "Limit type: tokens. Current limit: 8000"
+  if (limitType == null) {
+    const v3Type = lower.match(/limit type:\s*(tokens|requests|max_parallel_requests)/)
+    if (v3Type) limitType = v3Type[1]
+  }
+  if (limit == null) {
+    const v3Limit = lower.match(/current limit:\s*(\d+)/)
+    if (v3Limit) limit = Number(v3Limit[1])
+  }
+
+  // "current usage=8241" (body/message, both `=` and `= ` never occur with
+  // separators other than the literal shown in source).
+  let currentUsage: number | null = null
+  const usage = lower.match(/current usage=(\d+)/)
+  if (usage) currentUsage = Number(usage[1])
+
+  // Reset hints LiteLLM emits that the Anthropic-shaped parseResetTime does
+  // not cover: "Limit resets at: 2026-07-12 08:05:00 UTC" (v3 limiter — note
+  // the space separator, not ISO 'T') and "Try again in 27.5 seconds"
+  // (RouterRateLimitError).
+  let resetAtMs: number | null = null
+  const resetsAt = sample.match(
+    /limit resets at:\s*(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) UTC/i,
+  )
+  if (resetsAt) {
+    const d = new Date(`${resetsAt[1]}T${resetsAt[2]}Z`)
+    if (!Number.isNaN(d.getTime())) resetAtMs = d.getTime()
+  }
+  if (resetAtMs == null) {
+    const tryAgain = lower.match(/try again in\s+(\d+(?:\.\d+)?)\s*seconds/)
+    if (tryAgain) {
+      const secs = Number(tryAgain[1])
+      if (Number.isFinite(secs) && secs > 0 && secs < 7 * 24 * 3600) {
+        resetAtMs = parseTimeNow.getTime() + Math.round(secs * 1000)
+      }
+    }
+  }
+
+  return {
+    limitType,
+    limit: limit != null && Number.isFinite(limit) ? limit : null,
+    currentUsage:
+      currentUsage != null && Number.isFinite(currentUsage) ? currentUsage : null,
+    resetAtMs,
+  }
+}
+
 // ─── Detection ───────────────────────────────────────────────────────────────
 
 /**
@@ -138,6 +335,23 @@ export function detectModelUnavailable(
       : { kind: 'overload', raw: stderr }
   }
 
+  // ── 0.5. LiteLLM-proxy-LOCAL 429 — never a quota signal ─────────────────
+  // A 429 raised by the LiteLLM proxy's own limiters (`tpm_limit`/`rpm_limit`
+  // caps, router cooldown) never reached Anthropic — nothing about the
+  // account is exhausted, so it must classify to the calm retryable kind
+  // BEFORE the quota substrings run (some LiteLLM bodies contain the word
+  // "limit", which a negation-blind quota match could seize on). Runs after
+  // step 0 deliberately: account-affirming wording, when present, can only
+  // have originated upstream (LiteLLM never emits it) and wins — see the
+  // tie-break note on `classify429Detail` (throttle-tier.ts). Uses the full
+  // matcher (list + v3 co-occurrence pair) so every descriptor is covered.
+  if (isLitellmProxyLocal429(sample)) {
+    const resetAt = parseResetTime(sample)
+    return resetAt !== undefined
+      ? { kind: 'overload', resetAt, raw: stderr }
+      : { kind: 'overload', raw: stderr }
+  }
+
   // ── 1. Quota / billing exhaustion ──────────────────────────────────────
   const quotaSignals = [
     'out of extra usage',

package/telegram-plugin/runtime-metrics.ts

@@ -164,6 +164,37 @@ export type RuntimeMetricEvent =
       agent: string
       prompt_key: string
     }
+  /**
+   * Every terminal rate-limit-family operator event (429 burst / 529
+   * overload), classified by origin BEFORE the gateway acts on it — fires
+   * even when the user-facing card is cooldown-suppressed, so the count is
+   * honest. `classification` says where the limit lives (see
+   * `RateLimit429Classification` in throttle-tier.ts): `account-scoped` =
+   * Anthropic throttled the account (throttle tier ran), `litellm-local` =
+   * the LiteLLM proxy's own tpm/rpm/router limiter tripped (calm path, no
+   * account attribution), `generic-transient` = other server-side 429/529
+   * wording. `action` is what the gateway DECIDED (throttle / failover /
+   * calm), emitted PRE-execution: the actual failover fire is dedup-gated
+   * downstream (fleetFallbackGate), so N long-reset 429s inside one dedup
+   * window emit N `action: 'failover'` metrics for ONE real roll — count
+   * decisions here, count rolls via the broker/fallback announcements.
+   * Correlating `account-scoped` fires against fleet token throughput is
+   * the operator's evidence base for setting LiteLLM `tpm_limit` caps; the
+   * `litellm-local` count then shows those caps actually absorbing load.
+   * Limit/reset fields are best-effort parses of the error body (null when
+   * absent).
+   */
+  | {
+      kind: 'rate_limit_429_classified'
+      agent: string
+      classification: 'account-scoped' | 'litellm-local' | 'generic-transient'
+      action: 'throttle' | 'failover' | 'calm'
+      reset_at_ms: number | null
+      reset_in_ms: number | null
+      limit_type: string | null
+      limit: number | null
+      current_usage: number | null
+    }
 
 /**
  * The JSONL sink lives under the runtime state dir so it's per-agent