switchroom 0.18.14 → 0.18.15

package/telegram-plugin/session-tail.ts

@@ -41,7 +41,7 @@ function isMultiAgentEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   return env.PROGRESS_CARD_MULTI_AGENT !== '0'
 }
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
-import { isTransientUpstreamSignal } from './model-unavailable.js'
+import { isLitellmProxyLocal429, isTransientUpstreamSignal } from './model-unavailable.js'
 import { createToolLabelSidecar, type ToolLabelSidecar, type SidecarOptions } from './tool-label-sidecar.js'
 import { isModelSentinel } from './model-label.js'
 
@@ -684,9 +684,21 @@ export function detectErrorInTranscriptLine(
     // model-unavailable.ts) — an ambiguous 429 that merely says "limit" stays
     // quota-exhausted, biasing toward surfacing a real wall. Other statuses fall
     // through to the shared classifier.
+    //
+    // A 429 carrying LiteLLM-proxy-LOCAL limiter wording ("Deployment over
+    // user-defined ratelimit", "Rate limit exceeded for api_key: …" — the
+    // canonical `litellmProxyLocal429Signals` list) is the proxy's own
+    // `tpm_limit`/`rpm_limit` cap tripping BEFORE the request reached
+    // Anthropic. Nothing about the account is exhausted — blanket-labeling it
+    // quota-exhausted would fire the model-unavailable card + mark-exhausted +
+    // fleet failover for a purely proxy-local condition. It is rate-limited
+    // (calm path). Precedence when BOTH wordings appear is owned by
+    // `classify429Detail` gateway-side; here both branches yield the same
+    // 'rate-limited' kind, so order is immaterial.
     const kind: OperatorEventKind =
       status === 429
-        ? isTransientUpstreamSignal(`${text}\n${errStr}`)
+        ? isTransientUpstreamSignal(`${text}\n${errStr}`) ||
+          isLitellmProxyLocal429(`${text}\n${errStr}`)
           ? 'rate-limited'
           : 'quota-exhausted'
         : classifyClaudeError({ type: errStr, status, message: text })

package/telegram-plugin/tests/model-unavailable.test.ts

@@ -14,10 +14,52 @@ import { describe, it, expect } from 'vitest'
 import {
   detectModelUnavailable,
   formatModelUnavailableCard,
+  isLitellmProxyLocal429,
+  parseLitellmLimitDetail,
   resolveModelUnavailableFromOperatorEvent,
   type ModelUnavailableDetection,
 } from '../model-unavailable.js'
 
+// Real LiteLLM proxy-local 429 bodies, verbatim shapes from BerriAI/litellm
+// source (see the provenance comment on `litellmProxyLocal429Signals`).
+const LITELLM_DEPLOYMENT_CAP_BODY =
+  'Deployment over user-defined ratelimit. tpm limit=8000. current usage=8241. ' +
+  'id=abc123def, model_group=claude-fable-5'
+const LITELLM_DEPLOYMENT_CAP_MESSAGE =
+  'litellm.RateLimitError: Model rate limit exceeded. TPM limit=8000, current usage=8241'
+const LITELLM_V2_STRATEGY_BODY =
+  "Deployment over defined rpm limit=60. current usage=61. id=abc123def, " +
+  "model_group=claude-fable-5. Get the model info by calling 'router.get_model_info(id)"
+const LITELLM_ROUTER_COOLDOWN_BODY =
+  'No deployments available for selected model, Try again in 27.5 seconds. ' +
+  "Passed model=claude-fable-5. pre-call-checks=False, cooldown_list=['abc123def']"
+const LITELLM_V3_KEY_LIMIT_BODY =
+  'Rate limit exceeded for api_key: hashed-key-1a2b3c. Limit type: tokens. ' +
+  'Current limit: 8000, Remaining: 0. Limit resets at: 2026-07-12 08:05:00 UTC'
+// v1 shape A — the ProxyRateLimitError detail (parallel_request_limiter.py
+// ~line 124; the interpolated CommonProxyErrors.max_parallel_request_limit_
+// reached.value is "Crossed TPM / RPM / Max Parallel Request Limit").
+const LITELLM_V1_PARALLEL_BODY =
+  'LiteLLM Rate Limit Handler for rate limit type = requests. ' +
+  'Crossed TPM / RPM / Max Parallel Request Limit. ' +
+  'current rpm: 61, rpm limit: 60, current tpm: 100, tpm limit: 8000, ' +
+  'current max_parallel_requests: 1, max_parallel_requests: 10'
+// v1 shape B — raise_rate_limit_error's zero-limit branch: the standalone
+// "Max parallel request limit reached" prefix + additional_details
+// (parallel_request_limiter.py ~lines 88 + 183).
+const LITELLM_V1_ZERO_LIMIT_BODY =
+  'Max parallel request limit reached Crossed TPM / RPM / Max Parallel ' +
+  'Request Limit. Hit limit for tokens. Current limits: ' +
+  'max_parallel_requests: 10, tpm_limit: 0, rpm_limit: 60'
+// v3 limiter with a descriptor OUTSIDE any enumerated list — covered by the
+// litellmV3LimiterSignalPair co-occurrence rule (v3 descriptor keys also
+// include organization / team_member / model_per_team / agent / tag_per_key
+// / mcp_per_key and keep growing, so enumeration is a treadmill).
+const LITELLM_V3_TEAM_MODEL_BODY =
+  'Rate limit exceeded for model_per_team: team-1a2b3c:claude-fable-5. ' +
+  'Limit type: tokens. Current limit: 50000, Remaining: 0. ' +
+  'Limit resets at: 2026-07-12 08:05:00 UTC'
+
 // ─── detectModelUnavailable ──────────────────────────────────────────────────
 
 describe('detectModelUnavailable — quota / billing strings', () => {
@@ -117,6 +159,151 @@ describe('detectModelUnavailable — transient upstream 429 vs account quota (#2
   })
 })
 
