maxpool 1.0.6 → 1.1.0

package/README.md

@@ -6,6 +6,19 @@ Sits transparently between Claude Code and the Anthropic API, managing multiple
 
 ![Maxpool TUI](screenshots/maxpool.png)
 
+## ⚠️ Read this first: account risk and Anthropic's terms
+
+This tool sits in a **contested gray area** of Anthropic's terms. Using it could put your Claude accounts at risk. Please read before installing.
+
+- **Not blessed by Anthropic.** This is an independent project. Anthropic has not approved multi-account proxying, and nothing here is covered by an official "this is allowed" statement.
+- **The terms can be read to prohibit it.** Anthropic's Consumer Terms (Section 3, automated access) and its February 2026 rule that subscription OAuth tokens are "only authorized for use with Claude Code" can reasonably be read to cover a proxy that selects and injects tokens across accounts. It is genuinely ambiguous, and the ambiguity is not in your favor.
+- **Multiplexing is a detectable pattern.** Many accounts fronted by one machine, with parallel sessions and fast token rotation, looks like the anomaly Anthropic's automated systems flag, regardless of intent. People have lost accounts to pattern detection, and a clawback can hit all your pooled accounts at once.
+- **Owned accounts only. No spoofing.** Only use accounts you personally own and pay for. Never share accounts across people (that is the clear violation), and never add IP/residential proxies, fingerprint spoofing, or MITM. Those are the documented ban triggers, and this fork deliberately leaves them out. PRs adding them will be rejected.
+- **You are accepting the risk.** If you use this, you may lose accounts you pay for. This notice protects honesty, not your account.
+- **Do your own research. This is not legal advice.** The terms have moved several times in 2026. Check the current terms yourself before relying on it.
+
+If you want certainty, ask Anthropic support directly, or use **API-key accounts** (the sanctioned path for tooling) instead of subscription OAuth.
+
 ## Features
 
 - **Rate-aware load balancing** — ranks accounts by remaining quota ÷ time-to-reset, not raw usage %, so a near-reset account with quota left is drained (use-it-or-lose-it) and one burning fast early in its window is spared; sequential traffic rotates across accounts instead of funnelling onto one
@@ -286,8 +299,11 @@ TEAMCLAUDE_CONFIG=./my-config.json maxpool server
     "maxWaitMs": 86400000,
     "autoMaxWaitMs": null,
     "capacityMaxWaitMs": 900000,
+    "weeklyMaxWaitMs": 86400000,
+    "nonStreamMaxWaitMs": 300000,
+    "maxConcurrentQueued": 64,
+    "maxQueuedBytes": 1073741824,
     "maxQueuedBodyBytes": 268435456,
