maxpool 1.24.81 → 1.24.82

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -50,9 +50,50 @@ function toMs(v) {
50
50
  return Number.isFinite(t) ? t : null;
51
51
  }
52
52
 
53
+ // Scope map (D1 + research Q5, from the Claude Code 2.1.322 client rule
54
+ // `clears.includes(L) || (L==='seven_day' && givesBackWeekly)`): which limit a
55
+ // `clears` key refills. An UNMAPPED key means "we don't know what this refills" —
56
+ // the grant is shown, never claimed, and never lifts a cap (fail closed; the
57
+ // October z.ai drift class — never invent scope from a name).
58
+ export const GRANT_SCOPE_BY_KEY = {
59
+ seven_day: 'general', // refills the general weekly
60
+ five_hour: 'session', // refills the session window only
61
+ seven_day_overage_included: 'fable', // model-scoped: refills the Fable weekly
62
+ };
63
+
64
+ /** One shared applicability answer (per D1): the limits this grant refills.
65
+ * Returns an array of scopes from {general, session, fable}; unknown/unmapped
66
+ * keys contribute NOTHING (fail closed), and `unknown` is never returned as a
67
+ * scope — a grant with only unmapped keys has appliesTo() = [] (display-only).
68
+ * A `gives_back_weekly` grant ALSO returns 'general' (its model reset returns
69
+ * that model's usage to the general weekly) — the client's own OR rule. */
70
+ export function appliesTo(grant) {
71
+ if (!grant) return [];
72
+ const out = new Set();
73
+ for (const key of (Array.isArray(grant.clears) ? grant.clears : [])) {
74
+ const scope = GRANT_SCOPE_BY_KEY[key];
75
+ if (scope) out.add(scope);
76
+ }
77
+ // Both shapes: the raw API key AND the normalized field every STORED grant
78
+ // carries (reading only the raw key made the OR rule dead for stored grants).
79
+ if (grant.gives_back_weekly === true || grant.givesBackWeekly === true) out.add('general');
80
+ return [...out];
81
+ }
82
+
83
+ // Process-wide: the first listing logs the raw grant KEY SET (keys only, never
84
+ // values) once, so a schema drift is visible without per-sweep spam. Set by
85
+ // listResetGrants on the first grants-bearing response.
86
+ let _loggedRawGrantKeys = false;
87
+
53
88
  /** Normalize a cedar_ember grant. Drops malformed entries (the CLI does the same:
54
89
  * "ignoring a malformed grant"). Keeps expired ones OUT unless resets remain and
55
- * ends_at is still ahead — expired grants are display-only noise. */
90
+ * ends_at is still ahead — expired grants are display-only noise.
91
+ *
92
+ * FAIL-CLOSED defaults (pre-mortem #11, 2026-11-10): the old normalizer INVENTED
93
+ * scope and usability from missing fields (clears → ['five_hour','seven_day'],
94
+ * usable_now → true). A missing `clears` is scope UNKNOWN: [] — shown, never
95
+ * claimed, never lifts a cap. Missing `gives_back_weekly` is false. Missing
96
+ * `usable_now` is false (a usable grant's listing always says so). */
56
97
  export function normalizeGrant(raw, now = Date.now()) {
57
98
  if (!raw || typeof raw !== 'object') return null;
58
99
  const g = raw.id != null ? raw : { ...raw, id: raw }; // tolerate id-less shapes
@@ -71,22 +112,53 @@ export function normalizeGrant(raw, now = Date.now()) {
71
112
  label: g.label || null,
72
113
  resetsLeft, resetsTotal, startsAt, endsAt,
73
114
  // clears is the money field: [five_hour, seven_day, seven_day_overage_included]
74
- // means a grant clears BOTH windows (measured live). Default to assuming both
75
- // when absent rather than none — the observed server always sends it.
76
- clears: Array.isArray(g.clears) ? g.clears : ['five_hour', 'seven_day'],
77
- usableNow: g.usable_now !== false && (resetsLeft >= 1),
115
+ // (measured live, 2026-11-10). Missing → [] = scope unknown: display-only,
116
+ // never claimed, never lifts a cap. Never assume both.
117
+ clears: Array.isArray(g.clears) ? g.clears : [],
118
+ givesBackWeekly: g.gives_back_weekly === true,
119
+ blocking: g.blocking === true,
120
+ unavailableReason: typeof g.unavailable_reason === 'string' ? g.unavailable_reason : null,
121
+ percentUsed: Number.isFinite(Number(g.percent_used)) ? Number(g.percent_used) : null,
122
+ // Fail closed: a grant the listing does not explicitly mark usable is NOT
123
+ // claimable (pre-mortem #11). usable_now:false also fails here.
124
+ usableNow: g.usable_now === true && (resetsLeft >= 1),
78
125
  paused: g.paused === true,
79
126
  requiresLimit: g.use_requires_limit !== false, // most grants only fire at the wall
80
127
  expired: endsAt != null && endsAt <= now,
81
128
  };
82
129
  }
83
130
 
131
+ /** Log the raw grant key set once per process (drift visibility). Keys only. */
132
+ function _logRawGrantKeysOnce(ce, log = console.log) {
133
+ if (_loggedRawGrantKeys) return;
134
+ _loggedRawGrantKeys = true;
135
+ const keys = new Set();
136
+ for (const g of (Array.isArray(ce.grants) ? ce.grants : [])) {
137
+ if (g && typeof g === 'object') for (const k of Object.keys(g)) keys.add(k);
138
+ }
139
+ try { log(`[reset-grant] cedar_ember grant keys: [${[...keys].sort().join(', ')}]`); } catch { /* log-only */ }
140
+ }
141
+
142
+ // A `clears` value we have no scope for: the grant is shown, never claimed, never
143
+ // lifts a cap. Logged ONCE per key per process so a new limit name is visible.
144
+ const _loggedUnmappedClears = new Set();
145
+ function _logUnmappedClearsOnce(ce, log = console.log) {
146
+ for (const g of (Array.isArray(ce.grants) ? ce.grants : [])) {
147
+ for (const k of (Array.isArray(g?.clears) ? g.clears : [])) {
148
+ if (typeof k !== 'string' || k in GRANT_SCOPE_BY_KEY || _loggedUnmappedClears.has(k)) continue;
149
+ _loggedUnmappedClears.add(k);
150
+ try { log(`[reset-grant] unmapped clears key "${k}" — grant shown, never claimed`); } catch { /* log-only */ }
151
+ }
152
+ }
153
+ }
154
+
84
155
  /** List this account's banked resets. Zero-spend read (skip_spend=1).
85
- * Returns { grants: [], nextGrantId, cooldownUntil, eligible, reason } | { error }. */
86
- export async function listResetGrants(accessToken, { signal } = {}) {
156
+ * Returns { grants: [], nextGrantId, cooldownUntil, eligible, reason } | { error }.
157
+ * `fetchImpl` is the test seam (never hits api.anthropic.com from tests). */
158
+ export async function listResetGrants(accessToken, { signal, fetchImpl = (u, o) => fetch(u, o) } = {}) {
87
159
  if (!accessToken) return { error: 'no token' };
88
160
  try {
89
- const res = await fetch(`${USAGE_BASE}?cedar_ember=1&skip_spend=1`, {
161
+ const res = await fetchImpl(`${USAGE_BASE}?cedar_ember=1&skip_spend=1`, {
90
162
  headers: headers(accessToken), signal,
91
163
  });
92
164
  if (res.status === 401) return { error: 'unauthorized' };
@@ -102,6 +174,7 @@ export async function listResetGrants(accessToken, { signal } = {}) {
102
174
  eligible: false, reason: ce.ineligible_reason || 'ineligible' };
103
175
  }
104
176
  const now = Date.now();
177
+ if (Array.isArray(ce.grants) && ce.grants.length) { _logRawGrantKeysOnce(ce); _logUnmappedClearsOnce(ce); }
105
178
  const grants = (Array.isArray(ce.grants) ? ce.grants : []).map(g => normalizeGrant(g, now)).filter(Boolean);
106
179
  return {
107
180
  grants,
@@ -115,27 +188,47 @@ export async function listResetGrants(accessToken, { signal } = {}) {
115
188
  }
116
189
  }
117
190
 
191
+ // C6: org uuid cache — one profile GET per account per process (pre-mortem #6: a
192
+ // failing claim retried a profile GET + POST per sweep per account). Keyed by the
193
+ // account name the CALLER passes as accountKey. Cleared by forgetClaimOrg when
194
+ // the account is removed or re-logged-in (a same-name re-login may be a
195
+ // different org), and dropped on a 403/404 claim (the org no longer matches).
196
+ const _orgCache = new Map(); // accountKey -> org uuid
197
+
198
+ /** Forget the cached org for one account (removeAccount / token replacement). */
199
+ export function forgetClaimOrg(accountKey) {
200
+ if (accountKey != null) _orgCache.delete(accountKey);
201
+ }
202
+
118
203
  /** Claim one grant. The CLI never retries a claim on the wire; our request_id is
119
204
  * random per CALL (server treats already_used as success), so a caller retry is
120
205
  * safe but the id is not reused across distinct decisions. Returns
121
- * { ok:true } | { ok:false, error, code }. */
122
- export async function claimResetGrant(accessToken, grantId, { signal, requestId, fetchImpl } = {}) {
206
+ * { ok:true } | { ok:false, error, code, status } (`status` = the HTTP status
207
+ * of the failing call when there was one — a 401 means "token rejected", which
208
+ * callers treat as defer-to-the-sweep, not as a failed claim).
209
+ * `accountKey` (account name) caches the org uuid per account (C6): one profile
210
+ * GET per account per process. */
211
+ export async function claimResetGrant(accessToken, grantId, { signal, requestId, fetchImpl, accountKey } = {}) {
123
212
  if (!accessToken || !grantId) return { ok: false, error: 'missing args' };
124
213
  const doFetch = fetchImpl || ((u, o) => fetch(u, o));
125
214
  try {
126
- const prof = await doFetch(PROFILE_URL, { headers: headers(accessToken), signal });
127
- if (!prof.ok) return { ok: false, error: `profile HTTP ${prof.status}` };
128
- const body = await prof.json();
129
- // The profile returns `organization` (SINGULAR object) — measured live on
130
- // maxim.krasnykh@gmail.com 2026-10-09: {account, organization, application}.
131
- // v1.24.0-12 read only the plural `organizations` array (null for personal
132
- // accounts), so EVERY cedar_ember claim on a personal account failed with
133
- // 'no oauth organization' while the account sat exhausted with a usable reset
134
- // (owner report: 'this account is exhausted but the reset is not being used').
135
- // Accept both shapes; singular wins when present.
136
- const org = body?.organization?.uuid
137
- ?? (Array.isArray(body?.organizations) && body.organizations.length ? body.organizations[0].uuid : null);
138
- if (!org) return { ok: false, error: 'no oauth organization' };
215
+ let org = accountKey != null ? _orgCache.get(accountKey) : undefined;
216
+ if (org == null) {
217
+ const prof = await doFetch(PROFILE_URL, { headers: headers(accessToken), signal });
218
+ if (!prof.ok) return { ok: false, error: `profile HTTP ${prof.status}`, status: prof.status };
219
+ const body = await prof.json();
220
+ // The profile returns `organization` (SINGULAR object) — measured live on
221
+ // maxim.krasnykh@gmail.com 2026-10-09: {account, organization, application}.
222
+ // v1.24.0-12 read only the plural `organizations` array (null for personal
223
+ // accounts), so EVERY cedar_ember claim on a personal account failed with
224
+ // 'no oauth organization' while the account sat exhausted with a usable reset
225
+ // (owner report: 'this account is exhausted but the reset is not being used').
226
+ // Accept both shapes; singular wins when present.
227
+ org = body?.organization?.uuid
228
+ ?? (Array.isArray(body?.organizations) && body.organizations.length ? body.organizations[0].uuid : null);
229
+ if (!org) return { ok: false, error: 'no oauth organization' };
230
+ if (accountKey != null) _orgCache.set(accountKey, org);
231
+ }
139
232
 
140
233
  const rid = requestId || randomUUID();
141
234
  const res = await doFetch(`https://api.anthropic.com${CLAIM_PATH}/${org}/reset_rate_limits`, {
@@ -148,8 +241,15 @@ export async function claimResetGrant(accessToken, grantId, { signal, requestId,
148
241
  // Success shapes observed: {success:true} or result:"already_used" (idempotent).
149
242
  const okFlag = data?.success === true || data?.result === 'already_used';
150
243
  if (okFlag) return { ok: true, grantId, alreadyUsed: data?.result === 'already_used' };
151
- return { ok: false, error: data?.error?.message || JSON.stringify(data).slice(0, 200), code: data?.error?.type };
244
+ // 403/404 on the org path: the cached org no longer belongs to this login —
245
+ // drop it so the next claim re-reads the profile.
246
+ if ((res.status === 403 || res.status === 404) && accountKey != null) _orgCache.delete(accountKey);
247
+ return { ok: false, error: data?.error?.message || JSON.stringify(data).slice(0, 200), code: data?.error?.type,
248
+ status: Number.isFinite(res.status) ? res.status : null };
152
249
  } catch (err) {
153
250
  return { ok: false, error: err.message || String(err) };
154
251
  }
155
252
  }
253
+
254
+ /** Test seam: reset the once-per-process raw-key-set logger. */
255
+ export function _resetGrantKeyLogForTest() { _loggedRawGrantKeys = false; _loggedUnmappedClears.clear(); }
package/src/index.js CHANGED
@@ -1021,6 +1021,7 @@ async function serverWorkerCommand() {
1021
1021
  restartController.requestRouted(id, info.account);
1022
1022
  tui?.onRequestRouted(id, info);
1023
1023
  },
1024
+ onRequestFirstByte: (id) => { tui?.onRequestFirstByte(id); },
1024
1025
  onRequestEnd: (id, info) => {
1025
1026
  restartController.requestEnded(id);
1026
1027
  if (tui) {
package/src/prober.js CHANGED
@@ -11,8 +11,12 @@ import { fetchUsage, fetchProviderUsage } from './oauth.js';
11
11
  import { listResetCards, redeemResetCard, fetchZaiModelUsage } from './zai-reset-cards.js';
12
12
  import { listSubscriptions, monthlyPriceUSD } from './zai-subs.js';
13
13
  import { listResetGrants, claimResetGrant } from './claude-reset-grants.js';
14
- import { decideZai, decideClaude } from './reset-policy.js';
14
+ import { decideZai, decideClaudeWithReason, CLAUDE_WALL_WEEKLY } from './reset-policy.js';
15
15
  import { zaiHourlyCalls, compareOutsideUsage, isUsableZaiUsage, OUTSIDE_CHECK_MS } from './outside-usage.js';
16
+ // Reset-machinery timing lives in ONE leaf module (re-exported for callers that
17
+ // imported these from the prober).
18
+ import { GRANTS_EVERY_MS, GRANTS_RETRY_MS, CLAIM_BACKOFF_STEPS_MS, CLAIM_BACKOFF_CAP_MS, LIFT_GRACE_MS } from './reset-timing.js';
19
+ export { GRANTS_EVERY_MS, GRANTS_RETRY_MS, CLAIM_BACKOFF_STEPS_MS, CLAIM_BACKOFF_CAP_MS, LIFT_GRACE_MS };
16
20
 
17
21
  // How often a subscription-latched account is rechecked (one probe + at most one
18
22
  // token refresh per window — cheap, and bounded so a truly canceled plan isn't hammered).
@@ -221,6 +225,7 @@ export class Prober {
221
225
  const cards = await this._withTimeout(this.cardsFn(account.credential));
222
226
  if (cards) {
223
227
  this.am.applyResetCards(account.index, cards);
228
+ this._logCardListingTransition(account, cards);
224
229
  const act = decideZai(account, cards);
225
230
  if (act) await this._redeemZaiCard(account, act);
226
231
  }
@@ -291,9 +296,13 @@ export class Prober {
291
296
  this._cardRetryUntil.set(key, 0); // success clears any backoff
292
297
  this._cardTries?.set(key, 0); // ...and the failure count (red-team 2026-10-23)
293
298
  this.log(`[reset-card] ${account.name}: card ${act.card.recordId} redeemed`);
299
+ // A4: remove the redeemed card from the stored list BEFORE the follow-up
300
+ // read — if that read fails (or is drifted), the stale-kept list must not
301
+ // keep counting a card that no longer exists (pre-mortem #17).
302
+ this.am.removeResetCard?.(account.index, act.card.recordId);
294
303
  if (this.am.applyResetCards) {
295
304
  const fresh = await this._withTimeout(listResetCards(account.credential));
296
- if (fresh) this.am.applyResetCards(account.index, fresh);
305
+ if (fresh && !fresh.error) this.am.applyResetCards(account.index, fresh);
297
306
  }
298
307
  } else {
299
308
  const tries = (this._cardTries?.get(key) || 0) + 1;
@@ -307,15 +316,86 @@ export class Prober {
307
316
  } catch (e) { this.log(`[reset-card] ${account.name}: redeem error ${e.message}`); }
308
317
  }
309
318
 
310
- /** Execute a Claude cedar_ember claim decided by the policy. */
319
+ /** One log line per ok<->failing transition of the grant listing (no per-poll spam). */
320
+ _logGrantListingTransition(account, listing) {
321
+ const failing = Boolean(listing.error);
322
+ if (failing && !account._grantListFailing) {
323
+ account._grantListFailing = true;
324
+ this.log(`[reset-grant] ${account.name}: listing FAILED (${listing.error}) — keeping last known reset count, marked stale`);
325
+ } else if (!failing && account._grantListFailing) {
326
+ account._grantListFailing = false;
327
+ this.log(`[reset-grant] ${account.name}: listing recovered`);
328
+ }
329
+ }
330
+
331
+ /** A4: one log line per ok<->failing transition of the z.ai CARD listing. */
332
+ _logCardListingTransition(account, cards) {
333
+ const failing = Boolean(cards.error);
334
+ if (failing && !account._cardListFailing) {
335
+ account._cardListFailing = true;
336
+ this.log(`[reset-card] ${account.name}: listing FAILED (${cards.error}) — keeping last known cards, marked stale`);
337
+ } else if (!failing && account._cardListFailing) {
338
+ account._cardListFailing = false;
339
+ this.log(`[reset-card] ${account.name}: listing recovered`);
340
+ }
341
+ }
342
+
343
+ /** Execute a Claude cedar_ember claim decided by the policy.
344
+ * C6: the ONE claim lock per account lives on the account-manager (shared with
345
+ * the reactive path); a FAILED claim backs off per (account, grantId)
346
+ * 15m/30m/1h cap 6h; a SUCCESSFUL claim sets lastClaimAt (decideClaude then
347
+ * waits for a newer probe before claiming again) and clears any reactive
348
+ * scoped entry / weekly throttle so the account can serve again immediately. */
311
349
  async _claimClaudeGrant(account, act) {
350
+ if (!act?.grant) return false;
351
+ const now = Date.now();
352
+ const key = `${account.name}:${act.grant.id}`;
353
+ const until = this.am._claimRetryUntil?.get?.(key);
354
+ if (until && until > now) return false;
355
+ if (!this.am.acquireClaimLock?.(account.name)) return false;
312
356
  try {
313
357
  const q = account.quota || {};
314
358
  this.log(`[reset-grant] ${account.name}: claiming grant ${act.grant.id} (${act.reason}; ses=${q.unified5h ?? '?'} wk=${q.unified7d ?? '?'})`);
315
- const r = await this._withTimeout(claimResetGrant(account.credential, act.grant.id));
316
- if (r?.ok) this.log(`[reset-grant] ${account.name}: grant ${act.grant.id} claimed${r.alreadyUsed ? ' (already used — idempotent)' : ''}`);
317
- else this.log(`[reset-grant] ${account.name}: claim FAILED ${act.grant.id}: ${r?.error}`);
318
- } catch (e) { this.log(`[reset-grant] ${account.name}: claim error ${e.message}`); }
359
+ const r = await this._withTimeout(claimResetGrant(account.credential, act.grant.id, { accountKey: account.name }));
360
+ if (r?.ok) {
361
+ this.am.noteClaimSuccess?.(account.name, act.grant.id);
362
+ account.lastClaimAt = Date.now();
363
+ // Spend it in the STORED listing too: until the next listing (≤5 min) the
364
+ // held count, the lift and the reactive path must not see it as unspent.
365
+ this.am.noteGrantClaimed?.(account, act.grant.id);
366
+ // C3 give-back: snapshot unified7d BEFORE the claim so the next probe can
367
+ // measure the drop a give-back grant actually returned (cap+drop ceiling).
368
+ if (act.giveBack) {
369
+ account.giveBack = { pendingAt: account.lastClaimAt, utilBefore: Number(q.unified7d) || 0 };
370
+ }
371
+ // C3: a claim (success or failure) ends the cap lift.
372
+ this.am.endCapLift?.(account.index, 'claim succeeded');
373
+ // C2/C6: the wall this claim refills is gone — clear the reactive scoped
374
+ // entry (a Fable bench stuck at 1.0 was the double-claim shape) and end
375
+ // the bench so the account serves again.
376
+ if (act.scope && act.scope !== 'general' && account.quota?.scopedWeekly?.[act.scope]) {
377
+ delete account.quota.scopedWeekly[act.scope];
378
+ }
379
+ if (account.status === 'throttled') {
380
+ account.status = 'active';
381
+ account.rateLimitedUntil = null;
382
+ if (account.lastError === 'rate_limited') { account.lastError = null; account.lastErrorAt = null; }
383
+ }
384
+ this.log(`[reset-grant] ${account.name}: grant ${act.grant.id} claimed${r.alreadyUsed ? ' (already used — idempotent)' : ''}`);
385
+ return true;
386
+ }
387
+ const { tries, waitMs } = this.am.noteClaimFailure?.(account.name, act.grant.id, now)
388
+ || { tries: 1, waitMs: CLAIM_BACKOFF_STEPS_MS[0] };
389
+ this.log(`[reset-grant] ${account.name}: claim FAILED ${act.grant.id} (try ${tries}, next attempt in ${Math.round(waitMs / 60000)}min): ${r?.error}`);
390
+ // A failed claim ENDS any cap lift (C3: "ends at once on a claim (success or failure)").
391
+ this.am.endCapLift?.(account.index, 'claim failed');
392
+ return false;
393
+ } catch (e) {
394
+ this.log(`[reset-grant] ${account.name}: claim error ${e.message}`);
395
+ return false;
396
+ } finally {
397
+ this.am.releaseClaimLock?.(account.name);
398
+ }
319
399
  }
320
400
 
321
401
  /** Probe one OAUTH account. Returns {ok, status} so probeAll can pace/back-off
@@ -341,21 +421,50 @@ export class Prober {
341
421
  account._subRecheck = true;
342
422
  }
343
423
  try {
424
+ // A3: refresh the token BEFORE the grants listing — a near-expired token
425
+ // otherwise 401s the listing and blanks the count every refresh cycle.
426
+ await this.am.ensureTokenFresh(account.index);
344
427
  // Claude banked resets (cedar_ember) piggyback on the oauth poll — same
345
428
  // OWNER GATE as z.ai cards: a DISABLED account is never listed or claimed.
346
429
  try {
347
430
  // A pool-benched duplicate never claims a grant: the cloud owns this account
348
431
  // (mirror of the z.ai card guard above; red-team 2026-10-31).
349
432
  if (account.enabled !== false && account.credential && !account.poolBenchedBy && this.am.applyResetGrants) {
350
- const listing = await this._withTimeout(this.grantsFn(account.credential));
351
- if (listing) {
352
- this.am.applyResetGrants(account.index, listing);
353
- const act = decideClaude(account, listing);
354
- if (act) await this._claimClaudeGrant(account, act);
433
+ // A2 (pre-mortem #12, 2026-11-10): the grants call hits the SAME per-IP
434
+ // rate-limited /api/oauth/usage endpoint as the usage probe — listing it
435
+ // on EVERY sweep is half the 429 pressure that blanks the count. List at
436
+ // most once per GRANTS_EVERY_MS (5 min) per account. The usage probe
437
+ // below still runs every sweep, so /api/oauth/usage calls per sweep never
438
+ // exceed the pre-change count (2 per account on the grants tick, 1 otherwise).
439
+ const nowMs = this._now();
440
+ const last = account._grantsListedAt || 0;
441
+ const staleOrErrored = account.resetGrants == null
442
+ || account.resetGrants.stale === true
443
+ || account.resetGrants.eligible === false;
444
+ if (nowMs - last >= GRANTS_EVERY_MS || (last > 0 && staleOrErrored && nowMs - last >= GRANTS_RETRY_MS)) {
445
+ // A timeout or throw is a failed listing too (stale, logged once), not silence.
446
+ let listing;
447
+ try { listing = await this._withTimeout(this.grantsFn(account.credential)); }
448
+ catch (e) { listing = { error: e?.message || String(e) }; }
449
+ if (listing == null) listing = { error: 'timed out' };
450
+ if (listing) {
451
+ account._grantsListedAt = nowMs;
452
+ this.am.applyResetGrants(account.index, listing);
453
+ this._logGrantListingTransition(account, listing);
454
+ }
355
455
  }
456
+ // C1: decide AFTER this sweep's usage probe (below), never before it —
457
+ // a decision on the pre-probe reading (up to ~36 min old) is what spent
458
+ // resets right after a free refill. The decision runs at the END of
459
+ // probeOne via _decideClaimAfterProbe, once applyUsageData has stamped
460
+ // lastProbeOkAt.
356
461
  }
357
462
  } catch { /* grants are best-effort; never break the quota probe */ }
358
- await this.am.ensureTokenFresh(account.index);
463
+ // C1/finding 1: the SEND time of the probe whose reading a claim decides on.
464
+ // A probe sent before a claim and applied after it carries the PRE-claim
465
+ // reading; comparing the send time (not the apply time) with lastClaimAt
466
+ // keeps it from licensing a second claim for the same wall.
467
+ let probeSentAt = Date.now();
359
468
  let usage = await this._withTimeout(this.probeFn(account.credential));
360
469
  if (usage?.status === 401) {
361
470
  // Token rejected — force a refresh and retry once. NOT for a DISABLED account:
@@ -368,6 +477,7 @@ export class Prober {
368
477
  // account refreshes normally the moment it is re-enabled.
369
478
  if (account.enabled !== false) {
370
479
  await this.am.ensureTokenFresh(account.index, true);
480
+ probeSentAt = Date.now();
371
481
  usage = await this._withTimeout(this.probeFn(account.credential));
372
482
  }
373
483
  }
@@ -379,7 +489,10 @@ export class Prober {
379
489
  this.am.recordProbeError?.(account.index, usage.error, usage.status ?? null);
380
490
  return { ok: false, status: usage.status ?? null };
381
491
  }
382
- this.am.applyUsageData(account.index, usage); // clears the error + stamps freshness
492
+ this.am.applyUsageData(account.index, usage, { sentAt: probeSentAt }); // clears the error + stamps freshness
493
+ // C1: decide the claim on the reading JUST stored (this sweep's probe), on
494
+ // the listing stored this same sweep — never on a pre-probe reading.
495
+ await this._decideClaimAfterProbe(account);
383
496
  return { ok: true, status: 200 };
384
497
  } catch (e) { // best-effort; never let a probe throw
385
498
  this.am.recordProbeError?.(account.index, e?.message || String(e), null);
@@ -389,6 +502,41 @@ export class Prober {
389
502
  }
390
503
  }
391
504
 
505
+ /** C1 + C5: the claim decision proper, run AFTER applyUsageData. A skip at a
506
+ * reached limit logs ONCE per change of (account, reason), never per sweep. */
507
+ async _decideClaimAfterProbe(account) {
508
+ if (account.enabled === false || !account.credential || account.poolBenchedBy) return;
509
+ if (!this.am.applyResetGrants) return;
510
+ const listing = account.resetGrants;
511
+ if (!listing) return;
512
+ const { action, reason } = decideClaudeWithReason(account, listing);
513
+ if (action) {
514
+ account._claimSkipKey = null;
515
+ await this._claimClaudeGrant(account, action);
516
+ return;
517
+ }
518
+ // C5: at a reached limit with a held-but-unspent grant, say WHY once per
519
+ // (account, reason) change — the owner's live check reads exactly these lines.
520
+ // The reason is the POLICY's own rejection (stale listing, cooldown, already
521
+ // claimed, window elapsed, …), never a guess reconstructed here.
522
+ const q = account.quota || {};
523
+ const wk = q.unified7d ?? null;
524
+ const scopedAtWall = Object.values(q.scopedWeekly || {}).some(e =>
525
+ e && e.reactive !== true && e.utilization != null && e.utilization >= CLAUDE_WALL_WEEKLY);
526
+ const atWall = (wk != null && wk >= CLAUDE_WALL_WEEKLY) || scopedAtWall;
527
+ const held = (listing.grants || []).some(g => g && !g.paused && !g.expired);
528
+ if (!atWall || !held) {
529
+ // Left the wall (or holds nothing): the next wall logs its reason afresh.
530
+ account._claimSkipKey = null;
531
+ return;
532
+ }
533
+ if (reason == null) return;
534
+ if (account._claimSkipKey !== reason) {
535
+ account._claimSkipKey = reason;
536
+ this.log(`[reset-grant] ${account.name}: at wall, claim held (${reason})`);
537
+ }
538
+ }
539
+
392
540
  _withTimeout(promise) {
393
541
  return Promise.race([
394
542
  promise,
@@ -42,8 +42,11 @@
42
42
  * merely hours away. Dying-value redeems (R2) are exempt: an expiring card's
43
43
  * value cannot survive a wait.
44
44
  */
45
+ import { appliesTo as defaultAppliesTo } from './claude-reset-grants.js';
46
+ import { CLAIM_FRESH_MS } from './reset-timing.js';
47
+
45
48
  export const POLICY = {
46
- wallWeekly: 0.90, // weekly at 90% = at the wall
49
+ wallWeekly: 0.90, // weekly at 90% = at the wall (z.ai cards; UNCHANGED — pre-mortem #22)
47
50
  wallSes: 0.95, // 5h at 95% = at the wall
48
51
  dyingWindowMs: 24 * 3600 * 1000, // redeem-don't-save horizon
49
52
  dyingMinUtilWeekly: 0.30, // below this a dying weekly refill buys too little
@@ -52,6 +55,18 @@ export const POLICY = {
52
55
  freeRefillImmediate: 0.98, // R6: ...unless this full — never block the owner
53
56
  };
54
57
 
58
+ // Claude cedar_ember claims read their OWN wall (pre-mortem #22): 0.99, deliberately
59
+ // NOT POLICY.wallWeekly (0.90) which z.ai shares — moving the shared constant would
60
+ // redeem GLM cards at a different point. Claude benches at 0.999 (weeklyExhausted)
61
+ // and tiers critical at 0.95; 0.99 is "the weekly is effectively spent" for a claim.
62
+ export const CLAUDE_WALL_WEEKLY = 0.99;
63
+
64
+ // Claim freshness bound (C1, pre-mortem #5): the usage reading the claim decides on
65
+ // must be THIS fresh (≤ 5 min) — a reading taken before this sweep's probe (up to
66
+ // ~36 min stale after failed probes) would spend a reset right after a free refill.
67
+ // The value lives in the shared timing leaf; re-exported for existing callers.
68
+ export { CLAIM_FRESH_MS };
69
+
55
70
  function msLeft(t, now) { return t == null ? Infinity : t - now; }
56
71
 
57
72
  /** Decide the z.ai action. Returns {kind:'card', card, resetType} | null. */
@@ -97,34 +112,124 @@ export function decideZai(account, cards, now = Date.now()) {
97
112
  return null;
98
113
  }
99
114
 
100
- /** Decide the Claude action. Returns {kind:'grant', grant} | null. */
101
- export function decideClaude(account, listing, now = Date.now()) {
102
- if (account?.enabled === false) return null; // R0
103
- if (!listing || listing.error || listing.eligible === false) return null;
104
- if (listing.cooldownUntil != null && listing.cooldownUntil > now) return null;
105
- const grants = (listing.grants || [])
106
- .filter(g => g.usableNow && !g.paused && !g.expired)
107
- .sort((a, b) => (a.endsAt ?? Infinity) - (b.endsAt ?? Infinity));
108
- // The server names the next grant it would spend; honoring it avoids surprises.
109
- const chosen = grants.find(g => listing.nextGrantId == null || g.id === listing.nextGrantId) || grants[0];
110
- if (!chosen) return null;
115
+ /** Decide the Claude action. Returns {kind:'grant', grant, scope, reason} | null.
116
+ * Thin wrapper over decideClaudeWithReason for callers that only need the action. */
117
+ export function decideClaude(account, listing, now = Date.now(), opts = {}) {
118
+ return decideClaudeWithReason(account, listing, now, opts).action;
119
+ }
120
+
121
+ /** The ONE probe-send-time used to order a reading against a claim (finding 1):
122
+ * the SEND time of the last successful probe when the prober recorded it,
123
+ * else its apply time. A probe sent before a claim carries the pre-claim
124
+ * reading even when it lands after the claim. */
125
+ export function probeSentAt(q) {
126
+ return q?.lastProbeOkSentAt ?? q?.lastProbeOkAt ?? null;
127
+ }
111
128
 
129
+ /** Decide the Claude action AND say why when there is none.
130
+ * Returns { action: {kind:'grant', grant, scope, giveBack?, reason} | null,
131
+ * reason: string | null } — `reason` names the rejection when action
132
+ * is null (C5: the skip log prints exactly this), or the claim reason.
133
+ *
134
+ * C1 (amended, 2026-11-10): the claim is decided per grant by appliesTo (D1),
135
+ * NEVER by the server's nextGrantId order alone (pre-mortem #8: a Fable 429 could
136
+ * pick the general grant through that order). Freshness gates (pre-mortem #5):
137
+ * lastProbeOkAt within CLAIM_FRESH_MS, unified7dReset in the future (a window
138
+ * that just rolled means 0% used — don't spend on it), and a probe SENT after
139
+ * any claim we already made (no second claim for one wall).
140
+ * D4: a dying-value claim (not at the wall) waits when the free refill of the
141
+ * limit it clears is < 24h away; a wall claim never waits (limit effectively full).
142
+ * Session-only grants are NEVER claimed (owner 2026-10-30). */
143
+ export function decideClaudeWithReason(account, listing, now = Date.now(), opts = {}) {
144
+ const skip = reason => ({ action: null, reason });
145
+ if (account?.enabled === false) return skip('account disabled'); // R0
146
+ if (!listing) return skip('no listing');
147
+ // Only a FRESH listing may claim.
148
+ if (listing.error) return skip('listing failed');
149
+ if (listing.stale) return skip('listing stale');
150
+ if (listing.eligible === false) return skip('not eligible');
151
+ if (listing.cooldownUntil != null && listing.cooldownUntil > now) return skip('cooldown');
112
152
  const q = account.quota || {};
113
- const wkUtil = q.unified7d ?? null;
114
- const clearsWk = chosen.clears?.includes('seven_day');
115
153
 
116
- // Owner, 2026-10-30: "never spend resets on session limits, only on weekly."
117
- // A grant that clears ONLY the session window is never spent, at wall or dying.
118
- if (!clearsWk) return null;
154
+ // FRESHNESS (pre-mortem #5): decide on THIS sweep's probe, never an aging one.
155
+ // `freshNow` defaults to the real clock; tests may inject a frozen one.
156
+ const freshNow = opts.now ?? now;
157
+ const lastProbeOkAt = q.lastProbeOkAt ?? null;
158
+ if (lastProbeOkAt == null || freshNow - lastProbeOkAt > CLAIM_FRESH_MS) return skip('probe not fresh');
159
+ // A weekly window that already rolled over is empty — a claim right now buys
160
+ // nothing (spent right after the free refill, at 0% used).
161
+ if (q.unified7dReset != null && q.unified7dReset <= freshNow) return skip('weekly window elapsed');
162
+ // No second claim for one wall: a probe SENT after the last claim must land first.
163
+ const lastClaimAt = account.lastClaimAt ?? null;
164
+ if (lastClaimAt != null && probeSentAt(q) <= lastClaimAt) return skip('already claimed for this wall');
119
165
 
120
- const atWall = wkUtil != null && wkUtil >= POLICY.wallWeekly;
166
+ // Per-grant applicability (D1 via appliesTo), soonest-expiring first among
167
+ // SAME-scope grants. Grants with unknown scope (appliesTo []) are never chosen.
168
+ const held = (listing.grants || []).filter(g => g && !g.paused && !g.expired
169
+ && (g.endsAt == null || g.endsAt > now) && (g.resetsLeft ?? 1) > 0);
170
+ if (!held.length) return skip('no grant held');
171
+ const grants = held
172
+ .filter(g => g.usableNow !== false && !g.blocking && !g.unavailableReason)
173
+ .sort((a, b) => (a.endsAt ?? Infinity) - (b.endsAt ?? Infinity));
174
+ if (!grants.length) return skip('grant not usable');
175
+
176
+ const appliesTo = opts.appliesTo || defaultAppliesTo;
177
+ const wkUtil = q.unified7d ?? null;
178
+ const weeklyWall = wkUtil != null && wkUtil >= CLAUDE_WALL_WEEKLY;
179
+ // D4: the free refill of a limit < 24h away makes a not-at-the-wall spend redundant.
180
+ const refillSoon = resetAt => resetAt != null && msLeft(resetAt, now) < POLICY.freeRefillWaitMs;
181
+ let reason = null;
182
+ const note = r => { if (reason == null) reason = r; };
121
183
 
122
- // use_requires_limit: some grants may only fire AT the wall (server-enforced).
123
- const dying = msLeft(chosen.endsAt, now) < POLICY.dyingWindowMs
124
- && wkUtil != null && wkUtil >= POLICY.dyingMinUtilWeekly; // weekly window only (owner 2026-10-30)
125
- // A requires-limit grant cannot be redeemed pre-wall even for dying value.
126
- if (atWall || (dying && !chosen.requiresLimit)) {
127
- return { kind: 'grant', grant: chosen, reason: atWall ? 'at wall' : 'dying value' };
184
+ // GENERAL (clears the general weekly, or gives_back_weekly): claim at the wall.
185
+ // "Weekly reached" is the fresh unified7d reading ONLY — never the generic
186
+ // `rejected` status (that conflates the 5h window and per-model caps; pre-mortem #8).
187
+ const general = grants.filter(g => appliesTo(g).includes('general'));
188
+ for (const g of general) {
189
+ const giveBack = g.givesBackWeekly === true && !(Array.isArray(g.clears) && g.clears.includes('seven_day'));
190
+ if (weeklyWall) {
191
+ // A give-back-only grant (no seven_day in clears) returns only what the model
192
+ // used — the claim snapshots unified7d so the next probe measures the drop.
193
+ return { action: { kind: 'grant', grant: g, scope: 'general', giveBack, reason: 'weekly at wall' }, reason: 'weekly at wall' };
194
+ }
195
+ const dying = msLeft(g.endsAt, now) < POLICY.dyingWindowMs
196
+ && wkUtil != null && wkUtil >= POLICY.dyingMinUtilWeekly; // weekly window only (owner 2026-10-30)
197
+ if (!dying) continue;
198
+ if (g.requiresLimit) { note('requires limit'); continue; }
199
+ if (refillSoon(q.unified7dReset)) { note('free refill <24h away'); continue; }
200
+ return { action: { kind: 'grant', grant: g, scope: 'general', giveBack, reason: 'dying value' }, reason: 'dying value' };
128
201
  }
129
- return null;
202
+ if (weeklyWall && !general.length) note('general not held');
203
+
204
+ // MODEL-SCOPED (D3): claim when THAT model's probe-measured weekly bucket is at
205
+ // its wall. `reactive` entries (a 429's authoritative-high mark) do NOT count —
206
+ // only the probe's own measurement (pre-mortem #3/#8: a scoped 429 classified by
207
+ // guesswork must not spend a reset). D4 dying-value is evaluated per bucket
208
+ // BEFORE the below-the-wall skip (it applies exactly there).
209
+ const scopedFams = new Set();
210
+ for (const g of grants) for (const s of appliesTo(g)) if (s !== 'general' && s !== 'session') scopedFams.add(s);
211
+ for (const fam of scopedFams) {
212
+ const e = q.scopedWeekly?.[fam];
213
+ const measured = e && e.reactive !== true && e.utilization != null;
214
+ if (!measured) continue;
215
+ const cand = grants.find(g => appliesTo(g).includes(fam));
216
+ if (!cand) continue;
217
+ if (e.utilization >= CLAUDE_WALL_WEEKLY) {
218
+ return { action: { kind: 'grant', grant: cand, scope: fam, reason: `${fam} weekly at wall` }, reason: `${fam} weekly at wall` };
219
+ }
220
+ const dying = msLeft(cand.endsAt, now) < POLICY.dyingWindowMs
221
+ && e.utilization >= POLICY.dyingMinUtilWeekly;
222
+ if (!dying) continue;
223
+ if (cand.requiresLimit) { note('requires limit'); continue; }
224
+ if (refillSoon(e.resetAt)) { note('free refill <24h away'); continue; }
225
+ return { action: { kind: 'grant', grant: cand, scope: fam, reason: 'dying value' }, reason: 'dying value' };
226
+ }
227
+ // A scoped bucket measured at the wall with no grant for it.
228
+ for (const [fam, e] of Object.entries(q.scopedWeekly || {})) {
229
+ if (e && e.reactive !== true && e.utilization != null && e.utilization >= CLAUDE_WALL_WEEKLY
230
+ && !grants.some(g => appliesTo(g).includes(fam))) note(`${fam} not held`);
231
+ }
232
+
233
+ // Session-only grants: NEVER claimed (owner 2026-10-30) — falls through.
234
+ return skip(reason ?? 'below wall');
130
235
  }