maxpool 1.23.0 → 1.24.0

package/package.json

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

@@ -3423,6 +3423,33 @@ export class AccountManager {
    * (never the unified or scopedWeekly fields) so a provider reading can't reach
    * the OAuth quota gates.
    */
+  /** Store the latest Claude reset-grant listing (prober piggyback). */
+  applyResetGrants(accountIndex, listing) {
+    const account = this.accounts[accountIndex];
+    if (!account || !listing) return;
+    if (listing.error) { account.resetGrants = null; return; }
+    account.resetGrants = {
+      grants: listing.grants || [],
+      nextGrantId: listing.nextGrantId ?? null,
+      cooldownUntil: listing.cooldownUntil ?? null,
+      eligible: listing.eligible !== false,
+      checkedAt: Date.now(),
+    };
+  }
+
+  /** Store the latest reset-card listing for an account (prober piggyback).
+   *  Cards are display/decision state only — routing never reads them. */
+  applyResetCards(accountIndex, cards) {
+    const account = this.accounts[accountIndex];
+    if (!account || !cards) return;
+    if (cards.error) { account.resetCards = null; return; }   // never half-write
+    account.resetCards = {
+      fiveHour: cards.fiveHour || [],
+      weekly: cards.weekly || [],
+      checkedAt: Date.now(),
+    };
+  }
+
   applyProviderUsage(accountIndex, usage) {
     const account = this.accounts[accountIndex];
     if (!account || !usage) return;

package/src/claude-reset-grants.js

@@ -0,0 +1,146 @@
+/**
+ * Claude banked usage-limit resets (internal program `cedar_ember`; the
+ * session-only 1/week program is `juniper_tide` — deliberately NOT auto-claimed
+ * here: it costs a scarce weekly slot for the least valuable window).
+ *
+ * Endpoints (same shape Claude Code itself uses; verified against the 2.1.285
+ * binary and third-party implementations, 2026-09-30):
+ *   GET  /api/oauth/usage?cedar_ember=1&skip_spend=1
+ *        -> cedar_ember: { eligible, ineligible_reason, grants: [...],
+ *           next_grant_id, cooldown_until, weekly_resets_at }
+ *        Grant: { id, resets_total, resets_left, starts_at, ends_at, usable_now,
+ *                 paused, use_requires_limit }
+ *   GET  /api/oauth/profile -> organization uuids (organizations[].uuid)
+ *   POST /api/organizations/{org}/reset_rate_limits
+ *        { program:'cedar_ember', grant_id, request_id }
+ *
+ * CRITICAL: without a Claude Code User-Agent the usage endpoint answers
+ * eligible:false, ineligible_reason:"surface" for EVERY token — the grants exist
+ * but are invisible. Mirror the CLI's UA exactly.
+ *
+ * Envelope: claim returns HTTP 200 with success:false on failure; `already_used`
+ * counts as success (idempotent) — request_id is the client's idempotency key.
+ */
+import { randomUUID } from 'node:crypto';
+
+const USAGE_BASE = 'https://api.anthropic.com/api/oauth/usage';
+const PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
+const CLAIM_PATH = '/api/organizations';
+
+function cliUserAgent() {
+  // Match the installed CLI's version so server-side cli_version gating treats us
+  // like the real client. Falls back to a known-good recent version.
+  const v = process.env.MAXPOOL_CLAUDE_CLI_VERSION || '2.1.285';
+  return `claude-cli/${v} (external, cli)`;
+}
+
+function headers(accessToken) {
+  return {
+    'Authorization': `Bearer ${accessToken}`,
+    'User-Agent': cliUserAgent(),
+    'Accept': 'application/json',
+  };
+}
+
+/** Parse an ISO/epoch-ish timestamp into ms, or null. */
+function toMs(v) {
+  if (v == null) return null;
+  if (typeof v === 'number') return v > 1e12 ? v : v * 1e3;   // s vs ms heuristics
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : null;
+}
+
+/** Normalize a cedar_ember grant. Drops malformed entries (the CLI does the same:
+ *  "ignoring a malformed grant"). Keeps expired ones OUT unless resets remain and
+ *  ends_at is still ahead — expired grants are display-only noise. */
+export function normalizeGrant(raw, now = Date.now()) {
+  if (!raw || typeof raw !== 'object') return null;
+  const g = raw.id != null ? raw : { ...raw, id: raw };   // tolerate id-less shapes
+  const resetsTotal = Number(g.resets_total ?? g.resetsTotal);
+  const resetsLeft = Number(g.resets_left ?? g.resetsLeft);
+  if (!Number.isFinite(resetsTotal) || resetsTotal < 1) return null;
+  // resets_left:0 = SPENT (live 2026-09-30: the opus55-launch grant on
+  // max@gomokka.com shows resets_total:1, resets_left:0, usable_now:false — already
+  // consumed at the Opus 5.5 launch). Keep it OUT of the claimable list; the LIST
+  // still surfaces it so the TUI can show the spent history if wanted.
+  if (!Number.isFinite(resetsLeft) || resetsLeft < 1) return null;
+  const startsAt = toMs(g.starts_at ?? g.startsAt);
+  const endsAt = toMs(g.ends_at ?? g.endsAt);
+  return {
+    id: g.id,
+    label: g.label || null,
+    resetsLeft, resetsTotal, startsAt, endsAt,
+    // clears is the money field: [five_hour, seven_day, seven_day_overage_included]
+    // means a grant clears BOTH windows (measured live). Default to assuming both
+    // when absent rather than none — the observed server always sends it.
+    clears: Array.isArray(g.clears) ? g.clears : ['five_hour', 'seven_day'],
+    usableNow: g.usable_now !== false && (resetsLeft >= 1),
+    paused: g.paused === true,
+    requiresLimit: g.use_requires_limit !== false, // most grants only fire at the wall
+    expired: endsAt != null && endsAt <= now,
+  };
+}
+
+/** List this account's banked resets. Zero-spend read (skip_spend=1).
+ *  Returns { grants: [], nextGrantId, cooldownUntil, eligible, reason } | { error }. */
+export async function listResetGrants(accessToken, { signal } = {}) {
+  if (!accessToken) return { error: 'no token' };
+  try {
+    const res = await fetch(`${USAGE_BASE}?cedar_ember=1&skip_spend=1`, {
+      headers: headers(accessToken), signal,
+    });
+    if (res.status === 401) return { error: 'unauthorized' };
+    if (!res.ok) return { error: `HTTP ${res.status}` };
+    const body = await res.json();
+    const ce = body?.cedar_ember;
+    if (!ce || typeof ce !== 'object') {
+      // Not an error: most accounts simply aren't in the program.
+      return { grants: [], nextGrantId: null, cooldownUntil: null, eligible: false, reason: 'not_offered' };
+    }
+    if (ce.eligible === false) {
+      return { grants: [], nextGrantId: null, cooldownUntil: toMs(ce.cooldown_until ?? ce.cooldownUntil),
+               eligible: false, reason: ce.ineligible_reason || 'ineligible' };
+    }
+    const now = Date.now();
+    const grants = (Array.isArray(ce.grants) ? ce.grants : []).map(g => normalizeGrant(g, now)).filter(Boolean);
+    return {
+      grants,
+      nextGrantId: ce.next_grant_id ?? ce.nextGrantId ?? null,
+      cooldownUntil: toMs(ce.cooldown_until ?? ce.cooldownUntil),
+      eligible: true,
+      reason: null,
+    };
+  } catch (err) {
+    return { error: err.message || String(err) };
+  }
+}
+
+/** Claim one grant. The CLI never retries a claim on the wire; our request_id is
+ *  random per CALL (server treats already_used as success), so a caller retry is
+ *  safe but the id is not reused across distinct decisions. Returns
+ *  { ok:true } | { ok:false, error, code }. */
+export async function claimResetGrant(accessToken, grantId, { signal, requestId } = {}) {
+  if (!accessToken || !grantId) return { ok: false, error: 'missing args' };
+  try {
+    const prof = await fetch(PROFILE_URL, { headers: headers(accessToken), signal });
+    if (!prof.ok) return { ok: false, error: `profile HTTP ${prof.status}` };
+    const orgs = (await prof.json())?.organizations;
+    const org = Array.isArray(orgs) && orgs.length ? orgs[0].uuid : null;
+    if (!org) return { ok: false, error: 'no oauth organization' };
+
+    const rid = requestId || randomUUID();
+    const res = await fetch(`https://api.anthropic.com${CLAIM_PATH}/${org}/reset_rate_limits`, {
+      method: 'POST',
+      headers: { ...headers(accessToken), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ program: 'cedar_ember', grant_id: grantId, request_id: rid }),
+      signal,
+    });
+    const data = await res.json().catch(() => null);
+    // Success shapes observed: {success:true} or result:"already_used" (idempotent).
+    const okFlag = data?.success === true || data?.result === 'already_used';
+    if (okFlag) return { ok: true, grantId, alreadyUsed: data?.result === 'already_used' };
+    return { ok: false, error: data?.error?.message || JSON.stringify(data).slice(0, 200), code: data?.error?.type };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}

package/src/prober.js

@@ -8,6 +8,9 @@
 // This is the one sanctioned active-upstream feature; the proxy is otherwise passive.
 
 import { fetchUsage, fetchProviderUsage } from './oauth.js';
+import { listResetCards, redeemResetCard } from './zai-reset-cards.js';
+import { listResetGrants, claimResetGrant } from './claude-reset-grants.js';
+import { decideZai, decideClaude } from './reset-policy.js';
 
 export class Prober {
   constructor(accountManager, { intervalMs = 0, probeFn = fetchUsage, providerProbeFn = fetchProviderUsage, timeoutMs = 10_000, log = console.log, usageGapMs = null } = {}) {
@@ -179,9 +182,56 @@ export class Prober {
       const usage = await this._withTimeout(this.providerProbeFn(account));
       if (!usage) return; // timed out — try again next cycle
       this.am.applyProviderUsage(account.index, usage);
+      // Reset cards piggyback on the same poll cycle (z.ai only; zero-spend read).
+      // Failures are swallowed on purpose: cards are an enhancement, never a probe
+      // health signal — a card-list 401 must not turn the quota bars stale.
+      // OWNER GATE (2026-09-30): disabled accounts are excluded from listing AND
+      // redemption entirely — a readable key on a disabled account (someone else
+      // uses it) is not authority to act.
+      if (account.enabled !== false && account.credential) {
+        if (account.provider === 'zai' && this.am.applyResetCards) {
+          try {
+            const cards = await this._withTimeout(listResetCards(account.credential));
+            if (cards) {
+              this.am.applyResetCards(account.index, cards);
+              const act = decideZai(account, cards);
+              if (act) await this._redeemZaiCard(account, act);
+            }
+          } catch { /* cards are best-effort */ }
+        }
+      }
     } catch { /* best-effort; never let a probe throw */ }
   }
 
+  /** Execute a z.ai card redeem decided by the policy. Logs before/after. */
+  async _redeemZaiCard(account, act) {
+    try {
+      const q = account.quota || {};
+      this.log(`[reset-card] ${account.name}: redeeming ${act.resetType} card ${act.card.recordId} (${act.reason}; ses=${q.providerSes ?? '?'} wk=${q.providerWk ?? '?'})`);
+      const r = await this._withTimeout(redeemResetCard(account.credential, act.card.recordId, act.resetType));
+      if (r?.ok) {
+        this.log(`[reset-card] ${account.name}: card ${act.card.recordId} redeemed`);
+        if (this.am.applyResetCards) {
+          const fresh = await this._withTimeout(listResetCards(account.credential));
+          if (fresh) this.am.applyResetCards(account.index, fresh);
+        }
+      } else {
+        this.log(`[reset-card] ${account.name}: redeem FAILED card ${act.card.recordId}: ${r?.error}`);
+      }
+    } catch (e) { this.log(`[reset-card] ${account.name}: redeem error ${e.message}`); }
+  }
+
+  /** Execute a Claude cedar_ember claim decided by the policy. */
+  async _claimClaudeGrant(account, act) {
+    try {
+      const q = account.quota || {};
+      this.log(`[reset-grant] ${account.name}: claiming grant ${act.grant.id} (${act.reason}; ses=${q.unified5h ?? '?'} wk=${q.unified7d ?? '?'})`);
+      const r = await this._withTimeout(claimResetGrant(account.credential, act.grant.id));
+      if (r?.ok) this.log(`[reset-grant] ${account.name}: grant ${act.grant.id} claimed${r.alreadyUsed ? ' (already used — idempotent)' : ''}`);
+      else this.log(`[reset-grant] ${account.name}: claim FAILED ${act.grant.id}: ${r?.error}`);
+    } catch (e) { this.log(`[reset-grant] ${account.name}: claim error ${e.message}`); }
+  }
+
   /** Probe one OAUTH account. Returns {ok, status} so probeAll can pace/back-off
    *  and so a persistent failure is RECORDED (surfaced in the TUI/status) rather
    *  than silently swallowed — a swallowed failing probe is what let a stale
@@ -193,6 +243,18 @@ export class Prober {
     // on 2solarmax@ between 2026-09-18 and 09-20.
     if (account.subscriptionGone) return { ok: false, status: 403 };
     try {
+      // Claude banked resets (cedar_ember) piggyback on the oauth poll — same
+      // OWNER GATE as z.ai cards: a DISABLED account is never listed or claimed.
+      try {
+        if (account.enabled !== false && account.credential && this.am.applyResetGrants) {
+          const listing = await this._withTimeout(listResetGrants(account.credential));
+          if (listing) {
+            this.am.applyResetGrants(account.index, listing);
+            const act = decideClaude(account, listing);
+            if (act) await this._claimClaudeGrant(account, act);
+          }
+        }
+      } catch { /* grants are best-effort; never break the quota probe */ }
       await this.am.ensureTokenFresh(account.index);
       let usage = await this._withTimeout(this.probeFn(account.credential));
       if (usage?.status === 401) {

package/src/reset-policy.js

@@ -0,0 +1,121 @@
+/**
+ * WHEN to redeem a limit-reset: the deliberate decision layer.
+ *
+ * Two value sources, one policy:
+ *  - z.ai reset cards: { fiveHour:[{recordId,expiresAt,expired}], weekly:[...] }
+ *  - Claude cedar_ember grants: { grants:[{id,resetsLeft,endsAt,usableNow,paused,
+ *    requiresLimit,clears}], nextGrantId, cooldownUntil, eligible }
+ *
+ * Rules (owner, 2026-09-30 — "account not just for exhaustion, but also the time
+ * left until expiry of the reset"):
+ *
+ * R0  ENABLED GATE — the caller must never even ask about a disabled account. The
+ *     policy asserts it too: a disabled account's cards/grants are someone else's.
+ *     (privacy@gomokka.com: owner uses it elsewhere; readable key is not authority.)
+ *
+ * R1  AT-THE-WALL — redeem when the window the reset clears is effectively spent:
+ *     weekly >= 0.90, or (no weekly-clearing reset and 5h >= 0.95). Wall, not 100%:
+ *     routing benches an account before the bar reads full.
+ *
+ * R2  DYING VALUE — a reset expiring soon is worth MORE than waiting: redeem when
+ *     expiry < 24h AND the account has consumed enough that the refill buys real
+ *     capacity (utilization > 0.30 for weekly-clearing; > 0.50 for 5h-only). At
+ *     expiry the reset is worth zero, so "save it for a worse moment" is the
+ *     false economy — the worse moment must occur BEFORE expiry or never.
+ *
+ * R3  EXPIRED — never redeem an expired reset (idempotent keys protect retries,
+ *     but a redeem against an expired card is just a guaranteed API error).
+ *
+ * R4  ORDER — prefer the reset that clears the MOST (weekly clears both windows);
+ *     among equals, the soonest-expiring first. Never spend a weekly-clearing
+ *     reset when a 5h-only one would do — EXCEPT under R2 with <24h left on the
+ *     weekly reset and no 5h reset at all.
+ *
+ * R5  PACE — at most ONE redeem per account per evaluation. The caller invokes the
+ *     policy each poll cycle; the deterministic z.ai requestId makes an accidental
+ *     double-fire harmless, but the policy still returns a single action.
+ */
+export const POLICY = {
+  wallWeekly: 0.90,       // weekly at 90% = at the wall
+  wallSes: 0.95,          // 5h at 95% = at the wall
+  dyingWindowMs: 24 * 3600 * 1000, // redeem-don't-save horizon
+  dyingMinUtilWeekly: 0.30, // below this a dying weekly refill buys too little
+  dyingMinUtilSes: 0.50,    // 5h refills are cheap capacity; demand more waste first
+};
+
+function msLeft(t, now) { return t == null ? Infinity : t - now; }
+
+/** Decide the z.ai action. Returns {kind:'card', card, resetType} | null. */
+export function decideZai(account, cards, now = Date.now()) {
+  if (account?.enabled === false) return null;               // R0
+  if (!cards || cards.error) return null;
+  const q = account.quota || {};
+  const ses = q.providerSes ?? null;
+  const wk = q.weeklyAbsent ? null : (q.providerWk ?? null);
+  const wkUtil = wk; const sesUtil = ses;
+
+  const weeklyCards = (cards.weekly || []).filter(c => !c.expired && c.recordId != null);
+  const sesCards = (cards.fiveHour || []).filter(c => !c.expired && c.recordId != null);
+  // R4: soonest expiry first inside each class.
+  weeklyCards.sort((a, b) => (a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity));
+  sesCards.sort((a, b) => (a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity));
+
+  const weeklyCard = weeklyCards[0] || null;
+  const sesCard = sesCards[0] || null;
+
+  // --- weekly card: clears BOTH windows (z.ai docs; measured: glm1 100%->0% both)
+  if (weeklyCard) {
+    const worst = Math.max(wkUtil ?? 0, sesUtil ?? 0);
+    const atWall = wkUtil != null && wkUtil >= POLICY.wallWeekly;
+    const dying = msLeft(weeklyCard.expiresAt, now) < POLICY.dyingWindowMs
+      && worst >= POLICY.dyingMinUtilWeekly;
+    if (atWall || dying) {
+      return { kind: 'card', card: weeklyCard, resetType: 'WEEK',
+               reason: atWall ? 'weekly at wall' : 'dying value' };
+    }
+  }
+
+  // --- 5h card: clears only the session window
+  if (sesCard) {
+    const atWall = sesUtil != null && sesUtil >= POLICY.wallSes
+      && (weeklyCard == null);   // R4: a weekly card can do this job AND more
+    const dying = msLeft(sesCard.expiresAt, now) < POLICY.dyingWindowMs
+      && (sesUtil ?? 0) >= POLICY.dyingMinUtilSes;
+    if (atWall || dying) {
+      return { kind: 'card', card: sesCard, resetType: 'FIVE_HOUR',
+               reason: atWall ? 'session at wall' : 'dying value' };
+    }
+  }
+  return null;
+}
+
+/** Decide the Claude action. Returns {kind:'grant', grant} | null. */
+export function decideClaude(account, listing, now = Date.now()) {
+  if (account?.enabled === false) return null;               // R0
+  if (!listing || listing.error || listing.eligible === false) return null;
+  if (listing.cooldownUntil != null && listing.cooldownUntil > now) return null;
+  const grants = (listing.grants || [])
+    .filter(g => g.usableNow && !g.paused && !g.expired)
+    .sort((a, b) => (a.endsAt ?? Infinity) - (b.endsAt ?? Infinity));
+  // The server names the next grant it would spend; honoring it avoids surprises.
+  const chosen = grants.find(g => listing.nextGrantId == null || g.id === listing.nextGrantId) || grants[0];
+  if (!chosen) return null;
+
+  const q = account.quota || {};
+  const wkUtil = q.unified7d ?? null;
+  const sesUtil = q.unified5h ?? null;
+  const clearsWk = chosen.clears?.includes('seven_day');
+
+  let atWall = false;
+  if (clearsWk) atWall = wkUtil != null && wkUtil >= POLICY.wallWeekly;
+  else atWall = sesUtil != null && sesUtil >= POLICY.wallSes;
+
+  // use_requires_limit: some grants may only fire AT the wall (server-enforced).
+  const dying = msLeft(chosen.endsAt, now) < POLICY.dyingWindowMs
+    && Math.max(wkUtil ?? 0, sesUtil ?? 0) >= (clearsWk ? POLICY.dyingMinUtilWeekly : POLICY.dyingMinUtilSes);
+  // A requires-limit grant cannot be redeemed pre-wall even for dying value.
+  if (atWall || (dying && !chosen.requiresLimit)) {
+    return { kind: 'grant', grant: chosen, reason: atWall ? 'at wall' : 'dying value' };
+  }
+  return null;
+}

package/src/tui.js

@@ -255,6 +255,30 @@ function settingsTags(am, a) {
   }
   const capTag = capText(a, capBenched(am, a), am);
   if (capTag) tags.push(capTag);
+  // A switched-off account whose credentials ALSO died keeps "disabled" in the status
+  // column (so the disabled inventory stays readable at a glance) and carries the second
+  // problem here. Without this the row would hide the fact that re-enabling it later
+  // yields a broken account — the 2026-08-10 report that 8 disabled accounts were all
+  // sitting on dead credentials.
+  if (a?.enabled === false) {
+    if (a.refreshDead) tags.push(yellow('needs login'));
+    else if (a.subscriptionGone) tags.push(red('no sub'));
+    return tags;   // disabled: never show card inventory either (owner gate)
+  }
+  // Available limit resets — the pool redeems these automatically per policy
+  // (reset-policy.js). Shown so the owner can see banked value before it expires.
+  const rc = a?.resetCards;
+  if (rc) {
+    const live5 = (rc.fiveHour || []).filter(c => !c.expired).length;
+    const liveW = (rc.weekly || []).filter(c => !c.expired).length;
+    if (liveW) tags.push(green(`reset wk×${liveW}`));
+    if (live5) tags.push(green(`reset 5h×${live5}`));
+  }
+  const rg = a?.resetGrants;
+  if (rg?.eligible) {
+    const live = (rg.grants || []).filter(g => g.usableNow && !g.expired).length;
+    if (live) tags.push(green(`reset×${live}`));
+  }
   return tags;
 }
 
@@ -2084,7 +2108,9 @@ export class TUI {
     if (a.refreshDead) effectiveStatus = a.enabled === false ? 'disabled-reauth' : 'reauth';
     // Subscription gone (org-disabled 403): a DISTINCT state from reauth — re-logging in
     // will NOT fix it until the subscription is re-purchased. Says the actionable thing.
-    else if (a.subscriptionGone) effectiveStatus = 'no sub';
+    // Same precedence rule as reauth above: when the account is ALSO switched off,
+    // "disabled" stays the headline so the disabled inventory remains readable.
+    else if (a.subscriptionGone) effectiveStatus = a.enabled === false ? 'disabled-nosub' : 'no sub';
     switch (effectiveStatus) {
       case 'active':    status = isCur ? green('active') : 'active'; break;
       case 'reauth':    status = yellow('reauth'); break;
@@ -2093,9 +2119,19 @@ export class TUI {
       case 'waiting':   status = yellow('waiting'); break;
       case 'paused':    status = yellow('paused'); break;
       case 'disabled':  status = red('✕ disabled'); break;
-      // Disabled AND needs re-login — both facts matter: it won't serve because you
-      // switched it off, and it CAN'T serve until you log in again.
-      case 'disabled-reauth': status = red('✕ reauth'); break;
+      // Disabled AND needs re-login — both facts matter, and DISABLED LEADS.
+      // The owner's question that drove this (2026-09-30): "when I disable the account
+      // and then the token expires, does it show disabled or reauth? It needs to
+      // continue to show disabled otherwise I'm confused as to which ones I have
+      // disabled." Showing only '✕ reauth' made a deliberately-off account
+      // indistinguishable from a live one with dead credentials, so the disabled
+      // inventory could not be read off the screen at all. So the STATUS column always
+      // says 'disabled' for an account you switched off, and the reason it ALSO cannot
+      // serve rides as its own tag ("needs login" / "no sub") — collapsing both into one
+      // '+' marker would lose the distinction between "log in again" (fixable) and
+      // "subscription gone" (not fixable by logging in).
+      case 'disabled-reauth':
+      case 'disabled-nosub':  status = red('✕ disabled'); break;
       case 'no sub': status = red('✕ no sub'); break;
       case 'throttled': {
         // A transient auto-recovering cooldown — show the remaining time (from

package/src/zai-reset-cards.js

@@ -0,0 +1,118 @@
+/**
+ * z.ai Quota Reset Cards — list + redeem, via the same API key the quota poller
+ * already uses. Zero browser, zero captcha (the exact pain that motivated this:
+ * ~6 provider accounts, each a manual web login with an aggressive captcha to
+ * check for a card that usually isn't there).
+ *
+ * Endpoints (verified live 2026-09-30):
+ *   GET  /api/biz/customer-package-reset/list?targetType=PERSONAL
+ *        -> data.fiveHourResets[] / weekResets[], each {recordId, grantType,
+ *           expireTime 'YYYY-MM-DD HH:mm:ss' (UTC), available}
+ *   POST /api/biz/customer-package-reset/use
+ *        body {recordId, targetType:'PERSONAL', resetType:'WEEK'|'FIVE_HOUR',
+ *              requestId}  -> envelope; data echoes the recordId on success
+ *
+ * Semantics measured live:
+ *   - a WEEKLY card ALSO refills the 5h window (z.ai docs) — never spend a weekly
+ *     card on a 5h wall.
+ *   - `requestId` is the idempotency key: a retry with the SAME id cannot burn a
+ *     second card. We derive it deterministically from recordId so any retry of a
+ *     failed redeem is automatically safe.
+ *   - the envelope returns HTTP 200 with success:false on failure — always check
+ *     the envelope, never the status code.
+ *   - an unavailable/expired/foreign card returns code 400 "The specified reset
+ *     attempt is unavailable. Refresh and try again".
+ *   - invalid resetType vocabulary yields 400 "Unsupported reset type: X" (safe
+ *     probe that cannot spend anything).
+ */
+import { createHash } from 'node:crypto';
+
+const BASE = 'https://api.z.ai/api/biz/customer-package-reset';
+const LIST_URL = `${BASE}/list?targetType=PERSONAL`;
+const USE_URL = `${BASE}/use`;
+
+/** 'YYYY-MM-DD HH:mm:ss' (z.ai has no timezone suffix; it is UTC) -> epoch ms. */
+export function parseCardExpiry(s) {
+  if (!s || typeof s !== 'string') return null;
+  const m = s.match(/^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})/);
+  if (!m) return null;
+  return Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
+}
+
+/** Normalize a raw card array -> [{recordId, expiresAt, expired}], available only. */
+function normalizeCards(arr, now = Date.now()) {
+  const out = [];
+  for (const c of (Array.isArray(arr) ? arr : [])) {
+    if (!c || c.available !== true) continue;
+    const recordId = Number(c.recordId);
+    if (!Number.isFinite(recordId)) continue;
+    const expiresAt = parseCardExpiry(c.expireTime);
+    out.push({ recordId, expiresAt, expired: expiresAt != null && expiresAt <= now });
+  }
+  // Soonest-expiring first — that's the one to spend first.
+  out.sort((a, b) => (a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity));
+  return out;
+}
+
+/** List this account's available reset cards. Zero-spend read.
+ *  Returns { fiveHour: [], weekly: [] } | { error }. */
+export async function listResetCards(token, { signal } = {}) {
+  if (!token) return { error: 'no token' };
+  try {
+    const res = await fetch(LIST_URL, {
+      headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/json' },
+      signal,
+    });
+    if (res.status === 401) return { error: 'unauthorized' };
+    const data = await res.json();
+    if (data?.code !== 200 || !data?.data) {
+      return { error: `bad_envelope${data?.code != null ? ' code=' + data.code : ''}` };
+    }
+    const now = Date.now();
+    return {
+      fiveHour: normalizeCards(data.data.fiveHourResets, now),
+      weekly: normalizeCards(data.data.weekResets, now),
+      source: 'zai',
+    };
+  } catch (err) {
+    return { error: err.message || String(err) };
+  }
+}
+
+/** Deterministic requestId for a card: retries of the SAME redeem are idempotent
+ *  server-side, so a network blip mid-redeem can never double-spend. */
+function requestIdFor(recordId) {
+  const h = createHash('sha256').update(`maxpool-zai-card-${recordId}`).digest('hex').slice(0, 24);
+  return `maxpool-${h}`;
+}
+
+/** Redeem one card. NEVER retries on the wire here (the idempotency key makes a
+ *  caller-level retry safe). Returns { ok:true, recordId } | { ok:false, error, code }. */
+export async function redeemResetCard(token, recordId, resetType, { signal } = {}) {
+  if (resetType !== 'WEEK' && resetType !== 'FIVE_HOUR') {
+    return { ok: false, error: `invalid resetType ${resetType}` };
+  }
+  if (!Number.isFinite(recordId)) return { ok: false, error: 'invalid recordId' };
+  try {
+    const res = await fetch(USE_URL, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        recordId, targetType: 'PERSONAL', resetType,
+        requestId: requestIdFor(recordId),
+      }),
+      signal,
+    });
+    const data = await res.json().catch(() => null);
+    if (data?.success === true && (data.code === 200 || data.code === 0)) {
+      return { ok: true, recordId, data: data.data ?? null };
+    }
+    return {
+      ok: false,
+      error: data?.msg || `envelope code ${data?.code} (HTTP ${res.status})`,
+      code: data?.code ?? null,
+    };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}