maxpool 1.5.11 → 1.5.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.5.11",
+  "version": "1.5.13",
   "description": "Multi-account Claude Code proxy with adaptive, rate-aware load balancing across Claude accounts",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -1,4 +1,4 @@
-import { refreshAccessToken, isTokenExpiringSoon } from './oauth.js';
+import { refreshAccessToken, isTokenExpiringSoon, modelFamily } from './oauth.js';
 
 // Bounded re-poll hold for an account blocked ONLY by a transient, self-clearing
 // condition whose exact recovery time is unknown: (a) a weekly-critical account
@@ -36,8 +36,10 @@ function emptyQuota() {
     unified7dRaw: null,    // upstream-reported utilization before display clamp
     unified5hReset: null,  // ms timestamp
     unified7dReset: null,  // ms timestamp
-    unified7dSonnet: null,      // Sonnet-specific weekly utilization (from usage probe)
-    unified7dSonnetReset: null, // ms timestamp
+    // Per-model weekly sub-limits Anthropic enforces SEPARATELY from the unified
+    // weekly (e.g. Fable can be 100% while unified is 56%). Keyed by model family:
+    // { fable:{utilization,resetAt,severity,isActive}, opus:{...}, sonnet:{...} }.
+    scopedWeekly: {},
     unifiedStatus: null,   // allowed | allowed_warning | rejected
     resetsAt: null,
   };
@@ -91,7 +93,7 @@ const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
 // (probing, requalify, rateLimitedUntil) and credentials are intentionally
 // excluded. A stale restored window is wiped on first use by _clearExpiredQuotas.
 const PERSISTED_QUOTA_FIELDS = [
-  'unified5h', 'unified7d', 'unified5hReset', 'unified7dReset', 'unifiedStatus',
+  'unified5h', 'unified7d', 'unified5hReset', 'unified7dReset', 'unifiedStatus', 'scopedWeekly',
   'tokensLimit', 'tokensRemaining', 'requestsLimit', 'requestsRemaining', 'resetsAt',
 ];
 