-    "weeklyMaxWaitMs": 0,
     "pollMs": 1000
   },
   "shutdown": {
@@ -325,7 +341,10 @@ TEAMCLAUDE_CONFIG=./my-config.json maxpool server
 | `queue.autoMaxWaitMs` | Optional shorter auto-queue cap. Set to `null` or omit it to use `queue.maxWaitMs`; set a number for interactive sessions where you prefer fast errors |
 | `queue.capacityMaxWaitMs` | Separate cap for repeated upstream 5xx/overload failures; defaults to 15m so broken providers do not park requests for 24h |
 | `queue.maxQueuedBodyBytes` | Maximum request body Maxpool will hold in memory while waiting for capacity before the request has been sent upstream; defaults to 256 MiB |
-| `queue.weeklyMaxWaitMs` | Optional cap for weekly-limit waits. Defaults to `0`, so weekly exhaustion fails fast instead of parking requests for days |
+| `queue.weeklyMaxWaitMs` | How long to hold a request when every account is at its weekly (7d) cap. Defaults to 24h — but the early-exit gates on each account's REAL reset time, so it only waits when a reset genuinely lands inside the window and errors honestly otherwise. (Was `0` = fail-fast, which killed sessions the instant all accounts hit their weekly cap.) |
+| `queue.nonStreamMaxWaitMs` | Max hold for non-streaming requests; defaults to 5m. They have no SSE keepalive, so a longer hold would die on the client timeout anyway |
+| `queue.maxConcurrentQueued` | Backpressure: max requests held waiting at once; defaults to 64. Beyond it, new waiters get a clear "queue full" error instead of growing the heap |
+| `queue.maxQueuedBytes` | Backpressure: max aggregate buffered request-body bytes across all held requests; defaults to 1 GiB |
 | `queue.pollMs` | How often queued requests check for a recovered account/provider |
 | `queue.heartbeatMs` | SSE heartbeat interval for queued streaming requests; defaults to 10s so Claude Code keeps the queued connection alive |
 | `shutdown.drainTimeoutMs` | Maximum time quit/Ctrl-C waits for active requests before exiting |
@@ -355,7 +374,7 @@ The weekly usage bar shows raw upstream utilization and reset timing. Reset-awar
 11. In the `all` profile only, if all Claude accounts are unavailable, provider fallbacks are tried by priority: GLM before Kimi
 12. If all eligible accounts/providers are temporarily unavailable for a temporary reason (5h/session limit, provider cooldown, short 429), the proxy queues the request and retries when one recovers
 13. Repeated upstream 5xx/overload failures use the shorter `capacityMaxWaitMs` cap, not the long quota wait
-14. Weekly exhaustion and non-retryable 4xx errors fail fast by default; if the queue wait expires, returns 429 with the soonest retry time
+14. Weekly (7d) exhaustion is held and retried like a 5h cap, up to `weeklyMaxWaitMs`, but only when an account's real reset lands inside the window; if the soonest reset is beyond it (or unknown), it returns 429 promptly with an honest message naming the soonest reset rather than spinning. Non-retryable 4xx errors still fail fast
 15. Temporary OAuth refresh failures cool the account down and queue/fail over; invalid refresh credentials disable only that account and require login
 16. In an interactive terminal, the server runs under a foreground supervisor so confirmed Restart (`r`) can drain and restart without detaching the replacement TUI
 17. When Restart is confirmed, new upstream admission pauses immediately. Existing upstream requests finish, queued requests cannot deadlock restart, and their sockets close during relaunch so Claude Code reconnects automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "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

@@ -173,6 +173,7 @@ export class AccountManager {
       waiting: [],
       lastAdmissionAt: 0,
       rampUntil: 0,
+      bytes: 0, // aggregate buffered body bytes across all held requests
     };
     this.admissionPaused = false;
   }
@@ -197,6 +198,7 @@ export class AccountManager {
     let soonestTemporary = Infinity;
     let temporaryCause = null;
     let soonestWeekly = Infinity;
+    let weeklyUnknownReset = 0; // weekly-exhausted accounts whose reset time we don't know yet
     let matchingRoutes = 0;
     const reasons = {};
 
@@ -244,6 +246,11 @@ export class AccountManager {
       } else if (retry.cause === 'weekly_exhausted' && retry.retryAt) {
         const ms = retry.retryAt - Date.now();
         if (ms < soonestWeekly) soonestWeekly = ms;
+      } else if (retry.cause === 'weekly_exhausted' && !retry.retryAt) {
+        // Weekly-capped but we haven't learned the reset time (cold start /
+        // probe failure). We cannot estimate a wait — flag it so the caller
+        // emits an honest "reset time unknown" error instead of waiting forever.
+        weeklyUnknownReset++;
       }
     }
 
@@ -267,6 +274,16 @@ export class AccountManager {
       };
     }
 
+    if (weeklyUnknownReset > 0) {
+      return {
+        available: false,
+        retryAfterMs: Infinity,
+        cause: 'weekly_reset_unknown',
+        reasons,
+        matchingRoutes,
+      };
+    }
+
     return {
       available: false,
       retryAfterMs: Infinity,
@@ -574,13 +591,41 @@ export class AccountManager {
     });
   }
 
