maxpool 1.21.4 → 1.22.1

package/package.json

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

@@ -68,6 +68,16 @@ function emptyQuota() {
     // Provider (z.ai / Kimi) quota — kept SEPARATE from unified* so a provider
     // reading never leaks into the OAuth quota gates (_isAvailable / _weeklyRawState
     // / _accountScarcity read unified* only). z.ai is pollable; Kimi is not.
+    // Largest "time until reset" ever OBSERVED for each window, i.e. a lower bound on
+    // the window's true length. The dynamic cap needs a duration to know how far into a
+    // window it is, and the nominal 5h/7d table is an assumption about the VENDOR: a
+    // provider whose "weekly" is really 3 days would sit part-way up the ramp from the
+    // moment the window is born. Learning the span from observation fixes that, and the
+    // error direction of an UNDER-estimate (seen only late in a window) is conservative —
+    // it reports less elapsed, so the cap stays nearer its floor. Grows monotonically and
+    // self-corrects the first time a fresh window is seen.
+    capSpanSes: null,
+    capSpanWk: null,
     providerSes: null,          // utilization 0-1 (z.ai 5h token window)
     providerSesReset: null,     // ms
     providerWk: null,           // utilization 0-1 (z.ai weekly), null if plan has none
@@ -141,6 +151,11 @@ const DEFAULT_SCHEDULER = {
   // ACTIVE (_peakTier ≥ 1). Default OFF — mechanism shipped, immediate use declined.
   criticalPeakUnlock: false,
   weeklyBurnDebtWeight: 0.6,
+  // DYNAMIC CAP: the fraction of a quota window that elapses before a dynamic cap
+  // starts lifting off its floor. 0.5 holds the owner's full reserve through the first
+  // half of every window, then opens it up over the second half — so the reserve is
+  // protected while there is still time to use it, and spent when there is not.
+  capRampStart: 0.5,
   // Routing-cost tuning (lower cost = preferred). The goal is to AVOID
   // short-term (rate/concurrency) throttling by spreading load across healthy
   // accounts. So in-flight concurrency is the DOMINANT term, with a steep
@@ -289,7 +304,7 @@ const PERSISTED_QUOTA_FIELDS = [
   // flag and the fast-refill discount (plus the TUI "Wk none" rendering) silently
   // drops until the next probe sweep re-learns it. The probe still rewrites it on
   // every successful sweep, so a plan change heals on the same cadence.
-  'weeklyAbsent', 'providerSes', 'providerSesReset', 'providerWk', 'providerWkReset',
+  'weeklyAbsent', 'capSpanSes', 'capSpanWk', 'providerSes', 'providerSesReset', 'providerWk', 'providerWkReset',
   'providerQuotaSource', 'lastProbeOkAt',
 ];
 
@@ -344,14 +359,70 @@ function parseResetHeader(value) {
  * also logs once so a hand-edited config doesn't silently fail open (a NaN cap makes
  * every `util >= cap` comparison false = uncapped, with no error anywhere).
  */
-function _sanitizeCap(value, name) {
+function _sanitizeCap(value, name, quiet = false) {
   if (value == null) return null;
   const n = Number(value);
   if (Number.isFinite(n) && n > 0 && n < 1) return n;
-  console.log(`[Maxpool] Ignoring invalid capUtilization ${JSON.stringify(value)} for "${name}" — expected 0-1`);
+  // `quiet` is for the second call that only resolves the MODE from the same value —
+  // it would otherwise print the identical complaint twice per account per load.
+  if (!quiet) console.log(`[Maxpool] Ignoring invalid capUtilization ${JSON.stringify(value)} for "${name}" — expected 0-1`);
   return null;
 }
 
+/**
+ * The cap MODE for an account. Only meaningful when a cap is set. 'fixed' must be
+ * asked for EXPLICITLY; everything else (absent, unknown string) resolves to
+ * 'dynamic' — the owner's directive that the dynamic cap "become the new default for
+ * the accounts that currently have the fixed cap", which is exactly the config shape
+ * with a `capUtilization` and no `capMode`.
+ */
+/** A cap ramp start is a fraction of the window in [0,1); anything else means "use the
+ *  default". 1 or more would mean "never ramp", which is what `capMode:'fixed'` says
+ *  properly, so it is rejected here rather than silently creating a second way to say it. */
+function _sanitizeRampStart(value, name) {
+  if (value == null) return null;
+  const n = Number(value);
+  if (Number.isFinite(n) && n >= 0 && n < 1) return n;
+  console.log(`[Maxpool] Ignoring invalid capRampStart ${JSON.stringify(value)} for "${name}" — expected 0 to <1 (use capMode:"fixed" for no ramp)`);
+  return null;
+}
+
+function _capMode(value, sanitizedCap, name) {
+  if (sanitizedCap == null) return null;
+  if (value === 'fixed' || value === 'dynamic') return value;
+  // Absent is the migration case and is silent BY DESIGN — every pre-2026-09-24 config
+  // has a cap and no mode, and the owner asked for those to become dynamic. A value that
+  // is present but unrecognised is a typo, and swallowing it silently would be the same
+  // fail-open-without-a-word shape _sanitizeCap exists to prevent for the number.
+  if (value != null) {
+    console.log(`[Maxpool] Ignoring unknown capMode ${JSON.stringify(value)} for "${name}" — expected "fixed" or "dynamic"; using dynamic`);
+  }
+  return 'dynamic';
+}
+
+/**
+ * How far into a quota window we are, 0-1, from its reset stamp. Returns null when the
+ * stamp is unusable (absent / non-finite) so every caller can fail CLOSED rather than
+ * inventing a position in a window it cannot see. A stamp in the past clamps to 1
+ * (window over) and one further out than a nominal window clamps to 0 — both are real
+ * states around a rollover, and neither may produce a NaN.
+ */
+function _windowElapsedRatio(resetAt, durationMs, now) {
+  if (!Number.isFinite(resetAt) || !Number.isFinite(durationMs) || durationMs <= 0) return null;
+  // A stamp in the PAST means the window already rolled and we have not yet learned the
+  // new one — so our POSITION in the live window is unknown, and the utilization we hold
+  // belongs to the window that closed. Treating that as "fully elapsed" would ramp the cap
+  // to its ceiling on stale data: reproduced on a provider account (providerWk 0.55, stamp
+  // 3 days past) reading `normal` where the fixed cap says `capped`, and provider stamps
+  // are never cleared by _clearExpiredQuotas, so a probe outage holds that state open
+  // indefinitely. Unknown position must fail CLOSED to the floor, like a missing stamp.
+  if (resetAt <= now) return null;
+  // `resetAt > now` is guaranteed above and `durationMs > 0`, so the ratio cannot exceed
+  // 1; only the LOW side needs bounding, for a stamp further out than one nominal window
+  // (a vendor window longer than we assume) which must read as "window just started".
+  return Math.max(0, (durationMs - (resetAt - now)) / durationMs);
+}
+
 export class AccountManager {
   constructor(accounts, switchThreshold = 0.90, schedulerOptions = {}, dependencies = {}) {
     this.scheduler = { ...DEFAULT_SCHEDULER, ...schedulerOptions };
@@ -388,6 +459,18 @@ export class AccountManager {
       // to null HERE, visibly (below), so a hand-edited "50" or "abc" in the config
       // can never fail the >= comparisons open as NaN.
       capUtilization: _sanitizeCap(acct.capUtilization, acct.name),
+      // CAP MODE (owner-directed 2026-09-24). 'dynamic' is the DEFAULT for any account
+      // that carries a cap: the value above becomes a FLOOR, and the effective cap ramps
+      // toward switchThreshold as the window nears its reset, so reserved-but-unused
+      // capacity is spent instead of dying at reset. `capMode:'fixed'` opts back in to the
+      // constant cap. Uncapped accounts carry no mode (nothing to modulate).
+      capMode: _capMode(acct.capMode, _sanitizeCap(acct.capUtilization, acct.name, true), acct.name),
+      // Per-account overrides for the two numbers that decide how much reserve is kept
+      // and for how long. Defaults live in DEFAULT_SCHEDULER; these exist because the
+      // right answer is the OWNER's (how much of their own account to hold back, and
+      // from when), not a constant buried in the scheduler.
+      capCeiling: _sanitizeCap(acct.capCeiling, acct.name, true),
+      capRampStart: _sanitizeRampStart(acct.capRampStart, acct.name),
       model: acct.model || null,
       modelMap: acct.modelMap || null,
       stripBetaHeaders: Boolean(acct.stripBetaHeaders),
@@ -869,11 +952,15 @@ export class AccountManager {
     if (account.inFlight >= this.scheduler.safetyMaxActivePerAccount) return false;
     if (this.getGlobalInFlight() >= this.scheduler.safetyMaxGlobalActive) return false;
     if (account.status === 'exhausted' || account.status === 'error') return false;
-    if (this._isSessionQuotaUnavailable(account)) return false;
+    // `now` is threaded deliberately: under a DYNAMIC cap the bench threshold moves with
+    // the clock, so an availability decision and the retry oracle that explains it must
+    // read the same instant. The drift is milliseconds today, but it is always in the
+    // direction that manufactures a spurious 'capped' verdict, and nothing else enforces it.
+    if (this._isSessionQuotaUnavailable(account, now)) return false;
     // Gate on RAW weekly usage, not pace-adjusted: an account with real
     // headroom (e.g. 69% used, resets in days) must stay in the healthy-spread
     // pool even if it's burning fast. Pace is a soft SCORE cost, never a bench.
-    const weeklyState = this._weeklyRawState(account);
+    const weeklyState = this._weeklyRawState(account, now);
     if (weeklyState === 'exhausted' || weeklyState === 'capped') return false;
     if (weeklyState === 'critical' && !options.allowWeeklyCritical) return false;
     if (weeklyState === 'reserve' && !options.allowWeeklyReserve) return false;
@@ -1310,21 +1397,125 @@ export class AccountManager {
    * oracle can never desync from the bench (a capped-benched account MUST report a
    * finite retry time or a live session holding on it gets error-fasted).
    */
-  _sessionBenchThreshold(account) {
-    const cap = account?.capUtilization;
+  _sessionBenchThreshold(account, now = Date.now()) {
+    const cap = this._effectiveCap(account, 'ses', now);
     return (cap != null && cap < this.switchThreshold) ? cap : this.switchThreshold;
   }
 
+  /**
+   * The reset stamp + nominal duration of one quota window on this account. OAuth
+   * accounts carry `unified*`; providers carry `provider*` (the two never mix — see
+   * the note on emptyQuota). An account type with no reset stamp for the window
+   * (API-key) yields a null stamp, which the caller treats as "cannot ramp".
+   */
+  /** Record the largest remaining-time seen for a window — see capSpanSes/capSpanWk. */
+  _noteCapWindowSpan(account, window, resetAt, now = Date.now()) {
+    if (!Number.isFinite(resetAt)) return;
+    const remaining = resetAt - now;
+    if (!(remaining > 0)) return;
+    const key = window === 'ses' ? 'capSpanSes' : 'capSpanWk';
+    const q = account.quota;
+    const nominal = WINDOW_MS_BY_KIND[window];
+    // Never learn a span LONGER than nominal: that direction would push the cap up the
+    // ramp on an assumption, which is the fail-open side.
+    const bounded = Math.min(remaining, nominal);
+    if (q[key] == null || bounded > q[key]) q[key] = bounded;
+  }
+
+  _capWindowFields(account, window) {
+    const q = account?.quota || {};
+    const learned = window === 'ses' ? q.capSpanSes : q.capSpanWk;
+    // Prefer the observed span over the nominal assumption; both are bounded above by
+    // nominal, so this can only ever move the cap DOWN toward its floor.
+    const durationMs = Number.isFinite(learned) && learned > 0
+      ? Math.min(learned, WINDOW_MS_BY_KIND[window])
+      : WINDOW_MS_BY_KIND[window];
+    if (account?.type === 'provider') {
+      return { resetAt: window === 'ses' ? q.providerSesReset : q.providerWkReset, durationMs };
+    }
+    return { resetAt: window === 'ses' ? q.unified5hReset : q.unified7dReset, durationMs };
+  }
+
+  /**
+   * The cap THIS account is actually held to on THIS window RIGHT NOW.
+   *
+   *   fixed mode / no reset stamp  -> the configured value, unchanged
+   *   dynamic mode                 -> floor early in the window, ramping to the
+   *                                   ceiling (switchThreshold) as the reset nears
+   *
+   * The ceiling is switchThreshold and never 1.0, deliberately: the owner asked for a
+   * cap that "always preserves some meaningful room for usage of those accounts outside
+   * of MaxPool". A fully-ramped dynamic account therefore behaves exactly like an
+   * UNCAPPED one — never more aggressively — so this mechanism can only ever make an
+   * account MORE available than the fixed cap it replaces (pinned by T3c). That
+   * one-directionality is why it is not a live-session control surface.
+   *
+   * Fails CLOSED in every uncertain case (no stamp, unusable duration): an unknown
+   * window position returns the floor, never an opened-up cap.
+   */
+  _effectiveCap(account, window = 'wk', now = Date.now()) {
+    const floor = account?.capUtilization;
+    if (floor == null) return null;                       // uncapped — unchanged
+    if (account.capMode !== 'dynamic') return floor;      // fixed — byte-for-byte as before
+    const ceiling = account.capCeiling ?? this.switchThreshold;
+    if (floor >= ceiling) return floor;                   // never pull a high floor DOWN
+    const { resetAt, durationMs } = this._capWindowFields(account, window);
+    const elapsed = _windowElapsedRatio(resetAt, durationMs, now);
+    if (elapsed == null) return floor;                    // fail closed
+    const rampStart = account.capRampStart ?? this.scheduler.capRampStart;
+    const ramp = rampStart >= 1 ? 0 : clamp01((elapsed - rampStart) / (1 - rampStart));
+    return floor + (ceiling - floor) * ramp;
+  }
+
+  /**
+   * When a DYNAMIC cap will have risen far enough to stop benching `utilization` on
+   * this window — i.e. the instant the ramp crosses it. Null when that never happens
+   * before the reset (utilization at/above the ceiling), when the cap is fixed, or
+   * when the window position is unknown; the caller then falls back to the reset.
+   *
+   * Without this the cap's hold is keyed to the window RESET, which is correct for a
+   * fixed cap (only a reset unbenches it) and systematically too long for a rising one:
+   * util 0.85 on a 0.50-floor weekly with 20h left is routable in 15h, but the oracle
+   * would have told the client to wait the full 20h — an over-hold that lands exactly
+   * in this feature's own target regime (near reset). Linear in elapsed, so invert it.
+   */
+  _capUnbenchAt(account, utilization, window = 'wk', now = Date.now()) {
+    if (account?.capMode !== 'dynamic' || utilization == null) return null;
+    const floor = account.capUtilization;
+    const ceiling = account.capCeiling ?? this.switchThreshold;
+    if (floor == null || floor >= ceiling) return null;
+    if (utilization >= ceiling) return null;              // the ramp never reaches it
+    if (utilization < floor) return null;                 // not cap-benched at all
+    const { resetAt, durationMs } = this._capWindowFields(account, window);
+    if (_windowElapsedRatio(resetAt, durationMs, now) == null) return null;
+    const rampStart = account.capRampStart ?? this.scheduler.capRampStart;
+    if (rampStart >= 1) return null;
+    // effective(t) = floor + (ceiling-floor) * (elapsed(t) - rampStart)/(1 - rampStart)
+    // solve effective(t) = utilization for elapsed, then convert back to wall clock.
+    const neededRamp = (utilization - floor) / (ceiling - floor);
+    const neededElapsed = rampStart + neededRamp * (1 - rampStart);
+    const at = resetAt - durationMs * (1 - neededElapsed);
+    if (!Number.isFinite(at)) return null;
+    // Never report a time outside (now, reset]: a crossing already behind us means the
+    // account is not actually benched, and one past the reset is the reset's own case.
+    if (at <= now) return null;
+    // No upper bound needed: at = reset - duration*(1 - neededElapsed), and neededElapsed
+    // exceeds 1 only when utilization exceeds the ceiling, which returned null above. A
+    // `Math.min(at, resetAt)` here was dead defensive code — a brute-force sweep over
+    // span x remaining x utilization found the crossing never once landed past the reset.
+    return at;
+  }
+
   /** True when the account's usage cap has it benched on the given window reading. */
-  _capped(account, utilization) {
-    const cap = account?.capUtilization;
+  _capped(account, utilization, window = 'wk', now = Date.now()) {
+    const cap = this._effectiveCap(account, window, now);
     return cap != null && utilization != null && utilization >= cap;
   }
 
-  _isSessionQuotaUnavailable(account) {
+  _isSessionQuotaUnavailable(account, now = Date.now()) {
     const q = account.quota;
     this._clearExpiredQuotas(account);
-    const bench = this._sessionBenchThreshold(account);
+    const bench = this._sessionBenchThreshold(account, now);
 
     // Unified 5h quota is immediate availability. Weekly quota is handled
     // separately as long-horizon admission control.
@@ -1646,9 +1837,17 @@ export class AccountManager {
       // nextRetryForRequest → retryAfterMs: Infinity → server.js error-fasts → the
       // live session is KILLED, despite the real reset time being known all along.
       // Reproduced 2026-08-18 with providerWk=0.9995 + a known providerWkReset.
+      // A DYNAMIC cap unbenches on its own ramp, BEFORE the reset — so hold until the
+      // crossing, not the window end. `weeklyState === 'capped'` is the only case where
+      // that applies; a genuinely exhausted account still waits for the reset.
+      const wkReset = q.unified7dReset || q.providerWkReset || null;
+      const wkUtil = account.type === 'provider' ? q.providerWk : q.unified7d;
+      const capCrossing = weeklyState === 'capped'
+        ? this._capUnbenchAt(account, wkUtil, 'wk', now)
+        : null;
       return {
         cause: 'weekly_exhausted',
-        retryAt: q.unified7dReset || q.providerWkReset || null,
+        retryAt: capCrossing ?? wkReset,
         queueable: false,
       };
     }
@@ -1733,7 +1932,7 @@ export class AccountManager {
     // _isSessionQuotaUnavailable (_sessionBenchThreshold) — a capped account benched
     // at 50% MUST report a finite retryAt here or a live session holding on it gets
     // error-fasted instead of waiting out the window (red-team blocker 2).
-    const bench = this._sessionBenchThreshold(account);
+    const bench = this._sessionBenchThreshold(account, now);
     if (account.status === 'throttled' && account.rateLimitedUntil && now < account.rateLimitedUntil) {
       return { cause: 'rate_limited', retryAt: account.rateLimitedUntil, queueable: true };
     }
@@ -2951,7 +3150,7 @@ export class AccountManager {
       || (Number.isFinite(q.unified7d) && q.unified7d >= floor);
   }
 
-  _weeklyRawState(account) {
+  _weeklyRawState(account, now = Date.now()) {
     const q = account.quota;
     this._clearExpiredQuotas(account);
     if (this._isAccountWideRejected(account)) return 'exhausted';
@@ -2968,7 +3167,7 @@ export class AccountManager {
       // and outranks both the tier ladder and the upstream verdict. There is no
       // upstreamAllows carve-out for providers anyway, but the ordering documents
       // that a cap can never be talked out of by the vendor's "allowed".
-      if (this._capped(account, used)) return 'capped';
+      if (this._capped(account, used, 'wk', now)) return 'capped';
       if (used >= this.scheduler.weeklyExhaustedThreshold) return 'exhausted';
       if (used >= this.scheduler.weeklyCriticalThreshold) return 'critical';
       if (used >= this.scheduler.weeklyReserveThreshold) return 'reserve';
@@ -2994,7 +3193,7 @@ export class AccountManager {
     // right through the cap — the override exists for genuine over-limit-but-allowed
     // states and would otherwise make the cap a no-op on exactly the account it is
     // for (measured: this exact shape sat at unified7d=1.00 'allowed_warning').
-    if (this._capped(account, used)) return 'capped';
+    if (this._capped(account, used, 'wk', now)) return 'capped';
     const upstreamAllows = typeof q.unifiedStatus === 'string' && q.unifiedStatus.startsWith('allowed');
     if (used >= this.scheduler.weeklyExhaustedThreshold && !upstreamAllows) return 'exhausted';
     if (used >= this.scheduler.weeklyCriticalThreshold) return 'critical';
@@ -3003,9 +3202,9 @@ export class AccountManager {
     return 'normal';
   }
 
-  _weeklyPaceState(account) {
+  _weeklyPaceState(account, now = Date.now()) {
     // Provider quota lives in separate fields — see _weeklyRawState.
-    if (account.type === 'provider') return this._weeklyRawState(account);
+    if (account.type === 'provider') return this._weeklyRawState(account, now);
     if (account.quota.unified7d == null) return 'unknown';
     const effective = this._effectiveWeeklyUsage(account);
     if (effective >= this.scheduler.weeklyExhaustedThreshold) return 'exhausted';
@@ -3047,11 +3246,17 @@ export class AccountManager {
 
     if (usage.fiveHour) {
       if (usage.fiveHour.utilization != null) q.unified5h = clamp01(usage.fiveHour.utilization);
-      if (usage.fiveHour.resetAt != null) q.unified5hReset = usage.fiveHour.resetAt;
+      if (usage.fiveHour.resetAt != null) {
+        q.unified5hReset = usage.fiveHour.resetAt;
+        this._noteCapWindowSpan(account, 'ses', usage.fiveHour.resetAt);
+      }
     }
     if (usage.sevenDay) {
       if (usage.sevenDay.utilization != null) q.unified7d = clamp01(usage.sevenDay.utilization);
-      if (usage.sevenDay.resetAt != null) q.unified7dReset = usage.sevenDay.resetAt;
+      if (usage.sevenDay.resetAt != null) {
+        q.unified7dReset = usage.sevenDay.resetAt;
+        this._noteCapWindowSpan(account, 'wk', usage.sevenDay.resetAt);
+      }
     }
     this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.fiveHour?.resetAt, prevSesUtil);
     this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.sevenDay?.resetAt, prevWkUtil);
@@ -3202,11 +3407,17 @@ export class AccountManager {
     q.providerQuotaSource = usage.source || 'zai';
     if (usage.ses) {
       if (usage.ses.utilization != null) q.providerSes = clamp01(usage.ses.utilization);
-      if (usage.ses.resetAt != null) q.providerSesReset = usage.ses.resetAt;
+      if (usage.ses.resetAt != null) {
+        q.providerSesReset = usage.ses.resetAt;
+        this._noteCapWindowSpan(account, 'ses', usage.ses.resetAt);
+      }
     }
     if (usage.wk) {
       if (usage.wk.utilization != null) q.providerWk = clamp01(usage.wk.utilization);
-      if (usage.wk.resetAt != null) q.providerWkReset = usage.wk.resetAt;
+      if (usage.wk.resetAt != null) {
+        q.providerWkReset = usage.wk.resetAt;
+        this._noteCapWindowSpan(account, 'wk', usage.wk.resetAt);
+      }
       q.weeklyAbsent = false;
     } else {
       // Weekly window absent from this plan/response — clear so a stale weekly
@@ -3880,6 +4091,9 @@ export class AccountManager {
       configSourced: Boolean(acctData.configSourced),
       secretName: acctData.secretName || null,
       capUtilization: _sanitizeCap(acctData.capUtilization, acctData.name),
+      capMode: _capMode(acctData.capMode, _sanitizeCap(acctData.capUtilization, acctData.name, true), acctData.name),
+      capCeiling: _sanitizeCap(acctData.capCeiling, acctData.name, true),
+      capRampStart: _sanitizeRampStart(acctData.capRampStart, acctData.name),
       enabled: acctData.enabled !== false,
       refreshToken: acctData.refreshToken || null,
       expiresAt: acctData.expiresAt || null,
@@ -3945,6 +4159,7 @@ export class AccountManager {
     // cap the user set in the TUI.
     if (acctData.capUtilization !== undefined) {
       account.capUtilization = _sanitizeCap(acctData.capUtilization, account.name);
+      account.capMode = _capMode(acctData.capMode ?? account.capMode, account.capUtilization, account.name);
     }
     if (account.status === 'error' && changed) {
       account.status = 'active';
@@ -3986,6 +4201,11 @@ export class AccountManager {
         // And the usage cap, same reasoning: a TUI-set reservation must survive both
         // the restart AND the next `cc all` header re-send (the upsert guard).
         capUtilization: a.capUtilization ?? null,
+        capMode: a.capMode ?? null,
+        capEffective: a.capUtilization == null ? null : {
+          ses: this._effectiveCap(a, 'ses'),
+          wk: this._effectiveCap(a, 'wk'),
+        },
       }));
   }
 
@@ -4199,6 +4419,11 @@ export class AccountManager {
         profiles: a.profiles,
         priority: a.priority,
         capUtilization: a.capUtilization ?? null,
+        capMode: a.capMode ?? null,
+        capEffective: a.capUtilization == null ? null : {
+          ses: this._effectiveCap(a, 'ses'),
+          wk: this._effectiveCap(a, 'wk'),
+        },
         runtime: a.runtime,
         status: a.status,
         refreshDead: Boolean(a.refreshDead),

package/src/index.js

@@ -2113,9 +2113,15 @@ async function syncAccountsFromDisk(diskConfig, memConfig, accountManager) {
     // this a config-edit cap is stale until the next full reload).
     const diskCap = Number.isFinite(diskAcct.capUtilization) && diskAcct.capUtilization > 0 && diskAcct.capUtilization < 1
       ? diskAcct.capUtilization : null;
-    if (mgr.capUtilization !== diskCap) {
+    // The MODE rides along with the cap: a hand-edited config that adds/changes a cap
+    // without naming a mode gets the dynamic default, exactly as a fresh load would —
+    // otherwise a hot edit would silently produce a capped account with no mode, whose
+    // effective cap is the floor forever (a fixed cap wearing the new feature's name).
+    const diskMode = diskCap == null ? null : (diskAcct.capMode === 'fixed' ? 'fixed' : 'dynamic');
+    if (mgr.capUtilization !== diskCap || mgr.capMode !== diskMode) {
       mgr.capUtilization = diskCap;
-      console.log(`[Maxpool] Usage cap for "${mgr.name}" ${diskCap ? `set to ${Math.round(diskCap * 100)}%` : 'removed'} from config`);
+      mgr.capMode = diskMode;
+      console.log(`[Maxpool] Usage cap for "${mgr.name}" ${diskCap ? `set to ${Math.round(diskCap * 100)}% (${diskMode})` : 'removed'} from config`);
     }
     memConfig.accounts[memIdx] = { ...memConfig.accounts[memIdx], ...diskAcct };
 

package/src/tui.js

@@ -202,12 +202,42 @@ function loadText(load) {
  *  built for (max@gomokka.com) showed no cap anywhere: reported 2026-08-27, "I need
  *  to be able to see whether an account has a cap or not." Yellow while the cap is
  *  actively holding traffic back, dim otherwise. */
-function capText(a, benched) {
+function capText(a, benched, am) {
   if (a?.capUtilization == null) return '';
-  const t = `cap ${Math.round(a.capUtilization * 100)}%`;
+  const floorPct = Math.round(a.capUtilization * 100);
+  // DYNAMIC CAP (2026-09-24): the configured value is only a FLOOR — what routing
+  // actually holds the account to right now is the ramped effective cap, which climbs
+  // as the window nears its reset. Showing the floor alone would state a number the
+  // scheduler is not using. `cap 50%>67%` reads as "reserved 50%, currently allowing
+  // 67%"; the two collapse to one number while the cap sits at its floor, so an
+  // early-window dynamic account looks exactly like the fixed one it replaced.
+  // The WINDOW is named, not just the number. `cap 50%>75%` alone is ambiguous in the
+  // way that matters for the decision the row exists to support ("is it safe for me to
+  // use this account myself right now?"): a lift driven by the 5h window means reduced
+  // protection for minutes, the same number off the weekly means DAYS of it. Council
+  // finding 2026-09-24.
+  const eff = capEffectivePct(am, a);
+  const t = (eff != null && eff.pct !== floorPct)
+    ? `cap ${floorPct}%>${eff.pct}% ${eff.window}`
+    : `cap ${floorPct}%`;
   return benched ? yellow(t) : dim(t);
 }
 
+/** What routing is ACTUALLY enforcing on this account right now: the worse (lower) of
+ *  its two windows' effective caps — the one that benches first — AND WHICH window that
+ *  is. Returns {pct, window:'5h'|'wk'} or null for a fixed cap / when the manager cannot
+ *  compute one. The window label is load-bearing: the same percentage means "protection
+ *  is thin for the next few minutes" off the 5h window and "thin for days" off the weekly. */
+function capEffectivePct(am, a) {
+  if (!am?._effectiveCap || a?.capMode !== 'dynamic') return null;
+  const vals = [['ses', '5h'], ['wk', 'wk']]
+    .map(([w, label]) => ({ v: am._effectiveCap(a, w), window: label }))
+    .filter(e => typeof e.v === 'number' && Number.isFinite(e.v));
+  if (!vals.length) return null;
+  const worst = vals.reduce((lo, e) => (e.v < lo.v ? e : lo));
+  return { pct: Math.round(worst.v * 100), window: worst.window };
+}
+
 /** PER-ACCOUNT SETTINGS the user set by hand — the last column's whole job
  *  (owner, 2026-08-27: "the last column should contain any and all settings that
  *  are custom per account"). Fleet-wide settings (routing mode, peak policy) stay
@@ -223,7 +253,7 @@ function settingsTags(am, a) {
   if (am?.routingMode === 'preferred' && a?.name === am.preferredAccountName) {
     tags.push(cyan('preferred'));
   }
-  const capTag = capText(a, capBenched(am, a));
+  const capTag = capText(a, capBenched(am, a), am);
   if (capTag) tags.push(capTag);
   return tags;
 }
@@ -236,7 +266,10 @@ function capBenched(am, a) {
   const q = a.quota || {};
   const ses = a.type === 'provider' ? q.providerSes : q.unified5h;
   const wk = a.type === 'provider' ? q.providerWk : q.unified7d;
-  return !!(am?._capped?.(a, ses) || am?._capped?.(a, wk));
+  // Each reading is judged against ITS OWN window's cap — under the dynamic cap the
+  // two differ (a 5h window nearly over is lifted while the weekly is still at its
+  // floor), so passing the default window for both would mislabel one of them.
+  return !!(am?._capped?.(a, ses, 'ses') || am?._capped?.(a, wk, 'wk'));
 }
 
 export function weeklyPolicyText(am, account) {
@@ -246,7 +279,10 @@ export function weeklyPolicyText(am, account) {
   // exhausted, it's deliberately held, and labelling it "Wk exhausted 50%" (red team)
   // while the bar shows half-full misstates the owner's own setting.
   if (state === 'capped') {
-    return yellow(`Cap ${Math.round((account.capUtilization || 0) * 100)}%`);
+    // The WEEKLY window's own effective cap — the number that actually benched it.
+    const eff = am._effectiveCap?.(account, 'wk');
+    const pct = Math.round((Number.isFinite(eff) ? eff : account.capUtilization || 0) * 100);
+    return yellow(`Cap ${pct}%`);
   }
   if (!state || state === 'unknown' || state === 'normal') return '';
   // SAY IT ONCE (2026-08-27). An account Anthropic is rejecting outright already
@@ -353,7 +389,7 @@ export function applyProviderEnabledToConfig(config, name, enabled) {
   return { changed: true, previous };
 }
 
-export const __tuiTest = { applyProviderEnabledToConfig, formatReset, quotaLabel, bar, emptyBar, strip, loadText, countdown, acctHeader, fitLine, providerLabel };
+export const __tuiTest = { applyProviderEnabledToConfig, formatReset, quotaLabel, bar, emptyBar, strip, loadText, countdown, acctHeader, fitLine, providerLabel, weeklyPolicyText, capText, capEffectivePct };
 
 function timestamp() {
   return new Date().toLocaleTimeString('en-US', { hour12: false });
@@ -1166,9 +1202,14 @@ export class TUI {
       } else if (this.selAction === 'cap') {
         const targetIdx = this.selIdx;
         const current = account.name;
-        const existing = this.am.accounts[targetIdx]?.capUtilization;
+        const existingAcct = this.am.accounts[targetIdx];
+        const existing = existingAcct?.capUtilization;
+        const existingMode = existingAcct?.capMode;
+        const nowLabel = existing
+          ? `${Math.round(existing * 100)}%${existingMode === 'dynamic' ? ' dynamic' : ' fixed'}`
+          : 'off';
         this.mode = 'input';
-        this.inputPrompt = `Usage cap % for "${current}" (1-99, 0 = off, now ${existing ? Math.round(existing * 100) + '%' : 'off'})`;
+        this.inputPrompt = `Usage cap for "${current}" — NN = dynamic floor (rises near reset), fNN = fixed, 0 = off, now ${nowLabel}`;
         this.inputBuf = '';
         this.inputSensitive = false;
         this.inputCb = value => this._doSetCap(targetIdx, String(value || '').trim());
@@ -1359,35 +1400,50 @@ export class TUI {
     if (!account) { this._addLog('Account no longer exists'); return; }
     const v = String(raw || '').trim().toLowerCase();
     const off = v === '' || v === '0' || v === 'off' || v === '100';
+    // MODE PREFIX/SUFFIX: a bare number means the DYNAMIC cap (the default since
+    // 2026-09-24 — the floor that lifts as the window nears reset); `f` marks the
+    // fixed cap explicitly. `d` is accepted as the explicit dynamic spelling so the
+    // two modes are symmetric to type.
+    const explicitFixed = /^f/.test(v) || /f$/.test(v);
     let pct = null;
     if (!off) {
-      pct = parseInt(v, 10);
+      const digits = v.replace(/[fd]/g, '');
+      pct = parseInt(digits, 10);
       if (!Number.isInteger(pct) || pct < 1 || pct > 99) {
-        this._addLog(`Usage cap must be 1-99 (or 0 to remove) — got "${raw}"`);
+        this._addLog(`Usage cap must be 1-99, optionally f-prefixed for fixed (0 to remove) — got "${raw}"`);
         return;
       }
     }
     const cap = off ? null : pct / 100;
+    const mode = cap == null ? null : (explicitFixed ? 'fixed' : 'dynamic');
 
     const loc = this._configLocation(account);
     if (loc) {
       const prev = this.config[loc.array][loc.index].capUtilization ?? null;
+      const prevMode = this.config[loc.array][loc.index].capMode ?? null;
       if (cap == null) delete this.config[loc.array][loc.index].capUtilization;
       else this.config[loc.array][loc.index].capUtilization = cap;
+      if (mode == null) delete this.config[loc.array][loc.index].capMode;
+      else this.config[loc.array][loc.index].capMode = mode;
       try {
         await this.saveConfig(this.config);
       } catch (error) {
         // rollback both config and (below) skip the live apply
         if (prev == null) delete this.config[loc.array][loc.index].capUtilization;
         else this.config[loc.array][loc.index].capUtilization = prev;
+        if (prevMode == null) delete this.config[loc.array][loc.index].capMode;
+        else this.config[loc.array][loc.index].capMode = prevMode;
         throw error;
       }
     }
     // No loc: a runtime provider — in-memory + state.json persistence (same as enabled).
     account.capUtilization = cap;
+    account.capMode = mode;
     this._addLog(cap == null
       ? `Usage cap removed for "${account.name}" — fully utilized`
-      : `Usage cap ${pct}% set for "${account.name}" — the proxy stops routing to it at ${pct}% of the 5h and weekly windows`);
+      : mode === 'dynamic'
+        ? `Dynamic cap ${pct}% set for "${account.name}" — it keeps ${100 - pct}% free early in each window, then opens up as the window nears its reset so nothing is stranded`
+        : `Fixed cap ${pct}% set for "${account.name}" — the proxy stops routing to it at ${pct}% of the 5h and weekly windows`);
   }
 
   async _doRename(idx, newName) {