maxpool 1.12.0 → 1.13.1

package/package.json

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

@@ -1,5 +1,5 @@
 import { refreshAccessToken, isTokenExpiringSoon, modelFamily, tokenFingerprint } from './oauth.js';
-import { CapacityLedger } from './capacity-ledger.js';
+import { CapacityLedger, TANK_MIN_UTIL } from './capacity-ledger.js';
 
 // Nominal window length per kind — mirrors capacity-ledger's WINDOW_MS (kept here as a
 // local table so account-manager does not import a private constant).
@@ -1134,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;
@@ -1142,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;
@@ -2667,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;
 
@@ -2736,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') {
@@ -2915,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);
@@ -2928,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(), [
@@ -3046,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
@@ -3078,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 },
@@ -3277,6 +3288,28 @@ 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;
+    // Same rounding-noise guard as tankStats: a 1%-full window divides by vendor
+    // whole-percent rounding and can read absurd (measured live: 455k ÷ 1% = "≥45M").
+    // Below the floor the reading is noise — withhold rather than print a fiction.
+    if (est.utilization < TANK_MIN_UTIL) 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;
@@ -3289,6 +3322,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
@@ -3332,7 +3377,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),
+          });
         }
       }
     }
@@ -3340,7 +3392,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
@@ -3361,7 +3413,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,
+    });
   }
 
   /**

package/src/capacity-ledger.js

@@ -35,6 +35,14 @@ const SAME_BOUNDARY_MS = 5_000;
 // The minimum span of a COMPLETE cycle per window (80% of nominal): a real one is
 // flagged partial by the writer, so a complete cycle below this is corrupt history.
 const READ_FLOOR_MS = { ses: 4 * 3600_000, wk: 5 * 86400_000 };
+
+// TANK floor. tank = tokens ÷ utilization, and vendors report WHOLE percents — so at
+// 1% full, one percentage point of rounding swings the answer by 100% (measured live
+// 2026-08-25: a 1%-full window read "≥45M"). Below this the reading is rounding noise,
+// not a measurement. Exported because BOTH the closed-cycle average and the live
+// in-window estimate must apply the same floor; one guarding without the other is how
+// the absurd number reached the screen in the first place.
+export const TANK_MIN_UTIL = 0.05;
 const MAX_CYCLES_PER_WINDOW = 50;
 const MAX_DAY_BUCKETS = 10;
 
@@ -199,8 +207,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 +236,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 +250,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 +390,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 >= TANK_MIN_UTIL
+      && (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

@@ -2031,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; }
@@ -2039,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;
@@ -2065,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
@@ -2083,54 +2089,61 @@ 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);
-        }
+      const 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 may describe the previous one —
+      // the basis line says "unproven" instead of "live", but the number still renders:
+      // a restored reading after a restart is real data, and suppressing it would blank
+      // the page at exactly the moment the user opens it.
+      const unproven = tank?.source === 'live' && tank.fresh === false;
+
+      // 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(`${unproven ? 'from an older reading' : '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;
   }