-  registerQueuedRequest(requestInfo = {}) {
+  // Drop wedged head tickets (deadline passed or explicitly marked dead) so a
+  // single orphaned waiter cannot block every other request behind it. Cheap;
+  // safe to call before every head check.
+  _reapStaleQueueHead() {
+    const q = this.queueState;
+    const now = Date.now();
+    let guard = 0;
+    while (q.waiting.length && guard++ < 10_000) {
+      const head = q.waiting[0];
+      const stale = head.dead === true || (head.deadlineAt && now > head.deadlineAt);
+      if (!stale) break;
+      q.waiting.shift();
+      q.bytes = Math.max(0, q.bytes - (head.bytes || 0));
+    }
+  }
+
+  // Register a waiter. Returns the ticket, or null if a backpressure limit
+  // (maxConcurrentQueued / maxQueuedBytes) would be exceeded — the caller then
+  // rejects the request with a "queue full" error instead of holding it.
+  registerQueuedRequest(requestInfo = {}, opts = {}) {
     if (requestInfo.queueTicket) return requestInfo.queueTicket;
+    this._reapStaleQueueHead();
+    const bytes = Math.max(0, Number(opts.bytes) || 0);
+    const { maxConcurrentQueued, maxQueuedBytes } = opts;
+    if (maxConcurrentQueued != null && this.queueState.waiting.length >= maxConcurrentQueued) return null;
+    if (maxQueuedBytes != null && this.queueState.waiting.length > 0
+      && this.queueState.bytes + bytes > maxQueuedBytes) return null;
     const ticket = {
       id: this.queueState.nextId++,
       queuedAt: Date.now(),
+      bytes,
+      deadlineAt: opts.deadlineAt || null,
     };
     this.queueState.waiting.push(ticket);
+    this.queueState.bytes += bytes;
     requestInfo.queueTicket = ticket;
     return ticket;
   }
@@ -588,10 +633,12 @@ export class AccountManager {
   canAdmitQueuedRequest(requestInfo = {}) {
     const ticket = requestInfo.queueTicket;
     if (!ticket) return true;
+    this._reapStaleQueueHead();
     if (this.queueState.waiting[0]?.id !== ticket.id) return false;
     const now = Date.now();
     if (now < this.queueState.rampUntil && now - this.queueState.lastAdmissionAt < 250) return false;
     this.queueState.waiting.shift();
+    this.queueState.bytes = Math.max(0, this.queueState.bytes - (ticket.bytes || 0));
     this.queueState.lastAdmissionAt = now;
     requestInfo.queueTicket = null;
     requestInfo.queueAdmitted = true;
@@ -602,7 +649,10 @@ export class AccountManager {
     const ticket = requestInfo.queueTicket;
     if (!ticket) return;
     const index = this.queueState.waiting.findIndex(entry => entry.id === ticket.id);
-    if (index >= 0) this.queueState.waiting.splice(index, 1);
+    if (index >= 0) {
+      this.queueState.waiting.splice(index, 1);
+      this.queueState.bytes = Math.max(0, this.queueState.bytes - (ticket.bytes || 0));
+    }
     requestInfo.queueTicket = null;
   }
 

package/src/config.js

@@ -81,13 +81,20 @@ export function createDefaultConfig() {
     shutdown: {
       drainTimeoutMs: 15_000,
     },
+    // When every account is rate-limited, hold the request and retry until one
+    // frees up, instead of erroring and killing the session. Only error if
+    // nothing recovers within the window below (the early-exit gates on each
+    // account's REAL reset time, so a generous bound never spins pointlessly).
     queue: {
       enabled: true,
-      maxWaitMs: 24 * 60 * 60 * 1000,
-      autoMaxWaitMs: null,
-      capacityMaxWaitMs: 15 * 60 * 1000,
-      maxQueuedBodyBytes: 256 * 1024 * 1024,
-      weeklyMaxWaitMs: 0,
+      maxWaitMs: 24 * 60 * 60 * 1000,    // hard ceiling for any hold
+      autoMaxWaitMs: null,               // 5h/session-cap hold (null = maxWaitMs)
+      capacityMaxWaitMs: 15 * 60 * 1000, // upstream 529/overload — stays short, never governed by the others
+      weeklyMaxWaitMs: 24 * 60 * 60 * 1000, // weekly (7d) cap hold; was 0 (fail-fast) — that killed sessions on weekly cap
+      nonStreamMaxWaitMs: 5 * 60 * 1000, // non-streaming requests have no keepalive; cap their wait
+      maxConcurrentQueued: 64,           // backpressure: max requests held at once
+      maxQueuedBytes: 1024 * 1024 * 1024, // backpressure: max aggregate buffered body bytes (1 GiB)
+      maxQueuedBodyBytes: 256 * 1024 * 1024, // per-request cap on a queueable body
       pollMs: 1000,
       heartbeatMs: 10_000,
     },

package/src/server.js

@@ -19,7 +19,19 @@ const DEFAULT_QUEUE = {
   maxWaitMs: 24 * 60 * 60 * 1000,
   autoMaxWaitMs: null,
   capacityMaxWaitMs: 15 * 60 * 1000,
-  weeklyMaxWaitMs: 0,
+  // Weekly (7d) cap hold. A generous bound is SAFE because the early-exit
+  // gates on the REAL reset time (unified7dReset - now): it only waits when a
+  // reset genuinely lands inside the window, and errors honestly otherwise.
+  // 0 here was the bug — it fail-fast-killed sessions the instant every
+  // account hit its weekly cap, instead of waiting for the soonest reset.
+  weeklyMaxWaitMs: 24 * 60 * 60 * 1000,
+  // Non-streaming requests have no SSE heartbeat to keep them alive, so a long
+  // hold would die on the client timeout anyway. Cap their wait conservatively.
+  nonStreamMaxWaitMs: 5 * 60 * 1000,
+  // Backpressure: holds used to be 0ms, now they can be hours. Bound the queue
+  // so 22 retrying agents can't grow the heap without limit.
+  maxConcurrentQueued: 64,
+  maxQueuedBytes: 1024 * 1024 * 1024, // 1 GiB aggregate across all held bodies
   pollMs: 1000,
   heartbeatMs: 10_000,
 };
@@ -825,6 +837,14 @@ function hasEligibleRoute(accountManager, requestInfo = {}, excludedIndexes = ne
   return accountManager.hasAvailableRoute?.(requestInfo, excludedIndexes) || false;
 }
 
+function formatRetryDuration(seconds) {
+  const s = Math.max(0, Math.round(Number(seconds) || 0));
+  if (s >= 86400) return `${Math.round(s / 86400)}d`;
+  if (s >= 3600) return `${Math.round(s / 3600)}h`;
+  if (s >= 60) return `${Math.round(s / 60)}m`;
+  return `${s}s`;
+}
+
 function unavailableMessage(accountManager, requestInfo = {}, retryAfter, willRecoverSoon = true) {
   const thinking = requestInfo.requiresAnthropicThinkingIntegrity
     || accountManager._requiresAnthropicThinkingIntegrity?.(requestInfo);
@@ -834,7 +854,10 @@ function unavailableMessage(accountManager, requestInfo = {}, retryAfter, willRe
   // account is at its own 5h/weekly limit. A short "retry in Ns" would be a lie;
   // tell the user the real fix.
   if (!willRecoverSoon) {
-    const base = `No Claude account can take this request — all ${n} are at their 5h or weekly limit. Add another Claude account or wait for a quota reset.`;
+    const eta = Number.isFinite(retryAfter) && retryAfter > 0
+      ? ` Soonest reset in ~${formatRetryDuration(retryAfter)}, beyond the hold window.`
+      : '';
+    const base = `No Claude account can take this request — all ${n} are at their 5h or weekly limit.${eta} Add another Claude account or wait for a quota reset.`;
     return thinking
       ? `${base} GLM/Kimi fallback is unavailable because this session contains Anthropic signed thinking blocks; start a fresh non-thinking session to use them.`
       : base;
@@ -1062,29 +1085,64 @@ async function queueAndRetry(
     ? autoMaxWaitMs
     : Math.max(0, Number(queueConfig.capacityMaxWaitMs) || 0);
   const weeklyMaxWaitMs = Math.max(0, Number(queueConfig.weeklyMaxWaitMs) || 0);
+  const nonStreamMaxWaitMs = queueConfig.nonStreamMaxWaitMs == null
+    ? 5 * 60_000
+    : Math.max(0, Number(queueConfig.nonStreamMaxWaitMs) || 0);
   const retryPlan = accountManager.nextRetryForRequest?.(requestInfo, new Set()) || {
     retryAfterMs: Infinity,
     cause: 'unavailable',
   };
-  const queueWindowMs = retryPlan.cause === 'weekly_exhausted'
-    ? Math.min(maxWaitMs, weeklyMaxWaitMs)
-    : cause === 'capacity'
-      ? Math.min(maxWaitMs, capacityMaxWaitMs)
-    : Math.min(maxWaitMs, autoMaxWaitMs);
-  if (queueWindowMs <= 0) return finishQueuedStreamIfNeeded(res, requestInfo, 'No retry window is available.');
+
+  // Honest, cause-/thinking-aware message used for every give-up path below.
+  const honestMessage = unavailableMessage(
+    accountManager, requestInfo,
+    Math.ceil((Number.isFinite(retryPlan.retryAfterMs) ? retryPlan.retryAfterMs : 0) / 1000),
+    false,
+  );
+
+  // Weekly-capped but the reset time is unknown (cold start / probe failure):
+  // we can't estimate a wait, so don't pretend to — error honestly now.
+  if (retryPlan.cause === 'weekly_reset_unknown') {
+    return finishQueuedStreamIfNeeded(res, requestInfo, honestMessage);
+  }
+
+  // Pick the wait window. Capacity (upstream 529/overload) MUST stay on its own
+  // short cap even when it coincides with weekly exhaustion — never let a
+  // transient overload inherit the long weekly bound.
+  let queueWindowMs = cause === 'capacity'
+    ? Math.min(maxWaitMs, capacityMaxWaitMs)
+    : retryPlan.cause === 'weekly_exhausted'
+      ? Math.min(maxWaitMs, weeklyMaxWaitMs)
+      : Math.min(maxWaitMs, autoMaxWaitMs);
+  // Non-streaming requests have no SSE heartbeat, so a long hold would die on
+  // the client timeout. Cap them so we never promise a wait we can't deliver.
+  if (!requestInfo.stream) queueWindowMs = Math.min(queueWindowMs, nonStreamMaxWaitMs);
+
+  if (queueWindowMs <= 0) return finishQueuedStreamIfNeeded(res, requestInfo, honestMessage);
 
   const retryAfterMs = retryPlan.retryAfterMs;
   if (!Number.isFinite(retryAfterMs) || retryAfterMs > queueWindowMs) {
-    return finishQueuedStreamIfNeeded(res, requestInfo, 'No route is expected to recover within the configured queue window.');
+    return finishQueuedStreamIfNeeded(res, requestInfo, honestMessage);
   }
 
   requestInfo.queueStartedAt ||= Date.now();
-  accountManager.registerQueuedRequest?.(requestInfo);
+  const ticket = accountManager.registerQueuedRequest?.(requestInfo, {
+    bytes: body?.length || 0,
+    deadlineAt: requestInfo.queueStartedAt + queueWindowMs,
+    maxConcurrentQueued: queueConfig.maxConcurrentQueued,
+    maxQueuedBytes: queueConfig.maxQueuedBytes,
+  });
+  if (ticket === null) {
+    // Backpressure: too many requests already waiting / too many bytes buffered.
+    // Reject honestly instead of growing the heap unbounded.
+    return finishQueuedStreamIfNeeded(res, requestInfo,
+      'Maxpool queue is full — too many requests are already waiting for capacity. Try again shortly.');
+  }
   const elapsed = Date.now() - requestInfo.queueStartedAt;
   const remaining = queueWindowMs - elapsed;
   if (remaining <= 0) {
     accountManager.removeQueuedRequest?.(requestInfo);
-    return finishQueuedStreamIfNeeded(res, requestInfo, 'The Maxpool queue wait expired.');
+    return finishQueuedStreamIfNeeded(res, requestInfo, honestMessage);
   }
 
   ctx.account = '(queued)';
@@ -1096,7 +1154,7 @@ async function queueAndRetry(
   if (!available) {
     if (res.destroyed || req.destroyed) return true;
     accountManager.removeQueuedRequest?.(requestInfo);
-    return finishQueuedStreamIfNeeded(res, requestInfo, 'The Maxpool queue wait expired.');
+    return finishQueuedStreamIfNeeded(res, requestInfo, honestMessage);
   }
 
   return forwardRequest(
@@ -1163,7 +1221,10 @@ async function waitForAvailableRoute(req, res, accountManager, requestInfo, queu
       ) return true;
 
       const remaining = maxWaitMs - (Date.now() - startedAt);
-      await sleep(Math.min(pollMs, remaining));
+      // Jitter the poll so a synchronized weekly-reset event doesn't re-align
+      // every waiter's poll into the same instant (thundering scan).
+      const jittered = pollMs * (0.8 + Math.random() * 0.4);
+      await sleep(Math.min(jittered, remaining));
     }
 
     return accountManager.hasAvailableRoute(requestInfo, new Set())