maxpool 1.11.1 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.11.1",
+  "version": "1.13.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

@@ -161,6 +161,27 @@ const DEFAULT_SCHEDULER = {
   reserveConcurrencyTarget: 2,    // tighter in-flight cap for reserve (capPenalty bites at inflight>2 ⇒ load fans out
                                   // across the fleet before any single reserve account is dogpiled toward a 429)
   spreadShareWeight: 3,           // multiplies an account's share of recent fleet load (0..1)
+  // FAST-REFILL DISCOUNT (2026-08-25). The two LOAD-BALANCING terms — utilizationCost
+  // and paceCost — price a window by how FULL it is, never by how much absolute
+  // headroom it holds or how soon it refills. So "17% of a 5h window that refills 33.6x
+  // a week" is priced identically to "17% of a weekly window that refills once", and an
+  // account whose only cap is a fast-refilling session never pulls ahead of one guarding
+  // a scarce weekly budget. That is the whole reason the fleet's largest-capacity
+  // account sat at ~17% of fleet traffic (measured 2026-08-25) while four Claude
+  // accounts ran at weekly 1.0.
+  //
+  // The discount is a MULTIPLIER on those two terms only — never a flat bonus. A flat
+  // bonus would drive an idle account's total NEGATIVE (idle floor is concurrency×2 = 2),
+  // below the entire band structure that reserveFloorCost:5 / criticalPressureCost:21
+  // assume is non-negative. A multiplier in [0,1] cannot: it only ever REMOVES cost that
+  // is already there, so the total stays ≥ the concurrency floor and every safety term
+  // (concurrency, capPenalty, reserve, critical, ramp, failures) is untouched.
+  //
+  // It also DECAYS: at session util 0 the discount is full, and it is gone by
+  // fastRefillFadeUtil — so as the fast window fills, the account converges back to
+  // normal pricing and the fleet re-balances smoothly instead of flapping at a cliff.
+  fastRefillDiscount: 0.6,        // 0 = off (full cost), 0.6 = discount up to 60% of the two balancing terms
+  fastRefillFadeUtil: 0.65,       // discount reaches 0 at this session utilization (weeklySoftThreshold)
   recoveryRampWeight: 4,          // decaying penalty applied to a just-recovered account
   recoveryRampMs: 5 * 60_000,     // how long the post-recovery ramp lasts
   spreadWindowMs: 15 * 60_000,    // rolling window used to measure recent per-account load
@@ -250,6 +271,13 @@ const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
 const PERSISTED_QUOTA_FIELDS = [
   'unified5h', 'unified7d', 'unified5hReset', 'unified7dReset', 'unifiedStatus', 'scopedWeekly',
   'tokensLimit', 'tokensRemaining', 'requestsLimit', 'requestsRemaining', 'resetsAt',
+  // Plan identity, not a utilization: a successful probe's "no weekly window" is
+  // positive knowledge (2026-08-06). Without persisting it, every restart clears the
+  // 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',
+  'providerQuotaSource', 'lastProbeOkAt',
 ];
 
 function clampRetryAfterSeconds(value) {
@@ -1106,7 +1134,10 @@ export class AccountManager {
     // disappears (without this, OAuth cycles essentially never close: red-team 2026-08-22).
     if (q.unified5h != null && q.unified5hReset && now >= q.unified5hReset) {
       console.log(`[Maxpool] Account "${account.name}" session quota reset`);
-      this.capacity?.closeCycle?.(account.name, 'ses', q.unified5hReset, { resetAt: q.unified5hReset });
+      // TANK: q.unified5h is still the CLOSING window's fullness here — the nulls below
+      // come after. Snapshot into the cycle before the rollover wipes it.
+      this.capacity?.closeCycle?.(account.name, 'ses', q.unified5hReset,
+        { resetAt: q.unified5hReset, finalUtilization: q.unified5h });
       q.unified5h = null;
       q.unified5hReset = null;
       changed = true;
@@ -1114,7 +1145,8 @@ export class AccountManager {
     }
     if (q.unified7d != null && q.unified7dReset && now >= q.unified7dReset) {
       console.log(`[Maxpool] Account "${account.name}" weekly quota reset`);
-      this.capacity?.closeCycle?.(account.name, 'wk', q.unified7dReset, { resetAt: q.unified7dReset });
+      this.capacity?.closeCycle?.(account.name, 'wk', q.unified7dReset,
+        { resetAt: q.unified7dReset, finalUtilization: q.unified7d });
       q.unified7d = null;
       q.unified7dReset = null;
       q.unifiedStatus = null;
@@ -2487,7 +2519,11 @@ export class AccountManager {
 
     // Burn-pace COST only (demoted from the old dominant scarcity×6 term): a
     // soft de-preference of accounts burning ahead of an even pace. Never a bench.
-    const paceCost = this._accountScarcity(account, now) * this.scheduler.paceCostWeight;
+    // FAST-REFILL DISCOUNT: applied to the pace and utilization terms (and only
+    // those) for an account whose only cap is a fast-refilling session window —
+    // see the DEFAULT_SCHEDULER block for the full rationale.
+    const refillMult = this._fastRefillMultiplier(account);
+    const paceCost = this._accountScarcity(account, now) * this.scheduler.paceCostWeight * refillMult;
 
     // RAW utilization cost — direct, not pace-adjusted. The pace cost above discounts
     // by how far into the window you are, so an account at 80% with 2h left is only
@@ -2495,7 +2531,7 @@ export class AccountManager {
     // benching, but wrong for load balancing: an account at 80% should be clearly less
     // attractive than one at 10% even if both are "on pace". Measured 2026-08-10: cc at
     // 80% scored 52.30 vs glm at 10% at 52.15 — a 0.15 gap drowned by round-robin.
-    const utilizationCost = this._rawUtilization(account) * this.scheduler.utilizationWeight;
+    const utilizationCost = this._rawUtilization(account) * this.scheduler.utilizationWeight * refillMult;
 
     // Per-model weekly de-preference: an account whose scoped weekly for THIS
     // request's model (e.g. Fable) is high-but-not-exhausted is a poor pick for
@@ -2635,7 +2671,7 @@ export class AccountManager {
    *                  in-window) and criticalPeakUnlock is enabled. Default off.
    * Precedence prereset > pressure > peak: the cheaper drain wins.
    */
-  _criticalUnlock(account, requestInfo = {}, excludedIndexes = new Set(), pressureCache = null, now = Date.now()) {
+  _criticalUnlock(account, requestInfo = {}, excludedIndexes = new Set(), _pressureCache = null, now = Date.now()) {
     const state = this._weeklyRawState(account);
     if (state !== 'critical') return null;
 
@@ -2704,7 +2740,7 @@ export class AccountManager {
    *  - pressure/peak: a flat cost ABOVE reserve's attainable max, so critical is
    *    relief for a LOADED last route and never preempts an idle reserve.
    */
-  _criticalCost(account, now = Date.now(), unlock = null, weeklyState = this._weeklyRawState(account)) {
+  _criticalCost(account, _now = Date.now(), unlock = null, weeklyState = this._weeklyRawState(account)) {
     if (weeklyState !== 'critical') return 0;
     if (!unlock) return 0;
     if (unlock.reason === 'prereset') {
@@ -2722,6 +2758,39 @@ export class AccountManager {
     return this._criticalUnlock(account, { profile: 'claude' }, new Set(), null, now);
   }
 
+  /**
+   * FAST-REFILL MULTIPLIER — 1.0 (no change) or a discount in (0,1) for an account
+   * whose ONLY cap is a fast-refilling session window. The predicate is exactly the
+   * one the TUI already renders ("Wk none"): a provider whose quota poll succeeded
+   * and carried NO weekly window (positive knowledge the plan has none — measured
+   * 2026-08-06, z.ai `max` returns one TOKENS_LIMIT unit 3 = 5h and no unit-6 weekly).
+   *
+   * The discount is LINEARLY FADED to 0 by session utilization: full at 0%, gone at
+   * fastRefillFadeUtil. So the preference this grants decays as the window fills and
+   * the account converges back to normal pricing — no cliff, no flap. At util ≥ fade
+   * point the multiplier is exactly 1, making the term byte-identical to pre-2026-08-25
+   * behaviour by construction.
+   *
+   * Rationale (why a weeklyAbsent account at all): its window refills 33.6× per week
+   * vs a weekly window's 1×, so equal FULLNESS does not mean equal VALUE — capacity
+   * that expires unused every 5h is worth spending faster than capacity that guards a
+   * whole week. This is the use-it-or-lose-it principle _windowScarcity already applies
+   * WITHIN a window, extended across window KINDS. It is a discount on balancing terms
+   * only — never a flat bonus (a flat bonus drives the total negative, under the
+   * non-negative band structure reserveFloorCost/criticalPressureCost were calibrated
+   * against), and never on safety terms (concurrency, capPenalty, reserve, critical).
+   */
+  _fastRefillMultiplier(account) {
+    const disc = this.scheduler.fastRefillDiscount;
+    if (!(disc > 0)) return 1;                       // feature off → multiplier 1
+    if (!(account?.type === 'provider' && account.quota?.weeklyAbsent)) return 1;
+    const fade = this.scheduler.fastRefillFadeUtil;
+    const ses = clamp01(account.quota.providerSes ?? 0);
+    if (ses >= fade) return 1;
+    // 1 at ses=0 → 1-disc at ses=0; linear to 1 at ses=fade
+    return 1 - disc * (1 - ses / Math.max(1e-6, fade));
+  }
+
   _reserveCost(account, now = Date.now(), weeklyState = this._weeklyRawState(account)) {
     if (weeklyState !== 'reserve') return 0;
     const q = account.quota;
@@ -2850,10 +2919,14 @@ export class AccountManager {
     const account = this.accounts[accountIndex];
     if (!account || !usage) return;
     const q = account.quota;
-    // CAPACITY LEDGER: prev stamps, so a probe observing the window ADVANCE closes
-    // the old cycle (the OAuth twin of the applyProviderUsage hook).
+    // CAPACITY LEDGER: prev stamps AND prev utilizations, so a probe observing the
+    // window ADVANCE closes the old cycle with the OLD window's tank reading —
+    // snapshot BEFORE the writes below clobber the fields with the new window's
+    // values (the OAuth twin of the applyProviderUsage hook).
     const prevSesReset = q.unified5hReset;
     const prevWkReset = q.unified7dReset;
+    const prevSesUtil = q.unified5h;
+    const prevWkUtil = q.unified7d;
 
     if (usage.fiveHour) {
       if (usage.fiveHour.utilization != null) q.unified5h = clamp01(usage.fiveHour.utilization);
@@ -2863,8 +2936,8 @@ export class AccountManager {
       if (usage.sevenDay.utilization != null) q.unified7d = clamp01(usage.sevenDay.utilization);
       if (usage.sevenDay.resetAt != null) q.unified7dReset = usage.sevenDay.resetAt;
     }
-    this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.fiveHour?.resetAt);
-    this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.sevenDay?.resetAt);
+    this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.fiveHour?.resetAt, prevSesUtil);
+    this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.sevenDay?.resetAt, prevWkUtil);
     // Utilization readings feed the capacity ESTIMATE. The probe path passes per-window
     // marks so the DELTA method can difference consecutive readings.
     this.capacity.noteUtilizationObserved(Date.now(), [
@@ -2981,11 +3054,14 @@ export class AccountManager {
     const account = this.accounts[accountIndex];
     if (!account || !usage) return;
     const q = account.quota;
-    // CAPACITY LEDGER: snapshot the previous reset stamps so a probe observing the
-    // window ADVANCE (new stamp) closes the capacity cycle at the old boundary —
-    // covers windows whose old stamp was never learned (clock-close can't fire).
+    // CAPACITY LEDGER: snapshot the previous reset stamps AND utilizations so a probe
+    // observing the window ADVANCE (new stamp) closes the capacity cycle at the old
+    // boundary WITH the old window's tank reading — covers windows whose old stamp
+    // was never learned (clock-close can't fire). Snapshot before the writes below.
     const prevSesReset = q.providerSesReset;
     const prevWkReset = q.providerWkReset;
+    const prevSesUtil = q.providerSes;
+    const prevWkUtil = q.providerWk;
     if (usage.error) {
       // Distinguish "no pollable quota" (Kimi) from a transient probe failure.
       // Never clear existing values on a transient error — let them age into the
@@ -3013,8 +3089,8 @@ export class AccountManager {
       q.weeklyAbsent = true;
     }
     q.lastProbeOkAt = Date.now();
-    this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.ses?.resetAt);
-    this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.wk?.resetAt);
+    this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.ses?.resetAt, prevSesUtil);
+    this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.wk?.resetAt, prevWkUtil);
     this.capacity.noteUtilizationObserved(Date.now(), [
       { name: account.name, window: 'ses', utilization: usage.ses?.utilization },
       { name: account.name, window: 'wk', utilization: usage.wk?.utilization },
@@ -3212,6 +3288,24 @@ export class AccountManager {
     return this.capacity.estimateFromUtilization(a.name, window, util) || null;
   }
 
+  /** Measured TANK for an account+window: capacity, not delivery. Prefers completed
+   *  cycles (tokens ÷ closing utilization, averaged); falls back to the live open
+   *  window's estimate so a row is useful from minute one instead of reading
+   *  "no completed cycle yet" while the vendor is plainly reporting a percentage. */
+  capacityTank(accountIndex, window) {
+    const a = this.accounts[accountIndex];
+    if (!a) return null;
+    const measured = this.capacity.tankStats(a.name, window);
+    if (measured) return { ...measured, source: 'cycles' };
+    const est = this.capacityEstimate(accountIndex, window);
+    if (!est) return null;
+    return {
+      avg: est.tokens, last: est.tokens, n: 0, exact: est.lowerBound ? 0 : 1,
+      bounded: est.lowerBound ? 1 : 0, lowerBound: Boolean(est.lowerBound),
+      source: 'live', utilization: est.utilization, method: est.method, fresh: est.fresh,
+    };
+  }
+
   accrueCapacity(accountIndex, { input = 0, output = 0 } = {}) {
     const account = this.accounts[accountIndex];
     if (!account) return;
@@ -3224,6 +3318,18 @@ export class AccountManager {
     this.capacity.accrue(account.name, { input, output }, undefined, windows);
   }
 
+  /** The vendor's CURRENT fullness reading for a window — the tank numerator's
+   *  denominator. Returns null when unreadable (a null reading divides nothing and
+   *  must never coerce to 0, which would make tank = Infinity). */
+  _windowUtilization(account, window) {
+    const q = account?.quota;
+    if (!q) return null;
+    const v = account.type === 'provider'
+      ? (window === 'wk' ? q.providerWk : q.providerSes)
+      : (window === 'wk' ? q.unified7d : q.unified5h);
+    return Number.isFinite(v) && v >= 0 ? v : null;
+  }
+
   /** Close any window cycle whose reset time has passed — CLOCK-AUTHORITATIVE, so a
    *  stale or dead probe can never leave a cycle open and mis-attribute the next
    *  window's tokens to it (pre-mortem M5; worst case is the no-weekly account whose
@@ -3267,7 +3373,14 @@ export class AccountManager {
         // here as well (round-2) made a prober-first notice silently swallow all of
         // those whenever the sweep won the race (red-team round 3, RT3-1).
         if (resetAt && now >= resetAt) {
-          this.capacity.closeCycle(a.name, win, resetAt, { resetAt });
+          this.capacity.closeCycle(a.name, win, resetAt, {
+            resetAt,
+            // TANK: the vendor's own fullness for the window we are closing. Read it
+            // BEFORE _clearExpiredQuotas nulls it — this sweep runs first by design
+            // (see the close-only note above), which is exactly why the reading is
+            // still the CLOSING window's and not the new one's.
+            finalUtilization: this._windowUtilization(a, win),
+          });
         }
       }
     }
@@ -3275,7 +3388,7 @@ export class AccountManager {
 
   /** Close a cycle because a probe observed the window ADVANCE (a new reset stamp) —
    *  covers the case where the old stamp was never learned. */
-  noteCapacityWindowAdvance(accountName, window, prevResetAt, nextResetAt) {
+  noteCapacityWindowAdvance(accountName, window, prevResetAt, nextResetAt, prevUtilization = null) {
     if (!prevResetAt || !nextResetAt) return;
     // TWO guards, both learned from live data (2026-08-23):
     // 1. PAST stamp = a probe that answered late (its window rolled mid-request) or
@@ -3296,7 +3409,15 @@ export class AccountManager {
     // expired) — endedAt is always within [start, now].
     const boundary = Math.min(nextResetAt, nowMs);
     if (boundary - prevResetAt < WINDOW_ADVANCE_EPSILON_MS) return;
-    this.capacity.closeCycle(accountName, window, boundary, { resetAt: prevResetAt });
+    // TANK: the CLOSING window's own fullness, passed in by the caller. It must be the
+    // caller's SNAPSHOT, never a re-read here: both probe paths write the new window's
+    // utilization into the quota fields before calling us, so re-reading would divide
+    // the old window's tokens by the NEW window's percentage — a silently wrong tank
+    // on exactly the rollover this path exists to catch.
+    this.capacity.closeCycle(accountName, window, boundary, {
+      resetAt: prevResetAt,
+      finalUtilization: Number.isFinite(prevUtilization) && prevUtilization >= 0 ? prevUtilization : null,
+    });
   }
 
   /**
@@ -3974,6 +4095,22 @@ export class AccountManager {
         safetyMaxActivePerAccount: this.scheduler.safetyMaxActivePerAccount,
         safetyMaxGlobalActive: this.scheduler.safetyMaxGlobalActive,
         peak: this.peakSummary(),
+        // FAST-REFILL visibility (2026-08-25): monitors must be able to assert the
+        // discount is ARMED (config > 0) and, per eligible account, the multiplier
+        // actually being applied — a flag that can never show "inert" is not a
+        // monitorable feature. Mirrors the peak block's shape.
+        fastRefill: {
+          enabled: this.scheduler.fastRefillDiscount > 0,
+          discount: this.scheduler.fastRefillDiscount,
+          fadeUtil: this.scheduler.fastRefillFadeUtil,
+          accounts: this.accounts
+            .filter(a => a.type === 'provider' && a.quota?.weeklyAbsent)
+            .map(a => ({
+              name: a.name,
+              sesUtilization: clamp01(a.quota.providerSes ?? 0),
+              multiplier: Number(this._fastRefillMultiplier(a).toFixed(3)),
+            })),
+        },
       },
       upstreamThrottle: {
         active: this._isUpstreamThrottleBlocking(),

package/src/capacity-ledger.js

@@ -199,8 +199,15 @@ export class CapacityLedger {
 
   /** Close the open cycle for a window (M5: clock-authoritative — the close is keyed
    *  on `endedAt`, which the caller derives from the reset stamp or the clock, and the
-   *  cycle keeps its own book regardless of probe health). No-op if none open. */
-  closeCycle(name, window, endedAt = this._now(), { resetAt = null } = {}) {
+   *  cycle keeps its own book regardless of probe health). No-op if none open.
+   *
+   *  TANK (2026-08-25, owner-directed): the closed row records `finalUtilization` —
+   *  the vendor's own fullness reading for the window at close. tank = tokens ÷ util
+   *  is the CAPACITY of the plan, as distinct from the tokens we happened to deliver.
+   *  Delivery measures demand; tank measures the plan. Both are recorded; the UI
+   *  decides which to show. Recording happens on a best-effort basis here (the ledger
+   *  keeps its own book — the caller passes the reading in, it does not poll). */
+  closeCycle(name, window, endedAt = this._now(), { resetAt = null, finalUtilization = null } = {}) {
     const rec = this._accounts.get(name);
     if (!rec || !rec[window]?.open) return null;
     const open = rec[window].open;
@@ -221,7 +228,10 @@ export class CapacityLedger {
       // Fold ONLY a complete tail: folding a partial/disabled tail would flip the
       // flags on the prior legitimate observation and ERASE it from the averages
       // (round 3, RT3-2) — strictly worse than leaving a tiny excluded cycle.
+      // The fold ALSO takes the tail's tank reading if the prior row lacks one —
+      // same boundary, same window, so the later reading is simply fresher.
       prev.tokens += open.tokensSoFar;
+      if (prev.finalUtilization == null && finalUtilization != null) prev.finalUtilization = finalUtilization;
       rec[window].open = null;
       return prev;
     }
@@ -232,6 +242,12 @@ export class CapacityLedger {
       complete: open.complete,
       disabledDuring: open.disabledDuring,
       ...(open.partialReason ? { partialReason: open.partialReason } : {}),
+      ...(finalUtilization != null ? { finalUtilization } : {}),
+      // Carried onto the closed row because tankStats needs it: a cycle observed from
+      // its window START yields an EXACT tank; one we joined late yields a lower bound
+      // (we only counted the tokens that flowed through maxpool, while the vendor's
+      // percentage counts everything). Dropping it here made every tank read "bounded".
+      ...(open.windowStartedAt != null ? { windowStartedAt: open.windowStartedAt } : {}),
       resetAt,
     });
     if (rec[window].closed.length > MAX_CYCLES_PER_WINDOW) rec[window].closed.shift();
@@ -366,6 +382,48 @@ export class CapacityLedger {
    *  ABSENCE (present in dayKeys, absent from days) — and with MAX_DAY_BUCKETS=10 an
    *  idle day no longer even evicts; only real activity ages out. `partial` is true
    *  when any bucket in the window is flagged partial — the figure is ≤ observed. */
+  /** TANK STATS — the CAPACITY of the plan, from the owner's own formula:
+   *  tank = tokens delivered ÷ utilization at close, per cycle, averaged across
+   *  cycles (2026-08-25, owner-directed). This measures the plan, not the demand:
+   *  a cycle that delivered 812k at 96% and one that delivered 51k at 6% both say
+   *  "~846k tank". Delivered-only averages (windowStats) measure demand and stay
+   *  available separately.
+   *
+   *  Guards, because the raw formula lies in two ways:
+   *  - We only count tokens that flowed THROUGH maxpool; a cycle whose vendor util
+   *    includes spend we never saw (joined mid-window, or usage outside the proxy)
+   *    yields a tank ≥ the truth but not equal to it. Only a cycle observed from its
+   *    window start is exact; later ones are marked `lowerBound`.
+   *  - Vendors report whole percents. At 3% full, 1pp of rounding = 33% error, so a
+   *    reading below MIN_UTIL is excluded (rounding-dominated) rather than folded
+   *    into the average as fake precision.
+   *  Returns { avg, exact, n, bounded, last } or null when no usable readings. */
+  tankStats(name, window) {
+    const rec = this._accounts.get(name);
+    const floor = (this._readFloorOverride ?? READ_FLOOR_MS)[window] ?? 0;
+    const usable = (rec?.[window]?.closed || []).filter(c =>
+      c.complete && !c.disabledDuring
+      && Number.isFinite(c.finalUtilization)
+      && c.finalUtilization >= 0.05
+      && (c.endedAt - c.startedAt) >= floor - 1_000);
+    if (!usable.length) return null;
+    let sum = 0, exact = 0, bounded = 0;
+    for (const c of usable) {
+      const observedFromStart = c.startedAt != null && c.windowStartedAt != null
+        && c.startedAt <= c.windowStartedAt + 60_000;
+      sum += c.tokens / c.finalUtilization;
+      if (observedFromStart) exact++; else bounded++;
+    }
+    const last = usable[usable.length - 1];
+    return {
+      avg: Math.round(sum / usable.length),
+      exact, bounded,
+      n: usable.length,
+      last: Math.round(last.tokens / last.finalUtilization),
+      lowerBound: bounded > 0 && exact === 0,
+    };
+  }
+
   rollingThroughput(name, days = 7) {
     const rec = this._accounts.get(name);
     if (!rec) return { tokens: 0, partial: false };

package/src/tui.js

@@ -1961,6 +1961,13 @@ export class TUI {
         if (tier === 2) note += `  ${yellow(`peak·capped ${Math.round((wu ?? 0) * 100)}%`)}`;
         else if (tier === 1) note += wu == null ? `  ${dim('peak·cap n/a')}` : `  ${yellow('peak')}`;
       }
+      // FAST-REFILL tag (2026-08-25): mirrors the router's own _fastRefillMultiplier —
+      // the label cannot disagree with routing because it reads the same predicate.
+      // Only shown when a discount is actually applied (< 1).
+      if (a.quota?.weeklyAbsent && this.am._fastRefillMultiplier) {
+        const m = this.am._fastRefillMultiplier(a);
+        if (m < 1) note += `  ${cyan(`fast·refill ×${m.toFixed(2)}`)}`;
+      }
     } else if (q.providerQuotaSource === 'console-only') {
       sesCell = emptyBar('n/a', bw);
       wkCell = emptyBar('n/a', bw);
@@ -2024,7 +2031,7 @@ export class TUI {
     const ledger = this.am.capacity;
     const title = win === 'wk' ? 'Weekly (7d) capacity' : 'Session (5h) capacity';
     out.push('');
-    out.push(` ${bold(title)}  ${dim('— tokens delivered per completed cycle, per account')}`);
+    out.push(` ${bold(title)}  ${dim('— how many tokens each account can deliver per window')}`);
     out.push('');
 
     if (!ledger) { out.push(yellow('  Capacity ledger unavailable on this worker.')); return out; }
@@ -2032,15 +2039,19 @@ export class TUI {
     // Narrow terminals: drop trailing columns rather than let fitLine chop a number
     // mid-digit (at W=80 the full 6-column row is 82+ chars — every row silently lost
     // its last two cells). The dropped ones are the aggregates, not the observations.
-    const ALL_COLS = ['Last', 'Prev', 'Prev-1', 'Avg 3', 'Avg 10', 'All time'];
-    const CW = 9;
+    // CAPACITY (tank) is the headline: tokens ÷ the vendor's own fullness at close,
+    // per cycle. That measures the PLAN. The delivered-token columns measure DEMAND —
+    // useful, but they were the headline before 2026-08-25 and read as capacity, which
+    // is why an account that simply went unused looked small.
+    const ALL_COLS = ['Capacity', 'Used now', 'Last cyc', 'Avg cyc'];
+    const CW = 10;
     const nameW = 12;
     let COLS = ALL_COLS;
-    while (COLS.length > 1 && (nameW + PROVIDER_W + 2 + COLS.length * CW + 14) > W) {
+    while (COLS.length > 1 && (nameW + PROVIDER_W + 2 + COLS.length * CW + 16) > W) {
       COLS = COLS.slice(0, -1);
     }
     const header = '  ' + 'Account'.padEnd(nameW) + ' ' + 'Provider'.padEnd(PROVIDER_W) + ' '
-      + COLS.map(c => c.padStart(CW)).join('') + '  Cycles';
+      + COLS.map(c => c.padStart(CW)).join('') + '  Basis';
     out.push(dimUnderline(fitLine(header, W)));
 
     let anyData = false;
@@ -2058,14 +2069,16 @@ export class TUI {
         // capacity). 33.6 five-hour windows fit in 7 days — the user's own
         // approximation ("from the session limits"), shipped as a ceiling, never a cap.
         const t = ledger.rollingThroughput(a.name, 7);
-        const ses = ledger.windowStats(a.name, 'ses');
         const windowsPerWk = (7 * 24) / 5;
         anyData = anyData || t.tokens > 0;
         const vol = t.tokens > 0 ? formatTokens(t.tokens) : '--';
-        // The ceiling needs a measured session capacity; without one it would multiply
-        // a guess — show the volume alone rather than fabricate the headline.
-        const ceiling = ses ? ` · ≈${formatTokens(Math.round(windowsPerWk * ses.avg10))}/wk ceiling`
-                          + dim(` (${windowsPerWk.toFixed(0)} sessions × ${formatTokens(ses.avg10)})`) : '';
+        // The ceiling needs a measured session TANK (capacity, not avg delivery) —
+        // multiplying an old avg-delivery number understates a demand-limited account.
+        const sesTank = this.am.capacityTank?.(i, 'ses');
+        const ceiling = sesTank
+          ? ` · ≈${formatTokens(Math.round(windowsPerWk * sesTank.avg))}/wk ceiling`
+            + dim(` (${windowsPerWk.toFixed(0)} × ${formatTokens(sesTank.avg)} per 5h)`)
+          : '';
         // Always disclose the window's age boundary: today is unfinished, so the 7d
         // figure grows through the day; a genuinely partial day adds the ≤-observed floor.
         const note = t.partial
@@ -2076,54 +2089,60 @@ export class TUI {
         continue;
       }
       const st = ledger.windowStats(a.name, win);
-      if (!st) {
-        // No completed cycle yet — but the vendor's own fullness reading still yields
-        // an ESTIMATE (tokens seen ÷ utilization): useful from minute one, honest about
-        // being an estimate. `~` marks it; a measured column replaces it after the first
-        // full window. A stale-util caveat only when we cannot prove same-window.
-        const est = this.am.capacityEstimate?.(i, win);
-        // LIVE now-column: the open cycle is the only number that moves between window
-        // closes, and without it the page read as frozen (reported 2026-08-25: "they
-        // don't seem to be updating at all"). Rendered on every row that has one.
-        const nowOpen = ledger.openCycle(a.name, win);
-        const nowTag = nowOpen && nowOpen.tokensSoFar > 0
-          ? ' ' + yellow(`▸ ${formatTokens(nowOpen.tokensSoFar)} this window`) : '';
-        if (est) {
-          anyData = true;
-          const caveat = est.fresh ? '' : ' (utilization reading may be from the previous window)';
-          // ≥ = absolute method on a window we joined late: the true tank is at least
-          // this. No ≥ when the delta method fired — it is join-independent, or the
-          // window was observed from its start.
-          const op = est.lowerBound ? '≥' : '~';
-          const via = est.method === 'delta'
-            ? `Δ ${(est.utilization * 100).toFixed(0)}% full` : `${(est.utilization * 100).toFixed(0)}% full`;
-          out.push('  ' + name + ' ' + prov + ' ' + cyan(op + formatTokens(est.tokens).padStart(CW - 1))
-            + dim(` est from ${via}${caveat} — measured after this window completes`) + nowTag);
-        } else {
-          out.push('  ' + name + ' ' + prov + ' ' + dim('no completed cycle yet') + nowTag);
-        }
+      let tank = this.am.capacityTank?.(i, win);
+      const nowOpen = ledger.openCycle(a.name, win);
+      const util = this.am._windowUtilization?.(a, win);
+      // A reading we cannot prove is from THIS window must not badge the capacity
+      // number as "live" — it may describe the previous window entirely (the estimate
+      // still renders; the basis line just stops claiming freshness it can't prove).
+      if (tank?.source === 'live' && tank.fresh === false) tank = null;
+
+      // A row with NEITHER a tank nor any delivery has genuinely nothing to say. Say
+      // WHY in the account's own terms — "no completed cycle yet" was true and useless
+      // (reported 2026-08-25: an account sitting at 99% weekly rendered that line).
+      if (!tank && !st && !(nowOpen?.tokensSoFar > 0)) {
+        const why = util == null
+          ? 'no quota reading from this provider'
+          : util > 0
+            ? `${(util * 100).toFixed(0)}% used, but no traffic through maxpool to measure with`
+            : 'window empty — nothing used yet';
+        out.push('  ' + name + ' ' + prov + ' ' + dim(why));
         continue;
       }
       anyData = true;
-      const all = { Last: st.last, Prev: st.prev, 'Prev-1': st.prev1, 'Avg 3': st.avg3, 'Avg 10': st.avg10, 'All time': st.allTime };
-      const cells = COLS.map(c => formatTokens(all[c]).padStart(CW)).join('');
-      const nowOpen = ledger.openCycle(a.name, win);
-      const nowTag = nowOpen && nowOpen.tokensSoFar > 0
-        ? ' ' + yellow(`▸ ${formatTokens(nowOpen.tokensSoFar)}`) : '';
-      out.push('  ' + name + ' ' + prov + ' ' + cells + '  ' + dim(String(st.cycles)) + nowTag);
+
+      // Capacity: measured tank, or the live in-window estimate. `~` = estimate from an
+      // open window; `≥` = we joined the window late, so the vendor's percentage counts
+      // spend maxpool never saw and the true tank is at least this.
+      const capCell = tank
+        ? (tank.lowerBound ? '≥' : tank.source === 'live' ? '~' : ' ') + formatTokens(tank.avg)
+        : '--';
+      const usedNow = nowOpen?.tokensSoFar > 0 ? formatTokens(nowOpen.tokensSoFar) : '--';
+      const cellsByName = {
+        Capacity: capCell,
+        'Used now': usedNow,
+        'Last cyc': st ? formatTokens(st.last) : '--',
+        'Avg cyc': st ? formatTokens(st.avg10) : '--',
+      };
+      const cells = COLS.map(c => cellsByName[c].padStart(CW)).join('');
+
+      // Basis: how the capacity number was arrived at, in one short phrase. Never a
+      // bare count — "3" told the reader nothing about what it was counting.
+      const basis = !tank ? dim('no capacity reading yet')
+        : tank.source === 'cycles'
+          ? dim(`${tank.n} full ${tank.n === 1 ? 'window' : 'windows'}`)
+          : dim(`live · ${((tank.utilization ?? 0) * 100).toFixed(0)}% used`);
+      const pct = util != null && tank?.source !== 'live' ? dim(` (${(util * 100).toFixed(0)}% full now)`) : '';
+      out.push('  ' + name + ' ' + prov + ' ' + cyan(cells) + '  ' + basis + pct);
     }
 
     out.push('');
     if (!anyData) {
-      // Fresh install: the page is honest about WHY it is empty and WHEN it fills,
-      // instead of showing zeros that read like an account delivering nothing.
-      out.push(' ' + yellow('No completed cycles yet.') + dim(
-        win === 'wk'
-          ? ' A weekly figure appears after an account\'s 7d window resets once.'
-          : ' A session figure appears after an account\'s 5h window resets once.'));
-    }
-    out.push(' ' + dim('A cycle counts only if maxpool ran for all of it and the account stayed enabled.'));
-    out.push(' ' + dim('~ = estimated; ≥ = at least; Δ = exact-by-difference; ≈/wk = session-rate ceiling; ▸ = live this window.'));
+      out.push(' ' + yellow('Nothing to measure yet.')
+        + dim(' Capacity needs traffic through maxpool plus a quota reading from the provider.'));
+    }
+    out.push(' ' + dim('Capacity = tokens delivered ÷ how full the provider said the window was.'));
+    out.push(' ' + dim('~ = from the window still running · ≥ = at least this (maxpool joined the window late).'));
     return out;
   }