@@ -310,7 +312,7 @@ export class AccountManager {
       // finite hold. It must NEVER contribute the WEEKLY reset (days) — that is the
       // multi-day-hang the bounded path fences off; see the !fairnessOnlyBlock
       // guards on the weekly branches below.
-      if (!fairnessOnlyBlock && this._isAvailable(account, { allowWeeklyReserve: true })) {
+      if (!fairnessOnlyBlock && this._isAvailable(account, { allowWeeklyReserve: true, model: requestInfo.model })) {
         return {
           available: true,
           retryAfterMs: 0,
@@ -319,15 +321,15 @@ export class AccountManager {
           matchingRoutes,
         };
       }
-      if (fairnessOnlyBlock && this._isAvailable(account, { allowWeeklyReserve: true, allowWeeklyCritical: true })) {
+      if (fairnessOnlyBlock && this._isAvailable(account, { allowWeeklyReserve: true, allowWeeklyCritical: true, model: requestInfo.model })) {
         soonestBoundedHold = Math.min(soonestBoundedHold, BOUNDED_REPOLL_HOLD_MS);
         if (!boundedHoldCause) boundedHoldCause = 'queued_behind_fairness';
         continue;
       }
 
-      const retry = this._retryInfo(account);
+      const retry = this._retryInfo(account, requestInfo.model);
       note(retry.cause);
-      if (!fairnessOnlyBlock && retry.weeklyCritical && this._isAvailable(account, { allowWeeklyReserve: true, allowWeeklyCritical: true })) {
+      if (!fairnessOnlyBlock && retry.weeklyCritical && this._isAvailable(account, { allowWeeklyReserve: true, allowWeeklyCritical: true, model: requestInfo.model })) {
         return {
           available: true,
           retryAfterMs: 0,
@@ -434,7 +436,7 @@ export class AccountManager {
     return weeklyPasses.some(options => this.accounts.some(account => {
       if (excludedIndexes.has(account.index)) return false;
       if (!this._matchesRequest(account, profile, requestInfo)) return false;
-      return this._isAvailable(account, options);
+      return this._isAvailable(account, { ...options, model: requestInfo.model });
     }));
   }
 
@@ -452,7 +454,7 @@ export class AccountManager {
     const weight = Math.max(1, Number(requestInfo.weight) || 1);
     const upstreamThrottleProbe = account.type !== 'provider' && this._claimUpstreamThrottleProbe();
     if (requestInfo.sessionKey) {
-      this._bindSession(requestInfo.sessionKey, account);
+      this._bindSession(requestInfo.sessionKey, account, requestInfo.model);
     }
     account.inFlight++;
     account.activeWeight += weight;
@@ -492,6 +494,11 @@ export class AccountManager {
 
     if (outcome.neutral) return;
 
+    // A per-model weekly cap is NOT an account failure — the account is healthy for
+    // every other model. Don't poison its failure counters / scoring penalty (mirror
+    // the network-blip carve-out); the scoped bench is already set in markRateLimited.
+    if (outcome.error === 'model_rate_limited') return;
+
     if (outcome.success) {
       account.completedRequests++;
       account.consecutiveFailures = 0;
@@ -558,6 +565,21 @@ export class AccountManager {
     };
   }
 
+  // True (with the scoped reset) when THIS request's model family has hit its
+  // per-model weekly sub-limit on this account — a block SEPARATE from the unified
+  // weekly (Fable can be 100% while unified is 56%). A model-agnostic request (no
+  // family) or an account with no scoped data fails OPEN (returns null), matching
+  // prior behavior. Gate: is_active AND (severity critical OR util ≥ exhausted).
+  _scopedExhausted(account, model) {
+    const fam = modelFamily(model);
+    if (!fam) return null;
+    const e = account.quota?.scopedWeekly?.[fam];
+    if (!e || e.isActive === false) return null;
+    const exhausted = e.severity === 'critical'
+      || (e.utilization != null && e.utilization >= this.scheduler.weeklyExhaustedThreshold);
+    return exhausted ? { resetAt: e.resetAt || null, family: fam } : null;
+  }
+
   _isAvailable(account, options = {}) {
     if (!account) return false;
     if (!account.enabled) return false;
@@ -606,6 +628,11 @@ export class AccountManager {
     if (weeklyState === 'critical' && !options.allowWeeklyCritical) return false;
     if (weeklyState === 'reserve' && !options.allowWeeklyReserve) return false;
 
+    // Per-model weekly cap for THIS request's model — unavailable for this request
+    // (but the account still serves its other models). options.model is threaded in
+    // by request-path callers; model-agnostic call sites skip this gate.
+    if (options.model && this._scopedExhausted(account, options.model)) return false;
+
     return true;
   }
 
@@ -873,6 +900,18 @@ export class AccountManager {
       changed = true;
     }
 
+    // Expire per-model weekly sub-limits on their own reset (a family whose scoped
+    // window has passed is usable again for that model, independent of unified).
+    if (q.scopedWeekly && typeof q.scopedWeekly === 'object') {
+      for (const [fam, e] of Object.entries(q.scopedWeekly)) {
+        if (e && e.resetAt && now >= e.resetAt) {
+          console.log(`[Maxpool] Account "${account.name}" ${fam} weekly sub-limit reset`);
+          delete q.scopedWeekly[fam];
+          changed = true;
+        }
+      }
+    }
+
     // Clear expired standard quotas
     if (q.resetsAt && now >= new Date(q.resetsAt).getTime()) {
       q.tokensRemaining = null;
@@ -1028,8 +1067,8 @@ export class AccountManager {
       if (account.index === bound.index) continue;
       if (excludedIndexes.has(account.index)) continue;
       if (!this._matchesRequest(account, profile, requestInfo)) continue;
-      // Genuinely-healthy alternatives only (normal/soft/unknown weekly).
-      if (!this._isAvailable(account, { allowWeeklyReserve: false, allowWeeklyCritical: false })) continue;
+      // Genuinely-healthy alternatives only (normal/soft/unknown weekly + model headroom).
+      if (!this._isAvailable(account, { allowWeeklyReserve: false, allowWeeklyCritical: false, model: requestInfo.model })) continue;
       const score = this._scoreAccount(account, requestInfo, scoringCtx);
       if (score < bestScore) {
         bestScore = score;
@@ -1043,7 +1082,7 @@ export class AccountManager {
       && bestTier < boundTier;
   }
 
-  _retryInfo(account) {
+  _retryInfo(account, model = null) {
     const now = Date.now();
     const q = account.quota || {};
 
@@ -1056,6 +1095,14 @@ export class AccountManager {
     if (account.status === 'error') return { cause: 'error', retryAt: null, queueable: false };
     if (account.status === 'exhausted') return { cause: 'exhausted', retryAt: null, queueable: false };
 
+    // Per-model weekly cap for THIS request's model: a hard block until the scoped
+    // weekly reset (days), exactly like weekly_exhausted but scoped to one model —
+    // reuse that cause so the oracle's weekly-reset branches hold on the scoped
+    // reset consistently (agreeing with _isAvailable's model gate above; the oracle
+    // still returns available:true off any SIBLING account with model headroom).
+    const scoped = model ? this._scopedExhausted(account, model) : null;
+    if (scoped) return { cause: 'weekly_exhausted', retryAt: scoped.resetAt, queueable: false, modelScoped: true };
+
     // RAW weekly state, so the retry oracle agrees with _isAvailable's raw gate.
     // (Pace must NOT classify a raw-healthy account as weekly_critical here, or
     // the queue keys on a far-future reset instead of the account's real
@@ -1169,7 +1216,7 @@ export class AccountManager {
       const pinned = this.accounts.find(a => a.name === requestInfo.pinnedAccountName);
       if (pinned && !excludedIndexes.has(pinned.index)
         && this._matchesRequest(pinned, profile, requestInfo)
-        && this._isAvailable(pinned, { allowWeeklyReserve: true, allowWeeklyCritical: true })) {
+        && this._isAvailable(pinned, { allowWeeklyReserve: true, allowWeeklyCritical: true, model: requestInfo.model })) {
         this.currentIndex = pinned.index;
         return pinned;
       }
@@ -1182,7 +1229,7 @@ export class AccountManager {
         { allowWeeklyReserve: true, allowWeeklyCritical: false },
         { allowWeeklyReserve: true, allowWeeklyCritical: true },
       ];
-      if (preferredPasses.some(options => this._isAvailable(preferred, options))) {
+      if (preferredPasses.some(options => this._isAvailable(preferred, { ...options, model: requestInfo.model }))) {
         this.currentIndex = preferred.index;
         return preferred;
       }
@@ -1217,7 +1264,7 @@ export class AccountManager {
         const account = this.accounts[idx];
         if (excludedIndexes.has(account.index)) continue;
         if (!this._matchesRequest(account, profile, requestInfo)) continue;
-        if (!this._isAvailable(account, weeklyOptions)) continue;
+        if (!this._isAvailable(account, { ...weeklyOptions, model: requestInfo.model })) continue;
 
         const priority = Number.isFinite(account.priority) ? account.priority : 0;
         const score = this._scoreAccount(account, requestInfo, scoringCtx);
@@ -1296,11 +1343,11 @@ export class AccountManager {
     if (!account) return null;
     if (excludedIndexes.has(account.index)) return null;
     if (!this._matchesRequest(account, profile, requestInfo)) return null;
-    if (!this._isAvailable(account, options)) return null;
+    if (!this._isAvailable(account, { ...options, model: requestInfo.model })) return null;
     return account;
   }
 
-  _bindSession(sessionKey, account) {
+  _bindSession(sessionKey, account, model = null) {
     const priority = this._priority(account);
     const binding = this._sessionBinding(sessionKey) || {
       homeName: account.name,
@@ -1317,8 +1364,11 @@ export class AccountManager {
       // _boundAccount (which prefers homeName) doesn't snap the session straight
       // back to the hot home next request. If the old home is UNAVAILABLE this is a
       // FAILOVER → keep homeName so the session returns to it once it recovers.
+      // Model-aware: a move off a home that's capped for THIS model (but healthy
+      // for others) is a FAILOVER, not a by-choice rebalance — keep homeName so the
+      // session snaps back once the model's scoped cap resets.
       const oldHome = this.accounts.find(a => a.name === binding.homeName);
-      if (oldHome && this._isAvailable(oldHome, { allowWeeklyReserve: true })) {
+      if (oldHome && this._isAvailable(oldHome, { allowWeeklyReserve: true, model })) {
         binding.homeName = account.name;
       }
     }
@@ -1349,7 +1399,7 @@ export class AccountManager {
       if (excludedIndexes.has(account.index)) return false;
       if (!this._matchesRequest(account, profile, requestInfo)) return false;
       const priority = this._priority(account);
-      return priority < boundPriority && this._isAvailable(account, { allowWeeklyReserve: true });
+      return priority < boundPriority && this._isAvailable(account, { allowWeeklyReserve: true, model: requestInfo.model });
     });
   }
 
@@ -1619,9 +1669,21 @@ export class AccountManager {
       if (usage.sevenDay.utilization != null) q.unified7d = clamp01(usage.sevenDay.utilization);
       if (usage.sevenDay.resetAt != null) q.unified7dReset = usage.sevenDay.resetAt;
     }
-    if (usage.sevenDaySonnet) {
-      if (usage.sevenDaySonnet.utilization != null) q.unified7dSonnet = clamp01(usage.sevenDaySonnet.utilization);
-      if (usage.sevenDaySonnet.resetAt != null) q.unified7dSonnetReset = usage.sevenDaySonnet.resetAt;
+    // Per-model weekly sub-limits (Fable, Opus, ...). Replace wholesale with the
+    // fresh probe set so a family that dropped out of the response doesn't linger
+    // stale; expiry on reset is a backstop for the between-probe window.
+    if (usage.scopedWeekly && typeof usage.scopedWeekly === 'object') {
+      const fresh = {};
+      for (const [fam, e] of Object.entries(usage.scopedWeekly)) {
+        if (!e) continue;
+        fresh[fam] = {
+          utilization: e.utilization != null ? clamp01(e.utilization) : null,
+          resetAt: e.resetAt != null ? e.resetAt : null,
+          severity: e.severity || null,
+          isActive: e.isActive !== false,
+        };
+      }
+      q.scopedWeekly = fresh;
     }
 
     // If we just learned this account's weekly window while probing, re-evaluate
@@ -1745,6 +1807,27 @@ export class AccountManager {
     const account = this.accounts[accountIndex];
     if (!account) return;
     const retryAfter = clampRetryAfterSeconds(retryAfterSeconds);
+
+    // Model-scoped rate-limit: a per-model weekly cap (e.g. Fable) rejected this
+    // request while the account's UNIFIED quota is healthy. Record ONLY the scoped
+    // exhaustion — do NOT bench the whole account (its other models still have
+    // headroom). The just-429'd request fails over to a headroom account via the
+    // per-request excludedIndexes; future same-model requests are steered by the
+    // scoped gate; future other-model requests keep using this account.
+    if (options.modelScope) {
+      account.quota.scopedWeekly = account.quota.scopedWeekly || {};
+      account.quota.scopedWeekly[options.modelScope] = {
+        utilization: 1,
+        resetAt: Date.now() + (retryAfter * 1000),
+        severity: 'critical',
+        isActive: true,
+      };
+      account.lastStatus = options.status || 429;
+      account.lastErrorAt = Date.now();
+      console.log(`[Maxpool] Account "${account.name}" ${options.modelScope} weekly limit hit — scoped bench ${retryAfter}s (account stays active for other models)`);
+      return;
+    }
+
     account.status = 'throttled';
     account.rateLimitedUntil = Date.now() + (retryAfter * 1000);
     account.lastStatus = options.status || 429;
@@ -2099,6 +2182,16 @@ export class AccountManager {
       // could otherwise pin the account unavailable until the first live response.
       if (account.quota.unified5hReset == null) account.quota.unified5h = null;
       if (account.quota.unified7dReset == null) account.quota.unified7d = null;
+      // Drop restored scoped entries lacking a clearable reset window — they can't
+      // be expired by _clearExpiredQuotas and would otherwise pin an account
+      // unavailable-for-family until the first live probe.
+      if (account.quota.scopedWeekly && typeof account.quota.scopedWeekly === 'object') {
+        for (const [fam, e] of Object.entries(account.quota.scopedWeekly)) {
+          if (!e || e.resetAt == null) delete account.quota.scopedWeekly[fam];
+        }
+      } else {
+        account.quota.scopedWeekly = {};
+      }
       // We already know this account's weekly window, so it isn't "probing".
       if (account.quota.unified7dReset != null) account.probing = false;
     }

package/src/index.js

@@ -156,10 +156,20 @@ async function supervisorCommand() {
   // supervisor's acceptor is only LIVE during the brief cutover gap (it stops
   // once a worker confirms it is the sole acceptor). A bare handler is required
   // so the rare gap-accepted socket isn't left dangling.
-  const relistenMaster = () => new Promise((resolve, reject) => {
+  const relistenMaster = (retriesOnBusy = 20) => new Promise((resolve, reject) => {
     if (masterServer.listening) { resolve(); return; }
-    const onErr = err => { masterServer.removeListener('listening', onListen); reject(err); };
     const onListen = () => { masterServer.removeListener('error', onErr); resolve(); };
+    const onErr = err => {
+      masterServer.removeListener('listening', onListen);
+      // A just-SIGKILLed worker (seamless-reload fallback) may not have released the
+      // listening fd yet — SIGKILL is async; the port frees within a few ms. Retry
+      // bounded (~1s) rather than crashing the supervisor via handleServerListenError.
+      if (err.code === 'EADDRINUSE' && retriesOnBusy > 0) {
+        setTimeout(() => relistenMaster(retriesOnBusy - 1).then(resolve, reject), 50);
+        return;
+      }
+      reject(err);
+    };
     masterServer.once('error', onErr);
     masterServer.once('listening', onListen);
     masterServer.listen(port, host);
@@ -347,6 +357,19 @@ async function supervisorCommand() {
 
   try {
     while (true) {
+      // Ensure the master socket is LISTENING before handing it to a cold worker.
+      // After the previous primary worker sent MSG_PRIMARY the supervisor ran
+      // closeMasterAccept() (masterServer.close()), and the exiting worker released
+      // the last fd — so on every respawn masterServer is closed. Without this,
+      // spawnWorker sends a dead handle, the worker ignores it (falsy-handle guard),
+      // and never becomes primary → the interactive `r` restart hangs blank. Idempotent
+      // (no-op when already listening, e.g. the very first iteration after line 172).
+      try {
+        await relistenMaster();
+      } catch (err) {
+        handleServerListenError(err, host, port);
+        return;
+      }
       const worker = spawnWorker({ reload: false });
       const startedAt = Date.now();
       const result = await superviseTurn(worker);
@@ -725,7 +748,10 @@ async function serverWorkerCommand() {
     if (draining) return;
     // Interactive (live TUI) → full cold restart so the fresh worker re-renders the
     // TUI; headless/service → zero-downtime seamless baton (nothing visual to lose).
-    if (reloadStrategy({ supervised, useTUI }) === 'seamless') {
+    // Test-only: force the interactive cold-restart path headless (a pty can't be
+    // allocated in-suite), so the exit-75 respawn is exercised without a real TUI.
+    const forceCold = process.env.MAXPOOL_TEST_FORCE_COLD_RESTART === '1';
+    if (!forceCold && reloadStrategy({ supervised, useTUI }) === 'seamless') {
       try {
         process.send({ type: MSG_RELOAD_REQUEST });
         return;
@@ -991,6 +1017,12 @@ async function serverWorkerCommand() {
           // Cold start: take the socket and go primary immediately.
           await listenOnHandle(handle);
           await becomePrimary({ viaTakeover: false });
+        } else if (msg?.type === MSG_LISTEN && !handle) {
+          // Defense-in-depth for the stale-handle hang: if the supervisor ever hands
+          // a cold worker a dead/absent socket, fail LOUD and exit-75 so it respawns —
+          // never sit alive-but-not-primary (the blank-screen `r`-restart hang).
+          console.error('[Maxpool] Cold worker received MSG_LISTEN with no socket handle — exiting for respawn.');
+          process.exit(SERVER_RESTART_EXIT_CODE);
         } else if (msg?.type === MSG_PROBE_READY) {
           // Headless reload worker: we've booted the new code and restored quota
           // in memory. Confirm readiness (we are NOT yet accepting / writing).
@@ -1013,9 +1045,13 @@ async function serverWorkerCommand() {
           await releaseBatonAndDrain();
         }
       } catch (err) {
-        // A failed reload worker must NOT exit(1) (kills the supervisor loop).
-        // Report failure so the supervisor rolls back; stay alive harmlessly.
-        console.error(`[Maxpool] Reload worker error: ${err.message}`);
+        console.error(`[Maxpool] Worker message error: ${err.message}`);
+        // A COLD worker that failed to listen / become primary has no baton to roll
+        // back to — it would strand blank. Exit-75 so the supervisor respawns it
+        // (closes the silent-non-primary hang class). A RELOAD worker mid-baton must
+        // NOT exit (that kills the supervisor loop) — report MSG_FAILED so the
+        // supervisor rolls back and the old worker stays primary (zero disruption).
+        if (!isReloadWorker) process.exit(SERVER_RESTART_EXIT_CODE);
         try { process.send({ type: MSG_FAILED, reason: err.message }); } catch { /* ignore */ }
       }
     });

package/src/oauth.js

@@ -136,9 +136,34 @@ export async function fetchProfile(accessToken) {
 const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const OAUTH_USAGE_BETA = 'oauth-2025-04-20';
 
+/** Parse a reset timestamp (epoch-seconds, epoch-ms, or ISO string) to ms, or null. */
+export function parseResetTimestamp(rawReset) {
+  if (typeof rawReset === 'number') return rawReset < 1e12 ? rawReset * 1000 : rawReset;
+  if (typeof rawReset === 'string') {
+    const asNum = Number(rawReset);
+    if (Number.isFinite(asNum) && rawReset.trim() !== '') return asNum < 1e12 ? asNum * 1000 : asNum;
+    const parsed = Date.parse(rawReset);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+/** Map a model id or usage display name to a coarse family key, or null. Matches
+ *  BOTH request models (`claude-fable-5`) and usage `scope.model.display_name`
+ *  (`Fable`). Unmatched → null (caller treats as never model-scoped). */
+export function modelFamily(model) {
+  const s = String(model || '').toLowerCase();
+  if (s.includes('fable') || s.includes('mythos')) return 'fable';
+  if (s.includes('opus')) return 'opus';
+  if (s.includes('sonnet')) return 'sonnet';
+  if (s.includes('haiku')) return 'haiku';
+  return null;
+}
+
 /** Normalize one usage bucket from the /api/oauth/usage response to
  *  { utilization: 0..1, resetAt: ms-timestamp } (tolerant of field-name and
- *  percentage/epoch-vs-iso variations). */
+ *  percentage/epoch-vs-iso variations). Legacy top-level buckets only — the
+ *  `limits[]` path uses parseLimitEntry (clean 0-100 percent, no ambiguity). */
 export function normalizeUsageBucket(bucket) {
   if (!bucket || typeof bucket !== 'object') return null;
 
@@ -148,25 +173,26 @@ export function normalizeUsageBucket(bucket) {
     ? (parsedPct > 1 ? parsedPct / 100 : parsedPct)
     : null;
 
-  const rawReset = bucket.resets_at ?? bucket.resetsAt ?? bucket.reset_at ?? bucket.resetAt;
-  let resetAt = null;
-  if (typeof rawReset === 'number') {
-    resetAt = rawReset < 1e12 ? rawReset * 1000 : rawReset;
-  } else if (typeof rawReset === 'string') {
-    const asNum = Number(rawReset);
-    if (Number.isFinite(asNum) && rawReset.trim() !== '') {
-      resetAt = asNum < 1e12 ? asNum * 1000 : asNum;
-    } else {
-      const parsed = Date.parse(rawReset);
-      if (Number.isFinite(parsed)) resetAt = parsed;
-    }
-  }
+  return { utilization, resetAt: parseResetTimestamp(bucket.resets_at ?? bucket.resetsAt ?? bucket.reset_at ?? bucket.resetAt) };
+}
 
-  return { utilization, resetAt };
+/** Normalize one `limits[]` entry. `percent` is a clean 0-100 integer (unlike the
+ *  ambiguous top-level buckets), so utilization = percent/100 always. */
+export function parseLimitEntry(l) {
+  if (!l || typeof l !== 'object') return null;
+  const pct = typeof l.percent === 'number' ? l.percent : parseFloat(l.percent);
+  return {
+    utilization: Number.isFinite(pct) ? Math.max(0, Math.min(1, pct / 100)) : null,
+    resetAt: parseResetTimestamp(l.resets_at ?? l.resetsAt),
+    severity: typeof l.severity === 'string' ? l.severity : null,
+    isActive: l.is_active !== false,
+  };
 }
 
 /** Read an account's quota from the zero-spend /api/oauth/usage endpoint.
- *  Returns { fiveHour, sevenDay, sevenDaySonnet } buckets, or { error, status }. */
+ *  Returns { fiveHour, sevenDay, scopedWeekly } buckets, or { error, status }.
+ *  Per-model + unified limits now live in the `limits[]` array (the top-level
+ *  seven_day_opus / seven_day_sonnet keys are deprecated → always null). */
 export async function fetchUsage(accessToken) {
   try {
     const res = await fetch(USAGE_URL, {
@@ -189,10 +215,30 @@ export async function fetchUsage(accessToken) {
     }
 
     const data = await res.json();
+
+    // The `limits[]` array is the authoritative source: `session` (5h), unscoped
+    // `weekly_all` (unified 7d), and `weekly_scoped` entries carrying a
+    // `scope.model` — the PER-MODEL weekly sub-limits (e.g. Fable) Anthropic
+    // enforces separately from the unified weekly. Prefer it over the legacy
+    // top-level buckets (whose 0-100 percent misreads a genuine 1% as 100%).
+    const scopedWeekly = {};
+    let limitsSession = null;
+    let limitsWeeklyAll = null;
+    for (const l of (Array.isArray(data?.limits) ? data.limits : [])) {
+      if (l?.kind === 'weekly_scoped') {
+        const fam = l?.scope?.model?.display_name ? modelFamily(l.scope.model.display_name) : null;
+        if (fam) scopedWeekly[fam] = parseLimitEntry(l);
+      } else if (l?.kind === 'session') {
+        limitsSession = parseLimitEntry(l);
+      } else if (l?.kind === 'weekly_all') {
+        limitsWeeklyAll = parseLimitEntry(l);
+      }
+    }
+
     return {
-      fiveHour: normalizeUsageBucket(data?.five_hour),
-      sevenDay: normalizeUsageBucket(data?.seven_day),
-      sevenDaySonnet: normalizeUsageBucket(data?.seven_day_sonnet),
+      fiveHour: limitsSession || normalizeUsageBucket(data?.five_hour),
+      sevenDay: limitsWeeklyAll || normalizeUsageBucket(data?.seven_day),
+      scopedWeekly,
     };
   } catch (err) {
     return { error: err.message || String(err), status: null };

package/src/server.js

@@ -1,6 +1,7 @@
 import http from 'node:http';
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { modelFamily } from './oauth.js';
 
 
 const HOP_BY_HOP_HEADERS = new Set([
@@ -453,7 +454,7 @@ async function forwardRequest(
       const errorBody = await readErrorBody(upstreamRes);
       const retryAfter = parseRetryAfter(upstreamRes.headers.get('retry-after'))
         || parseProviderRetryAfter(errorBody, account.provider);
-      const rateLimit = classifyRateLimit(account, rateLimitHeaders, errorBody);
+      const rateLimit = classifyRateLimit(account, rateLimitHeaders, errorBody, { model: requestInfo.model, retryAfter });
       if (rateLimit.scope === 'upstream') {
         const parsedError = parseJsonError(errorBody);
         const fingerprint = `429:${rateLimit.fingerprint || overloadFingerprint(errorBody, body)}`;
@@ -552,8 +553,9 @@ async function forwardRequest(
         status: 429,
         recordFailure: false,
         fingerprint: rateLimit.scope === 'unknown' ? rateLimit.fingerprint : null,
+        modelScope: rateLimit.modelScope || null,
       });
-      accountManager.releaseAccount(lease, { status: 429, error: 'rate_limited' });
+      accountManager.releaseAccount(lease, { status: 429, error: rateLimit.modelScope ? 'model_rate_limited' : 'rate_limited' });
 
       if (logDir) {
         logSections.push(`=== RESPONSE 429 — "${account.name}" rate-limited ${retryAfter}s ===\n${formatHeaders(upstreamRes.headers)}`);
@@ -1008,7 +1010,7 @@ function unavailableMessage(accountManager, requestInfo = {}, retryAfter, willRe
   return `All ${n} accounts exhausted. Retry in ${retryAfter}s.`;
 }
 
-export const __serverTest = { unavailableMessage, computeQueueWindowMs, isRetriableUpstreamStatus, headerValue, getMaxpoolProfile, ensureQueueHeartbeat, clearQueueHeartbeat, describeRequest };
+export const __serverTest = { unavailableMessage, computeQueueWindowMs, isRetriableUpstreamStatus, headerValue, getMaxpoolProfile, ensureQueueHeartbeat, clearQueueHeartbeat, describeRequest, classifyRateLimit };
 
 async function readErrorBody(upstreamRes, limitBytes = 64 * 1024) {
   if (!upstreamRes.body) return '';
@@ -1073,7 +1075,7 @@ function parseJsonError(body) {
   }
 }
 
-function classifyRateLimit(account, headers, body) {
+function classifyRateLimit(account, headers, body, opts = {}) {
   if (account.type === 'provider') return { scope: 'account', fingerprint: null };
 
   const parsed = parseJsonError(body);
@@ -1085,18 +1087,38 @@ function classifyRateLimit(account, headers, body) {
   const tokensRemaining = Number(headers['anthropic-ratelimit-tokens-remaining']);
   const requestsRemaining = Number(headers['anthropic-ratelimit-requests-remaining']);
 
+  // A PER-MODEL weekly sub-limit (e.g. Fable) rejects while the account's UNIFIED
+  // quota is healthy. We can't rely on a captured Fable-429 body shape, so detect
+  // by the CONTRADICTION: a weekly-class (long) reset AND both unified buckets NOT
+  // exhausted AND the request carries a known model family. Tagging modelScope
+  // makes the failover bench only (account, model) — not the whole account (which
+  // still has headroom for its other models). retryAfter is in SECONDS.
+  const fam = modelFamily(opts.model);
+  const retryAfter = Number(opts.retryAfter);
+  // Model-scope requires POSITIVE evidence the unified quota has headroom: at least
+  // one unified utilization header present AND both present ones below the floor. A
+  // rejection with NO utilization headers is treated as account-wide (safer — a
+  // genuine account cap with stripped headers must bench the whole account, not one
+  // model). Neither bucket may be at/above the exhaustion floor.
+  const haveUnifiedEvidence = Number.isFinite(weekly) || Number.isFinite(fiveHour);
+  const unifiedNotExhausted =
+    (!Number.isFinite(weekly) || weekly < 0.985) && (!Number.isFinite(fiveHour) || fiveHour < 0.985);
+  const modelScope =
+    (fam && haveUnifiedEvidence && unifiedNotExhausted && Number.isFinite(retryAfter) && retryAfter >= 30 * 60)
+      ? fam : null;
+
   const quotaHeaderExhaustion =
     unifiedStatus === 'rejected'
     || (Number.isFinite(fiveHour) && fiveHour >= 0.985)
     || (Number.isFinite(weekly) && weekly >= 0.985)
     || (headers['anthropic-ratelimit-tokens-remaining'] != null && tokensRemaining <= 0)
     || (headers['anthropic-ratelimit-requests-remaining'] != null && requestsRemaining <= 0);
-  if (quotaHeaderExhaustion) return { scope: 'account', fingerprint: null };
+  if (quotaHeaderExhaustion) return { scope: 'account', fingerprint: null, modelScope };
 
   const quotaBodyExhaustion =
     /\b(account|plan|session|weekly|quota)\b.{0,40}\b(exhausted|limit|exceeded|reached)\b/i.test(message)
     || /\busage\b.{0,40}\b(exhausted|exceeded|reached)\b/i.test(message);
-  if (quotaBodyExhaustion) return { scope: 'account', fingerprint: null };
+  if (quotaBodyExhaustion) return { scope: 'account', fingerprint: null, modelScope };
 
   const explicitSharedThrottle =
     message.includes('not your usage limit')

package/src/tui.js

@@ -986,6 +986,15 @@ export class TUI {
     }
     const weekly = weeklyPolicyText(this.am, a);
     if (weekly) line += `  ${weekly}`;
+    // Per-model weekly caps (e.g. Fable maxed while the unified weekly still has
+    // headroom) — surfaced separately so a capped model on an otherwise-healthy
+    // account is visible, and routing away from it is explained.
+    const exhaustedFloor = this.am.scheduler?.weeklyExhaustedThreshold ?? 0.985;
+    const capped = Object.entries(q.scopedWeekly || {})
+      .filter(([, e]) => e && e.isActive !== false
+        && (e.severity === 'critical' || (e.utilization != null && e.utilization >= exhaustedFloor)))
+      .map(([fam]) => fam.charAt(0).toUpperCase() + fam.slice(1));
+    if (capped.length) line += `  ${red(`${capped.join(',')} maxed`)}`;
     line += `  ${dim(loadText(this._accountLoad(a)))}`;
     return line;
   }