+describe('detectModelUnavailable — LiteLLM-proxy-LOCAL 429s (never quota)', () => {
+  // A 429 raised by LiteLLM's OWN limiter never reached Anthropic — it must
+  // classify to the calm retryable kind, never quota_exhausted (which drives
+  // the scary card + mark-exhausted + fleet failover for an account that was
+  // never touched). Bodies are verbatim LiteLLM source shapes.
+  it.each([
+    ['deployment tpm cap (model_rate_limit_check body)', LITELLM_DEPLOYMENT_CAP_BODY],
+    ['deployment tpm cap (RateLimitError message)', LITELLM_DEPLOYMENT_CAP_MESSAGE],
+    ['usage-based-routing v2 rpm wording', LITELLM_V2_STRATEGY_BODY],
+    ['router cooldown (RouterRateLimitError)', LITELLM_ROUTER_COOLDOWN_BODY],
+    ['virtual-key tpm_limit (parallel_request_limiter_v3)', LITELLM_V3_KEY_LIMIT_BODY],
+    ['team model cap — non-enumerated v3 descriptor (co-occurrence rule)', LITELLM_V3_TEAM_MODEL_BODY],
+    ['v1 parallel-request limiter (Rate Limit Handler detail)', LITELLM_V1_PARALLEL_BODY],
+    ['v1 zero-limit branch (Max parallel request limit reached prefix)', LITELLM_V1_ZERO_LIMIT_BODY],
+  ])('classifies %s as overload, NOT quota_exhausted', (_name, body) => {
+    const d = detectModelUnavailable(body)
+    expect(d?.kind).toBe('overload')
+  })
+
+  it('a rate-limited operator event with a LiteLLM-local body resolves to NO model-unavailable card', () => {
+    // End-to-end seam the gateway uses: resolveModelUnavailableFromOperatorEvent
+    // returning null is what keeps the calm 🚦 card AND blocks the
+    // auto-fallback branch (fallback only fires when a detection resolves).
+    for (const body of [
+      LITELLM_DEPLOYMENT_CAP_BODY,
+      LITELLM_V3_KEY_LIMIT_BODY,
+      LITELLM_ROUTER_COOLDOWN_BODY,
+    ]) {
+      expect(
+        resolveModelUnavailableFromOperatorEvent({ kind: 'rate-limited', detail: body }),
+      ).toBeNull()
+    }
+  })
+})
+
+describe('isLitellmProxyLocal429 — signal matching', () => {
+  it('matches every canonical LiteLLM limiter wording', () => {
+    for (const body of [
+      LITELLM_DEPLOYMENT_CAP_BODY,
+      LITELLM_DEPLOYMENT_CAP_MESSAGE,
+      LITELLM_V2_STRATEGY_BODY,
+      LITELLM_ROUTER_COOLDOWN_BODY,
+      LITELLM_V3_KEY_LIMIT_BODY,
+      LITELLM_V1_PARALLEL_BODY,
+      LITELLM_V1_ZERO_LIMIT_BODY,
+    ]) {
+      expect(isLitellmProxyLocal429(body)).toBe(true)
+    }
+  })
+
+  it('matches ANY v3 descriptor via the co-occurrence pair, not an enumerated list', () => {
+    // model_per_team is not in litellmProxyLocal429Signals — only the
+    // "rate limit exceeded for " + "limit type:" pair catches it. Same for
+    // any descriptor litellm adds later.
+    expect(isLitellmProxyLocal429(LITELLM_V3_TEAM_MODEL_BODY)).toBe(true)
+    expect(
+      isLitellmProxyLocal429(
+        'Rate limit exceeded for organization: org-1a2b3c. Limit type: requests. ' +
+          'Current limit: 100, Remaining: 0. Limit resets at: 2026-07-12 08:05:00 UTC',
+      ),
+    ).toBe(true)
+    // HALF the pair is not enough — "rate limit exceeded for" prose without
+    // the v3 "Limit type:" field must not classify proxy-local.
+    expect(
+      isLitellmProxyLocal429('Rate limit exceeded for this account, try later'),
+    ).toBe(false)
+    expect(isLitellmProxyLocal429('Limit type: tokens')).toBe(false)
+  })
+
+  it('does NOT match Anthropic account/wall/server wordings', () => {
+    expect(
+      isLitellmProxyLocal429(
+        "This request would exceed your account's rate limit. Please try again later.",
+      ),
+    ).toBe(false)
+    expect(
+      isLitellmProxyLocal429('Server is temporarily limiting requests (not your usage limit)'),
+    ).toBe(false)
+    expect(isLitellmProxyLocal429("You've hit your limit · resets 8:50am")).toBe(false)
+  })
+
+  it('does NOT match the bare litellm.RateLimitError exception-mapping prefix', () => {
+    // The pass-through wraps FORWARDED upstream 429s with the same prefix —
+    // it is not evidence the limit was proxy-local.
+    expect(
+      isLitellmProxyLocal429(
+        "litellm.RateLimitError: RateLimitError: This request would exceed your account's rate limit.",
+      ),
+    ).toBe(false)
+  })
+
+  it('never throws on weird input', () => {
+    expect(isLitellmProxyLocal429('')).toBe(false)
+    expect(isLitellmProxyLocal429(undefined as unknown as string)).toBe(false)
+    expect(isLitellmProxyLocal429(42 as unknown as string)).toBe(false)
+    // Slice guard: signal past the 16KB sample is not scanned.
+    expect(isLitellmProxyLocal429('A'.repeat(100_000) + LITELLM_DEPLOYMENT_CAP_BODY)).toBe(false)
+  })
+})
+
+describe('parseLitellmLimitDetail — instrumentation extraction', () => {
+  const NOW = new Date(Date.UTC(2026, 6, 12, 8, 0, 0))
+
+  it('extracts tpm limit + current usage from the deployment-cap body', () => {
+    const d = parseLitellmLimitDetail(LITELLM_DEPLOYMENT_CAP_BODY, NOW)
+    expect(d.limitType).toBe('tpm')
+    expect(d.limit).toBe(8000)
+    expect(d.currentUsage).toBe(8241)
+    expect(d.resetAtMs).toBeNull()
+  })
+
+  it('extracts rpm limit from the v2 strategy body', () => {
+    const d = parseLitellmLimitDetail(LITELLM_V2_STRATEGY_BODY, NOW)
+    expect(d.limitType).toBe('rpm')
+    expect(d.limit).toBe(60)
+    expect(d.currentUsage).toBe(61)
+  })
+
+  it('extracts the v3 limiter limit type, limit, and "Limit resets at" UTC timestamp', () => {
+    const d = parseLitellmLimitDetail(LITELLM_V3_KEY_LIMIT_BODY, NOW)
+    expect(d.limitType).toBe('tokens')
+    expect(d.limit).toBe(8000)
+    expect(d.resetAtMs).toBe(Date.UTC(2026, 6, 12, 8, 5, 0))
+  })
+
+  it('extracts the router-cooldown "Try again in N seconds" relative reset', () => {
+    const d = parseLitellmLimitDetail(LITELLM_ROUTER_COOLDOWN_BODY, NOW)
+    expect(d.resetAtMs).toBe(NOW.getTime() + 27_500)
+  })
+
+  it('extracts the v1 limiter colon-form rpm limit', () => {
+    const d = parseLitellmLimitDetail(LITELLM_V1_PARALLEL_BODY, NOW)
+    expect(d.limitType).toBe('rpm')
+    expect(d.limit).toBe(60)
+  })
+
+  it('returns all-null on non-LiteLLM prose and never throws on weird input', () => {
+    const empty = { limitType: null, limit: null, currentUsage: null, resetAtMs: null }
+    expect(parseLitellmLimitDetail('Please try again later.', NOW)).toEqual(empty)
+    expect(parseLitellmLimitDetail('', NOW)).toEqual(empty)
+    expect(parseLitellmLimitDetail(undefined as unknown as string, NOW)).toEqual(empty)
+    expect(parseLitellmLimitDetail({} as unknown as string, NOW)).toEqual(empty)
+  })
+})
+
 describe('detectModelUnavailable — network failures', () => {
   it('classifies ECONNREFUSED', () => {
     expect(detectModelUnavailable('connect ECONNREFUSED 1.2.3.4:443')?.kind).toBe('network')

package/telegram-plugin/tests/operator-events-session-tail.test.ts

@@ -198,6 +198,61 @@ describe('detectErrorInTranscriptLine — error detection', () => {
     expect(detection).toBeNull()
   })
 
+  // A 429 whose body carries LiteLLM-proxy-LOCAL limiter wording is the
+  // proxy's own tpm_limit/rpm_limit cap tripping BEFORE the request reached
+  // Anthropic. Nothing about the account is exhausted — it must take the
+  // calm rate-limited path (no model-unavailable card, no mark-exhausted,
+  // no fleet failover). Prerequisite for enabling litellm tpm caps on the
+  // fleet: without this, every cap trip would bench a healthy account.
+  it('classifies a LiteLLM-proxy-local 429 as rate-limited, NOT quota-exhausted', () => {
+    const litellmBodies = [
+      // Deployment tpm cap (model_rate_limit_check.py body, verbatim shape).
+      'API Error: 429 Deployment over user-defined ratelimit. tpm limit=8000. ' +
+        'current usage=8241. id=abc123def, model_group=claude-fable-5',
+      // Virtual-key tpm_limit (parallel_request_limiter_v3.py).
+      'API Error: 429 Rate limit exceeded for api_key: hashed-key-1a2b3c. ' +
+        'Limit type: tokens. Current limit: 8000, Remaining: 0. ' +
+        'Limit resets at: 2026-07-12 08:05:00 UTC',
+      // Router cooldown (RouterRateLimitError).
+      'API Error: 429 No deployments available for selected model, ' +
+        'Try again in 27.5 seconds. Passed model=claude-fable-5.',
+      // Team-level model cap — a v3 descriptor OUTSIDE the enumerated signal
+      // list, covered only by the co-occurrence pair
+      // (litellmV3LimiterSignalPair). Pre-fix this missed every signal →
+      // quota-exhausted → scary card + failover.
+      'API Error: 429 Rate limit exceeded for model_per_team: ' +
+        'team-1a2b3c:claude-fable-5. Limit type: tokens. ' +
+        'Current limit: 50000, Remaining: 0. ' +
+        'Limit resets at: 2026-07-12 08:05:00 UTC',
+    ]
+    for (const text of litellmBodies) {
+      const line = JSON.stringify({
+        type: 'assistant',
+        message: {
+          role: 'assistant',
+          model: '<synthetic>',
+          content: [{ type: 'text', text }],
+        },
+        error: 'rate_limit',
+        isApiErrorMessage: true,
+        apiErrorStatus: 429,
+      })
+      const result = detectErrorInTranscriptLine(line)
+      expect(result).not.toBeNull()
+      expect(result!.kind).toBe('rate-limited')
+      expect(result!.transient).toBe(true)
+      // End-to-end: the resolver must NOT produce a model-unavailable card —
+      // null is what keeps the calm 🚦 card and blocks the auto-fallback
+      // branch in emitGatewayOperatorEvent.
+      expect(
+        resolveModelUnavailableFromOperatorEvent({
+          kind: result!.kind,
+          detail: result!.detail,
+        }),
+      ).toBeNull()
+    }
+  })
+
   // Guard against over-correcting: a GENUINE quota wall (no transient marker)
   // must STILL be quota-exhausted AND still resolve to a card.
   it('a genuine quota-wall 429 still produces the quota-exhausted card', () => {

package/telegram-plugin/tests/runtime-metrics.test.ts

@@ -91,6 +91,30 @@ describe('runtime-metrics — JSONL sink', () => {
     expect(typeof parsed.ts).toBe('number')
   })
 
+  it('rate_limit_429_classified carries classification + action + limit/reset detail', () => {
+    emitRuntimeMetric({
+      kind: 'rate_limit_429_classified',
+      agent: 'carrie',
+      classification: 'litellm-local',
+      action: 'calm',
+      reset_at_ms: 1_783_850_700_000,
+      reset_in_ms: 300_000,
+      limit_type: 'tpm',
+      limit: 8000,
+      current_usage: 8241,
+    })
+    const parsed = JSON.parse(readFileSync(metricsPath, 'utf-8').trim())
+    expect(parsed.kind).toBe('rate_limit_429_classified')
+    expect(parsed.agent).toBe('carrie')
+    expect(parsed.classification).toBe('litellm-local')
+    expect(parsed.action).toBe('calm')
+    expect(parsed.reset_in_ms).toBe(300_000)
+    expect(parsed.limit_type).toBe('tpm')
+    expect(parsed.limit).toBe(8000)
+    expect(parsed.current_usage).toBe(8241)
+    expect(typeof parsed.ts).toBe('number')
+  })
+
   it('appends — does not overwrite — across calls', () => {
     for (let i = 0; i < 5; i++) {
       emitRuntimeMetric({

package/telegram-plugin/tests/throttle-tier.test.ts

@@ -12,6 +12,8 @@
 
 import { describe, it, expect } from 'vitest'
 import {
+  build429ClassifiedMetric,
+  classify429Detail,
   decideThrottleTier,
   evaluateThrottleNotice,
   isAccountScopedThrottle,
@@ -136,6 +138,180 @@ describe('decideThrottleTier — decision matrix', () => {
   })
 })
 
+// Verbatim LiteLLM proxy-local 429 shapes (provenance on
+// `litellmProxyLocal429Signals`, model-unavailable.ts).
+const LITELLM_TPM_CAP =
+  'Deployment over user-defined ratelimit. tpm limit=8000. current usage=8241. ' +
+  'id=abc123def, model_group=claude-fable-5'
+const LITELLM_KEY_LIMIT =
+  'Rate limit exceeded for api_key: hashed-key-1a2b3c. Limit type: tokens. ' +
+  'Current limit: 8000, Remaining: 0. Limit resets at: 2026-07-12 08:05:00 UTC'
+const LITELLM_ROUTER_COOLDOWN =
+  'No deployments available for selected model, Try again in 27.5 seconds. ' +
+  "Passed model=claude-fable-5. pre-call-checks=False, cooldown_list=['abc123def']"
+// v3 limiter, descriptor NOT in the enumerated signal list — matched by the
+// litellmV3LimiterSignalPair co-occurrence rule (model-unavailable.ts).
+const LITELLM_TEAM_MODEL_LIMIT =
+  'Rate limit exceeded for model_per_team: team-1a2b3c:claude-fable-5. ' +
+  'Limit type: tokens. Current limit: 50000, Remaining: 0. ' +
+  'Limit resets at: 2026-07-12 08:05:00 UTC'
+
+describe('decideThrottleTier — LiteLLM-proxy-local 429s never enter the tier', () => {
+  // OUTCOME pin: `none` is what keeps a proxy-local cap trip off the
+  // account-scoped machinery — no broker mark-throttled, no throttle-tier
+  // runner fire, no failover escalation. The gateway additionally gates on
+  // classify429Detail, but the decision module must agree.
+  it.each([
+    ['deployment tpm cap', LITELLM_TPM_CAP],
+    ['virtual-key tpm_limit', LITELLM_KEY_LIMIT],
+    ['router cooldown', LITELLM_ROUTER_COOLDOWN],
+    ['team model cap (non-enumerated v3 descriptor)', LITELLM_TEAM_MODEL_LIMIT],
+  ])('%s → none (calm path owns it)', (_name, detail) => {
+    expect(decideThrottleTier({ detail, now: NOW, thresholdMs: THRESHOLD })).toEqual({
+      action: 'none',
+    })
+  })
+})
+
+describe('classify429Detail — three-way origin classification', () => {
+  it('classifies LiteLLM limiter wordings as litellm-local', () => {
+    expect(classify429Detail(LITELLM_TPM_CAP)).toBe('litellm-local')
+    expect(classify429Detail(LITELLM_KEY_LIMIT)).toBe('litellm-local')
+    expect(classify429Detail(LITELLM_ROUTER_COOLDOWN)).toBe('litellm-local')
+    // Non-enumerated v3 descriptor — the co-occurrence pair, not a list
+    // entry, carries this one.
+    expect(classify429Detail(LITELLM_TEAM_MODEL_LIMIT)).toBe('litellm-local')
+  })
+
+  it('classifies Anthropic account-affirming wording as account-scoped', () => {
+    expect(classify429Detail(TRANSIENT('resets in 3m'))).toBe('account-scoped')
+    expect(
+      classify429Detail('would exceed your account’s rate limit'),
+    ).toBe('account-scoped')
+  })
+
+  it('classifies server-side / bare rate-limit wording as generic-transient', () => {
+    expect(
+      classify429Detail('Server is temporarily limiting requests (not your usage limit)'),
+    ).toBe('generic-transient')
+    expect(classify429Detail('overloaded_error 529')).toBe('generic-transient')
+    expect(classify429Detail('rate_limit_error: try again later')).toBe('generic-transient')
+  })
+
+  it('TIE-BREAK: account-affirming wording wins over LiteLLM wording when both appear', () => {
+    // The pass-through shape: LiteLLM wraps a FORWARDED upstream Anthropic
+    // account 429 (exception mapping / limiter prose in the same body).
+    // LiteLLM never emits the account wording itself, so its presence means
+    // Anthropic really throttled the account — the broker throttle mark and
+    // the throttle tier must still run.
+    const mixed =
+      `litellm.RateLimitError: ${LITELLM_TPM_CAP} — upstream said: ` +
+      "This request would exceed your account's rate limit. Please try again later."
+    expect(classify429Detail(mixed)).toBe('account-scoped')
+    // And the tier decision still engages (not 'none').
+    expect(
+      decideThrottleTier({ detail: mixed, now: NOW, thresholdMs: THRESHOLD }).action,
+    ).not.toBe('none')
+  })
+
+  it('a bare litellm.RateLimitError wrapper WITHOUT limiter wording stays generic-transient', () => {
+    // The exception-mapping prefix alone is not proxy-local evidence.
+    expect(
+      classify429Detail('litellm.RateLimitError: RateLimitError: 429 try again later'),
+    ).toBe('generic-transient')
+  })
+
+  it('never throws on weird input', () => {
+    expect(classify429Detail('')).toBe('generic-transient')
+    expect(classify429Detail(undefined as unknown as string)).toBe('generic-transient')
+    expect(classify429Detail(9000 as unknown as string)).toBe('generic-transient')
+    expect(classify429Detail('A'.repeat(200_000))).toBe('generic-transient')
+  })
+})
+
+describe('build429ClassifiedMetric — instrumentation payload', () => {
+  it('litellm-local deployment cap → limit fields + calm action', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: LITELLM_TPM_CAP,
+      classification: 'litellm-local',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m).toEqual({
+      kind: 'rate_limit_429_classified',
+      agent: 'carrie',
+      classification: 'litellm-local',
+      action: 'calm',
+      reset_at_ms: null,
+      reset_in_ms: null,
+      limit_type: 'tpm',
+      limit: 8000,
+      current_usage: 8241,
+    })
+  })
+
+  it('litellm-local NON-enumerated v3 descriptor (model_per_team) → full metric payload', () => {
+    // Finding-pin: a team-level model cap must produce the metric (it used
+    // to miss every signal → quota-exhausted → no metric at all).
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: LITELLM_TEAM_MODEL_LIMIT,
+      classification: 'litellm-local',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m.kind).toBe('rate_limit_429_classified')
+    expect(m.classification).toBe('litellm-local')
+    expect(m.limit_type).toBe('tokens')
+    expect(m.limit).toBe(50_000)
+    expect(m.reset_at_ms).toBe(Date.UTC(2026, 6, 12, 8, 5, 0))
+  })
+
+  it('litellm-local v3 key limit → tokens limit type + parsed "Limit resets at" UTC reset', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: LITELLM_KEY_LIMIT,
+      classification: 'litellm-local',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m.limit_type).toBe('tokens')
+    expect(m.limit).toBe(8000)
+    expect(m.reset_at_ms).toBe(Date.UTC(2026, 6, 12, 8, 5, 0))
+    expect(m.reset_in_ms).toBe(Date.UTC(2026, 6, 12, 8, 5, 0) - NOW)
+  })
+
+  it('account-scoped 429 → Anthropic-parsed reset, no limit fields', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: TRANSIENT('resets in 3m'),
+      classification: 'account-scoped',
+      action: 'throttle',
+      now: NOW,
+    })
+    expect(m.classification).toBe('account-scoped')
+    expect(m.action).toBe('throttle')
+    expect(m.reset_at_ms).toBe(NOW + 3 * 60_000)
+    expect(m.reset_in_ms).toBe(3 * 60_000)
+    expect(m.limit_type).toBeNull()
+    expect(m.limit).toBeNull()
+    expect(m.current_usage).toBeNull()
+  })
+
+  it('never throws on weird detail; nulls out unparseable resets', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: undefined as unknown as string,
+      classification: 'generic-transient',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m.reset_at_ms).toBeNull()
+    expect(m.reset_in_ms).toBeNull()
+  })
+})
+
 describe('isAccountScopedThrottle — the tier gate', () => {
   it("matches account-affirming wording (both apostrophe variants + 'not your account')", () => {
     expect(isAccountScopedThrottle("would exceed your account's rate limit")).toBe(true)

package/telegram-plugin/throttle-tier.ts

@@ -33,7 +33,12 @@
 
 import { escapeMarkdown } from './card-format.js'
 import { formatResetRelative } from './quota-check.js'
-import { parseResetTime } from './model-unavailable.js'
+import {
+  isLitellmProxyLocal429,
+  parseLitellmLimitDetail,
+  parseResetTime,
+} from './model-unavailable.js'
+import type { RuntimeMetricEvent } from './runtime-metrics.js'
 
 // ─── Account-scoped throttle wording ─────────────────────────────────────────
 
@@ -65,6 +70,98 @@ export function isAccountScopedThrottle(text: string): boolean {
   return accountScopedThrottleSignals.some((s) => lower.includes(s))
 }
 
+// ─── Three-way 429 classification ────────────────────────────────────────────
+
+/**
+ * Where a terminal 429-family failure originated:
+ *   - `account-scoped`   — Anthropic throttled THIS account ("would exceed
+ *     your account's rate limit"). Eligible for the throttle tier below
+ *     (broker mark-throttled / failover).
+ *   - `litellm-local`    — the LiteLLM proxy's OWN limiter tripped
+ *     (`tpm_limit`/`rpm_limit` cap, router cooldown — see
+ *     `litellmProxyLocal429Signals` in model-unavailable.ts). The request
+ *     never reached Anthropic; account state must not be touched.
+ *   - `generic-transient` — everything else in the rate-limit family
+ *     (server-side 429/529 wording, bare `rate_limit_error`). Calm path.
+ */
+export type RateLimit429Classification =
+  | 'account-scoped'
+  | 'litellm-local'
+  | 'generic-transient'
+
+/**
+ * Classify a terminal `rate-limited` operator event's detail text.
+ *
+ * TIE-BREAK (both wordings present): account-scoped wins, and only on its
+ * EXPLICIT wording. Rationale: LiteLLM never emits the account-affirming
+ * strings itself, so when they co-occur with LiteLLM wording the detail is a
+ * genuine upstream Anthropic account 429 that traversed (and was wrapped by)
+ * the proxy — e.g. the pass-through's "litellm.RateLimitError: …would exceed
+ * your account's rate limit…" exception mapping. Classifying that as
+ * proxy-local would drop the broker throttle mark and walk every retry
+ * straight back into the same account throttle. The reverse risk is nil: a
+ * purely proxy-local 429 (limiter fired BEFORE any upstream call) cannot
+ * contain Anthropic's account wording.
+ *
+ * BOUND: operator events forwarded over IPC carry `detail` truncated to
+ * 1000 chars (bridge.ts `sendOperatorEvent`'s `.slice(0, 1000)`;
+ * `OPERATOR_EVENT_DETAIL_MAX` in gateway/ipc-server.ts), so on that path the
+ * tie-break sees only the first 1000 chars of the body. In practice both
+ * wordings sit well inside that window (real Anthropic and LiteLLM bodies
+ * are <400 chars), and a truncated-away account marker would merely
+ * downgrade account-scoped → litellm-local/generic-transient — the calm
+ * path, never a wrong account mark.
+ *
+ * Never throws on weird input (both matchers are total).
+ */
+export function classify429Detail(text: string): RateLimit429Classification {
+  if (isAccountScopedThrottle(text)) return 'account-scoped'
+  if (isLitellmProxyLocal429(text)) return 'litellm-local'
+  return 'generic-transient'
+}
+
+/**
+ * Build the `rate_limit_429_classified` runtime metric for one terminal
+ * rate-limited operator event — the instrumentation that lets an operator
+ * correlate Anthropic ACCOUNT 429s with fleet TPM (the prerequisite for
+ * enabling LiteLLM `tpm_limit` caps; see docs/auth.md § LiteLLM-proxy-local
+ * 429s). Pure builder so the payload shape is unit-testable; the gateway
+ * emits the result via emitRuntimeMetric (PostHog + JSONL dual sink).
+ *
+ * `action` is what the gateway decided for this event:
+ *   - `throttle` / `failover` — the account-scoped throttle tier's decision
+ *   - `calm` — the existing calm rate-limited path (litellm-local and
+ *     generic-transient always land here; no broker mark, no failover)
+ *
+ * Reset detail is best-effort: the Anthropic-shaped `parseResetTime` first,
+ * then LiteLLM's own shapes ("Limit resets at: … UTC" / "Try again in Ns")
+ * via `parseLitellmLimitDetail`. Limit fields parse only from LiteLLM
+ * wording (Anthropic bodies carry no numeric limit).
+ */
+export function build429ClassifiedMetric(opts: {
+  agent: string
+  detail: string
+  classification: RateLimit429Classification
+  action: 'throttle' | 'failover' | 'calm'
+  now: number
+}): Extract<RuntimeMetricEvent, { kind: 'rate_limit_429_classified' }> {
+  const detail = typeof opts.detail === 'string' ? opts.detail : ''
+  const litellm = parseLitellmLimitDetail(detail, new Date(opts.now))
+  const anthropicResetMs = parseResetTime(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,
+  }
+}
+
 /**
  * Default retry-in-place ceiling: a transient 429 whose reset is within this
  * window waits on the account instead of failing the fleet over. Override